@shopify/ui-extensions 2025.10.1 → 2025.10.3

package/src/surfaces/admin/components/Modal/examples/form-modal.jsx

@@ -0,0 +1,53 @@
+<s-stack gap="base">
+  <s-button variant="primary" commandFor="edit-modal" command="--show">
+    Edit customer
+  </s-button>
+
+  <s-modal id="edit-modal" heading="Edit customer information" size="large">
+    <s-stack gap="base">
+      <s-text-field
+        label="Customer name"
+        name="name"
+        value="Sarah Johnson"
+       />
+
+      <s-text-field
+        label="Email address"
+        name="email"
+        type="email"
+        value="sarah@example.com"
+       />
+
+      <s-text-field
+        label="Phone number"
+        name="phone"
+        value="+1 555-0123"
+       />
+
+      <s-select label="Customer group" name="group">
+        <s-option value="retail">Retail</s-option>
+        <s-option value="wholesale" selected>
+          Wholesale
+        </s-option>
+        <s-option value="vip">VIP</s-option>
+      </s-select>
+    </s-stack>
+
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      commandFor="edit-modal"
+      command="--hide"
+    >
+      Save changes
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="edit-modal"
+      command="--hide"
+    >
+      Cancel
+    </s-button>
+  </s-modal>
+</s-stack>

package/src/surfaces/admin/components/Modal/examples/modal-without-padding.html

@@ -0,0 +1,20 @@
+<s-stack gap="base">
+  <s-button commandFor="image-modal" command="--show">
+    View product image
+  </s-button>
+
+  <s-modal id="image-modal" heading="Product image" padding="none">
+    <s-box background="subdued" padding="base">
+      <s-text>Image would display here with full width</s-text>
+    </s-box>
+
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="image-modal"
+      command="--hide"
+    >
+      Close
+    </s-button>
+  </s-modal>
+</s-stack>

package/src/surfaces/admin/components/Modal/examples/modal-without-padding.jsx

@@ -0,0 +1,20 @@
+<s-stack gap="base">
+  <s-button commandFor="image-modal" command="--show">
+    View product image
+  </s-button>
+
+  <s-modal id="image-modal" heading="Product image" padding="none">
+    <s-box background="subdued" padding="base">
+      <s-text>Image would display here with full width</s-text>
+    </s-box>
+
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="image-modal"
+      command="--hide"
+    >
+      Close
+    </s-button>
+  </s-modal>
+</s-stack>

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -20,6 +20,20 @@ export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
       (event: CallbackEvent<T>): void;
     })
   | null;
+/** Used when an element does not have children. */
+export interface PreactBaseElementProps<TClass extends HTMLElement> {
+  /** Assigns a unique key to this element. */
+  key?: preact.Key;
+  /** Assigns a ref (generally from `useRef()`) to this element. */
+  ref?: preact.Ref<TClass>;
+  /** Assigns this element to a parent's slot. */
+  slot?: Lowercase<string>;
+}
+/** Used when an element has children. */
+export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
+  extends PreactBaseElementProps<TClass> {
+  children?: preact.ComponentChildren;
+}
 
 export type RequiredAlignedModalProps = Required<ModalProps$1>;
 export interface ModalProps
@@ -102,15 +116,39 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
+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.
+   *
+   * 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.
+   *
+   * @default '--auto'
+   */
+  command: Extract<
+    InteractionProps['command'],
+    '--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.
+   */
+  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.
+   */
+  interestFor: Extract<InteractionProps['interestFor'], string>;
+}
+
 /**
  * Shared symbols for overlay control functionality.
  * These symbols are used by components that implement overlay behavior
  * (like Popover, Tooltip, Modal, etc.) to communicate with the overlay control system.
  */
-/**
- * Symbol used to invoke the method for overlay commands, e.g. `--show`, `--hide`, etc.
- */
-declare const overlayCommand: unique symbol;
 /**
  * Symbol used to track the open or closed state of the overlay.
  */
