@shopify/ui-extensions 2025.10.0-rc.4 → 2025.10.0-rc.40

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

@@ -0,0 +1,148 @@
+/** VERSION: 1.19.0 **/
+/* eslint-disable import/extensions */
+
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {
+  ComponentChild,
+  TooltipProps$1,
+  InteractionProps,
+} from './shared.d.ts';
+
+export interface TooltipProps extends Required<Pick<TooltipProps$1, 'id'>> {}
+
+/** 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) => ComponentChild;
+  styles?: Styles;
+};
+export interface ActivationEventEsque {
+  shiftKey: boolean;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  button: number;
+}
+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);
+
+  /** @private */
+  setAttribute(name: string, value: string): void;
+  /** @private */
+  attributeChangedCallback(name: string): void;
+  /** @private */
+  connectedCallback(): void;
+  /** @private */
+  disconnectedCallback(): void;
+  /** @private */
+  adoptedCallback(): void;
+  /**
+   * Queue a run of the render function.
+   * You shouldn't need to call this manually - it should be handled by changes to @property values.
+   * @private
+   */
+  queueRender(): void;
+  /**
+   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
+   *
+   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
+   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
+   * @private
+   * @param options
+   */
+  click({sourceEvent}?: ClickOptions): void;
+}
+
+/**
+ * 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.
+ */
+declare const overlayHidden: unique symbol;
+/**
+ * Symbol used to track the element that opened the overlay. In some cases, like tooltips and popovers, the overlay is positioned against this element. In all cases, focus should be restored to this element when the overlay is closed.
+ */
+declare const overlayActivator: unique symbol;
+declare const overlayHideFrameId: unique symbol;
+
+declare class PreactOverlayElement extends PreactCustomElement {
+  constructor(renderImpl: RenderImpl);
+  /** @private */
+  [overlayHidden]: boolean;
+  /** @private */
+  [overlayActivator]: HTMLElement | null | undefined;
+  /** @private */
+  [overlayHideFrameId]?: number;
+  /** @private */
+  [overlayCommand](
+    command: InteractionProps['command'],
+    overlayActivatorEl: HTMLElement | null | undefined,
+  ): void;
+}
+
+declare class Tooltip extends PreactOverlayElement implements TooltipProps {
+  constructor();
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: Tooltip;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: TooltipJSXProps & PreactBaseElementPropsWithChildren<Tooltip>;
+    }
+  }
+}
+
+declare const tagName = 's-tooltip';
+export interface TooltipJSXProps
+  extends Partial<TooltipProps>,
+    Pick<TooltipProps$1, 'id'> {}
+
+export {Tooltip};
+export type {TooltipJSXProps};

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -72,18 +72,12 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
-export type CallbackEvent<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> = TEvent & {
-  currentTarget: HTMLElementTagNameMap[TTagName];
+export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  currentTarget: HTMLElementTagNameMap[T];
 };
