Add documentation and example for Admin Modal component

Author: sam-b-rose

.changeset/small-roses-double.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Add documentation for Admin Modal

packages/ui-extensions/docs/surfaces/admin/screenshots/components/modal.png

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Use modal to display content in a overlay. This component is useful for creating a distraction-free experience, such as a confirmation dialog or a settings panel.',
   category: 'Polaris web components',
-  subCategory: 'Overlay',
+  subCategory: 'Overlays',
   related: [],
 };
 

packages/ui-extensions/src/docs/shared/components/Modal.ts

@@ -6041,8 +6041,17 @@ export type RequiredAlignedModalProps = Required<ModalProps$1>;
 export interface ModalProps
   extends Pick<
     RequiredAlignedModalProps,
-    'accessibilityLabel' | 'heading' | 'padding' | 'size'
+    | 'accessibilityLabel'
+    | 'heading'
+    | 'padding'
+    | 'size'
+    | 'hideOverlay'
+    | 'showOverlay'
+    | 'toggleOverlay'
   > {
+  /**
+   * Adjust the size of the Modal.
+   */
   size: Extract<
     ModalProps$1['size'],
     'small-100' | 'small' | 'base' | 'large' | 'large-100'
@@ -6129,13 +6138,13 @@ export interface ModalJSXProps
    *
    * Only a `Button` with a variant of `primary` is allowed.
    */
-  primaryAction: ComponentChild;
+  primaryAction?: ComponentChild;
   /**
    * The secondary actions to perform.
    *
    * Only `ButtonGroup` or `Button` with a variant of `secondary` or `auto` are allowed.
    */
-  secondaryActions: ComponentChild;
+  secondaryActions?: ComponentChild;
   onHide?: ((event: CallbackEvent<typeof tagName$z>) => void) | null;
   onShow?: ((event: CallbackEvent<typeof tagName$z>) => void) | null;
   onAfterHide?: ((event: CallbackEvent<typeof tagName$z>) => void) | null;
@@ -7853,13 +7862,13 @@ export interface ModalSlots {
    *
    * Only a `Button` with a variant of `primary` is allowed.
    */
-  'primary-action': HTMLElement;
+  'primary-action'?: HTMLElement;
   /**
    * The secondary actions to perform.
    *
    * Only `ButtonGroup` or `Button` with a variant of `secondary` or `auto` are allowed.
    */
-  'secondary-actions': HTMLElement;
+  'secondary-actions'?: HTMLElement;
 }
 
 export interface MoneyFieldEvents {

packages/ui-extensions/src/surfaces/admin/components.d.ts

@@ -16,8 +16,17 @@ export type RequiredAlignedModalProps = Required<ModalProps$1>;
 export interface ModalProps
   extends Pick<
     RequiredAlignedModalProps,
-    'accessibilityLabel' | 'heading' | 'padding' | 'size'
+    | 'accessibilityLabel'
+    | 'heading'
+    | 'padding'
+    | 'size'
+    | 'hideOverlay'
+    | 'showOverlay'
+    | 'toggleOverlay'
   > {
+  /**
+   * Adjust the size of the Modal.
+   */
   size: Extract<
     ModalProps$1['size'],
     'small-100' | 'small' | 'base' | 'large' | 'large-100'
@@ -205,13 +214,13 @@ export interface ModalJSXProps
    *
    * Only a `Button` with a variant of `primary` is allowed.
    */
-  primaryAction: ComponentChild;
+  primaryAction?: ComponentChild;
   /**
    * The secondary actions to perform.
    *
    * Only `ButtonGroup` or `Button` with a variant of `secondary` or `auto` are allowed.
    */
-  secondaryActions: ComponentChild;
+  secondaryActions?: ComponentChild;
   onHide?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   onShow?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   onAfterHide?: ((event: CallbackEvent<typeof tagName>) => void) | null;

packages/ui-extensions/src/surfaces/admin/components/Modal.d.ts

@@ -0,0 +1,40 @@
+import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
+import sharedContent from '../../../../docs/shared/components/Modal';
+
+const data: AdminReferenceEntityTemplateSchema = {
+  ...sharedContent,
+  thumbnail: '/assets/templated-apis-screenshots/admin/components/modal.png',
+  isVisualComponent: true,
+  definitions: [
+    {
+      title: 'Properties',
+      description: '',
+      type: 'Modal',
+    },
+    {
+      title: 'Events',
+      description:
+        'Learn more about [registering events](/docs/api/app-home/using-polaris-components#event-handling).',
+      type: 'ModalEvents',
+    },
+    {
+      title: 'Slots',
+      description: '',
+      type: 'ModalSlots',
+    },
+  ],
+  defaultExample: {
+    codeblock: {
+      title: 'Code',
+      tabs: [
+        {
+          code: './examples/default.html',
+          language: 'preview',
+          layout: 'alignStart',
+        },
+      ],
+    },
+  },
+};
+
+export default data;

packages/ui-extensions/src/surfaces/admin/components/Modal/Modal.doc.ts

@@ -0,0 +1,15 @@
+<s-button commandFor="modal">Open</s-button>
+
+<s-modal id="modal" heading="Reach more shoppers with Instagram product tags">
+  <s-paragraph>
+    Use Instagram posts to share your products with millions of people.
+    Let shoppers buy from your store without leaving Instagram.
+  </s-paragraph>
+
+  <s-button slot="secondary-actions" commandFor="modal" command="--hide">
+    Learn more
+  </s-button>
+  <s-button slot="primary-action" variant="primary" commandFor="modal" command="--hide">
+    Add Instagram
+  </s-button>
+</s-modal>

packages/ui-extensions/src/surfaces/admin/components/Modal/examples/default.html

@@ -25,6 +25,7 @@ export type StandardComponents =
   | 'Link'
   | 'ListItem'
   | 'Menu'
+  | 'Modal'
   | 'MoneyField'
   | 'NumberField'
   | 'Option'