@shopify/ui-extensions 2025.10.13 → 2025.10.14

package/src/surfaces/admin/components/Button.d.ts

@@ -14,29 +14,54 @@ import type {
   InteractionProps,
 } from './shared.d.ts';
 
+/**
+ * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements.
+ */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  /**
+   * The element that the event listener is attached to, strongly typed based on the element's tag name.
+   */
   currentTarget: HTMLElementTagNameMap[T];
 };
+/**
+ * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type.
+ */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
       (event: CallbackEvent<T>): void;
     })
   | null;
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements without children. Provides `key`, `ref`, and `slot` properties for element identification, DOM access, and slot-based positioning.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for the element when used in lists. Preact uses keys for efficient rendering and reconciliation when lists change.
+   */
   key?: preact.Key;
-  /** Assigns a ref (generally from `useRef()`) to this element. */
+  /**
+   * A reference to the underlying DOM element. Typically created with `useRef()` to access the element directly for imperative operations like focusing or measuring.
+   */
   ref?: preact.Ref<TClass>;
-  /** Assigns this element to a parent's slot. */
+  /**
+   * The named slot this element should be placed in when used within a web component. Learn more about [using slots](/docs/api/app-ui/using-web-components#slots).
+   */
   slot?: Lowercase<string>;
 }
-/** Used when an element has children. */
+/**
+ * The base properties for Preact elements with children. Extends `PreactBaseElementProps` with the ability to render child elements.
+ */
 export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
   extends PreactBaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: preact.ComponentChildren;
 }
 
+/**
+ * The configuration for icons used within Button components. Defines the visual appearance, size, and semantic meaning of icons displayed in buttons.
+ */
 export interface IconProps
   extends Pick<
     IconProps$1,
@@ -46,20 +71,52 @@ export interface IconProps
    * Specifies the type of icon that will be displayed.
    */
   type: '' | IconType | 'empty';
+  /**
+   * Determines the color used for the icon based on semantic meaning. Available options:
+   * - `'auto'` - Lets the system automatically choose the appropriate tone based on context.
+   * - `'neutral'` - Gray styling for general information.
+   * - `'info'` - Blue styling for informational content.
+   * - `'success'` - Green styling for positive states.
+   * - `'caution'` - Yellow styling for situations that need attention.
+   * - `'warning'` - Orange styling for important notices.
+   * - `'critical'` - Red styling for errors and urgent issues.
+   *
+   * @default 'auto'
+   */
   tone: Extract<
     IconProps$1['tone'],
     'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical'
   >;
+  /**
+   * Controls the visual prominence of the icon. Available options:
+   * - `'base'` - Standard color intensity for normal emphasis.
+   * - `'subdued'` - Reduced color intensity for less emphasis.
+   *
+   * @default 'base'
+   */
   color: Extract<IconProps$1['color'], 'base' | 'subdued'>;
+  /**
+   * Determines the size of the icon. Available options:
+   * - `'small'` - Smaller icon size for compact layouts.
+   * - `'base'` - Standard icon size for most use cases.
+   *
+   * @default 'base'
+   */
   size: Extract<IconProps$1['size'], 'small' | 'base'>;
 }
 
+/**
+ * The button-specific properties extracted from the base button props type, used internally for type safety.
+ */
 export type ButtonOnlyProps = Extract<
   ButtonProps$1,
   {
     type?: unknown;
   }
 >;
+/**
+ * The base required properties for the button component, including all essential button configuration options. This type ensures all button properties have default values.
+ */
 export type ButtonBaseProps = Required<
   Pick<
     ButtonOnlyProps,
@@ -79,25 +136,71 @@ export type ButtonBaseProps = Required<
     | 'download'
   >
 >;
+/**
+ * The properties for the button component. Buttons trigger actions or navigation when clicked, with customizable visual styles, states, and optional icons.
+ */
 export interface ButtonProps extends ButtonBaseProps {
+  /**
+   * Determines the visual appearance and semantic meaning of the button. Buttons rely on the tone system for semantic meaning, so using custom styling might not clearly convey intent to merchants. Available options:
+   * - `'auto'` - Lets the system automatically choose the appropriate tone based on context.
+   * - `'neutral'` - Standard styling for general actions without specific semantic meaning.
+   * - `'critical'` - Red styling for destructive actions that can't be undone, such as deleting data.
+   *
+   * @default 'auto'
+   */
   tone: Extract<ButtonProps$1['tone'], 'neutral' | 'critical' | 'auto'>;
+  /**
+   * The icon to display inside the button. Accepts any valid icon type or an empty string to display no icon.
+   *
+   * @default ''
+   */
   icon: IconProps['type'];
 }
 
