diff --git a/common/changes/@adobe/ccweb-add-on-sdk-types/release-20241003_2024-10-03-11-14.json b/common/changes/@adobe/ccweb-add-on-sdk-types/release-20241003_2024-10-03-11-14.json new file mode 100644 index 0000000..f901eeb --- /dev/null +++ b/common/changes/@adobe/ccweb-add-on-sdk-types/release-20241003_2024-10-03-11-14.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@adobe/ccweb-add-on-sdk-types", + "comment": "New Text, SelectionChange, PerElementMetadata experimental document sandbox APIs", + "type": "minor" + } + ], + "packageName": "@adobe/ccweb-add-on-sdk-types" +} \ No newline at end of file diff --git a/packages/wxp-sdk-types/package.json b/packages/wxp-sdk-types/package.json index cd83cc6..54de3cf 100644 --- a/packages/wxp-sdk-types/package.json +++ b/packages/wxp-sdk-types/package.json @@ -1,6 +1,6 @@ { "name": "@adobe/ccweb-add-on-sdk-types", - "version": "1.9.1", + "version": "1.10.0", "author": "Adobe", "license": "MIT", "description": "Type definitions for Adobe Creative Cloud Web Add-on SDK.", diff --git a/packages/wxp-sdk-types/sandbox/express-document-sdk.d.ts b/packages/wxp-sdk-types/sandbox/express-document-sdk.d.ts index b076e89..2aa4be2 100644 --- a/packages/wxp-sdk-types/sandbox/express-document-sdk.d.ts +++ b/packages/wxp-sdk-types/sandbox/express-document-sdk.d.ts @@ -26,18 +26,122 @@ import { mat2d } from "gl-matrix"; +/** + * AddOnData class provides APIs to read, write, remove private metadata to a Node. + * This metadata is accessible only to the add-on that has set it. + */ +export declare class AddOnData { + /** + * + * + * **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 + * Sets a private metadata entry on the node. + * @param key - The key for the private metadata entry. + * @param value - The value for the private metadata entry. + */ + setItem(key: string, value: string): void; + /** + * + * + * **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 + * Retrieves the private metadata value for the specified key on the node. + * @param key - The key of the private metadata entry to retrieve. + * @returns The value of the private metadata entry. + */ + getItem(key: string): string | undefined; + /** + * + * + * **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 + * Removes a single private metadata entry on the node. + * @param key - The key of the private metadata entry to remove. + */ + removeItem(key: string): void; + /** + * + * + * **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 + * Clears all private metadata entries on the node. + */ + clear(): void; + /** + * + * + * **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 an array of all keys for the private metadata entries on the node. + */ + keys(): string[]; + /** + * + * + * **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 an object with the remaining quota for private metadata on the node for this add-on. + * The object contains the following properties: + * - sizeInBytes: The remaining quota size in bytes (maximum 3KB). + * - numKeys: The remaining quota for the number of keys (maximum 20 keys). + */ + get remainingQuota(): Readonly<{ + sizeInBytes: number; + numKeys: number; + }>; + /** + * @returns an iterator for all the private metadata entries on the node. + * The iterator yields the metadata key-value pairs. + */ + [Symbol.iterator](): Iterator<[string, string]>; +} + declare namespace ApiConstants { - export { ArrowHeadType, BlendMode, FillRule, FillType, SceneNodeType, StrokePosition, StrokeType, TextAlignment }; + export { + ArrowHeadType, + BlendMode, + FillRule, + FillType, + SceneNodeType, + StrokePosition, + StrokeType, + TextAlignment, + TextType, + EditorEvent, + VisualEffectType + }; } declare interface ApiModuleExport { editor: ExpressEditor; constants: unknown; colorUtils: ExpressColorUtils; + fonts: ExpressFonts; } /** * + * + * **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 + */ +export declare interface AreaTextLayout { + type: TextType.area; + width: number; + height: number; +} + +/** + * + * * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. */ declare enum ArrowHeadType { @@ -73,6 +177,7 @@ export declare class ArtboardList extends RestrictedItemList { * An ArtboardNode represents an artboard object in the scenegraph. All user visual content must be contained on an artboard. * * When multiple artboards exist on a page, the artboards represent "scenes" in a linear timeline sequence. + * Please note that creating and deleting an artboard in a single frame will crash the editor. */ export declare class ArtboardNode extends VisualNode implements IRectangularNode, ContainerNode { /** @@ -107,6 +212,87 @@ export declare class ArtboardNode extends VisualNode implements IRectangularNode get height(): number; } +/** + * + * + * **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 + */ +export declare interface AutoHeightTextLayout { + type: TextType.autoHeight; + width: number; +} + +/** + * Font the current user has access or licensing permissions to create / edit content with. + */ +export declare class AvailableFont extends BaseFont { + /** + * + * + * **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 + * Whether the font is a premium Adobe font. + */ + get isPremium(): boolean; + get availableForEditing(): true; +} + +/** + * + * + * **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 + * Base character styles that can be applied to a range of characters. + */ +declare interface BaseCharacterStyles { + fontSize: number; + color: Color; + tracking: number; + underline: boolean; +} + +/** + * Represents a font that is able to be rendered within this document. However, the user may not have edit permissions for + * all such fonts. + */ +declare abstract class BaseFont { + /** + * + * + * **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 + * The PostScript name of the font. + */ + get postscriptName(): string; + /** + * + * + * **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 + * The font family containing the font. + */ + get family(): string; + /** + * + * + * **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 + * The style of the font within the family. + */ + get style(): string; + /** + * Whether the current user has permission to create / edit content using this font. + */ + abstract get availableForEditing(): boolean; +} + /** * A "node" represents an object in the scenegraph, the document's visual content tree. This base class includes only the * most fundamental nonvisual properties that even nodes near the top of the document structure share (such as PageNode). @@ -114,6 +300,16 @@ export declare class ArtboardNode extends VisualNode implements IRectangularNode * properties. */ export declare class BaseNode { + /** + * + * + * **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 + * Get {@link AddOnData} reference for managing the private metadata on this node for this add-on. + */ + get addOnData(): AddOnData; + /** * A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is * moved to a different part of the document. @@ -170,6 +366,7 @@ export declare interface BitmapImage { /** * + * * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. * * Determines how a scenenode is composited on top of the content rendered below it. @@ -212,6 +409,50 @@ declare enum BlendMode { luminosity = 17 } +/** + * + * + * **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 + * Text styles of a range of characters, even a short span like a single word. + */ +export declare interface CharacterStyles extends BaseCharacterStyles { + font: Font; +} + +/** + * + * + * **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 + * Input shape of the applyCharacterStyle API. + */ +export declare interface CharacterStylesInput extends Partial { + font?: AvailableFont; +} + +/** + * + * + * **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 + * Output shape of the characterStyleRange getter. + */ +export declare interface CharacterStylesRange extends CharacterStyles, StyleRange {} + +/** + * + * + * **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 + * Input shape of the characterStyleRange setter. + */ +export declare interface CharacterStylesRangeInput extends CharacterStylesInput, StyleRange {} + /** * Represents an RGBA color value. */ @@ -344,6 +585,32 @@ export declare class Context { * @returns The currently viewed page. */ get currentPage(): PageNode; + /** + * + * + * **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 + * Registers a handler for editor events such as selection change. + * The registered callback will be invoked when the specified event occurs. + * Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application. + * @param eventName - an editor event name. + * @param callback - a callback to be registered for an editor event. + * @returns a unique ID for the registered event handler. + */ + on(eventName: EditorEvent, callback: EditorEventHandler): EventHandlerId; + /** + * + * + * **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 + * Unregisters handlers for editor events like selection change. + * @param eventName - an editor event name. + * @param handlerId - a unique ID returned by `editor.context.on` API. + * Callback that was previously registered will be removed and will no more be invoked when the event occurs. + */ + off(eventName: EditorEvent, handlerId: EventHandlerId): void; } /** @@ -364,7 +631,7 @@ export declare class Editor { * Generally, calling any setter or method is treated as an edit; but simple getters may be safely called at any time. * * Example of typical usage: - * ```javascript + * ```js * // Assume insertImage() is called from your UI code, and given a Blob containing image data * async function insertImage(blob) { * // This function was invoked from the UI iframe, so we can make any edits we want synchronously here. @@ -473,8 +740,11 @@ export declare class Editor { makeStroke(options?: Partial): SolidColorStroke; /** * @returns a text node with default styles. The text content is initially empty, so the text node will be - * invisible until its `text` property is set. Creates point text, so the node's width will automatically + * invisible until its `fullContent` property's `text` is set. Creates point text, so the node's width will automatically * adjust to accommodate whatever text is set. + * + * Note: the registration point of this text node is not guaranteed to be at the top-left of the bounding box of its + * insertion parent. Recommend using `setPositionInParent` over `translation` to set the position. */ createText(): TextNode; /** @@ -489,6 +759,28 @@ export declare class Editor { export declare const editor: ExpressEditor; +/** + * + * + * **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 + * This enum represents the supported editor events. + */ +export declare enum EditorEvent { + selectionChange = "selectionChange" +} + +/** + * + * + * **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 + * This type represents function signature for the editor event handler callback. + */ +export declare type EditorEventHandler = () => void; + /** * An EllipseNode represents an ellipse object in the scenegraph. */ @@ -513,6 +805,16 @@ export declare class EllipseNode extends FillableNode { set ry(value: number); } +/** + * + * + * **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 + * This type represents unique id of each event handler callback that is registered. + */ +export declare type EventHandlerId = string; + declare const expressApiModule: ApiModuleExport; export default expressApiModule; @@ -520,6 +822,8 @@ declare class ExpressColorUtils extends ColorUtils {} declare class ExpressEditor extends Editor {} +declare class ExpressFonts extends Fonts {} + /** * An ExpressRootNode represents the root node of the document's "scenegraph" artwork tree. The root contains a collection * of {@link pages}. Each page contains one or more artboards, arranged in a timeline sequence. All the visual content of @@ -559,6 +863,7 @@ export declare class FillableNode extends StrokableNode implements IFillableNode /** * + * * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. * * The fill rule, aka "winding rule," specifies how the interior area of a path is determined in cases where the path is @@ -571,9 +876,11 @@ declare enum FillRule { /** * + * * *Do not depend on the literal string values of these constants*, as they may change. Always reference the enum identifiers in your code. * * + * * *Additional fill types may be added in the future.* If your code has different branches or cases depending on fill type, * always have a default/fallback case to handle any unknown values you may encounter. */ @@ -582,11 +889,58 @@ declare enum FillType { color = "Color" } +/** + * + * + * **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 + * Represents a font in the document. + * + * Note: not every font encountered in the existing content is available for editing. + * Check the `availableForEditing` property to be sure. + */ +export declare type Font = AvailableFont | UnavailableFont; + +/** + * The Fonts class provides methods to work with fonts. + */ +export declare class Fonts { + /** + * + * + * **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 + * Get an {@link AvailableFont} that exactly matches the given PostScript name, if any. Only fonts that the user has permission to use + * for editing content are returned, so the result of this call is always safe to apply to a {@link TextContentModel}'s styles. + * + * @param postscriptName - The PostScript name of the font. + * @returns The Font object if found and available for editing, otherwise undefined. + */ + fromPostscriptName(postscriptName: string): Promise; +} + +export declare const fonts: ExpressFonts; + +/** + * A GridCellNode represents the MediaContainerNode aspect of a grid cell. Unlike other MediaContainerNodes, + * GridCellNodes cannot be translated or rotated directly. This implementation translates and rotates the + * MediaRectangle child of the GridCellNode when those actions are applied. + */ +export declare class GridCellNode extends MediaContainerNode {} + /** * A GridLayoutNode represents a grid layout in the scenegraph. The GridLayoutNode is used to create * a layout grid that other content can be placed into. */ export declare class GridLayoutNode extends Node implements Readonly { + /** + * The Grid's regular children. Does not include rectangles and skips over media constainer nodes to return fill grandchildren. + * Grid Cells are ordered by the y and then x position of their top left corner, i.e. left to right and top to bottom. + * The children cannot be added or removed. + */ + get allChildren(): Readonly>; /** * The background fill of the GridLayout. */ @@ -688,6 +1042,8 @@ export declare class ItemList extends RestrictedItemList /** * Add one or more items to the end of the list. The last argument will become the last item in this list. Items are * removed from their previous parent, if any – or if an item is already in *this* list, its index is simply changed. + * + * @throws - if item has a different parent and item is a {@link TextNode} that's a part of a Text Flow, or if item's children subtree contains a TextNode who is a part of a Text Flow. */ append(...items: T[]): void; /** @@ -698,18 +1054,24 @@ export declare class ItemList extends RestrictedItemList * Replace `oldItem` with `newItem` in this list. Throws if `oldItem` is not a member of this list. * `newItem` is removed from its previous parent, if any – or if it's already in *this* list, its index is simply * changed. No-op if both arguments are the same item. + * + * @throws - if newItem has a different parent and newItem is a {@link TextNode} that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow. */ replace(oldItem: T, newItem: T): void; /** * Insert `newItem` so it is immediately before `before` in this list: places `newItem` at the index that `before` used * to occupy, shifting `before` and all later items to higher indices. `newItem` is removed from its previous parent, * if any – or if it's already in *this* list, its index is simply changed. No-op if both arguments are the same item. + * + * @throws - if newItem has a different parent and it is a {@link TextNode} that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow. */ insertBefore(newItem: T, before: T): void; /** * Insert `newItem` so it is immediately after `after` in this list: places `newItem` at the index one higher than `after`, * shifting all later items to higher indices (the index of `after` remains unchanged). `newItem` is removed from its previous parent, * if any – or if it's already in *this* list, its index is simply changed. No-op if both arguments are the same item. + * + * @throws - if newItem has a different parent and it is a {@link TextNode} that's a part of a Text Flow, or if newItem's children subtree contains a TextNode who is a part of a Text Flow. */ insertAfter(newItem: T, after: T): void; } @@ -993,6 +1355,17 @@ export declare interface Point { y: number; } +/** + * + * + * **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 + */ +export declare interface PointTextLayout { + type: TextType.autoWidth; +} + /** * ReadOnlyItemList represents an ordered list of API objects, representing items that are all children of the * same parent node. (The reverse is not necessarily true, however: this list might not include all @@ -1144,9 +1517,11 @@ declare class RestrictedItemList extends ReadOnlyItemList /** * + * * *Do not depend on the literal string values of these constants*, as they may change. Always reference the enum identifiers in your code. * * + * * *Additional node types may be added in the future.* If your code has different branches or cases depending on node type, * always have a default/fallback case to handle any unknown values you may encounter. */ @@ -1155,7 +1530,6 @@ declare enum SceneNodeType { rectangle = "Rectangle", ellipse = "Ellipse", path = "Path", - text = "Text", linkedAsset = "LinkedAsset", group = "Group", artboard = "ab:Artboard", @@ -1173,8 +1547,12 @@ declare enum SceneNodeType { solidColorShape = "SolidColorShape", /** Type of StrokeShapeNode, representing a stroke-only prepackaged shape that appears as a leaf node in the UI */ strokeShape = "StrokeShape", + /** Type of MediaContainerNode which is a child of a GridLayout, representing one of the Grid's cells*/ + gridCell = "GridCell", /** Type of GridLayoutNode represents a grid layout in the scenegraph used to create a layout grid that other content can be placed into */ - gridLayout = "GridLayout" + gridLayout = "GridLayout", + /** Type of TextNode, representing a non-threaded text or a threaded text frame */ + text = "Text" } /** @@ -1255,6 +1633,7 @@ export declare interface Stroke { /** * + * * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. * * A stroke's {@link Stroke.position} determines how the thickness of the stroke is aligned along a shape's path outline. @@ -1273,9 +1652,11 @@ export declare class StrokeShapeNode extends StrokableNode {} /** * + * * *Do not depend on the literal string values of these constants*, as they may change. Always reference the enum identifiers in your code. * * + * * *Additional stroke types may be added in the future.* If your code has different branches or cases depending on stroke type, * always have a default/fallback case to handle any unknown values you may encounter. */ @@ -1286,8 +1667,21 @@ declare enum StrokeType { color = "Color" } +/** + * Represents a range of characters defined by a length (and implicitly started at the end of the previous range). + */ +declare interface StyleRange { + /** + * The length or number of characters in which character styles will be applied. + * Note: since characters are represented as UTF-16 code units, some symbols + * such as emojis are considered to have a length of 2. + */ + length: number; +} + /** * + * * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. */ declare enum TextAlignment { @@ -1297,22 +1691,180 @@ declare enum TextAlignment { } /** - * A TextNode represents a text object in the scenegraph. + * Represents a complete piece of text content flow, which may be split across multiple {@link TextNode} frames for display. + * Use this model to get or modify the text string and the style ranges applied to it. + */ +export declare class TextContentModel { + /** + * + * + * **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 + * A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is + * moved to a different part of the document. + * + * To determine if two TextNodes are connected to the same TextContentModel, + * check if both models have the same id. + * Comparing two models using `===` will always fail. + */ + get id(): string; + /** + * + * + * **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 + * Get ordered list of all {@link TextNode}s that display this text content in the scenegraph. The text content + * starts in the first {@link TextNode} "frame", and then flows into the second node once it has filled the first one. The ending of the + * text content may not be visible at all, if the last {@link TextNode} "frame" is not large enough to accommodate it. + * + * If there are multiple {@link TextNode}s, all of them must be configured to use {@link AreaTextLayout}. + */ + get allTextNodes(): Readonly>; + /** + * The complete text string, which may span multiple {@link TextNode} "frames" in the scenegraph. + */ + get text(): string; + set text(textContent: string); + /** + * + * + * **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 + * The character style ranges of this text content. + */ + get characterStyleRanges(): readonly CharacterStylesRange[]; + set characterStyleRanges(styles: readonly CharacterStylesRangeInput[]); + /** + * + * + * **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 + * Apply one or more styles to the characters in the given range, leaving other styles in this range unchanged. Does + * not modify any styles in the text outside this range. + * @param styles - The styles to apply. + * @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. + */ + applyCharacterStyles( + styles: CharacterStylesInput, + range?: { + start: number; + length: number; + } + ): void; +} + +/** + * A TextNode represents a text display frame in the scenegraph. It may display an entire piece of text, or sometimes just + * a subset of longer text that flows across multiple TextNode "frames". Because of this, the TextNode does not directly hold + * the text content and styles – instead it refers to a {@link TextContentModel}, which may be shared across multiple TextNodes. */ export declare class TextNode extends Node { /** - * The text string of the node. + * The model containing the complete text string and its styles, only part of which may be visible within the bounds of + * this specific TextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a + * fixed-size frame using {@link AreaTextLayout} does not fit all the (remaining) text. + * + * Note: When traversing the scenegraph in search of text content, bear in mind that multiple TextNodes may refer to the + * same single {@link TextContentModel}; this can give the impression that the same text is duplicated multiple times when it is + * not. Use {@link TextContentModel}.id to determine whether a given piece of text content is unique or if it's already been + * encountered before. + */ + get fullContent(): TextContentModel; + /** + * + * + * **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 + * The next TextNode that text overflowing this node will spill into, if any. If undefined and this TextNode is fixed size + * ({@link AreaTextLayout}), any text content that does not fit within this node's area will be clipped. + * + * To get *all* TextNodes that the text content may be split across, use `TextNode.fullContent.allTextNodes`. + */ + get nextTextNode(): TextNode | undefined; + /** + * The text string content which is partially *or* fully displayed in this TextNode "frame." + * WARNING: If a piece of text content flows across several TextNodes, *each* TextNode's `text` getter will return + * the *entire* text content string. + * @deprecated - Use the text getter on {@link TextContentModel} instead. Access it via `TextNode.fullContent.text`. */ get text(): string; /** - * Sets the text content of the text node. + * Sets the text content of the TextNode. + * WARNING: If a piece of text content flows across several TextNodes, + * *each* TextNode's `text` setter will sets the *entire* text content string. + * @deprecated - Use the text setter on {@link TextContentModel} instead. Access it via `TextNode.fullContent.text`. */ set text(textContent: string); /** - * The horizontal text alignment of the text node. Alignment is always the same across this node's entire text content. + * The horizontal text alignment of the TextNode. Alignment is always the same across this node's entire text content. */ get textAlignment(): TextAlignment; set textAlignment(alignment: TextAlignment); + /** + * + * + * **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 The list of visual effects applied to the TextNode. + */ + get visualEffects(): readonly VisualEffectType[]; + /** + * + * + * **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 The layout mode of the TextNode "frame." + */ + get layout(): Readonly; + /** + * + * + * **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 + * Sets the layout mode of the TextNode "frame." + * + * If this TextNode is part of a multi-frame text content flow, it must be configured to use {@link AreaTextLayout}. Other + * layout modes 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 TextNode is part of a multi-frame text content flow and the layout is not {@link AreaTextLayout}. + */ + set layout(layout: PointTextLayout | AutoHeightTextLayout | AreaTextLayout); +} + +/** + * + * + * *Do not depend on the literal numeric values of these constants*, as they may change. Always reference the enum identifiers in your code. + */ +declare enum TextType { + /** + * Point text + */ + autoWidth = 0, + /** + * Soft bottom + */ + autoHeight = 1, + area = 2, + magicFit = 3, + circular = 4 +} + +/** + * Font the current user does not have access or licensing permissions to create / edit content with. + */ +export declare class UnavailableFont extends BaseFont { + get availableForEditing(): false; } /** @@ -1320,6 +1872,32 @@ export declare class TextNode extends Node { */ export declare class UnknownNode extends Node {} +/** + * + * + * **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 + */ +export declare interface UnsupportedTextLayout { + type: TextType.magicFit | TextType.circular; +} + +/** + * + * + * **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 + * Visual effects that can be applied to a text node. + */ +declare enum VisualEffectType { + generativeTextEffects = "GenerativeTextEffects", + outline = "Outline", + shadow = "Shadow", + shapeDecoration = "ShapeDecoration" +} + /** * A "node" represents an object in the scenegraph, the document's visual content tree. This class represents any node * that can be visually perceived in the content. Most visual content is a subclass of the richer Node class which extends diff --git a/packages/wxp-sdk-types/ui/ui-sdk.d.ts b/packages/wxp-sdk-types/ui/ui-sdk.d.ts index c61827c..f535680 100644 --- a/packages/wxp-sdk-types/ui/ui-sdk.d.ts +++ b/packages/wxp-sdk-types/ui/ui-sdk.d.ts @@ -259,7 +259,6 @@ declare interface ApplicationBase { */ startPremiumUpgradeIfFreeUser(): Promise; /** - * @experimental - Experimental API * Get information regarding current platform. * @returns the details regarding the current platform. */ @@ -519,7 +518,6 @@ declare namespace Constants { export { Constants }; /** - * @experimental - Experimental API * Interface for the current platform */ export declare interface CurrentPlatformPayload { @@ -599,7 +597,6 @@ export declare interface DevFlags { } /** - * @experimental - Experimental API * Denotes the device class */ export declare enum DeviceClass { @@ -683,9 +680,13 @@ export declare type DisableDragToDocument = () => void; */ declare interface Document_2 { /** - * Add image/gif/Ps/Ai files to the current page + * Add image/Ps/Ai files to the current page */ addImage(blob: Blob, attributes?: MediaAttributes): Promise; + /** + * Add GIF files to the current page + */ + addAnimatedImage(blob: Blob, attributes?: MediaAttributes): Promise; /** * Add video to the current page */ @@ -1231,7 +1232,6 @@ export declare interface PdfRenditionOptions extends RenditionOptions { } /** - * @experimental - Experimental API * Denotes the enum for current environment */ export declare enum PlatformEnvironment { @@ -1246,7 +1246,6 @@ export declare enum PlatformEnvironment { } /** - * @experimental - Experimental API * Denotes the type of platform */ export declare enum PlatformType { diff --git a/rush.json b/rush.json index c6bcd97..ca5ec7e 100644 --- a/rush.json +++ b/rush.json @@ -19,49 +19,49 @@ "packageName": "@adobe/ccweb-add-on-manifest", "projectFolder": "packages/add-on-manifest", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-core", "projectFolder": "packages/wxp-core", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/create-ccweb-add-on", "projectFolder": "packages/create-ccweb-add-on", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-scaffolder", "projectFolder": "packages/wxp-add-on-scaffolder", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-scripts", "projectFolder": "packages/wxp-scripts", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-ssl", "projectFolder": "packages/wxp-ssl", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-analytics", "projectFolder": "packages/wxp-analytics", "reviewCategory": "production", - "shouldPublish": true + "shouldPublish": false }, { "packageName": "@adobe/ccweb-add-on-sdk-types", "projectFolder": "packages/wxp-sdk-types", "reviewCategory": "production", - "shouldPublish": false + "shouldPublish": true } ] } diff --git a/scripts/pre-release.sh b/scripts/pre-release.sh index d2a76bf..6ce23bc 100755 --- a/scripts/pre-release.sh +++ b/scripts/pre-release.sh @@ -55,6 +55,15 @@ find -E ./wxp-sdk-types -type f -regex '.*package\.json' -exec sed -i '.bak' 's/ find ./wxp-sdk-types -name '*.bak' -type f -delete echo $'Done!\n' +echo 'Fixing tsconfig.json ...' +find -E ./ -type f -regex '.*tsconfig\.json' -exec sed -i '.bak' '/"inlineSources/d;' {} \; +find . -name '*.bak' -type f -delete +find -E ./ -type f -regex '.*tsconfig\.json' -exec sed -i '.bak' '/"rootDir/d;' {} \; +find . -name '*.bak' -type f -delete +find -E ./ -type f -regex '.*tsconfig\.json' -exec sed -i '.bak' '/"tsBuildInfoFile/d;' {} \; +find . -name '*.bak' -type f -delete +echo $'Done!\n' + echo 'Removing eslint configurations ...' find . -name '.eslintignore' -type f -delete find . -name '.eslintrc' -type f -delete