@shopify/ui-extensions 2026.4.0-rc.3 → 2026.4.1

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

@@ -11,93 +11,110 @@
 import type {PopoverProps$1,SizeUnitsOrAuto, SizeUnitsOrNone, SizeUnits} 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;
 }
+/**
+ * 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-popover";
+/** @publicDocs */
 export interface PopoverElementProps extends Pick<PopoverProps$1, 'id'> {
     /**
-     * Adjust the block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+     * The block size of the popover (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
      *
      * @default 'auto'
      */
     blockSize?: SizeUnitsOrAuto;
     /**
-     * Adjust the inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+     * The inline size of the popover (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
      *
      * @default 'auto'
      */
     inlineSize?: SizeUnitsOrAuto;
     /**
-     * Adjust the maximum block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+     * The maximum block size of the popover. Constrains the popover's height to prevent it from exceeding this value. Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
      *
      * @default 'none'
      */
     maxBlockSize?: SizeUnitsOrNone;
     /**
-     * Adjust the maximum inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+     * The maximum inline size of the popover. Constrains the popover's width to prevent it from exceeding this value. Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
      *
      * @default 'none'
      */
     maxInlineSize?: SizeUnitsOrNone;
     /**
-     * Adjust the minimum block size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+     * The minimum block size of the popover. Ensures the popover maintains at least this height. Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
      *
      * @default '0'
      */
     minBlockSize?: SizeUnits;
     /**
-     * Adjust the minimum inline size.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+     * The minimum inline size of the popover. Ensures the popover maintains at least this width. Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
      *
      * @default '0'
      */
     minInlineSize?: SizeUnits;
 }
+/**
+ * The event callbacks for monitoring popover visibility changes.
+ */
 export interface PopoverEvents extends Pick<PopoverProps$1, 'onHide' | 'onShow'> {
 }
+/** @publicDocs */
 export interface PopoverElementEvents {
     /**
-     * Callback fired after the overlay is hidden.
+     * A callback fired immediately after the popover is hidden.
      */
     hide?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback fired after the overlay is shown.
+     * A callback fired immediately after the popover is shown.
      */
     show?: CallbackEventListener<typeof tagName>;
 }
+/**
+ * The HTML element interface for the `s-popover` custom element.
+ */
 export interface PopoverElement extends Omit<PopoverProps, 'onHide' | 'onShow'>, Omit<HTMLElement, 'id'> {
     onhide: PopoverProps['onHide'];
     onshow: PopoverProps['onShow'];
 }
