@shopify/ui-extensions 2026.1.2 → 2026.1.3

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

@@ -1,3 +1,11 @@
+const [expanded, setExpanded] = useState({
+  guide: true,
+  step1: true,
+  step2: false,
+  step3: false,
+});
+
+return (
 <s-section>
   <s-grid gap="base">
     <s-grid gap="small-200">
@@ -17,7 +25,8 @@
           accessibilityLabel="Toggle setup guide"
           variant="tertiary"
           tone="neutral"
-          icon="chevron-up"
+          onClick={() => setExpanded({ ...expanded, guide: !expanded.guide })}
+          icon={expanded.guide ? "chevron-up" : "chevron-down"}
          />
       </s-grid>
       <s-paragraph>
@@ -25,17 +34,27 @@
       </s-paragraph>
       <s-paragraph color="subdued">0 out of 3 steps completed</s-paragraph>
     </s-grid>
-    <s-box borderRadius="base" border="base" background="base">
+    <s-box
+      borderRadius="base"
+      border="base"
+      background="base"
+      display={expanded.guide ? "auto" : "none"}
+    >
       <s-box>
         <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
           <s-checkbox label="Upload an image for your puzzle" />
           <s-button
             accessibilityLabel="Toggle step 1 details"
             variant="tertiary"
-            icon="chevron-up"
+            onClick={() => setExpanded({ ...expanded, step1: !expanded.step1 })}
+            icon={expanded.step1 ? "chevron-up" : "chevron-down"}
            />
         </s-grid>
-        <s-box padding="small" paddingBlockStart="none">
+        <s-box
+          padding="small"
+          paddingBlockStart="none"
+          display={expanded.step1 ? "auto" : "none"}
+        >
           <s-box padding="base" background="subdued" borderRadius="base">
             <s-grid
               gridTemplateColumns="1fr auto"
@@ -73,13 +92,39 @@
           <s-button
             accessibilityLabel="Toggle step 2 details"
             variant="tertiary"
-            icon="chevron-down"
+            onClick={() => setExpanded({ ...expanded, step2: !expanded.step2 })}
+            icon={expanded.step2 ? "chevron-up" : "chevron-down"}
            />
         </s-grid>
         <s-box
           padding="small"
           paddingBlockStart="none"
-         />
+          display={expanded.step2 ? "auto" : "none"}
+        >
+          <s-box padding="base" background="subdued" borderRadius="base">
+            <s-grid
+              gridTemplateColumns="1fr auto"
+              gap="base"
+              alignItems="center"
+            >
+              <s-grid gap="small-200">
+                <s-paragraph>
+                  Choose from our library of puzzle templates including classic
+                  jigsaw, hexagonal, and irregular shapes.
+                </s-paragraph>
+                <s-stack direction="inline" gap="small-200">
+                  <s-button variant="primary">Browse templates</s-button>
+                </s-stack>
+              </s-grid>
+              <s-box maxBlockSize="80px" maxInlineSize="80px">
+                <s-image
+                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
+                  alt="Template selection illustration"
+                 />
+              </s-box>
+            </s-grid>
+          </s-box>
+        </s-box>
       </s-box>
       <s-divider />
       <s-box>
@@ -88,14 +133,41 @@
           <s-button
             accessibilityLabel="Toggle step 3 details"
             variant="tertiary"
-            icon="chevron-down"
+            onClick={() => setExpanded({ ...expanded, step3: !expanded.step3 })}
+            icon={expanded.step3 ? "chevron-up" : "chevron-down"}
            />
         </s-grid>
         <s-box
           padding="small"
           paddingBlockStart="none"
-         />
+          display={expanded.step3 ? "auto" : "none"}
+        >
+          <s-box padding="base" background="subdued" borderRadius="base">
+            <s-grid
+              gridTemplateColumns="1fr auto"
+              gap="base"
+              alignItems="center"
+            >
+              <s-grid gap="small-200">
+                <s-paragraph>
+                  Fine-tune the shape and interlocking style of your puzzle
+                  pieces for a unique experience.
+                </s-paragraph>
+                <s-stack direction="inline" gap="small-200">
+                  <s-button variant="primary">Customize shapes</s-button>
+                </s-stack>
+              </s-grid>
+              <s-box maxBlockSize="80px" maxInlineSize="80px">
+                <s-image
+                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
+                  alt="Customization illustration"
+                 />
+              </s-box>
+            </s-grid>
+          </s-box>
+        </s-box>
       </s-box>
     </s-box>
   </s-grid>
-</s-section>
+</s-section>
+)

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

