@shopify/ui-extensions 2025.10.0-rc.5 → 2025.10.0-rc.7

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

@@ -0,0 +1,349 @@
+// ===
+// Settings page pattern
+// ===
+
+export default function SettingsPage() {
+  const handleFormReset = (event) => {
+    console.log("Handle discarded changes if necessary");
+  };
+
+  const handleFormSubmit = (event) => {
+    event.preventDefault();
+    const formData = new FormData(event.target);
+    const formEntries = Object.fromEntries(formData);
+    console.log("Form data", formEntries);
+  };
+
+  return (
+    <form data-save-bar onSubmit={handleFormSubmit} onReset={handleFormReset}>
+      <s-page>
+        {/* === */}
+        {/* Title Bar */}
+        {/* Note: ui-title-bar requires AppBridge to render correctly */}
+        {/* === */}
+        <ui-title-bar title="Settings"></ui-title-bar>
+        {/* === */}
+        {/* Store settings */}
+        {/* === */}
+        <s-grid gap="base">
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Store Settings</s-heading>
+              <s-paragraph>Manage your store information</s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Store information section">
+              {/* Card-like container with border and padding */}
+              <s-box
+                padding="base"
+                border="base"
+                borderStyle="solid"
+                borderRadius="base"
+              >
+                <s-grid gap="base">
+                  <s-stack direction="inline" justifyContent="space-between">
+                    <s-stack
+                      direction="inline"
+                      alignItems="center"
+                      gap="small-200"
+                    >
+                      <s-icon type="store"></s-icon>
+                      <s-paragraph>Puzzlify Store</s-paragraph>
+                    </s-stack>
+                    {/* Icon-only button requires accessibilityLabel for screen readers */}
+                    <s-button
+                      icon="edit"
+                      variant="tertiary"
+                      tone="neutral"
+                      accessibilityLabel="Edit store name"
+                    ></s-button>
+                  </s-stack>
+                  <s-divider></s-divider>
+                  <s-stack
+                    direction="inline"
+                    justifyContent="space-between"
+                    alignItems="center"
+                  >
+                    <s-stack
+                      direction="inline"
+                      alignItems="center"
+                      gap="small-200"
+                    >
+                      <s-icon type="location"></s-icon>
+                      <s-box>
+                        <s-paragraph>Business address</s-paragraph>
+                        <s-paragraph>Puzzle Retailer</s-paragraph>
+                      </s-box>
+                    </s-stack>
+                    <s-box>
+                      {/* Icon-only button requires accessibilityLabel for screen readers */}
+                      <s-button
+                        icon="edit"
+                        variant="tertiary"
+                        tone="neutral"
+                        accessibilityLabel="Edit business address"
+                      ></s-button>
+                    </s-box>
+                  </s-stack>
+                </s-grid>
+              </s-box>
+            </s-section>
+          </s-grid>
+
+          {/* === */}
+          {/* Product defaults */}
+          {/* === */}
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Product Defaults</s-heading>
+              <s-paragraph>Set default options for new puzzles</s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Product defaults section">
+              <s-grid gap="base">
+                <s-grid gap="base">
+                  <s-select
+                    label="Default puzzle size"
+                    name="default-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="Default piece count"
+                    name="default-piece-count"
+                  >
+                    <s-option value="250" selected>
+                      250 pieces (Easy)
+                    </s-option>
+                    <s-option value="500">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="Default material" name="default-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>
+                  {/* switches (rather than checkboxes) should be used to enable/disable a single option */}
+                  <s-switch
+                    label="Include reference image"
+                    name="include-reference-image"
+                    details="Ship a reference image with the puzzle"
+                  ></s-switch>
+                </s-grid>
+              </s-grid>
+            </s-section>
+          </s-grid>
+
+          {/* === */}
+          {/* Customer experience */}
+          {/* === */}
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Puzzle Experience</s-heading>
+              <s-paragraph>
+                Configure how customers interact with your puzzles
+              </s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Puzzle experience settings">
+              <s-grid gap="base">
+                <s-choice-list
+                  label="Default puzzle packaging style"
+                  name="packaging-style"
+                  details="This will be used for all new puzzles"
+                >
+                  <s-choice
+                    label="Standard box with preview image"
+                    value="standard-preview"
+                    selected
+                  ></s-choice>
+                  <s-choice
+                    label="Mystery box (no preview)"
+                    value="mystery"
+                  ></s-choice>
+                  <s-choice
+                    label="Gift packaging with ribbon"
+                    value="gift"
+                  ></s-choice>
+                  <s-choice
+                    label="Eco-friendly minimal packaging"
+                    value="eco"
+                  ></s-choice>
+                </s-choice-list>
+              </s-grid>
+            </s-section>
+          </s-grid>
+
+          {/* === */}
+          {/* Catalog settings */}
+          {/* === */}
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Catalog Settings</s-heading>
+              <s-paragraph>Configure your online puzzle catalog</s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Catalog settings section">
+              <s-grid gap="base">
+                <s-grid gap="base">
+                  <s-select label="Default sorting" name="default-sorting">
+                    <s-option value="newest" selected>
+                      Newest first
+                    </s-option>
+                    <s-option value="bestselling">Best selling</s-option>
+                    <s-option value="price-low">Price: Low to high</s-option>
+                    <s-option value="price-high">Price: High to low</s-option>
+                  </s-select>
+                  <s-choice-list
+                    label="Display options"
+                    name="display-options"
+                    multiple
+                  >
+                    <s-choice
+                      label="Show difficulty levels"
+                      value="show-difficulty"
+                      selected
+                    ></s-choice>
+                    <s-choice
+                      label="Show piece counts"
+                      value="show-piece-count"
+                    ></s-choice>
+                    <s-choice
+                      label="Show dimensions"
+                      value="show-dimensions"
+                    ></s-choice>
+                  </s-choice-list>
+                </s-grid>
+              </s-grid>
+            </s-section>
+          </s-grid>
+
+          {/* === */}
+          {/* Order notifications */}
+          {/* === */}
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Order Notifications</s-heading>
+              <s-paragraph>Manage your business notifications</s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Order notifications section">
+              <s-grid gap="base">
+                <s-grid gap="base">
+                  <s-select
+                    label="Notification frequency"
+                    name="notification-frequency"
+                  >
+                    <s-option value="immediately" selected>
+                      Immediately
+                    </s-option>
+                    <s-option value="hourly">Hourly digest</s-option>
+                    <s-option value="daily">Daily digest</s-option>
+                  </s-select>
+                  <s-choice-list
+                    label="Notifications type"
+                    name="notifications-type"
+                    multiple
+                  >
+                    <s-choice
+                      label="New order notifications"
+                      value="new-order"
+                      selected
+                    ></s-choice>
+                    <s-choice
+                      label="Low stock alerts"
+                      value="low-stock"
+                    ></s-choice>
+                    <s-choice
+                      label="Customer review notifications"
+                      value="customer-review"
+                    ></s-choice>
+                    <s-choice
+                      label="Shipping updates"
+                      value="shipping-updates"
+                    ></s-choice>
+                  </s-choice-list>
+                </s-grid>
+              </s-grid>
+            </s-section>
+          </s-grid>
+
+          {/* === */}
+          {/* Shipping settings */}
+          {/* === */}
+          <s-grid
+            gridTemplateColumns="@container (inline-size <= 700px) 1fr, 2fr 5fr"
+            gap="base"
+          >
+            {/* Left column */}
+            <s-box>
+              <s-heading>Shipping</s-heading>
+              <s-paragraph>Configure shipping settings</s-paragraph>
+            </s-box>
+            {/* Right column */}
+            <s-section accessibilityLabel="Shipping settings section">
+              <s-grid gap="base">
+                <s-select
+                  label="Default shipping method"
+                  name="default-shipping-method"
+                >
+                  <s-option value="standard" selected>
+                    Standard shipping
+                  </s-option>
+                  <s-option value="express">Express shipping</s-option>
+                  <s-option value="free">Free shipping (over $50)</s-option>
+                </s-select>
+                <s-choice-list
+                  label="Shipping preferences"
+                  name="shipping-preferences"
+                  multiple
+                >
+                  <s-choice
+                    label="Calculate shipping based on weight"
+                    value="calculate-shipping"
+                    selected
+                  ></s-choice>
+                  <s-choice
+                    label="Offer international shipping"
+                    value="international-shipping"
+                  ></s-choice>
+                  <s-choice
+                    label="Show estimated delivery dates"
+                    value="estimated-delivery-dates"
+                  ></s-choice>
+                </s-choice-list>
+              </s-grid>
+            </s-section>
+          </s-grid>
+        </s-grid>
+      </s-page>
+    </form>
+  );
+}

