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

package/src/surfaces/admin/api/standard/storage.ts

@@ -0,0 +1,110 @@
+export interface Storage<
+  BaseStorageTypes extends Record<string, any> = Record<string, unknown>,
+> {
+  /**
+   * Sets the value of a key in the storage.
+   *
+   * @param key - The key to set the value for.
+   * @param value - The value to set for the key.
+   * Can be any primitive type supported by `JSON.stringify`.
+   *
+   * Rejects with a `StorageExceededError` if the extension exceeds its allotted storage limit.
+   */
+  set<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(
+    key: Keys,
+    value: StorageTypes[Keys],
+  ): Promise<void>;
+
+  /**
+   * Sets multiple key-value pairs in the storage at once.
+   *
+   * If the operation fails, no changes are made to storage.
+   *
+   * @param entries - An object containing key-value pairs to store.
+   * Values can be any primitive type supported by `JSON.stringify`.
+   *
+   * Rejects with a `StorageExceededError` if the extension exceeds its allotted storage limit.
+   */
+  setMany<StorageTypes extends BaseStorageTypes = BaseStorageTypes>(
+    entries: Partial<StorageTypes>,
+  ): Promise<void>;
+
+  /**
+   * Gets the value of a key in the storage.
+   *
+   * @param key - The key to get the value for.
+   * @returns The value of the key.
+   *
+   * If no value for the key exists, the resolved value is undefined.
+   */
+  get<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(
+    key: Keys,
+  ): Promise<StorageTypes[Keys] | undefined>;
+
+  /**
+   * Gets the values of multiple keys in the storage at once.
+   *
+   * @param keys - An array of keys to get the values for.
+   * @returns An object containing key-value pairs for the requested keys.
+   *
+   * The returned array is in the same order as `keys`, with `undefined` values for keys that do not exist.
+   */
+  getMany<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(
+    keys: Keys[],
+  ): Promise<(StorageTypes[Keys] | undefined)[]>;
+
+  /**
+   * Clears the storage.
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Deletes a key from the storage.
+   *
+   * @param key - The key to delete.
+   * @returns A promise that resolves to `true` if the key was deleted, or `false` if the key did not exist.
+   */
+  delete<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(
+    key: Keys,
+  ): Promise<boolean>;
+
+  /**
+   * Deletes multiple keys from the storage at once.
+   *
+   * @param keys - An array of keys to delete.
+   * @returns A promise that resolves to an object with `keys` keys, and boolean values,
+   * which are `true` if the key was deleted, or `false` if the key did not exist.
+   */
+  deleteMany<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(
+    keys: Keys[],
+  ): Promise<Record<Keys, boolean>>;
+
+  /**
+   * Gets all the keys and values in the storage.
+   *
+   * @returns An iterator containing all the keys and values in the storage.
+   */
+  entries<
+    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
+    Keys extends keyof StorageTypes = keyof StorageTypes,
+  >(): Promise<IterableIterator<[Keys, StorageTypes[Keys]]>>;
+}
+
+export interface StorageExceededError extends Error {
+  name: 'StorageExceededError';
+}

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

package/src/surfaces/admin/components/AdminPrintAction/examples/default.tsx

@@ -1,7 +1,7 @@
 import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 