+/**
+ * The properties for the popover component when it's used in JSX.
+ */
 export interface PopoverProps extends PopoverElementProps, PopoverEvents {
 }
 declare global {

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

@@ -24,35 +24,43 @@ 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-press-button";
+/** @publicDocs */
 export interface PressButtonElementProps extends Pick<PressButtonProps$1, 'accessibilityLabel' | 'id' | 'inlineSize' | 'lang' | 'disabled' | 'loading' | 'pressed' | 'defaultPressed'> {
 }
 export interface PressButtonEvents extends Pick<PressButtonProps$1, 'onClick' | 'onBlur' | 'onFocus'> {
 }
+/** @publicDocs */
 export interface PressButtonElementEvents {
     /**
-     * Callback when the button is activated.
+     * A callback fired when the button is clicked.
      *
-     * @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>;
     /**
-     * Callback when the button has lost focus.
+     * A callback fired when the button loses focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the button has received focus.
+     * A callback fired when the button receives focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
      */
     focus?: CallbackEventListener<typeof tagName>;
 }

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

@@ -11,20 +11,45 @@
 import type {ProductThumbnailProps$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>;
 }
 
 declare const tagName = "s-product-thumbnail";
+/** @publicDocs */
 export interface ProductThumbnailElementProps extends Pick<ProductThumbnailProps$1, 'alt' | 'size' | 'sizes' | 'src' | 'srcSet' | 'totalItems'> {
+    /**
+     * The size of the product thumbnail image.
+     *
+     * - `'base'`: Default size that works well in most contexts.
+     * - `'small'`: Small thumbnail, good for secondary contexts or tight layouts.
+     * - `'small-100'`: Extra small thumbnail for compact displays or dense lists.
+     *
+     * @default 'base'
+     */
     size?: Extract<ProductThumbnailProps$1['size'], 'small-100' | 'small' | 'base'>;
 }
+/**
+ * The HTML element interface for the `s-product-thumbnail` custom element.
+ */
 export interface ProductThumbnailElement extends ProductThumbnailElementProps, Omit<HTMLElement, 'id'> {
 }
+/**
+ * The properties for the product thumbnail component when it's used in JSX.
+ */
 export interface ProductThumbnailProps extends ProductThumbnailElementProps {
 }
 declare global {

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

@@ -20,8 +20,35 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 
 declare const tagName = "s-progress";
+/** @publicDocs */
 export interface ProgressElementProps extends Pick<ProgressProps$1, 'accessibilityLabel' | 'id' | 'max' | 'tone' | 'value'> {
+    /**
+     * A label announced by assistive technologies that describes what is progressing. Use this to provide context about the ongoing task, such as "Loading order details" or "Uploading file".
+     */
+    accessibilityLabel?: ProgressProps$1['accessibilityLabel'];
+    /**
+     * The total amount of work the task requires. Must be a value greater than `0` and a valid floating point number.
+     *
+     * Learn more about the [max attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#max).
+     *
+     * @default 1
+     */
+    max?: ProgressProps$1['max'];
+    /**
+     * The semantic meaning and color treatment of the progress indicator.
+     *
+     * - `auto`: Automatically determined based on context.
+     * - `critical`: Indicates an urgent or error state requiring immediate attention.
+     *
+     * @default 'auto'
+     */
     tone?: Extract<ProgressProps$1['tone'], 'auto' | 'critical'>;
+    /**
+     * How much of the task has been completed. Must be a valid floating point number between `0` and `max`, or between `0` and `1` if `max` is omitted. When no value is set, the progress bar is indeterminate, indicating an ongoing activity with no estimated completion time.
+     *
+     * Learn more about the [value attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#value).
+     */
+    value?: ProgressProps$1['value'];
 }
 export interface ProgressElement extends ProgressElementProps, Omit<HTMLElement, 'id'> {
 }

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

@@ -11,35 +11,60 @@
 import type {QRCodeProps$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>;
 }
+/**
+ * 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-qr-code";
+/** @publicDocs */
 export interface QRCodeElementProps extends QRCodeProps$1 {
 }
+/**
+ * The event handlers for the QR code component.
+ */
 export interface QRCodeEvents extends Pick<QRCodeProps$1, 'onError'> {
 }
+/** @publicDocs */
 export interface QRCodeElementEvents {
     /**
-     * Invoked when the conversion of `content` to a QR code fails.
-     * If an error occurs, the QR code and its child elements will not be displayed.
+     * A callback that's fired when the conversion of `content` to a QR code fails.
      */
     error?: CallbackEventListener<typeof tagName>;
 }
+/**
+ * The HTML element interface for the `s-qr-code` custom element.
+ */
 export interface QRCodelement extends QRCodeElementProps, Omit<HTMLElement, 'id' | 'onerror'> {
     onerror: QRCodeEvents['onError'];
 }
+/**
+ * The properties for the QR code component when it's used in JSX.
+ */
 export interface QRCodeProps extends QRCodeElementProps, QRCodeEvents {
 }
 declare global {

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

@@ -26,6 +26,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-query-container";
+/** @publicDocs */
 export interface QueryContainerElementProps extends Pick<QueryContainerProps$1, 'containerName' | 'id'> {
 }
 export interface QueryContainerElement extends QueryContainerElementProps, Omit<HTMLElement, 'id'> {

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

@@ -10,8 +10,25 @@
 /// <reference lib="DOM" />
 import type {ScrollBoxProps$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,49 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-scroll-box";
+/** @publicDocs */
 export interface ScrollBoxElementProps extends Pick<ScrollBoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the scroll box.
+     *
+     * - `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<ScrollBoxProps$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 roundedness of the scroll box'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<ScrollBoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
+    /**
+     * 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> | '';
 }
 export interface ScrollBoxElement extends ScrollBoxElementProps, Omit<HTMLElement, 'id'> {

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

@@ -20,16 +20,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-section";
+/** @publicDocs */
 export interface SectionElementProps extends Pick<SectionProps$1, 'accessibilityLabel' | 'heading' | 'id'> {
 }
+/** @publicDocs */
 export interface SectionElement extends SectionElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface SectionProps extends SectionElementProps {
 }
 declare global {

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

@@ -24,35 +24,43 @@ 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-select";
+/** @publicDocs */
 export interface SelectElementProps extends Pick<SelectProps$1, 'autocomplete' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'placeholder' | 'required' | 'value'> {
 }
 export interface SelectEvents extends Pick<SelectProps$1, 'onBlur' | 'onChange' | 'onFocus'> {
 }
+/** @publicDocs */
 export interface SelectElementEvents {
     /**
-     * Callback when the element loses focus.
+     * A callback fired when the select loses focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+     * A callback fired when the select value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the element receives focus.
+     * A callback fired when the select receives focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
      */
     focus?: CallbackEventListener<typeof tagName>;
 }

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

@@ -11,69 +11,93 @@
 import type {SheetProps$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;
 }
+/**
+ * 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-sheet";
+/** @publicDocs */
 export interface SheetElementProps extends Pick<SheetProps$1, 'defaultOpen' | 'heading' | 'id'> {
     /**
-     * A label that describes the purpose of the modal. When set,
-     * it will be announced to users using assistive technologies and will
-     * provide them with more context.
-     *
-     * This overrides the `heading` prop for screen readers.
+     * A label that describes the purpose of the sheet, announced by assistive technologies. When set, screen readers will use this label instead of the `heading` to describe the sheet.
      */
     accessibilityLabel?: string;
 }
+/**
+ * The event callbacks for monitoring sheet visibility changes.
+ */
 export interface SheetEvents extends Pick<SheetProps$1, 'onAfterHide' | 'onAfterShow' | 'onHide' | 'onShow'> {
 }
+/** @publicDocs */
 export interface SheetElementEvents {
     /**
-     * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished.
+     * A callback fired when the sheet is hidden, after any hide animations have completed.
      */
     afterhide?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback fired when the overlay is shown **after** any animations to show the overlay have finished.
+     * A callback fired when the sheet is shown, after any show animations have completed.
      */
     aftershow?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback fired after the overlay is hidden.
+     * A callback fired immediately after the sheet is hidden.
      */
     hide?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback fired after the overlay is shown.
+     * A callback fired immediately after the sheet is shown.
      */
     show?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface SheetElementSlots {
     /**
-     * The primary action to perform, provided as a button type element.
+     * The main action button displayed in the sheet footer, representing the primary action users should take. Only accepts a single button component.
      */
     'primary-action'?: HTMLElement;
     /**
-     * The secondary actions to perform, provided as a button type element.
+     * Additional action buttons displayed in the sheet footer, providing alternative or supporting actions.
      */
     'secondary-actions'?: HTMLElement;
 }
+/** @publicDocs */
 export interface SheetElementMethods extends Pick<SheetProps$1, 'hideOverlay'> {
 }
+/**
+ * The HTML element interface for the `s-sheet` custom element.
+ */
 export interface SheetElement extends SheetElementProps, SheetElementMethods, Omit<HTMLElement, 'id'> {
     afterhide: SheetEvents['onAfterHide'];
     aftershow: SheetEvents['onAfterShow'];
@@ -82,6 +106,9 @@ export interface SheetElement extends SheetElementProps, SheetElementMethods, Om
     onafterhide: SheetEvents['onAfterHide'];
     onaftershow: SheetEvents['onAfterShow'];
 }
+/**
+ * The properties for the sheet component when it's used in JSX.
+ */
 export interface SheetProps extends SheetElementProps, SheetEvents {
 }
 declare global {

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

@@ -20,6 +20,7 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 
 declare const tagName = "s-skeleton-paragraph";
+/** @publicDocs */
 export interface SkeletonParagraphElementProps extends SkeletonParagraphProps$1 {
 }
 export interface SkeletonParagraphElement extends SkeletonParagraphElementProps, Omit<HTMLElement, 'id'> {

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

@@ -20,7 +20,23 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 
 declare const tagName = "s-spinner";
+/** @publicDocs */
 export interface SpinnerElementProps extends SpinnerProps$1 {
+    /**
+     * A label that describes the purpose of the spinner for assistive technologies like screen readers. Provide an `accessibilityLabel` when there is no visible text that conveys a loading state.
+     */
+    accessibilityLabel?: SpinnerProps$1['accessibilityLabel'];
+    /**
+     * The size of the spinner icon.
+     *
+     * - `base`: The default size, suitable for most use cases.
+     * - `small`: A compact size for secondary loading states.
+     * - `small-100`: The smallest size for tight spaces or inline indicators.
+     * - `large`: A larger size for more prominent loading states.
+     * - `large-100`: The largest size for full-page or section-level loading indicators.
+     *
+     * @default 'base'
+     */
     size?: Extract<SpinnerProps$1['size'], 'small-100' | 'small' | 'base' | 'large' | 'large-100'>;
 }
 export interface SpinnerElement extends SpinnerElementProps, Omit<HTMLElement, 'id'> {