@shopify/ui-extensions 0.0.0-internal-20230622171951

package/src/surfaces/checkout/components/Button/Button.ts

@@ -0,0 +1,87 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {
+  Appearance,
+  InlineAlignment,
+  ButtonAccessibilityRole,
+  OverlayActivatorProps,
+} from '../shared';
+
+export interface ButtonProps extends OverlayActivatorProps {
+  /**
+   * The type of button that will be rendered. The visual presentation of the button type
+   * is controlled by merchants through the Branding API.
+   *
+   *
+   * `primary`: button used for main actions. For example: "Continue to next step".
+   *
+   * `secondary`: button used for secondary actions not blocking user progress. For example: "Download Shop app".
+   *
+   * `plain`: renders a button that visually looks like a link.
+   *
+   *
+   * @defaultValue 'primary'
+   */
+  kind?: 'primary' | 'secondary' | 'plain';
+  /**
+   * Specify the color treatment of the Button.
+   */
+  appearance?: Extract<Appearance, 'monochrome' | 'critical'>;
+  /**
+   * Allows the button to submit a form.
+   * @deprecated use `accessibilityRole="submit"` instead
+   */
+  submit?: boolean;
+  /**
+   * Destination URL to link to. If this value is set, the button will render as a Link.
+   */
+  to?: string;
+  /**
+   * Specifies the inline alignment of the content.
+   *
+   * @defaultValue 'center'
+   */
+  inlineAlignment?: InlineAlignment;
+  /**
+   * Replaces content with a loading indicator.
+   *
+   * @defaultValue false
+   */
+  loading?: boolean;
+  /**
+   * Accessible label for the loading indicator when user prefers reduced motion. This value is
+   * only used if `loading` is true.
+   */
+  loadingLabel?: string;
+  /**
+   * A label used for buyers using assistive technologies. When set, any
+   * `children` supplied to this component are hidden from being seen for
+   * accessibility purposes to prevent duplicate content from being read.
+   */
+  accessibilityLabel?: string;
+  /**
+   * The role of the button that will be rendered.
+   *
+   * `button`: renders a regular button.
+   *
+   * `submit`: renders a button that submits a form.
+   *
+   * @defaultValue 'button'
+   */
+  accessibilityRole?: ButtonAccessibilityRole;
+  /**
+   * Disables the button, disallowing any interaction.
+   *
+   * @defaultValue false
+   */
+  disabled?: boolean;
+  /**
+   * Callback that is run when the button is pressed.
+   */
+  onPress?(): void;
+}
+
+/**
+ * Buttons are used for actions, such as “Add”, “Continue”, “Pay now”, or “Save”.
+ */
+export const Button = createRemoteComponent<'Button', ButtonProps>('Button');

package/src/surfaces/checkout/components/Button/README.md

