@shopify/ui-extensions 2026.7.4 → 2026.10.0-rc.10

package/build/ts/surfaces/admin/components/Thumbnail.d.ts

@@ -1,4 +1,4 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.23.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -6,20 +6,32 @@
 
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {ThumbnailProps$1, ComponentChildren} from './shared.d.ts';
+import type {
+  ThumbnailProps$1,
+  PreactCustomElement,
+  RenderImpl,
+} from './shared.d.ts';
+import * as preact$1 from 'preact';
+import {ReactNode, RefAttributes} from 'react';
 
 /**
- * A callback event that's typed to a specific HTML element.
+ * An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event.
+ *
+ * This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.
  * @publicDocs
  */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
-  /**
-   * The element that currently has the event listener attached.
-   */
   currentTarget: HTMLElementTagNameMap[T];
 };
 /**
- * An event listener for callback events, typed to a specific HTML element.
+ * A function that handles events from UI components.
+ *
+ * This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.
+ *
+ * @example
+ * const handleClick: CallbackEventListener<'button'> = (event) => {
+ *   console.log('Button clicked:', event.currentTarget);
+ * };
  * @publicDocs
  */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
@@ -28,42 +40,73 @@ export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
     })
   | null;
 /**
- * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ * Base props for Preact custom elements without children support. Includes common properties like key, ref, and slot for elements that don't accept child content.
  * @publicDocs
  */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
   /**
-   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists change by tracking which items have been added, removed, or reordered.
+   * A unique identifier for this element, used by the virtual DOM to efficiently track and update elements in lists.
+   * Essential for maintaining component state and optimizing re-renders when lists change.
    */
   key?: preact.Key;
   /**
-   * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+   * A reference to access the underlying DOM element directly.
+   * Typically created using `useRef()` to interact with the element imperatively or measure its properties.
    */
   ref?: preact.Ref<TClass>;
   /**
-   * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns.
+   * The named slot to which this element is assigned in the parent component's shadow DOM.
+   *
+   * Used for advanced component composition with web components.
    */
   slot?: Lowercase<string>;
 }
 
+export type ReactIntrinsicElementChildren<PreactProps extends object> =
+  'children' extends keyof PreactProps
+    ? {
+        children?: ReactNode;
+      }
+    : Record<never, never>;
+export type ReactIntrinsicElementProps<
+  PreactProps extends object,
+  ElementType,
+> = Omit<PreactProps, 'children' | 'key' | 'ref' | 'slot'> &
+  ReactIntrinsicElementChildren<PreactProps> &
+  RefAttributes<ElementType> & {
+    slot?: Lowercase<string>;
+  };
+export type ReactIntrinsicElements = {
+  [Tag in Exclude<
+    Extract<keyof preact$1.createElement.JSX.IntrinsicElements, `s-${string}`>,
+    `s-test-${string}`
+  >]: ReactIntrinsicElementProps<
+    preact$1.createElement.JSX.IntrinsicElements[Tag],
+    Tag extends keyof HTMLElementTagNameMap
+      ? HTMLElementTagNameMap[Tag]
+      : HTMLElement
+  >;
+};
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends ReactIntrinsicElements {}
+  }
+}
+
 /**
- * The properties for the thumbnail component. A thumbnail displays a small preview image with configurable sizing. Properties include `src` for the image URL, `alt` for accessibility text, and `size` for controlling the thumbnail dimensions.
- * @publicDocs
+ * Configure the following properties on the thumbnail component.
  */
 export interface ThumbnailProps
   extends Required<Pick<ThumbnailProps$1, 'src' | 'alt' | 'size'>> {
   /**
-   * The URL of the image to display in the thumbnail. You can provide an absolute or relative URL pointing to the image file.
-   */
-  src: ThumbnailProps$1['src'];
-  /**
-   * Alternative text that describes the image for screen readers. This text should convey the meaning or content of the image to users who can't see it.
-   */
-  alt: ThumbnailProps$1['alt'];
-  /**
-   * The size of the thumbnail. Choose from `'small-200'`, `'small-100'`, `'small'`, `'base'`, `'large'`, or `'large-100'` to control the thumbnail dimensions.
+   * The size of the product thumbnail image.
    *
-   * @default 'base'
+   * - `small-200`: Smallest thumbnail size, ideal for compact product lists or tables.
+   * - `small-100`: Very small thumbnail, suitable for dense layouts.
+   * - `small`: Small thumbnail for space-constrained contexts.
+   * - `base`: Default size that balances visibility and space efficiency.
+   * - `large`: Larger thumbnail for featured products or detailed views.
+   * - `large-100`: Extra large thumbnail for prominent product display.
    */
   size: Extract<
     ThumbnailProps$1['size'],
@@ -71,126 +114,37 @@ export interface ThumbnailProps
   >;
 }
 