+/**
+ * The CSS styles as a string, used for styling web components within their shadow DOM.
+ */
 export type Styles = string;
+/**
+ * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM.
+ */
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
+  /**
+   * The render function that returns Preact/JSX elements to display in the component's shadow root.
+   */
   ShadowRoot: (element: any) => ComponentChildren;
+  /**
+   * The optional CSS styles to inject into the component's shadow DOM.
+   */
   styles?: Styles;
 };
+/**
+ * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed.
+ */
 export interface ActivationEventEsque {
+  /**
+   * Whether the Shift key was pressed during the activation event.
+   */
   shiftKey: boolean;
+  /**
+   * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event.
+   */
   metaKey: boolean;
+  /**
+   * Whether the Control key was pressed during the activation event.
+   */
   ctrlKey: boolean;
+  /**
+   * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click).
+   */
   button: number;
 }
+/**
+ * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab.
    */
   sourceEvent?: ActivationEventEsque;
 }
@@ -144,17 +247,19 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
+/**
+ * The properties for controlling overlay interactions via commands. These properties enable buttons to control other components like modals, popovers, and dialogs using declarative commands.
+ */
 export interface PreactOverlayControlProps
   extends Pick<InteractionProps, 'commandFor' | 'interestFor'> {
   /**
-   * Sets the action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this clickable is activated.
+   * Sets the action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this button is activated. Available options:
+   * - `'--auto'`: Performs the default action appropriate for the target component.
+   * - `'--show'`: Displays the target component if it's currently hidden.
+   * - `'--hide'`: Conceals the target component from view.
+   * - `'--toggle'`: Alternates the target component between visible and hidden states.
    *
-   * See the documentation of particular components for the actions they support.
-   *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
+   * The supported actions vary by target component type.
    *
    * @default '--auto'
    */
@@ -163,32 +268,77 @@ export interface PreactOverlayControlProps
     '--show' | '--hide' | '--toggle' | '--auto'
   >;
   /**
-   * Sets the element the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this clickable is activated.
+   * Sets the element ID that the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this button is activated. References another component by its `id` attribute.
    */
   commandFor: Extract<InteractionProps['commandFor'], string>;
   /**
-   * Sets the element the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this clickable is activated.
+   * Sets the element ID that the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this button is activated. Used for interest-based interactions with other components.
    */
   interestFor: Extract<InteractionProps['interestFor'], string>;
 }
 
+/**
+ * The base class for the button component, combining Preact custom element functionality with overlay control capabilities.
+ */
 declare const Button_base: (abstract new (
   args_0: RenderImpl,
 ) => PreactCustomElement & PreactOverlayControlProps) &
   Pick<typeof PreactCustomElement, 'prototype' | 'observedAttributes'>;
+/**
+ * The button custom element class that renders interactive buttons in the Shopify admin interface. This component triggers actions or navigation when clicked, with customizable visual styles, states, and optional icons.
+ */
 declare class Button extends Button_base implements ButtonProps {
+  /**
+   * Whether the button is disabled, preventing any interaction. When `true`, the button appears visually disabled and doesn't respond to user clicks.
+   */
   accessor disabled: ButtonProps['disabled'];
+  /**
+   * The icon to display inside the button. Accepts any valid icon type from the admin icon set, or an empty string to display no icon.
+   */
   accessor icon: ButtonProps['icon'];
+  /**
+   * Whether the button is in a loading state. When `true`, displays a loading indicator and prevents interaction to show that an action is in progress.
+   */
   accessor loading: ButtonProps['loading'];
+  /**
+   * The visual style variant of the button that determines its emphasis. Available options: `'primary'`, `'secondary'`, `'tertiary'`, or `'plain'`.
+   */
   accessor variant: ButtonProps['variant'];
+  /**
+   * The tone that determines the button's visual appearance and semantic meaning. Available options: `'auto'`, `'neutral'`, or `'critical'`.
+   */
   accessor tone: ButtonProps['tone'];
+  /**
+   * Specifies where to open the linked document when the button acts as a link. Available options: `''`, `'_blank'`, `'_self'`, `'_parent'`, or `'_top'`.
+   */
   accessor target: ButtonProps['target'];
+  /**
+   * A URL that the button should navigate to when clicked. When provided, the button behaves as a link.
+   */
   accessor href: ButtonProps['href'];
+  /**
+   * Prompts the user to save the linked URL as a file with the specified filename. Only works when `href` is provided.
+   */
   accessor download: ButtonProps['download'];
+  /**
+   * A callback that's invoked when the button is clicked. Receives the click event as an argument.
+   */
   accessor onclick: CallbackEventListener<typeof tagName> | null;
+  /**
+   * A callback that's invoked when the button loses focus. Receives the blur event as an argument.
+   */
   accessor onblur: CallbackEventListener<typeof tagName> | null;
+  /**
+   * A callback that's invoked when the button receives focus. Receives the focus event as an argument.
+   */
   accessor onfocus: CallbackEventListener<typeof tagName> | null;
+  /**
+   * The button's behavior in forms. Available options: `'button'`, `'submit'`, or `'reset'`.
+   */
   accessor type: ButtonProps['type'];
+  /**
+   * A text description of the button's purpose for screen readers. This is essential for accessibility when the button doesn't have visible text.
+   */
   accessor accessibilityLabel: ButtonProps['accessibilityLabel'];
   constructor();
 }
