@shopify/ui-extensions 2025.10.0-rc.9 → 2025.10.0

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

@@ -0,0 +1,250 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {
+  StackProps,
+  SizeUnitsOrAuto,
+  SizeUnitsOrNone,
+  SizeUnits,
+  AlignItemsKeyword,
+  AlignContentKeyword,
+  SpacingKeyword,
+  JustifyContentKeyword,
+  SizeKeyword,
+  MaybeAllValuesShorthandProperty,
+  MaybeTwoValuesShorthandProperty,
+  Key,
+  Ref,
+} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  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-stack';
+export type PaddingKeyword = SizeKeyword | 'none';
+export type PickedProps = Pick<
+  StackProps,
+  | 'id'
+  | 'alignItems'
+  | 'alignContent'
+  | 'gap'
+  | 'columnGap'
+  | 'direction'
+  | 'blockSize'
+  | 'maxBlockSize'
+  | 'maxInlineSize'
+  | 'minBlockSize'
+  | 'minInlineSize'
+  | 'inlineSize'
+  | 'justifyContent'
+  | 'rowGap'
+>;
+export interface StackJSXProps extends PickedProps {
+  /**
+   * 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 | '';
+  /**
+   * Adjust the block size.
+   * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size
+   *
+   * @default 'auto'
+   */
+  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.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size
+   *
+   * @default 'none'
+   */
+  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.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size
+   *
+   * @default 'none'
+   */
+  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.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size
+   *
+   * @default '0'
+   */
+  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.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size
+   *
+   * @default '0'
+   */
+  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 {
+    [tagName]: StackJSXProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<StackJSXProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {StackJSXProps};

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

@@ -0,0 +1,3 @@
+<s-text>
+  <s-text type="strong">Name:</s-text> Jane Doe
+</s-text>

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

@@ -0,0 +1,75 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {TextProps, Key, Ref} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  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-text';
+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 {
+  interface HTMLElementTagNameMap {
+    [tagName]: TextJSXProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<TextJSXProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {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

@@ -0,0 +1,4 @@
+<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

@@ -0,0 +1,96 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {
+  TextAreaProps,
+  Key,
+  Ref,
+  ComponentChild,
+} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  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>;
+export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  currentTarget: HTMLElementTagNameMap[T];
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  detail?: any;
+  eventPhase: number;
+  target: HTMLElementTagNameMap[T] | null;
+}
+
+declare const tagName = 's-text-area';
+export interface TextAreaJSXProps
+  extends Pick<
+    TextAreaProps,
+    | 'id'
+    | 'label'
+    | 'details'
+    | 'value'
+    | 'placeholder'
+    | 'disabled'
+    | 'error'
+    | 'required'
+    | 'maxLength'
+    | 'rows'
+  > {
+  /**
+   * 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;
+  /**
+   * 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]: ElementProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<ElementProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {TextAreaJSXProps};

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

@@ -0,0 +1,5 @@
+<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);
+  }}
+/>

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

@@ -0,0 +1,95 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {
+  TextFieldProps,
+  Key,
+  Ref,
+  ComponentChild,
+} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  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>;
+export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  currentTarget: HTMLElementTagNameMap[T];
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  detail?: any;
+  eventPhase: number;
+  target: HTMLElementTagNameMap[T] | null;
+}
+
+declare const tagName = 's-text-field';
+export interface TextFieldJSXProps
+  extends Pick<
+    TextFieldProps,
+    | 'id'
+    | 'label'
+    | 'details'
+    | 'value'
+    | 'placeholder'
+    | 'disabled'
+    | 'error'
+    | 'required'
+    | 'maxLength'
+  > {
+  /**
+   * 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;
+  /**
+   * Additional content to be displayed in the field. Commonly used to display clickable text.
+   */
+  accessory?: ComponentChild;
+}
+export type ElementProps = Omit<TextFieldJSXProps, 'accessory'>;
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: ElementProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<ElementProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {TextFieldJSXProps};

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

@@ -0,0 +1,2 @@
+<s-tile heading="Extension title" subheading="Subtitle" />
+<s-tile heading="Extension title" subheading="Subtitle" tone="accent" />

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

@@ -0,0 +1,71 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {TileProps, Key, Ref} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  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>;
+export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  currentTarget: HTMLElementTagNameMap[T];
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  detail?: any;
+  eventPhase: number;
+  target: HTMLElementTagNameMap[T] | null;
+}
+
+declare const tagName = 's-tile';
+export interface TileJSXProps
+  extends Pick<
+    TileProps,
+    'heading' | 'id' | 'itemCount' | 'tone' | 'subheading'
+  > {
+  /**
+   * Disables the Tile meaning it cannot be clicked or receive focus.
+   *
+   * @default false
+   */
+  disabled?: TileProps['disabled'];
+  /**
+   * Callback when the Tile is activated.
+   */
+  onClick?: (event: CallbackEvent<typeof tagName>) => void;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: TileJSXProps;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<TileJSXProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {TileJSXProps};

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

@@ -0,0 +1,4 @@
+<s-time-field
+  label="Time"
+  value="11:42"
+/>

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

@@ -0,0 +1,8 @@
+<s-time-field
+  label="Appointment time"
+  value="14:30"
+  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')}
+/>