@@ -120,6 +158,21 @@ declare const overlayHidden: unique symbol;
  */
 declare const overlayActivator: unique symbol;
 declare const overlayHideFrameId: unique symbol;
+export type PolyfillCommandEventInit = EventInit & {
+  source: HTMLElement | null | undefined;
+  command: PreactOverlayControlProps['command'];
+};
+export type PolyfillCommandEvent = Event & {
+  source: PolyfillCommandEventInit['source'];
+  command: PolyfillCommandEventInit['command'];
+  /** Have to use `_s_shadowSource` because `source` is retargeted to the shadow host by browsers */
+  _s_shadowSource: PolyfillCommandEventInit['source'];
+};
+declare global {
+  interface GlobalEventHandlersEventMap {
+    command: PolyfillCommandEvent;
+  }
+}
 
 declare class PreactOverlayElement extends PreactCustomElement {
   constructor(renderImpl: RenderImpl);
@@ -129,25 +182,52 @@ declare class PreactOverlayElement extends PreactCustomElement {
   [overlayActivator]: HTMLElement | null | undefined;
   /** @private */
   [overlayHideFrameId]?: number;
-  /** @private */
-  [overlayCommand](
-    command: InteractionProps['command'],
-    overlayActivatorEl: HTMLElement | null | undefined,
-  ): void;
+}
+
+export interface Context<T> {
+  readonly defaultValue: T;
+}
+/**
+ * A callback which is provided by a context requester and is called with the value satisfying the request.
+ * This callback can be called multiple times by context providers as the requested value is changed.
+ */
+export type ContextCallback<T> = (value: T) => void;
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ */
+declare class ContextRequestEvent<T> extends Event {
+  readonly context: Context<T>;
+  readonly callback: ContextCallback<T>;
+  constructor(context: Context<T>, callback: ContextCallback<T>);
+}
+declare global {
+  interface HTMLElementEventMap {
+    /**
+     * A 'context-request' event can be emitted by any element which desires
+     * a context value to be injected by an external provider.
+     */
+    'context-request': ContextRequestEvent<unknown>;
+  }
 }
 
 declare const hasOpenChildModal: unique symbol;
 
-declare const open: unique symbol;
 declare const show: unique symbol;
 declare const hide: unique symbol;
+declare const isOpen: unique symbol;
 declare const dialog: unique symbol;
+declare const dismiss: unique symbol;
+declare const focusedElement: unique symbol;
 declare const onEscape: unique symbol;
 declare const nestedModals: unique symbol;
 declare const onBackdropClick: unique symbol;
 declare const abortController: unique symbol;
 declare const onChildModalChange: unique symbol;
 declare const childrenRerenderObserver: unique symbol;
+declare const shadowDomRerenderObserver: unique symbol;
 declare class Modal extends PreactOverlayElement implements ModalProps {
   accessor accessibilityLabel: ModalProps['accessibilityLabel'];
   accessor heading: ModalProps['heading'];
@@ -162,17 +242,23 @@ declare class Modal extends PreactOverlayElement implements ModalProps {
   /** @private */
   [dialog]: HTMLDialogElement | null;
   /** @private */
+  [focusedElement]: HTMLElement | null;
+  /** @private */
   [nestedModals]: Map<Modal, boolean>;
   /** @private */
   [childrenRerenderObserver]: MutationObserver;
   /** @private */
+  [shadowDomRerenderObserver]: MutationObserver;
+  /** @private */
   [onEscape]: (event: KeyboardEvent) => void;
   /** @private */
   [onBackdropClick]: (event: MouseEvent) => void;
   /** @private */
   [onChildModalChange]: EventListenerOrEventListenerObject;
   /** @private */
-  get [open](): boolean;
+  get [isOpen](): boolean;
+  /** @private */
+  [dismiss](): void;
   /** @private */
   get [hasOpenChildModal](): boolean;
   /** @private */
@@ -196,7 +282,8 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<ModalJSXProps, 'primaryAction' | 'secondaryActions'>;
+      [tagName]: Omit<ModalJSXProps, 'primaryAction' | 'secondaryActions'> &
+        PreactBaseElementPropsWithChildren<Modal>;
     }
   }
 }
