@shopify/ui-extensions 2025.10.0-rc.4 → 2025.10.0-rc.40

package/src/surfaces/admin/components/EmailField.d.ts

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -72,18 +72,12 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
-export type CallbackEvent<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> = TEvent & {
-  currentTarget: HTMLElementTagNameMap[TTagName];
+export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  currentTarget: HTMLElementTagNameMap[T];
 };
-export type CallbackEventListener<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> =
+export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
-      (event: CallbackEvent<TTagName, TEvent>): void;
+      (event: CallbackEvent<T>): void;
     })
   | null;
 export interface FieldReactProps<T extends keyof HTMLElementTagNameMap> {
@@ -92,6 +86,15 @@ export interface FieldReactProps<T extends keyof HTMLElementTagNameMap> {
   onFocus?: ((event: CallbackEvent<T>) => void) | null;
   onBlur?: ((event: CallbackEvent<T>) => void) | null;
 }
+/** Used when an element does not have children. */
+export interface PreactBaseElementProps<TClass extends HTMLElement> {
+  /** Assigns a unique key to this element. */
+  key?: preact.Key;
+  /** Assigns a ref (generally from `useRef()`) to this element. */
+  ref?: preact.Ref<TClass>;
+  /** Assigns this element to a parent's slot. */
+  slot?: Lowercase<string>;
+}
 
 declare const internals: unique symbol;
 export type PreactInputProps = Required<
@@ -213,12 +216,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: EmailFieldJSXProps & BaseProps;
+      [tagName]: EmailFieldJSXProps & PreactBaseElementProps<EmailField>;
     }
   }
 }

package/src/surfaces/admin/components/Form.d.ts

@@ -1,11 +1,45 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {ComponentChild} from './shared.d.ts';
+import type {ExtendableEvent, FormProps$1, ComponentChild} from './shared.d.ts';
+
+export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  currentTarget: HTMLElementTagNameMap[T];
+};
+export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
+  | (EventListener & {
+      (event: CallbackEvent<T>): void;
+    })
+  | null;
+export interface CallbackExtendableEvent<
+  TTagName extends keyof HTMLElementTagNameMap,
+> extends CallbackEvent<TTagName>,
+    Pick<ExtendableEvent, 'waitUntil'> {}
+export type CallbackExtendableEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+> =
+  | (EventListener & {
+      (event: CallbackExtendableEvent<TTagName>): void;
+    })
+  | null;
+
+export interface FormProps extends Pick<FormProps$1, 'id'> {}
+
+declare const tagName = 's-form';
+export interface FormJSXProps extends Partial<FormProps> {
+  /**
+   * A callback that is run when the form is submitted.
+   */
+  onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
+  /**
+   * A callback that is run when the form is reset.
+   */
+  onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+}
 
 export type Styles = string;
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
@@ -67,25 +101,15 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
-export type CallbackEvent<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> = TEvent & {
-  currentTarget: HTMLElementTagNameMap[TTagName];
-};
-export type CallbackEventListener<
-  TTagName extends keyof HTMLElementTagNameMap,
-  TEvent extends Event = Event,
-> =
-  | (EventListener & {
-      (event: CallbackEvent<TTagName, TEvent>): void;
-    })
-  | null;
-
-export interface FormProps {}
 declare class Form extends PreactCustomElement implements FormProps {
   constructor();
-  accessor onsubmit: ((event: ExtendableEvent) => void) | null;
+  /**
+   * A callback that is run when the form is submitted.
+   */
+  accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
+  /**
+   * A callback that is run when the form is reset.
+   */
   accessor onreset: CallbackEventListener<typeof tagName> | null;
 }
 declare global {
@@ -103,21 +127,5 @@ declare module 'preact' {
   }
 }
 
-declare const tagName = 's-form';
-export interface ExtendableEvent extends CallbackEvent<typeof tagName> {
-  waitUntil(f: Promise<unknown>): void;
-}
-export interface FormJSXProps extends Partial<FormProps> {
-  id?: string;
-  /**
-   * A callback that is run when the form is submitted.
-   */
-  onSubmit?: ((event: ExtendableEvent) => void) | null;
-  /**
-   * A callback that is run when the form is reset.
-   */
-  onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-}
-
 export {Form};
 export type {FormJSXProps};

package/src/surfaces/admin/components/FunctionSettings.d.ts