@@ -0,0 +1,22 @@
+# Button
+
+Buttons are used for actions, such as “Add”, “Continue”, “Pay now”, or “Save”.
+
+## Props
+
+optional = ?
+
+| Name                | Type                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| kind?               | <code>"primary" &#124; "secondary" &#124; "plain"</code> | The type of button that will be rendered. The visual presentation of the button type is controlled by merchants through the Branding API.<br /><br />`primary`: button used for main actions. For example: &#34;Continue to next step&#34;.<br /><br />`secondary`: button used for secondary actions not blocking user progress. For example: &#34;Download Shop app&#34;.<br /><br />`plain`: renders a button that visually looks like a link.<br /><br />Default value: <code>'primary'</code> |
+| appearance?         | <code>"critical" &#124; "monochrome"</code>              | Specify the color treatment of the Button.<br /><br /><code>"critical"</code>: Use to convey a problem has arisen.<br /><br /><code>"monochrome"</code>: Will take the color of its parent                                                                                                                                                                                                                                                                                                         |
+| submit?             | <code>boolean</code>                                     | Allows the button to submit a form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| to?                 | <code>string</code>                                      | Destination URL to link to. If this value is set, the button will render as a Link.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| inlineAlignment?    | <code>"start" &#124; "center" &#124; "end"</code>        | Specifies the inline alignment of the content.<br /><br />Default value: <code>'center'</code>                                                                                                                                                                                                                                                                                                                                                                                                     |
+| loading?            | <code>boolean</code>                                     | Replaces content with a loading indicator.<br /><br />Default value: <code>false</code>                                                                                                                                                                                                                                                                                                                                                                                                            |
+| loadingLabel?       | <code>string</code>                                      | Accessible label for the loading indicator when user prefers reduced motion. This value is only used if `loading` is true.                                                                                                                                                                                                                                                                                                                                                                         |
+| accessibilityLabel? | <code>string</code>                                      | A label used for buyers using assistive technologies. When set, any `children` supplied to this component are hidden from being seen for accessibility purposes to prevent duplicate content from being read.                                                                                                                                                                                                                                                                                      |
+| accessibilityRole?  | <code>"button" &#124; "submit"</code>                    | The role of the button that will be rendered.<br /><br />`button`: renders a regular button.<br /><br />`submit`: renders a button that submits a form.<br /><br />Default value: <code>'button'</code>                                                                                                                                                                                                                                                                                            |
+| disabled?           | <code>boolean</code>                                     | Disables the button, disallowing any interaction.<br /><br />Default value: <code>false</code>                                                                                                                                                                                                                                                                                                                                                                                                     |
+| onPress?            | <code>() => void</code>                                  | Callback that is run when the button is pressed.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| overlay?            | <code>RemoteFragment</code>                              | An overlay component to render when the user interacts with the component.                                                                                                                                                                                                                                                                                                                                                                                                                         |

package/src/surfaces/checkout/components/Button/content/guidelines.md

@@ -0,0 +1,10 @@
+## Best practices
+
+- Make button labels clear, so that customers can predict the results of interacting with the button.
+- Use primary buttons for actions that progress customers through checkout, such as **Continue to shipping** and **Pay now**.
+- Use secondary buttons for actions that you want to draw attention to, but aren't primary, such as **Track your order**.
+- Use plain buttons when you want the appearance of a text link with the hit area of a button. This works well alongside other buttons to create hierarchies such as **Continue** and **Return to cart**.
+
+## Related components
+
+- [`Link`](https://github.com/Shopify/ui-extensions/tree/main/packages/checkout-ui-extensions/src/components/Link): Makes text interactive so that customers can perform an action, such as navigating to another location.

package/src/surfaces/checkout/components/Button/examples/basic-button.example.ts

@@ -0,0 +1,11 @@
+import {extend, Button} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const button = root.createComponent(
+    Button,
+    {onPress: () => console.log('onPress event')},
+    'Pay now',
+  );
+
+  root.appendChild(button);
+});

package/src/surfaces/checkout/components/Checkbox/Checkbox.ts

@@ -0,0 +1,63 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface CheckboxProps {
+  /**
+   * A unique identifier for the field. When no `id` is set,
+   * a globally unique value will be used instead.
+   */
+  id?: string;
+
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name?: string;
+
+  /**
+   * Whether the checkbox is active. This prop is an alias for `checked`,
+   * and can be useful in form libraries that provide a normalized API for
+   * dealing with both `boolean` and `string` values. If both `value` and
+   * `checked` are set, `checked` takes precedence.
+   */
+  value?: boolean;
+
+  /**
+   * Whether the checkbox is active.
+   */
+  checked?: boolean;
+
+  /**
+   * Whether the checkbox can be changed.
+   */
+  disabled?: boolean;
+
+  /**
+   * Indicate an error to the user. The field will be given a specific stylistic treatment
+   * to communicate problems that have to be resolved immediately.
+   */
+  error?: string;
+
+  /**
+   * A label to use for the field that will be used for buyers using
+   * assistive technologies. When set, any `children` supplied to
+   * this component are hidden from being seen for accessibility purposes
+   * to prevent duplicate content from being read.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * A callback that is run whenever the checkbox is changed. This callback
+   * is called with a boolean indicating whether the checkbox should now be
+   * active or inactive. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components),
+   * so you must store this value in state and reflect it back in the
+   * `checked` or `value` props.
+   */
+  onChange?(value: boolean): void;
+}
+
+/**
+ * Use checkboxes to give customers a single binary option, such as signing up for marketing, or agreeing to terms and conditions.
+ */
+export const Checkbox = createRemoteComponent<'Checkbox', CheckboxProps>(
+  'Checkbox',
+);

