Merge branch 'main' into unzela/rename_enum

Author: undavide

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

@@ -133,10 +133,6 @@ Please note that Adobe Express uses the terms **make** and **create** to disting
 
 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.
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../references/manifest/index.md#requirements) section of the `manifest.json`.
-
 #### Benefits
 
 - It simplifies the process of selecting a color, bypassing the Browser's color picker.
@@ -167,7 +163,7 @@ The `showColorPicker()` method requires an HTML element as its anchor point. Her
 
 ```js
 import addOnUISdk, {
-  ColorPickerEvents,
+  ColorPickerEvent,
   ColorPickerPlacement,
 } from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
@@ -192,14 +188,14 @@ addOnUISdk.ready.then(async () => {
   });
 
   // Add a listener for the colorpicker-color-change event
-  colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
+  colorPickerButton.addEventListener(ColorPickerEvent.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) => {
+  colorPickerButton.addEventListener(ColorPickerEvent.close, (event) => {
     console.log(event.type); // "colorpicker-close"
   });
 });
@@ -266,7 +262,7 @@ addOnUISdk.ready.then(async () => {
     });
   });
 
-  colorDisplay.addEventListener(ColorPickerEvents.colorChange, (event) => {
+  colorDisplay.addEventListener(ColorPickerEvent.colorChange, (event) => {
     // Update the color swatch display in the UI
     colorDisplay.style.backgroundColor = event.detail.color;
   });

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

@@ -258,10 +258,6 @@ See the use case implementations for an example of the [custom modal dialog](../
 
 Shows the Adobe Express color picker based on specific options passed in.
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../manifest/index.md#requirements) section of the `manifest.json`.
-
 #### Signature
 
 `showColorPicker(anchorElement: HTMLElement, options?: ColorPickerOptions): Promise<void>;`
@@ -275,13 +271,13 @@ Shows the Adobe Express color picker based on specific options passed in.
 
 ##### `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`. |
+| Name                     |                                                               Type |                                                                                                                                                                                                                                                                                                                       Description |
+| ------------------------ | -----------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| `title?`                 |                                                           `string` |                                                                                                                                                                                                                                                                      Label header/title for the color picker. Default value: `""` |
+| `initialColor?`          |                                               `number` or `string` | Default/starting color when you open the color picker for the first time on a `anchorElement`, in the format `0xRRGGBB[AA]` or `"#RRGGBB[AA]"`. 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
 
@@ -301,7 +297,7 @@ colorPickerButton.addEventListener("click", () => {
   });
 });
 
-colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
+colorPickerButton.addEventListener(ColorPickerEvent.colorChange, (event) => {
   console.log("Color change event received!", event.detail.color;);
 });
 ```
@@ -310,10 +306,6 @@ colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
 
 Hides the Adobe Express color picker.
 
-<InlineAlert slots="text" variant="warning"/>
-
-**IMPORTANT:** This is currently **_experimental only_** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../manifest/index.md#requirements) section of the `manifest.json`.
-
 #### Signature
 
 `hideColorPicker(): Promise<void>;`

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

@@ -40,7 +40,7 @@ A set of constants used throughout the add-on SDK. These constants are equal to
     </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>ColorPickerEvent</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>

src/pages/references/changelog.md

@@ -22,11 +22,15 @@ contributors:
 
 # Changelog
 
-## 2025-04-30
+## 2025-05-05
 
 ### Updated
 
