@shopify/ui-extensions 2026.4.0-rc.2 → 2026.4.0

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

@@ -10,12 +10,81 @@
 /// <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.
+ */
 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.
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * 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.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -33,17 +102,87 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 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>;
 }
 export interface GridElement extends GridElementProps, Omit<HTMLElement, 'id'> {

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

@@ -10,8 +10,25 @@
 /// <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.
+ */
 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.
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * 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.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -29,11 +46,51 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 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'>>;
 }
 export interface GridItemElement extends GridItemElementProps, Omit<HTMLElement, 'id'> {

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

@@ -26,6 +26,10 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-heading";
+/**
+ * The element props interface for the Heading component.
+ * @publicDocs
+ */
 export interface HeadingElementProps extends Pick<HeadingProps$1, 'accessibilityRole' | 'id'> {
 }
 export interface HeadingElement extends HeadingElementProps, Omit<HTMLElement, 'id'> {

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

@@ -11,29 +11,74 @@
 import type {IconProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 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.
+ */
 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.
+ */
 export interface IconElement extends IconElementProps, Omit<HTMLElement, 'id'> {
 }
+/**
+ * The properties for the icon component when it's used in JSX.
+ */
 export interface IconProps extends IconElementProps {
 }
 declare global {

package/src/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.
+ */
 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.
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * 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'`.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 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.
+ */
 export interface ImageElement extends ImageElementProps, Omit<HTMLElement, 'id'> {
 }
+/**
+ * The properties for the image component when it's used in JSX.
+ */
 export interface ImageProps extends ImageElementProps {
 }
 declare global {

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

@@ -24,26 +24,39 @@ export interface BaseElementProps<TClass = HTMLElement> {
 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.
+ */
 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.
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-link";
+/**
+ * Configure the following properties on the link component.
+ * @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'>;
 }
 export interface LinkEvents extends Pick<LinkProps$1, 'onClick'> {
 }
+/**
+ * The link component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ * @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>;
 }

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

@@ -26,6 +26,10 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-list-item";
+/**
+ * The element props interface for the ListItem component.
+ * @publicDocs
+ */
 export interface ListItemElementProps extends Pick<ListItemProps$1, 'id'> {
 }
 export interface ListItemElement extends ListItemElementProps, Omit<HTMLElement, 'id'> {

package/src/surfaces/checkout/components/Map.d.ts

@@ -11,71 +11,133 @@
 import type {MapProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 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 when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
+    /**
+     * The child elements to render within this component.
+     */
     children?: preact.ComponentChildren;
 }
+/**
+ * A callback event typed to a specific HTML element, with a strongly typed `currentTarget`.
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * An event listener typed to a specific HTML element, with a strongly typed `currentTarget`.
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-map";
+/** @publicDocs */
 export interface MapElementProps extends Pick<MapProps$1, 'accessibilityLabel' | 'apiKey' | 'blockSize' | 'id' | 'inlineSize' | 'latitude' | 'longitude' | 'maxBlockSize' | 'maxInlineSize' | 'maxZoom' | 'minBlockSize' | 'minInlineSize' | 'minZoom' | 'zoom'> {
 }
+/**
+ * The event handlers for the map component.
+ */
 export interface MapEvents extends Pick<MapProps$1, 'onBoundsChange' | 'onClick' | 'onDblClick' | 'onViewChange'> {
 }
+/**
+ * A geographic coordinate pair representing a location on the map, defined by latitude and longitude values.
+ */
 export interface MapLocation {
+    /**
+     * The latitude of the location in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
+     */
     latitude?: number;
+    /**
+     * The longitude of the location in degrees. Valid values range from -180 (west) to 180 (east).
+     */
     longitude?: number;
 }
+/**
+ * The event data provided when a map interaction occurs at a specific geographic location, such as a click or double-click.
+ */
 export interface MapLocationEvent {
+    /**
+     * The geographic location on the map where the interaction occurred, as a latitude/longitude coordinate pair.
+     */
     location?: MapLocation;
 }
+/**
+ * The event data provided when the visible map boundaries change, such as after a pan or zoom completes. Contains the new geographic bounds of the visible area.
+ */
 export interface MapBoundsEvent {
+    /**
+     * The geographic boundaries of the currently visible map area, defined by its north-east and south-west corners.
+     */
     bounds?: {
+        /**
+         * The north-east corner of the visible map area, representing the top-right of the visible region.
+         */
         northEast?: MapLocation;
+        /**
+         * The south-west corner of the visible map area, representing the bottom-left of the visible region.
+         */
         southWest?: MapLocation;
     };
 }
+/**
+ * The event data provided when the map view changes, such as after the user pans or zooms. Contains the new center location and zoom level.
+ */
 export interface MapViewChangeEvent extends MapLocationEvent {
+    /**
+     * The current zoom level of the map after the view change, as a number from 0 (world view) to 18 (street level).
+     */
     zoom?: number;
 }
+/** @publicDocs */
 export interface MapElementEvents {
     /**
-     * Callback when the viewport bounds have changed or the map is resized.
+     * A callback fired when the visible map boundaries change, such as after a pan or zoom completes.
      */
     boundschange?: CallbackEventListener<typeof tagName, MapBoundsEvent>;
     /**
-     * Callback when the user clicks on the map.
+     * A callback fired when the user clicks on the map. Provides the geographic location of the click.
      */
     click?: CallbackEventListener<typeof tagName, MapLocationEvent>;
     /**
-     * Callback when the user double-clicks on the map.
+     * A callback fired when the user double-clicks on the map. Provides the geographic location of the double-click.
      */
     dblclick?: CallbackEventListener<typeof tagName, MapLocationEvent>;
     /**
-     * Callback when the map view changes.
+     * A callback fired when the map view changes, such as when the user pans or zooms. Provides the new center location and zoom level.
      */
     viewchange?: CallbackEventListener<typeof tagName, MapViewChangeEvent>;
 }
+/**
+ * The HTML element interface for the `s-map` custom element.
+ */
 export interface MapElement extends MapElementProps, Omit<HTMLElement, 'id' | 'onclick' | 'ondblclick'> {
     onboundschange: MapEvents['onBoundsChange'];
     onclick: MapEvents['onClick'];
     ondblclick: MapEvents['onDblClick'];
     onviewchange: MapEvents['onViewChange'];
 }
+/**
+ * The properties for the map component when it's used in JSX.
+ */
 export interface MapProps extends MapElementProps, MapEvents {
 }
 declare global {