-export type CallbackEventListener<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> =
+export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
-      (event: CallbackEvent<TTagName, TEvent>): void;
+      (event: CallbackEvent<T>): void;
     })
   | null;
 export interface FieldReactProps<T extends keyof HTMLElementTagNameMap> {
@@ -92,6 +86,15 @@ export interface FieldReactProps<T extends keyof HTMLElementTagNameMap> {
   onFocus?: ((event: CallbackEvent<T>) => void) | null;
   onBlur?: ((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>;
+}
 
 declare const internals: unique symbol;
 export type PreactInputProps = Required<
@@ -213,12 +216,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: URLFieldJSXProps & BaseProps;
+      [tagName]: URLFieldJSXProps & PreactBaseElementProps<URLField>;
     }
   }
 }

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -69,6 +69,21 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
+/** 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;
+}
+
 declare class UnorderedList
   extends PreactCustomElement
   implements UnorderedListProps
@@ -81,13 +96,10 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: UnorderedListJSXProps & BaseProps;
+      [tagName]: UnorderedListJSXProps &
+        PreactBaseElementPropsWithChildren<UnorderedList>;
     }
   }
 }

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

@@ -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-thumbnail>
+    <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-button>
+    </s-stack>
+  </s-grid>
+</s-clickable>

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

@@ -0,0 +1,35 @@
+<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-image>
+        </s-box>
+      </s-stack>
+    </s-grid>
+    <s-button
+      icon="x"
+      tone="neutral"
+      variant="tertiary"
+      accessibilityLabel="Dismiss card"
+    ></s-button>
+  </s-grid>
+</s-section>

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

@@ -0,0 +1,228 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
+    <title>Pattern</title>
+  </head>
+  <body>
+    <!-- === -->
+    <!-- Details page pattern -->
+    <!-- === -->
+    <form data-save-bar>
+      <s-page heading="Mountain view">
+        <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>
+        <!-- === -->
+        <!-- Puzzle information -->
+        <!-- === -->
+        <s-section heading="Puzzle information">
+          <s-grid gap="base">
+            <s-text-field
+              label="Puzzle name"
+              name="name"
+              labelAccessibilityVisibility="visible"
+              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"
+              labelAccessibilityVisibility="visible"
+              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"
+              labelAccessibilityVisibility="visible"
+              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>
+        <!-- === -->
+        <!-- Puzzle templates -->
+        <!-- === -->
+        <s-section heading="Puzzle templates">
+          <s-grid gap="base">
+            <s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="center">
+              <s-grid-item>
+                <s-search-field
+                  label="Search templates"
+                  labelAccessibilityVisibility="exclusive"
+                  placeholder="Search templates"
+                ></s-search-field>
+              </s-grid-item>
+              <s-grid-item>
+                <s-button>Browse</s-button>
+              </s-grid-item>
+            </s-grid>
+            <s-box
+              background="strong"
+              border="base"
+              borderRadius="base"
+              borderStyle="solid"
+              overflow="hidden"
+            >
+              <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-table-header>
+                </s-table-header-row>
+                <s-table-body>
+                  <s-table-row>
+                    <s-table-cell listSlot="primary">
+                      <s-stack direction="inline" gap="base" alignItems="center">
+                        <s-box
+                          border="base"
+                          borderRadius="base"
+                          overflow="hidden"
+                          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-box>
+                        16-pieces puzzle
+                      </s-stack>
+                    </s-table-cell>
+                    <s-table-cell>
+                      <s-stack alignItems="end">
+                        <s-link>Preview</s-link>
+                      </s-stack>
+                    </s-table-cell>
+                    <s-table-cell>
+                      <s-stack alignItems="end">
+                        <s-button
+                          icon="x"
+                          tone="neutral"
+                          variant="tertiary"
+                          accessibilityLabel="Remove 16-Pieces Puzzle template"
+                        ></s-button>
+                      </s-stack>
+                    </s-table-cell>
+                  </s-table-row>
+                  <s-table-row>
+                    <s-table-cell listSlot="primary">
+                      <s-stack direction="inline" gap="base" alignItems="center">
+                        <s-box
+                          border="base"
+                          borderRadius="base"
+                          overflow="hidden"
+                          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-box>
+                        9-pieces puzzle
+                      </s-stack>
+                    </s-table-cell>
+                    <s-table-cell>
+                      <s-stack direction="inline" gap="base" justifyContent="end">
+                        <s-link>Preview</s-link>
+                      </s-stack>
+                    </s-table-cell>
+                    <s-table-cell listSlot="secondary">
+                      <s-stack alignItems="end">
+                        <s-button
+                          icon="x"
+                          tone="neutral"
+                          variant="tertiary"
+                          accessibilityLabel="Remove 9-Pieces Puzzle template"
+                        ></s-button>
+                      </s-stack>
+                    </s-table-cell>
+                  </s-table-row>
+                  <!-- Add more rows as needed here -->
+                  <!-- If more than 10 rows are needed, details page tables should use the paginate, hasPreviousPage, hasNextPage, onPreviousPage, and onNextPage attributes to display and handle pagination) -->
+                </s-table-body>
+              </s-table>
+            </s-box>
+          </s-grid>
+        </s-section>
+        <!-- === -->
+        <!-- Settings -->
+        <!-- === -->
+        <s-section heading="Settings">
+          <s-grid gap="base">
+            <s-select label="Puzzle size" name="puzzle-size">
+              <s-option value="small">Small (9" x 9")</s-option>
+              <s-option value="medium" selected> Medium (18" x 24") </s-option>
+              <s-option value="large">Large (24" x 36")</s-option>
+            </s-select>
+            <s-select label="Piece count" name="piece-count">
+              <s-option value="250">250 pieces (Easy)</s-option>
+              <s-option value="500" selected> 500 pieces (Medium) </s-option>
+              <s-option value="1000">1000 pieces (Hard)</s-option>
+              <s-option value="2000">2000 pieces (Expert)</s-option>
+            </s-select>
+            <s-select label="Material" name="material">
+              <s-option value="standard" selected> Standard cardboard </s-option>
+              <s-option value="premium">Premium cardboard</s-option>
+              <s-option value="wooden">Wooden pieces</s-option>
+            </s-select>
+            <s-number-field
+              label="Quantity in stock"
+              name="quantity-in-stock"
+              labelAccessibilityVisibility="visible"
+              value="50"
+              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 -->
+        <s-box slot="aside">
+          <!-- === -->
+          <!-- Puzzle summary -->
+          <!-- === -->
+          <s-section heading="Puzzle summary">
+            <s-heading>Mountain view</s-heading>
+            <s-unordered-list>
+              <s-list-item>16-piece puzzle with medium difficulty</s-list-item>
+              <s-list-item>Pieces can be rotated</s-list-item>
+              <s-list-item>No time limit</s-list-item>
+              <s-list-item>
+                <s-stack direction="inline" gap="small">
+                  <s-text>Current status:</s-text>
+                  <s-badge color="base" tone="success">
+                    Active
+                  </s-badge>
+                </s-stack>
+              </s-list-item>
+            </s-unordered-list>
+          </s-section>
+        </s-box>
+      </s-page>
+    </form>
+  </body>
+</html>