Merge pull request #111 from AdobeDocs/barranca/colorpicker

Barranca/colorpicker

Author: undavide

gatsby-config.js

@@ -498,6 +498,16 @@ module.exports = {
           },
         ],
       },
+      {
+        title: "Built-in UI Components",
+        path: "references/ui-components/color-picker.md",
+        pages: [
+          {
+            title: "Color Picker",
+            path: "references/ui-components/color-picker.md",
+          },
+        ],
+      },
       {
         title: "Manifest Schema",
         description: "Manifest schema",

src/pages/guides/develop/how_to/use_color.md

@@ -16,6 +16,7 @@ keywords:
   - Text Color
   - HEX Color
   - RGB Color
+  - Color Picker
 title: Use Color
 description: Use Color.
 contributors:
@@ -127,3 +128,157 @@ ellipse.stroke = editor.makeStroke({
 Naming conventions
 
 Please note that Adobe Express uses the terms **make** and **create** to distinguish between plain objects and live document objects. You `makeColorFill()`, but `createEllipse()`.
+
+## Use the Color Picker
+
+Adobe Express includes a native Color Picker, with special features such as Recommended Swatches, Eyedropper, Themes, Library and Brand colors. The Color Picker is available also to add-ons, you can invoke it using the [`addOnUISdk.app.showColorPicker()`](../../../references/addonsdk/addonsdk-app.md#showcolorpicker) method.
+
+#### Benefits
+
+- It simplifies the process of selecting a color, bypassing the Browser's color picker.
+- It's in sync with any swatches or Brand colors defined in Adobe Express.
+- It will evolve with Adobe Express, providing a consistent color picking experience across different parts of the application.
+
+The `showColorPicker()` method accepts a reference to an HTML element as its first argument, which will become the color picker's anchor element. The picker will be positioned relative to this element, based on the placement options available in the `ColorPickerPlacement` enum; additionally, the anchor will receive a custom `"colorpicker-color-change"` event when the color changes and a `"colorpicker-close"` event when it is closed.
+
+The `showColorPicker()` method requires an HTML element as its anchor point. Here's how it works:
+
+1. **Anchor Element**
+
+- Pass an HTML element reference as the first argument.
+- The color picker will position itself relative to this element.
+- Use the `ColorPickerPlacement` enum to control positioning.
+
+2. **Event Handling**
+
+- The anchor element receives two custom events:
+  - `"colorpicker-color-change"`: Fires when a new color is selected.
+  - `"colorpicker-close"`: Fires when the picker is closed.
+
+### Example: Show the Color Picker
+
+<CodeBlock slots="heading, code" repeat="2" languages="js, html"/>
+
+#### ui/index.js
+
+```js
+import addOnUISdk, {
+  ColorPickerEvents,
+  ColorPickerPlacement,
+} from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
+
+addOnUISdk.ready.then(async () => {
+  // Get the button element
+  const colorPickerButton = document.getElementById("colorPicker");
+
+  // Add a click event listener to the button to show the color picker
+  colorPickerButton.addEventListener("click", () => {
+    addOnUISdk.app.showColorPicker(colorPickerButton, {
+      // The title of the color picker
+      title: "Awesome Color Picker",
+      // The placement of the color picker
+      placement: ColorPickerPlacement.left,
+      // Whether the eyedropper hides the color picker
+      eyedropperHidesPicker: true,
+      // The initial color of the color picker
+      initialColor: 0x0000ff,
+      // Whether the alpha channel is disabled
+      disableAlphaChannel: false,
+    });
+  });
+
+  // Add a listener for the colorpicker-color-change event
+  addOnUISdk.app.on(ColorPickerEvents.ColorChange, (event) => {
+    // Get the color from the event
+    console.log(event.detail.color);
+    // e.g., "#F0EDD8FF" in HEX (RRGGBBAA) format
+  });
+
+  // Add a listener for the colorpicker-close event
+  colorPickerButton.addEventListener(ColorPickerEvents.close, (event) => {
+    console.log(event.type); // "colorpicker-close"
+  });
+});
+```
+
+#### index.html
+
+```html
+<button id="colorPicker">Show the Color Picker</button>
+```
+
+Please note that the color returned by the `colorpicker-color-change` event is always a string in HEX format—with or without an alpha value, e.g., `#F0EDD8FF` or `#F0EDD8` depending on the `disableAlphaChannel` option.
+
+### Example: Hide the Color Picker
+
+You can decide to hide picker UI e.g., after a certain amount of time.
+
+```js
+colorPickerButton.addEventListener("click", () => {
+  addOnUISdk.app.showColorPicker(colorPickerButton, {
+    /* ... */
+  });
+  setTimeout(() => {
+    console.log("Hiding the Color Picker after 10 seconds");
+    addOnUISdk.app.hideColorPicker();
+  }, 10000);
+});
+```
+
+### Example: Use the color
+
+You can use any HTML element as the color picker's anchor element; in the example below, we're using a `<div>` element to display a color swatch.
+
+<CodeBlock slots="heading, code" repeat="2" languages="html, js"/>
+
+#### index.html
+
+```html
+<style>
+  #color-display {
+    width: 30px;
+    height: 30px;
+    border: 1px solid black;
+    border-radius: 4px;
+    background-color: white;
+  }
+</style>
+<body>
+  <div id="color-display"></div>
+</body>
+```
+
+#### index.js
+
+```js
+addOnUISdk.ready.then(async () => {
+  const colorDisplay = document.getElementById("color-display");
+
+  colorDisplay.addEventListener("click", () => {
+    addOnUISdk.app.showColorPicker(colorDisplay, {
+      title: "Color Picker 1",
+      placement: ColorPickerPlacement.left,
+      eyedropperHidesPicker: true,
+    });
+  });
+
+  colorDisplay.addEventListener(ColorPickerEvents.colorChange, (event) => {
+    // Update the color swatch display in the UI
+    colorDisplay.style.backgroundColor = event.detail.color;
+  });
+});
+```
+
+To use the picked color in the Document Sandbox, you can use the [`colorUtils.fromHex()`](../../../references/document-sandbox/document-apis/classes/ColorUtils.md#fromhex) method, which converts the HEX color string to a [`Color`](../../../references/document-sandbox/document-apis/interfaces/Color.md) object.
+
+```js
+// sandbox/code.js
+const color = colorUtils.fromHex(event.detail.color); // 👈 A Color object
+
+// Use the color in the Document Sandbox, for example:
+let selection = editor.context.selection;
+if (selection.length === 1 && selection[0].type === "Text") {
+  const textContentModel = selection[0].fullContent;
+  textContentModel.applyCharacterStyles({ color }); // 👈 Using the color
+}
+```

src/pages/guides/getting_started/quickstart.md

@@ -49,7 +49,7 @@ The **[Adobe Express add-on CLI](dev_tooling.md#using-the-cli) (Command Line Int
 Open your terminal and run the following command:
 
 ```bash
-npx @adobe/create-ccweb-add-on hello-world --template javascript-with-document-sandbox     
+npx @adobe/create-ccweb-add-on hello-world --template javascript-with-document-sandbox
 ```
 
 This command will create a new add-on based on pure JavaScript with Document Sandbox support (the set of APIs that allow you to interact with Adobe Express documents).
@@ -71,13 +71,13 @@ Please run this command to clear the `npx` cache and ensure the latest version o
 
 ```bash
 npx clear-npx-cache
-npx @adobe/create-ccweb-add-on hello-world 
+npx @adobe/create-ccweb-add-on hello-world
 ```
 
 The above may prove useful when updated versions of the CLI are released. If you want to read each individual CLI command manual page, run them via `npx` with the `--help` flag, for example:
 
 ```bash
-npx @adobe/ccweb-add-on-scripts start --help  
+npx @adobe/ccweb-add-on-scripts start --help
 ```
 
 ## Step 2: Build and start your add-on
@@ -134,9 +134,9 @@ For simplicity's sake, this Quickstart guide covers the document creation method
 
 - Once clicked, a modal will appear where you will provide the URL of your locally hosted add-on.
 
-   **Note:** Use the default `https://localhost:5241` supplied unless you are intentionally using a different port.
+  **Note:** Use the default `https://localhost:5241` supplied unless you are intentionally using a different port.
 
-   Select the *I understand the risks of loading an add-on from an external server* checkbox and press the **Connect** button.
+  Select the _I understand the risks of loading an add-on from an external server_ checkbox and press the **Connect** button.
 
 ![Add-on connect modal](./img/connect-modal-v2.png)
 
@@ -170,7 +170,7 @@ You can continue to update your code while your add-on is running, and the add-o
 
 **Manifest updates**<br/>
 
-Any changes to the `manifest.json` will *require a manual reload of your add-on*. The **Add-on Development** panel will indicate this in the log messages, and the **Refresh** button can be used to reload the add-on directly within Adobe Express. You can try this by updating the `name` field in the `src/manifest.json` file of your running add-on from "Hello World" to, say, **"Draw Rectangle"**.
+Any changes to the `manifest.json` will _require a manual reload of your add-on_. The **Add-on Development** panel will indicate this in the log messages, and the **Refresh** button can be used to reload the add-on directly within Adobe Express. You can try this by updating the `name` field in the `src/manifest.json` file of your running add-on from "Hello World" to, say, **"Draw Rectangle"**.
 
 ![manifest update](./img/manifest-update-v2.png)
 

src/pages/references/addonsdk/addonsdk-app.md

@@ -254,6 +254,85 @@ async function showInputDialog() {
 
 See the use case implementations for an example of the [custom modal dialog](../../guides/develop/how_to/modal_dialogs.md#custom-dialog).
 
+### showColorPicker()
+
+Shows the Adobe Express color picker based on specific options passed in.
+
+#### Signature
+
+`showColorPicker(anchorElement: HTMLElement, options?: ColorPickerOptions): Promise<void>;`
+
+#### Parameters
+
+| Name            | Type                 |                                       Description |
+| --------------- | -------------------- | ------------------------------------------------: |
+| `anchorElement` | `HTMLElement`        |        The element to anchor the color picker to. |
+| `options`       | `ColorPickerOptions` | The optional options to pass to the color picker. |
+
+##### `ColorPickerOptions`
+
+| Name                     |                                                               Type |                                                                                                                                                                                                                                                                      Description |
+| ------------------------ | -----------------------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| `title?`                 |                                                           `string` |                                                                                                                                                                                                                     Label header/title for the color picker. Default value: `""` |
+| `initialColor?`          |                                                           `number` | Default/starting color when you open the color picker for the first time on a `anchorElement`. When you have already changed the color with this picker, then the next time you open the picker, the last selected color will be the starting color. Default: `0xFFFFFF` (white) |
+| `placement?`             | `object` [ColorPickerPlacement](./addonsdk-constants.md#constants) |                                                                                                                                                                                                 Placement of the popover with respect to the anchor element (default: `"left"`). |
+| `eyedropperHidesPicker?` |                                                          `boolean` |                                                                                                                Closes the color picker popover while using the EyeDropper. After the color is selected via the EyeDropper, the color picker popup opens again. Default: `false`. |
+| `disableAlphaChannel?`   |                                                          `boolean` |                                                                                                                                                                                  Disables the transparency slider in the "custom" section of the color picker. Default: `false`. |
+
+#### Return Value
+
+Returns a void `Promise`.
+
+#### Example Usage
+
+```js
+const colorPickerButton = document.getElementById("color-picker-button");
+
+colorPickerButton.addEventListener("click", () => {
+  addOnUISdk.app.showColorPicker(colorPickerButton, {
+    title: "Add-on's Color Picker",
+    placement: ColorPickerPlacement.left,
+    eyedropperHidesPicker: true,
+    disableAlphaChannel: false,
+  });
+});
+
+colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
+  console.log("Color change event received!", event.detail.color;);
+});
+```
+
+### hideColorPicker()
+
+Hides the Adobe Express color picker.
+
+#### Signature
+
+`hideColorPicker(): Promise<void>;`
+
+#### Return Value
+
+Returns a void `Promise`.
+
+#### Example Usage
+
+```js
+const colorPickerButton = document.getElementById("color-picker-button");
+
+colorPickerButton.addEventListener("click", () => {
+  addOnUISdk.app.showColorPicker(colorPickerButton, {
+    title: "Add-on's Color Picker",
+    placement: ColorPickerPlacement.left,
+    eyedropperHidesPicker: true,
+    disableAlphaChannel: false,
+  });
+  setTimeout(() => {
+    console.log("Hiding Color Picker after 10 seconds...");
+    addOnUISdk.app.hideColorPicker();
+  }, 10000);
+});
+```
+
 ### registerIframe()
 
 Allows an iframe hosted within an add-on to register its intent to communicate with the add-on SDK. While iframes can be used for embedding media without SDK interaction, `registerIframe()` is needed for those requiring SDK capabilities. It marks a transition to a more controlled approach, where add-ons must explicitly opt-in to this level of integration.

src/pages/references/addonsdk/addonsdk-constants.md

@@ -39,6 +39,30 @@ A set of constants used throughout the add-on SDK. These constants are equal to
         </ul>
     </td>
 </tr>
+<tr class="spectrum-Table-row">
+    <td class="spectrum-Table-cell"><p><pre>ColorPickerEvents</pre></p></td>
+    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
+    <td style="vertical-align: bottom;">
+        <p>Custom events dispatched by the Color Picker.</p>
+        <ul>
+          <li><strong>colorChange</strong></li><pre>"colorpicker-color-change"</pre>
+          <li><strong>close</strong></li><pre>"colorpicker-close"</pre>
+        </ul>
+    </td>
+</tr>
+<tr class="spectrum-Table-row">
+    <td class="spectrum-Table-cell"><p><pre>ColorPickerPlacement</pre></p></td>
+    <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>
+    <td style="vertical-align: bottom;">
+        <p>Placement of the color picker popover with respect to the anchor element.</p>
+        <ul>
+          <li><strong>top</strong></li><pre>"top"</pre>
+        <li><strong>bottom</strong></li><pre>"bottom"</pre>
+        <li><strong>left</strong></li><pre>"left"</pre>
+        <li><strong>right</strong></li><pre>"right"</pre>
+        </ul>
+    </td>
+</tr>
 <tr class="spectrum-Table-row">
     <td class="spectrum-Table-cell"><p><pre>DialogResultType</pre></p></td>
     <td class="spectrum-Table-cell"><p><pre>string</pre></p></td>

src/pages/references/changelog.md

@@ -22,6 +22,15 @@ contributors:
 
 # Changelog
 
+## 2025-03-21
+
+### Added
+
+- A native Color Picker is available to add-ons via the [`showColorPicker()`](../references/addonsdk/addonsdk-app.md#showcolorpicker) and [`hideColorPicker()`](../references/addonsdk/addonsdk-app.md#hidecolorpicker) methods of the `addOnUiSdk.app` object.
+- We've updated the [Use Color](../guides/develop/how_to/use_color.md) How-to guide, now including a few examples on the Color Picker.
+- A [new section](../references/ui-components/color-picker.md) has been added to the documentation, which provides a reference for the Adobe Express built-in UI components available to add-ons, like the Color Picker.
+- A new version of the `@adobe/ccweb-add-on-sdk-types` package (v1.14.0) has been released for the CLI. Run `npm update` from the root of your add-on project to update to get the latest typings.
+
 ## 2025-03-07
 
 ### Added