@@ -214,7 +301,7 @@ export interface ModalJSXProps
   /**
    * The secondary actions to perform.
    *
-   * Only `ButtonGroup` or `Button` with a variant of `secondary` or `auto` are allowed.
+   * Only `Button` elements with a variant of `secondary` or `auto` are allowed.
    */
   secondaryActions?: ComponentChildren;
   onHide?: ((event: CallbackEvent<typeof tagName>) => void) | null;

package/src/surfaces/admin/components/MoneyField/examples/basic-field.html

@@ -0,0 +1,6 @@
+<s-money-field
+  label="Product cost"
+  value="29.99"
+  min="0.01"
+  error="Product cost is required"
+></s-money-field>

package/src/surfaces/admin/components/MoneyField/examples/basic-field.jsx

@@ -0,0 +1,6 @@
+<s-money-field
+  label="Product cost"
+  value="29.99"
+  min="0.01"
+  error="Product cost is required"
+ />

package/src/surfaces/admin/components/MoneyField/examples/basic-usage.html

@@ -0,0 +1,7 @@
+<s-money-field
+  label="Price"
+  value="19.99"
+  min="0"
+  max="1000"
+  step="0.01"
+></s-money-field>

package/src/surfaces/admin/components/MoneyField/examples/basic-usage.jsx

@@ -0,0 +1,7 @@
+<s-money-field
+  label="Price"
+  value="19.99"
+  min={0}
+  max={1000}
+  step="0.01"
+ />

package/src/surfaces/admin/components/MoneyField/examples/currency-formatting-with-form-integration.html

@@ -0,0 +1,28 @@
+<s-stack direction="block" gap="base">
+  <s-money-field
+    label="Price"
+    value="0.00"
+    min="0.01"
+    max="99999.99"
+    step="0.01"
+    details="Customers will see this price"
+  ></s-money-field>
+
+  <s-money-field
+    label="Compare at price"
+    value=""
+    min="0"
+    max="99999.99"
+    step="0.01"
+    details="Show customers the original price when on sale"
+  ></s-money-field>
+
+  <s-money-field
+    label="Cost per item"
+    value=""
+    min="0"
+    max="99999.99"
+    step="0.01"
+    details="Customers won't see this"
+  ></s-money-field>
+</s-stack>

package/src/surfaces/admin/components/MoneyField/examples/currency-formatting-with-form-integration.jsx

@@ -0,0 +1,28 @@
+<s-stack direction="block" gap="base">
+  <s-money-field
+    label="Price"
+    value="0.00"
+    min="0.01"
+    max="99999.99"
+    step="0.01"
+    details="Customers will see this price"
+   />
+
+  <s-money-field
+    label="Compare at price"
+    value=""
+    min={0}
+    max="99999.99"
+    step="0.01"
+    details="Show customers the original price when on sale"
+   />
+
+  <s-money-field
+    label="Cost per item"
+    value=""
+    min={0}
+    max="99999.99"
+    step="0.01"
+    details="Customers won't see this"
+   />
+</s-stack>

package/src/surfaces/admin/components/MoneyField/examples/default.jsx

@@ -0,0 +1,5 @@
+<s-money-field
+  label="Regional Price"
+  placeholder="99.99"
+  details="Recommended price for the European market"
+ />

package/src/surfaces/admin/components/MoneyField/examples/validation-example.jsx