@@ -0,0 +1,183 @@
+/** VERSION: 1.19.0 **/
+/* eslint-disable import/extensions */
+
+/* eslint-disable @typescript-eslint/no-namespace */
+
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {
+  FunctionSettingsProps$1,
+  ExtendableEvent,
+  ComponentChild,
+} from './shared.d.ts';
+
+export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  currentTarget: HTMLElementTagNameMap[T];
+};
+export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
+  | (EventListener & {
+      (event: CallbackEvent<T>): void;
+    })
+  | null;
+export type CallbackErrorEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+  TError extends Error = Error,
+> =
+  | (EventListener & {
+      (
+        event: CallbackEvent<TTagName> & {
+          error: TError;
+        },
+      ): void;
+    })
+  | null;
+export interface CallbackExtendableEvent<
+  TTagName extends keyof HTMLElementTagNameMap,
+> extends CallbackEvent<TTagName>,
+    Pick<ExtendableEvent, 'waitUntil'> {}
+export type CallbackExtendableEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+> =
+  | (EventListener & {
+      (event: CallbackExtendableEvent<TTagName>): void;
+    })
+  | null;
+
+export interface FunctionSettingsProps
+  extends Pick<FunctionSettingsProps$1, 'id'> {}
+
+declare const tagName = 's-function-settings';
+export interface FunctionSettingsJSXProps
+  extends Partial<
+    FunctionSettingsProps & Pick<FunctionSettingsProps$1, 'onError'>
+  > {
+  /**
+   * An optional callback function that will be run by the admin when the user
+   * commits their changes in the admin-rendered part of the function settings
+   * experience. If `event.waitUntil` is called with a promise, the admin will wait for the
+   * promise to resolve before committing any changes to Shopify’s servers. If
+   * the promise rejects, the admin will abort the changes and display an error,
+   * using the `message` property of the error you reject with.
+   */
+  onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
+  /**
+   * A callback that is run when the function settings form is reset.
+   */
+  onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+}
+
+export type Styles = string;
+export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
+  ShadowRoot: (element: any) => ComponentChild;
+  styles?: Styles;
+};
+export interface ActivationEventEsque {
+  shiftKey: boolean;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  button: number;
+}
+export interface ClickOptions {
+  /**
+   * The event you want to influence the synthetic click.
+   */
+  sourceEvent?: ActivationEventEsque;
+}
+/**
+ * Base class for creating custom elements with Preact.
+ * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
+ * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
+ */
+declare const BaseClass: typeof globalThis.HTMLElement;
+declare abstract class PreactCustomElement extends BaseClass {
+  /** @private */
+  static get observedAttributes(): string[];
+  constructor({
+    styles,
+    ShadowRoot: renderFunction,
+    delegatesFocus,
+    ...options
+  }: RenderImpl);
+
+  /** @private */
+  setAttribute(name: string, value: string): void;
+  /** @private */
+  attributeChangedCallback(name: string): void;
+  /** @private */
+  connectedCallback(): void;
+  /** @private */
+  disconnectedCallback(): void;
+  /** @private */
+  adoptedCallback(): void;
+  /**
+   * Queue a run of the render function.
+   * You shouldn't need to call this manually - it should be handled by changes to @property values.
+   * @private
+   */
+  queueRender(): void;
+  /**
+   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
+   *
+   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
+   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
+   * @private
+   * @param options
+   */
+  click({sourceEvent}?: ClickOptions): void;
+}
+
+export type FunctionSettingsErrorEvent = Parameters<
+  NonNullable<FunctionSettingsProps$1['onError']>
+>[0];
+declare class FunctionSettings
+  extends PreactCustomElement
+  implements FunctionSettingsProps
+{
+  constructor();
+  /**
+   * An optional callback function that will be run by the admin when the user
+   * commits their changes in the admin-rendered part of the function settings
+   * experience. If `event.waitUntil` is called with a promise, the admin will wait for the
+   * promise to resolve before committing any changes to Shopify’s servers. If
+   * the promise rejects, the admin will abort the changes and display an error,
+   * using the `message` property of the error you reject with.
+   */
+  accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
+  /**
+   * An optional callback function that will be run by the admin when
+   * committing the changes to Shopify’s servers fails. The error event you receive includes
+   * an `error` property that is an `AggregateError` object. This object includes
+   * an array of errors that were caused by data your extension provided.
+   * Network errors and user errors that are out of your control will not be reported here.
+   *
+   * In the `onError` callback, you should update your extension’s UI to
+   * highlight the fields that caused the errors, and display the error messages
+   * to the user.
+   */
+  accessor onerror: CallbackErrorEventListener<
+    typeof tagName,
+    FunctionSettingsErrorEvent['error']['errors'][0]
+  > | null;
+
+  /**
+   * A callback that is run when the function settings form is reset.
+   */
+  accessor onreset: CallbackEventListener<typeof tagName> | null;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: FunctionSettings;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: FunctionSettingsJSXProps & {
+        children?: preact.ComponentChildren;
+      };
+    }
+  }
+}
+
+export {FunctionSettings};
+export type {FunctionSettingsJSXProps};