package/src/surfaces/admin/components/patterns/index.ab.doc.ts

@@ -0,0 +1,82 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Index',
+  isOneColumnLayout: true,
+  overviewPreviewDescription:
+    'Manage objects efficiently with dynamic table actions.',
+  description: `The index layout lets merchants view and manage all their objects at once in a table format. They can filter, sort and do quick actions on their objects. To prevent tables from becoming visually cluttered, reveal actions only when the row is hovered over or selected
+
+  | Used to    | Examples |
+| -------- | ------- |
+| View all objects at once  | Products, orders, customers, discounts    |
+| Perform bulk actions | Delete products, pause/activate campaigns      |
+
+  ![Preview of the index pattern](/assets/templated-apis-screenshots/admin/patterns/index-example.png)
+
+  This pattern uses \`Section\`, \`Stack\`, \`Heading\`, \`Button\`, \`Table\`, \`Paragraph\`, \`Box\` and \`Grid\` components.
+
+  ---
+
+  ## Design guidelines
+  Design your index page so users can organize and take action on resource objects.
+
+  ### Navigation
+
+  * Users must be able to return to the previous page without using the browser button. To achieve this, your app can provide breadcrumbs or a Back button on the page.
+  * Offer users clear and predictable action labels.
+
+  ---
+
+  ### Layout
+
+  * Design your app to be responsive and adapt to different screen sizes and devices. This ensures a seamless user experience across various platforms.
+  * For resource index pages, use a full-width page. This is helpful when users are dealing with lists of data that have many columns.
+
+  ---
+
+  <style>
+    div[class*="CodeBlock-module-CodeBlock_"] {
+      max-height: calc(100vh - 80px) !important;
+    }
+    div[class*="Tabs-module-TabsContent_"] {
+      overflow: auto !important;
+    }
+    div[class*="Screenshot-module-Screenshot_"] {
+      display: none !important;
+    }
+  </style>`,
+  isVisualComponent: true,
+  category: 'Patterns',
+  thumbnail: '/assets/templated-apis-screenshots/admin/patterns/index.png',
+  defaultExample: {
+    image:
+      '/assets/templated-apis-screenshots/admin/patterns/index-example.png',
+    codeblock: {
+      title: 'Index',
+      tabs: [
+        {
+          title: 'JSX',
+          code: './examples/index.jsx',
+          language: 'jsx',
+        },
+        {
+          title: 'HTML',
+          code: './examples/index.html',
+          language: 'html',
+        },
+      ],
+    },
+  },
+
+  related: [
+    {
+      name: 'Built for Shopify',
+      subtitle: 'Requirements',
+      url: '/docs/apps/launch/built-for-shopify/requirements',
+      type: 'component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/Abbreviation.d.ts

@@ -1,32 +1,44 @@
 /** VERSION: 0.0.0 **/
-/* eslint-disable import/extensions */
+/* eslint-disable import-x/extensions */
 /* eslint-disable @typescript-eslint/no-namespace */
 /* eslint-disable @typescript-eslint/member-ordering */
 /* eslint-disable line-comment-position */
 /* eslint-disable @typescript-eslint/unified-signatures */
 /* eslint-disable no-var */
-/* eslint-disable import/namespace */
+/* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
 import type {AbbreviationProps$1} from './components-shared.d.ts';
 
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+    key?: preact.Key;
+    ref?: preact.Ref<TClass>;
+    slot?: Lowercase<string>;
+}
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
+    children?: preact.ComponentChildren;
+}
+
+declare const tagName = "s-abbreviation";
 export interface AbbreviationProps extends Pick<AbbreviationProps$1, 'title'> {
 }
 export interface AbbreviationElement extends AbbreviationProps, Omit<HTMLElement, 'id' | 'title'> {
 }
 declare global {
     interface HTMLElementTagNameMap {
-        's-abbreviation': AbbreviationElement;
+        [tagName]: AbbreviationElement;
     }
 }
 declare module 'preact' {
-    interface BaseProps {
-        children?: preact.ComponentChildren;
-        slot?: Lowercase<string>;
-    }
     namespace createElement.JSX {
         interface IntrinsicElements {
-            's-abbreviation': AbbreviationProps & BaseProps;
+            [tagName]: AbbreviationProps & BaseElementPropsWithChildren<AbbreviationElement>;
         }
     }
 }

package/src/surfaces/checkout/components/Banner.d.ts

@@ -1,37 +1,76 @@
 /** VERSION: 0.0.0 **/
-/* eslint-disable import/extensions */
+/* eslint-disable import-x/extensions */
 /* eslint-disable @typescript-eslint/no-namespace */
 /* eslint-disable @typescript-eslint/member-ordering */
 /* eslint-disable line-comment-position */
 /* eslint-disable @typescript-eslint/unified-signatures */
 /* eslint-disable no-var */
-/* eslint-disable import/namespace */
+/* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
 import type {BannerProps$1} from './components-shared.d.ts';
 
-export interface BannerProps extends Pick<BannerProps$1, 'collapsible' | 'dismissible' | 'heading' | 'hidden' | 'id' | 'onAfterHide' | 'onDismiss' | 'tone'> {
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+    key?: preact.Key;
+    ref?: preact.Ref<TClass>;
+    slot?: Lowercase<string>;
+}
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
+    children?: preact.ComponentChildren;
+}
+export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
+    currentTarget: HTMLElementTagNameMap[TTagName];
+};
+
+declare const tagName = "s-banner";
+export interface BannerBaseProps extends Pick<BannerProps$1, 'collapsible' | 'dismissible' | 'heading' | 'hidden' | 'id' | 'tone'> {
     tone?: Extract<BannerProps$1['tone'], 'auto' | 'info' | 'success' | 'warning' | 'critical'>;
 }
-export interface BannerElement extends Omit<BannerProps, 'onAfterHide' | 'onDismiss'>, Omit<HTMLElement, 'id' | 'title' | 'hidden'> {
-    onafterhide: BannerProps['onAfterHide'];
-    ondismiss: BannerProps['onDismiss'];
+export interface BannerEvents extends Pick<BannerProps$1, 'onAfterHide' | 'onDismiss'> {
+}
+export interface BannerElementEvents {
+    /**
+     * Event handler when the banner has fully hidden.
+     *
+     * The `hidden` property will be `true` when this event fires.
+     *
+     * @implementation If implementations animate the hiding of the banner,
+     * this event must fire after the banner has fully hidden.
+     * We can add an `onHide` event in future if we want to provide a hook for the start of the animation.
+     */
+    afterhide?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+    /**
+     * Event handler when the banner is dismissed by the user.
+     *
+     * This does not fire when setting `hidden` manually.
+     *
+     * The `hidden` property will be `false` when this event fires.
+     */
+    dismiss?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+}
+export interface BannerElement extends BannerBaseProps, Omit<BannerEvents, 'onAfterHide' | 'onDismiss'>, Omit<HTMLElement, 'id' | 'title' | 'hidden'> {
+    onafterhide: BannerEvents['onAfterHide'];
+    ondismiss: BannerEvents['onDismiss'];
+}
+export interface BannerProps extends BannerBaseProps, BannerEvents {
 }
 declare global {
     interface HTMLElementTagNameMap {
-        's-banner': BannerElement;
+        [tagName]: BannerElement;
     }
 }
 declare module 'preact' {
-    interface BaseProps {
-        children?: preact.ComponentChildren;
-        slot?: Lowercase<string>;
-    }
     namespace createElement.JSX {
         interface IntrinsicElements {
-            's-banner': BannerProps & BaseProps;
+            [tagName]: BannerProps & BaseElementPropsWithChildren<BannerElement>;
         }
     }
 }
 
-export type { BannerElement, BannerProps };
+export type { BannerBaseProps, BannerElement, BannerElementEvents, BannerEvents, BannerProps };

package/src/surfaces/checkout/components/Box.d.ts

@@ -1,11 +1,11 @@
 /** VERSION: 0.0.0 **/
-/* eslint-disable import/extensions */
+/* eslint-disable import-x/extensions */
 /* eslint-disable @typescript-eslint/no-namespace */
 /* eslint-disable @typescript-eslint/member-ordering */
 /* eslint-disable line-comment-position */
 /* eslint-disable @typescript-eslint/unified-signatures */
 /* eslint-disable no-var */
-/* eslint-disable import/namespace */
+/* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
 import type {BoxProps$1,MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,ColorKeyword} from './components-shared.d.ts';
@@ -13,8 +13,23 @@ import type {BoxProps$1,MaybeAllValuesShorthandProperty,BorderSizeKeyword, Borde
 export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base' | 'large' | 'large-100' | 'large-200'>;
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+    key?: preact.Key;
+    ref?: preact.Ref<TClass>;
+    slot?: Lowercase<string>;
+}
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
+    children?: preact.ComponentChildren;
+}
 
-export interface BoxProps extends Pick<BoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+declare const tagName = "s-box";
+export interface BoxProps extends Pick<BoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
     background?: Extract<BoxProps$1['background'], 'transparent' | 'subdued' | 'base'>;
     border?: BorderShorthand;
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
@@ -24,17 +39,13 @@ export interface BoxElement extends BoxProps, Omit<HTMLElement, 'id'> {
 }
 declare global {
     interface HTMLElementTagNameMap {
-        's-box': BoxElement;
+        [tagName]: BoxElement;
     }
 }
 declare module 'preact' {
-    interface BaseProps {
-        children?: preact.ComponentChildren;
-        slot?: Lowercase<string>;
-    }
     namespace createElement.JSX {
         interface IntrinsicElements {
-            's-box': BoxProps & BaseProps;
+            [tagName]: BoxProps & BaseElementPropsWithChildren<BoxElement>;
         }
     }
 }