-- Renamed enum TextType to [`TextLayout`](./document-sandbox/document-apis/enumerations/TextLayout.md) in the Text APIs.
+- There are a few notable changes regarding the [Color Picker APIs](../references/addonsdk/addonsdk-app.md#showcolorpicker), which have now moved to stable:
+  - The `initialColor` parameter now accepts a string in `"#RRGGBB[AA]"` format, in addition to the previous HEX number `0xRRGGBB[AA]`—both with optional alpha channel.
+  - We fixed the return value of the `ColorPickerEvent.colorChange` event, which now correctly handles the color with or without the alpha channel, depending on the value of the `disableAlphaChannel` parameter.
+  - **Breaking change**: the `ColorPickerEvents` enum has been renamed to `ColorPickerEvent` (singular).
+- Renamed the TextType enumerable to [`TextLayout`](./document-sandbox/document-apis/enumerations/TextLayout.md) in the Text APIs.
 
 ## 2025-04-22
 

src/pages/references/ui-components/color-picker.md

@@ -32,13 +32,15 @@ The Adobe Express native Color Picker offers several unique features, compared t
 
 ![Color Picker](./images/colorpicker_brand.png)
 
-Using the Adobe ExpressColor Picker in your add-on instead of building your own version provides a few benefits:
+Using the Adobe Express Color Picker in your add-on instead of building your own version provides a few benefits:
 
 - It simplifies the process of selecting a color, bypassing the Browser's color picker.
 - It provides a consistent experience to users, as the color picker is integrated with Adobe Express.
 - It's in sync with any swatches or Brand colors defined in the application.
 - It will evolve with Adobe Express, adding new features over time.
 
+Please note that the Color Picker is going to be available to add-ons in Adobe Express on desktop environment only.
+
 ## API
 
 The [`addOnUISdk.app`](../addonsdk/addonsdk-app.md) has two dedicated method:
@@ -137,18 +139,18 @@ addOnUISdk.app.showColorPicker(element, {
 
 ```js
 import addOnUISdk, {
-  ColorPickerEvents,
+  ColorPickerEvent,
 } from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
 addOnUISdk.ready.then(async () => {
   const colorPickerButton = document.getElementById("colorPicker");
 
   // Add event listeners for color picker events
-  colorPickerButton.addEventListener(ColorPickerEvents.colorChange, (event) => {
+  colorPickerButton.addEventListener(ColorPickerEvent.colorChange, (event) => {
     console.log("Color picker color change event from add-on:", event.detail);
   });
 
-  colorPickerButton.addEventListener(ColorPickerEvents.close, (event) => {
+  colorPickerButton.addEventListener(ColorPickerEvent.close, (event) => {
     console.log("Color picker closed from add-on:", event.detail);
   });
 
@@ -197,30 +199,30 @@ The color picker can be positioned relative to the anchor element using the `pla
 
 **Invalid anchor element: must be an instance of `HTMLElement`.**
 
-- **Origin:** Parameter `anchorElement`
-- **Fix:** the anchorElement should be a valid `HTMLElement`
+- **Origin:** Parameter `anchorElement`.
+- **Fix:** the anchorElement should be a valid `HTMLElement`.
 
 **Invalid title: must be a string.**
 
-- **Origin:** Property `title` in the `ColorPickerOptions`
-- **Fix:** the `title` should be a valid string
+- **Origin:** Property `title` in the `ColorPickerOptions`.
+- **Fix:** the `title` should be a valid string.
 
-**Invalid initial color: must be a HEX number in `0xRRGGBB` format.**
+**Invalid initialColor: must be either a number in `0xRRGGBB[AA]` format or a string in `"#RRGGBB[AA]"` format.**
 
-- **Origin:** Property `initialColor` in the `ColorPickerOptions`
-- **Fix:** the `initialColor` should be a valid number in 0xRRGGBB format.
+- **Origin:** Property `initialColor` in the `ColorPickerOptions`.
+- **Fix:** the `initialColor` should be a valid number in `0xRRGGBB[AA]` format or a valid string in `"#RRGGBB[AA]"` format.
 
 **Invalid placement value: must be one of the valid `ColorPickerPlacement` values.**
 
-- **Origin:** Property `placement` in the `ColorPickerOptions`
+- **Origin:** Property `placement` in the `ColorPickerOptions`.
 - **Fix:** the `placement` should be a valid string from the `ColorPickerPlacement` enum.
 
 **Invalid `eyedropperHidesPicker`: must be a boolean value.**
 
-- **Origin:** Property `eyedropperHidesPicker` in the `ColorPickerOptions`
+- **Origin:** Property `eyedropperHidesPicker` in the `ColorPickerOptions`.
 - **Fix:** the `eyedropperHidesPicker` must be a boolean value.
 
 **Invalid `disableAlphaChannel`: must be a boolean value.**
 
-- **Origin:** Property `disableAlphaChannel` in the `ColorPickerOptions`
+- **Origin:** Property `disableAlphaChannel` in the `ColorPickerOptions`.
 - **Fix:** the `disableAlphaChannel` must be a boolean value.