@shopify/ui-extensions 2025.10.0-rc.37 → 2025.10.0-rc.38

package/src/surfaces/admin/docs-types.ts

@@ -1,8 +1,12 @@
+import type {CSSProperties} from 'react';
 import {
   ReferenceEntityTemplateSchema,
   CodeTabType,
 } from '@shopify/generate-docs';
 
+// Don't allow all CSS properties to be used in the customStyles property
+type AllowedCSSProperties = Pick<CSSProperties, 'minHeight' | 'minBlockSize'>;
+
 export interface AdminReferenceEntityTemplateSchema
   extends Omit<ReferenceEntityTemplateSchema, 'defaultExample'> {
   defaultExample?: Omit<
@@ -11,7 +15,10 @@ export interface AdminReferenceEntityTemplateSchema
   > & {
     codeblock?: {
       title: string;
-      tabs: (CodeTabType & {layout?: string})[];
+      tabs: (CodeTabType & {
+        layout?: string;
+        customStyles?: AllowedCSSProperties;
+      })[];
     };
   };
 }

package/src/surfaces/customer-account/api/cart-line/cart-line-item.ts

@@ -1,9 +1,9 @@
 import {CartLine} from '../order-status/order-status';
-import {ReadonlySignalLike} from '../shared';
+import {SubscribableSignalLike} from '../shared';
 
 export interface CartLineItemApi {
   /**
    * The cart line the extension is attached to.
    */
-  target: ReadonlySignalLike<CartLine>;
+  target: SubscribableSignalLike<CartLine>;
 }

package/src/surfaces/customer-account/api/order-status/order-status.ts

@@ -6,7 +6,7 @@ import type {
   Attribute,
   MailingAddress,
   Language,
-  ReadonlySignalLike,
+  SubscribableSignalLike,
 } from '../shared';
 import type {ExtensionTarget} from '../../extension-targets';
 import {Extension} from '../shared';