package/src/surfaces/admin/components/Grid.d.ts

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -9,6 +9,11 @@ import type {
   BoxProps$1,
   GridProps$1,
   MaybeAllValuesShorthandProperty,
+  SizeUnits,
+  AlignItemsKeyword,
+  JustifyItemsKeyword,
+  AlignContentKeyword,
+  JustifyContentKeyword,
   ComponentChild,
 } from './shared.d.ts';
 
@@ -58,6 +63,7 @@ export type ResponsiveBoxProps = MakeResponsivePick<
   | 'paddingInline'
   | 'paddingInlineStart'
   | 'paddingInlineEnd'
+  | 'display'
 >;
 export interface BoxProps
   extends Pick<
@@ -72,7 +78,6 @@ export interface BoxProps
     | 'borderRadius'
     | 'borderStyle'
     | 'borderWidth'
-    | 'display'
     | 'inlineSize'
     | 'maxBlockSize'
     | 'maxInlineSize'
@@ -103,8 +108,7 @@ export interface BoxProps
   /**
    * Adjust the padding of all edges.
    *
-   * 1-to-4-value syntax (@see 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:
+   * [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`
@@ -118,9 +122,7 @@ export interface BoxProps
    *
    * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed.
    *
-   * `padding` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
-   *
-   * This also accepts up to 4 values (e.g. `@container (inline-size > 500px) large-300 small-300 large-100 small-100, small-200`)
+   * `padding` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
    * @default 'none'
    */
@@ -132,9 +134,7 @@ export interface BoxProps
    *
    * This overrides the block value of `padding`.
    *
-   * `paddingBlock` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
-   *
-   * This also accepts up to 2 values (e.g. `@container (inline-size > 500px) large-300 small-300, small-200`)
+   * `paddingBlock` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
@@ -144,9 +144,8 @@ export interface BoxProps
    *
    * This overrides the block-start value of `paddingBlock`.
    *
-   * `paddingBlockStart` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
+   * `paddingBlockStart` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
-   * This only accepts 1 value per predicate (e.g. `@container (inline-size > 500px) large-300, small-200`)
    * @default '' - meaning no override
    */
   paddingBlockStart: ResponsiveBoxProps['paddingBlockStart'];
@@ -155,9 +154,8 @@ export interface BoxProps
    *
    * This overrides the block-end value of `paddingBlock`.
    *
-   * `paddingBlockEnd` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
+   * `paddingBlockEnd` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
-   * This only accepts up to 1 value per predicate (e.g. `@container (inline-size > 500px) large-300, small-200`)
    * @default '' - meaning no override
    */
   paddingBlockEnd: ResponsiveBoxProps['paddingBlockEnd'];
@@ -168,9 +166,7 @@ export interface BoxProps
    *
    * This overrides the inline value of `padding`.
    *
-   * `paddingInline` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
-   *
-   * This also accepts up to 2 values (e.g. `@container (inline-size > 500px) large-300 small-300, small-200`)
+   * `paddingInline` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
@@ -180,8 +176,7 @@ export interface BoxProps
    *
    * This overrides the inline-start value of `paddingInline`.
    *
-   * `paddingInlineStart` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
-   * This only accepts 1 value per predicate (e.g. `@container (inline-size > 500px) large-300, small-200`)
+   * `paddingInlineStart` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
@@ -191,12 +186,26 @@ export interface BoxProps
    *
    * This overrides the inline-end value of `paddingInline`.
    *
