@shopify/ui-extensions 2025.10.2 → 2025.10.4

package/src/surfaces/admin/components/Link/examples/links-with-auto-tone.jsx

@@ -0,0 +1,3 @@
+<s-paragraph>
+  You have 15 pending orders to fulfill. <s-link href="javascript:void(0)">Review unfulfilled orders</s-link> to keep customers happy.
+</s-paragraph>

package/src/surfaces/admin/components/Link/examples/links-with-different-tones.html

@@ -0,0 +1,25 @@
+<s-stack gap="base">
+  <s-paragraph>
+    Default tone: <s-link>View orders</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="success">
+    Neutral tone: <s-link>Inventory help</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="critical">
+    Critical tone: <s-link>Close store</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="warning">
+    Warning tone: <s-link>Update billing info</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="info">
+    Info tone: <s-link>Learn more about reports</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="caution">
+    Subdued tone: <s-link>View archived products</s-link>
+  </s-paragraph>
+</s-stack>

package/src/surfaces/admin/components/Link/examples/links-with-different-tones.jsx

@@ -0,0 +1,25 @@
+<s-stack gap="base">
+  <s-paragraph>
+    Default tone: <s-link>View orders</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="success">
+    Success tone: <s-link>Inventory help</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="critical">
+    Critical tone: <s-link>Close store</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="warning">
+    Warning tone: <s-link>Update billing info</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="info">
+    Info tone: <s-link>Learn more about reports</s-link>
+  </s-paragraph>
+
+  <s-paragraph tone="caution">
+    Caution tone: <s-link>View archived products</s-link>
+  </s-paragraph>
+</s-stack>

package/src/surfaces/admin/components/Link/examples/links-with-language-attribute.html

@@ -0,0 +1,3 @@
+<s-paragraph>
+  Voir en français: <s-link lang="fr">Gérer les produits</s-link>
+</s-paragraph>

package/src/surfaces/admin/components/Link/examples/links-with-language-attribute.jsx

