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

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.23.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -15,43 +15,106 @@ import type {
   SizeUnits,
   SizeUnitsOrNone,
   InteractionProps,
+  PreactCustomElement,
+  RenderImpl,
 } from './shared.d.ts';
+import * as preact$1 from 'preact';
+import {ReactNode, RefAttributes} from 'react';
+import * as _shopify_admin_web_component_foundations from '@shopify/admin-web-component-foundations';
 
+/**
+ * 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 & {
   currentTarget: HTMLElementTagNameMap[T];
 };
+/**
+ * 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> =
   | (EventListener & {
       (event: CallbackEvent<T>): void;
     })
   | 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>;
 }
 /**
- * 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> {
+  /**
+   * The child elements to be rendered within this component.
+   */
   children?: preact.ComponentChildren;
 }
-/**  * @publicDocs
+
+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 {}
+  }
+}
+
+/**
+ * Makes a type responsive by allowing it to be either the base value or a container query string. This enables conditional styling based on container dimensions.
+ * @publicDocs
  */
 export type MakeResponsive<T> = T | `@container${string}`;
 /**
@@ -75,7 +138,24 @@ export type MakeResponsivePick<TType, TProperty extends keyof TType> = {
   [P in TProperty]: MakeResponsive<TType[P]>;
 };
 
+/**
+ * Represents the box component props with all properties marked as required.
+ * @publicDocs
+ */
 export type RequiredBoxProps = Required<BoxProps$1>;
+/**
+ * Represents the subset of border radius values supported by the component.
+ *
+ * - `small-200`: Extra small radius for subtle rounding.
+ * - `small-100`: Small radius for minimal corner rounding.
+ * - `small`: Standard small radius.
+ * - `base`: Medium radius for moderate corner rounding.
+ * - `large`: Standard large radius for pronounced rounding.
+ * - `large-100`: Large radius for more prominent corner rounding.
+ * - `large-200`: Extra large radius for maximum rounding.
+ * - `none`: No border radius (sharp corners).
+ * @publicDocs
+ */
 export type BoxBorderRadii = Extract<
   RequiredBoxProps['borderRadius'],
   | 'none'
@@ -87,10 +167,25 @@ export type BoxBorderRadii = Extract<
   | 'large-100'
   | 'large-200'
 >;
+/**
+ * Represents the subset of border style values supported by the box component.
+ *
+ * - `auto`: Default border style determined by the system.
+ * - `none`: No border style (removes the border).
+ * - `solid`: Continuous line border.
+ * - `dashed`: Border made up of dashes.
+ * @publicDocs
+ */
 export type BoxBorderStyles = Extract<
   RequiredBoxProps['borderStyle'],
   'none' | 'solid' | 'dashed' | 'auto'
 >;
+/**
+ * Represents box props with responsive capabilities for layout properties.
+ *
+ * This enables conditional styling based on container queries.
+ * @publicDocs
+ */
 export type ResponsiveBoxProps = MakeResponsivePick<
   RequiredBoxProps,
   | 'padding'
