@shopify/ui-extensions 2025.10.14 → 2025.10.15

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

@@ -10,72 +10,136 @@
 /// <reference lib="DOM" />
 import type {MapProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. Used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+     */
     ref?: preact.Ref<TClass>;
+    /**
+     * Assigns this element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
+ * @publicDocs
  */
 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`.
+ * @publicDocs
+ */
 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`.
+ * @publicDocs
+ */
 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'> {
 }
+/** @publicDocs */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 export interface MapElement extends MapElementProps, Omit<HTMLElement, 'id' | 'onclick' | 'ondblclick'> {
     onboundschange: MapEvents['onBoundsChange'];
     onclick: MapEvents['onClick'];
     ondblclick: MapEvents['onDblClick'];
     onviewchange: MapEvents['onViewChange'];
 }
+/** @publicDocs */
 export interface MapProps extends MapElementProps, MapEvents {
 }
 declare global {

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

@@ -10,52 +10,78 @@
 /// <reference lib="DOM" />
 import type {MapMarkerProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
+/**
+ * A callback event typed to a specific HTML element, with a strongly typed `currentTarget`.
+ * @publicDocs
+ */
 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`.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-map-marker";
+/** @publicDocs */
 export interface MapMarkerElementProps extends Pick<MapMarkerProps$1, 'accessibilityLabel' | 'blockSize' | 'command' | 'commandFor' | 'clusterable' | 'inlineSize' | 'latitude' | 'longitude'> {
+    /**
+     * Sets the action the `commandFor` target should take when this component is activated. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
+     *
+     * - `--auto`: a default action for the target component.
+     * - `--show`: shows the target component.
+     * - `--hide`: hides the target component.
+     * - `--toggle`: toggles the target component.
+     *
+     * @default '--auto'
+     */
     command?: Extract<MapMarkerProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
+    /**
+     * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+     */
+    commandFor?: MapMarkerProps$1['commandFor'];
 }
+/** @publicDocs */
 export interface MapMarkerEvents extends Pick<MapMarkerProps$1, 'onClick'> {
 }
+/** @publicDocs */
 export interface MapMarkerElementEvents {
     /**
-     * Callback when a marker is clicked.
-     *
-     * It does not trigger a click event on the map itself.
+     * A callback fired when the user clicks on the marker. This event does not propagate to the parent map — only the marker receives the click.
      */
     click?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface MapMarkerElementSlots {
     /**
-     * The graphic to use as the marker.
-     *
-     * If unset, it will default to the provider’s default marker.
+     * A custom graphic element to use as the marker. If not provided, the map provider’s default marker pin is displayed.
      */
     graphic?: HTMLElement;
 }
+/**
+ * The HTML element interface for the `s-map-marker` custom element.
+ * @publicDocs
+ */
 export interface MapMarkerElement extends MapMarkerElementProps, Omit<HTMLElement, 'id' | 'onclick'> {
     onclick: MapMarkerEvents['onClick'];
 }
+/** @publicDocs */
 export interface MapMarkerProps extends MapMarkerElementProps, MapMarkerEvents {
 }
 declare global {

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

@@ -10,69 +10,110 @@
 /// <reference lib="DOM" />
 import type {ModalProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. Used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+     */
     ref?: preact.Ref<TClass>;
+    /**
+     * Assigns this element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
+ * @publicDocs
  */
 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.
+ * @publicDocs
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-modal";
+/** @publicDocs */
 export interface ModalElementProps extends Pick<ModalProps$1, 'accessibilityLabel' | 'heading' | 'id' | 'padding' | 'size'> {
+    /**
+     * The size of the modal.
+     *
+     * - `'base'`: The default size, suitable for most use cases.
+     * - `'small'`: A compact modal for simple confirmations or short messages.
+     * - `'small-100'`: The smallest modal size.
+     * - `'large'`: A large modal for complex content or forms.
+     * - `'large-100'`: The largest fixed-size modal, providing maximum room for content.
+     * - `'max'`: Expands the modal to its maximum size as defined by the host application, on both the horizontal and vertical axes.
+     *
+     * @default 'base'
+     */
     size?: Extract<ModalProps$1['size'], 'small-100' | 'small' | 'base' | 'large-100' | 'large' | 'max'>;
 }
+/** @publicDocs */
 export interface ModalElementSlots {
     /**
-     * The primary action to perform, provided as a button type element.
+     * The main action button displayed in the modal footer, representing the primary action users should take. Only accepts a single button component.
      */
     'primary-action'?: HTMLElement;
     /**
-     * The secondary actions to perform, provided as button type elements.
+     * Additional action buttons displayed in the modal footer, providing alternative or supporting actions.
      */
     'secondary-actions'?: HTMLElement;
 }
+/** @publicDocs */
 export interface ModalEvents extends Pick<ModalProps$1, 'onAfterHide' | 'onAfterShow' | 'onHide' | 'onShow'> {
 }
+/** @publicDocs */
 export interface ModalElementMethods extends Pick<ModalProps$1, 'hideOverlay'> {
 }
+/** @publicDocs */
 export interface ModalElementEvents {
     /**
-     * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished.
+     * A callback fired when the modal 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 modal 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 modal is hidden.
      */
     hide?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback fired after the overlay is shown.
+     * A callback fired immediately after the modal is shown.
      */
     show?: CallbackEventListener<typeof tagName>;
 }
+/**
+ * The HTML element interface for the `s-modal` custom element.
+ * @publicDocs
+ */
 export interface ModalElement extends ModalElementProps, ModalElementMethods, Omit<HTMLElement, 'id'> {
     onafterhide: ModalEvents['onAfterHide'];
     onaftershow: ModalEvents['onAfterShow'];
     onhide: ModalEvents['onHide'];
     onshow: ModalEvents['onShow'];
 }
+/** @publicDocs */
 export interface ModalProps extends ModalElementProps, ModalEvents {
 }
 declare global {

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

@@ -10,58 +10,85 @@
 /// <reference lib="DOM" />
 import type {MoneyFieldProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
     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.
+ * @publicDocs
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-money-field";
+/** @publicDocs */
 export interface MoneyFieldElementProps extends Pick<MoneyFieldProps$1, 'autocomplete' | 'defaultValue' | 'disabled' | 'error' | 'id' | 'label' | 'labelAccessibilityVisibility' | 'max' | 'min' | 'name' | 'readOnly' | 'required' | 'step' | 'value'> {
 }
+/** @publicDocs */
 export interface MoneyFieldEvents extends Pick<MoneyFieldProps$1, 'onBlur' | 'onChange' | 'onFocus' | 'onInput'> {
 }
+/** @publicDocs */
 export interface MoneyFieldElementEvents {
     /**
-     * Callback when the element loses focus.
+<<<<<<< HEAD
+     * A callback fired when the element loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      *
      * @see 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.
+     * Callback when the user has **finished editing** a field, for example, once they have blurred the field.
      *
      * @see 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 element receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
+=======
+     * A callback fired when the money field value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
-    focus?: CallbackEventListener<typeof tagName>;
+    change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the money field.
+>>>>>>> 8763c703b (Improve Forms component descriptions to match admin quality)
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
+    /**
+     * A callback fired when the money field loses focus.
+     *
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
+     */
+    blur?: CallbackEventListener<typeof tagName>;
+    /**
+     * A callback fired when the money field receives focus.
+     *
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
+     */
+    focus?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface MoneyFieldElement extends MoneyFieldElementProps {
     onblur: MoneyFieldEvents['onBlur'];
     onchange: MoneyFieldEvents['onChange'];
     onfocus: MoneyFieldEvents['onFocus'];
     oninput: MoneyFieldEvents['onInput'];
 }
+/** @publicDocs */
 export interface MoneyFieldProps extends MoneyFieldElementProps, MoneyFieldEvents {
 }
 declare global {

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

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {IconProps$1, NumberFieldProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,6 +18,7 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
@@ -30,20 +29,31 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
  * @see https://github.com/Shopify/ui-api-design/blob/main/packages/ui-api-design/src/components/Icon/Icon.ts#L10
  */
 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", "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"];
+/** @publicDocs */
 export type ReducedIconTypes = (typeof CHECKOUT_AVAILABLE_ICONS)[number];
+/**
+ * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ * @publicDocs
+ */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
+ */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName$1 = "s-icon";
+/** @publicDocs */
 export interface IconProps extends Pick<IconProps$1, 'id' | 'size' | 'tone' | 'type'> {
     tone?: Extract<IconProps$1['tone'], 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'custom'>;
     size?: Extract<IconProps$1['size'], 'small-200' | 'small-100' | 'small' | 'base' | 'large' | 'large-100'>;
     type?: '' | ReducedIconTypes;
 }
+/** @publicDocs */
 export interface IconElement extends IconProps, Omit<HTMLElement, 'id'> {
 }
 declare global {
@@ -60,6 +70,7 @@ declare module 'preact' {
 }
 
 declare const tagName = "s-number-field";
+/** @publicDocs */
 export interface NumberFieldElementProps extends Pick<NumberFieldProps$1, 'autocomplete' | 'controls' | 'defaultValue' | 'disabled' | 'error' | 'icon' | 'inputMode' | 'id' | 'label' | 'labelAccessibilityVisibility' | 'max' | 'min' | 'name' | 'prefix' | 'readOnly' | 'required' | 'step' | 'suffix' | 'value'> {
     icon?: IconProps['type'];
     /**
@@ -68,47 +79,69 @@ export interface NumberFieldElementProps extends Pick<NumberFieldProps$1, 'autoc
      */
     placeholder?: string;
 }
+/** @publicDocs */
 export interface NumberFieldEvents extends Pick<NumberFieldProps$1, 'onBlur' | 'onChange' | 'onFocus' | 'onInput'> {
 }
+/** @publicDocs */
 export interface NumberFieldElementEvents {
     /**
-     * Callback when the element loses focus.
+<<<<<<< HEAD
+     * A callback fired when the element loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      *
      * @see 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.
+     * Callback when the user has **finished editing** a field, for example, once they have blurred the field.
      *
      * @see 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 element receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
+=======
+     * A callback fired when the number field value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
-    focus?: CallbackEventListener<typeof tagName>;
+    change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the number field.
+>>>>>>> 8763c703b (Improve Forms component descriptions to match admin quality)
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
+    /**
+     * A callback fired when the number field loses focus.
+     *
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
+     */
+    blur?: CallbackEventListener<typeof tagName>;
+    /**
+     * A callback fired when the number field receives focus.
+     *
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
+     */
+    focus?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface NumberFieldElementSlots {
     /**
-     * Additional content to be displayed in the field.
-     * Commonly used to display an icon that activates a tooltip providing more information.
+     * Additional interactive content displayed within the field.
+     *
+     * Accepts button and clickable components with text content only. Other component types or complex layouts are not supported.
      */
     accessory?: HTMLElement;
 }
+/** @publicDocs */
 export interface NumberFieldElement extends NumberFieldElementProps, Omit<HTMLElement, 'id' | 'inputMode' | 'onblur' | 'onchange' | 'onfocus' | 'oninput' | 'prefix'> {
     onblur: NumberFieldEvents['onBlur'];
     onchange: NumberFieldEvents['onChange'];
     onfocus: NumberFieldEvents['onFocus'];
     oninput: NumberFieldEvents['onInput'];
 }
+/** @publicDocs */
 export interface NumberFieldProps extends NumberFieldElementProps, NumberFieldEvents {
 }
 declare global {

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

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {OptionProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,14 +18,17 @@ 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-option";
+/** @publicDocs */
 export interface OptionProps extends Pick<OptionProps$1, 'accessibilityLabel' | 'defaultSelected' | 'disabled' | 'id' | 'selected' | 'value'> {
 }
+/** @publicDocs */
 export interface OptionElement extends OptionProps, Omit<HTMLElement, 'id'> {
 }
 declare global {

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

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {OrderedListProps$1} from './components-shared.d.ts';
 
-/**
- * Used when an element does not have children.
- */
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -20,14 +18,17 @@ 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-ordered-list";
+/** @publicDocs */
 export interface OrderedListProps extends OrderedListProps$1 {
 }
+/** @publicDocs */
 export interface OrderedListElement extends OrderedListProps, Omit<HTMLElement, 'id'> {
 }
 declare global {