-export default function extension() {
+export default async () => {
   render(
     <s-admin-print-action src="https://example.com"></s-admin-print-action>,
     document.body,

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */

package/src/surfaces/admin/components/Avatar/examples/default.html

@@ -0,0 +1,4 @@
+<s-avatar
+  alt="John Doe"
+  initials="JD"
+></s-avatar>

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

@@ -0,0 +1,133 @@
+/** VERSION: 1.19.0 **/
+/* eslint-disable import/extensions */
+
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {AvatarProps$1, ComponentChild} from './shared.d.ts';
+
+export interface AvatarProps
+  extends Required<Pick<AvatarProps$1, 'initials' | 'src' | 'alt' | 'size'>> {
+  size: Extract<
+    AvatarProps$1['size'],
+    'small-200' | 'small' | 'base' | 'large' | 'large-200'
+  >;
+}
+
+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 CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  currentTarget: HTMLElementTagNameMap[T];
+};
+export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
+  | (EventListener & {
+      (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>;
+}
+/** Used when an element has children. */
+export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
+  extends PreactBaseElementProps<TClass> {
+  children?: preact.ComponentChildren;
+}
+
+declare class Avatar extends PreactCustomElement implements AvatarProps {
+  accessor initials: AvatarProps['initials'];
+  accessor src: AvatarProps['src'];
+  accessor size: AvatarProps['size'];
+  accessor alt: AvatarProps['alt'];
+  accessor onload: CallbackEventListener<typeof tagName> | null;
+  accessor onerror: OnErrorEventHandler;
+  constructor();
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: Avatar;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: AvatarJSXProps & PreactBaseElementPropsWithChildren<Avatar>;
+    }
+  }
+}
+
+declare const tagName = 's-avatar';
+export interface AvatarJSXProps
+  extends Partial<AvatarProps>,
+    Pick<AvatarProps$1, 'id'> {
+  onLoad?: () => void;
+  onError?: () => void;
+}
+
+export {Avatar};
+export type {AvatarJSXProps};

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -14,7 +14,10 @@ import type {
 } from './shared.d.ts';
 
 export interface IconProps
-  extends Pick<IconProps$1, 'type' | 'tone' | 'color' | 'size'> {
+  extends Pick<
+    IconProps$1,
+    'type' | 'tone' | 'color' | 'size' | 'interestFor'
+  > {
   /**
    * Specifies the type of icon that will be displayed.
    */
@@ -28,7 +31,7 @@ export interface IconProps
 }
 
 export interface BadgeProps
-  extends Pick<BadgeProps$1, 'color' | 'size' | 'tone'> {
+  extends Pick<BadgeProps$1, 'color' | 'icon' | 'size' | 'tone'> {
   color: Extract<BadgeProps$1['color'], 'base' | 'strong'>;
   icon: IconProps['type'] | '';
   size: Extract<BadgeProps$1['size'], 'base' | 'large' | 'large-100'>;
@@ -98,6 +101,21 @@ declare abstract class PreactCustomElement extends BaseClass {
   click({sourceEvent}?: ClickOptions): void;
 }
 
+/** 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;
+}
+
 declare class Badge extends PreactCustomElement implements BadgeProps {
   accessor color: BadgeProps['color'];
   accessor icon: BadgeProps['icon'];
@@ -111,13 +129,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: BadgeJSXProps & BaseProps;
+      [tagName]: BadgeJSXProps & PreactBaseElementPropsWithChildren<Badge>;
     }
   }
 }

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -20,20 +20,28 @@ export interface BannerProps
   >;
 }
 
-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;
+/** 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'> & {
@@ -110,13 +118,10 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<BannerJSXProps, 'secondaryActions'> & BaseProps;
+      [tagName]: Omit<BannerJSXProps, 'secondaryActions'> &
+        PreactBaseElementPropsWithChildren<Banner>;
     }
   }
 }

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -8,6 +8,7 @@
 import type {
   BoxProps$1,
   MaybeAllValuesShorthandProperty,
+  SizeUnits,
   ComponentChild,
 } from './shared.d.ts';
 
@@ -57,6 +58,7 @@ export type ResponsiveBoxProps = MakeResponsivePick<
   | 'paddingInline'
   | 'paddingInlineStart'
   | 'paddingInlineEnd'
+  | 'display'
 >;
 export interface BoxProps
   extends Pick<
@@ -71,7 +73,6 @@ export interface BoxProps
     | 'borderRadius'
     | 'borderStyle'
     | 'borderWidth'
-    | 'display'
     | 'inlineSize'
     | 'maxBlockSize'
     | 'maxInlineSize'
@@ -102,8 +103,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`
@@ -117,9 +117,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'
    */
@@ -131,9 +129,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
    */
@@ -143,9 +139,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'];
@@ -154,9 +149,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'];
@@ -167,9 +161,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
    */
@@ -179,8 +171,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
    */
@@ -190,12 +181,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 Styles = string;
@@ -286,6 +291,21 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
   accessor display: BoxProps['display'];
 }
 
+/** 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;
+}
+
 declare class Box extends BoxElement implements BoxProps {
   constructor();
 }
@@ -295,13 +315,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: BoxJSXProps & BaseProps;
+      [tagName]: BoxJSXProps & PreactBaseElementPropsWithChildren<Box>;
     }
   }
 }

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.0.0 **/
+/** VERSION: 1.19.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -15,7 +15,10 @@ import type {
 } from './shared.d.ts';
 
 export interface IconProps
-  extends Pick<IconProps$1, 'type' | 'tone' | 'color' | 'size'> {
+  extends Pick<
+    IconProps$1,
+    'type' | 'tone' | 'color' | 'size' | 'interestFor'
+  > {
   /**
    * Specifies the type of icon that will be displayed.
    */
@@ -41,6 +44,8 @@ export type ButtonBaseProps = Required<
     | 'disabled'
     | 'command'
     | 'commandFor'
+    | 'icon'
+    | 'interestFor'
     | 'lang'
     | 'loading'
     | 'type'
@@ -56,20 +61,28 @@ export interface ButtonProps extends ButtonBaseProps {
   icon: IconProps['type'];
 }
 
-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;
+/** 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'> & {
@@ -132,9 +145,9 @@ declare abstract class PreactCustomElement extends BaseClass {
 }
 
 export interface PreactOverlayControlProps
-  extends Pick<InteractionProps, 'commandFor'> {
+  extends Pick<InteractionProps, 'commandFor' | 'interestFor'> {
   /**
-   * Sets the action the `commandFor` should take when this clickable is activated.
+   * Sets the action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this clickable is activated.
    *
    * See the documentation of particular components for the actions they support.
    *
@@ -144,13 +157,19 @@ export interface PreactOverlayControlProps
    * - `--toggle`: toggles the target component.
    *
    * @default '--auto'
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
    */
   command: Extract<
     InteractionProps['command'],
     '--show' | '--hide' | '--toggle' | '--auto'
   >;
+  /**
+   * Sets the element the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this clickable is activated.
+   */
   commandFor: Extract<InteractionProps['commandFor'], string>;
+  /**
+   * Sets the element the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this clickable is activated.
+   */
+  interestFor: Extract<InteractionProps['interestFor'], string>;
 }
 
 declare const Button_base: (abstract new (
@@ -179,13 +198,9 @@ declare global {
   }
 }
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: ButtonJSXProps & BaseProps;
+      [tagName]: ButtonJSXProps & PreactBaseElementPropsWithChildren<Button>;
     }
   }
 }