@shopify/ui-extensions 2024.4.0 → 2024.4.2

package/src/surfaces/checkout/api/standard/standard.ts

@@ -72,7 +72,7 @@ export type Capability =
   | 'collect_buyer_consent.customer_privacy';
 
 /**
- * Meta information about an extension target.
+ * The meta information about an extension target.
  */
 export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
@@ -90,31 +90,31 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
    *
-   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a customer's progress and the merchant has allowed this blocking behavior.
    *
-   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
+   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect customer consent for SMS marketing.
    *
-   * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register buyer consent decisions that will be honored on Shopify-managed services.
+   * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register customer consent decisions that will be honored on Shopify-managed services.
    */
   capabilities: StatefulRemoteSubscribable<Capability[]>;
 
   /**
    * Information about the editor where the extension is being rendered.
    *
-   * The value is undefined if the extension is not rendering in an editor.
+   * If the value is undefined, then the extension is not running in an editor.
    */
   editor?: Editor;
 
   /**
-   * Whether your extension is currently rendered to the screen.
+   * A Boolean to show whether your extension is currently rendered to the screen.
    *
    * Shopify might render your extension before it's visible in the UI,
    * typically to pre-render extensions that will appear on a later step of the
    * checkout.
    *
-   * Your extension might also continue to run after the buyer has navigated away
+   * Your extension might also continue to run after the customer has navigated away
    * from where it was rendered. The extension continues running so that
-   * your extension is immediately available to render if the buyer navigates back.
+   * your extension is immediately available to render if the customer navigates back.
    */
   rendered: StatefulRemoteSubscribable<boolean>;
 
