@shopify/ui-extensions 2025.10.0-rc.45 → 2025.10.0-rc.47

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

@@ -26,9 +26,11 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-divider';
-export interface DividerJSXProps extends Pick<DividerProps, 'direction'> {}
+export interface DividerJSXProps
+  extends Pick<DividerProps, 'id' | 'direction'> {}
 declare global {
   interface HTMLElementTagNameMap {
     [tagName]: DividerJSXProps;
@@ -37,8 +39,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: DividerJSXProps &
-        BaseElementPropsWithChildren<DividerJSXProps>;
+      [tagName]: IntrinsicElementProps<DividerJSXProps>;
     }
   }
 }

package/src/surfaces/point-of-sale/components/EmailField/examples/accessory-slot.jsx

@@ -0,0 +1,9 @@
+<s-email-field
+  label="Newsletter signup"
+  placeholder="Enter email address"
+  value="customer@example.com"
+>
+  <s-button slot="accessory" onClick={() => console.log('Subscribe')}>
+    Subscribe
+  </s-button>
+</s-email-field>;

package/src/surfaces/point-of-sale/components/EmailField/examples/default.html

@@ -1,12 +1,5 @@
 <s-email-field 
-  label="Email" 
-  placeholder="Enter your email"
+  label="Email"
+  value="snowdevil@shopify.com"
   required
-  value="example@shopify.com"></s-email-field>
-
-<s-email-field 
-  label="Email" 
-  placeholder="Enter your email"
-  required
-  error="Enter a valid email address"
-  value="example.com"></s-email-field>
+/>

package/src/surfaces/point-of-sale/components/EmailField/examples/event-handling.jsx

@@ -0,0 +1,8 @@
+<s-email-field
+  label="Customer email"
+  placeholder="customer@example.com"
+  onInput={(event) => console.log('Input:', event.target.value)}
+  onChange={(event) => console.log('Change:', event.target.value)}
+  onFocus={(event) => console.log('Focus')}
+  onBlur={(event) => console.log('Blur')}
+/>

package/src/surfaces/point-of-sale/components/EmailField.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-email-field';
 export interface EmailFieldJSXProps
   extends Pick<
     EmailFieldProps,
+    | 'id'
     | 'label'
     | 'value'
     | 'placeholder'
@@ -54,22 +56,37 @@ export interface EmailFieldJSXProps
     | 'maxLength'
     | 'details'
   > {
+  /**
+   * Callback when the user makes any changes in the field.
+   */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback after editing completes (typically on blur).
+   */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the element loses focus.
+   */
+  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the element receives focus.
+   */
+  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Additional content to be displayed in the field. Commonly used to display clickable text.
+   */
   accessory?: ComponentChild;
 }
+export type ElementProps = Omit<EmailFieldJSXProps, 'accessory'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: EmailFieldJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<EmailFieldJSXProps, 'accessory'> &
-        BaseElementPropsWithChildren<Omit<EmailFieldJSXProps, 'accessory'>>;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

package/src/surfaces/point-of-sale/components/Heading/examples/default.html

@@ -1,8 +1,7 @@
-<s-heading>Heading (h2)</s-heading>
-
+<s-heading>Heading (H2)</s-heading>
 <s-section>
-  <s-heading>Heading (h3)</s-heading>
+  <s-heading>Heading (H3)</s-heading>
   <s-section>
-    <s-heading>Heading (h4)</s-heading>
+    <s-heading>Heading (H4)</s-heading>
   </s-section>
-</s-section>
+</s-section>

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

@@ -8,7 +8,7 @@
 /* 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 {HeadingProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
@@ -26,9 +26,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-heading';
-export interface HeadingJSXProps {
+export interface HeadingJSXProps extends Pick<HeadingProps, 'id'> {
+  /**
+   * The content of the Heading.
+   */
   children?: ComponentChildren;
 }
 declare global {
@@ -39,8 +43,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: HeadingJSXProps &
-        BaseElementPropsWithChildren<HeadingJSXProps>;
+      [tagName]: IntrinsicElementProps<HeadingJSXProps>;
     }
   }
 }

package/src/surfaces/point-of-sale/components/Icon/examples/default.html

