@shopify/ui-extensions 2026.1.3 → 2026.1.4

package/build/ts/surfaces/customer-account/components/Abbreviation.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {AbbreviationProps$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-abbreviation";
+/** @publicDocs */
 export interface AbbreviationElementProps extends Pick<AbbreviationProps$1, 'title' | 'id'> {
 }
+/** @publicDocs */
 export interface AbbreviationElement extends AbbreviationElementProps, Omit<HTMLElement, 'id' | 'title'> {
 }
+/** @publicDocs */
 export interface AbbreviationProps extends AbbreviationElementProps {
 }
 declare global {

package/build/ts/surfaces/customer-account/components/Announcement.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {AnnouncementProps$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,68 +18,100 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 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.
+ * @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;
+/**
+ * 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";
+/** @publicDocs */
 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 [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState` property](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
+     * - If the element is transitioning from showing to hidden, then the `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), [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
      */
     toggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
 }
+/** @publicDocs */
 export interface AnnouncementElement extends AnnouncementMethods, Omit<HTMLElement, 'id' | 'ontoggle'> {
     onaftertoggle?: AnnouncementEvents['onAfterToggle'];
     ondismiss?: AnnouncementEvents['onDismiss'];
     ontoggle?: AnnouncementEvents['onToggle'];
 }
+/** @publicDocs */
 export interface AnnouncementProps extends AnnouncementEvents {
 }
+/** @publicDocs */
 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/build/ts/surfaces/customer-account/components/Avatar.d.ts

@@ -1,5 +1,8 @@
 import {BaseElementPropsWithChildren, IdProps, SizeKeyword} from './shared';
 
+/**
+ * An event listener typed to a specific HTML element, with a strongly typed `currentTarget`.
+ */
 export type CallbackEventListener<
   TTagName extends keyof HTMLElementTagNameMap,
   TEvent extends Event = Event,
@@ -9,21 +12,30 @@ export type CallbackEventListener<
     })
   | null;
 
+/**
+ * The properties for the avatar component. An avatar displays a user or entity image with fallback initials when the image isn't available. Properties include `src` for the image URL, `initials` for the fallback text, `alt` for accessibility text, and `size` for controlling the avatar dimensions.
+ */
 export interface AvatarElementProps extends IdProps {
   /**
-   * Initials to display in the avatar.
+   * The initials to display in the avatar when no image is provided or fails to load. Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe.
    *
-   * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.
+   * Characters beyond the first two might be truncated. Special characters, emojis, and non-Latin scripts might not render as expected.
    */
   initials?: string;
 
   /**
-   * The URL or path to the image.
+   * The URL or path to the avatar image. When provided, the image takes priority over `initials`. If the image fails to load or loads slowly, `initials` will be rendered as a fallback.
    */
   src?: string;
 
   /**
-   * Size of the avatar.
+   * The size of the avatar image.
+   *
+   * - `'small'`: Small avatar, good for secondary contexts or tight layouts.
+   * - `'large'`: Large avatar for emphasis or when the avatar is a focal point.
+   * - `'base'`: Default size that works well in most contexts.
+   * - `'small-200'`: Extra small avatar, suitable for compact displays or lists with many items.
+   * - `'large-200'`: Extra large avatar for prominent display.
    *
    * @default 'base'
    */
@@ -33,28 +45,40 @@ export interface AvatarElementProps extends IdProps {
   >;
 
   /**
-   * An alternative text description that describe the image for the reader
-   * to understand what it is about or identify the user the avatar belongs to.
+   * Alternative text that describes the avatar for accessibility.
+   *
+   * Provides a text description of the avatar for users with assistive technology
+   * and serves as a fallback when the avatar fails to load. A well-written description
+   * enables people with visual impairments to understand non-text content.
+   *
+   * When a screen reader encounters an avatar, it reads this description aloud.
+   * When an avatar fails to load, this text displays on screen, helping all users
+   * understand what content was intended.
+   *
+   * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4)
+   * and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
    */
   alt?: string;
 }
 
+/**
+ * The event handlers for the avatar component.
+ */
 export interface AvatarElementEvents {
   /**
-   * Invoked when load of provided image completes successfully.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+   * A callback that's fired when the avatar image has loaded successfully.
    */
   onLoad?(event: Event): void;
 
   /**
-   * Invoked on load error of provided image.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   * A callback that's fired when the avatar image fails to load.
    */
   onError?(event: Event): void;
 }
 
+/**
+ * The HTML element interface for the `s-avatar` custom element.
+ */
 export interface AvatarElement
   extends AvatarElementProps,
     Omit<HTMLElement, 'id'> {
@@ -62,18 +86,24 @@ export interface AvatarElement
   onerror: AvatarElementEvents['onError'];
 }
 
+/**
+ * The event listeners for the `s-avatar` custom element.
+ */
 export interface AvatarEvents {
   /**
-   * Callback when the image loads successfully.
+   * A callback that's fired when the avatar image has loaded successfully.
    */
   load?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
 
   /**
-   * Callback when the image fails to load.
+   * A callback that's fired when the avatar image fails to load.
    */
   error?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
 }
 
+/**
+ * The properties for the avatar component when it's used in JSX.
+ */
 export type AvatarProps = AvatarElementProps & AvatarElementEvents;
 
 declare global {

package/build/ts/surfaces/customer-account/components/Badge.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {BadgeProps$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,27 +18,71 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     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'];
 }
+/** @publicDocs */
 export interface BadgeElement extends BadgeElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface BadgeProps extends BadgeElementProps {
 }
 declare global {

package/build/ts/surfaces/customer-account/components/Banner.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {BannerProps$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,47 +18,104 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 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.
+ * @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-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'>;
 }
+/** @publicDocs */
 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>;
 }
+/** @publicDocs */
 export interface BannerElement extends BannerElementProps, Omit<HTMLElement, 'id' | 'title' | 'hidden'> {
     onafterhide: BannerEvents['onAfterHide'];
     ondismiss: BannerEvents['onDismiss'];
 }
+/** @publicDocs */
 export interface BannerProps extends BannerElementProps, BannerEvents {
 }
 declare global {

package/build/ts/surfaces/customer-account/components/Box.d.ts

@@ -10,12 +10,30 @@
 /// <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.
+ * @publicDocs
+ */
 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.
+ * @publicDocs
+ */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
-export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
- * Used when an element does not have children.
+ * 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.
+ * @publicDocs
  */
+export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
+/** @publicDocs */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
     ref?: preact.Ref<TClass>;
@@ -23,20 +41,56 @@ 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-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'>>;
 }
+/** @publicDocs */
 export interface BoxElement extends BoxElementProps, Omit<HTMLElement, 'id'> {
 }
+/** @publicDocs */
 export interface BoxProps extends BoxElementProps {
 }
 declare global {

package/build/ts/surfaces/customer-account/components/Button.d.ts

@@ -10,9 +10,7 @@
 /// <reference lib="DOM" />
 import type {ButtonProps$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,38 +18,61 @@ export interface BaseElementProps<TClass = HTMLElement> {
 }
 /**
  * Used when an element has children.
+ * @publicDocs
  */
 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.
+ * @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-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'>;
+    /**
+     * The behavioral type of the button component, which determines what action it performs when activated.
+     *
+     * - `submit`: Submits the nearest containing form.
+     * - `button`: Performs no default action, relying on the `click` event handler for behavior.
+     *
+     * This property is ignored if `href` or `commandFor`/`command` is set.
+     *
+     * @default 'button'
+     */
     type?: Extract<ButtonProps$1['type'], 'submit' | 'button'>;
     variant?: Extract<ButtonProps$1['variant'], 'auto' | 'primary' | 'secondary'>;
 }
+/** @publicDocs */
 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>;
 }
+/** @publicDocs */
 export interface ButtonElement extends ButtonElementProps, Omit<HTMLElement, 'id' | 'onclick'> {
     onclick: ButtonEvents['onClick'];
 }
+/** @publicDocs */
 export interface ButtonProps extends ButtonElementProps, ButtonEvents {
 }
 declare global {