@shopify/ui-extensions 2026.1.3 → 2026.1.4

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

@@ -1,23 +1,31 @@
 import {BaseElementPropsWithChildren, IdProps} from './shared';
-
+/**
+ * @publicDocs
+ */
 export interface ButtonGroupProps extends IdProps {
   /**
-   * Label for the button group that describes the content of the group for screen reader users to understand what's included.
+   * A label that describes the purpose of the button group for users of assistive technologies such as screen readers. Use this to provide context about the grouped actions, such as "Order actions" or "Profile settings."
    */
   accessibilityLabel?: string;
 }
 
+/**
+ * @publicDocs
+ */
 export interface ButtonGroupElementSlots {
   /**
-   * The primary action for the group. Accepts a single [Button](/docs/api/checkout-ui-extensions/web-components/actions/button) element.
+   * The primary action for the group. Accepts a single [button](/docs/api/customer-account-ui-extensions/{API_VERSION}/web-components/actions/button) element. Use this for the most important action in the group, such as "Save" or "Submit."
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions for the group. Accepts multiple [Button](/docs/api/checkout-ui-extensions/web-components/actions/button) elements.
+   * The secondary actions for the group. Accepts multiple [button](/docs/api/customer-account-ui-extensions/{API_VERSION}/web-components/actions/button) elements. Use this for supplementary actions like "Cancel", "Delete", or other alternatives.
    */
   'secondary-actions'?: HTMLElement;
 }
 
+/**
+ * @publicDocs
+ */
 export interface ButtonGroupElement
   extends ButtonGroupProps,
     Omit<HTMLElement, 'id'> {}

package/src/surfaces/customer-account/components/CustomerAccountAction.d.ts

@@ -1,23 +1,31 @@
 import {BaseElementPropsWithChildren, IdProps} from './shared';
-
+/**
+ * @publicDocs
+ */
 export interface CustomerAccountActionProps extends IdProps {
   /**
-   * Sets the heading of the action container.
+   * The main title displayed at the top of the action modal, rendered in the header alongside the close button. Use a short, descriptive phrase that tells the customer what the action does, such as "Request a return" or "Edit shipping address."
    */
   heading: string;
 }
 
+/**
+ * @publicDocs
+ */
 export interface CustomerAccountActionElementSlots {
   /**
-   * The primary action for the page. Accepts a single Button element with restricted properties (see below).
+   * The primary action for the modal. Accepts a single [button](/docs/api/customer-account-ui-extensions/{API_VERSION}/web-components/actions/button) element. Use this for the main confirmation action, such as "Submit" or "Confirm."
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
+   * The secondary actions for the modal. Accepts multiple [button](/docs/api/customer-account-ui-extensions/{API_VERSION}/web-components/actions/button) elements. Use this for dismissive actions like "Cancel" or alternative actions.
    */
   'secondary-actions'?: HTMLElement;
 }
 
+/**
+ * @publicDocs
+ */
 export interface CustomerAccountActionElement
   extends HTMLElement,
     CustomerAccountActionProps {}

package/src/surfaces/customer-account/components/ImageGroup.d.ts

@@ -1,13 +1,18 @@
 import {BaseElementPropsWithChildren, IdProps} from './shared';
 
+/**
+ * The properties for the image group component. An image group displays a collection of images in a grid layout with an optional overflow count, useful for showing multiple product images or gallery previews.
+ */
 export interface ImageGroupProps extends IdProps {
   /**
-   * Indicates the total number of items that could be displayed in the image group.
-   * It is used to determine the remaining number to show when all the available image slots have been filled.
+   * The total number of items that the image group represents. When this value exceeds the number of visible images, the component displays a badge showing the remaining count (for example, "+3"), indicating there are more images than currently displayed.
    */
   totalItems?: number;
 }
 