@@ -206,16 +356,94 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-button';
+/**
+ * The JSX props for the button component. These properties extend `ButtonProps` with event callbacks and additional options for rendering buttons in JSX.
+ */
 export interface ButtonJSXProps
   extends Partial<ButtonProps>,
     Pick<ButtonProps$1, 'id' | 'children'> {
   /**
-   * The content of the Button.
+   * The text label or content to display inside the button. Can be plain text or other components.
    */
   children?: ComponentChildren;
+  /**
+   * Callback function that's invoked when the button is clicked. Receives the click event as an argument.
+   */
   onClick?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback function that's invoked when the button receives focus. Receives the focus event as an argument.
+   */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback function that's invoked when the button loses focus. Receives the blur event as an argument.
+   */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
+   *
+   * @default ''
+   */
+  accessibilityLabel?: string;
+  /**
+   * Prevents the button from being clicked when set to `true`. The button appears visually disabled and doesn't respond to user interaction.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Displays a loading indicator and prevents interaction when set to `true`. Use this to show that an action triggered by the button is in progress.
+   *
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * Determines the visual style and emphasis of the button. Available options:
+   * - `'primary'` - Highest emphasis for the main action on a screen.
+   * - `'secondary'` - Medium emphasis for secondary actions.
+   * - `'tertiary'` - Lowest emphasis for less important actions.
+   * - `'plain'` - Text-only appearance for subtle actions that don't need visual weight.
+   *
+   * @default 'secondary'
+   */
+  variant?: ButtonProps['variant'];
+  /**
+   * Specifies where to open the linked document when the button acts as a link (when `href` is provided). Available options:
+   * - `''` - Opens in the same frame (default behavior).
+   * - `'_blank'` - Opens in a new window or tab.
+   * - `'_self'` - Opens in the same frame (explicit version of default).
+   * - `'_parent'` - Opens in the parent frame.
+   * - `'_top'` - Opens in the full body of the window.
+   *
+   * @default ''
+   */
+  target?: ButtonProps['target'];
+  /**
+   * A URL that the button should navigate to when clicked. When provided, the button behaves as a link.
+   *
+   * @default ''
+   */
+  href?: ButtonProps['href'];
+  /**
+   * Prompts the user to save the linked URL as a file with the specified filename. Only works when `href` is provided.
+   *
+   * @default ''
+   */
+  download?: ButtonProps['download'];
+  /**
+   * Specifies the button's behavior in forms. Available options:
+   * - `'button'` - A standard button with no default behavior.
+   * - `'submit'` - Submits the form data to the server.
+   * - `'reset'` - Resets all form controls to their initial values.
+   *
+   * @default 'button'
+   */
+  type?: ButtonProps['type'];
+  /**
+   * The language of the button's content, specified as a BCP 47 language tag (such as `'en'` or `'fr'`). This helps assistive technologies pronounce content correctly.
+   *
+   * @default ''
+   */
+  lang?: ButtonProps['lang'];
 }
 
 export {Button};

package/src/surfaces/admin/components/ButtonGroup.d.ts

@@ -8,23 +8,56 @@
 /// <reference lib="DOM" />
 import type {ComponentChildren, ButtonGroupProps$1} from './shared.d.ts';
 
+/**
+ * Properties for rendering a button group that arranges multiple buttons together with consistent spacing and semantic grouping.
+ */
 export interface ButtonGroupProps
   extends Required<Pick<ButtonGroupProps$1, 'gap' | 'accessibilityLabel'>> {}
 
+/**
+ * CSS styles that will be applied to the component's shadow DOM.
+ */
 export type Styles = string;
+/**
+ * Configuration for rendering a custom element with Preact and shadow DOM.
+ */
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
+  /**
+   * A function that renders the component's content inside the shadow root.
+   */
   ShadowRoot: (element: any) => ComponentChildren;