@@ -123,7 +218,7 @@ export interface BoxProps
     | 'overflow'
   > {
   /**
-   * The background color of the clickable element.
+   * The background color of the component.
    *
    * @default 'transparent'
    */
@@ -132,16 +227,13 @@ export interface BoxProps
     'transparent' | 'base' | 'subdued' | 'strong'
   >;
   /**
-   * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
+   * A border applied using shorthand syntax to specify width, color, and style in a single property.
    *
-   * - `small`: Thin border for subtle definition.
-   * - `small-100`: Extra thin border for minimal emphasis.
-   * - `base`: Standard border width.
-   * - `large`: Thick border for strong emphasis.
-   * - `large-100`: Extra thick border for maximum prominence.
-   * - `none`: No border.
-   *
-   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different widths per side.
+   * @default 'none'
+   */
+  border: RequiredBoxProps['border'];
+  /**
+   * The thickness of the border on all sides. When set, this overrides the width value specified in the `border` property.
    *
    * @default '' - meaning no override
    */
@@ -154,10 +246,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Controls the visual style of the border on all sides (solid, dashed, auto, or none).
-   *
-   * When set, this overrides the style value specified in the `border` property.
-   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side.
+   * The visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property.
    *
    * @default '' - meaning no override
    */
@@ -165,10 +254,7 @@ export interface BoxProps
     | MaybeAllValuesShorthandProperty<BoxBorderStyles>
     | Extract<RequiredBoxProps['borderStyle'], ''>;
   /**
-   * Controls the color of the border using the design system's color scale.
-   *
-   * When set, this overrides the color value specified in the `border` property.
-   * Choose from `subdued`, `base`, or `strong` to match the visual emphasis needed.
+   * The color of the border using the design system's color scale. When set, this overrides the color value specified in the `border` property.
    *
    * @default '' - meaning no override
    */
@@ -177,101 +263,85 @@ export interface BoxProps
     'subdued' | 'base' | 'strong' | ''
   >;
   /**
-   * Controls the roundedness of the element's corners using the design system's radius scale.
-   *
-   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different radii per corner. Use this to create rounded or pill-shaped clickable elements.
+   * The roundedness of the element's corners using the design system's radius scale.
    *
    * @default 'none'
    */
   borderRadius: MaybeAllValuesShorthandProperty<BoxBorderRadii>;
   /**
-   * The padding applied to all edges of the clickable element.
-   *
-   * [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:
+   * The padding applied to all edges of the component.
    *
-   * - 4 values: `block-start inline-end block-end inline-start`
-   * - 3 values: `block-start inline block-end`
-   * - 2 values: `block inline`
+   * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values:
+   * - 1 value applies to all sides
+   * - 2 values apply to block (top/bottom) and inline (left/right)
+   * - 3 values apply to block-start (top), inline (left/right), and block-end (bottom)
+   * - 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left)
    *
-   * 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`.
+   * **Examples:** `base`, `large none`, `base large-100 base small`
    *
-   * 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 [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Use `auto` to inherit padding from the nearest container with removed padding. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default 'none'
    */
   padding: ResponsiveBoxProps['padding'];
   /**
-   * The padding applied to the block axis (top and bottom in horizontal writing modes).
+   * The block-direction padding (top and bottom in horizontal writing modes).
    *
-   * - `large none` means block-start padding is `large`, block-end padding is `none`.
+   * Accepts a single value for both sides or two space-separated values for block-start and block-end.
    *
-   * This overrides the block value of `padding`.
+   * **Example:** `large none` applies `large` to the top and `none` to the bottom.
    *
-   * `paddingBlock` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the block value from `padding`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlock: ResponsiveBoxProps['paddingBlock'];
   /**
-   * The padding applied to the block-start edge (top in horizontal writing modes).
-   *
-   * This overrides the block-start value of `paddingBlock`.
+   * The block-start padding (top in horizontal writing modes).
    *
-   * `paddingBlockStart` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the block-start value from `paddingBlock`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlockStart: ResponsiveBoxProps['paddingBlockStart'];
   /**
-   * The padding applied to the block-end edge (bottom in horizontal writing modes).
+   * The block-end padding (bottom in horizontal writing modes).
    *
-   * This overrides the block-end value of `paddingBlock`.
-   *
-   * `paddingBlockEnd` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the block-end value from `paddingBlock`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingBlockEnd: ResponsiveBoxProps['paddingBlockEnd'];
   /**
-   * The padding applied to the inline axis (left and right in horizontal writing modes).
+   * The inline-direction padding (left and right in horizontal writing modes).
    *
-   * - `large none` means inline-start padding is `large`, inline-end padding is `none`.
+   * Accepts a single value for both sides or two space-separated values for inline-start and inline-end.
    *
-   * This overrides the inline value of `padding`.
+   * **Example:** `large none` applies `large` to the left and `none` to the right.
    *
-   * `paddingInline` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the inline value from `padding`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingInline: ResponsiveBoxProps['paddingInline'];
   /**
-   * The padding applied to the inline-start edge (left in left-to-right languages).
-   *
-   * This overrides the inline-start value of `paddingInline`.
+   * The inline-start padding (left in LTR writing modes, right in RTL).
    *
-   * `paddingInlineStart` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the inline-start value from `paddingInline`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
    *
    * @default '' - meaning no override
    */
   paddingInlineStart: ResponsiveBoxProps['paddingInlineStart'];
   /**
-   * The padding applied to the inline-end edge (right in left-to-right languages).
+   * The inline-end padding (right in LTR writing modes, left in RTL).
    *
-   * This overrides the inline-end value of `paddingInline`.
-   *
-   * `paddingInlineEnd` also accepts a [responsive value](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported `PaddingKeyword` as a query value.
+   * Overrides the inline-end value from `paddingInline`. Also accepts a [responsive value](/docs/api/polaris/using-polaris-web-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).
+   * 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.
@@ -280,7 +350,7 @@ export interface BoxProps
    */
   display: ResponsiveBoxProps['display'];
   /**
-   * The vertical size of the component in standard layouts (height in left-to-right or right-to-left writing modes).
+   * The vertical size of the element in standard layouts (height in left-to-right or right-to-left writing modes).
    *
    * Block size adjusts based on the writing direction: in horizontal layouts, it controls the height;
    * in vertical layouts, it controls the width. This ensures consistent behavior across different text directions.
@@ -291,37 +361,53 @@ export interface BoxProps
    */
   blockSize: SizeUnitsOrAuto;
   /**
-   * The [minimum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) (minimum height in horizontal writing modes) of the clickable element.
+   * The minimum height in horizontal writing modes, or minimum width in vertical writing modes.
+   * Prevents the element from shrinking below this size.
+   *
+   * Learn more about [min-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
    *
    * @default '0'
    */
   minBlockSize: SizeUnits;
   /**
-   * The [maximum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) (maximum height in horizontal writing modes) of the clickable element.
+   * The maximum height in horizontal writing modes, or maximum width in vertical writing modes.
+   * Prevents the element from growing beyond this size.
+   *
+   * Learn more about [max-block-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
    *
    * @default 'none'
    */
   maxBlockSize: SizeUnitsOrNone;
   /**
-   * The [inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size) (width in horizontal writing modes) of the clickable element.
+   * The width in horizontal writing modes, or height in vertical writing modes.
+   * Use this for flow-relative sizing that adapts to text direction. Learn more about [inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
    *
    * @default 'auto'
    */
   inlineSize: SizeUnitsOrAuto;
   /**
-   * The [minimum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) (minimum width in horizontal writing modes) of the clickable element.
+   * The minimum width in horizontal writing modes, or minimum height in vertical writing modes.
+   * Prevents the element from shrinking below this size.
+   *
+   * Learn more about [min-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
    *
    * @default '0'
    */
   minInlineSize: SizeUnits;
   /**
-   * The [maximum inline size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) (maximum width in horizontal writing modes) of the clickable element.
+   * The maximum width in horizontal writing modes, or maximum height in vertical writing modes.
+   * Prevents the element from growing beyond this size.
+   *
+   * Learn more about [max-inline-size](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
    *
    * @default 'none'
    */
   maxInlineSize: SizeUnitsOrNone;
 }
