@shopify/ui-extensions 2025.10.13 → 2025.10.14

package/build/ts/surfaces/admin/components/Image.d.ts

@@ -16,24 +16,44 @@ import type {
   ComponentChildren,
 } from './shared.d.ts';
 
+/**
+ * A callback event that's typed to a specific HTML element. This type provides access to the element that triggered the event.
+ */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  /**
+   * The element that currently has the event listener attached.
+   */
   currentTarget: HTMLElementTagNameMap[T];
 };
+/**
+ * An event listener for callback events, typed to a specific HTML element.
+ */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
       (event: CallbackEvent<T>): void;
     })
   | null;
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists change by tracking which items have been added, removed, or reordered.
+   */
   key?: preact.Key;
-  /** Assigns a ref (generally from `useRef()`) to this element. */
+  /**
+   * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+   */
   ref?: preact.Ref<TClass>;
-  /** Assigns this element to a parent's slot. */
+  /**
+   * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns.
+   */
   slot?: Lowercase<string>;
 }
 
+/**
+ * Makes a type value responsive by allowing container query strings.
+ */
 export type MakeResponsive<T> = T | `@container${string}`;
 /**
  * Makes a property's value potentially responsive.
@@ -55,7 +75,13 @@ export type MakeResponsivePick<TType, TProperty extends keyof TType> = {
   [P in TProperty]: MakeResponsive<TType[P]>;
 };
 
+/**
+ * The box properties with all fields marked as required.
+ */
 export type RequiredBoxProps = Required<BoxProps$1>;
+/**
+ * The available border radius values for Box components.
+ */
 export type BoxBorderRadii = Extract<
   RequiredBoxProps['borderRadius'],
   | 'none'
@@ -67,10 +93,16 @@ export type BoxBorderRadii = Extract<
   | 'large-100'
   | 'large-200'
 >;
+/**
+ * The available border style values for Box components.
+ */
 export type BoxBorderStyles = Extract<
   RequiredBoxProps['borderStyle'],
   'none' | 'solid' | 'dashed' | 'auto'
 >;
+/**
+ * The box properties that support responsive values through container queries.
+ */
 export type ResponsiveBoxProps = MakeResponsivePick<
   RequiredBoxProps,
   | 'padding'