-/**
- * A string containing CSS styles for a custom element.
- * @publicDocs
- */
-export type Styles = string;
-/**
- * The configuration for rendering a custom element with Preact.
- * @publicDocs
- */
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  /**
-   * The function that renders the shadow root content.
-   */
-  ShadowRoot: (element: any) => ComponentChildren;
-  /**
-   * The optional CSS styles to apply to the shadow root.
-   */
-  styles?: Styles;
-};
-/**
- * The properties of an activation event, such as a click or keypress. These properties capture which modifier keys were pressed and which mouse button was used during the event.
- * @publicDocs
- */
-export interface ActivationEventEsque {
-  /**
-   * Whether the shift key was pressed during the event.
-   */
-  shiftKey: boolean;
-  /**
-   * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during the event.
-   */
-  metaKey: boolean;
-  /**
-   * Whether the control key was pressed during the event.
-   */
-  ctrlKey: boolean;
-  /**
-   * The mouse button that was pressed (0 for left, 1 for middle, 2 for right).
-   */
-  button: number;
-}
-/**
- * The options for triggering a synthetic click event.
- * @publicDocs
- */
-export interface ClickOptions {
-  /**
-   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
-   */
-  sourceEvent?: ActivationEventEsque;
-}
-/**
- * The 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;
-/**
- * An abstract base class for creating custom elements that render with Preact.
- */
-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;
+declare class PolarisCustomElement extends PreactCustomElement {
+  constructor(renderImpl: Omit<RenderImpl, 'globalShadowCSS'>);
   /** @private */
   connectedCallback(): void;
   /** @private */
-  disconnectedCallback(): void;
-  /** @private */
   adoptedCallback(): void;
-  /**
-   * Queues 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 a background tab.
-   * @private
-   * @param options
-   */
-  click({sourceEvent}?: ClickOptions): void;
 }
 
 /**
- * A thumbnail displays a small preview image with configurable sizing.
+ * Configure the following properties on the thumbnail component.
+ * @publicDocs
  */