package/src/surfaces/checkout/components/Checkbox/README.md

@@ -0,0 +1,18 @@
+# Checkbox
+
+Use checkboxes to give customers a single binary option, such as signing up for marketing, or agreeing to terms and conditions.
+
+## Props
+
+optional = ?
+
+| Name                | Type                                  | Description                                                                                                                                                                                                                                                                                                                                               |
+| ------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id?                 | <code>string</code>                   | A unique identifier for the field. When no `id` is set, a globally unique value will be used instead.                                                                                                                                                                                                                                                     |
+| name?               | <code>string</code>                   | An identifier for the field that is unique within the nearest containing `Form` component.                                                                                                                                                                                                                                                                |
+| value?              | <code>boolean</code>                  | Whether the checkbox is active. This prop is an alias for `checked`, and can be useful in form libraries that provide a normalized API for dealing with both `boolean` and `string` values. If both `value` and `checked` are set, `checked` takes precedence.                                                                                            |
+| checked?            | <code>boolean</code>                  | Whether the checkbox is active.                                                                                                                                                                                                                                                                                                                           |
+| disabled?           | <code>boolean</code>                  | Whether the checkbox can be changed.                                                                                                                                                                                                                                                                                                                      |
+| error?              | <code>string</code>                   | Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.                                                                                                                                                                                                       |
+| accessibilityLabel? | <code>string</code>                   | A label to use for the field that will be used for buyers using assistive technologies. When set, any `children` supplied to this component are hidden from being seen for accessibility purposes to prevent duplicate content from being read.                                                                                                           |
+| onChange?           | <code>(value: boolean) => void</code> | A callback that is run whenever the checkbox is changed. This callback is called with a boolean indicating whether the checkbox should now be active or inactive. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store this value in state and reflect it back in the `checked` or `value` props. |

package/src/surfaces/checkout/components/Checkbox/content/guidelines.md

@@ -0,0 +1,9 @@
+## Best practices
+
+- Frame labels positively. For example, use **Turn on notifications** instead of **Turn off notifications**.
+- Be aware of any legal issues around checkboxes. For example, to comply with GDPR, marketing sign-up checkboxes should always be deselected by default.
+- Link to more information or include a subtitle as required to provide more explanation. Don’t rely on tooltips to explain a checkbox.
+
+## Related components
+
+- [`ChoiceList`](https://github.com/Shopify/checkout-web/tree/master/packages/checkout-ui-extensions/src/components/ChoiceList): Creates a group of related options for customers to choose from. `ChoiceList` can be made up of radio buttons or checkboxes.

package/src/surfaces/checkout/components/Checkbox/examples/basic-checkbox.example.ts

@@ -0,0 +1,11 @@
+import {extend, Checkbox} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const checkbox = root.createComponent(
+    Checkbox,
+    {id: 'checkbox', name: 'checkbox'},
+    'Save this information for next time',
+  );
+
+  root.appendChild(checkbox);
+});

package/src/surfaces/checkout/components/Choice/Choice.ts