@@ -103,7 +135,7 @@ export interface BoxProps
     | 'overflow'
   > {
   /**
-   * Adjust the background of the component.
+   * The background color of the image container.
    *
    * @default 'transparent'
    */
@@ -112,7 +144,16 @@ export interface BoxProps
     'transparent' | 'base' | 'subdued' | 'strong'
   >;
   /**
-   * Adjust the width of the border.
+   * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
+   *
+   * - `small`: Thin border for subtle definition.
+   * - `small-100`: Extra thin border for minimal emphasis.
+   * - `base`: Standard border width.
+   * - `large`: Thick border for strong emphasis.
+   * - `large-100`: Extra thick border for maximum prominence.
+   * - `none`: No border.
+   *
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different widths per side.
    *
    * @default '' - meaning no override
    */
@@ -125,7 +166,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Adjust the style of the border.
+   * The visual style of the border (solid, dashed, auto, or none).
    *
    * @default '' - meaning no override
    */
@@ -133,7 +174,7 @@ export interface BoxProps
     | MaybeAllValuesShorthandProperty<BoxBorderStyles>
     | Extract<RequiredBoxProps['borderStyle'], ''>;
   /**
-   * Adjust the color of the border.
+   * The color of the border using the design system's color scale.
    *
    * @default '' - meaning no override
    */
@@ -142,13 +183,13 @@ export interface BoxProps
     'subdued' | 'base' | 'strong' | ''
   >;
   /**
-   * Adjust the radius of the border.
+   * The roundedness of the corners using the design system's radius scale.
    *
    * @default 'none'
    */
   borderRadius: MaybeAllValuesShorthandProperty<BoxBorderRadii>;
   /**
-   * Adjust the padding of all edges.
+   * The padding applied to all edges of the image container.
    *
    * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
    *
@@ -164,71 +205,71 @@ export interface BoxProps
    *
    * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
    *
-   * `padding` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `padding` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default 'none'
    */
   padding: ResponsiveBoxProps['padding'];
   /**
-   * Adjust the block-padding.
+   * The padding applied to the block axis (top and bottom in horizontal writing modes).
    *
    * - `large none` means block-start padding is `large`, block-end padding is `none`.
    *
    * This overrides the block value of `padding`.
    *
-   * `paddingBlock` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingBlock` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlock: ResponsiveBoxProps['paddingBlock'];
   /**
-   * Adjust the block-start padding.
+   * The padding applied to the block-start edge (top in horizontal writing modes).
    *
    * This overrides the block-start value of `paddingBlock`.
    *
-   * `paddingBlockStart` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingBlockStart` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart: ResponsiveBoxProps['paddingBlockStart'];
   /**
-   * Adjust the block-end padding.
+   * The padding applied to the block-end edge (bottom in horizontal writing modes).
    *
    * This overrides the block-end value of `paddingBlock`.
    *
-   * `paddingBlockEnd` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingBlockEnd` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd: ResponsiveBoxProps['paddingBlockEnd'];
   /**
-   * Adjust the inline padding.
+   * The padding applied to the inline axis (left and right in horizontal writing modes).
    *
    * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
    *
    * This overrides the inline value of `padding`.
    *
-   * `paddingInline` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingInline` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingInline: ResponsiveBoxProps['paddingInline'];
   /**
-   * Adjust the inline-start padding.
+   * The padding applied to the inline-start edge (left in left-to-right languages).
    *
    * This overrides the inline-start value of `paddingInline`.
    *
-   * `paddingInlineStart` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingInlineStart` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart: ResponsiveBoxProps['paddingInlineStart'];
   /**
-   * Adjust the inline-end padding.
+   * The padding applied to the inline-end edge (right in left-to-right languages).
    *
    * This overrides the inline-end value of `paddingInline`.
    *
-   * `paddingInlineEnd` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
+   * `paddingInlineEnd` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
@@ -243,43 +284,51 @@ export interface BoxProps
    */
   display: ResponsiveBoxProps['display'];
   /**
-   * Adjust the [block size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
+   * The vertical size of the image in standard layouts (height in left-to-right or right-to-left writing modes).
+   *
+   * Block size adjusts based on the writing direction: in horizontal layouts, it controls the height;
+   * in vertical layouts, it controls the width. This ensures consistent behavior across different text directions.
+   *
+   * Learn more about [block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
    *
    * @default 'auto'
    */
   blockSize: SizeUnitsOrAuto;
   /**
-   * Adjust the [minimum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
+   * The [minimum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) (minimum height in horizontal writing modes) of the image.
    *
    * @default '0'
    */
   minBlockSize: SizeUnits;
   /**
-   * Adjust the [maximum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
+   * The [maximum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) (maximum height in horizontal writing modes) of the image.
    *
    * @default 'none'
    */
   maxBlockSize: SizeUnitsOrNone;
   /**
-   * Adjust the [inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
+   * The [inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) (width in horizontal writing modes) of the image.
    *
    * @default 'auto'
    */
   inlineSize: SizeUnitsOrAuto;
   /**
-   * Adjust the [minimum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
+   * The [minimum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) (minimum width in horizontal writing modes) of the image.
    *
    * @default '0'
    */
   minInlineSize: SizeUnits;
   /**
-   * Adjust the [maximum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
+   * The [maximum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) (maximum width in horizontal writing modes) of the image.
    *
    * @default 'none'
    */
   maxInlineSize: SizeUnitsOrNone;
 }
 
+/**
+ * The properties for the image component. An image displays pictures with configurable sizing, loading behavior, and borders. Properties include `src` for the image URL, `alt` for accessibility text, `aspectRatio` for sizing, `loading` for lazy loading, and border styling options.
+ */
 export interface ImageProps
   extends Required<
       Pick<
@@ -304,31 +353,121 @@ export interface ImageProps
         | 'borderStyle'
         | 'borderWidth'
       >
