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

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

@@ -26,6 +26,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-abbreviation";
+/** @publicDocs */
 export interface AbbreviationElementProps extends Pick<AbbreviationProps$1, 'title' | 'id'> {
 }
 export interface AbbreviationElement extends AbbreviationElementProps, Omit<HTMLElement, 'id' | 'title'> {

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

@@ -24,50 +24,68 @@ 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;
+/**
+ * The visibility state of a toggleable element.
+ *
+ * - `open`: The element is visible and showing its content.
+ * - `closed`: The element is hidden and its content is not visible.
+ */
 export type ToggleState = 'open' | 'closed';
+/**
+ * The event data provided to toggle-related callbacks. Contains the previous and next visibility states of the element.
+ */
 export interface ToggleArgumentsEvent {
+    /**
+     * The visibility state of the element before the toggle occurred.
+     */
     oldState?: ToggleState;
+    /**
+     * The visibility state of the element after the toggle occurred.
+     */
     newState?: ToggleState;
 }
 
 declare const tagName = "s-announcement";
 export interface AnnouncementEvents extends Pick<AnnouncementProps$1, 'onAfterToggle' | 'onDismiss' | 'onToggle'> {
 }
+/** @publicDocs */
 export interface AnnouncementElementEvents {
     /**
-     * Callback fired when the element state changes **after** any animations have finished.
+     * A callback that fires when the element state changes, after any toggle animations have finished.
      *
      * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the
      *   `newState` property will be set to `open`.
      * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the
      *   `newState` will be `closed`.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+     * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
      */
     aftertoggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
     /**
-     * Callback fired when the announcement is dismissed by the user
-     * (either via the built-in dismiss button or programmatically).
+     * A callback that fires when the announcement is dismissed by the user clicking the close button or by calling the `dismiss()` method programmatically.
      */
     dismiss?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback straight after the element state changes.
+     * A callback that fires immediately when the element state changes, before any animations.
      *
      * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the
      *   `newState` property will be set to `open`.
      * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the
      *   `newState` will be `closed`.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState
+     * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
      */
     toggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
 }
@@ -79,9 +97,16 @@ export interface AnnouncementElement extends AnnouncementMethods, Omit<HTMLEleme
 export interface AnnouncementProps extends AnnouncementEvents {
 }
 export interface AnnouncementMethods {
+    /**
+     * Programmatically dismisses the announcement. This triggers the `dismiss` event callback.
+     */
     dismiss: () => void;
 }
+/** @publicDocs */
 export interface AnnouncementElementMethods {
+    /**
+     * Programmatically dismisses the announcement. This triggers the `dismiss` event callback.
+     */
     dismiss: AnnouncementMethods['dismiss'];
 }
 declare global {

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

@@ -25,19 +25,60 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
     children?: preact.ComponentChildren;
 }
 /**
- * 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 available icon types for checkout components. This is the single source of truth for checkout icon names.
  */
 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-badge";
+/** @publicDocs */
 export interface BadgeElementProps extends Pick<BadgeProps$1, 'color' | 'icon' | 'iconPosition' | 'id' | 'size' | 'tone'> {
+    /**
+     * The size of the badge.
+     *
+     * - `base`: The default size, suitable for most use cases.
+     * - `small`: A smaller badge for compact layouts.
+     * - `small-100`: The smallest badge for tight spaces or dense lists.
+     *
+     * @default 'base'
+     */
     size?: Extract<BadgeProps$1['size'], 'small' | 'small-100' | 'base'>;
+    /**
+     * The semantic meaning and color treatment of the badge.
+     *
+     * - `auto`: Automatically determined based on context.
+     * - `neutral`: General information without specific intent.
+     * - `critical`: Urgent problems or destructive actions.
+     *
+     * @default 'auto'
+     */
     tone?: Extract<BadgeProps$1['tone'], 'auto' | 'neutral' | 'critical'>;
+    /**
+     * Controls the visual weight and emphasis of the badge.
+     *
+     * - `base`: Standard weight with moderate emphasis, suitable for most use cases.
+     * - `subdued`: Reduced visual weight for less prominent or secondary badges.
+     *
+     * @default 'base'
+     */
     color?: Extract<BadgeProps$1['color'], 'base' | 'subdued'>;
+    /**
+     * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. Set to an empty string to display no icon.
+     *
+     * @default ''
+     */
     icon?: '' | ReducedIconTypes;
+    /**
+     * The position of the icon relative to the badge text.
+     *
+     * - `start`: Places the icon before the text.
+     * - `end`: Places the icon after the text.
+     */
+    iconPosition?: BadgeProps$1['iconPosition'];
 }
 export interface BadgeElement extends BadgeElementProps, Omit<HTMLElement, 'id'> {
 }

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

@@ -24,36 +24,87 @@ 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-banner";
+/** @publicDocs */
 export interface BannerElementProps extends Pick<BannerProps$1, 'collapsible' | 'dismissible' | 'heading' | 'hidden' | 'id' | 'tone'> {
+    /**
+     * Whether the banner content can be collapsed and expanded by the user. A collapsible banner conceals child elements initially, allowing the user to expand the banner to reveal them.
+     *
+     * @default false
+     */
+    collapsible?: BannerProps$1['collapsible'];
+    /**
+     * Whether the banner displays a close button that allows users to dismiss it.
+     *
+     * When the close button is pressed, the `dismiss` event will fire,
+     * then `hidden` will be set to `true`,
+     * any animation will complete,
+     * and the `afterhide` event will fire.
+     *
+     * @default false
+     */
+    dismissible?: BannerProps$1['dismissible'];
+    /**
+     * The heading text displayed at the top of the banner to summarize the message or alert.
+     *
+     * @default ''
+     */
+    heading?: BannerProps$1['heading'];
+    /**
+     * Controls whether the banner is visible or hidden.
+     *
+     * When using a controlled component pattern and the banner is `dismissible`,
+     * update this property to `true` when the `dismiss` event fires.
+     *
+     * You can hide the banner programmatically by setting this to `true` even if it's not `dismissible`.
+     *
+     * @default false
+     */
+    hidden?: BannerProps$1['hidden'];
+    /**
+     * The semantic meaning and color treatment of the component. The banner is a live region and the type of status is dictated by the tone selected.
+     *
+     * - `info`: Informational content or helpful tips.
+     * - `auto`: Automatically determined based on context.
+     * - `success`: Positive outcomes or successful states.
+     * - `warning`: Important warnings about potential issues.
+     * - `critical`: Urgent problems or destructive actions.
+     *
+     * The `critical` tone creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately. The `info`, `success`, and `warning` tones create an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.
+     *
+     * @default 'auto'
+     */
     tone?: Extract<BannerProps$1['tone'], 'auto' | 'info' | 'success' | 'warning' | 'critical'>;
 }
 export interface BannerEvents extends Pick<BannerProps$1, 'onAfterHide' | 'onDismiss'> {
 }
+/** @publicDocs */
 export interface BannerElementEvents {
     /**
-     * Event handler when the banner has fully hidden.
-     *
-     * The `hidden` property will be `true` when this event fires.
+     * A callback that fires when the banner has fully hidden, including after any hide animations have completed.
      *
-     * @implementation If implementations animate the hiding of the banner,
-     * this event must fire after the banner has fully hidden.
-     * We can add an `onHide` event in future if we want to provide a hook for the start of the animation.
+     * The `hidden` property is `true` when this event fires.
      */
     afterhide?: CallbackEventListener<typeof tagName>;
     /**
-     * Event handler when the banner is dismissed by the user.
+     * A callback that fires when the banner is dismissed by the user clicking the close button.
      *
-     * This does not fire when setting `hidden` manually.
+     * This doesn't fire when setting `hidden` manually.
      *
-     * The `hidden` property will be `false` when this event fires.
+     * The `hidden` property is `false` when this event fires.
      */
     dismiss?: CallbackEventListener<typeof tagName>;
 }

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

@@ -10,8 +10,25 @@
 /// <reference lib="DOM" />
 import type {BoxProps$1,MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,ColorKeyword} 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,10 +46,43 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-box";
+/** @publicDocs */
 export interface BoxElementProps extends Pick<BoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the 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<BoxProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * 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 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<BoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
 }
 export interface BoxElement extends BoxElementProps, Omit<HTMLElement, 'id'> {

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

@@ -24,14 +24,21 @@ 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-button";
+/** @publicDocs */
 export interface ButtonElementProps extends Pick<ButtonProps$1, 'accessibilityLabel' | 'command' | 'commandFor' | 'disabled' | 'href' | 'id' | 'inlineSize' | 'interestFor' | 'loading' | 'target' | 'tone' | 'type' | 'variant'> {
     target?: Extract<ButtonProps$1['target'], 'auto' | '_blank'>;
     tone?: Extract<ButtonProps$1['tone'], 'auto' | 'neutral' | 'critical'>;
@@ -40,12 +47,12 @@ export interface ButtonElementProps extends Pick<ButtonProps$1, 'accessibilityLa
 }
 export interface ButtonEvents extends Pick<ButtonProps$1, 'onClick'> {
 }
+/** @publicDocs */
 export interface ButtonElementEvents {
     /**
-     * Callback when the button is activated.
-     * This will be called before the action indicated by `type`.
+     * A callback fired when the button is clicked. This will be called before the action indicated by `type`.
      *
-     * @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/Chat.d.ts

@@ -0,0 +1,20 @@
+/** VERSION: 0.0.0 **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {ChatProps$1} from './components-shared.d.ts';
+
+/** @publicDocs */
+export interface ChatProps extends Pick<ChatProps$1, 'accessibilityLabel' | 'blockSize' | 'id' | 'inlineSize' | 'onMessage' | 'onReady'> {
+    blockSize?: Extract<ChatProps$1['blockSize'], `${number}px` | '0'>;
+    inlineSize?: Extract<ChatProps$1['inlineSize'], `${number}px` | '0'>;
+    remoteMethods?: Record<string, (...args: unknown[]) => unknown>;
+}
+
+export type { ChatProps };

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

@@ -18,24 +18,32 @@ export interface BaseElementProps<TClass = HTMLElement> {
     ref?: preact.Ref<TClass>;
     slot?: Lowercase<string>;
 }
+/**
+ * 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-checkbox";
+/** @publicDocs */
 export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'required' | 'value'> {
     command?: Extract<CheckboxProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
 }
 export interface CheckboxEvents extends Pick<CheckboxProps$1, 'onChange'> {
 }
+/** @publicDocs */
 export interface CheckboxElementEvents {
     /**
-     * A callback that is run whenever the control is changed.
+     * A callback fired when the checkbox 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>;
 }

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

@@ -26,13 +26,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-chip";
+/** @publicDocs */
 export interface ChipElementProps extends Pick<ChipProps$1, 'accessibilityLabel' | 'id'> {
 }
+/** @publicDocs */
 export interface ChipElementSlots {
     /**
-     * The graphic to display inside of the chip.
-     *
-     * Only `s-icon` element and its `type` attribute are supported.
+     * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported.
      */
     graphic?: HTMLElement;
 }

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

@@ -26,8 +26,10 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-choice";
+/** @publicDocs */
 export interface ChoiceElementProps extends Pick<ChoiceProps$1, 'accessibilityLabel' | 'defaultSelected' | 'disabled' | 'id' | 'selected' | 'error' | 'value'> {
 }
+/** @publicDocs */
 export interface ChoiceElementSlots {
     /**
      * Additional text to provide context or guidance for the input.

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

@@ -24,23 +24,31 @@ 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-choice-list";
+/** @publicDocs */
 export interface ChoiceListElementProps extends Pick<ChoiceListProps$1, 'disabled' | 'error' | 'id' | 'label' | 'labelAccessibilityVisibility' | 'multiple' | 'name' | 'values' | 'variant'> {
 }
 export interface ChoiceListEvents extends Pick<ChoiceListProps$1, 'onChange'> {
 }
+/** @publicDocs */
 export interface ChoiceListElementEvents {
     /**
-     * A callback that is run whenever the control is changed.
+     * A callback fired when the choice list 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>;
 }

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

@@ -10,8 +10,25 @@
 /// <reference lib="DOM" />
 import type {ClickableProps$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 type for specifying border properties. Accepts a border size, or a combination of size and color, or size, color, and style.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -27,14 +44,21 @@ 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-clickable";
+/** @publicDocs */
 export interface ClickableElementProps extends Pick<ClickableProps$1, 'accessibilityLabel' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'command' | 'commandFor' | 'disabled' | 'display' | 'href' | 'id' | 'inlineSize' | 'interestFor' | 'lang' | 'loading' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart' | 'target' | 'type'> {
     background?: Extract<ClickableProps$1['background'], 'transparent' | 'subdued' | 'base'>;
     border?: BorderShorthand;
@@ -45,24 +69,24 @@ export interface ClickableElementProps extends Pick<ClickableProps$1, 'accessibi
 }
 export interface ClickableEvents extends Pick<ClickableProps$1, 'onBlur' | 'onClick' | 'onFocus'> {
 }
+/** @publicDocs */
 export interface ClickableElementEvents {
     /**
-     * Callback when the element loses focus.
+     * A callback fired when the component 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 is activated.
-     * This will be called before the action indicated by `type`.
+     * A callback fired when the component is clicked. This will be called before the action indicated by `type`.
      *
-     * @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 element receives focus.
+     * A callback fired when the component 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/ClickableChip.d.ts

@@ -24,39 +24,46 @@ 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-clickable-chip";
+/** @publicDocs */
 export interface ClickableChipElementProps extends Pick<ClickableChipProps$1, 'accessibilityLabel' | 'disabled' | 'hidden' | 'href' | 'id' | 'removable'> {
 }
 export interface ClickableChipEvents extends Pick<ClickableChipProps$1, 'onAfterHide' | 'onClick' | 'onRemove'> {
 }
+/** @publicDocs */
 export interface ClickableChipElementEvents {
     /**
-     * Event handler when the chip has fully hidden.
-     *
-     * The `hidden` property will be `true` when this event fires.
+     * A callback fired after the chip is hidden. The `hidden` property will be `true` when this event fires.
      */
     afterhide?: CallbackEventListener<typeof tagName>;
     /**
-     * Event handler when the chip is clicked.
+     * A callback fired when the chip is clicked.
+     *
+     * Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).
      */
     click?: CallbackEventListener<typeof tagName>;
     /**
-     * Event handler when the chip is removed.
+     * A callback fired when the chip is removed.
      */
     remove?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface ClickableChipElementSlots {
     /**
-     * The graphic to display inside of the chip.
-     *
-     * Only `s-icon` element and its `type` attribute are supported.
+     * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported.
      */
     graphic?: HTMLElement;
 }