@@ -1 +1,4 @@
-<s-icon type="alert-circle"></s-icon>
+<s-icon type="arrow-up" />
+<s-icon type="arrow-down" />
+<s-icon type="arrow-left" />
+<s-icon type="arrow-right" />

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

@@ -10,6 +10,7 @@
 /// <reference lib="DOM" />
 import type {IconProps, Key, Ref} from './components-shared.d.ts';
 
+export type ComponentChildren = any;
 /**
  * Used when an element does not have children.
  */
@@ -18,6 +19,14 @@ 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-icon';
 export type SupportedIconNames = Extract<
@@ -149,9 +158,10 @@ export type SupportedIconNames = Extract<
   | 'x-circle'
 >;
 export interface IconJSXProps
-  extends Pick<IconProps, 'tone' | 'color' | 'size'> {
+  extends Pick<IconProps, 'id' | 'tone' | 'color' | 'size'> {
   /**
-   * The type of icon to display. Maps to PDS icon names.
+   * The type of icon to display.
+   *
    * @default ''
    */
   type?: SupportedIconNames;
@@ -164,7 +174,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: IconJSXProps & BaseElementProps<IconJSXProps>;
+      [tagName]: IntrinsicElementProps<IconJSXProps>;
     }
   }
 }

package/src/surfaces/point-of-sale/components/Image/examples/default.html

@@ -1 +1 @@
-<s-image src="example.png" inlineSize="auto"></s-image>
+<s-image src="example.png" inlineSize="auto" />

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

@@ -26,11 +26,10 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
+export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-image';
-export type PickedProps = Pick<ImageProps, 'src' | 'inlineSize' | 'objectFit'>;
-export interface ImageJSXProps extends PickedProps {
-  children?: ComponentChildren;
+export interface ImageJSXProps extends Pick<ImageProps, 'id' | 'objectFit'> {
   /**
    * The displayed inline width of the image.
    *
@@ -45,7 +44,15 @@ export interface ImageJSXProps extends PickedProps {
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width
    */
-  inlineSize?: PickedProps['inlineSize'];
+  inlineSize?: ImageProps['inlineSize'];
+  /**
+   * The image source, which should be a remote URL.
+   *
+   * When the image is loading or no `src` is provided, a placeholder will be rendered.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+   */
+  src?: ImageProps['src'];
 }
 declare global {
   interface HTMLElementTagNameMap {
@@ -55,7 +62,7 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: ImageJSXProps & BaseElementPropsWithChildren<ImageJSXProps>;
+      [tagName]: IntrinsicElementProps<ImageJSXProps>;
     }
   }
 }

package/src/surfaces/point-of-sale/components/Modal/examples/default.html

@@ -1,9 +1,7 @@
-<s-button command="--show" commandFor="modal">Open modal</s-button>
-<s-modal id="modal" heading="Header">
-  <s-stack alignItems="center" justifyContent="center" gap="base">
-    <s-text color="subdued">Subheader</s-text>
-  </s-stack>
-  <s-button slot="primary-action" onClick={handlePrimaryAction}>
-    Label
-  </s-button>
+<s-button command="--show" commandFor="modal">
+  Open modal
+</s-button>
+<s-modal id="modal" heading="Changes could not be saved">
+  Please check your internet connection and try again.
+  <s-button slot="primary-action">OK</s-button>
 </s-modal>

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/examples/controls-constraints.jsx

@@ -0,0 +1,9 @@
+<s-number-field
+  label="Quantity"
+  value="5"
+  min={1}
+  max={100}
+  controls
+  onInput={(event) => console.log('Input:', event.target.value)}
+  onChange={(event) => console.log('Change:', event.target.value)}
+/>;

package/src/surfaces/point-of-sale/components/NumberField/examples/default.html

@@ -1,2 +1,5 @@
-<s-number-field label="Phone number" required value="+1 (416) 555-5555"></s-number-field>
-<s-number-field label="Phone number" required value="+1 (416) 555-5555555" error="Enter a valid phone number"></s-number-field>
+<s-number-field 
+  label="Item count"
+  value="976"
+  required
+/>

package/src/surfaces/point-of-sale/components/NumberField/examples/input-mode.jsx

