@shopify/ui-extensions 2026.1.3 → 2026.1.4

package/build/ts/surfaces/checkout/components/Form.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {FormProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,35 +18,49 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
+/**
+ * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ * @publicDocs
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-form";
+/** @publicDocs */
 export interface FormElementProps extends Pick<FormProps$1, 'disabled' | 'id'> {
 }
+/** @publicDocs */
 export interface FormEvents extends Pick<FormProps$1, 'onSubmit'> {
     /**
-     * A callback that is run when the form is submitted.
+     * A callback fired when the form is submitted.
      */
     onSubmit?: () => void;
 }
+/** @publicDocs */
 export interface FormElementEvents {
     /**
-     * A callback that is run when the form is submitted.
+     * A callback fired when the form is submitted.
      */
     submit?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface FormElement extends FormElementProps, Omit<HTMLElement, 'id' | 'onsubmit'> {
     onsubmit: FormEvents['onSubmit'];
 }
+/** @publicDocs */
 export interface FormProps extends FormElementProps, FormEvents {
 }
 declare global {

package/build/ts/surfaces/checkout/components/Grid.d.ts

@@ -10,16 +10,86 @@
 /// <reference lib="DOM" />
 import type {GridProps$1,MaybeResponsive, MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,AlignContentKeyword, AlignItemsKeyword, JustifyContentKeyword, JustifyItemsKeyword,ColorKeyword} from './components-shared.d.ts';
 
+/**
+ * The subset of `align-content` values available for the grid component.
+ *
+ * - `center`: Packs rows toward the center of the grid.
+ * - `start`: Packs rows toward the start of the block axis.
+ * - `end`: Packs rows toward the end of the block axis.
+ * - `normal`: Default browser behavior.
+ * - `space-between`: Distributes rows evenly with no space at the edges.
+ * - `space-around`: Distributes rows evenly with equal space around each.
+ * - `space-evenly`: Distributes rows with equal space between and at the edges.
+ * - `stretch`: Stretches rows to fill the available space.
+ *
+ * @publicDocs
+ */
 export type ReducedAlignContentKeyword = Extract<AlignContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `align-items` values available for the grid component.
+ *
+ * - `center`: Centers items along the block axis.
+ * - `start`: Aligns items to the start of the block axis.
+ * - `end`: Aligns items to the end of the block axis.
+ * - `normal`: Default browser behavior.
+ * - `baseline`: Aligns items along their text baseline.
+ * - `stretch`: Stretches items to fill the cell along the block axis.
+ *
+ * @publicDocs
+ */
 export type ReducedAlignItemsKeyword = Extract<AlignItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `justify-content` values available for the grid component.
+ *
+ * - `center`: Packs columns toward the center of the grid.
+ * - `start`: Packs columns toward the start of the inline axis.
+ * - `end`: Packs columns toward the end of the inline axis.
+ * - `normal`: Default browser behavior.
+ * - `space-between`: Distributes columns evenly with no space at the edges.
+ * - `space-around`: Distributes columns evenly with equal space around each.
+ * - `space-evenly`: Distributes columns with equal space between and at the edges.
+ * - `stretch`: Stretches columns to fill the available space.
+ *
+ * @publicDocs
+ */
 export type ReducedJustifyContentKeyword = Extract<JustifyContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `justify-items` values available for the grid component.
+ *
+ * - `center`: Centers items along the inline axis.
+ * - `start`: Aligns items to the start of the inline axis.
+ * - `end`: Aligns items to the end of the inline axis.
+ * - `normal`: Default browser behavior.
+ * - `baseline`: Aligns items along their text baseline.
+ * - `stretch`: Stretches items to fill the cell along the inline axis.
+ *
+ * @publicDocs
+ */
 export type ReducedJustifyItemsKeyword = Extract<JustifyItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of border size values available for this component.
+ *
+ * - `base`: Standard border width.
+ * - `large`: Thick border for strong emphasis.
+ * - `large-100`: Extra thick border for maximum prominence.
+ * - `large-200`: The thickest available border.
+ * - `none`: No border.
+ * @publicDocs
+ */
 export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base' | 'large' | 'large-100' | 'large-200'>;
+/**
+ * The subset of border color values available for this component.
+ *
+ * - `base`: The standard border color for most contexts.
+ * @publicDocs
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
-export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ * @publicDocs
  */
+export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -27,27 +97,98 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-grid";
+/** @publicDocs */
 export interface GridElementProps extends Pick<GridProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'alignContent' | 'alignItems' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'columnGap' | 'display' | 'gap' | 'gridTemplateColumns' | 'gridTemplateRows' | 'id' | 'inlineSize' | 'justifyContent' | 'justifyItems' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart' | 'placeContent' | 'placeItems' | 'rowGap'> {
+    /**
+     * Controls how the grid's rows are distributed along the block (column) axis when there is extra space. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     alignContent?: MaybeResponsive<ReducedAlignContentKeyword | ''>;
+    /**
+     * Aligns grid items along the block (column) axis. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     alignItems?: MaybeResponsive<ReducedAlignItemsKeyword | ''>;
+    /**
+     * The background color of the grid.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<GridProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The color of the border using the design system's color scale. Overrides the color value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderColor?: ReducedColorKeyword | '';
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * The roundedness of the grid's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
+    /**
+     * Controls how the grid's columns are distributed along the inline (row) axis when there is extra space. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     justifyContent?: MaybeResponsive<ReducedJustifyContentKeyword | ''>;
+    /**
+     * Aligns grid items along the inline (row) axis. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     justifyItems?: MaybeResponsive<ReducedJustifyItemsKeyword | ''>;
+    /**
+     * A shorthand for `justifyContent` and `alignContent` that sets both distribution axes at once.
+     *
+     * @default 'normal normal'
+     */
     placeContent?: MaybeResponsive<`${ReducedAlignContentKeyword} ${ReducedJustifyContentKeyword}` | ReducedAlignContentKeyword>;
+    /**
+     * A shorthand for `justifyItems` and `alignItems` that sets both alignment axes at once.
+     *
+     * @default 'normal normal'
+     */
     placeItems?: MaybeResponsive<`${ReducedAlignItemsKeyword} ${ReducedJustifyItemsKeyword}` | ReducedAlignItemsKeyword>;
 }
+/** @publicDocs */
 export interface GridElement extends GridElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface GridProps extends GridElementProps {
 }
 declare global {

package/build/ts/surfaces/checkout/components/GridItem.d.ts

@@ -10,12 +10,30 @@
 /// <reference lib="DOM" />
 import type {GridItemProps$1,BorderSizeKeyword, BorderStyleKeyword,ColorKeyword,MaybeAllValuesShorthandProperty} from './components-shared.d.ts';
 
+/**
+ * The subset of border size values available for this component.
+ *
+ * - `base`: Standard border width.
+ * - `large`: Thick border for strong emphasis.
+ * - `large-100`: Extra thick border for maximum prominence.
+ * - `large-200`: The thickest available border.
+ * - `none`: No border.
+ * @publicDocs
+ */
 export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base' | 'large' | 'large-100' | 'large-200'>;
+/**
+ * The subset of border color values available for this component.
+ *
+ * - `base`: The standard border color for most contexts.
+ * @publicDocs
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
-export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ * @publicDocs
  */
+export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -23,21 +41,62 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-grid-item";
+/** @publicDocs */
 export interface GridItemElementProps extends Pick<GridItemProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'gridColumn' | 'gridRow' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the grid item.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<GridItemProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The color of the border using the design system's color scale. Overrides the color value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderColor?: ReducedColorKeyword | '';
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * The roundedness of the grid item's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridItemProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
 }
+/** @publicDocs */
 export interface GridItemElement extends GridItemElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface GridItemProps extends GridItemElementProps {
 }
 declare global {

package/build/ts/surfaces/checkout/components/Heading.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {HeadingProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,16 +18,20 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-heading";
+/** @publicDocs */
 export interface HeadingElementProps extends Pick<HeadingProps$1, 'accessibilityRole' | 'id'> {
 }
+/** @publicDocs */
 export interface HeadingElement extends HeadingElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface HeadingProps extends HeadingElementProps {
 }
 declare global {

package/build/ts/surfaces/checkout/components/Icon.d.ts

@@ -10,30 +10,73 @@
 /// <reference lib="DOM" />
 import type {IconProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. Used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * 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 named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
- * Used as the single source of truth for checkout icon types.
- *
- * @see https://github.com/Shopify/ui-api-design/blob/main/packages/ui-api-design/src/components/Icon/Icon.ts#L10
+ * The complete list of [icon names](https://github.com/Shopify/ui-api-design/blob/main/packages/ui-api-design/src/components/Icon/Icon.ts#L10) available in checkout and customer account surfaces. These icons are drawn from Shopify's design system and cover common UI patterns like navigation, status indicators, actions, and commerce concepts.
  */
 declare const CHECKOUT_AVAILABLE_ICONS: readonly ["alert-circle", "alert-triangle-filled", "alert-triangle", "arrow-down", "arrow-left", "arrow-right", "arrow-up-right", "arrow-up", "bag", "bullet", "calendar", "camera", "caret-down", "cart", "cash-dollar", "categories", "check-circle", "check-circle-filled", "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle", "clipboard", "clock", "credit-card", "delete", "delivered", "delivery", "disabled", "discount", "edit", "email", "empty", "external", "filter", "geolocation", "gift-card", "globe", "grid", "image", "info-filled", "info", "list-bulleted", "location", "lock", "map", "menu-horizontal", "menu-vertical", "menu", "minus", "mobile", "note", "order", "organization", "plus", "profile", "question-circle-filled", "question-circle", "reorder", "reset", "return", "savings", "search", "settings", "star-filled", "star-half", "star", "store", "truck", "upload", "x-circle-filled", "x-circle", "x"];
+/**
+ * The subset of icon types available in checkout and customer account surfaces. This is a narrowed set from the full Shopify icon library, containing only the icons supported in these contexts.
+ * @publicDocs
+ */
 export type ReducedIconTypes = (typeof CHECKOUT_AVAILABLE_ICONS)[number];
 
 declare const tagName = "s-icon";
+/** @publicDocs */
 export interface IconElementProps extends Pick<IconProps$1, 'id' | 'size' | 'tone' | 'type'> {
+    /**
+     * The semantic meaning and color treatment of the icon.
+     *
+     * - `'info'`: Informational content or helpful tips.
+     * - `'auto'`: Automatically determined based on context.
+     * - `'neutral'`: General information without specific intent.
+     * - `'success'`: Positive outcomes or successful states.
+     * - `'warning'`: Important warnings about potential issues.
+     * - `'critical'`: Urgent problems or destructive actions.
+     * - `'custom'`: Inherits a custom color from its parent element's CSS.
+     *
+     * @default 'auto'
+     */
     tone?: Extract<IconProps$1['tone'], 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'custom'>;
+    /**
+     * The size of the icon.
+     *
+     * - `'base'`: Default size that works well for most use cases.
+     * - `'small'`: Small icon for inline use within text or compact UI elements.
+     * - `'small-200'`: Extra small icon for the most compact contexts.
+     * - `'small-100'`: Small icon suitable for tight or dense layouts.
+     * - `'large'`: Large icon for emphasis or prominent display.
+     * - `'large-100'`: Extra large icon for maximum visual impact.
+     *
+     * @default 'base'
+     */
     size?: Extract<IconProps$1['size'], 'small-200' | 'small-100' | 'small' | 'base' | 'large' | 'large-100'>;
+    /**
+     * The type of icon that will be displayed. You can specify an icon name from the available icon set, or use an empty string to show no icon.
+     */
     type?: '' | ReducedIconTypes;
 }
+/**
+ * The HTML element interface for the `s-icon` custom element.
+ * @publicDocs
+ */
 export interface IconElement extends IconElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface IconProps extends IconElementProps {
 }
 declare global {

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

@@ -10,26 +10,68 @@
 /// <reference lib="DOM" />
 import type {ImageProps$1,BorderSizeKeyword, BorderStyleKeyword,ColorKeyword,MaybeAllValuesShorthandProperty} from './components-shared.d.ts';
 
+/**
+ * The subset of border size values available for the image component. These control the thickness of any border applied around the image.
+ *
+ * - `base`: Standard border width.
+ * - `large`: Thick border for strong emphasis.
+ * - `large-100`: Extra thick border for maximum prominence.
+ * - `large-200`: The thickest available border.
+ * - `none`: No border.
+ * @publicDocs
+ */
 export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base' | 'large' | 'large-100' | 'large-200'>;
+/**
+ * The subset of border color values available for the image component.
+ *
+ * - `base`: The standard border color for most contexts.
+ * @publicDocs
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
-export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * A shorthand string for specifying border properties on the image component. Supports size alone, size with color, or size with color and style — following the pattern `'size'`, `'size color'`, or `'size color style'`.
+ * @publicDocs
  */
+export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. Used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * 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 named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 
 declare const tagName = "s-image";
+/** @publicDocs */
 export interface ImageElementProps extends Pick<ImageProps$1, 'accessibilityRole' | 'alt' | 'aspectRatio' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'id' | 'inlineSize' | 'loading' | 'objectFit' | 'sizes' | 'src' | 'srcSet'> {
+    /**
+     * A shorthand for setting the border around the image. Accepts a size keyword alone (for example, `'base'`), a size and color (for example, `'base base'`), or a size, color, and style (for example, `'base base solid'`). Use `'none'` to remove the border.
+     */
     border?: BorderShorthand;
+    /**
+     * 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) to control individual sides. When set, this overrides the width value specified in the `border` shorthand.
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) to control individual corners.
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<ImageProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
 }
+/**
+ * The HTML element interface for the `s-image` custom element.
+ * @publicDocs
+ */
 export interface ImageElement extends ImageElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface ImageProps extends ImageElementProps {
 }
 declare global {

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

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {LinkProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,36 +18,49 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
+/**
+ * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ * @publicDocs
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-link";
+/** @publicDocs */
 export interface LinkElementProps extends Pick<LinkProps$1, 'accessibilityLabel' | 'command' | 'commandFor' | 'href' | 'id' | 'interestFor' | 'lang' | 'target' | 'tone'> {
     target?: Extract<LinkProps$1['target'], 'auto' | '_blank'>;
     tone?: Extract<LinkProps$1['tone'], 'auto' | 'neutral'>;
 }
+/** @publicDocs */
 export interface LinkEvents extends Pick<LinkProps$1, 'onClick'> {
 }
+/** @publicDocs */
 export interface LinkElementEvents {
     /**
-     * Callback when the link is activated.
-     * This will be called before navigating to the location specified by `href`.
+     * A callback fired when the link is clicked, before navigating to the location specified by `href`.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
+     * Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
      */
     click?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface LinkElement extends LinkElementProps, Omit<HTMLElement, 'id' | 'lang' | 'onclick'> {
     onclick: LinkEvents['onClick'];
 }
+/** @publicDocs */
 export interface LinkProps extends LinkElementProps, LinkEvents {
 }
 declare global {

package/build/ts/surfaces/checkout/components/ListItem.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {ListItemProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,16 +18,20 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-list-item";
+/** @publicDocs */
 export interface ListItemElementProps extends Pick<ListItemProps$1, 'id'> {
 }
+/** @publicDocs */
 export interface ListItemElement extends ListItemElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface ListItemProps extends ListItemElementProps {
 }
 declare global {