@@ -368,7 +368,7 @@ export interface Market {
 
 export interface Localization {
   /**
-   * The currency that the buyer sees for money amounts in the checkout.
+   * The currency that the customer sees for money amounts in the checkout.
    */
   currency: StatefulRemoteSubscribable<Currency>;
 
@@ -378,19 +378,19 @@ export interface Localization {
   timezone: StatefulRemoteSubscribable<Timezone>;
 
   /**
-   * The language the buyer sees in the checkout.
+   * The language the customer sees in the checkout.
    */
   language: StatefulRemoteSubscribable<Language>;
 
   /**
-   * This is the buyer's language, as supported by the extension.
-   * If the buyer's actual language is not supported by the extension,
-   * this is the fallback locale used for translations.
+   * This is the customer's language, as supported by the extension.
+   * If the customer's actual language is not supported by the extension,
+   * then this is the language that is used for translations.
    *
-   * For example, if the buyer's language is 'fr-CA' but your extension
+   * For example, if the customer's language is 'fr-CA' but your extension
    * only supports translations for 'fr', then the `isoCode` for this
    * language is 'fr'. If your extension does not provide french
-   * translations at all, this value is the default locale for your
+   * translations at all, then this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
   extensionLanguage: StatefulRemoteSubscribable<Language>;
@@ -399,7 +399,7 @@ export interface Localization {
    * The country context of the checkout. This value carries over from the
    * context of the cart, where it was used to contextualize the storefront
    * experience. It will update if the buyer changes the country of their
-   * shipping address. The value is undefined if unknown.
+   * shipping address. If the country is unknown, then the value is undefined.
    */
   country: StatefulRemoteSubscribable<Country | undefined>;
 
@@ -407,8 +407,8 @@ export interface Localization {
    * The [market](https://shopify.dev/docs/apps/markets) context of the
    * checkout. This value carries over from the context of the cart, where it
    * was used to contextualize the storefront experience. It will update if the
-   * buyer changes the country of their shipping address. The value is undefined
-   * if unknown.
+   * buyer changes the country of their shipping address.  If the market is unknown,
+   * then the value is undefined.
    */
   market: StatefulRemoteSubscribable<Market | undefined>;
 }
@@ -500,7 +500,7 @@ export interface BuyerJourneyStep {
 
 export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   * The methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
    */
   analytics: Analytics;
 
@@ -523,7 +523,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   appMetafields: StatefulRemoteSubscribable<AppMetafieldEntry[]>;
 
   /**
-   * Custom attributes left by the customer to the merchant, either in their cart or during checkout.
+   * The custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */
   attributes: StatefulRemoteSubscribable<Attribute[] | undefined>;
 
@@ -542,7 +542,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Provides details on the buyer's progression through the checkout.
    *
-   * See [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/apis/buyer-journey#examples)
+   * Refer to [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/apis/buyer-journey#examples)
    * examples for more information.
    */
   buyerJourney: BuyerJourney;
@@ -553,10 +553,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   checkoutSettings: StatefulRemoteSubscribable<CheckoutSettings>;
 
   /**
-   * A stable id that represents the current checkout.
+   * A stable ID that represents the current checkout.
    *
    * Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout)
-   * and the `checkout_token` field in the [Admin REST API Order resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
+   * and the `checkout_token` field in the [REST Admin API `Order` resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
    */
   checkoutToken: StatefulRemoteSubscribable<CheckoutToken | undefined>;
 
@@ -581,7 +581,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   discountAllocations: StatefulRemoteSubscribable<CartDiscountAllocation[]>;
 
   /**
-   * Meta information about the extension.
+   * The meta information about the extension.
    */
   extension: Extension<Target>;
 
@@ -603,7 +603,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization)
    * of the checkout.
    *
-   * See [localization examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples)
+   * Refer to [`localization` examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples)
    * for more information.
    */
   i18n: I18n;
@@ -614,7 +614,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   lines: StatefulRemoteSubscribable<CartLine[]>;
 
   /**
-   * Details about the location, language, and currency of the buyer. For utilities to easily
+   * The details about the location, language, and currency of the customer. For utilities to easily
    * format and translate content based on these details, you can use the
    * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-i18n)
    * object instead.
@@ -640,9 +640,9 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   note: StatefulRemoteSubscribable<string | undefined>;
 
   /**
-   * Used to query the Storefront GraphQL API with a prefetched token.
+   * The method used to query the Storefront GraphQL API with a prefetched token.
    *
-   * See [storefront api access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information.
+   * Refer to [Storefront API access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information.
    */
   query: <Data = unknown, Variables = Record<string, unknown>>(
     query: string,
@@ -655,9 +655,13 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   selectedPaymentOptions: StatefulRemoteSubscribable<SelectedPaymentOption[]>;
 
   /**
-   * Provides access to session tokens, which can be used to verify token claims on your app's server.
+   * The session token providing a set of claims as a signed JSON Web Token (JWT).
    *
-   * See [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information.
+   * The token has a TTL of 5 minutes.
+   *
+   * If the previous token expires, this value will reflect a new session token with a new signature and expiry.
+   *
+   * Refer to [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information.
    */
   sessionToken: SessionToken;
 
@@ -665,7 +669,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * The settings matching the settings definition written in the
    * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
    *
-   *  See [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings) for more information.
+   *  Refer to [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings#examples) for more information.
    *
    * > Note: When an extension is being installed in the editor, the settings will be empty until
    * a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.
@@ -673,7 +677,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   settings: StatefulRemoteSubscribable<ExtensionSettings>;
 
   /**
-   * The proposed buyer shipping address. During the information step, the address
+   * The proposed customer shipping address. During the information step, the address
    * updates when the field is committed (on change) rather than every keystroke.
    * An address value is only present if delivery is required. Otherwise, the
    * subscribable value is undefined.
@@ -683,22 +687,24 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   shippingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
 
   /**
-   * The proposed buyer billing address. The address updates when the field is
+   * The proposed customer billing address. The address updates when the field is
    * committed (on change) rather than every keystroke.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   billingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
 
-  /** Shop where the checkout is taking place. */
+  /** The shop where the checkout is taking place. */
   shop: Shop;
 
   /**
-   * Key-value storage for the extension.
-   * Uses `localStorage` and should persist across the buyer's current checkout session.
-   * However, data persistence isn't guaranteed and storage is reset when the buyer starts a new checkout.
+   * The key-value storage for the extension.
+   *
+   * It uses `localStorage` and should persist across the customer's current checkout session.
    *
-   * Data is shared across all activated extension targets of this extension. In versions `<=2023-07`,
+   * > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
+   *
+   * Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier,
    * each activated extension target had its own storage.
    */
   storage: Storage;
@@ -716,12 +722,16 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   version: Version;
 
   /**
-   * Customer cookie consent settings and a flag denoting if consent has previously been collected.
+   * Customer privacy consent settings and a flag denoting if consent has previously been collected.
    */
   customerPrivacy: StatefulRemoteSubscribable<CustomerPrivacy>;
 
   /**
-   * Allows setting and updating customer cookie consent settings.
+   * Allows setting and updating customer privacy consent settings and tracking consent metafields.
+   *
+   * > Note: Requires the [`customer_privacy` capability](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/configuration#collect-buyer-consent) to be set to `true`.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   applyTrackingConsentChange: ApplyTrackingConsentChangeType;
 }
@@ -778,7 +788,7 @@ export interface BuyerIdentity {
 }
 
 /**
- * Information about a company that the business customer is purchasing on behalf of.
+ * The information about a company that the business customer is purchasing on behalf of.
  */
 export interface PurchasingCompany {
   /**
@@ -1149,7 +1159,7 @@ export interface SelectedPaymentOption {
   /**
    * The unique handle referencing `PaymentOption.handle`.
    *
-   * See [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/apis/payments#standardapi-propertydetail-availablepaymentoptions).
+   * Refer to [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/apis/payments#standardapi-propertydetail-availablepaymentoptions).
    */
   handle: string;
 }
@@ -1413,7 +1423,7 @@ export interface PaymentTermsTemplate {
    */
   id: string;
   /**
-   * The name of the payment terms translated to the buyer's current language. See [localization.language](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-localization).
+   * The name of the payment terms translated to the buyer's current language. Refer to [localization.language](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-localization).
    */
   name: string;
   /**
@@ -1734,28 +1744,81 @@ export interface DeliveryGroupDetails extends DeliveryGroup {
   targetedCartLines: CartLine[];
 }
 
+export interface AllowedProcessing {
+  /**
+   * Can collect customer analytics about how the shop was used and interactions made on the shop.
+   */
+  analytics: boolean;
+  /**
+   * Can collect customer preference for marketing, attribution and targeted advertising from the merchant.
+   */
+  marketing: boolean;
+  /**
+   * Can collect customer preferences such as language, currency, size, and more.
+   */
+  preferences: boolean;
+  /**
+   * Can collect customer preference for sharing data with third parties, usually for behavioral advertising.
+   */
+  saleOfData: boolean;
+}
+
 export interface VisitorConsent {
   /**
-   * Cookies to understand how customers interact with the site.
+   * Visitor consents to recording data to understand how customers interact with the site.
    */
   analytics?: boolean;
   /**
-   * Cookies to provide ads and marketing communications based on customer interests.
+   * Visitor consents to ads and marketing communications based on customer interests.
    */
   marketing?: boolean;
   /**
-   * Cookies that remember customer preferences, such as country or language, to personalize visits to the website.
+   * Visitor consent to remembering customer preferences, such as country or language, to personalize visits to the website.
    */
   preferences?: boolean;
   /**
-   * Opts the customer out of data sharing / sales.
+   * Opts the visitor out of data sharing / sales.
    */
   saleOfData?: boolean;
 }
 
-type PartialVisitorConsent = Partial<VisitorConsent>;
+export interface TrackingConsentMetafield {
+  /**
+   * The name of the metafield. It must be between 3 and 30 characters in
+   * length (inclusive).
+   */
+  key: string;
+  /**
+   * The information to be stored as metadata.
+   *
+   * @example 'any string', '', or a stringified JSON object
+   */
+  value: string;
+}
+
+export interface TrackingConsentMetafieldChange {
+  /**
+   * The name of the metafield. It must be between 3 and 30 characters in
+   * length (inclusive).
+   */
+  key: string;
+  /**
+   * The information to be stored as metadata. If the value is `null`, the metafield will be deleted.
+   *
+   * @example 'any string', `null`, or a stringified JSON object
+   */
+  value: string | null;
+}
 
-export interface VisitorConsentChange extends PartialVisitorConsent {
+export interface VisitorConsentChange extends VisitorConsent {
+  /**
+   * Tracking consent metafield data to be saved.
+   *
+   * If the value is `null`, the metafield will be deleted.
+   *
+   * @example `[{key: 'granularAnalytics', value: 'true'}, {key: 'granularMarketing', value: 'false'}]`
+   */
+  metafields?: TrackingConsentMetafieldChange[];
   type: 'changeVisitorConsent';
 }
 
@@ -1786,11 +1849,25 @@ export interface CustomerPrivacyRegion {
 
 export interface CustomerPrivacy {
   /**
-   * An object containing the customer's current cookie consent settings.
+   * An object containing flags for each consent property denoting whether they can be processed based on visitor consent, merchant configuration, and user location.
+   */
+  allowedProcessing: AllowedProcessing;
+  /**
+   * Stored tracking consent metafield data.
+   *
+   * @example `[{key: 'analyticsType', value: 'granular'}, {key: 'marketingType', value: 'granular'}]`, or `[]`
+   */
+  metafields: TrackingConsentMetafield[];
+  /**
+   * An object containing the customer's current privacy consent settings.
+   * *
+   * @example `true` — the customer has actively granted consent, `false` — the customer has actively denied consent, or `undefined` — the customer has not yet made a decision.
    */
   visitorConsent: VisitorConsent;
   /**
-   * Whether a consent banner should be displayed.
+   * Whether a consent banner should be displayed by default when the page loads. Use this as the initial open/expanded state of the consent banner.
+   *
+   * This is determined by the visitor's current privacy consent, the shop's [region visibility configuration](https://help.shopify.com/en/manual/privacy-and-security/privacy/customer-privacy-settings/privacy-settings#add-a-cookie-banner) settings, and the region in which the visitor is located.
    */
   shouldShowBanner: boolean;
   /**

package/src/surfaces/checkout/components/Sheet/Sheet.doc.ts

@@ -0,0 +1,69 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Sheet',
+  description:
+    'The Sheet component displays essential information for customers at the bottom of the screen, appearing above other elements. Use it sparingly to avoid distracting customers during checkout. This component requires access to [Customer Privacy API](/docs/api/checkout-ui-extensions/unstable/configuration#collect-buyer-consent) to be rendered. \n\nThe library automatically applies the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the activator and the sheet content.',
+  requires:
+    'configuration of the [Customer Privacy](/docs/api/checkout-ui-extensions/unstable/configuration#collect-buyer-consent) capability to be rendered.',
+  thumbnail: 'sheet-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'SheetProps',
+      description: '',
+      type: 'SheetProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Overlays',
+  defaultExample: {
+    image: 'sheet-default.png',
+    codeblock: {
+      title: 'Basic Sheet',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Sheet/examples/basic-sheet.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-sheet.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'shopify-controlled-surfaces',
+      title: 'Shopify-controlled surfaces',
+      sectionContent:
+        'To prevent disruptions during checkout, we maintain strict design control over key areas of the Sheet component. These Shopify-controlled elements include: \n\n<h3>Locations of elements</h3>\n\nThe Sheet elements (header, content, action buttons, and dismiss button) are strategically positioned and sized to present vital information upfront.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces1.png" />\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces2.png" />\n\n<br>\n\n<h3>Padding and spacing</h3>\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces3.png" />\n\n<br>\n\n<h3>Maximum height</h3>\n\nTo balance customer attention and task completion, a maximum height is set for the Sheet component.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces4.png" />\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces5.png" />\n\nWhen content pushes the sheet to exceed this limit, the following UI behaviors are triggered:\n\n<br>\n\n<h3>Heading and content are scrollable</h3>\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces6.png" />\n\n<br>\n\n<h3>Expand pill appears to allow customers to view the entire content</h3>\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces7.png" />\n\n<br>\n\n<h3>Actions slot and dismiss button remain fixed</h3>\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-controlled-surfaces8.png" />',
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'privacy-consent-requirements',
+      title: 'Privacy consent requirements',
+      sectionContent:
+        '<h3>Content</h3>\n\nFor the best customer experience, ensure content is brief and to the point.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations1.png" />\n\nVarious strategies can be employed to avoid content scrolling.\n\n<br>\n\n<h4>Use short content</h4>\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations2.png" />\n\n<br>\n\n<h4>Use small text size</h4>\n\n <img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations3.png" />\n\n<br>\n\n<h4>Remove the header</h4>\n\n <img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations4.png" />\n\n<br>\n\n<h3>Actions slot</h3>\n\nThe actions slots allows customers to make decisions and is split into primary and secondary sections.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations5.png" />\n\n<br>\n\n<h3>Primary section</h3>\n\n Contains primary actions for customer decisions on the sheet’s prompt. Up to two buttons are allowed. Keep the button’s content brief so that it doesn’t wrap to more than one line.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations6.png" />\n\n<br>\n\n<h3>Secondary section</h3>\n\nContains action that is unrelated to the sheet’s prompt. Only one button is allowed. A modal can be activated when engaging with the secondary action. Keep the button’s content brief so that it doesn’t wrap to more than one line.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations7.png" />\n\n<br>\n\n<h3>Consent, denial of consent, and sheet dismissal</h3>\n\n <h4>Consent</h4>\n\nWhen a customer expresses consent by pressing the acceptance button, cookies will load and the sheet should not re-appear on refresh.\n\n<br>\n\n<h4>Denial of consent</h4>\n\nWhen a customer expresses denial of consent by pressing the rejection button, cookies will not load and the sheet will not re-appear on refresh.\n\n<br>\n\n<h4>Sheet dismissal</h4>\n\nWhen a customer neither grants nor denies consent by pressing the dismiss button, cookies will not load and the sheet will re-appear on refresh.\n\n<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/sheet-content-recommendations8.png" />',
+    },
+  ],
+  examples: {
+    description: '',
+    examples: [
+      getExample('ui-components/sheet-consent', ['jsx', 'js']),
+      getExample('ui-components/sheet-description-preferences', ['jsx', 'js']),
+      getExample('ui-components/sheet-icon-button-preferences', ['jsx', 'js']),
+      getExample('ui-components/sheet-layout-content', ['jsx', 'js']),
+    ],
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,56 @@
+import type {RemoteFragment} from '@remote-ui/core';
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {IdProps} from '../shared';
+
+export interface SheetProps extends IdProps {
+  /**
+   * A label to describe the purpose of the sheet that is announced by screen readers.
+   * If not set, it will use the value of `heading`.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Indicates whether the sheet should be open by default.
+   *
+   * This property is necessary in some cases, but its usage is generally discouraged due to potential negative impacts on user experience.
+   *
+   * Developers should:
+   * - Only set this property to true when there are vitally important behaviors of the application that depend on the user interacting with the sheet.
+   * - Make every effort to conditionally hide the sheet based on the state of checkout. An explicit example is custom privacy consent, where the sheet should only be displayed when consent is necessary and has not yet been explicitly given by the user.
+   *
+   * This property is useful for when the Sheet needs to be rendered on the page load and not triggered by a user action.
+   * The property should only take effect when the `Sheet` is rendered for the first time.
+   */
+  defaultOpen?: boolean;
+
+  /** A heading rendered at the top of the sheet. */
+  heading?: string;
+
+  /** Callback fired when the sheet is opened. */
+  onShow?(): void;
+
+  /** Callback fired when the sheet is closed. */
+  onHide?(): void;
+
+  /**
+   * The primary action to perform, provided as a `Button` component.
+   * The property allows up to two buttons to be rendered.
+   */
+  primaryAction?: RemoteFragment;
+
+  /**
+   * The secondary action to perform, provided as a `Button` component.
+   * The property allows only one button to be rendered.
+   */
+  secondaryAction?: RemoteFragment;
+}
+
+/**
+ * Sheet is designed to be used on top of other elements in a user interface and is typically bound to the bottom of a page.
+ * Sheet can contain and display various types of content such as forms, or informational messages.
+ * Unlike a Modal, which interrupts user flow, a Sheet offers a less intrusive, fluid experience.
+ *
+ * The library automatically applies the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the activator and the sheet content.
+ */
+export const Sheet = createRemoteComponent<'Sheet', SheetProps>('Sheet');

package/src/surfaces/checkout/components/Sheet/examples/basic-sheet.example.ts

@@ -0,0 +1,29 @@
+import {
+  extension,
+  Link,
+  Sheet,
+  TextBlock,
+} from '@shopify/ui-extensions/checkout';
+
+// This component requires access to Customer Privacy API to be rendered.
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const sheetFragment = root.createFragment();
+  const sheet = root.createComponent(
+    Sheet,
+    {
+      id: 'basic-sheet',
+      heading: 'Basic Sheet',
+      accessibilityLabel: 'A sheet with text content',
+    },
+    [root.createComponent(TextBlock, undefined, 'Basic Sheet Content')],
+  );
+  sheetFragment.appendChild(sheet);
+  const link = root.createComponent(
+    Link,
+    {overlay: sheetFragment},
+    'Open sheet',
+  );
+
+  root.appendChild(link);
+});

package/src/surfaces/checkout/components.ts

@@ -140,6 +140,9 @@ export type {
 export {Select} from './components/Select/Select';
 export type {SelectProps, SelectOptionProps} from './components/Select/Select';
 
+export {Sheet} from './components/Sheet/Sheet';
+export type {SheetProps} from './components/Sheet/Sheet';
+
 export {SkeletonImage} from './components/SkeletonImage/SkeletonImage';
 export type {SkeletonImageProps} from './components/SkeletonImage/SkeletonImage';
 

package/src/surfaces/checkout/helper.docs.ts

@@ -110,6 +110,45 @@ export function getExamples(
         tabs: getExtensionCodeTabs('ui-components/choicelist-time-picking'),
       },
     },
+    'ui-components/sheet-consent': {
+      description:
+        'The Sheet component can be used to display privacy consent preferences in the Checkout interface. Sheet can be defaulted to open for this use case.\n\n This component requires access to [Customer Privacy API](/docs/api/checkout-ui-extensions/unstable/apis/customer-privacy) to be rendered.',
+      codeblock: {
+        title: 'Using Sheet to display consent preferences',
+        tabs: getExtensionCodeTabs('ui-components/sheet-consent'),
+      },
+    },
+    'ui-components/sheet-description-preferences': {
+      description:
+        'In order to save space in the action slot, secondary actions can be placed in the content area.',
+      image: 'sheet-description-preferences.png',
+      codeblock: {
+        title: 'Preferences button is in the description as a link',
+        tabs: getExtensionCodeTabs(
+          'ui-components/sheet-description-preferences',
+        ),
+      },
+    },
+    'ui-components/sheet-layout-content': {
+      description:
+        'The description can take in layout components to allow for different types of content to be structured in specific ways.',
+      image: 'sheet-layout-content.png',
+      codeblock: {
+        title: 'Using layout component in the description ',
+        tabs: getExtensionCodeTabs('ui-components/sheet-layout-content'),
+      },
+    },
+    'ui-components/sheet-icon-button-preferences': {
+      description:
+        'An icon button can be used in the secondary actions area to allow for more space for the primary actions.',
+      image: 'sheet-icon-button-preferences.png',
+      codeblock: {
+        title: 'Icon button used for preferences',
+        tabs: getExtensionCodeTabs(
+          'ui-components/sheet-icon-button-preferences',
+        ),
+      },
+    },
   };
 }