-    > {}
+    > {
+  /**
+   * The URL of the image to display. You can provide an absolute or relative URL pointing to the image file.
+   */
+  src: ImageProps$1['src'];
+  /**
+   * A set of source images with different sizes for responsive loading. Use this to provide multiple image sizes for different screen resolutions (for example, `'image-320w.jpg 320w, image-640w.jpg 640w'`).
+   */
+  srcSet: ImageProps$1['srcSet'];
+  /**
+   * The sizes of the image at different viewport widths. Use this with `srcSet` to tell the browser which image to load (for example, `'(max-width: 320px) 280px, 640px'`).
+   */
+  sizes: ImageProps$1['sizes'];
+  /**
+   * Alternative text that describes the image for screen readers. This text should convey the meaning or content of the image to users who can't see it.
+   */
+  alt: ImageProps$1['alt'];
+  /**
+   * The aspect ratio of the image as a width-to-height ratio (for example, `'16/9'` or `'1'`). This helps prevent layout shifts while the image loads.
+   */
+  aspectRatio: ImageProps$1['aspectRatio'];
+  /**
+   * How the image should be resized to fit its container. Choose `'cover'` to fill the container while maintaining aspect ratio (cropping if needed), or `'contain'` to fit the entire image within the container.
+   */
+  objectFit: ImageProps$1['objectFit'];
+  /**
+   * When the image should be loaded. Use `'lazy'` to defer loading until the image is near the viewport, or `'eager'` to load immediately.
+   */
+  loading: ImageProps$1['loading'];
+  /**
+   * The accessibility role for the image. Set this to provide semantic meaning for screen readers.
+   */
+  accessibilityRole: ImageProps$1['accessibilityRole'];
+  /**
+   * The inline size (width in horizontal writing modes) of the image. You can use size units like `'100px'` or `'50%'`.
+   */
+  inlineSize: ImageProps$1['inlineSize'];
+  /**
+   * Whether to show a border around the image. Set to `true` to display a border, or `false` to hide it.
+   */
+  border: BoxProps['border'];
+  /**
+   * The width of the border around the image. You can use a single value to apply the same width to all sides, or use the 1-to-4-value syntax to control individual sides.
+   */
+  borderWidth: BoxProps['borderWidth'];
+  /**
+   * The style of the border around the image. You can use a single value to apply the same style to all sides, or use the 1-to-4-value syntax to control individual sides.
+   */
+  borderStyle: BoxProps['borderStyle'];
+  /**
+   * The color of the border around the image. Choose from `'subdued'`, `'base'`, or `'strong'` to control the visual emphasis.
+   */
+  borderColor: BoxProps['borderColor'];
+  /**
+   * The radius of the border corners around the image. You can use a single value to apply the same radius to all corners, or use the 1-to-4-value syntax to control individual corners.
+   */
+  borderRadius: BoxProps['borderRadius'];
+}
 
+/**
+ * A string containing CSS styles for a custom element.
+ */
 export type Styles = string;
+/**
+ * The configuration for rendering a custom element with Preact.
+ */
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
+  /**
+   * The function that renders the shadow root content.
+   */
   ShadowRoot: (element: any) => ComponentChildren;
+  /**
+   * The optional CSS styles to apply to the shadow root.
+   */
   styles?: Styles;
 };
+/**
+ * The properties of an activation event, such as a click or keypress. These properties capture which modifier keys were pressed and which mouse button was used during the event.
+ */
 export interface ActivationEventEsque {
+  /**
+   * Whether the shift key was pressed during the event.
+   */
   shiftKey: boolean;
+  /**
+   * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during the event.
+   */
   metaKey: boolean;
+  /**
+   * Whether the control key was pressed during the event.
+   */
   ctrlKey: boolean;
+  /**
+   * The mouse button that was pressed (0 for left, 1 for middle, 2 for right).
+   */
   button: number;
 }
+/**
+ * The options for triggering a synthetic click event.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
    */
   sourceEvent?: ActivationEventEsque;
 }
 /**
- * Base class for creating custom elements with Preact.
+ * The base class for creating custom elements with Preact.
  * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
- * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
+ * So we give it a type of `HTMLElement` to avoid typing issues later where it's used, which will only happen in the browser.
  */
 declare const BaseClass: typeof globalThis.HTMLElement;