-/**  * @publicDocs
+
+/**
+ * Represents the base clickable props with all properties marked as required.
+ * @publicDocs
  */
 export type ClickableBaseProps = Required<
   Pick<
@@ -340,87 +426,47 @@ export type ClickableBaseProps = Required<
   >
 >;
 /**
- * The properties for the clickable component. These properties define a low-level interactive container element that responds to user clicks while inheriting all box styling capabilities. The component serves as a foundation for building custom interactive components.
- * @publicDocs
- */
-export interface ClickableProps
-  extends Required<BoxProps>,
-    ClickableBaseProps {}
-/**  * @publicDocs
+ * Configure the following properties on the clickable component.
  */
-export type Styles = string;
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  ShadowRoot: (element: any) => ComponentChildren;
-  styles?: Styles;
-};
-export interface ActivationEventEsque {
-  shiftKey: boolean;
-  metaKey: boolean;
-  ctrlKey: boolean;
-  button: number;
-}
-/**  *
- * @publicDocs
- */
-export interface ClickOptions {
+export interface ClickableProps extends Required<BoxProps>, ClickableBaseProps {
   /**
-   * 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.
+   * Whether the component is in a loading state, which indicates to assistive technology that an action is in progress and prevents interaction.
    */
-  sourceEvent?: ActivationEventEsque;
+  loading: Required<ClickableProps$1>['loading'];
+  /**
+   * The language of the text content.
+   *
+   * Use this when the text is in a different language than the rest of the page, allowing assistive technologies
+   * such as screen readers to invoke the correct pronunciation.
+   *
+   * The value should be a valid language subtag from the [IANA language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
+   *
+   * @default ''
+   */
+  lang: Required<ClickableProps$1>['lang'];
+  /**
+   * Whether the component is disabled, preventing clicks and focus. When disabled, the `click` event won't fire and click events from child elements stop propagating immediately. Interactive child elements can still receive focus and be interacted with. This doesn't apply visual styling by default. You should apply disabled styling as needed.
+   */
+  disabled: Required<ClickableProps$1>['disabled'];
 }
-/**
- * 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;
 }
-/**  * @publicDocs
- */
+
 export interface PreactOverlayControlProps
   extends Pick<InteractionProps, 'commandFor' | 'interestFor'> {
   /**
-   * The action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated. The supported actions vary by target component type.
+   * The action that [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated.
    *
-   * - `--auto`: Performs the default action appropriate for the target component.
-   * - `--show`: Displays the target component if it's currently hidden.
-   * - `--hide`: Conceals the target component from view.
-   * - `--toggle`: Alternates the target component between visible and hidden states.
+   * - `--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'
    */
@@ -429,16 +475,16 @@ export interface PreactOverlayControlProps
     '--show' | '--hide' | '--toggle' | '--auto'
   >;
   /**
-   * Sets the component 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>;
   /**
-   * Sets the component 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>;
 }
 
-declare class BoxElement extends PreactCustomElement implements BoxProps {
+declare class BoxElement extends PolarisCustomElement implements BoxProps {
   constructor(renderImpl: RenderImpl);
   accessor accessibilityRole: BoxProps['accessibilityRole'];
   accessor background: BoxProps['background'];
@@ -467,18 +513,50 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
 }
 
 declare const Clickable_base: (abstract new (
-  renderImpl: RenderImpl,
+  renderImpl: _shopify_admin_web_component_foundations.RenderImpl,
 ) => BoxElement & PreactOverlayControlProps) &
   Pick<typeof BoxElement, 'prototype' | 'observedAttributes'>;
+/**
+ * Configure the following properties on the clickable component.
+ * @publicDocs
+ */
 declare class Clickable extends Clickable_base implements ClickableProps {
   accessor disabled: ClickableProps['disabled'];
   accessor loading: ClickableProps['loading'];
+  /**
+   * The browsing context where the linked URL should be displayed.
+   *
+   * - `auto`: The target is automatically determined based on the origin of the URL.
+   * - `_blank`: Opens the URL in a new window or tab.
+   * - `_self`: Opens the URL in the same browsing context as the current one.
+   * - `_parent`: Opens the URL in the parent browsing context of the current one. If there is no parent, behaves as `_self`.
+   * - `_top`: Opens the URL in the topmost browsing context (the highest ancestor of the current one). If there is no ancestor, behaves as `_self`.
+   */
   accessor target: ClickableProps['target'];
+  /**
+   * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
+   */
   accessor href: ClickableProps['href'];
+  /**
+   * Prompts the browser to download the linked URL rather than navigate to it. When set, the value specifies the suggested filename for the downloaded file.
+   *
+   * The filename suggestion is only respected for same-origin URLs, `blob:`, and `data:` schemes. Cross-origin URLs can still trigger downloads, but browsers might ignore the suggested filename.
+   *
+   * Learn more about the [download attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
+   */
   accessor download: ClickableProps['download'];
   accessor onclick: CallbackEventListener<typeof tagName> | null;
   accessor onblur: CallbackEventListener<typeof tagName> | null;
   accessor onfocus: CallbackEventListener<typeof tagName> | null;
+  /**
+   * The behavior of the button component.
+   *
+   * - `button`: Used to indicate the component acts as a button, meaning it has no default action.
+   * - `reset`: Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values).
+   * - `submit`: Used to indicate the component acts as a submit button, meaning it submits the closest form.
+   *
+   * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set.
+   */
   accessor type: ClickableProps['type'];
   constructor();
 }
@@ -497,85 +575,25 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-clickable';
-/**
- * The JSX properties for the clickable component. These properties define how a clickable container is rendered in Preact or JSX.
- * @publicDocs
- */
 export interface ClickableJSXProps
   extends Partial<ClickableProps>,
     Pick<ClickableProps$1, 'id' | 'children'> {
   /**
-   * The content to display inside the component. This can include text, components, or any other UI elements.
+   * The content displayed within the clickable component, which makes any content interactive and clickable without the semantic meaning of a button or link.
    */
   children?: ComponentChildren;
   /**
-   * A callback function that's invoked when the component is clicked. It receives the click event as an argument.
+   * A callback fired when the chip is clicked.
    */
   onClick?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * A callback function that's invoked when the component receives focus. It receives the focus event as an argument.
+   * A callback fired when the chip receives focus.
    */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * A callback function that's invoked when the component loses focus. It receives the blur event as an argument.
+   * A callback fired when the chip loses focus.
    */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  /**
-   * A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
-   *
-   * @default ''
-   */
-  accessibilityLabel?: string;
-  /**
-   * Whether the component is disabled, preventing interaction. When disabled, the `click` event won't fire and click events from child elements stop propagating immediately. Interactive child elements can still receive focus and be interacted with. This doesn't apply visual styling by default. You should apply disabled styling as needed.
-   *
-   * @default false
-   */
-  disabled?: boolean;
-  /**
-   * Whether a loading indicator is displayed and interaction is prevented. Set this to `true` to show that an action triggered by the click is in progress.
-   *
-   * @default false
-   */
-  loading?: boolean;
-  /**
-   * The URL that the component navigates to when clicked. When provided, the component behaves as a link.
-   *
-   * @default ''
-   */
-  href?: string;
-  /**
-   * Where to open the linked document when the component acts as a link (when `href` is provided). Available options:
-   * - `''` - Opens in the same frame (default behavior).
-   * - `'_blank'` - Opens in a new window or tab.
-   * - `'_self'` - Opens in the same frame (explicit version of default).
-   * - `'_parent'` - Opens in the parent frame.
-   * - `'_top'` - Opens in the full body of the window.
-   *
-   * @default ''
-   */
-  target?: string;
-  /**
-   * The filename to save the linked URL as when downloaded. This only works when `href` is provided.
-   *
-   * @default ''
-   */
-  download?: string;
-  /**
-   * The language of the component's content, specified as a BCP 47 language tag (such as `en` or `fr`). This helps assistive technologies pronounce content correctly.
-   *
-   * @default ''
-   */
-  lang?: string;
-  /**
-   * The component's behavior in forms when it's used as a form control. Available options:
-   * - `'button'` - A standard clickable with no default behavior.
-   * - `'submit'` - Submits the form data to the server.
-   * - `'reset'` - Resets all form controls to their initial values.
-   *
-   * @default 'button'
-   */
-  type?: string;
 }
 
 export {Clickable};