@@ -0,0 +1,24 @@
+const [amount, setAmount] = useState('150');
+const [error, setError] = useState('Value must be no more than $100');
+
+return (
+  <s-section>
+    <s-stack gap="base" inlineAlign="start">
+      <s-text-field label="Product name" />
+      <s-money-field
+        label="Discount amount"
+        value={amount}
+        min={0}
+        max={100}
+        step="0.5"
+        details="Enter discount amount between $0 and $100"
+        error={error}
+        onInput={(e) => {
+          setAmount(e.target.value);
+          const val = parseFloat(e.target.value);
+          setError(val > e.target.max ? 'Value must be no more than $100' : val < e.target.min ? 'Value must be at least $0' : '');
+        }}
+      />
+    </s-stack>
+  </s-section>
+)

package/src/surfaces/admin/components/MoneyField/examples/with-validation-limits.html

@@ -0,0 +1,8 @@
+<s-money-field
+  label="Discount amount"
+  value="5.00"
+  min="0"
+  max="100"
+  step="0.5"
+  details="Enter discount amount between $0 and $100"
+></s-money-field>

package/src/surfaces/admin/components/MoneyField/examples/with-validation-limits.jsx

@@ -0,0 +1,8 @@
+<s-money-field
+  label="Discount amount"
+  value="5.00"
+  min={0}
+  max={100}
+  step="0.5"
+  details="Enter discount amount between $0 and $100"
+/>

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

package/src/surfaces/admin/components/NumberField/examples/basic-usage.html

@@ -0,0 +1,7 @@
+<s-number-field
+  label="Order quantity"
+  value="5"
+  min="1"
+  max="999"
+  step="1"
+></s-number-field>

package/src/surfaces/admin/components/NumberField/examples/basic-usage.jsx

@@ -0,0 +1,7 @@
+<s-number-field
+  label="Order quantity"
+  value={5}
+  min={1}
+  max={999}
+  step={1}
+ />

package/src/surfaces/admin/components/NumberField/examples/default.html

@@ -1,7 +1,7 @@
 <s-number-field
   label="Quantity"
   details="Number of items in stock"
-  placeholder="10"
+  placeholder="0"
   step="5"
   min="0"
   max="100"

package/src/surfaces/admin/components/NumberField/examples/default.jsx

@@ -0,0 +1,8 @@
+<s-number-field
+  label="Quantity"
+  details="Number of items in stock"
+  placeholder={0}
+  step={5}
+  min={0}
+  max={100}
+/>

package/src/surfaces/admin/components/NumberField/examples/multiple-examples.html

@@ -0,0 +1,29 @@
+<s-stack gap="base">
+  <s-number-field
+    label="Inventory count"
+    value="150"
+    min="0"
+    step="1"
+    inputMode="numeric"
+    details="Current stock available for sale"
+  ></s-number-field>
+
+  <s-number-field
+    label="Discount percentage"
+    value="15"
+    suffix="%"
+    min="0"
+    max="100"
+    step="0.1"
+    inputMode="decimal"
+  ></s-number-field>
+
+  <s-number-field
+    label="Shipping weight"
+    value="2.5"
+    suffix="kg"
+    min="0.1"
+    step="0.1"
+    inputMode="decimal"
+  ></s-number-field>
+</s-stack>

package/src/surfaces/admin/components/NumberField/examples/multiple-examples.jsx

@@ -0,0 +1,29 @@
+<s-stack gap="base">
+  <s-number-field
+    label="Inventory count"
+    value={150}
+    min={0}
+    step={1}
+    inputMode="numeric"
+    details="Current stock available for sale"
+   />
+
+  <s-number-field
+    label="Discount percentage"
+    value={15}
+    suffix="%"
+    min={0}
+    max={100}
+    step="0.1"
+    inputMode="decimal"
+   />
+
+  <s-number-field
+    label="Shipping weight"
+    value={2.5}
+    suffix="kg"
+    min={0.1}
+    step={0.1}
+    inputMode="decimal"
+   />
+</s-stack>

package/src/surfaces/admin/components/NumberField/examples/with-prefix-and-suffix.html