@@ -137,17 +137,17 @@ export interface OrderStatusLocalization {
   /**
    * The currency that the buyer sees for money amounts in the checkout.
    */
-  currency: ReadonlySignalLike<Currency>;
+  currency: SubscribableSignalLike<Currency>;
 
   /**
    * The buyer’s time zone.
    */
-  timezone: ReadonlySignalLike<Timezone>;
+  timezone: SubscribableSignalLike<Timezone>;
 
   /**
    * The language the buyer sees in the checkout.
    */
-  language: ReadonlySignalLike<Language>;
+  language: SubscribableSignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -160,7 +160,7 @@ export interface OrderStatusLocalization {
    * translations at all, this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
-  extensionLanguage: ReadonlySignalLike<Language>;
+  extensionLanguage: SubscribableSignalLike<Language>;
 
   /**
    * The country context of the checkout. This value carries over from the
@@ -168,7 +168,7 @@ export interface OrderStatusLocalization {
    * experience. It will update if the buyer changes the country of their
    * shipping address. The value is undefined if unknown.
    */
-  country: ReadonlySignalLike<Country | undefined>;
+  country: SubscribableSignalLike<Country | undefined>;
 
   /**
    * The [market](https://shopify.dev/docs/apps/markets) context of the
@@ -177,7 +177,7 @@ export interface OrderStatusLocalization {
    * buyer changes the country of their shipping address. The value is undefined
    * if unknown.
    */
-  market: ReadonlySignalLike<Market | undefined>;
+  market: SubscribableSignalLike<Market | undefined>;
 }
 
 export type AuthenticationState = 'fully_authenticated' | 'pre_authenticated';
@@ -186,7 +186,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * Gift Cards that have been applied to the order.
    */
-  appliedGiftCards: ReadonlySignalLike<AppliedGiftCard[]>;
+  appliedGiftCards: SubscribableSignalLike<AppliedGiftCard[]>;
 
   /**
    * The metafields requested in the
@@ -196,12 +196,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  appMetafields: ReadonlySignalLike<AppMetafieldEntry[]>;
+  appMetafields: SubscribableSignalLike<AppMetafieldEntry[]>;
 
   /**
    * Custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */
-  attributes: ReadonlySignalLike<Attribute[] | undefined>;
+  attributes: SubscribableSignalLike<Attribute[] | undefined>;
 
   /**
    * Information about the buyer that is interacting with the order.
@@ -213,7 +213,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * Settings applied to the buyer's checkout.
    */
-  checkoutSettings: ReadonlySignalLike<CheckoutSettings>;
+  checkoutSettings: SubscribableSignalLike<CheckoutSettings>;
 
   /**
    * Details on the costs of the purchase for the buyer.
@@ -223,12 +223,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of discount codes applied to the purchase.
    */
-  discountCodes: ReadonlySignalLike<CartDiscountCode[]>;
+  discountCodes: SubscribableSignalLike<CartDiscountCode[]>;
 
   /**
    * Discounts that have been applied to the entire cart.
    */
-  discountAllocations: ReadonlySignalLike<CartDiscountAllocation[]>;
+  discountAllocations: SubscribableSignalLike<CartDiscountAllocation[]>;
 
   /**
    * Meta information about the extension.
@@ -251,7 +251,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of lines containing information about the items the customer intends to purchase.
    */
-  lines: ReadonlySignalLike<CartLine[]>;
+  lines: SubscribableSignalLike<CartLine[]>;
 
   /**
    * Details about the location, language, and currency of the buyer. For utilities to easily
@@ -281,17 +281,17 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * Once the order is created, you can query these metafields using the
    * [GraphQL Admin API](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)
    */
-  metafields: ReadonlySignalLike<Metafield[]>;
+  metafields: SubscribableSignalLike<Metafield[]>;
 
   /**
    * A note left by the customer to the merchant, either in their cart or during checkout.
    */
-  note: ReadonlySignalLike<string | undefined>;
+  note: SubscribableSignalLike<string | undefined>;
 
   /**
    * Information about the order that was placed.
    */
-  order: ReadonlySignalLike<Order | undefined>;
+  order: SubscribableSignalLike<Order | undefined>;
 
   /**
    * id that represents the checkout used to create the order.
@@ -299,21 +299,21 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * 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).
    */
-  checkoutToken: ReadonlySignalLike<CheckoutToken | undefined>;
+  checkoutToken: SubscribableSignalLike<CheckoutToken | undefined>;
 
   /**
    * The buyer shipping address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  shippingAddress?: ReadonlySignalLike<MailingAddress | undefined>;
+  shippingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /**
    * The buyer billing address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  billingAddress?: ReadonlySignalLike<MailingAddress | undefined>;
+  billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /** Shop where the purchase took place. */
   shop: Shop;
@@ -333,7 +333,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * The authentication state of Order status page.
    */
-  authenticationState: ReadonlySignalLike<AuthenticationState>;
+  authenticationState: SubscribableSignalLike<AuthenticationState>;
 }
 
 export interface OrderStatusBuyerIdentity {
@@ -343,7 +343,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  customer: ReadonlySignalLike<OrderStatusCustomer | undefined>;
+  customer: SubscribableSignalLike<OrderStatusCustomer | undefined>;
 
   /**
    * The email address of the buyer that is interacting with the cart.
@@ -351,7 +351,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  email: ReadonlySignalLike<string | undefined>;
+  email: SubscribableSignalLike<string | undefined>;
 
   /**
    * The phone number of the buyer that is interacting with the cart.
@@ -359,7 +359,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  phone: ReadonlySignalLike<string | undefined>;
+  phone: SubscribableSignalLike<string | undefined>;
 
   /**
    * Provides details of the company and the company location that the business customer is purchasing on behalf of.
@@ -368,7 +368,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  purchasingCompany: ReadonlySignalLike<
+  purchasingCompany: SubscribableSignalLike<
     OrderStatusPurchasingCompany | undefined
   >;
 }
@@ -479,28 +479,28 @@ export interface CartCost {
    * A `Money` value representing the subtotal value of the items in the cart at the current
    * step of checkout.
    */
-  subtotalAmount: ReadonlySignalLike<Money>;
+  subtotalAmount: SubscribableSignalLike<Money>;
 
   /**
    * A `Money` value representing the total shipping a buyer can expect to pay at the current
    * step of checkout. This value includes shipping discounts. Returns undefined if shipping
    * has not been negotiated yet, such as on the information step.
    */
-  totalShippingAmount: ReadonlySignalLike<Money | undefined>;
+  totalShippingAmount: SubscribableSignalLike<Money | undefined>;
 
   /**
    * A `Money` value representing the total tax a buyer can expect to pay at the current
    * step of checkout or the total tax included in product and shipping prices. Returns
    * undefined if taxes are unavailable.
    */
-  totalTaxAmount: ReadonlySignalLike<Money | undefined>;
+  totalTaxAmount: SubscribableSignalLike<Money | undefined>;
 
   /**
    * A `Money` value representing the minimum a buyer can expect to pay at the current
    * step of checkout. This value excludes amounts yet to be negotiated. For example,
    * the information step might not have delivery costs calculated.
    */
-  totalAmount: ReadonlySignalLike<Money>;
+  totalAmount: SubscribableSignalLike<Money>;
 }
 
 export interface CartLine {

package/src/surfaces/customer-account/api/shared.ts

@@ -9,7 +9,7 @@ import type {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
-  ReadonlySignalLike,
+  SubscribableSignalLike,
 } from '../../../shared';
 
 export {
@@ -21,7 +21,7 @@ export {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
-  ReadonlySignalLike,
+  SubscribableSignalLike,
 };
 
 /**
@@ -163,7 +163,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * * [`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.
    */
-  capabilities: ReadonlySignalLike<Capability[]>;
+  capabilities: SubscribableSignalLike<Capability[]>;
 
   /**
    * Information about the editor where the extension is being rendered.
@@ -183,7 +183,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    * from where it was rendered. The extension continues running so that
    * your extension is immediately available to render if the buyer navigates back.
    */
-  rendered: ReadonlySignalLike<boolean>;
+  rendered: SubscribableSignalLike<boolean>;
 
   /**
    * The URL to the script that started the extension target.
@@ -346,11 +346,11 @@ export interface AuthenticatedAccount {
    * Provides the company info of the authenticated business customer.
    * If the customer is not authenticated or is not a business customer, this value is `undefined`.
    */
-  purchasingCompany: ReadonlySignalLike<PurchasingCompany | undefined>;
+  purchasingCompany: SubscribableSignalLike<PurchasingCompany | undefined>;
   /**
    * Provides the customer information of the authenticated customer.
    */
-  customer: ReadonlySignalLike<Customer | undefined>;
+  customer: SubscribableSignalLike<Customer | undefined>;
 }
 
 /**

package/src/surfaces/customer-account/api/standard-api/standard-api.ts

@@ -12,7 +12,7 @@ import {
   CustomerPrivacy,
   ApplyTrackingConsentChangeType,
   ToastApi,
-  ReadonlySignalLike,
+  SubscribableSignalLike,
 } from '../shared';
 
 import type {ExtensionTarget} from '../../extension-targets';
@@ -96,7 +96,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * > 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.
    */
-  settings: ReadonlySignalLike<ExtensionSettings>;
+  settings: SubscribableSignalLike<ExtensionSettings>;
 
   /**
    * The Toast API displays a non-disruptive message that displays at the bottom
@@ -128,7 +128,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Customer privacy consent settings and a flag denoting if consent has previously been collected.
    */
-  customerPrivacy: ReadonlySignalLike<CustomerPrivacy>;
+  customerPrivacy: SubscribableSignalLike<CustomerPrivacy>;
 
   /**
    * Allows setting and updating customer privacy consent settings and tracking consent metafields.
@@ -166,7 +166,7 @@ export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
    */
-  language: ReadonlySignalLike<Language>;
+  language: SubscribableSignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -179,14 +179,14 @@ export interface Localization {
    * translations at all, this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
-  extensionLanguage: ReadonlySignalLike<Language>;
+  extensionLanguage: SubscribableSignalLike<Language>;
 
   /**
    * The country context of the buyer sees in the customer account.
    * It will update if the buyer changes the country in the customer account
    * If the country is unknown, then the value is undefined.
    */
-  country: ReadonlySignalLike<Country | undefined>;
+  country: SubscribableSignalLike<Country | undefined>;
 }
 
 /**

package/src/surfaces/customer-account/api.ts

@@ -78,7 +78,7 @@ export type {
   VisitorResult,
   VisitorSuccess,
   VisitorError,
-  ReadonlySignalLike,
+  SubscribableSignalLike,
 } from './api/shared';
 
 export type {CartLineItemApi} from './api/cart-line/cart-line-item';

package/src/surfaces/customer-account/preact/subscription.ts

@@ -1,8 +1,8 @@
 import {useEffect, useState} from 'preact/hooks';
 
-import {ReadonlySignalLike} from '../api/shared';
+import {SubscribableSignalLike} from '../api/shared';
 
-type Subscriber<T> = Parameters<ReadonlySignalLike<T>['subscribe']>[0];
+type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
 
 /**
  * Subscribes to the special wrapper type that all “changeable” values in the
@@ -14,7 +14,7 @@ type Subscriber<T> = Parameters<ReadonlySignalLike<T>['subscribe']>[0];
  * > for accessing the current value of each individual resource in the checkout.
  */
 export function useSubscription<Value>(
-  subscription: ReadonlySignalLike<Value>,
+  subscription: SubscribableSignalLike<Value>,
 ): Value {
   const [, setValue] = useState(subscription.value);
 

package/src/surfaces/point-of-sale/components/Badge.d.ts

@@ -31,7 +31,7 @@ declare const tagName = 's-badge';
 export interface BadgeJSXProps extends Pick<BadgeProps, 'id'> {
   tone?: Extract<
     BadgeProps['tone'],
-    'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical'
+    'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution'
   >;
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Box.d.ts

@@ -8,7 +8,14 @@
 /* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {BoxProps, Key, Ref} from './components-shared.d.ts';
+import type {
+  BoxProps,
+  SizeKeyword,
+  MaybeAllValuesShorthandProperty,
+  MaybeTwoValuesShorthandProperty,
+  Key,
+  Ref,
+} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
@@ -28,16 +35,10 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
 }
 
 declare const tagName = 's-box';
+export type PaddingKeyword = SizeKeyword | 'none';
 export interface BoxJSXProps
   extends Pick<
     BoxProps,
-    | 'padding'
-    | 'paddingBlock'
-    | 'paddingBlockStart'
-    | 'paddingBlockEnd'
-    | 'paddingInline'
-    | 'paddingInlineStart'
-    | 'paddingInlineEnd'
     | 'blockSize'
     | 'minBlockSize'
     | 'maxBlockSize'
@@ -45,6 +46,79 @@ export interface BoxJSXProps
     | 'minInlineSize'
     | 'maxInlineSize'
   > {
+  /**
+   * Adjust the padding of all edges.
+   *
+   * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is
+   * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is:
+   *
+   * - 4 values: `block-start inline-end block-end inline-start`
+   * - 3 values: `block-start inline block-end`
+   * - 2 values: `block inline`
+   *
+   * For example:
+   * - `large` means block-start, inline-end, block-end and inline-start paddings are `large`.
+   * - `large none` means block-start and block-end paddings are `large`, inline-start and inline-end paddings are `none`.
+   * - `large none large` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `none`.
+   * - `large none large small` means block-start padding is `large`, inline-end padding is `none`, block-end padding is `large` and inline-start padding is `small`.
+   *
+   * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
+   *
+   * @default 'none'
+   */
+  padding?: MaybeAllValuesShorthandProperty<PaddingKeyword>;
+  /**
+   * Adjust the block-padding.
+   *
+   * - `large none` means block-start padding is `large`, block-end padding is `none`.
+   *
+   * This overrides the block value of `padding`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
+  /**
+   * Adjust the block-start padding.
+   *
+   * This overrides the block-start value of `paddingBlock`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingBlockStart?: PaddingKeyword | '';
+  /**
+   * Adjust the block-end padding.
+   *
+   * This overrides the block-end value of `paddingBlock`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingBlockEnd?: PaddingKeyword | '';
+  /**
+   * Adjust the inline padding.
+   *
+   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
+   *
+   * This overrides the inline value of `padding`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
+  /**
+   * Adjust the inline-start padding.
+   *
+   * This overrides the inline-start value of `paddingInline`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingInlineStart?: PaddingKeyword | '';
+  /**
+   * Adjust the inline-end padding.
+   *
+   * This overrides the inline-end value of `paddingInline`.
+   *
+   * @default '' - meaning no override
+   */
+  paddingInlineEnd?: PaddingKeyword | '';
   children?: ComponentChildren;
 }
 declare global {