-declare class Thumbnail extends PreactCustomElement implements ThumbnailProps {
+declare class Thumbnail extends PolarisCustomElement implements ThumbnailProps {
   /**
-   * The URL of the image to display in the thumbnail.
+   * The image source (either a remote URL or a local file resource).
+   *
+   * When the image is loading or no `src` is provided, a placeholder is rendered.
    */
   accessor src: ThumbnailProps['src'];
   /**
-   * Alternative text that describes the image for screen readers.
+   * Alternative text that describes the image for accessibility.
+   *
+   * Provides a text description of the image for users with assistive technology and serves as a fallback when the image fails to load. A well-written description enables people with visual impairments to understand non-text content.
+   *
+   * When a screen reader encounters an image, it reads this description aloud. When an image fails to load, this text displays on screen, helping all users understand what content was intended.
+   *
+   * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4) and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
    */
   accessor alt: ThumbnailProps['alt'];
-  /**
-   * The size of the thumbnail.
-   */
   accessor size: ThumbnailProps['size'];
-  /**
-   * A callback that's fired when the image has loaded successfully.
-   */
   accessor onload: CallbackEventListener<typeof tagName> | null;
-  /**
-   * A callback that's fired when the image fails to load.
-   */
   accessor onerror: OnErrorEventHandler;
   constructor();
 }
@@ -208,19 +162,15 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-thumbnail';
-/**
- * The properties for the thumbnail component when it's used in JSX.
- * @publicDocs
- */
 export interface ThumbnailJSXProps
   extends Partial<ThumbnailProps>,
     Pick<ThumbnailProps$1, 'id'> {
   /**
-   * A callback that's fired when the image has loaded successfully.
+   * A callback fired when the thumbnail image loads successfully.
    */
   onLoad?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * A callback that's fired when the image fails to load.
+   * A callback fired when the thumbnail image fails to load.
    */
   onError?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }

package/build/ts/surfaces/admin/components/Tooltip.d.ts

@@ -1,4 +1,4 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.23.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -9,151 +9,100 @@
 import type {
   ComponentChildren,
   TooltipProps$1,
+  PreactCustomElement,
+  RenderImpl,
   InteractionProps,
 } from './shared.d.ts';
+import * as preact$1 from 'preact';
+import {ReactNode, RefAttributes} from 'react';
+
+export type ReactIntrinsicElementChildren<PreactProps extends object> =
+  'children' extends keyof PreactProps
+    ? {
+        children?: ReactNode;
+      }
+    : Record<never, never>;
+export type ReactIntrinsicElementProps<
+  PreactProps extends object,
+  ElementType,
+> = Omit<PreactProps, 'children' | 'key' | 'ref' | 'slot'> &
+  ReactIntrinsicElementChildren<PreactProps> &
+  RefAttributes<ElementType> & {
+    slot?: Lowercase<string>;
+  };
+export type ReactIntrinsicElements = {
+  [Tag in Exclude<
+    Extract<keyof preact$1.createElement.JSX.IntrinsicElements, `s-${string}`>,
+    `s-test-${string}`
+  >]: ReactIntrinsicElementProps<
+    preact$1.createElement.JSX.IntrinsicElements[Tag],
+    Tag extends keyof HTMLElementTagNameMap
+      ? HTMLElementTagNameMap[Tag]
+      : HTMLElement
+  >;
+};
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends ReactIntrinsicElements {}
+  }
+}
 
 /**
- * The properties you can set on a tooltip component.
- * @publicDocs
+ * Configure the following properties on the tooltip component.
  */
 export interface TooltipProps extends Required<Pick<TooltipProps$1, 'id'>> {}
 
 /**
- * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ * Base props for Preact custom elements without children support. Includes common properties like key, ref, and slot for elements that don't accept child content.
  * @publicDocs
  */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
   /**
-   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists change by tracking which items have been added, removed, or reordered.
+   * A unique identifier for this element, used by the virtual DOM to efficiently track and update elements in lists.
+   * Essential for maintaining component state and optimizing re-renders when lists change.
    */
   key?: preact.Key;
   /**
-   * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+   * A reference to access the underlying DOM element directly.
+   * Typically created using `useRef()` to interact with the element imperatively or measure its properties.
    */
   ref?: preact.Ref<TClass>;
   /**
-   * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns.
+   * The named slot to which this element is assigned in the parent component's shadow DOM.
+   *
+   * Used for advanced component composition with web components.
    */
   slot?: Lowercase<string>;
 }
 /**
- * The base properties for Preact elements that have children, extending the base element properties to include child content.
+ * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements.
  * @publicDocs
  */
 export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
   extends PreactBaseElementProps<TClass> {
-  children?: preact.ComponentChildren;
-}
-
-/**
- * A string that contains CSS styles to apply to the component.
- * @publicDocs
- */
-export type Styles = string;
-/**
- * The implementation details for rendering a Preact custom element with a shadow root.
- * @publicDocs
- */
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  /**
-   * The function that renders the component's shadow root content.
-   */
-  ShadowRoot: (element: any) => ComponentChildren;
-  /**
-   * The CSS styles to apply to the component.
-   */
-  styles?: Styles;
-};
-/**
- * An object that resembles an activation event, containing information about which modifier keys were pressed and which mouse button was used.
- * @publicDocs
- */
-export interface ActivationEventEsque {
-  /**
-   * Whether the Shift key was pressed during the event.
-   */
-  shiftKey: boolean;
-  /**
-   * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the event.
-   */
-  metaKey: boolean;
-  /**
-   * Whether the Control key was pressed during the event.
-   */
-  ctrlKey: boolean;
   /**
-   * The mouse button that was pressed. A value of `0` means the primary button (usually left), `1` means the middle button, and `2` means the secondary button (usually right).
+   * The child elements to be rendered within this component.
    */
-  button: number;
-}
-/**
- * The options for customizing how a synthetic click is performed.
- * @publicDocs
- */
-export interface ClickOptions {
-  /**
-   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
-   */
-  sourceEvent?: ActivationEventEsque;
+  children?: preact.ComponentChildren;
 }
-/**
- * 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;
+declare class PolarisCustomElement extends PreactCustomElement {
+  constructor(renderImpl: Omit<RenderImpl, 'globalShadowCSS'>);
   /** @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;
 }
 
-/**
- * The properties for controlling overlay elements like popovers, tooltips, and menus through command interactions.
- * @publicDocs
- */
 export interface PreactOverlayControlProps
   extends Pick<InteractionProps, 'commandFor' | 'interestFor'> {
   /**
-   * The action that the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated.
-   *
-   * See the documentation of specific components for the actions they support.
+   * The action that [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated.
    *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the visibility of the target component.
    *
    * @default '--auto'
    */
@@ -162,11 +111,11 @@ export interface PreactOverlayControlProps
     '--show' | '--hide' | '--toggle' | '--auto'
   >;
   /**
-   * The element that the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this component is activated.
+   * The component that [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this component is activated.
    */
   commandFor: Extract<InteractionProps['commandFor'], string>;
   /**
-   * The element that the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this component is activated.
+   * The ID of the component to show when users hover over or focus on this component. Use this to connect interactive components to popovers or tooltips that provide additional context or information.
    */
   interestFor: Extract<InteractionProps['interestFor'], string>;
 }