@@ -0,0 +1,25 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ChoiceProps {
+  /**
+   * A unique identifier for the choice.
+   */
+  id: string;
+  /**
+   * Whether the choice can be changed.
+   */
+  disabled?: boolean;
+  /**
+   * A label to use for the choice that will be used for buyers using
+   * assistive technologies. When set, any `children` supplied to
+   * this component are hidden from being seen for accessibility purposes
+   * to prevent duplicate content from being read.
+   */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Options inside a `ChoiceList`.
+ * The wrapping `ChoiceList` component will dictate if the choice renders as radio buttons or checkboxes.
+ */
+export const Choice = createRemoteComponent<'Choice', ChoiceProps>('Choice');

package/src/surfaces/checkout/components/Choice/README.md

@@ -0,0 +1,14 @@
+# Choice
+
+Options inside a `ChoiceList`.
+The wrapping `ChoiceList` component will dictate if the choice renders as radio buttons or checkboxes.
+
+## Props
+
+optional = ?
+
+| Name                | Type                 | Description                                                                                                                                                                                                                                      |
+| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| id                  | <code>string</code>  | A unique identifier for the choice.                                                                                                                                                                                                              |
+| disabled?           | <code>boolean</code> | Whether the choice can be changed.                                                                                                                                                                                                               |
+| accessibilityLabel? | <code>string</code>  | A label to use for the choice that will be used for buyers using assistive technologies. When set, any `children` supplied to this component are hidden from being seen for accessibility purposes to prevent duplicate content from being read. |

package/src/surfaces/checkout/components/Choice/content/guidelines.md

@@ -0,0 +1,9 @@
+## Best practices
+
+- Include a title that either tells customers what to do or explains their available options.
+- Label options clearly based on what the option will do.
+- Avoid options that contradict each other when you're allowing for multiple selections.
+
+## Related components
+
+- [`ChoiceList`](https://github.com/Shopify/ui-extensions/tree/main/packages/checkout-ui-extensions/src/components/ChoiceList): Use choice lists to present a list of choices where buyers can make a single selection or multiple selections.

package/src/surfaces/checkout/components/Choice/examples/basic-choice.example.ts

@@ -0,0 +1,50 @@
+import {
+  extend,
+  ChoiceList,
+  Choice,
+  BlockStack,
+  InlineStack,
+} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const choiceList = root.createComponent(
+    ChoiceList,
+    {
+      name: 'choice',
+      value: 'first',
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [
+      root.createComponent(BlockStack, undefined, [
+        root.createComponent(Choice, {id: 'first'}, 'Ship'),
+        root.createComponent(Choice, {id: 'second'}, 'Pickup'),
+      ]),
+    ],
+  );
+
+  const multipleChoiceList = root.createComponent(
+    ChoiceList,
+    {
+      name: 'multipleChoice',
+      value: ['multipleFirst'],
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [
+      root.createComponent(BlockStack, undefined, [
+        root.createComponent(Choice, {id: 'multipleFirst'}, 'Gift message'),
+        root.createComponent(Choice, {id: 'multipleSecond'}, 'Gift wrapping'),
+      ]),
+    ],
+  );
+
+  const layout = root.createComponent(InlineStack, undefined, [
+    choiceList,
+    multipleChoiceList,
+  ]);
+
+  root.appendChild(layout);
+});

package/src/surfaces/checkout/components/ChoiceList/ChoiceList.ts

@@ -0,0 +1,33 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ChoiceListProps<T extends string | string[]> {
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name: string;
+  /**
+   * A `string` or `string[]` indicating the ids of selected choices. When
+   * a string is set, choices render as radios. When a string array is
+   * set, choices render as checkboxes.
+   */
+  value: T;
+  /**
+   * A callback that is run whenever the choice list is changed. This callback
+   * is called with a string or array of strings indicating the ids of choices
+   * that should now be selected. This component is
+   * [controlled](https://reactjs.org/docs/forms.html#controlled-components),
+   * so you must store this value in state and reflect it back in the
+   * `value` prop.
+   */
+  onChange(value: T): void;
+}
+
+/**
+ * Use choice lists to present a list of choices where buyers can make
+ * a single selection or multiple selections.
+ */
+export const ChoiceList = createRemoteComponent<
+  'ChoiceList',
+  ChoiceListProps<string | string[]>
+>('ChoiceList');

package/src/surfaces/checkout/components/ChoiceList/README.md

@@ -0,0 +1,14 @@
+# ChoiceList
+
+Use choice lists to present a list of choices where buyers can make
+a single selection or multiple selections.
+
+## Props
+
+optional = ?
+
+| Name     | Type                                                 | Description                                                                                                                                                                                                                                                                                                                                                |
+| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name     | <code>string</code>                                  | An identifier for the field that is unique within the nearest containing `Form` component.                                                                                                                                                                                                                                                                 |
+| value    | <code>string &#124; string[]</code>                  | A `string` or `string[]` indicating the ids of selected choices. When a string is set, choices render as radios. When a string array is set, choices render as checkboxes.                                                                                                                                                                                 |
+| onChange | <code>(value: string &#124; string[]) => void</code> | A callback that is run whenever the choice list is changed. This callback is called with a string or array of strings indicating the ids of choices that should now be selected. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store this value in state and reflect it back in the `value` prop. |

package/src/surfaces/checkout/components/ChoiceList/content/guidelines.md

@@ -0,0 +1,10 @@
+## Best practices
+
+- Include a title that either tells customers what to do or explains the available options.
+- Label options clearly based on what the option will do.
+- Avoid mutually exclusive options when you're allowing for multiple selections.
+
+## Related components
+
+- [`Choice`](https://github.com/Shopify/checkout-web/tree/master/packages/checkout-ui-extensions/src/components/Choice): The options inside the `ChoiceList` component.
+- [`Checkbox`](https://github.com/Shopify/checkout-web/tree/master/packages/checkout-ui-extensions/src/components/Checkbox): Gives customers a single binary option, such as signed up for marketing, or agreeing to terms and conditions.

package/src/surfaces/checkout/components/ChoiceList/examples/basic-choicelist.example.ts

@@ -0,0 +1,50 @@
+import {
+  extend,
+  ChoiceList,
+  Choice,
+  BlockStack,
+  InlineStack,
+} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const choiceList = root.createComponent(
+    ChoiceList,
+    {
+      name: 'choice',
+      value: 'first',
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [
+      root.createComponent(BlockStack, undefined, [
+        root.createComponent(Choice, {id: 'first'}, 'Ship'),
+        root.createComponent(Choice, {id: 'second'}, 'Pickup'),
+      ]),
+    ],
+  );
+
+  const multipleChoiceList = root.createComponent(
+    ChoiceList,
+    {
+      name: 'multipleChoice',
+      value: ['multipleFirst'],
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [
+      root.createComponent(BlockStack, undefined, [
+        root.createComponent(Choice, {id: 'multipleFirst'}, 'Gift message'),
+        root.createComponent(Choice, {id: 'multipleSecond'}, 'Gift wrapping'),
+      ]),
+    ],
+  );
+
+  const layout = root.createComponent(InlineStack, undefined, [
+    choiceList,
+    multipleChoiceList,
+  ]);
+
+  root.appendChild(layout);
+});

package/src/surfaces/checkout/components/Divider/Divider.ts

@@ -0,0 +1,33 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {Size, Alignment, Direction} from '../shared';
+
+export interface DividerProps {
+  /**
+   * Use to create dividers with varying widths.
+   *
+   * @defaultValue 'small'
+   */
+  size?: Extract<Size, 'small' | 'base' | 'large' | 'extraLarge'>;
+
+  /**
+   * Use to specify direction of divider.
+   *
+   * @defaultValue 'inline'
+   */
+  direction?: Direction;
+
+  /**
+   * Use to specify alignment of contents of divider.
+   *
+   * @defaultValue 'center'
+   */
+  alignment?: Alignment;
+}
+
+/**
+ * A divider separates content and represents a thematic break between elements.
+ */
+export const Divider = createRemoteComponent<'Divider', DividerProps>(
+  'Divider',
+);

package/src/surfaces/checkout/components/Divider/README.md

@@ -0,0 +1,13 @@
+# Divider
+
+A divider separates content and represents a thematic break between elements.
+
+## Props
+
+optional = ?
+
+| Name       | Type                                                                  | Description                                                                                      |
+| ---------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| size?      | <code>"small" &#124; "base" &#124; "large" &#124; "extraLarge"</code> | Use to create dividers with varying widths.<br /><br />Default value: <code>'small'</code>       |
+| direction? | <code>"inline" &#124; "block"</code>                                  | Use to specify direction of divider.<br /><br />Default value: <code>'inline'</code>             |
+| alignment? | <code>"start" &#124; "center" &#124; "end"</code>                     | Use to specify alignment of contents of divider.<br /><br />Default value: <code>'center'</code> |

package/src/surfaces/checkout/components/Divider/examples/basic-divider.example.ts

@@ -0,0 +1,7 @@
+import {extend, Divider} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const divider = root.createComponent(Divider);
+
+  root.appendChild(divider);
+});

package/src/surfaces/checkout/components/Form/Form.ts

@@ -0,0 +1,30 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface FormProps {
+  /**
+   * Whether the form is able to be submitted. When set to `true`, this will
+   * disable the implicit submit behavior of the form.
+   */
+  disabled?: boolean;
+  /**
+   * A callback that is run when the form is submitted.
+   */
+  onSubmit(): void;
+  /**
+   * An optional override for the autogenerated form ID.
+   */
+  id?: string;
+}
+
+/**
+ * The form component should be used to wrap one or more form controls. This
+ * component provides an "implicit submit" behavior, where customers can submit
+ * the form from any input by pressing "Enter" on their keyboards. This
+ * behavior is widely expected, and should be respected as often as possible.
+ *
+ * Unlike an HTML `form` element, this component does not support configuring
+ * the descendant fields to be submitted via HTTP automatically. Instead, you
+ * must provide an `onSubmit` callback that will perform the necessary HTTP
+ * requests in JavaScript.
+ */
+export const Form = createRemoteComponent<'Form', FormProps>('Form');

package/src/surfaces/checkout/components/Form/README.md

@@ -0,0 +1,21 @@
+# Form
+
+The form component should be used to wrap one or more form controls. This
+component provides an "implicit submit" behavior, where customers can submit
+the form from any input by pressing "Enter" on their keyboards. This
+behavior is widely expected, and should be respected as often as possible.
+
+Unlike an HTML `form` element, this component does not support configuring
+the descendant fields to be submitted via HTTP automatically. Instead, you
+must provide an `onSubmit` callback that will perform the necessary HTTP
+requests in JavaScript.
+
+## Props
+
+optional = ?
+
+| Name      | Type                    | Description                                                                                                               |
+| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| disabled? | <code>boolean</code>    | Whether the form is able to be submitted. When set to `true`, this will disable the implicit submit behavior of the form. |
+| onSubmit  | <code>() => void</code> | A callback that is run when the form is submitted.                                                                        |
+| id?       | <code>string</code>     | An optional override for the autogenerated form ID.                                                                       |

package/src/surfaces/checkout/components/Form/content/guidelines.md

@@ -0,0 +1,4 @@
+## Best practices
+
+- Wrap around all form input elements.
+- Forms can have only one submit button and it must be at the end of the form.

package/src/surfaces/checkout/components/Form/examples/basic-form.example.ts

@@ -0,0 +1,48 @@
+import {
+  extend,
+  BlockSpacer,
+  Button,
+  Form,
+  Grid,
+  GridItem,
+  TextField,
+  View,
+} from '@shopify/ui-extensions/checkout';
+
+extend('Checkout::Dynamic::Render', (root) => {
+  const fields = root.createComponent(
+    Grid,
+    {columns: ['50%', '50%'], spacing: 'base'},
+    [
+      root.createComponent(
+        View,
+        undefined,
+        root.createComponent(TextField, {label: 'First name'}),
+      ),
+      root.createComponent(
+        View,
+        undefined,
+        root.createComponent(TextField, {label: 'Last name'}),
+      ),
+      root.createComponent(
+        GridItem,
+        {columnSpan: 2},
+        root.createComponent(TextField, {label: 'Company'}),
+      ),
+    ],
+  );
+  const spacer = root.createComponent(BlockSpacer, {spacing: 'base'});
+  const button = root.createComponent(
+    Button,
+    {accessibilityRole: 'submit'},
+    'Submit',
+  );
+
+  const form = root.createComponent(
+    Form,
+    {onSubmit: () => console.log('onSubmit event')},
+    [fields, spacer, button],
+  );
+
+  root.appendChild(form);
+});