@shopify/ui-extensions 2025.10.0-rc.46 → 2025.10.0-rc.48

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

@@ -31,6 +31,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
   currentTarget: HTMLElementTagNameMap[T];
   bubbles?: boolean;
@@ -43,24 +44,44 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 
 declare const tagName = 's-modal';
 export interface ModalJSXProps extends Pick<ModalProps, 'id' | 'heading'> {
-  primaryAction?: ComponentChild;
-  secondaryActions?: ComponentChild;
+  /**
+   * Callback when the modal is hidden.
+   */
   onHide?: (event: CallbackEvent<typeof tagName>) => void | null;
+  /**
+   * Callback when the modal is shown.
+   */
   onShow?: (event: CallbackEvent<typeof tagName>) => void | null;
+  /**
+   * The primary action button displayed in the modal.
+   *
+   * The tone of the button is used to define the tone of the modal.
+   *
+   * If omitted, the modal will default to an 'info' tone, and show an 'OK' button, translated according to the user's locale.
+   */
+  primaryAction?: ComponentChild;
+  /**
+   * The secondary action buttons displayed in the modal.
+   */
+  secondaryActions?: ComponentChild;
+  /**
+   * The content of the Modal.
+   */
   children?: ComponentChildren;
 }
+export type ElementProps = Omit<
+  ModalJSXProps,
+  'primaryAction' | 'secondaryActions'
+>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: ModalJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<ModalJSXProps, 'primaryAction' | 'secondaryActions'> &
-        BaseElementPropsWithChildren<
-          Omit<ModalJSXProps, 'primaryAction' | 'secondaryActions'>
-        >;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -31,6 +31,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
   currentTarget: HTMLElementTagNameMap[T];
   bubbles?: boolean;
@@ -45,6 +46,7 @@ declare const tagName = 's-number-field';
 export interface NumberFieldJSXProps
   extends Pick<
     NumberFieldProps,
+    | 'id'
     | 'label'
     | 'details'
     | 'value'
@@ -122,25 +124,33 @@ export interface NumberFieldJSXProps
    * - `auto`: the presence of the controls depends on the surface and context.
    */
   controls?: NumberFieldProps['controls'];
