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

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

@@ -1,7 +1,8 @@
 <s-scroll-box>
-  <s-choice-list multiple>
-    {data.map((item) => (
-      <s-choice value={item.value}>{item.label}</s-choice>
-    ))}
+  <s-choice-list>
+    <s-choice value="true-twin">True Twin board</s-choice>
+    <s-choice value="directional">Directional board</s-choice>
+    <s-choice value="volume">Volume shifted board</s-choice>
+    <s-choice value="asymmetrical">Asymmetrical board</s-choice>
   </s-choice-list>
 </s-scroll-box>

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

@@ -1 +1 @@
-<s-search-field placeholder="Search"></s-search-field>
+<s-search-field placeholder="Search" />

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

@@ -0,0 +1,8 @@
+<s-search-field
+  placeholder="Search products..."
+  value=""
+  onInput={(event) => console.log('Input:', event.target.value)}
+  onChange={(event) => console.log('Change:', event.target.value)}
+  onFocus={(event) => console.log('Search focused')}
+  onBlur={(event) => console.log('Search blurred')}
+/>

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,11 +39,23 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 
 declare const tagName = 's-search-field';
 export interface SearchFieldJSXProps
-  extends Pick<SearchFieldProps, 'disabled' | 'placeholder' | 'value'> {
-  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  extends Pick<SearchFieldProps, 'id' | 'disabled' | 'placeholder' | 'value'> {
+  /**
+   * Callback when the user changes the value in the field.
+   */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the field loses focus after the user changes the value in the field.
+   */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the field loses focus.
+   */
+  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * Callback when the field is focused.
+   */
+  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 declare global {
   interface HTMLElementTagNameMap {
@@ -52,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/examples/default.html

@@ -1,10 +1,8 @@
-<s-section heading="Section header">
-  <s-button slot="secondary-actions" onClick={onActionClick}>
-    Action
-  </s-button>
+<s-section heading="Select product category">
+  <s-button slot="secondary-actions">Edit</s-button>
   <s-choice-list>
-    {data.map((item) => (
-      <s-choice value={item.value}>{item.label}</s-choice>
-    ))}
+    <s-choice value="snowboards">Snowboards</s-choice>
+    <s-choice value="jackets">Jackets</s-choice>
+    <s-choice value="label">Label</s-choice>
   </s-choice-list>
-</s-section>
+</s-section>

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

@@ -1,4 +1,4 @@
-<s-stack>
-  <s-text>First item</s-text>
-  <s-text>Second item</s-text>
+<s-stack gap="small" direction="inline" justifyContent="center">
+  <s-badge tone="neutral">Paid</s-badge>
+  <s-badge tone="success">Active</s-badge>
 </s-stack>

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

@@ -1,6 +1,3 @@
-<s-text>Text</s-text>
-<s-text color="subdued">Text</s-text>
-<s-text tone="info">Text</s-text>
-<s-text tone="success">Text</s-text>
-<s-text tone="warning">Text</s-text>
-<s-text tone="critical">Text</s-text>
+<s-text>
+  <s-text type="strong">Name:</s-text> Jane Doe
+</s-text>

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

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

@@ -0,0 +1,9 @@
+<s-text-area
+  label="Product description"
+  placeholder="Enter product details..."
+  value="This is a sample product description"
+>
+  <s-button slot="accessory" onClick={() => console.log('Clear')}>
+    Clear
+  </s-button>
+</s-text-area>;

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

@@ -1 +1,4 @@
-<s-text-area label="Add note" placeholder="Enter a custom note" value="Custom note" ></s-text-area>
+<s-text-area 
+  label="Shipping address" 
+  value="1776 Barnes Street, Orlando, FL 32801"
+/>

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

@@ -0,0 +1,8 @@
+<s-text-area
+  label="Customer feedback"
+  placeholder="Enter feedback..."
+  onInput={(event) => console.log('Input:', event.target.value)}
+  onChange={(event) => console.log('Change:', event.target.value)}
+  onFocus={(event) => console.log('Focused')}
+  onBlur={(event) => console.log('Blurred')}
+/>

package/src/surfaces/point-of-sale/components/TextArea/examples/rows-configuration.jsx

@@ -0,0 +1,7 @@
+<s-text-area
+  label="Order notes"
+  placeholder="Add special instructions..."
+  rows={5}
+  maxLength={500}
+  onInput={(event) => console.log('Characters:', event.target.value.length)}
+/>

package/src/surfaces/point-of-sale/components/TextArea.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-text-area';
 export interface TextAreaJSXProps
   extends Pick<
     TextAreaProps,
+    | 'id'
     | 'label'
     | 'details'
     | 'value'
@@ -55,22 +57,37 @@ export interface TextAreaJSXProps
     | 'maxLength'
     | 'rows'
   > {
+  /**
+   * 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<TextAreaJSXProps, 'accessory'>;
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: TextAreaJSXProps;
+    [tagName]: ElementProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<TextAreaJSXProps, 'accessory'> &
-        BaseElementPropsWithChildren<Omit<TextAreaJSXProps, 'accessory'>>;
+      [tagName]: IntrinsicElementProps<ElementProps>;
     }
   }
 }

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

@@ -0,0 +1,5 @@
+<s-text-field label="Discount code" value="SUMMER2024">
+  <s-button slot="accessory" onClick={() => console.log('Apply discount')}>
+    Apply
+  </s-button>
+</s-text-field>;

package/src/surfaces/point-of-sale/components/TextField/examples/common-props.jsx

@@ -0,0 +1,11 @@
+<s-text-field
+  label="Product SKU"
+  value={sku}
+  placeholder="Enter SKU"
+  details="Use format: ABC-123"
+  error={hasError ? "SKU already exists" : undefined}
+  disabled={isProcessing}
+  required
+  maxLength={20}
+  onChange={(event) => setSku(event.target.value)}
+/>

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

@@ -1,3 +1,5 @@
-<s-text-field label="Label" required value=""></s-text-field>
-<s-text-field label="Label" required value="Content"></s-text-field>
-<s-text-field label="Label" required value="Content" error="Error message"></s-text-field>
+<s-text-field
+  label="Store name" 
+  value="Snowdevil" 
+  required
+/>

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

@@ -0,0 +1,17 @@
+<s-text-field
+  label="Product SKU"
+  placeholder="Enter SKU"
+  onInput={(event) => {
+    console.log('Input:', event.target.value);
+    console.log('Current error:', event.target.error);
+  }}
+  onFocus={(event) => {
+    console.log('Focused with value:', event.target.value);
+  }}
+  onBlur={(event) => {
+    console.log('Blurred with value:', event.target.value);
+  }}
+  onChange={(event) => {
+    console.log('Changed to:', event.target.value);
+  }}
+/>