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

package/src/surfaces/checkout/preact/storage.ts

@@ -10,6 +10,7 @@ import {useApi} from './api';
  *
  * Data is shared across all activated extension targets of this extension. In versions `<=2023-07`,
  * each activated extension target had its own storage.
+ * @publicDocs
  */
 export function useStorage<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/preact/subscription.ts

@@ -13,6 +13,7 @@ type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
  * > As of version 2025-10, you no longer need this hook. When you access `.value`
  * > (instead of `.current`) on subscribable properties, Preact will automatically
  * > re-render as `.value` changes.
+ * @publicDocs
  */
 export function useSubscription<Value>(
   subscription: SubscribableSignalLike<Value>,

package/src/surfaces/checkout/preact/target.ts

@@ -23,6 +23,7 @@ class ExtensionHasNoTargetError extends Error {
  * > Caution: Deprecated as of version `2023-10`, use `useCartLineTarget()` instead.
  *
  * @deprecated Deprecated as of version `2023-10`, use `useCartLineTarget()` instead.
+ * @publicDocs
  */
 export function useTarget(): CartLine {
   const api = useApi<

package/src/surfaces/checkout/preact/timezone.ts

@@ -7,6 +7,7 @@ import {useSubscription} from './subscription';
 /**
  * Returns the time zone of the checkout, and automatically re-renders
  * your component if the time zone changes.
+ * @publicDocs
  */
 export function useTimezone<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/preact/translate.ts

@@ -5,6 +5,7 @@ import {useApi} from './api';
 
 /**
  * Returns the `I18nTranslate` interface used to translate strings.
+ * @publicDocs
  */
 export function useTranslate<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/shared.ts

@@ -11,6 +11,7 @@ export const SUPPORTED_COMPONENTS = [
   'Banner',
   'Box',
   'Button',
+  'Chat',
   'Checkbox',
   'Chip',
   'Choice',
@@ -69,18 +70,10 @@ export const SUPPORTED_COMPONENTS = [
   'UrlField',
 ] as const;
 
-/**
- * Note: Chat is not supported in the 2025-10 release candidate, but it is tied to a target, and we don't want to remove the target documentation.
- * Once Chat is supported, you can remove this note.
- * @private
- */
-export type PrivateComponent = 'Chat';
-
 export type ThankYouComponent = 'Announcement';
 
-export type AnyComponent =
-  | (typeof SUPPORTED_COMPONENTS)[number]
-  | PrivateComponent;
+/** @publicDocs */
+export type AnyComponent = (typeof SUPPORTED_COMPONENTS)[number];
 
 /**
  * The list of supported components.
@@ -95,24 +88,21 @@ export type AnyCheckoutComponentExcept<Except extends AnyCheckoutComponent> =
   Exclude<AnyCheckoutComponent, Except>;
 
 /**
- * Represents a read-only value managed on the main thread that an extension can subscribe to.
- *
- * Example: Checkout uses this to manage the state of an object and
- * communicate state changes to extensions running in a sandboxed web worker.
- *
- * This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709).
- *
- * Some fields are deprecated but still supported for backwards compatibility.
- * In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.
- *
+ * Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.
  */
 export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
   /**
+   * The current value of the signal. Equivalent to `.value`, accessing this property
+   * subscribes to changes when used in a reactive context.
+   *
    * @deprecated Use `.value` instead.
    */
   readonly current: T;
   /**
-   * @deprecated No longer needed. Use Preact Signal management instead.
+   * Cleans up the subscription and releases any resources held by this signal. After calling
+   * `destroy()`, the signal stops receiving updates from the main thread.
+   *
+   * @deprecated No longer needed. Use [Preact Signals](https://preactjs.com/guide/v10/signals) to manage reactive state instead.
    */
   destroy(): Promise<void>;
 }

package/src/surfaces/checkout/style/style.ts

@@ -88,6 +88,7 @@ const when: WhenFunction = function when<
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface DocsStyle {
   /**
    * Sets an optional default value to use when no other condition is met.

package/src/surfaces/checkout/style/types.ts

@@ -1,33 +1,43 @@
-type Resolution = 1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4;
+/** @publicDocs */
+export type Resolution = 1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4;
 
+/** @publicDocs */
 export interface InteractiveConditions {
   hover: true;
   focus: true;
 }
 
+/** @publicDocs */
 export interface ResolutionCondition {
   resolution: Resolution;
 }
 
-type ViewportInlineSize = 'extraSmall' | 'small' | 'medium' | 'large';
+/** @publicDocs */
+export type ViewportInlineSize = 'extraSmall' | 'small' | 'medium' | 'large';
 
+/** @publicDocs */
 export interface ViewportSizeCondition<T = ViewportInlineSize> {
   viewportInlineSize: {min: T};
 }
 
+/** @publicDocs */
 export type AtLeastOne<T, U = {[K in keyof T]: Pick<T, K>}> = Partial<T> &
   U[keyof U];
 
-type DefaultConditions = InteractiveConditions & ViewportSizeCondition;
+/** @publicDocs */
+export type DefaultConditions = InteractiveConditions & ViewportSizeCondition;
 
+/** @publicDocs */
 export type Conditions = AtLeastOne<DefaultConditions>;
 
+/** @publicDocs */
 export type BaseConditions = AtLeastOne<
   DefaultConditions & ResolutionCondition
 >;
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface StylesBaseConditions {
   viewportInlineSize?: {min: ViewportInlineSize};
   hover?: true;
@@ -37,6 +47,7 @@ export interface StylesBaseConditions {
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface StylesConditions {
   viewportInlineSize?: {min: ViewportInlineSize};
   hover?: true;
@@ -45,6 +56,7 @@ export interface StylesConditions {
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface StylesConditionalValue<
   T,
   AcceptedConditions extends StylesBaseConditions = StylesBaseConditions,
@@ -62,6 +74,7 @@ export interface StylesConditionalValue<
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface StylesConditionalStyle<
   T,
   AcceptedConditions extends StylesBaseConditions = StylesBaseConditions,
@@ -77,6 +90,7 @@ export interface StylesConditionalStyle<
   conditionals: StylesConditionalValue<T, AcceptedConditions>[];
 }
 
+/** @publicDocs */
 export interface ConditionalValue<
   T,
   AcceptedConditions extends BaseConditions = Conditions,
@@ -92,6 +106,7 @@ export interface ConditionalValue<
   value: T;
 }
 
+/** @publicDocs */
 export interface ConditionalStyle<
   T,
   AcceptedConditions extends BaseConditions = Conditions,
@@ -110,8 +125,7 @@ export interface ConditionalStyle<
 /**
  * A type that represents a value that can be a conditional style.
  * We highly recommend using the `Style` helper which simplifies the creation of conditional styles.
- *
- * To learn more check out the [conditional styles](/api/checkout-ui-extensions/components/utilities/stylehelper) documentation.
+ * @publicDocs
  */
 export type MaybeConditionalStyle<
   T,
@@ -121,8 +135,7 @@ export type MaybeConditionalStyle<
 /**
  * A type that represents a value that can be a conditional style. The conditions are based on the viewport size.
  * We highly recommend using the `Style` helper which simplifies the creation of conditional styles.
- *
- * To learn more check out the [conditional styles](/api/checkout-ui-extensions/components/utilities/stylehelper) documentation.
+ * @publicDocs
  */
 export type MaybeResponsiveConditionalStyle<T> =
   | T

package/src/surfaces/customer-account/api/cart-line/cart-line-item.ts

@@ -1,6 +1,9 @@
 import {CartLine} from '../order-status/order-status';
 import {SubscribableSignalLike} from '../shared';
 
+/**
+ * @publicDocs
+ */
 export interface CartLineItemApi {
   /**
    * The cart line the extension is attached to.

package/src/surfaces/customer-account/api/docs.ts

@@ -2,6 +2,10 @@ import {OrderStatusApi} from './order-status/order-status';
 import {StandardApi} from './standard-api/standard-api';
 import {CartLineItemApi} from './cart-line/cart-line-item';
 
+/**
+ * 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,
@@ -9,6 +13,10 @@ export type CallbackEvent<
   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,
   TEvent extends Event = Event,
@@ -76,11 +84,11 @@ interface ButtonProps {
    */
   loading?: boolean;
   /**
-   * Specifies where to display the linked URL
+   * Specifies where to display the linked URL.
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
    *
    * 'auto' - The target is automatically determined based on the origin of the URL. Surfaces can set specific rules on how they handle each URL.
-   * It’s expected that the behavior of `auto` is as `_self` except in specific cases.
+   * It's expected that the behavior of `auto` is as `_self` except in specific cases.
    * For example, a surface could decide to open cross-origin URLs in a new window (as `_blank`).
    *
    * @default 'auto'
@@ -120,92 +128,206 @@ interface ButtonProps {
   click?: ((event: CallbackEventListener<typeof buttonTagName>) => void) | null;
 }
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with metafields.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_MetafieldsApi
   extends Pick<OrderStatusApi<any>, 'appMetafields'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with attributes.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AttributesApi
   extends Pick<OrderStatusApi<any>, 'attributes'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with buyer identity.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_BuyerIdentityApi
   extends Pick<OrderStatusApi<any>, 'buyerIdentity'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with checkout settings.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CheckoutSettingsApi
   extends Pick<OrderStatusApi<any>, 'checkoutSettings'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with order cost.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CostApi
   extends Pick<OrderStatusApi<any>, 'cost'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with localization.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_LocalizationApi
   extends Pick<OrderStatusApi<any>, 'localization'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with discounts.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_DiscountsApi
   extends Pick<OrderStatusApi<any>, 'discountAllocations' | 'discountCodes'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with gift cards.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_GiftCardsApi
   extends Pick<OrderStatusApi<any>, 'appliedGiftCards'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with the order note.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_NoteApi
   extends Pick<OrderStatusApi<any>, 'note'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with shipping and billing addresses.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AddressApi
   extends Pick<OrderStatusApi<any>, 'shippingAddress' | 'billingAddress'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with shop information.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_ShopApi
   extends Pick<OrderStatusApi<any>, 'shop'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for requiring buyer login.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_RequireLoginApi
   extends Pick<OrderStatusApi<any>, 'requireLogin'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with authentication state.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AuthenticationStateApi
   extends Pick<OrderStatusApi<any>, 'authenticationState'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with cart lines.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CartLinesApi
   extends Pick<OrderStatusApi<any>, 'lines'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` cart line item extension targets.
+ * @publicDocs
+ */
 export interface Docs_CartLineItem_CartLinesApi
   extends Pick<CartLineItemApi, 'target'> {}
 
+/**
+ * The API object provided to `customer-account.order-status` extension targets for interacting with order details.
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_OrderApi
   extends Pick<OrderStatusApi<any>, 'order'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with extension metadata.
+ * @publicDocs
+ */
 export interface Docs_Standard_ExtensionApi
   extends Pick<StandardApi<any>, 'extension'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with the authenticated account.
+ * @publicDocs
+ */
 export interface Docs_Standard_AuthenticatedAccountApi
   extends Pick<StandardApi<any>, 'authenticatedAccount'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for retrieving the renderer version.
+ * @publicDocs
+ */
 export interface Docs_Standard_VersionApi
   extends Pick<StandardApi<any>, 'version'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with localization.
+ * @publicDocs
+ */
 export interface Docs_Standard_LocalizationApi
   extends Pick<StandardApi<any>, 'localization' | 'i18n'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with session tokens.
+ * @publicDocs
+ */
 export interface Docs_Standard_SessionTokenApi
   extends Pick<StandardApi<any>, 'sessionToken'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with analytics.
+ * @publicDocs
+ */
 export interface Docs_Standard_AnalyticsApi
   extends Pick<StandardApi<any>, 'analytics'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with extension settings.
+ * @publicDocs
+ */
 export interface Docs_Standard_SettingsApi
   extends Pick<StandardApi, 'settings'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with key-value storage.
+ * @publicDocs
+ */
 export interface Docs_Standard_StorageApi
   extends Pick<StandardApi<any>, 'storage'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for interacting with customer privacy and tracking consent.
+ * @publicDocs
+ */
 export interface Docs_Standard_CustomerPrivacyApi
   extends Pick<
     StandardApi<any>,
     'customerPrivacy' | 'applyTrackingConsentChange'
   > {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for displaying toast notifications.
+ * @publicDocs
+ */
 export interface Docs_Standard_ToastApi
   extends Pick<StandardApi<any>, 'toast'> {}
 
+/**
+ * The base API object provided to all `customer-account` extension targets for querying the Storefront API.
+ * @publicDocs
+ */
 export interface Docs_Standard_QueryApi
   extends Pick<StandardApi<any>, 'query'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_StandardApi extends Omit<StandardApi<any>, 'router'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_PrimaryAction
   extends Pick<
     ButtonProps,
@@ -216,7 +338,52 @@ export interface Docs_Page_Button_PrimaryAction
     | 'href'
     | 'command'
     | 'commandFor'
-  > {}
+  > {
+  /**
+   * A label that describes the button's purpose to assistive technologies. Use this when the button text alone doesn't provide enough context.
+   */
+  accessibilityLabel?: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the button is activated, before the action indicated by `type`.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The action the `commandFor` target should take when this button is activated.
+   *
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the target component.
+   * - `--copy`: Copies the target ClipboardItem.
+   *
+   * @default '--auto'
+   */
+  command?: ButtonProps['command'];
+  /**
+   * The `id` of a component that should respond to activations on this button. See `command` for how to control the behavior of the target.
+   */
+  commandFor?: ButtonProps['commandFor'];
+  /**
+   * Whether the button is disabled and non-interactive.
+   *
+   * @default false
+   */
+  disabled?: ButtonProps['disabled'];
+  /**
+   * The URL to navigate to when the button is activated. If a `commandFor` is set, the `command` is executed instead of the navigation.
+   */
+  href?: ButtonProps['href'];
+  /**
+   * Whether to replace the button content with a loading indicator.
+   *
+   * @default false
+   */
+  loading?: ButtonProps['loading'];
+}
+
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_SecondaryAction
   extends Pick<
     ButtonProps,
@@ -227,22 +394,82 @@ export interface Docs_Page_Button_SecondaryAction
     | 'href'
     | 'command'
     | 'commandFor'
-  > {}
+  > {
+  /**
+   * A label that describes the button's purpose to assistive technologies. Use this when the button text alone doesn't provide enough context.
+   */
+  accessibilityLabel?: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the button is activated, before the action indicated by `type`.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The action the `commandFor` target should take when this button is activated.
+   *
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the target component.
+   * - `--copy`: Copies the target ClipboardItem.
+   *
+   * @default '--auto'
+   */
+  command?: ButtonProps['command'];
+  /**
+   * The `id` of a component that should respond to activations on this button. See `command` for how to control the behavior of the target.
+   */
+  commandFor?: ButtonProps['commandFor'];
+  /**
+   * Whether the button is disabled and non-interactive.
+   *
+   * @default false
+   */
+  disabled?: ButtonProps['disabled'];
+  /**
+   * The URL to navigate to when the button is activated. If a `commandFor` is set, the `command` is executed instead of the navigation.
+   */
+  href?: ButtonProps['href'];
+  /**
+   * Whether to replace the button content with a loading indicator.
+   *
+   * @default false
+   */
+  loading?: ButtonProps['loading'];
+}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_BreadcrumbAction
   extends Pick<ButtonProps, 'click' | 'href'> {
   /**
-   * A label used for buyers using assistive technologies. Needed because `children` passed to this component will be discarded.
+   * A label that describes the breadcrumb's destination to assistive technologies. Required because `children` passed to this button are discarded.
    */
   accessibilityLabel: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the breadcrumb is activated.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The URL to navigate to when the breadcrumb is activated.
+   */
+  href?: ButtonProps['href'];
 }
 
+/**
+ * The menu component exclusively accepts button elements with restricted props as its children.
+ * @publicDocs
+ */
 export interface Docs_Menu_Button_Action
   extends Omit<
     ButtonProps,
     'variant' | 'textDecoration' | 'inlineAlignment' | 'inlineSize' | 'size'
   > {}
 
+/**
+ * Supported props for Buttons used in order action menus.
+ * @publicDocs
+ */
 export interface Docs_OrderActionMenu_Button
   extends Pick<
     ButtonProps,
@@ -256,6 +483,10 @@ export interface Docs_OrderActionMenu_Button
   href: ButtonProps['href'];
 }
 
+/**
+ * Supported props for Buttons used inside CustomerAccountAction slots.
+ * @publicDocs
+ */
 export interface Docs_CustomerAccountAction_SlotButton
   extends Pick<
     ButtonProps,