@shopify/ui-extensions 2026.1.3 → 2026.1.4

package/build/ts/surfaces/customer-account/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/customer-account/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/customer-account/components/Menu.d.ts

@@ -2,7 +2,7 @@ import {BaseElementPropsWithChildren, IdProps} from './shared';
 
 export interface MenuProps extends IdProps {
   /**
-   * A label to describe the purpose of the menu that is announced by screen readers.
+   * A label that describes the purpose of the menu for users of assistive technologies such as screen readers. Use this to provide context about the available actions, such as "Order actions" or "Account settings."
    */
   accessibilityLabel?: string;
 }

package/build/ts/surfaces/customer-account/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/customer-account/components/MoneyField.d.ts

@@ -10,58 +10,81 @@
 /// <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).
+=======
+     * A callback fired when the money field loses focus.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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.
+<<<<<<< HEAD
+     * Callback when the user has **finished editing** a field, for example, once they have blurred the field.
+=======
+     * A callback fired when the money field value changes.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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.
+<<<<<<< HEAD
+     * 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 receives focus.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the money field.
      *
-     * @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>;
 }
+/** @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/customer-account/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,22 +29,34 @@ 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-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"];
+/** @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 IconElementProps 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 IconElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface IconProps extends IconElementProps {
 }
 declare global {
@@ -62,6 +73,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'];
     /**
@@ -70,47 +82,63 @@ 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).
+=======
+     * A callback fired when the number field loses focus.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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.
+<<<<<<< HEAD
+     * Callback when the user has **finished editing** a field, for example, once they have blurred the field.
+=======
+     * A callback fired when the number field value changes.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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.
+<<<<<<< HEAD
+     * 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 receives focus.
+>>>>>>> eb0f07393 (Improve Forms component descriptions to match admin quality)
      *
-     * @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>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the number field.
      *
-     * @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>;
 }
+/** @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/customer-account/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,16 +18,20 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-option";
+/** @publicDocs */
 export interface OptionElementProps extends Pick<OptionProps$1, 'accessibilityLabel' | 'defaultSelected' | 'disabled' | 'id' | 'selected' | 'value'> {
 }
+/** @publicDocs */
 export interface OptionElement extends OptionElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface OptionProps extends OptionElementProps {
 }
 declare global {

package/build/ts/surfaces/customer-account/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,16 +18,20 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
 }
 
 declare const tagName = "s-ordered-list";
+/** @publicDocs */
 export interface OrderedListElementProps extends OrderedListProps$1 {
 }
+/** @publicDocs */
 export interface OrderedListElement extends OrderedListElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface OrderedListProps extends OrderedListElementProps {
 }
 declare global {