[App home] Additional examples for patterns.

packages/ui-extensions/src/surfaces/admin/components/patterns/accountConnection.ab.doc.ts

@@ -24,12 +24,13 @@ const data: AdminReferenceEntityTemplateSchema = {
     'Stack',
     'Text',
   ],
-  recommendedTemplates: ['Details'],
+  recommendedApis: ['Modal API', 'Toast API'],
+  recommendedTemplates: ['Settings'],
   defaultExample: {
     description:
-      'This pattern displays account connection layout with a connect button and terms. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns account information and button, the [section](/docs/api/app-home/polaris-web-components/layout-and-structure/section) provides padding, and the terms text below describes the connection agreement.',
+      'Merchants need to connect or disconnect external services (e.g. marketing platforms, sales channels) from your app. This pattern displays account connection layout with a connect button and terms. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns account information and button, the [section](/docs/api/app-home/polaris-web-components/layout-and-structure/section) provides padding, and the terms text below describes the connection agreement.',
     codeblock: {
-      title: 'Account connection',
+      title: 'Display connection status with connect button and terms',
       tabs: [
         {
           title: 'html',
@@ -45,6 +46,59 @@ const data: AdminReferenceEntityTemplateSchema = {
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the account connection pattern with additional functionality:
+
+- [Modal API](#example-confirm-disconnect-with-modal): Confirm account disconnection before removing an integration.
+- [Toast API](#example-show-connection-feedback-with-toast): Show feedback when connection status changes.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use the [Modal API](/docs/api/app-home/apis/modal-api) to confirm account disconnection before removing the integration.',
+            codeblock: {
+              title: 'Confirm disconnect with Modal',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/accountConnection-modal.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/accountConnection-modal.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Use the [Toast API](/docs/api/app-home/apis/toast) to show feedback when an account is connected or disconnected.',
+            codeblock: {
+              title: 'Show connection feedback with Toast',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/accountConnection-toast.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/accountConnection-toast.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/appCard.ab.doc.ts

@@ -23,12 +23,13 @@ const data: AdminReferenceEntityTemplateSchema = {
     'Stack',
     'Thumbnail',
   ],
-  recommendedTemplates: ['Details'],
+  recommendedApis: ['Navigation API'],
+  recommendedTemplates: ['Homepage'],
   defaultExample: {
     description:
-      'This pattern displays a tappable app card with thumbnail and content layout. The [clickable](/docs/api/app-home/polaris-web-components/actions/clickable) component wraps the card, the [thumbnail](/docs/api/app-home/polaris-web-components/images/thumbnail) shows the app icon, and the [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns the content.',
+      "Merchants can discover and install complementary apps that extend your app's functionality. This pattern displays a tappable app card with thumbnail and content layout. The [clickable](/docs/api/app-home/polaris-web-components/actions/clickable) component wraps the card, the [thumbnail](/docs/api/app-home/polaris-web-components/images/thumbnail) shows the app icon, and the [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns the content.",
     codeblock: {
-      title: 'App card',
+      title: 'Display a tappable app card with thumbnail and content',
       tabs: [
         {
           title: 'html',
@@ -44,6 +45,38 @@ const data: AdminReferenceEntityTemplateSchema = {
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the app card with additional functionality:
+
+- [Navigation API](#example-navigate-to-app-store): Provide a link a recommended app when merchants click the card or its install button.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use `href` attributes to navigate merchants to the App Store when they click the card or install button.',
+            codeblock: {
+              title: 'Navigate to App Store',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/appCard-nav.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/appCard-nav.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/calloutCard.ab.doc.ts

@@ -24,12 +24,13 @@ const data: AdminReferenceEntityTemplateSchema = {
     'Section',
     'Stack',
   ],
-  recommendedTemplates: ['Details'],
+  recommendedApis: ['Navigation API', 'Toast API'],
+  recommendedTemplates: ['Homepage'],
   defaultExample: {
     description:
-      'This pattern presents a callout card that stacks content on smaller screens with a prominent illustration and call-to-action. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) uses responsive column templates. The illustration and button draw attention to important actions or promotions.',
+      'Merchants can take action on new features or opportunities you highlight. This pattern presents a callout card that stacks content on smaller screens with a prominent illustration and call-to-action. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) uses responsive column templates. The illustration and button draw attention to important actions or promotions.',
     codeblock: {
-      title: 'Callout card',
+      title: 'Display a callout card with illustration and call-to-action',
       tabs: [
         {
           title: 'html',
@@ -45,6 +46,59 @@ const data: AdminReferenceEntityTemplateSchema = {
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the callout card with additional functionality:
+
+- [Navigation API](#example-navigate-to-feature-pages): Add links to the pattern for CTA navigation.
+- [Toast API](#example-show-dismiss-feedback-with-toast): Dismiss feedback.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use `href` attributes on buttons to navigate merchants to feature pages when they click CTA buttons.',
+            codeblock: {
+              title: 'Navigate to feature pages',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/calloutCard-nav.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/calloutCard-nav.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Use the [Toast API](/docs/api/app-home/apis/toast) to show feedback when the callout card is dismissed.',
+            codeblock: {
+              title: 'Show dismiss feedback with Toast',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/calloutCard-toast.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/calloutCard-toast.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/details.ab.doc.ts

@@ -43,13 +43,13 @@ const data: AdminReferenceEntityTemplateSchema = {
     'UnorderedList',
     'URLField',
   ],
-  recommendedApis: ['Save Bar API', 'Modal API', 'Intents API'],
-  recommendedCompositions: ['Empty state', 'Footer help', 'Media card'],
+  recommendedApis: ['Modal API', 'Save Bar API'],
+  recommendedCompositions: ['Footer help', 'Resource list'],
   defaultExample: {
     description:
-      'This example presents a product details view for a Product Quality Auditor app with editable quality score fields in the main column and image and score in the sidebar.',
+      'Merchants need to edit and view a single resource with supporting info in the sidebar. This example presents a product details view for a Product Quality Auditor app with editable quality score fields in the main column and image and score in the sidebar.',
     codeblock: {
-      title: 'Details',
+      title: 'Present a product details view with editable fields and sidebar',
       tabs: [
         {
           title: 'html',
@@ -68,6 +68,59 @@ const data: AdminReferenceEntityTemplateSchema = {
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the details template with additional functionality:
+
+- [Modal API](#example-confirm-destructive-actions-with-modal-api): Confirm before performing destructive actions, like deleting a resource.
+- [Save Bar API](#example-retain-unsaved-changes-with-save-bar): Display save and discard controls when forms have unsaved changes.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use the [Modal API](/docs/api/app-home/apis/modal) to confirm destructive actions like deleting a resource. The modal prevents accidental data loss by requiring explicit confirmation.',
+            codeblock: {
+              title: 'Confirm destructive actions with Modal API',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: './examples/details-modal.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: './examples/details-modal.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Add `data-save-bar` to your form element to enable the [Save Bar API](/docs/api/app-home/apis/save-bar), which displays save/discard controls when the form has unsaved changes.',
+            codeblock: {
+              title: 'Retain unsaved changes with Save Bar',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: './examples/details-save-bar.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: './examples/details-save-bar.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/emptyState.ab.doc.ts

@@ -24,13 +24,13 @@ const data: AdminReferenceEntityTemplateSchema = {
     'Section',
     'Stack',
   ],
-  recommendedApis: ['Navigation API', 'Intents API'],
-  recommendedTemplates: ['Details'],
+  recommendedApis: ['Intents API', 'Navigation API'],
+  recommendedTemplates: ['Index'],
   defaultExample: {
     description:
-      'This pattern displays an empty state with centered content and primary and secondary actions. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) centers content vertically and horizontally. Use the [button group](/docs/api/app-home/polaris-web-components/actions/button-group) with `slot="primary-action"` and `slot="secondary-actions"` for clear next steps.',
+      'Merchants need guidance and a clear next step when a list or page is empty. This pattern displays an empty state with centered content and primary and secondary actions. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) centers content vertically and horizontally. Use the [button group](/docs/api/app-home/polaris-web-components/actions/button-group) with `slot="primary-action"` and `slot="secondary-actions"` for clear next steps.',
     codeblock: {
-      title: 'Empty state',
+      title: 'Display an empty state with centered content and actions',
       tabs: [
         {
           title: 'Preview',
@@ -46,6 +46,59 @@ const data: AdminReferenceEntityTemplateSchema = {
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the empty state with additional functionality:
+
+- [Intents API](#example-open-shopify-interfaces-with-intents): Open native Shopify interfaces for browsing or creating resources.
+- [Navigation API](#example-navigate-to-create-page): Navigate to a create page from the empty state action.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use `href` attributes to navigate merchants to a create page when they click the primary action button.',
+            codeblock: {
+              title: 'Navigate to create page',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/emptyState-nav.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/emptyState-nav.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Use the [Intents API](/docs/api/app-home/apis/intents) to make empty state actions open native Shopify interfaces, allowing merchants to browse existing resources or create new ones without leaving your app.',
+            codeblock: {
+              title: 'Open Shopify interfaces with Intents',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/emptyState-intents.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/emptyState-intents.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;