@shopify/ui-extensions 2025.10.1 → 2025.10.3

package/src/surfaces/admin/components/Tooltip/examples/with-icon-button.jsx

@@ -0,0 +1,8 @@
+<>
+  <s-tooltip id="delete-button-tooltip">
+    <s-text>Delete item permanently</s-text>
+  </s-tooltip>
+  <s-button interestFor="delete-button-tooltip">
+    <s-icon tone="neutral" type="info" />
+  </s-button>
+</>

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.20.0 **/
+/** VERSION: 1.22.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -89,15 +89,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.
  */
@@ -107,6 +131,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);
@@ -116,11 +155,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 Tooltip extends PreactOverlayElement implements TooltipProps {

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

@@ -0,0 +1,7 @@
+<s-stack gap="base">
+  <!-- Simple URL input -->
+  <s-url-field
+    label="Website URL"
+    placeholder="https://example.com"
+  ></s-url-field>
+</s-stack>

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

@@ -0,0 +1,7 @@
+<s-stack gap="base">
+  {/* Simple URL input */}
+  <s-url-field
+    label="Website URL"
+    placeholder="https://example.com"
+   />
+</s-stack>

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

@@ -0,0 +1,5 @@
+<s-url-field
+  label="Your website"
+  details="Join the partner ecosystem"
+  placeholder="https://shopify.com/partner"
+ />

package/src/surfaces/admin/components/URLField/examples/disabled-state.html

@@ -0,0 +1,5 @@
+<s-url-field
+  label="Store URL"
+  value="https://your-store.myshopify.com"
+  disabled
+></s-url-field>

package/src/surfaces/admin/components/URLField/examples/disabled-state.jsx

@@ -0,0 +1,5 @@
+<s-url-field
+  label="Store URL"
+  value="https://your-store.myshopify.com"
+  disabled
+/>

package/src/surfaces/admin/components/URLField/examples/with-default-value.html

@@ -0,0 +1,7 @@
+<s-stack gap="base">
+  <s-url-field
+    label="Profile URL"
+    value="https://shop.myshopify.com"
+    readOnly
+  ></s-url-field>
+</s-stack>

package/src/surfaces/admin/components/URLField/examples/with-default-value.jsx

@@ -0,0 +1,7 @@
+<s-stack gap="base">
+  <s-url-field
+    label="Profile URL"
+    defaultValue="https://shop.myshopify.com"
+    readOnly
+  />
+</s-stack>

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

@@ -0,0 +1,7 @@
+<s-url-field
+  label="Company website"
+  required
+  minLength="10"
+  maxLength="200"
+  error="Please enter a valid website URL"
+></s-url-field>

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

@@ -0,0 +1,7 @@
+<s-url-field
+  label="Company website"
+  required
+  minLength={10}
+  maxLength={200}
+  error="Please enter a valid website URL"
+  />

package/src/surfaces/admin/components/URLField.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/UnorderedList/examples/default.jsx

@@ -0,0 +1,5 @@
+<s-unordered-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-unordered-list>

package/src/surfaces/admin/components/UnorderedList/examples/store-setup-checklist.html

@@ -0,0 +1,24 @@
+<s-stack gap="base">
+  <s-box borderWidth="small-100" borderRadius="base" padding="base">
+    <s-unordered-list>
+      <s-list-item>Configure payment settings</s-list-item>
+      <s-list-item>
+        Set up shipping options
+        <s-unordered-list>
+          <s-list-item>Domestic shipping rates</s-list-item>
+          <s-list-item>International shipping zones</s-list-item>
+        </s-unordered-list>
+      </s-list-item>
+      <s-list-item>Add product descriptions</s-list-item>
+    </s-unordered-list>
+  </s-box>
+
+  <s-box borderWidth="small-100" borderRadius="base" padding="base">
+    <s-unordered-list>
+      <s-list-item>Enable online payments</s-list-item>
+      <s-list-item>Set up shipping rates</s-list-item>
+      <s-list-item>Configure tax settings</s-list-item>
+      <s-list-item>Add product descriptions</s-list-item>
+    </s-unordered-list>
+  </s-box>
+</s-stack>

package/src/surfaces/admin/components/UnorderedList/examples/store-setup-checklist.jsx

@@ -0,0 +1,24 @@
+<s-stack gap="base">
+  <s-box borderWidth="small-100" borderRadius="base" padding="base">
+    <s-unordered-list>
+      <s-list-item>Configure payment settings</s-list-item>
+      <s-list-item>
+        Set up shipping options
+        <s-unordered-list>
+          <s-list-item>Domestic shipping rates</s-list-item>
+          <s-list-item>International shipping zones</s-list-item>
+        </s-unordered-list>
+      </s-list-item>
+      <s-list-item>Add product descriptions</s-list-item>
+    </s-unordered-list>
+  </s-box>
+
+  <s-box borderWidth="small-100" borderRadius="base" padding="base">
+    <s-unordered-list>
+      <s-list-item>Enable online payments</s-list-item>
+      <s-list-item>Set up shipping rates</s-list-item>
+      <s-list-item>Configure tax settings</s-list-item>
+      <s-list-item>Add product descriptions</s-list-item>
+    </s-unordered-list>
+  </s-box>
+</s-stack>

package/src/surfaces/admin/components/UnorderedList.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/patterns/examples/accountConnection.jsx

@@ -0,0 +1,20 @@
+<s-section>
+  <s-stack gap="base">
+    <s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="center">
+      <s-grid-item>
+        <s-stack>
+          <s-heading>Puzzlify</s-heading>
+          <s-text color="subdued">No account connected</s-text>
+        </s-stack>
+      </s-grid-item>
+      <s-grid-item>
+        <s-button variant="primary">Connect</s-button>
+      </s-grid-item>
+    </s-grid>
+    <s-text>
+      By clicking Connect, you agree to accept Sample App's terms and
+      conditions. You'll pay a commission rate of 15% on sales made through
+      Sample App.
+    </s-text>
+  </s-stack>
+</s-section>

package/src/surfaces/admin/components/patterns/examples/appCard.jsx

@@ -0,0 +1,30 @@
+<s-clickable
+  href="https://apps.shopify.com/planet"
+  border="base"
+  borderRadius="base"
+  padding="base"
+  inlineSize="100%"
+  accessibilityLabel="Download Shopify Planet"
+>
+  <s-grid gridTemplateColumns="auto 1fr auto" alignItems="stretch" gap="base">
+    <s-thumbnail
+      size="small"
+      src="https://cdn.shopify.com/app-store/listing_images/87176a11f3714753fdc2e1fc8bbf0415/icon/CIqiqqXsiIADEAE=.png"
+      alt="Shopify Planet icon"
+     />
+    <s-box>
+      <s-heading>Shopify Planet</s-heading>
+      <s-paragraph>Free</s-paragraph>
+      <s-paragraph>
+        Offer carbon-neutral shipping and showcase your commitment.
+      </s-paragraph>
+    </s-box>
+    <s-stack justifyContent="start">
+      <s-button
+        href="https://apps.shopify.com/planet"
+        icon="download"
+        accessibilityLabel="Download Shopify Planet"
+       />
+    </s-stack>
+  </s-grid>
+</s-clickable>

package/src/surfaces/admin/components/patterns/examples/calloutCard.jsx

@@ -0,0 +1,39 @@
+<s-section>
+  <s-grid gridTemplateColumns="1fr auto" gap="small-400" alignItems="start">
+    <s-grid
+      gridTemplateColumns="@container (inline-size <= 480px) 1fr, auto auto"
+      gap="base"
+      alignItems="center"
+    >
+      <s-grid gap="small-200">
+        <s-heading>Ready to create your custom puzzle?</s-heading>
+        <s-paragraph>
+          Start by uploading an image to your gallery or choose from one of our
+          templates.
+        </s-paragraph>
+        <s-stack direction="inline" gap="small-200">
+          <s-button> Upload image </s-button>
+          <s-button tone="neutral" variant="tertiary">
+            {" "}
+            Browse templates{" "}
+          </s-button>
+        </s-stack>
+      </s-grid>
+      <s-stack alignItems="center">
+        <s-box maxInlineSize="200px" borderRadius="base" overflow="hidden">
+          <s-image
+            src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
+            alt="Customize checkout illustration"
+            aspectRatio="1/0.5"
+           />
+        </s-box>
+      </s-stack>
+    </s-grid>
+    <s-button
+      icon="x"
+      tone="neutral"
+      variant="tertiary"
+      accessibilityLabel="Dismiss card"
+     />
+  </s-grid>
+</s-section>

package/src/surfaces/admin/components/patterns/examples/details.jsx

@@ -17,7 +17,9 @@ export default function DetailsPage() {
   return (
     <form data-save-bar onSubmit={handleFormSubmit} onReset={handleFormReset}>
       <s-page heading="Mountain view">
-        <s-link slot="breadcrumb-actions" href="/app/puzzles">Puzzles</s-link>
+        <s-link slot="breadcrumb-actions" href="/app/puzzles">
+          Puzzles
+        </s-link>
         <s-button slot="secondary-actions">Duplicate</s-button>
         <s-button slot="secondary-actions">Delete</s-button>
         {/* === */}
@@ -32,7 +34,7 @@ export default function DetailsPage() {
               placeholder="Enter puzzle name"
               value="Mountain view"
               details="Players will see this name when browsing puzzles."
-            ></s-text-field>
+             />
             <s-text-area
               label="Description"
               name="description"
@@ -40,7 +42,7 @@ export default function DetailsPage() {
               placeholder="Brief description of your puzzle"
               value="A beautiful mountain landscape puzzle"
               details="Help players understand what your puzzle features"
-            ></s-text-area>
+             />
             <s-money-field
               label="Price"
               name="price"
@@ -48,14 +50,14 @@ export default function DetailsPage() {
               placeholder="0.00"
               value="9.99"
               details="Set the price for this puzzle"
-            ></s-money-field>
+             />
             <s-url-field
               label="Reference image URL"
               name="reference-image-url"
               labelAccessibilityVisibility="visible"
               placeholder="https://example.com/image.jpg"
               details="Optional link to original image"
-            ></s-url-field>
+             />
           </s-grid>
         </s-section>
 
@@ -74,7 +76,7 @@ export default function DetailsPage() {
                   label="Search templates"
                   labelAccessibilityVisibility="exclusive"
                   placeholder="Search templates"
-                ></s-search-field>
+                 />
               </s-grid-item>
               <s-grid-item>
                 <s-button>Browse</s-button>
@@ -87,18 +89,14 @@ export default function DetailsPage() {
               borderStyle="solid"
               overflow="hidden"
             >
-              <s-table
-                border="base"
-                borderRadius="base"
-                borderStyle="solid"
-              >
+              <s-table border="base" borderRadius="base" borderStyle="solid">
                 <s-table-header-row>
                   <s-table-header listSlot="primary">Template</s-table-header>
                   <s-table-header>
                     <s-stack alignItems="end">Actions</s-stack>
                   </s-table-header>
                   <s-table-header listSlot="secondary">
-                    <s-stack direction="inline" alignItems="end"></s-stack>
+                    <s-stack direction="inline" alignItems="end" />
                   </s-table-header>
                 </s-table-header-row>
                 <s-table-body>
@@ -116,7 +114,10 @@ export default function DetailsPage() {
                           maxInlineSize="40px"
                           maxBlockSize="40px"
                         >
-                          <s-image alt="16-pieces puzzle template" src="https://cdn.shopify.com/static/images/polaris/patterns/16-pieces.png"></s-image>
+                          <s-image
+                            alt="16-pieces puzzle template"
+                            src="https://cdn.shopify.com/static/images/polaris/patterns/16-pieces.png"
+                           />
                         </s-box>
                         16-pieces puzzle
                       </s-stack>
@@ -133,7 +134,7 @@ export default function DetailsPage() {
                           tone="neutral"
                           variant="tertiary"
                           accessibilityLabel="Remove 16-Pieces Puzzle template"
-                        ></s-button>
+                         />
                       </s-stack>
                     </s-table-cell>
                   </s-table-row>
@@ -151,7 +152,10 @@ export default function DetailsPage() {
                           maxInlineSize="40px"
                           maxBlockSize="40px"
                         >
-                          <s-image alt="9-pieces puzzle template" src="https://cdn.shopify.com/static/images/polaris/patterns/9-pieces.png"></s-image>
+                          <s-image
+                            alt="9-pieces puzzle template"
+                            src="https://cdn.shopify.com/static/images/polaris/patterns/9-pieces.png"
+                           />
                         </s-box>
                         9-pieces puzzle
                       </s-stack>
@@ -172,7 +176,7 @@ export default function DetailsPage() {
                           tone="neutral"
                           variant="tertiary"
                           accessibilityLabel="Remove 9-Pieces Puzzle template"
-                        ></s-button>
+                         />
                       </s-stack>
                     </s-table-cell>
                   </s-table-row>
@@ -219,12 +223,12 @@ export default function DetailsPage() {
               min="0"
               placeholder="0"
               details="Current inventory quantity"
-            ></s-number-field>
+             />
             <s-switch
               label="Include reference image"
               name="include-reference-image"
               details="Ship a reference image with the puzzle"
-            ></s-switch>
+             />
           </s-grid>
         </s-section>
         {/* Use the aside slot for sidebar content */}
@@ -252,4 +256,4 @@ export default function DetailsPage() {
       </s-page>
     </form>
   );
-}
+}

package/src/surfaces/admin/components/patterns/examples/emptyState.jsx

@@ -0,0 +1,32 @@
+<s-section accessibilityLabel="Empty state section">
+  <s-grid gap="base" justifyItems="center" paddingBlock="large-400">
+    <s-box maxInlineSize="200px" maxBlockSize="200px">
+      <s-image
+        aspectRatio="1/0.5"
+        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
+        alt="A stylized graphic of four characters, each holding a puzzle piece"
+      />
+    </s-box>
+    <s-grid justifyItems="center" maxInlineSize="450px" gap="base">
+      <s-stack alignItems="center">
+        <s-heading>Start creating puzzles</s-heading>
+        <s-paragraph>
+          Create and manage your collection of puzzles for players to enjoy.
+        </s-paragraph>
+      </s-stack>
+      <s-button-group>
+        <s-button
+          slot="secondary-actions"
+          aria-label="Learn more about creating puzzles"
+        >
+          {" "}
+          Learn more{" "}
+        </s-button>
+        <s-button slot="primary-action" aria-label="Add a new puzzle">
+          {" "}
+          Create puzzle{" "}
+        </s-button>
+      </s-button-group>
+    </s-grid>
+  </s-grid>
+</s-section>