@@ -0,0 +1,15 @@
+<s-stack>
+  <s-number-field
+    label="Price"
+    placeholder="0.00"
+    inputMode="decimal"
+    onInput={(event) => console.log('Value:', event.target.value)}
+  />
+
+  <s-number-field
+    label="Stock count"
+    placeholder="0"
+    inputMode="numeric"
+    onInput={(event) => console.log('Value:', event.target.value)}
+  />
+</s-stack>;

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;
@@ -42,9 +43,10 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 }
 
 declare const tagName = 's-number-field';
-export interface PickedJSXProps
+export interface NumberFieldJSXProps
   extends Pick<
     NumberFieldProps,
+    | 'id'
     | 'label'
     | 'details'
     | 'value'
@@ -56,20 +58,12 @@ export interface PickedJSXProps
     | 'min'
     | 'controls'
   > {
-  inputMode?: Extract<NumberFieldProps['inputMode'], 'decimal' | 'numeric'>;
-  onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  accessory?: ComponentChild;
-}
-export interface NumberFieldJSXProps extends PickedJSXProps {
   /**
    * Content to use as the field label.
    *
    * Label is not supported when using Stepper controls
    */
-  label?: PickedJSXProps['label'];
+  label?: NumberFieldProps['label'];
   /**
    * Additional text to provide context or guidance for the field.
    * This text is displayed along with the field and its label
@@ -79,7 +73,7 @@ export interface NumberFieldJSXProps extends PickedJSXProps {
    *
    * Details are not supported when using Stepper controls
    */
-  details?: PickedJSXProps['details'];
+  details?: NumberFieldProps['details'];
   /**
    * Whether the field needs a value. This requirement adds semantic value
    * to the field, but it will not cause an error to appear automatically.
@@ -90,14 +84,14 @@ export interface NumberFieldJSXProps extends PickedJSXProps {
    *
    * Required is not supported when using Stepper controls
    */
-  required?: PickedJSXProps['required'];
+  required?: NumberFieldProps['required'];
   /**
    * 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 is not supported when using Stepper controls
    */
-  error?: PickedJSXProps['error'];
+  error?: NumberFieldProps['error'];
   /**
    * Sets the virtual keyboard.
    *
@@ -106,20 +100,19 @@ export interface NumberFieldJSXProps extends PickedJSXProps {
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode
    * @default 'decimal'
    */
-  inputMode?: PickedJSXProps['inputMode'];
+  inputMode?: NumberFieldProps['inputMode'];
   /**
    * A short hint that describes the expected value of the field.
    *
    * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones.
    */
-  placeholder?: PickedJSXProps['placeholder'];
+  placeholder?: NumberFieldProps['placeholder'];
   /**
-   * Additional content to be displayed in the field.
-   * Commonly used to display an icon that activates a tooltip providing more information.
+   *  Additional content to be displayed in the field. Commonly used to display clickable text.
    *
-   * Accessory is not supported when using Stepper controls
+   * > Note: Accessory is not supported when using Stepper controls
    */
-  accessory?: PickedJSXProps['accessory'];
+  accessory?: ComponentChild;
   /**
    * Sets the type of controls displayed for the field.
    *
@@ -130,18 +123,34 @@ export interface NumberFieldJSXProps extends PickedJSXProps {
    * - `none`: no controls are displayed and users must input the value manually.
    * - `auto`: the presence of the controls depends on the surface and context.
    */
-  controls?: PickedJSXProps['controls'];
+  controls?: NumberFieldProps['controls'];
+  /**
+   * Callback when the user makes any changes in the field.
+   */
+  onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback after editing completes (typically on blur).
+   */
+  onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the element loses focus.
+   */
+  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * 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/examples/default.html

@@ -1,6 +1,5 @@
 <s-page heading="Title">
-  <s-button slot="secondary-actions" onClick={onActionClick}>
-    Label
+  <s-button slot="secondary-actions">
+    Action
   </s-button>
-  <s-heading>Title</s-heading>
-</s-page>
+</s-page>

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/examples/default.html

@@ -1,11 +1,5 @@
 <s-pos-block>
-  <s-button
-    slot="secondary-actions"
-    onClick={onActionClick}
-  >
-    Action
-  </s-button>
-  <s-box padding="base">
-    <s-text>Label</s-text>
+  <s-box paddingBlock="base">
+    <s-text>Customer Loyalty</s-text>
   </s-box>
-</s-pos-block>
+</s-pos-block>

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>;
     }
   }
 }