@@ -0,0 +1,9 @@
+<s-number-field
+  label="Product price"
+  value="29.99"
+  prefix="$"
+  suffix="CAD"
+  inputMode="decimal"
+  step="0.01"
+  min="0"
+></s-number-field>

package/src/surfaces/admin/components/NumberField/examples/with-prefix-and-suffix.jsx

@@ -0,0 +1,9 @@
+<s-number-field
+  label="Product price"
+  value={29.99}
+  prefix="$"
+  suffix="CAD"
+  inputMode="decimal"
+  step={0.01}
+  min={0}
+ />

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

package/src/surfaces/admin/components/OrderedList/examples/basic-usage.html

@@ -0,0 +1,5 @@
+<s-ordered-list>
+  <s-list-item>Add products to your catalog</s-list-item>
+  <s-list-item>Set up payment methods</s-list-item>
+  <s-list-item>Configure shipping zones</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/basic-usage.jsx

@@ -0,0 +1,5 @@
+<s-ordered-list>
+  <s-list-item>Add products to your catalog</s-list-item>
+  <s-list-item>Set up payment methods</s-list-item>
+  <s-list-item>Configure shipping zones</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/default.jsx

@@ -0,0 +1,5 @@
+<s-ordered-list>
+  <s-list-item>Red shirt</s-list-item>
+  <s-list-item>Green shirt</s-list-item>
+  <s-list-item>Blue shirt</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/fulfillment-process.html

@@ -0,0 +1,18 @@
+<s-ordered-list>
+  <s-list-item>
+    Process payment
+    <s-ordered-list>
+      <s-list-item>Verify card details</s-list-item>
+      <s-list-item>Apply discount codes</s-list-item>
+      <s-list-item>Calculate taxes</s-list-item>
+    </s-ordered-list>
+  </s-list-item>
+  <s-list-item>
+    Prepare shipment
+    <s-ordered-list>
+      <s-list-item>Print shipping label</s-list-item>
+      <s-list-item>Pack items securely</s-list-item>
+    </s-ordered-list>
+  </s-list-item>
+  <s-list-item>Update customer with tracking info</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/fulfillment-process.jsx

@@ -0,0 +1,18 @@
+<s-ordered-list>
+  <s-list-item>
+    Process payment
+    <s-ordered-list>
+      <s-list-item>Verify card details</s-list-item>
+      <s-list-item>Apply discount codes</s-list-item>
+      <s-list-item>Calculate taxes</s-list-item>
+    </s-ordered-list>
+  </s-list-item>
+  <s-list-item>
+    Prepare shipment
+    <s-ordered-list>
+      <s-list-item>Print shipping label</s-list-item>
+      <s-list-item>Pack items securely</s-list-item>
+    </s-ordered-list>
+  </s-list-item>
+  <s-list-item>Update customer with tracking info</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/order-processing-steps.html

@@ -0,0 +1,8 @@
+<s-ordered-list>
+  <s-list-item>Review order details and customer information</s-list-item>
+  <s-list-item>Verify payment and billing address</s-list-item>
+  <s-list-item>Check inventory availability for all items</s-list-item>
+  <s-list-item>Generate fulfillment labels and packing slip</s-list-item>
+  <s-list-item>Package items and update tracking information</s-list-item>
+  <s-list-item>Send shipment confirmation to customer</s-list-item>
+</s-ordered-list>

package/src/surfaces/admin/components/OrderedList/examples/order-processing-steps.jsx

@@ -0,0 +1,8 @@
+<s-ordered-list>
+  <s-list-item>Review order details and customer information</s-list-item>
+  <s-list-item>Verify payment and billing address</s-list-item>
+  <s-list-item>Check inventory availability for all items</s-list-item>
+  <s-list-item>Generate fulfillment labels and packing slip</s-list-item>
+  <s-list-item>Package items and update tracking information</s-list-item>
+  <s-list-item>Send shipment confirmation to customer</s-list-item>
+</s-ordered-list>