-  /** Function called when the user makes any changes in the field. */
+  /**
+   * Callback when the user makes any changes in the field.
+   */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called after editing completes (typically on blur). */
+  /**
+   * Callback after editing completes (typically on blur).
+   */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called when the element loses focus. */
+  /**
+   * Callback when the element loses focus.
+   */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called when the element receives focus. */
+  /**
+   * Callback when the element receives focus.
+   */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
+export type ElementProps = Omit<NumberFieldJSXProps, 'accessory'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: NumberFieldJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<NumberFieldJSXProps, 'accessory'> &
-        BaseElementPropsWithChildren<Omit<NumberFieldJSXProps, 'accessory'>>;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -31,29 +31,43 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-page';
-export type PickedProps = Pick<
-  PageProps,
-  'heading' | 'subheading' | 'secondaryActions' | 'aside'
->;
-export interface PageJSXProps extends PickedProps {
-  children?: ComponentChildren;
+export interface PageJSXProps extends Pick<PageProps, 'id'> {
+  /**
+   * The main page heading, displayed in the action bar at the top of the page.
+   *
+   * @default: ''
+   */
+  heading?: PageProps['heading'];
+  /**
+   * A secondary page heading, displayed under the main heading in the action bar.
+   */
+  subheading?: PageProps['subheading'];
+  /**
+   * Button element to display in the action bar. Only a single button is supported.
+   */
   secondaryActions?: ComponentChild;
+  /**
+   * Content to display in the page's sidebar.
+   */
   aside?: ComponentChild;
+  /**
+   * The content of the Page.
+   */
+  children?: ComponentChildren;
 }
+export type ElementProps = Omit<PageJSXProps, 'secondaryActions' | 'aside'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: PageJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<PageJSXProps, 'secondaryActions' | 'aside'> &
-        BaseElementPropsWithChildren<
-          Omit<PageJSXProps, 'secondaryActions' | 'aside'>
-        >;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -9,7 +9,7 @@
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
 import type {
-  SectionProps,
+  POSBlockProps,
   Key,
   Ref,
   ComponentChild,
@@ -31,31 +31,30 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-pos-block';
-export interface PosBlockJSXProps extends Pick<SectionProps, 'children'> {
+export interface PosBlockJSXProps
+  extends Pick<POSBlockProps, 'id' | 'heading'> {
+  /**
+   * The secondary actions to perform, provided as button or link type elements.
+   */
   secondaryActions?: ComponentChild;
   /**
-   * Adds title text displayed at the top left of the section
-   *
-   * **Mobile surfaces:** Uses the standard POS Design System heading style for a section (not h2).
-   *
-   * @default undefined
+   * The content of the Block.
    */
-  heading?: string;
+  children?: ComponentChildren;
 }
+export type ElementProps = Omit<PosBlockJSXProps, 'secondaryActions'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: PosBlockJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<PosBlockJSXProps, 'secondaryActions'> &
-        BaseElementPropsWithChildren<
-          Omit<PosBlockJSXProps, 'secondaryActions'>
-        >;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -8,8 +8,9 @@
 /* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {Key, Ref} from './components-shared.d.ts';
+import type {QRCodeProps, Key, Ref} from './components-shared.d.ts';
 
+export type ComponentChildren = any;
 /**
  * Used when an element does not have children.
  */
@@ -18,14 +19,17 @@ export interface BaseElementProps<TClass = HTMLElement> {
   ref?: Ref<TClass>;
   slot?: Lowercase<string>;
 }
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement>
+  extends BaseElementProps<TClass> {
+  children?: ComponentChildren;
+}
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-qr-code';
-export interface QrCodeJSXProps {
-  /**
-   * The value to encode in the QR code
-   */
-  content: string;
-}
+export interface QrCodeJSXProps extends Pick<QRCodeProps, 'id' | 'content'> {}
 declare global {
   interface HTMLElementTagNameMap {
     [tagName]: QrCodeJSXProps;
@@ -34,7 +38,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: QrCodeJSXProps & BaseElementProps<QrCodeJSXProps>;
+      [tagName]: IntrinsicElementProps<QrCodeJSXProps>;
     }
   }
 }

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

@@ -13,6 +13,9 @@ import type {
   MaybeAllValuesShorthandProperty,
   MaybeTwoValuesShorthandProperty,
   SizeKeyword,
+  SizeUnitsOrAuto,
+  SizeUnitsOrNone,
+  SizeUnits,
   Key,
   Ref,
 } from './components-shared.d.ts';
@@ -33,20 +36,47 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 export type PaddingKeyword = SizeKeyword | 'none';
 declare const tagName = 's-scroll-box';
-export interface ScrollBoxJSXProps
-  extends Pick<
-    ScrollBoxProps,
-    | 'id'
-    | 'blockSize'
-    | 'minBlockSize'
-    | 'maxBlockSize'
-    | 'inlineSize'
-    | 'minInlineSize'
-    | 'maxInlineSize'
-  > {
+export interface ScrollBoxJSXProps extends Pick<ScrollBoxProps, 'id'> {
+  /**
+   * Adjust the block size.
+   *
+   * @default 'auto'
+   */
+  blockSize?: SizeUnitsOrAuto;
+  /**
+   * Adjust the inline size.
+   *
+   * @default 'auto'
+   */
+  inlineSize?: SizeUnitsOrAuto;
+  /**
+   * Adjust the maximum block size.
+   *
+   * @default 'none'
+   */
+  maxBlockSize?: SizeUnitsOrNone;
+  /**
+   * Adjust the maximum inline size.
+   *
+   * @default 'none'
+   */
+  maxInlineSize?: SizeUnitsOrNone;
+  /**
+   * Adjust the minimum block size.
+   *
+   * @default '0'
+   */
+  minBlockSize?: SizeUnits;
+  /**
+   * Adjust the minimum inline size.
+   *
+   * @default '0'
+   */
+  minInlineSize?: SizeUnits;
   /**
    * Adjust the padding of all edges.
    *
@@ -77,7 +107,7 @@ export interface ScrollBoxJSXProps
    *
    * @default '' - meaning no override
    */
-  paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
+  paddingBlock?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
    * Adjust the block-start padding.
    *
@@ -103,7 +133,7 @@ export interface ScrollBoxJSXProps
    *
    * @default '' - meaning no override
    */
-  paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword | ''>;
+  paddingInline?: MaybeTwoValuesShorthandProperty<PaddingKeyword> | '';
   /**
    * Adjust the inline-start padding.
    *
@@ -120,6 +150,9 @@ export interface ScrollBoxJSXProps
    * @default '' - meaning no override
    */
   paddingInlineEnd?: PaddingKeyword | '';
+  /**
+   * The content of the ScrollBox.
+   */
   children?: ComponentChildren;
 }
 declare global {
@@ -130,8 +163,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: ScrollBoxJSXProps &
-        BaseElementPropsWithChildren<ScrollBoxJSXProps>;
+      [tagName]: IntrinsicElementProps<ScrollBoxJSXProps>;
     }
   }
 }

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

@@ -26,6 +26,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
   currentTarget: HTMLElementTagNameMap[T];
   bubbles?: boolean;
@@ -38,14 +39,22 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 
 declare const tagName = 's-search-field';
 export interface SearchFieldJSXProps
-  extends Pick<SearchFieldProps, 'disabled' | 'placeholder' | 'value'> {
-  /** Function called when the user changes the value in the field. */
+  extends Pick<SearchFieldProps, 'id' | 'disabled' | 'placeholder' | 'value'> {
+  /**
+   * Callback when the user changes the value in the field.
+   */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called when the field loses focus after the user changes the value in the field. */
+  /**
+   * Callback when the field loses focus after the user changes the value in the field.
+   */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called when the field loses focus. */
+  /**
+   * Callback when the field loses focus.
+   */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /** Function called when the field is focused. */
+  /**
+   * Callback when the field is focused.
+   */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 declare global {
@@ -56,8 +65,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: SearchFieldJSXProps &
-        BaseElementPropsWithChildren<SearchFieldJSXProps>;
+      [tagName]: IntrinsicElementProps<SearchFieldJSXProps>;
     }
   }
 }

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

@@ -31,29 +31,35 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-section';
-export interface SectionJSXProps extends Pick<SectionProps, 'children'> {
-  secondaryActions?: ComponentChild;
+export interface SectionJSXProps extends Pick<SectionProps, 'id'> {
   /**
-   * Adds title text displayed at the top left of the section
-   *
-   * **Mobile surfaces:** Uses the standard POS Design System heading style for a section (not h2).
+   * A title that describes the content of the section.
    *
-   * @default undefined
+   * If omitted, and no secondaryActions are provided, the section will be rendered without a header.
    */
   heading?: string;
+  /**
+   * Button element to display in the section heading. A single button is supported.
+   */
+  secondaryActions?: ComponentChild;
+  /**
+   * The content of the Section.
+   */
+  children?: ComponentChildren;
 }
+export type ElementProps = Omit<SectionJSXProps, 'secondaryActions'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: SectionJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<SectionJSXProps, 'secondaryActions'> &
-        BaseElementPropsWithChildren<Omit<SectionJSXProps, 'secondaryActions'>>;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -10,6 +10,13 @@
 /// <reference lib="DOM" />
 import type {
   StackProps,
+  SizeUnitsOrAuto,
+  SizeUnitsOrNone,
+  SizeUnits,
+  AlignItemsKeyword,
+  AlignContentKeyword,
+  SpacingKeyword,
+  JustifyContentKeyword,
   SizeKeyword,
   MaybeAllValuesShorthandProperty,
   MaybeTwoValuesShorthandProperty,
@@ -33,11 +40,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-stack';
 export type PaddingKeyword = SizeKeyword | 'none';
 export type PickedProps = Pick<
   StackProps,
+  | 'id'
   | 'alignItems'
   | 'alignContent'
   | 'gap'
@@ -126,7 +135,6 @@ export interface StackJSXProps extends PickedProps {
    * @default '' - meaning no override
    */
   paddingInlineEnd?: PaddingKeyword | '';
-  children?: ComponentChildren;
   /**
    * Adjust the block size.
    * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
@@ -135,7 +143,7 @@ export interface StackJSXProps extends PickedProps {
    *
    * @default 'auto'
    */
-  blockSize?: PickedProps['blockSize'];
+  blockSize?: SizeUnitsOrAuto;
   /**
    * Adjust the maximum block size.
    * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
@@ -144,7 +152,7 @@ export interface StackJSXProps extends PickedProps {
    *
    * @default 'none'
    */
-  maxBlockSize?: PickedProps['maxBlockSize'];
+  maxBlockSize?: SizeUnitsOrNone;
   /**
    * Adjust the maximum inline size.
    * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
@@ -153,7 +161,7 @@ export interface StackJSXProps extends PickedProps {
    *
    * @default 'none'
    */
-  maxInlineSize?: PickedProps['maxInlineSize'];
+  maxInlineSize?: SizeUnitsOrNone;
   /**
    * Adjust the minimum block size.
    * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
@@ -162,7 +170,7 @@ export interface StackJSXProps extends PickedProps {
    *
    * @default '0'
    */
-  minBlockSize?: PickedProps['minBlockSize'];
+  minBlockSize?: SizeUnits;
   /**
    * Adjust the minimum inline size.
    * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
@@ -171,7 +179,59 @@ export interface StackJSXProps extends PickedProps {
    *
    * @default '0'
    */
-  minInlineSize?: PickedProps['minInlineSize'];
+  minInlineSize?: SizeUnits;
+  /**
+   * Aligns the Stack's children along the cross axis.
+   */
+  alignItems?: AlignItemsKeyword;
+  /**
+   * Aligns the Stack along the cross axis.
+   */
+  alignContent?: AlignContentKeyword;
+  /**
+   * Adjust spacing between elements.
+   * A single value applies to both axes. A pair of values (eg large-100 large-500) can be used to set the inline and block axes respectively.
+   *
+   * @default 'none'
+   */
+  gap?: MaybeTwoValuesShorthandProperty<SpacingKeyword>;
+  /**
+   * Adjust spacing between elements in the inline axis. This overrides the column value of gap.
+   *
+   * @default '' - meaning no override
+   */
+  columnGap?: SpacingKeyword | '';
+  /**
+   * Sets how the children are placed within the Stack. This uses logical properties.
+   *
+   * @default 'block'
+   * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block'
+   */
+  direction?: 'block' | 'inline';
+  /**
+   * Adjust the inline size.
+   * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size
+   *
+   * @default 'auto'
+   */
+  inlineSize?: SizeUnitsOrAuto;
+  /**
+   * Aligns the Stack along the main axis.
+   * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
+   *
+   * @default 'normal'
+   */
+  justifyContent?: JustifyContentKeyword;
+  /**
+   * Adjust spacing between elements in the block axis. This overrides the row value of gap.
+   *
+   * @default '' - meaning no override
+   */
+  rowGap?: SpacingKeyword | '';
+  /**
+   * The content of the Stack.
+   */
+  children?: ComponentChildren;
 }
 declare global {
   interface HTMLElementTagNameMap {
@@ -181,7 +241,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: StackJSXProps & BaseElementPropsWithChildren<StackJSXProps>;
+      [tagName]: IntrinsicElementProps<StackJSXProps>;
     }
   }
 }

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

@@ -26,15 +26,36 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-text';
-export interface TextJSXProps extends Pick<TextProps, 'tone' | 'type'> {
-  color?: 'subdued' | 'base' | 'strong';
-  type?: Extract<TextProps['type'], 'strong' | 'small' | 'generic'>;
+export interface TextJSXProps extends Pick<TextProps, 'id'> {
+  /**
+   * Modify the color to be more or less intense.
+   *
+   * @default 'base'
+   */
+  color?: Extract<TextProps['color'], 'base' | 'strong' | 'subdued'>;
+  /**
+   * Provide semantic meaning and default styling to the text.
+   *
+   * Other presentation properties on Text override the default styling.
+   *
+   * @default 'generic'
+   */
+  type?: Extract<TextProps['type'], 'generic' | 'strong' | 'small'>;
+  /**
+   * Sets the tone of the component, based on the intention of the information being conveyed.
+   *
+   * @default 'auto'
+   */
   tone?: Extract<
     TextProps['tone'],
     'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution'
   >;
+  /**
+   * The Text content. Supports nested text elements.
+   */
   children?: ComponentChildren;
 }
 declare global {
@@ -45,7 +66,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: TextJSXProps & BaseElementPropsWithChildren<TextJSXProps>;
+      [tagName]: IntrinsicElementProps<TextJSXProps>;
     }
   }
 }