@@ -0,0 +1,3 @@
+<s-paragraph>
+  Voir en français: <s-link lang="fr">Gérer les produits</s-link>
+</s-paragraph>

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.25.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -172,7 +172,11 @@ declare module 'preact' {
 declare const tagName = 's-link';
 export interface LinkJSXProps
   extends Partial<LinkProps>,
-    Pick<LinkProps$1, 'id' | 'lang'> {
+    Pick<LinkProps$1, 'id' | 'lang' | 'children'> {
+  /**
+   * The content of the Link.
+   */
+  children?: ComponentChildren;
   onClick?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.25.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -104,7 +104,12 @@ declare module 'preact' {
 declare const tagName = 's-list-item';
 export interface ListItemJSXProps
   extends Partial<ListItemProps>,
-    Pick<ListItemProps$1, 'id'> {}
+    Pick<ListItemProps$1, 'id' | 'children'> {
+  /**
+   * The content of the ListItem.
+   */
+  children?: ComponentChildren;
+}
 
 export {ListItem};
 export type {ListItemJSXProps};

package/src/surfaces/admin/components/Menu/examples/basic-menu.html

@@ -0,0 +1,7 @@
+<s-button commandFor="product-menu">Product actions</s-button>
+
+<s-menu id="product-menu" accessibilityLabel="Product actions">
+  <s-button icon="edit">Edit product</s-button>
+  <s-button icon="duplicate">Duplicate product</s-button>
+  <s-button icon="archive">Archive product</s-button>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/basic-menu.jsx

@@ -0,0 +1,9 @@
+<>
+  <s-button commandFor="product-menu">Product actions</s-button>
+
+  <s-menu id="product-menu" accessibilityLabel="Product actions">
+    <s-button icon="edit">Edit product</s-button>
+    <s-button icon="duplicate">Duplicate product</s-button>
+    <s-button icon="archive">Archive product</s-button>
+  </s-menu>
+</>

package/src/surfaces/admin/components/Menu/examples/customer-actions-menu.html

@@ -0,0 +1,14 @@
+<s-button commandFor="customer-menu">Edit customer</s-button>
+
+<s-menu id="customer-menu" accessibilityLabel="Customer actions">
+  <s-section heading="Customer management">
+    <s-button icon="edit">Edit customer</s-button>
+    <s-button icon="email">Send email</s-button>
+    <s-button icon="order">View orders</s-button>
+  </s-section>
+  <s-section heading="Account actions">
+    <s-button icon="reset">Reset password</s-button>
+    <s-button icon="lock">Disable account</s-button>
+  </s-section>
+  <s-button tone="critical" icon="delete">Delete customer</s-button>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/customer-actions-menu.jsx

@@ -0,0 +1,18 @@
+<>
+  <s-button commandFor="customer-menu">Edit customer</s-button>
+
+  <s-menu id="customer-menu" accessibilityLabel="Customer actions">
+    <s-section heading="Customer management">
+      <s-button icon="edit">Edit customer</s-button>
+      <s-button icon="email">Send email</s-button>
+      <s-button icon="order">View orders</s-button>
+    </s-section>
+    <s-section heading="Account actions">
+      <s-button icon="reset">Reset password</s-button>
+      <s-button icon="lock">Disable account</s-button>
+    </s-section>
+    <s-button tone="critical" icon="delete">
+      Delete customer
+    </s-button>
+  </s-menu>
+</>

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

@@ -0,0 +1,11 @@
+<>
+  <s-button commandFor="customer-menu">Edit customer</s-button>
+
+  <s-menu id="customer-menu" accessibilityLabel="Customer actions">
+    <s-button icon="merge">Merge customer</s-button>
+    <s-button icon="incoming">Request customer data</s-button>
+    <s-button icon="delete" tone="critical">
+      Delete customer
+    </s-button>
+  </s-menu>
+</>

package/src/surfaces/admin/components/Menu/examples/menu-with-icons.html

@@ -0,0 +1,8 @@
+<s-button icon="caret-down" commandFor="actions-menu">More actions</s-button>
+
+<s-menu id="actions-menu" accessibilityLabel="Product actions menu">
+  <s-button icon="edit">Edit product</s-button>
+  <s-button icon="duplicate">Duplicate product</s-button>
+  <s-button icon="archive">Archive product</s-button>
+  <s-button icon="delete" tone="critical">Delete product</s-button>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/menu-with-icons.jsx

@@ -0,0 +1,14 @@
+<>
+  <s-button icon="caret-down" commandFor="actions-menu">
+    More actions
+  </s-button>
+
+  <s-menu id="actions-menu" accessibilityLabel="Product actions menu">
+    <s-button icon="edit">Edit product</s-button>
+    <s-button icon="duplicate">Duplicate product</s-button>
+    <s-button icon="archive">Archive product</s-button>
+    <s-button icon="delete" tone="critical">
+      Delete product
+    </s-button>
+  </s-menu>
+</>

package/src/surfaces/admin/components/Menu/examples/menu-with-links-and-disabled-items.html

@@ -0,0 +1,9 @@
+<s-button commandFor="mixed-menu">Options</s-button>
+
+<s-menu id="mixed-menu" accessibilityLabel="Mixed menu options">
+  <s-button href="javascript:void(0)" target="_blank">
+    View product page
+  </s-button>
+  <s-button disabled>Unavailable action</s-button>
+  <s-button download href="javascript:void(0)">Download report</s-button>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/menu-with-links-and-disabled-items.jsx

@@ -0,0 +1,13 @@
+<>
+  <s-button commandFor="mixed-menu">Options</s-button>
+
+  <s-menu id="mixed-menu" accessibilityLabel="Mixed menu options">
+    <s-button href="javascript:void(0)" target="_blank">
+      View product page
+    </s-button>
+    <s-button disabled>Unavailable action</s-button>
+    <s-button download="sales-report.csv" href="/reports/sales-report.csv">
+      Download report
+    </s-button>
+  </s-menu>
+</>

package/src/surfaces/admin/components/Menu/examples/menu-with-sections.html

@@ -0,0 +1,13 @@
+<s-button commandFor="organized-menu">Bulk actions</s-button>
+
+<s-menu id="organized-menu" accessibilityLabel="Organized menu">
+  <s-section heading="Product actions">
+    <s-button icon="edit">Edit selected</s-button>
+    <s-button icon="duplicate">Duplicate selected</s-button>
+    <s-button icon="archive">Archive selected</s-button>
+  </s-section>
+  <s-section heading="Export options">
+    <s-button icon="export">Export as CSV</s-button>
+    <s-button icon="print">Print barcodes</s-button>
+  </s-section>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/menu-with-sections.jsx

@@ -0,0 +1,15 @@
+<>
+  <s-button commandFor="organized-menu">Bulk actions</s-button>
+
+  <s-menu id="organized-menu" accessibilityLabel="Organized menu">
+    <s-section heading="Product actions">
+      <s-button icon="edit">Edit selected</s-button>
+      <s-button icon="duplicate">Duplicate selected</s-button>
+      <s-button icon="archive">Archive selected</s-button>
+    </s-section>
+    <s-section heading="Export options">
+      <s-button icon="export">Export as CSV</s-button>
+      <s-button icon="print">Print barcodes</s-button>
+    </s-section>
+  </s-menu>
+</>

package/src/surfaces/admin/components/Menu/examples/settings-menu.html

@@ -0,0 +1,15 @@
+<s-button icon="settings" commandFor="admin-settings">Settings</s-button>
+
+<s-menu id="admin-settings" accessibilityLabel="Settings menu">
+  <s-section heading="Account">
+    <s-button icon="profile">Profile settings</s-button>
+    <s-button icon="lock">Security</s-button>
+    <s-button>Billing information</s-button>
+  </s-section>
+  <s-section heading="Store">
+    <s-button icon="store">Store settings</s-button>
+    <s-button>Payment providers</s-button>
+    <s-button icon="delivery">Shipping rates</s-button>
+  </s-section>
+  <s-button href="javascript:void(0)" icon="person-exit">Sign out</s-button>
+</s-menu>

package/src/surfaces/admin/components/Menu/examples/settings-menu.jsx

@@ -0,0 +1,19 @@
+<>
+  <s-button icon="settings" commandFor="admin-settings">
+    Settings
+  </s-button>
+
+  <s-menu id="admin-settings" accessibilityLabel="Settings menu">
+    <s-section heading="Account">
+      <s-button icon="profile">Profile settings</s-button>
+      <s-button icon="lock">Security</s-button>
+      <s-button>Billing information</s-button>
+    </s-section>
+    <s-section heading="Store">
+      <s-button icon="store">Store settings</s-button>
+      <s-button>Payment providers</s-button>
+      <s-button icon="delivery">Shipping rates</s-button>
+    </s-section>
+    <s-button href="javascript:void(0)" icon="person-exit">Sign out</s-button>
+  </s-menu>
+</>

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.25.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -15,6 +15,21 @@ import type {
 export interface MenuProps
   extends Required<Pick<MenuProps$1, 'id' | 'accessibilityLabel'>> {}
 
+/** 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 Styles = string;
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
   ShadowRoot: (element: any) => ComponentChildren;
@@ -75,15 +90,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.
  */
@@ -93,6 +132,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);
@@ -102,11 +156,6 @@ declare class PreactOverlayElement extends PreactCustomElement {
   [overlayActivator]: HTMLElement | null | undefined;
   /** @private */
   [overlayHideFrameId]?: number;
-  /** @private */
-  [overlayCommand](
-    command: InteractionProps['command'],
-    overlayActivatorEl: HTMLElement | null | undefined,
-  ): void;
 }
 
 declare class Menu extends PreactOverlayElement implements MenuProps {
@@ -125,7 +174,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: MenuJSXProps;
+      [tagName]: MenuJSXProps & PreactBaseElementPropsWithChildren<Menu>;
     }
   }
 }
@@ -133,7 +182,14 @@ declare module 'preact' {
 declare const tagName = 's-menu';
 export interface MenuJSXProps
   extends Partial<MenuProps>,
-    Pick<MenuProps$1, 'id'> {}
+    Pick<MenuProps$1, 'id' | 'children'> {
+  /**
+   * The Menu items.
+   *
+   * Only accepts `Button` and `Section` components.
+   */
+  children?: ComponentChildren;
+}
 
 export {Menu};
 export type {MenuJSXProps};

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

@@ -0,0 +1,9 @@
+<s-button commandFor="info-modal" command="--show">Show product info</s-button>
+
+<s-modal id="info-modal" heading="Product information">
+  <s-text>This product is currently out of stock and cannot be ordered.</s-text>
+
+  <s-button slot="secondary-actions" commandFor="info-modal" command="--hide">
+    Close
+  </s-button>
+</s-modal>

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

@@ -0,0 +1,15 @@
+<>
+  <s-button commandFor="info-modal" command="--show">
+    Show product info
+  </s-button>
+
+  <s-modal id="info-modal" heading="Product information">
+    <s-text>
+      This product is currently out of stock and cannot be ordered.
+    </s-text>
+
+    <s-button slot="secondary-actions" commandFor="info-modal" command="--hide">
+      Close
+    </s-button>
+  </s-modal>
+</>

package/src/surfaces/admin/components/Modal/examples/confirmation-modal-with-actions.html

@@ -0,0 +1,30 @@
+<s-stack gap="base">
+  <s-button tone="critical" commandFor="delete-modal" command="--show">
+    Delete product
+  </s-button>
+
+  <s-modal id="delete-modal" heading="Delete product?">
+    <s-stack gap="base">
+      <s-text>Are you sure you want to delete "Winter jacket"?</s-text>
+      <s-text tone="caution">This action cannot be undone.</s-text>
+    </s-stack>
+
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      tone="critical"
+      commandFor="delete-modal"
+      command="--hide"
+    >
+      Delete product
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="delete-modal"
+      command="--hide"
+    >
+      Cancel
+    </s-button>
+  </s-modal>
+</s-stack>

package/src/surfaces/admin/components/Modal/examples/confirmation-modal-with-actions.jsx

@@ -0,0 +1,30 @@
+<s-stack gap="base">
+  <s-button tone="critical" commandFor="delete-modal" command="--show">
+    Delete product
+  </s-button>
+
+  <s-modal id="delete-modal" heading="Delete product?">
+    <s-stack gap="base">
+      <s-text>Are you sure you want to delete "Winter jacket"?</s-text>
+      <s-text tone="caution">This action cannot be undone.</s-text>
+    </s-stack>
+
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      tone="critical"
+      commandFor="delete-modal"
+      command="--hide"
+    >
+      Delete product
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="delete-modal"
+      command="--hide"
+    >
+      Cancel
+    </s-button>
+  </s-modal>
+</s-stack>

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

@@ -1,23 +1,17 @@
-<s-button commandFor="modal">
-  Open
-</s-button>
+<s-button commandFor="modal">Open</s-button>
 
 <s-modal id="modal" heading="Details">
-  <s-paragraph>
-    Displaying more details here.
-  </s-paragraph>
+  <s-paragraph>Displaying more details here.</s-paragraph>
 
-  <s-button
-    slot="secondary-actions"
-    commandFor="modal"
-    command="--hide">
+  <s-button slot="secondary-actions" commandFor="modal" command="--hide">
     Close
   </s-button>
   <s-button
     slot="primary-action"
     variant="primary"
     commandFor="modal"
-    command="--hide">
+    command="--hide"
+  >
     Save
   </s-button>
 </s-modal>

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

@@ -0,0 +1,19 @@
+<>
+  <s-button commandFor="modal">Open</s-button>
+
+  <s-modal id="modal" heading="Details">
+    <s-paragraph>Displaying more details here.</s-paragraph>
+
+    <s-button slot="secondary-actions" commandFor="modal" command="--hide">
+      Close
+    </s-button>
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      commandFor="modal"
+      command="--hide"
+    >
+      Save
+    </s-button>
+  </s-modal>
+</>

package/src/surfaces/admin/components/Modal/examples/different-modal-sizes.html

@@ -0,0 +1,61 @@
+<s-stack gap="base">
+  <s-stack direction="inline" gap="base">
+    <s-button commandFor="small-modal" command="--show">Small modal</s-button>
+    <s-button commandFor="large-modal" command="--show">Large modal</s-button>
+  </s-stack>
+
+  <!-- Small modal for quick confirmations -->
+  <s-modal id="small-modal" heading="Confirm action" size="small-100">
+    <s-text>Are you sure you want to proceed?</s-text>
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      commandFor="small-modal"
+      command="--hide"
+    >
+      Confirm
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      commandFor="small-modal"
+      command="--hide"
+    >
+      Cancel
+    </s-button>
+  </s-modal>
+
+  <!-- Large modal for detailed content -->
+  <s-modal id="large-modal" heading="Order details" size="large-100">
+    <s-stack gap="base">
+      <s-section>
+        <s-heading>Order #1001</s-heading>
+        <s-text>Placed on March 15, 2024</s-text>
+      </s-section>
+
+      <s-divider></s-divider>
+
+      <s-section>
+        <s-heading>Items</s-heading>
+        <s-stack gap="small">
+          <s-text>Winter jacket - $89.99</s-text>
+          <s-text>Wool scarf - $29.99</s-text>
+          <s-text>Leather gloves - $45.99</s-text>
+        </s-stack>
+      </s-section>
+
+      <s-divider></s-divider>
+
+      <s-text type="strong">Total: $165.97</s-text>
+    </s-stack>
+
+    <s-button
+      slot="primary-action"
+      variant="primary"
+      commandFor="large-modal"
+      command="--hide"
+    >
+      Close
+    </s-button>
+  </s-modal>
+</s-stack>