+/**
+ * The HTML element interface for the `s-image-group` custom element.
+ */
 export interface ImageGroupElement extends HTMLElement, ImageGroupProps {}
 
 declare global {

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

@@ -1,32 +1,40 @@
 import {BaseElementPropsWithChildren, IdProps} from './shared';
-
+/**
+ * @publicDocs
+ */
 export interface PageProps extends IdProps {
   /**
-   * The main page heading
+   * The main heading displayed at the top of the page.
    */
   heading?: string;
 
   /**
-   * The text to be used as subheading.
+   * A secondary heading displayed below the main heading for additional context.
    */
   subheading?: string;
 }
 
+/**
+ * @publicDocs
+ */
 export interface PageElementSlots {
   /**
-   * The breadcrumb actions for the page. Accepts a single Button element with restricted properties (see below).
+   * A navigation link that lets the customer return to the previous page. Accepts a single [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) component. Learn more about [breadcrumb actions](#breadcrumb-actions).
    */
   'breadcrumb-actions'?: HTMLElement;
   /**
-   * The primary action for the page. Accepts a single Button element with restricted properties (see below).
+   * The main call-to-action for the page. Accepts a single [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) component. Learn more about [primary actions](#primary-actions).
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
+   * Additional actions for the page. Accepts one or more [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) components. Learn more about [secondary actions](#secondary-actions).
    */
   'secondary-actions'?: HTMLElement;
 }
 
+/**
+ * @publicDocs
+ */
 export interface PageElement extends HTMLElement, PageProps {}
 
 declare global {

package/src/surfaces/customer-account/components/Section.d.ts

@@ -1,12 +1,10 @@
 import {BaseElementPropsWithChildren, IdProps} from './shared';
-
+/**
+ * @publicDocs
+ */
 export interface SectionProps extends IdProps {
   /**
-   * A label used to describe the section that will be announced by assistive technologies.
-   *
-   * When no `heading` property is provided or included as a children of the Section, you **must** provide an
-   * `accessibilityLabel` to describe the Section. This is important as it allows assistive technologies to provide
-   * the right context to users.
+   * A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.
    */
   accessibilityLabel?: string;
 
@@ -16,17 +14,23 @@ export interface SectionProps extends IdProps {
   heading?: string;
 }
 
+/**
+ * @publicDocs
+ */
 export interface SectionElementSlots {
   /**
-   * The primary action for the section. Accepts a single [Button](/docs/api/checkout-ui-extensions/web-components/actions/button) element.
+   * The main call-to-action for the section. Accepts a single [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) component.
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions for the section. Accepts multiple [Button](/docs/api/checkout-ui-extensions/web-components/actions/button) elements.
+   * Additional actions for the section. Accepts one or more [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) components.
    */
   'secondary-actions'?: HTMLElement;
 }
 
+/**
+ * @publicDocs
+ */
 export interface SectionElement extends SectionProps, Omit<HTMLElement, 'id'> {}
 
 declare global {

package/src/surfaces/customer-account/components/polaris-elements.d.ts

@@ -0,0 +1,151 @@
+// Polaris web component element types for customer-account surface
+// These are required for public docs and must be exported for doc generation.
+// Each export is tagged with @publicDocs and a placeholder JSDoc. Update descriptions as needed.
+
+// Button
+/**
+ * Properties for the button component element.
+ * @publicDocs
+ */
+export type ButtonElementProps =
+  import('../../checkout/components/Button').ButtonElementProps;
+/**
+ * Events for the button component element.
+ * @publicDocs
+ */
+export type ButtonElementEvents =
+  import('../../checkout/components/Button').ButtonElementEvents;
+/**
+ * Slots for the button component element.
+ * @publicDocs
+ */
+export type ButtonElementSlots =
+  import('../../checkout/components/Button').ButtonElementSlots;
+/**
+ * Methods for the button component element.
+ * @publicDocs
+ */
+export type ButtonElementMethods =
+  import('../../checkout/components/Button').ButtonElementMethods;
+
+// Add similar exports for all other missing Polaris web components (TextField, Checkbox, etc.) following this pattern.
+
+// Checkbox
+/**
+ * Properties for the Checkbox component element.
+ * @publicDocs
+ */
+export type CheckboxElementProps =
+  import('../../checkout/components/Checkbox').CheckboxElementProps;
+/**
+ * Events for the Checkbox component element.
+ * @publicDocs
+ */
+export type CheckboxElementEvents =
+  import('../../checkout/components/Checkbox').CheckboxElementEvents;
+// No slots or methods for Checkbox in checkout
+
+// TextField
+/**
+ * Properties for the TextField component element.
+ * @publicDocs
+ */
+export type TextFieldElementProps =
+  import('../../checkout/components/TextField').TextFieldElementProps;
+/**
+ * Events for the TextField component element.
+ * @publicDocs
+ */
+export type TextFieldElementEvents =
+  import('../../checkout/components/TextField').TextFieldElementEvents;
+/**
+ * Slots for the TextField component element.
+ * @publicDocs
+ */
+export type TextFieldElementSlots =
+  import('../../checkout/components/TextField').TextFieldElementSlots;
+// No methods for TextField in checkout
+
+// Select
+/**
+ * Properties for the Select component element.
+ * @publicDocs
+ */
+export type SelectElementProps =
+  import('../../checkout/components/Select').SelectElementProps;
+/**
+ * Events for the Select component element.
+ * @publicDocs
+ */
+export type SelectElementEvents =
+  import('../../checkout/components/Select').SelectElementEvents;
+// No slots or methods for Select in checkout
+
+// ClickableChip
+/**
+ * Slots for the ClickableChip component element.
+ * @publicDocs
+ */
+export type ClickableChipElementSlots =
+  import('../../checkout/components/ClickableChip').ClickableChipElementSlots;
+
+/**
+ * Events for the ClickableChip component element.
+ * @publicDocs
+ */
+export type ClickableChipElementEvents =
+  import('../../checkout/components/ClickableChip').ClickableChipElementEvents;
+
+// Badge
+/**
+ * Properties for the Badge component element.
+ * @publicDocs
+ */
+export type BadgeElementProps =
+  import('../../checkout/components/Badge').BadgeElementProps;
+
+// Spinner
+/**
+ * Properties for the Spinner component element.
+ * @publicDocs
+ */
+export type SpinnerElementProps =
+  import('../../checkout/components/Spinner').SpinnerElementProps;
+
+// Tooltip
+/**
+ * Properties for the Tooltip component element.
+ * @publicDocs
+ */
+export type TooltipElementProps =
+  import('../../checkout/components/Tooltip').TooltipElementProps;
+
+// Chip
+/**
+ * Properties for the Chip component element.
+ * @publicDocs
+ */
+export type ChipElementProps =
+  import('../../checkout/components/Chip').ChipElementProps;
+/**
+ * Slots for the Chip component element.
+ * @publicDocs
+ */
+export type ChipElementSlots =
+  import('../../checkout/components/Chip').ChipElementSlots;
+
+// UnorderedList
+/**
+ * Properties for the UnorderedList component element.
+ * @publicDocs
+ */
+export type UnorderedListElementProps =
+  import('../../checkout/components/UnorderedList').UnorderedListElementProps;
+
+// OrderedList
+/**
+ * Properties for the OrderedList component element.
+ * @publicDocs
+ */
+export type OrderedListElementProps =
+  import('../../checkout/components/OrderedList').OrderedListElementProps;

package/src/surfaces/customer-account/components/shared.ts

@@ -1,10 +1,16 @@
+/**
+ * Provides an `id` property for uniquely identifying elements. This is used across customer account components to enable targeting specific elements for styling, scripting, or accessibility purposes.
+ */
 export interface IdProps {
   /**
-   * A unique identifier for the element.
+   * A unique identifier for the element. Use this to target the element with CSS, JavaScript, or accessibility attributes. The `id` must be unique within the document.
    */
   id?: string;
 }
 
+/**
+ * The design system's size scale, used to control the dimensions of components like avatars, icons, and thumbnails. Values range from `'small-500'` (smallest) through `'base'` (standard) to `'large-500'` (largest). Not all components support every size — check the component's `size` property type for its available options.
+ */
 export type SizeKeyword =
   | 'small-500'
   | 'small-400'
@@ -20,19 +26,31 @@ export type SizeKeyword =
   | 'large-400'
   | 'large-500';
 
+/**
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
+ */
 export interface BaseElementProps<TClass = HTMLElement> {
-  // Assigns a unique key to this element.
+  /**
+   * A unique identifier for this element within its parent. Used by Preact for efficient rendering and reconciliation when lists of elements change by tracking which items have been added, removed, or reordered.
+   */
   key?: preact.Key;
-  // Assigns a ref (generally from `useRef()`) to this element.
+  /**
+   * 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 for imperative operations.
+   */
   ref?: preact.Ref<TClass>;
-  // Assigns this element to a parent's slot.
+  /**
+   * Assigns this element to a named slot in a parent component that uses slot-based composition patterns.
+   */
   slot?: Lowercase<string>;
 }
 
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: preact.ComponentChildren;
 }

package/src/surfaces/customer-account/components.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @publicDocs
+ */
 /**
  * @fileoverview This file is used to generate the documentation for the customer-account surface. For component types, see the components folder.
  */
@@ -26,8 +29,29 @@ import {
   SectionElementSlots,
 } from './components/Section';
 
+/**
+ * The element props interface for the avatar component.
+ * @publicDocs
+ */
+export type AvatarElementPropsDocs = AvatarElementProps;
+/**
+ * @publicDocs
+ */
+export type AvatarElementEventsDocs = AvatarEvents;
+
+/**
+ * @publicDocs
+ */
 export type CustomerAccountActionPropsDocs = CustomerAccountActionProps;
+/**
+ * The custom element interface for the customer account action component.
+ * @publicDocs
+ */
 export type CustomerAccountActionElementDocs = CustomerAccountActionElement;
+/**
+ * The customer account action component supports slots for additional content placement within the modal. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ * @publicDocs
+ */
 export type CustomerAccountActionElementSlotsDocs =
   CustomerAccountActionElementSlots;
 
@@ -50,7 +74,14 @@ declare module 'preact' {
   }
 }
 
+/**
+ * @publicDocs
+ */
 export type ImageGroupPropsDocs = ImageGroupProps;
+/**
+ * The custom element interface for the image group component.
+ * @publicDocs
+ */
 export type ImageGroupElementDocs = ImageGroupElement;
 
 declare global {
@@ -71,8 +102,18 @@ declare module 'preact' {
   }
 }
 
+/**
+ * @publicDocs
+ */
 export type PagePropsDocs = PageProps;
+/**
+ * @publicDocs
+ */
 export type PageElementDocs = PageElement;
+/**
+ * The page component supports slots for additional content placement within the page. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ * @publicDocs
+ */
 export type PageElementSlotsDocs = PageElementSlots;
 
 declare global {
@@ -94,9 +135,19 @@ declare module 'preact' {
   }
 }
 
-export type AvatarElementPropsDocs = AvatarElementProps;
+/**
+ * @publicDocs
+ */
 export type AvatarPropsDocs = AvatarProps;
+/**
+ * The custom element interface for the avatar component.
+ * @publicDocs
+ */
 export type AvatarElementDocs = AvatarElement;
+/**
+ * The avatar component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ * @publicDocs
+ */
 export type AvatarEventsDocs = AvatarEvents;
 
 declare global {
@@ -115,7 +166,13 @@ declare module 'preact' {
   }
 }
 
+/**
+ * @publicDocs
+ */
 export type MenuPropsDocs = MenuProps;
+/**
+ * @publicDocs
+ */
 export type MenuElementDocs = MenuElement;
 
 declare global {
@@ -136,8 +193,19 @@ declare module 'preact' {
   }
 }
 
+/**
+ * @publicDocs
+ */
 export type ButtonGroupPropsDocs = ButtonGroupProps;
+/**
+ * The custom element interface for the button group component.
+ * @publicDocs
+ */
 export type ButtonGroupElementDocs = ButtonGroupElement;
+/**
+ * The button group component supports slots for additional content placement within the group. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ * @publicDocs
+ */
 export type ButtonGroupElementSlotsDocs = ButtonGroupElementSlots;
 
 declare global {
@@ -159,8 +227,18 @@ declare module 'preact' {
   }
 }
 
+/**
+ * @publicDocs
+ */
 export type SectionPropsDocs = SectionProps;
+/**
+ * @publicDocs
+ */
 export type SectionElementDocs = SectionElement;
+/**
+ * The section component supports slots for additional content placement within the section. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ * @publicDocs
+ */
 export type SectionElementSlotsDocs = SectionElementSlots;
 
 declare global {