+/**
+ * An abstract base class for creating custom elements that render with Preact.
+ */
 declare abstract class PreactCustomElement extends BaseClass {
   /** @private */
   static get observedAttributes(): string[];
@@ -350,8 +489,8 @@ declare abstract class PreactCustomElement extends BaseClass {
   /** @private */
   adoptedCallback(): void;
   /**
-   * Queue a run of the render function.
-   * You shouldn't need to call this manually - it should be handled by changes to @property values.
+   * Queues a run of the render function.
+   * You shouldn't need to call this manually - it should be handled by changes to `@property` values.
    * @private
    */
   queueRender(): void;
@@ -359,29 +498,80 @@ declare abstract class PreactCustomElement extends BaseClass {
    * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
    *
    * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
-   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
+   * components will attempt to produce the desired behavior on links, such as opening the page in a background tab.
    * @private
    * @param options
    */
   click({sourceEvent}?: ClickOptions): void;
 }
 
+/**
+ * An image displays pictures with configurable sizing, loading behavior, and borders.
+ */
 declare class Image extends PreactCustomElement implements ImageProps {
+  /**
+   * The URL of the image to display.
+   */
   accessor src: ImageProps['src'];
+  /**
+   * A set of source images with different sizes for responsive loading.
+   */
   accessor srcSet: ImageProps['srcSet'];
+  /**
+   * The sizes of the image at different viewport widths.
+   */
   accessor sizes: ImageProps['sizes'];
+  /**
+   * Alternative text that describes the image for screen readers.
+   */
   accessor alt: ImageProps['alt'];
+  /**
+   * The aspect ratio of the image as a width-to-height ratio.
+   */
   accessor aspectRatio: ImageProps['aspectRatio'];
+  /**
+   * How the image should be resized to fit its container.
+   */
   accessor objectFit: ImageProps['objectFit'];
+  /**
+   * When the image should be loaded.
+   */
   accessor loading: ImageProps['loading'];
+  /**
+   * The accessibility role for the image.
+   */
   accessor accessibilityRole: ImageProps['accessibilityRole'];
+  /**
+   * The inline size (width in horizontal writing modes) of the image.
+   */
   accessor inlineSize: ImageProps['inlineSize'];
+  /**
+   * Whether to show a border around the image.
+   */
   accessor border: ImageProps['border'];
+  /**
+   * The width of the border around the image.
+   */
   accessor borderWidth: ImageProps['borderWidth'];
+  /**
+   * The style of the border around the image.
+   */
   accessor borderStyle: ImageProps['borderStyle'];
+  /**
+   * The color of the border around the image.
+   */
   accessor borderColor: ImageProps['borderColor'];
+  /**
+   * The radius of the border corners around the image.
+   */
   accessor borderRadius: ImageProps['borderRadius'];
+  /**
+   * A callback that's fired when the image has loaded successfully.
+   */
   accessor onload: CallbackEventListener<typeof tagName> | null;
+  /**
+   * A callback that's fired when the image fails to load.
+   */
   accessor onerror: OnErrorEventHandler;
   constructor();
 }
@@ -399,10 +589,19 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-image';
+/**
+ * The properties for the image component when it's used in JSX.
+ */
 export interface ImageJSXProps
   extends Partial<ImageProps>,
     Pick<ImageProps$1, 'id'> {
+  /**
+   * A callback that's fired when the image fails to load.
+   */
   onError?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * A callback that's fired when the image has loaded successfully.
+   */
   onLoad?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 

package/build/ts/surfaces/admin/components/Link/Link.doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Link.doc.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/admin/components/Link/Link.doc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,kCAAkC,EAAC,MAAM,kBAAkB,CAAC;AAGpE,QAAA,MAAM,IAAI,EAAE,kCAgQX,CAAC;AAEF,eAAe,IAAI,CAAC"}
+{"version":3,"file":"Link.doc.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/admin/components/Link/Link.doc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,kCAAkC,EAAC,MAAM,kBAAkB,CAAC;AAGpE,QAAA,MAAM,IAAI,EAAE,kCAmKX,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/build/ts/surfaces/admin/components/Link.d.ts

@@ -20,16 +20,26 @@ export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
       (event: CallbackEvent<T>): void;
     })
   | null;
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists change by tracking which items have been added, removed, or reordered.
+   */
   key?: preact.Key;
-  /** Assigns a ref (generally from `useRef()`) to this element. */
+  /**
+   * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+   */
   ref?: preact.Ref<TClass>;
-  /** Assigns this element to a parent's slot. */
+  /**
+   * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns.
+   */
   slot?: Lowercase<string>;
 }
-/** Used when an element has children. */
+/**
+ * The base properties for Preact elements that have children, extending the base element properties to include child content.
+ */
 export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
   extends PreactBaseElementProps<TClass> {
   children?: preact.ComponentChildren;
@@ -50,7 +60,18 @@ export type LinkBaseProps = Required<
     | 'tone'
   >
 >;
+/**
+ * The properties for the link component. These properties define a clickable link that navigates users to different pages or sections with customizable visual styles and semantic meaning.
+ */
 export interface LinkProps extends LinkBaseProps {
+  /**
+   * The visual appearance and semantic meaning of the link. Links rely on the tone system for semantic meaning, so using custom styling might not clearly convey intent to merchants. Available options:
+   * - `'auto'` - The system automatically chooses the appropriate tone based on context.
+   * - `'neutral'` - Standard styling for general navigation without specific semantic meaning.
+   * - `'critical'` - Red styling for links that lead to destructive actions or important warnings.
+   *
+   * @default 'auto'
+   */
   tone: Extract<RequiredLinkProps['tone'], 'auto' | 'neutral' | 'critical'>;
 }
 
@@ -67,7 +88,7 @@ export interface ActivationEventEsque {
 }
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
    */
   sourceEvent?: ActivationEventEsque;
 }
@@ -117,14 +138,12 @@ declare abstract class PreactCustomElement extends BaseClass {
 export interface PreactOverlayControlProps
   extends Pick<InteractionProps, 'commandFor' | 'interestFor'> {
   /**
-   * Sets the action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this clickable is activated.
-   *
-   * See the documentation of particular components for the actions they support.
+   * The action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated. The supported actions vary by target component type.
    *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
+   * - `--auto`: Performs the default action appropriate for the target component.
+   * - `--show`: Displays the target component if it's currently hidden.
+   * - `--hide`: Conceals the target component from view.
+   * - `--toggle`: Alternates the target component between visible and hidden states.
    *
    * @default '--auto'
    */
@@ -133,11 +152,11 @@ export interface PreactOverlayControlProps
     '--show' | '--hide' | '--toggle' | '--auto'
   >;
   /**
-   * Sets the element the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this clickable is activated.
+   * Sets the element the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this component is activated.
    */
   commandFor: Extract<InteractionProps['commandFor'], string>;
   /**
-   * Sets the element the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this clickable is activated.
+   * Sets the element the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this component is activated.
    */
   interestFor: Extract<InteractionProps['interestFor'], string>;
 }
@@ -170,14 +189,55 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-link';
+/**
+ * The JSX properties for the link component. These properties define how a link is rendered in Preact or JSX.
+ */
 export interface LinkJSXProps
   extends Partial<LinkProps>,
     Pick<LinkProps$1, 'id' | 'lang' | 'children'> {
   /**
-   * The content of the Link.
+   * The text or content to display inside the link. This typically describes the destination or action the link performs.
    */
   children?: ComponentChildren;
+  /**
+   * A callback function that's invoked when the link is clicked. It receives the click event as an argument.
+   */
   onClick?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
+   *
+   * @default ''
+   */
+  accessibilityLabel?: string;
+  /**
+   * The URL that the link navigates to when clicked. This is the primary property that defines where the link leads.
+   *
+   * @default ''
+   */
+  href?: LinkProps['href'];
+  /**
+   * Where to open the linked document. Available options:
+   * - `''` - Opens in the same frame (default behavior).
+   * - `'_blank'` - Opens in a new window or tab.
+   * - `'_self'` - Opens in the same frame (explicit version of default).
+   * - `'_parent'` - Opens in the parent frame.
+   * - `'_top'` - Opens in the full body of the window.
+   *
+   * @default ''
+   */
+  target?: LinkProps['target'];
+  /**
+   * The filename to save the linked URL as when downloaded. When provided, clicking the link will download the resource instead of navigating to it.
+   *
+   * @default ''
+   */
+  download?: LinkProps['download'];
+  /**
+   * The language of the link's content, specified as a BCP 47 language tag (such as `'en'` or `'fr'`). This helps assistive technologies pronounce content correctly.
+   *
+   * @default ''
+   */
+  lang?: string;
 }
 
 export {Link};