+  /**
+   * CSS styles that will be applied to the shadow DOM.
+   */
   styles?: Styles;
 };
+/**
+ * Information about modifier keys and mouse buttons that were active during an interaction.
+ */
 export interface ActivationEventEsque {
+  /**
+   * Whether the Shift key was held down during the interaction.
+   */
   shiftKey: boolean;
+  /**
+   * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction.
+   */
   metaKey: boolean;
+  /**
+   * Whether the Control key was held down during the interaction.
+   */
   ctrlKey: boolean;
+  /**
+   * The mouse button that was pressed during the interaction.
+   */
   button: number;
 }
+/**
+ * Options for influencing how a programmatic click behaves.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
    */
   sourceEvent?: ActivationEventEsque;
 }
@@ -70,28 +103,75 @@ declare abstract class PreactCustomElement extends BaseClass {
    */
   click({sourceEvent}?: ClickOptions): void;
 }
+export interface ClickOptions {
+  /**
+   * The event you want to influence the synthetic click.
+   */
+  sourceEvent?: ActivationEventEsque;
+}
+/**
+ * Base class for creating custom elements with Preact.
+ * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
+ * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
+ */
+declare const BaseClass: typeof globalThis.HTMLElement;
+declare abstract class PreactCustomElement extends BaseClass {
+  /** @private */
+  static get observedAttributes(): string[];
+  constructor({
+    styles,
+    ShadowRoot: renderFunction,
+    delegatesFocus,
+    ...options
+  }: RenderImpl);
+}
 
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists 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.
+   */
   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 shadow DOM or slot-based composition patterns.
+   */
   slot?: Lowercase<string>;
 }
-/** Used when an element has children. */
+
+/**
+ * The base properties for Preact elements that have children, extending the base element properties to include child content.
+ */
 export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
   extends PreactBaseElementProps<TClass> {
+  /**
+   * The child elements or content that will be rendered inside this element.
+   */
   children?: preact.ComponentChildren;
 }
 
+/**
+ * A button group that arranges multiple buttons together with consistent spacing and semantic grouping for related actions.
+ */
 declare class ButtonGroup
   extends PreactCustomElement
   implements ButtonGroupProps
 {
+  /**
+   * The amount of spacing between buttons in the group, affecting the visual separation of actions.
+   */
   accessor gap: ButtonGroupProps['gap'];
+
+  /**
+   * A label that's only visible to screen readers, describing the purpose of this group of buttons.
+   */
   accessor accessibilityLabel: ButtonGroupProps['accessibilityLabel'];
+
   constructor();
 }
 declare global {
@@ -112,21 +192,26 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-button-group';
+
+/**
+ * Properties for using the button group component in JSX with React-style props.
+ */
 export interface ButtonGroupJSXProps
   extends Partial<ButtonGroupProps>,
     Pick<ButtonGroupProps$1, 'id' | 'children'> {
   /**
-   * The content of the ButtonGroup.
+   * The buttons that should be grouped together, provided as Button components.
    */
   children?: ComponentChildren;
   /**
-   * The primary action button for the group.
-   * Accepts a single Button element with a `variant` of `primary`.
-   * Cannot be used when gap="none".
+   * A single primary action button that's visually emphasized as the most important action in the group.
+   *
+   * Accepts a single Button element with a `variant` of `primary`. Can't be used when `gap` is set to `none`.
    */
   primaryAction?: ComponentChildren;
   /**
-   * Secondary action buttons for the group.
+   * One or more secondary action buttons that provide alternative or less prominent actions.
+   *
    * Accepts Button elements with a `variant` of `secondary` or `auto`.
    */
   secondaryActions?: ComponentChildren;

package/src/surfaces/admin/components/Checkbox/examples/indeterminate-state.html

@@ -0,0 +1,10 @@
+<s-stack gap="small">
+  <s-checkbox
+    label="Select all items"
+    indeterminate
+  ></s-checkbox>
+  <s-divider></s-divider>
+  <s-checkbox label="Item 1" checked></s-checkbox>
+  <s-checkbox label="Item 2"></s-checkbox>
+  <s-checkbox label="Item 3"></s-checkbox>
+</s-stack>

package/src/surfaces/admin/components/Checkbox/examples/validation-example.html

@@ -0,0 +1,9 @@
+<s-section>
+  <s-stack gap="base" justifyContent="start">
+    <s-text-field label="Name"></s-text-field>
+    <s-checkbox
+      label="I agree to the terms"
+      error="You must accept the terms to continue"
+    ></s-checkbox>
+  </s-stack>
+</s-section>