@adobe/ccweb-add-on-sdk-types 1.14.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/ccweb-add-on-sdk-types",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "author": "Adobe",
   "license": "MIT",
   "description": "Type definitions for Adobe Creative Cloud Web Add-on SDK.",

package/sandbox/express-document-sdk.d.ts

@@ -81,7 +81,7 @@ declare namespace ApiConstants {
         StrokePosition,
         StrokeType,
         TextAlignment,
-        TextType,
+        TextLayout,
         EditorEvent,
         VisualEffectType,
         ParagraphListType,
@@ -105,7 +105,7 @@ declare interface ApiModuleExport {
  * @experimental
  */
 export declare interface AreaTextLayout {
-    type: TextType.area;
+    type: TextLayout.area;
     /**
      * The width of the text node in pixels.
      */
@@ -120,6 +120,11 @@ export declare interface AreaTextLayout {
  * <InlineAlert slots="text" variant="warning"/>
  *
  * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code.
+ *
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * *Additional arrowhead types may be added in the future.* If your code has different branches or cases depending on arrow type,
+ * always have a default/fallback case to handle any unknown values you may encounter.
  */
 declare enum ArrowHeadType {
     none = 0,
@@ -175,6 +180,7 @@ export declare class ArtboardNode extends VisualNode implements IRectangularNode
     get children(): ItemList<Node>;
     /**
      * The background fill of the artboard. Artboards must always have a fill.
+     *
      */
     set fill(fill: Fill);
     get fill(): Readonly<Fill>;
@@ -200,7 +206,7 @@ export declare class ArtboardNode extends VisualNode implements IRectangularNode
  * @experimental
  */
 export declare interface AutoHeightTextLayout {
-    type: TextType.autoHeight;
+    type: TextLayout.autoHeight;
     /**
      * The width of the text node in pixels.
      */
@@ -1476,7 +1482,7 @@ export declare interface Point {
  * @experimental
  */
 export declare interface PointTextLayout {
-    type: TextType.autoWidth;
+    type: TextLayout.autoWidth;
 }
 
 /**
@@ -1798,11 +1804,17 @@ declare interface StyleRange {
  * <InlineAlert slots="text" variant="warning"/>
  *
  * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code.
+ *
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * *Additional alignment types may be added in the future.* If your code has different branches or cases depending on text alignment,
+ * always have a default/fallback case to handle any unknown values you may encounter.
  */
 declare enum TextAlignment {
     left = 1,
     right = 2,
-    center = 3
+    center = 3,
+    justifyLeft = 4
 }
 
 /**
@@ -1885,13 +1897,7 @@ export declare class TextContentModel {
      * If the specified range doesn't align well with the paragraph boundaries, the range will be expanded to cover the
      * entire paragraphs, it overlaps.
      */
-    applyCharacterStyles(
-        styles: CharacterStylesInput,
-        range?: {
-            start: number;
-            length: number;
-        }
-    ): void;
+    applyCharacterStyles(styles: CharacterStylesInput, range?: TextRange): void;
     /**
      * <InlineAlert slots="text" variant="warning"/>
      *
@@ -1907,13 +1913,56 @@ export declare class TextContentModel {
      * @param range - The start and length of character sequence to which the styles should be applied.
      * If not specified the styles will be applied to the entire piece of text content flow.
      */
-    applyParagraphStyles(
-        styles: ParagraphStylesInput,
-        range?: {
-            start: number;
-            length: number;
-        }
-    ): void;
+    applyParagraphStyles(styles: ParagraphStylesInput, range?: TextRange): void;
+    /**
+     * <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`.
+     *
+     * @experimental
+     * Returns true if this text contains any fonts unavailable to the current user.
+     * Currently, if any unavailable fonts are present, the text content cannot be modified and
+     * certain styling changes are limited as well. To remove these restrictions, you must modify
+     * the character styles to use only AvailableFonts.
+     */
+    hasUnavailableFonts(): boolean;
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code.
+ *
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * *Additional text layout types may be added in the future.* If your code has different branches or cases depending on layout type,
+ * always have a default/fallback case to handle any unknown values you may encounter.
+ */
+declare enum TextLayout {
+    /**
+     * Area text: both width and height are explicitly set. If text content is too long to fit, the end of the text will be
+     * clipped. If text content is short, the frame's bounds will occupy extra height that is just blank space.
+     */
+    area = 1,
+    /**
+     * Auto-height text: Width is explicitly set, and text wraps to use as much vertical space as necessary to display the
+     * full content.
+     */
+    autoHeight = 2,
+    /**
+     * Auto-width, aka point text: both width and height are automatically determined based on the content. There is no
+     * automatic line wrapping, so the text will all be on one line unless the text contains explicit newlines.
+     */
+    autoWidth = 3,
+    /**
+     * Text is arranged in a circle or arc. The API does not yet support setting or reading the details of this layout style.
+     */
+    circular = 4,
+    /**
+     * Aka "Dynamic" layout in the UI: text size and styles are automatically varied to create an attractive multi-line layout.
+     * The API does not yet support setting or reading the details of this layout style.
+     */
+    magicFit = 5
 }
 
 /**
@@ -2005,7 +2054,7 @@ export declare class TextNode extends Node {
      * If this TextNode is part of a multi-frame text content flow, it must be configured to use {@link AreaTextLayout}. Other
      * layout modes, except for {@link AreaTextLayout}, are only available for single-frame text.
      *
-     * @throws if changing text layout to/from {@link TextType.magicFit} or {@link TextType.circular} layout when the text contains font(s) unavailable to the current user.
+     * @throws if changing text layout to/from {@link TextLayout.magicFit} or {@link TextLayout.circular} layout when the text contains font(s) unavailable to the current user.
      * @throws if {@link TextNode} is part of a multi-frame text content flow and the layout is not {@link AreaTextLayout}.
      * @throws if {@link TextNode} is not a part of a multi-frame text content flow and the layout is {@link AreaTextLayout}.
      */
@@ -2013,22 +2062,11 @@ export declare class TextNode extends Node {
 }
 
 /**
- * <InlineAlert slots="text" variant="warning"/>
- *
- * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code.
+ * A range of text in a {@link TextContentModel}.
  */
-declare enum TextType {
-    /**
-     * Point text
-     */
-    autoWidth = 0,
-    /**
-     * Soft bottom
-     */
-    autoHeight = 1,
-    area = 2,
-    magicFit = 3,
-    circular = 4
+declare interface TextRange {
+    start: number;
+    length: number;
 }
 
 /**
@@ -2082,7 +2120,7 @@ export declare interface UnorderedListStyleInput extends BaseParagraphListStyle
  * @experimental
  */
 export declare interface UnsupportedTextLayout {
-    type: TextType.magicFit | TextType.circular;
+    type: TextLayout.magicFit | TextLayout.circular;
 }
 
 /**

package/ui/ui-sdk.d.ts

@@ -151,6 +151,10 @@ export declare enum AppEvent {
      * triggered when the document id is available in the application.
      */
     documentIdAvailable = "documentIdAvailable",
+    /**
+     * triggered when the document link is available in the application.
+     */
+    documentLinkAvailable = "documentLinkAvailable",
     /**
      * triggered when the document title is changed in the application.
      */
@@ -171,6 +175,7 @@ declare interface AppEventsTypeMap {
     [AppEvent.dragend]: AppDragEndEventData;
 
     [AppEvent.documentIdAvailable]: DocumentIdAvailableEventData;
+    [AppEvent.documentLinkAvailable]: DocumentLinkAvailableEventData;
     [AppEvent.documentTitleChange]: DocumentTitleChangeEventData;
 }
 
@@ -253,17 +258,15 @@ declare interface ApplicationBase {
     showModalDialog(dialogOptions: CustomDialogOptions): Promise<CustomDialogResult>;
 
     /**
-     * @experimental - Experimental API
      * Shows a color picker popover anchored to the specified element.
      * The anchor element must be an instance of HTMLElement.
      * Custom DOM events are dispatched on the anchor element when the color changes or the color picker closes.
-     * See {@link ColorPickerEvents} for more details.
+     * See {@link ColorPickerEvent} for more details.
      * @param anchorElement - The HTML element to anchor the color picker to.
      * @param options - Optional configuration options for customizing the color picker behavior and appearance.
      */
     showColorPicker(anchorElement: HTMLElement, options?: ColorPickerOptions): Promise<void>;
     /**
-     * @experimental - Experimental API
      * Hides the color picker popover if it is currently visible.
      */
     hideColorPicker(): Promise<void>;
@@ -533,10 +536,9 @@ export declare interface ClientStorage {
 }
 
 /**
- * @experimental - Experimental API
  * Custom DOM events dispatched on the anchor element passed to `showColorPicker()` API.
  */
-export declare enum ColorPickerEvents {
+export declare enum ColorPickerEvent {
     /**
      * Color change event dispatched when a color is selected.
      * The event detail will contain a 'color' property of type string.
@@ -549,7 +551,6 @@ export declare enum ColorPickerEvents {
 }
 
 /**
- * @experimental - Experimental API
  * Options that can be passed to the `showColorPicker` API to customize the color picker's behavior and appearance.
  */
 export declare interface ColorPickerOptions {
@@ -559,10 +560,12 @@ export declare interface ColorPickerOptions {
      */
     title?: string;
     /**
-     * Initial color for the color picker, in 0xRRGGBB format.
+     * Initial color for the color picker, in hex format.
+     * Can provide either as a number in 0xRRGGBB or 0xRRGGBBAA format,
+     * or as a string in "#RRGGBB" or "#RRGGBBAA" format.
      * Default color is 0xFFFFFF (white).
      */
-    initialColor?: number;
+    initialColor?: number | string;
     /**
      * Placement of the color picker popover relative to the anchor element.
      * Default placement is ColorPickerPlacement.left.
@@ -581,7 +584,6 @@ export declare interface ColorPickerOptions {
 }
 
 /**
- * @experimental - Experimental API
  * Denotes the placement of the color picker popover relative to its anchor element.
  * Used in the placement option of `showColorPicker()` API.
  */
@@ -607,6 +609,7 @@ export declare enum ColorPickerPlacement {
 declare namespace Constants {
     export {
         Range_2 as Range,
+        LinkOptions,
         RenditionFormat,
         RenditionType,
         RenditionIntent,
@@ -625,7 +628,6 @@ declare namespace Constants {
         DeviceClass,
         PlatformType,
         ColorPickerPlacement,
-        ColorPickerEvents,
         AuthorizationStatus
     };
 }
@@ -822,6 +824,11 @@ declare interface Document_2 {
      * Get document id
      */
     id(): Promise<string | undefined>;
+    /**
+     * @experimental - Experimental API
+     * Get document Link
+     */
+    link(options: LinkOptions): Promise<string | undefined>;
     /**
      * Get document name/title
      */
@@ -845,14 +852,21 @@ export { Document_2 as Document };
 /**
  * The payload data sent to the document id available event handler.
  */
-declare interface DocumentIdAvailableEventData {
+export declare interface DocumentIdAvailableEventData {
     documentId: string | undefined;
 }
 
+/**
+ * The payload data sent to the document link available event handler.
+ */
+export declare interface DocumentLinkAvailableEventData {
+    documentLink: string | undefined;
+}
+
 /**
  * The payload data sent to the document title change event handler.
  */
-declare interface DocumentTitleChangeEventData {
+export declare interface DocumentTitleChangeEventData {
     documentTitle: string;
 }
 
@@ -889,7 +903,7 @@ export declare interface DragCompletionData {
 /**
  * Interface to provide drag options which can be passed to enableDragToDocument to change the drag behavior.
  */
-declare interface DragOptions {
+export declare interface DragOptions {
     /**
      * Use preview size for the drag image instead of the element size
      */
@@ -1052,6 +1066,17 @@ export declare interface JpgRenditionOptions extends RenditionOptions {
     };
 }
 
+/**
+ * @experimental - Experimental API
+ * Link options for document link
+ */
+export declare enum LinkOptions {
+    /**
+     * Link to the current document
+     */
+    document = "document"
+}
+
 /**
  * Takes the raw type of a remote object or function as a remote thread would see it through a proxy (e.g. when
  * passed in as a function argument) and returns the type the local thread has to supply.
@@ -1749,7 +1774,7 @@ declare type UnproxyOrClone<T> = T extends RemoteObject<ProxyMarked> ? Local<T>
 /**
  * Callback to unregister iframe from the add-on SDK.
  */
-declare type UnregisterIframe = () => void;
+export declare type UnregisterIframe = () => void;
 
 /**
  * Types of dialog variants supported.