@@ -1,57 +1,53 @@
-import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
 
-const data: ReferenceEntityTemplateSchema = {
+const data: AdminReferenceEntityTemplateSchema = {
   name: 'Index',
   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
+    'Most apps need a way for merchants to manage collections of resources and perform actions on them.',
+  description: `Most apps need a way for merchants to manage collections of resources and perform actions on them. For React Router-based Shopify apps, that index route file (\`app.[resources].jsx\`) should use a plural noun for the resource type. For example, \`app.products.jsx\` for managing products through your app. 
 
-  | 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 \`Badge\`, \`Box\`, \`Button\`, \`Clickable\`, \`Grid\`, \`Heading\`, \`Image\`, \`Link\`, \`Paragraph\`, \`Section\`, \`Stack\`, and \`Table\` 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 - 400px) !important;
-    }
-    div[class*="Tabs-module-TabsContent_"] {
-      overflow: auto !important;
-    }
-    div[class*="Screenshot-module-Screenshot_"] {
-      display: none !important;
-    }
-  </style>`,
+  The index pattern provides this foundation while following proven design guidelines that help your app feel native to the Shopify admin. See [Built for Shopify requirements](/docs/apps/launch/built-for-shopify/requirements) for more details on these guidelines.
+  `,
   isVisualComponent: true,
   category: 'Patterns',
   subCategory: 'Templates',
+  isOneColumnLayout: true,
   thumbnail: '/assets/templated-apis-screenshots/admin/patterns/index.png',
+  usedComponents: [
+    'Badge',
+    'Box',
+    'Button',
+    'ButtonGroup',
+    'Checkbox',
+    'Choice',
+    'ChoiceList',
+    'Grid',
+    'Heading',
+    'Icon',
+    'Image',
+    'Link',
+    'Paragraph',
+    'Popover',
+    'Section',
+    'Stack',
+    'Table',
+    'TableBody',
+    'TableCell',
+    'TableHeader',
+    'TableHeaderRow',
+    'TableRow',
+    'Text',
+    'TextField',
+    'Thumbnail',
+    'Tooltip',
+  ],
+  recommendedApis: ['Intents API', 'Modal API', 'Navigation API', 'Toast API'],
+  recommendedCompositions: ['Empty state', 'Footer help', 'Metrics card'],
   defaultExample: {
+    description:
+      'Merchants need to manage a collection of resources and perform actions on them. This example displays an index table for a Product Quality Auditor app with filter tabs, search, sortable columns, bulk selection, and bulk actions. The table shows product thumbnails, quality scores, issue counts, and status badges.',
     codeblock: {
-      title: 'Index',
+      title: 'Display an index table with filters, search, and bulk actions',
       tabs: [
         {
           title: 'html',
@@ -62,19 +58,46 @@ const data: ReferenceEntityTemplateSchema = {
           title: 'jsx',
           code: './examples/index.jsx',
           language: 'preview-jsx',
+          layout: 'templatePattern',
+          customStyles: {
+            minHeight: '400px',
+          },
         },
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the index template with additional functionality:
 
-  related: [
-    {
-      name: 'Built for Shopify',
-      subtitle: 'Requirements',
-      url: '/docs/apps/launch/built-for-shopify/requirements',
-      type: 'component',
-    },
-  ],
+- [Intents API](#example-make-empty-states-actionable-using-intents): Open native Shopify editors to create resources without leaving your app.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use the [Intents API](/docs/api/app-home/apis/intents) to open native Shopify interfaces for creating products directly from an empty state.',
+            codeblock: {
+              title: 'Make empty states actionable using Intents',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: './examples/index-intents.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: './examples/index-intents.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;