-   * `paddingInlineEnd` also accepts a container query string with the supported PaddingKeyword as a query value e.g. (`@container (inline-size > 500px) large-300, small-300`)
-   * This only accepts 1 value per predicate (e.g. `@container (inline-size > 500px) large-300, small-200`)
+   * `paddingInlineEnd` also accepts a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported PaddingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
   paddingInlineEnd: ResponsiveBoxProps['paddingInlineEnd'];
+  /**
+   * Sets the outer [display](https://developer.mozilla.org/en-US/docs/Web/CSS/display) type of the component. The outer type sets a component's participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout).
+   *
+   * - `auto` the component's initial value. The actual value depends on the component and context.
+   * - `none` hides the component from display and removes it from the accessibility tree, making it invisible to screen readers.
+   *
+   * @default 'auto'
+   */
+  display: ResponsiveBoxProps['display'];
+  blockSize: SizeUnits | 'auto';
+  minBlockSize: SizeUnits | '0';
+  maxBlockSize: SizeUnits | 'none';
+  inlineSize: SizeUnits | 'auto';
+  minInlineSize: SizeUnits | '0';
+  maxInlineSize: SizeUnits | 'none';
 }
 
 export type RequiredAlignedProps = Required<GridProps$1>;
@@ -219,13 +228,21 @@ export interface GridProps
         | 'placeContent'
       >
     > {
+  alignItems: AlignItemsKeyword | '';
+  justifyItems: JustifyItemsKeyword | '';
+  placeItems: `${AlignItemsKeyword} ${JustifyItemsKeyword}` | AlignItemsKeyword;
+  alignContent: AlignContentKeyword | '';
+  justifyContent: JustifyContentKeyword | '';
+  placeContent:
+    | `${AlignContentKeyword} ${JustifyContentKeyword}`
+    | AlignContentKeyword;
   /**
    * Adjust spacing between elements.
    *
    * `gap` can either accept:
-   * * a single SpacingKeyword value applied to both axes (e.g. `large-100`).
-   * *OR a pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively.
-   * OR a container query string with supported SpacingKeyword values as query values (e.g.@container (inline-size > 500px) large-300, small-300)
+   * - a single SpacingKeyword value applied to both axes (e.g. `large-100`)
+   * - OR a pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively
+   * - OR a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported SpacingKeyword as a query value.
    *
    * @default 'none'
    */
@@ -235,8 +252,8 @@ export interface GridProps
    *
    * This overrides the row value of `gap`.
    * `rowGap` either accepts:
-   * * a single SpacingKeyword value (e.g. `large-100`)
-   * *OR a container query string with supported SpacingKeyword values as query values (e.g. @container (inline-size > 500px) large-300, small-300)
+   * - a single SpacingKeyword value (e.g. `large-100`)
+   * - OR a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported SpacingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
@@ -246,14 +263,29 @@ export interface GridProps
    *
    * This overrides the column value of `gap`.
    * `columnGap` either accepts:
-   * * a single SpacingKeyword value (e.g. `large-100`)
-   * * OR a container query string with supported SpacingKeyword values as query values (e.g. @container (inline-size > 500px) large-300, small-300)
+   * - a single SpacingKeyword value (e.g. `large-100`)
+   * - OR a [responsive value](https://shopify.dev/docs/api/app-home/using-polaris-components#responsive-values) string with the supported SpacingKeyword as a query value.
    *
    * @default '' - meaning no override
    */
   columnGap: ResponsiveGridProps['columnGap'];
 }
 
+/** Used when an element does not have children. */
+export interface PreactBaseElementProps<TClass extends HTMLElement> {
+  /** Assigns a unique key to this element. */
+  key?: preact.Key;
+  /** Assigns a ref (generally from `useRef()`) to this element. */
+  ref?: preact.Ref<TClass>;
+  /** Assigns this element to a parent's slot. */
+  slot?: Lowercase<string>;
+}
+/** Used when an element has children. */
+export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
+  extends PreactBaseElementProps<TClass> {
+  children?: preact.ComponentChildren;
+}
+
 export type Styles = string;
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
   ShadowRoot: (element: any) => ComponentChild;
@@ -362,13 +394,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: GridJSXProps & BaseProps;
+      [tagName]: GridJSXProps & PreactBaseElementPropsWithChildren<Grid>;
     }
   }
 }