@@ -174,43 +123,37 @@ export interface PreactOverlayControlProps
 /**
  * Shared symbols for overlay control functionality.
  * These symbols are used by components that implement overlay behavior
- * (such as Popover, Tooltip, and Modal) to communicate with the overlay control system.
+ * (like Popover, Tooltip, Modal, etc.) to communicate with the overlay control system.
+ */
+/**
+ * Symbol used to track the open or closed state of the overlay.
  */
-/** @private */
 declare const overlayHidden: unique symbol;
-/** @private */
+/**
+ * Symbol used to track the element that opened the overlay. In some cases, like tooltips and popovers, the overlay is positioned against this element. In all cases, focus should be restored to this element when the overlay is closed.
+ */
 declare const overlayActivator: unique symbol;
-/** @private */
 declare const overlayHideFrameId: unique symbol;
 /**
- * The initialization object for creating a polyfill command event.
+ * Represents the initialization object for creating a polyfill command event. Used for overlay control commands in environments that require polyfills.
  * @publicDocs
  */
 export type PolyfillCommandEventInit = EventInit & {
-  /**
-   * The element that triggered the command.
-   */
   source: HTMLElement | null | undefined;
-  /**
-   * The command action that should be performed.
-   */
   command: PreactOverlayControlProps['command'];
+  rootActivator?: HTMLElement | null;
 };
 /**
- * A polyfill event for the command interaction pattern, which is used to control overlay elements.
+ * Represents a polyfill command event for overlay controls. Used in environments where native command events are not available.
  * @publicDocs
  */
 export type PolyfillCommandEvent = Event & {
-  /**
-   * The element that triggered the command.
-   */
   source: PolyfillCommandEventInit['source'];
-  /**
-   * The command action that should be performed.
-   */
   command: PolyfillCommandEventInit['command'];
-  /** You have to use `_s_shadowSource` because `source` is retargeted to the shadow host by browsers. */
+  /** Have to use `_s_shadowSource` because `source` is retargeted to the shadow host by browsers */
   _s_shadowSource: PolyfillCommandEventInit['source'];
+  /** Root activator for nested overlays (e.g., menu button when modal opened from menu item) */
+  _s_rootActivator?: HTMLElement | null;
 };
 declare global {
   interface GlobalEventHandlersEventMap {
@@ -218,15 +161,11 @@ declare global {
   }
 }
 
-/**
- * The base class for overlay elements that can be shown and hidden through command interactions.
- */
-declare class PreactOverlayElement extends PreactCustomElement {
-  /**
-   * Creates a new overlay element with the given render implementation.
-   */
+declare class PreactOverlayElement extends PolarisCustomElement {
   constructor(renderImpl: RenderImpl);
   /** @private */
+  disconnectedCallback(): void;
+  /** @private */
   [overlayHidden]: boolean;
   /** @private */
   [overlayActivator]: HTMLElement | null | undefined;
@@ -235,12 +174,10 @@ declare class PreactOverlayElement extends PreactCustomElement {
 }
 
 /**
- * A component that displays a small popup with explanatory text when the user hovers over or focuses on an element.
+ * Configure the following properties on the tooltip component.
+ * @publicDocs
  */
 declare class Tooltip extends PreactOverlayElement implements TooltipProps {
-  /**
-   * Creates a new Tooltip instance.
-   */
   constructor();
 }
 declare global {
@@ -256,19 +193,14 @@ declare module 'preact' {
   }
 }
 
-/**
- * The custom element tag name for the tooltip component.
- */
 declare const tagName = 's-tooltip';
-/**
- * The JSX properties you can set on a tooltip component.
- * @publicDocs
- */
 export interface TooltipJSXProps
   extends Partial<TooltipProps>,
     Pick<TooltipProps$1, 'id' | 'children'> {
   /**
-   * The content to display inside the tooltip, which should include text or paragraph components, or raw text content.
+   * The informational text or elements displayed within the tooltip overlay, providing helpful context or explanations when users interact with the associated element.
+   *
+   * Only accepts text, paragraph components, and raw `textContent`.
    */
   children?: ComponentChildren;
 }