diff --git a/.changeset/admin-component-type-drift.md b/.changeset/admin-component-type-drift.md new file mode 100644 index 0000000000..526d411123 --- /dev/null +++ b/.changeset/admin-component-type-drift.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': minor +--- + +Regenerate the Admin per-component types so they match the components as shipped. Around 35 components gain properties that existed in the implementation but were missing from the types, including the whole of `DatePicker` (`allow`, `allowDays`, `defaultValue`, `defaultView`, `disallow`, `disallowDays`, `value`, `view`, `visibleMonths`), typography properties on `Text`, `Paragraph`, and `Heading` (`fontSize`, `fontWeight`, `fontVariantNumeric`), `Banner`'s `heading` and `dismissible`, `Button`'s `variant` and `accessibilityLabel`, and `ColorPicker`'s `alpha`, `value`, and `defaultValue`. diff --git a/.changeset/admin-number-empty-state-types.md b/.changeset/admin-number-empty-state-types.md new file mode 100644 index 0000000000..56ceddbb09 --- /dev/null +++ b/.changeset/admin-number-empty-state-types.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': minor +--- + +Add Admin `Number` and `EmptyState` types. `Number` exposes the `tone`, `color`, `fontSize`, and `fontWeight` properties; `EmptyState` exposes the `heading` property and the `graphic`, `subheading`, `primaryAction`, and `secondaryActions` slots. diff --git a/.changeset/admin-section-header-slots.md b/.changeset/admin-section-header-slots.md new file mode 100644 index 0000000000..50cc5dfe7a --- /dev/null +++ b/.changeset/admin-section-header-slots.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': minor +--- + +Added `subheading` property and the `primaryAction`, `secondaryActions`, `graphic`, `accessory`, and `supplemental` slots to Admin `Section`. diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminAction.d.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminAction.d.ts index 1b9f978638..ac304f6b26 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/AdminAction.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/AdminAction.d.ts @@ -1,151 +1,105 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, AdminActionProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + AdminActionProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * The properties for the admin action component. These properties configure the heading and loading state of the admin action extension interface. + * Configure the following properties on the admin action component. * @publicDocs */ export interface AdminActionProps - extends Pick {} + extends Pick { + /** + * Whether the action is in a loading state, such as during initial page load or when the action is being opened. + * When `true`, the action is in an inert state that prevents user interaction. + * + * @default false + */ + loading: AdminActionProps$1['loading']; +} -declare const tagName = 's-admin-action'; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 JSX props for the admin action component. These properties extend `AdminActionProps` with slots for primary and secondary action buttons that merchants can interact with. - * @publicDocs - */ +declare const tagName = 's-admin-action'; export interface AdminActionJSXProps extends Partial, Pick { /** - * The primary action button or link to display in the admin action area. This is the main call-to-action that appears prominently in the interface. Typically uses a button component with `variant="primary"` to complete or advance the workflow. + * The main action button or link displayed in the admin action modal. + * This represents the primary or most important action that users can take in this modal context, typically displayed with high visual prominence. */ primaryAction: ComponentChildren; /** - * The secondary action buttons or links to display in the admin action area. These are supporting actions like cancel, back, or alternative operations. Typically uses button components with `variant="secondary"` or `variant="tertiary"`. + * Additional action buttons or links displayed in the admin action modal. + * These provide alternative or supporting actions, visually de-emphasized compared to the primary action to establish clear hierarchy. */ secondaryActions: ComponentChildren; } -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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 admin action custom element class that renders action controls in the Shopify admin interface. This component creates a standardized action area with a heading and slots for primary and secondary action buttons, used exclusively in admin action extensions. + * Configure the following properties on the admin action component. + * @publicDocs */ declare class AdminAction - extends PreactCustomElement + extends PolarisCustomElement implements AdminActionProps { /** - * The heading text to display at the top of the action area. This title describes the action or task the merchant is performing. If not provided, the extension name is used as the heading. + * The text to use as the Action modal's title. If not provided, the name of the extension will be used. */ heading: string; - /** - * Whether the action extension is currently in a loading state, such as during initial data fetching or when opening the action. When `true`, the action area might display loading indicators and prevent user interaction until loading completes. - * - * @default false + * Whether the action is in a loading state, such as during initial page load or when the action is being opened. When `true`, the action might be in an inert state that prevents user interaction. */ loading: boolean; - constructor(); } declare global { diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminBlock.d.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminBlock.d.ts index 6d80f01de6..5cfdddc8a7 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/AdminBlock.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/AdminBlock.d.ts @@ -1,140 +1,55 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {AdminBlockProps$1, ComponentChildren} from './shared.d.ts'; +import type { + AdminBlockProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; /** - * The properties for the admin block component. These properties configure the heading and collapsed summary of collapsible content blocks in the admin interface. + * Configure the following properties on the admin block component. * @publicDocs */ export interface AdminBlockProps - extends Pick {} - -declare const tagName = 's-admin-block'; - -/** - * The JSX props for the admin block component. These properties extend `AdminBlockProps` with an optional `id` for element identification in JSX rendering. - * @publicDocs - */ -export interface AdminBlockJSXProps - extends Partial, - Pick {} - -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; + extends Pick { /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. + * The text displayed as the block's title in the header. If not provided, the extension name will be used. */ - metaKey: boolean; + heading: AdminBlockProps$1['heading']; /** - * Whether the Control key was pressed during the activation event. + * The summary text displayed when the app block is collapsed. Summaries longer than 30 characters will be truncated. */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; + collapsedSummary: AdminBlockProps$1['collapsedSummary']; } -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; +declare const tagName = 's-admin-block'; +export interface AdminBlockJSXProps + extends Partial, + Pick {} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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 admin block custom element class that renders a collapsible content block in the Shopify admin interface. This component organizes content into expandable sections with headings and provides a summary when collapsed. + * Configure the following properties on the admin block component. + * @publicDocs */ declare class AdminBlock - extends PreactCustomElement + extends PolarisCustomElement implements AdminBlockProps { - /** - * The heading text to display at the top of the block. This title describes the content section the merchant is viewing. If not provided, no heading is displayed. - */ heading: string; - - /** - * The summary text to display when the block is collapsed. This provides merchants with a preview of the block's contents without expanding it. If not provided, no summary is displayed. - */ collapsedSummary: string; - constructor(); } declare global { diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction.d.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction.d.ts index cca98e64c7..f5790035e8 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction.d.ts @@ -1,135 +1,54 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {AdminPrintActionProps$1, ComponentChildren} from './shared.d.ts'; +import type { + AdminPrintActionProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; /** - * The properties for the admin print action component. These properties configure the source URL for printing content within admin extensions. + * Configure the following properties on the admin print action component. * @publicDocs */ export interface AdminPrintActionProps - extends Pick {} + extends Pick { + /** + * The URL of the document to preview and print. Supports HTML, PDF, and image formats. + * If not provided, the preview will show an empty state and the print button will be disabled. + */ + src: AdminPrintActionProps$1['src']; +} declare const tagName = 's-admin-print-action'; - -/** - * The JSX props for the admin print action component. These properties extend `AdminPrintActionProps` with an optional `id` for element identification in JSX rendering. - * @publicDocs - */ export interface AdminPrintActionJSXProps extends Partial, Pick {} -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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 admin print action custom element class that renders a print interface in the Shopify admin. This component enables merchants to print content from a specified source URL using the browser's print functionality. + * Configure the following properties on the admin print action component. + * @publicDocs */ declare class AdminPrintAction - extends PreactCustomElement + extends PolarisCustomElement implements AdminPrintActionProps { /** - * The source URL of the content to print. This should point to the document or page that'll be sent to the printer when the merchant initiates the print action. + * The `src` URL of the preview and the document to print. If not provided, the preview will show an empty state and the print button will be disabled. HTML, PDFs, and images are supported. */ src: string; - constructor(); } declare global { diff --git a/packages/ui-extensions/src/surfaces/admin/components/AppNav.d.ts b/packages/ui-extensions/src/surfaces/admin/components/AppNav.d.ts index 359288d2bc..d3f5a20b75 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/AppNav.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/AppNav.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.67.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,9 +10,42 @@ import type { PreactCustomElement, RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; export interface AppNavProps {} +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + declare const tagName = 's-app-nav'; export interface AppNavJSXProps extends Partial, @@ -20,6 +53,10 @@ export interface AppNavJSXProps declare class PolarisCustomElement extends PreactCustomElement { constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; } declare class AppNav extends PolarisCustomElement implements AppNavProps { diff --git a/packages/ui-extensions/src/surfaces/admin/components/Avatar.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Avatar.d.ts index ffa9595c85..357423c188 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Avatar.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Avatar.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,146 +6,124 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {AvatarProps$1, ComponentChildren} from './shared.d.ts'; +import type { + AvatarProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 avatar component. An avatar displays a user or entity image with fallback initials when the image isn't available. Properties include `src` for the image URL, `initials` for the fallback text, `alt` for accessibility text, and `size` for controlling the avatar dimensions. - * @publicDocs + * Configure the following properties on the avatar component. */ export interface AvatarProps extends Required> { /** - * The initials to display when no image is provided or if the image fails to load. This typically includes the first letter of a user's first and last name (for example, `'JD'` for John Doe). - */ - initials: AvatarProps$1['initials']; - /** - * The URL of the avatar image to display. You can provide an absolute or relative URL pointing to the image file. - */ - src: AvatarProps$1['src']; - /** - * Alternative text that describes the avatar for screen readers. This text should identify who or what the avatar represents. - */ - alt: AvatarProps$1['alt']; - /** - * The size of the avatar. Choose from `'small-200'`, `'small'`, `'base'`, `'large'`, or `'large-200'` to control the avatar dimensions. + * The size of the avatar image. * - * @default 'base' + * - `small-200`: Extra small avatar, suitable for compact displays or lists with many items. + * - `small-100`: Alias of `small`. + * - `small`: Small avatar, good for secondary contexts or tight layouts. + * - `base`: Default size that works well in most contexts. + * - `large`: Large avatar for emphasis or when the avatar is a focal point. + * - `large-100`: Alias of `large`. + * - `large-200`: Extra large avatar for prominent display. */ size: Extract< AvatarProps$1['size'], - 'small-200' | 'small' | 'base' | 'large' | 'large-200' + | 'small-200' + | 'small-100' + | 'small' + | 'base' + | 'large' + | 'large-100' + | 'large-200' >; -} - -/** - * 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 & { - /** - * 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. + * Alternative text that describes the avatar for accessibility. + * + * Provides a text description of the avatar for users with assistive technology + * and serves as a fallback when the avatar fails to load. A well-written description + * enables people with visual impairments to understand non-text content. + * + * When a screen reader encounters an avatar, it reads this description aloud. + * When an avatar 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). */ - metaKey: boolean; + alt: Required['alt']; /** - * Whether the control key was pressed during the event. + * The URL or path to the avatar image. When provided, the image takes priority over `initials`. + * If the image fails to load or loads slowly, `initials` will be rendered as a fallback. */ - ctrlKey: boolean; + src: Required['src']; /** - * The mouse button that was pressed (0 for left, 1 for middle, 2 for right). + * The initials to display in the avatar when no image is provided or fails to load. + * Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe. */ - button: number; + initials: Required['initials']; } -/** - * 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); /** @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 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 = 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 = @@ -154,51 +132,38 @@ export type CallbackEventListener = }) | 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 { /** - * 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; /** - * 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; } /** - * An avatar displays a user or entity image with fallback initials when the image isn't available. + * Configure the following properties on the avatar component. + * @publicDocs */ -declare class Avatar extends PreactCustomElement implements AvatarProps { - /** - * The initials to display when no image is provided or if the image fails to load. - */ +declare class Avatar extends PolarisCustomElement implements AvatarProps { accessor initials: AvatarProps['initials']; - /** - * The URL of the avatar image to display. - */ accessor src: AvatarProps['src']; - /** - * The size of the avatar. - */ accessor size: AvatarProps['size']; - /** - * Alternative text that describes the avatar for screen readers. - */ accessor alt: AvatarProps['alt']; - /** - * A callback that's fired when the avatar image has loaded successfully. - */ accessor onload: CallbackEventListener | null; - /** - * A callback that's fired when the avatar image fails to load. - */ accessor onerror: OnErrorEventHandler; constructor(); } @@ -216,19 +181,15 @@ declare module 'preact' { } declare const tagName = 's-avatar'; -/** - * The properties for the avatar component when it's used in JSX. - * @publicDocs - */ export interface AvatarJSXProps extends Partial, Pick { /** - * A callback that's fired when the avatar image has loaded successfully. + * A callback fired when the avatar image loads successfully. */ onLoad?: () => void; /** - * A callback that's fired when the avatar image fails to load. + * A callback fired when the avatar image fails to load. */ onError?: () => void; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Badge.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Badge.d.ts index d1a0d99533..3ab4d685a8 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Badge.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Badge.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -11,30 +11,68 @@ import type { IconProps$1, BadgeProps$1, IconType, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 configuration for icons used within Badge components. Defines the visual appearance, size, and semantic meaning of icons displayed in badges. - * @publicDocs + * Configure the following properties on the icon component. */ export interface IconProps - extends Pick< - IconProps$1, - 'type' | 'tone' | 'color' | 'size' | 'interestFor' + extends Required< + Pick > { /** - * The type of icon to display inside the badge. Use any valid icon name from the admin icon set, an empty string for no icon, or `'empty'` to reserve space for an icon without displaying one. + * The icon to display from the icon library. + * + * Set to a valid icon name to display that icon. To hide the icon completely, + * use an empty string `''`. To reserve the icon's space without displaying an icon, + * use `'empty'`. */ type: '' | IconType | 'empty'; /** - * Determines the color used for the icon based on semantic meaning. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'neutral'` - Gray styling for general information. - * - `'info'` - Blue styling for informational content. - * - `'success'` - Green styling for positive states. - * - `'caution'` - Yellow styling for situations that need attention. - * - `'warning'` - Orange styling for important notices. - * - `'critical'` - Red styling for errors and urgent issues. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `caution`: Advisory notices that need attention. * * @default 'auto' */ @@ -43,61 +81,62 @@ export interface IconProps 'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical' >; /** - * Controls the visual prominence of the icon. Available options: - * - `'base'` - Standard color intensity for normal emphasis. - * - `'subdued'` - Reduced color intensity for less emphasis. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. * * @default 'base' */ color: Extract; /** - * Determines the size of the icon. Available options: - * - `'small'` - Smaller icon size for compact layouts. - * - `'base'` - Standard icon size for most use cases. + * The size of the icon. * - * @default 'base' + * - `small`: Smaller icon suitable for inline use within text or compact UI elements. + * - `base`: Default size that works well for standalone icons and standard use cases. */ size: Extract; } /** - * The properties for the badge component. Badges display status information through compact visual indicators with customizable tones, sizes, and optional icons. - * @publicDocs + * Configure the following properties on the badge component. */ export interface BadgeProps extends Pick { /** - * Controls the visual weight and emphasis of the badge. Available options: - * - `'base'` - Standard weight with moderate emphasis, suitable for most use cases. - * - `'strong'` - Increased visual weight for higher emphasis and prominence. + * Controls the visual weight and emphasis of the badge. + * + * - `base`: Standard weight with moderate emphasis, suitable for most use cases. + * - `strong`: Increased visual weight for higher emphasis and prominence. * * @default 'base' */ color: Extract; /** - * The icon to display inside the badge. Accepts any valid icon type or an empty string to display no icon. + * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. + * Accepts any icon name from the icon library or a custom string identifier. * * @default '' */ icon: IconProps['type'] | ''; /** - * Determines the size of the badge. Available options: - * - `'base'` - Standard size for most use cases. - * - `'large'` - Larger size for increased visibility and prominence. - * - `'large-100'` - Extra large size for maximum visibility in specific contexts. + * The size of the badge. * - * @default 'base' + * - `base`: Default size suitable for most badge use cases. + * - `large`: Larger badge for increased visibility and prominence. + * - `large-100`: Extra large badge for maximum visibility in emphasized contexts. */ size: Extract; /** - * Determines the visual appearance and semantic meaning of the badge. Badges rely on the tone system for semantic meaning, so using custom styling might not clearly convey meaning to merchants. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'neutral'` - Gray styling for general status information that doesn't require emphasis. - * - `'info'` - Blue styling for informational content and neutral updates. - * - `'success'` - Green styling for positive states, completed actions, and successful operations. - * - `'caution'` - Yellow styling for situations that need attention but aren't urgent. - * - `'warning'` - Orange styling for important notices that require merchant awareness. - * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `caution`: Advisory notices that need attention. * * @default 'auto' */ @@ -107,149 +146,65 @@ export interface BadgeProps >; } -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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; +} + +declare abstract class BadgeBase + extends PolarisCustomElement + implements Pick +{ + accessor color: BadgeProps['color']; + accessor size: BadgeProps['size']; + abstract tone: string; + abstract icon: string; + constructor(renderImpl: Omit); } /** - * The base properties for Preact elements without children. Provides key, ref, and slot properties for element identification, DOM access, and slot-based positioning. + * 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 { /** - * A unique identifier for the element when used in lists. Preact uses keys for efficient rendering and reconciliation when lists change. + * 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 with `useRef()` to access the element directly for imperative operations like focusing or measuring. + * 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; /** - * The named slot this element should be placed in when used within a web component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * 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; } /** - * The base properties for Preact elements with children. Extends `PreactBaseElementProps` with the ability to render child elements. + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { /** - * The child elements to render within this component. + * The child elements to be rendered within this component. */ children?: preact.ComponentChildren; } /** - * The badge custom element class that renders status indicators in the Shopify admin interface. This component displays compact visual indicators with customizable tones, sizes, and optional icons to communicate status information to merchants. + * Configure the following properties on the badge component. + * @publicDocs */ -declare class Badge extends PreactCustomElement implements BadgeProps { - /** - * The visual weight of the badge. Available options: `'base'` for standard weight or `'strong'` for increased emphasis. - */ - accessor color: BadgeProps['color']; - /** - * The icon to display inside the badge. Accepts any valid icon type from the admin icon set, or an empty string to display no icon. - */ +declare class Badge extends BadgeBase implements BadgeProps { accessor icon: BadgeProps['icon']; - /** - * The size of the badge. Available options: `'base'` for standard size, `'large'` for larger size, or `'large-100'` for extra large size. - */ - accessor size: BadgeProps['size']; - /** - * The tone that determines the badge's visual appearance and semantic meaning. Available options: `'auto'`, `'neutral'`, `'info'`, `'success'`, `'caution'`, `'warning'`, or `'critical'`. - */ accessor tone: BadgeProps['tone']; constructor(); } @@ -267,15 +222,11 @@ declare module 'preact' { } declare const tagName = 's-badge'; -/** - * The JSX props for the badge component. These properties extend `BadgeProps` with an optional `id` and `children` for rendering badge content in JSX. - * @publicDocs - */ export interface BadgeJSXProps extends Partial, Pick { /** - * The text content to display inside the badge. Typically a short status label like "Fulfilled", "Draft", or "Active". + * The text label displayed within the badge component, typically a short status indicator or category label. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Banner.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Banner.d.ts index bc53b6c290..75b99874b6 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Banner.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Banner.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,33 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, BannerProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + BannerProps$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 = 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 = @@ -28,43 +41,77 @@ export type CallbackEventListener = }) | 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { /** - * The child elements to render inside this element. + * The child elements to be rendered within this component. */ children?: preact.ComponentChildren; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * All properties for the banner component marked as required. + * Represents the banner component props with all properties marked as required. * @publicDocs */ export type RequiredBannerProps = Required; /** - * The properties for the banner component. These properties define an important message or notification with visual styling that conveys its semantic meaning. - * @publicDocs + * Configure the following properties on the banner component. */ export interface BannerProps extends Pick< @@ -72,7 +119,13 @@ export interface BannerProps 'heading' | 'dismissible' | 'hidden' | 'tone' > { /** - * The color tone of the banner based on its semantic meaning. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. * * @default 'auto' */ @@ -80,129 +133,52 @@ export interface BannerProps RequiredBannerProps['tone'], 'auto' | 'critical' | 'warning' | 'success' | 'info' >; -} - -/** - * A string containing CSS styles for the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with Preact. - * @publicDocs - */ -export type RenderImpl = Omit & { /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An event-like object that contains activation information for synthetic clicks. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during activation. - */ - shiftKey: boolean; - /** - * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during activation. + * The heading text displayed at the top of the banner. + * + * @default '' */ - metaKey: boolean; + heading: RequiredBannerProps['heading']; /** - * Whether the control key was pressed during activation. + * Whether the banner displays a close button that allows users to dismiss it. + * + * When the close button is pressed, the `dismiss` event fires, then `hidden` is set to `true`, + * any animation completes, and the `afterhide` event fires. + * + * @default false */ - ctrlKey: boolean; + dismissible: RequiredBannerProps['dismissible']; /** - * The mouse button that was pressed during activation. - */ - button: number; -} -/** - * Options for customizing synthetic click behavior. - * @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. + * Controls whether the banner is visible or hidden. + * + * When using a controlled component pattern and the banner is `dismissible`, + * update this property to `true` when the `dismiss` event fires. + * + * You can hide the banner programmatically by setting this to `true` even if it's not `dismissible`. + * + * @default false */ - sourceEvent?: ActivationEventEsque; + hidden: RequiredBannerProps['hidden']; } -/** - * 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); /** @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; } /** - * A custom element for displaying important messages and notifications. + * Configure the following properties on the banner component. + * @publicDocs */ -declare class Banner extends PreactCustomElement implements BannerProps { - /** - * The heading text displayed at the top of the banner. - */ +declare class Banner extends PolarisCustomElement implements BannerProps { accessor heading: BannerProps['heading']; - /** - * The color tone of the banner based on its semantic meaning. - */ accessor tone: BannerProps['tone']; - /** - * Whether the banner is hidden from view. - */ accessor hidden: BannerProps['hidden']; - /** - * Whether the banner can be dismissed by the user. - */ accessor dismissible: BannerProps['dismissible']; - /** - * A callback that's fired when the banner is dismissed. - */ accessor ondismiss: CallbackEventListener | null; - /** - * A callback that's fired after the banner finishes hiding. - */ accessor onafterhide: CallbackEventListener | null; constructor(); } @@ -221,27 +197,26 @@ declare module 'preact' { } declare const tagName = 's-banner'; -/** - * The JSX properties for the banner component. These properties define how a banner is rendered in Preact or JSX. - * @publicDocs - */ export interface BannerJSXProps extends Partial, Pick { /** - * The content of the banner. + * The main message content displayed within the banner component, providing important information or guidance to users. */ children?: ComponentChildren; /** - * The secondary actions to display at the bottom of the banner. Only buttons with the `variant` of `'secondary'` or `'auto'` are allowed. A maximum of two `s-button` components can be provided. + * Action buttons displayed at the bottom of the banner that let users respond to the message. + * Accepts up to two button components with `variant="secondary"` or `variant="auto"`. */ secondaryActions?: ComponentChildren; /** - * A callback that's fired when the banner is dismissed. + * A callback fired when the user dismisses the banner by clicking the close button. + * Use this to update your app state and control the banner's visibility. */ onDismiss?: ((event: CallbackEvent) => void) | null; /** - * A callback that's fired after the banner finishes hiding. + * A callback fired when the banner is completely hidden, after any hide animations have completed. + * Use this to perform cleanup or trigger subsequent actions after the banner is no longer visible. */ onAfterHide?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Box.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Box.d.ts index af7e829eb5..fe3aec7fe6 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Box.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Box.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -12,10 +12,45 @@ import type { SizeUnitsOrAuto, SizeUnits, SizeUnitsOrNone, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * A type that allows a value to be responsive using container query syntax. + * 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 | `@container${string}`; @@ -41,12 +76,21 @@ export type MakeResponsivePick = { }; /** - * A version of the box properties with all fields required. + * Represents the box component props with all properties marked as required. * @publicDocs */ export type RequiredBoxProps = Required; /** - * The allowed border radius values for a box component. + * 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< @@ -61,7 +105,12 @@ export type BoxBorderRadii = Extract< | 'large-200' >; /** - * The allowed border style values for a box component. + * 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< @@ -69,7 +118,9 @@ export type BoxBorderStyles = Extract< 'none' | 'solid' | 'dashed' | 'auto' >; /** - * The box properties that support responsive values through container queries. + * Represents box props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveBoxProps = MakeResponsivePick< @@ -83,10 +134,6 @@ export type ResponsiveBoxProps = MakeResponsivePick< | 'paddingInlineEnd' | 'display' >; -/** - * The properties for the box component. A box provides control over layout, spacing, sizing, borders, and background styling for its content. - * @publicDocs - */ export interface BoxProps extends Pick< RequiredBoxProps, @@ -108,7 +155,7 @@ export interface BoxProps | 'overflow' > { /** - * The background color of the box. You can choose from `'transparent'`, `'base'`, `'subdued'`, or `'strong'` to control the visual emphasis of the background. + * The background color of the component. * * @default 'transparent' */ @@ -117,16 +164,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 */ @@ -139,11 +183,7 @@ export interface BoxProps > | Extract; /** - * 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: one value applies to all sides, - * two values apply to block and inline sides, and so on. + * 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 */ @@ -151,10 +191,7 @@ export interface BoxProps | MaybeAllValuesShorthandProperty | Extract; /** - * 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 */ @@ -163,64 +200,94 @@ 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 corners or fully rounded elements. - * One value applies to all corners, two values apply to opposite corners, and so on. + * The roundedness of the element's corners using the design system's radius scale. * * @default 'none' */ borderRadius: MaybeAllValuesShorthandProperty; /** - * The padding on all sides of the box. The [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is supported, using flow-relative values in the order `block-start inline-end block-end inline-start`. For example, `'large'` applies large padding to all sides, while `'large none'` applies large padding to the block axis and no padding to the inline axis. A value of `'auto'` will use the default padding from the closest container that has had its padding removed. This property also accepts responsive values using container query syntax. + * The padding applied to all edges of the component. + * + * 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) + * + * **Examples:** `base`, `large none`, `base large-100 base small` + * + * 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 on the block axis (top and bottom in horizontal writing modes). This property overrides the block-axis value set by the `padding` property. For example, `'large none'` applies large padding to the block-start and no padding to the block-end. This property also accepts responsive values using container query syntax. + * The block-direction padding (top and bottom in horizontal writing modes). + * + * Accepts a single value for both sides or two space-separated values for block-start and block-end. + * + * **Example:** `large none` applies `large` to the top and `none` to the bottom. + * + * 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 at the start of the block axis (top in horizontal writing modes). This property overrides the block-start value set by the `paddingBlock` property. It also accepts responsive values using container query syntax. + * The block-start padding (top in horizontal writing modes). + * + * 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 at the end of the block axis (bottom in horizontal writing modes). This property overrides the block-end value set by the `paddingBlock` property. It also accepts responsive values using container query syntax. + * The block-end padding (bottom in horizontal writing modes). + * + * 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 on the inline axis (left and right in horizontal writing modes). This property overrides the inline-axis value set by the `padding` property. For example, `'large none'` applies large padding to the inline-start and no padding to the inline-end. This property also accepts responsive values using container query syntax. + * The inline-direction padding (left and right in horizontal writing modes). + * + * Accepts a single value for both sides or two space-separated values for inline-start and inline-end. + * + * **Example:** `large none` applies `large` to the left and `none` to the right. + * + * 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 at the start of the inline axis (left in left-to-right writing modes). This property overrides the inline-start value set by the `paddingInline` property. It also accepts responsive values using container query syntax. + * The inline-start padding (left in LTR writing modes, right in RTL). + * + * 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 at the end of the inline axis (right in left-to-right writing modes). This property overrides the inline-end value set by the `paddingInline` property. It also accepts responsive values using container query syntax. + * The inline-end padding (right in LTR writing modes, left in RTL). + * + * 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']; /** - * The outer [display](https://developer.mozilla.org/en-US/docs/Web/CSS/display) type of the component, which controls how it participates in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout). Use `'auto'` for the component's default behavior, or `'none'` to hide the component completely and remove it from the accessibility tree. + * 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']; /** - * The vertical size of the box 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. @@ -231,275 +298,123 @@ export interface BoxProps */ blockSize: SizeUnitsOrAuto; /** - * The [minimum block size](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) of the box (minimum height in horizontal writing modes). + * 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) of the box (maximum height in horizontal writing modes). + * 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) of the box (width in horizontal writing modes). + * 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) of the box (minimum width in horizontal writing modes). + * 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) of the box (maximum width in horizontal writing modes). + * 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; } -/** - * 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 & { - /** - * 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); /** @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 base element class for Box components with all Box properties as accessors. - */ -declare class BoxElement extends PreactCustomElement implements BoxProps { +declare class BoxElement extends PolarisCustomElement implements BoxProps { constructor(renderImpl: RenderImpl); - /** - * The ARIA role that defines the semantic meaning of the box for assistive technologies. - */ accessor accessibilityRole: BoxProps['accessibilityRole']; - /** - * The background color of the box using the design system's color scale. Choose from `transparent`, `subdued`, `base`, or `strong`. - */ accessor background: BoxProps['background']; - /** - * The height of the box in horizontal writing modes, or width in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor blockSize: BoxProps['blockSize']; - /** - * The minimum height of the box in horizontal writing modes, or minimum width in vertical writing modes. - * Prevents the box from shrinking below this size. - */ accessor minBlockSize: BoxProps['minBlockSize']; - /** - * The maximum height of the box in horizontal writing modes, or maximum width in vertical writing modes. - * Prevents the box from growing beyond this size. - */ accessor maxBlockSize: BoxProps['maxBlockSize']; - /** - * The width of the box in horizontal writing modes, or height in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor inlineSize: BoxProps['inlineSize']; - /** - * The minimum width of the box in horizontal writing modes, or minimum height in vertical writing modes. - * Prevents the box from shrinking below this size. - */ accessor minInlineSize: BoxProps['minInlineSize']; - /** - * The maximum width of the box in horizontal writing modes, or maximum height in vertical writing modes. - * Prevents the box from growing beyond this size. - */ accessor maxInlineSize: BoxProps['maxInlineSize']; - /** - * Controls how content that exceeds the box's boundaries is displayed. Use `hidden` to clip overflow or `visible` to allow content to extend beyond boundaries. - */ accessor overflow: BoxProps['overflow']; - /** - * The padding on all sides of the box. - */ accessor padding: BoxProps['padding']; - /** - * The vertical padding (top and bottom) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingBlock: BoxProps['paddingBlock']; - /** - * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes. - */ accessor paddingBlockStart: BoxProps['paddingBlockStart']; - /** - * The padding at the bottom in horizontal writing modes, or at the end edge in vertical writing modes. - */ accessor paddingBlockEnd: BoxProps['paddingBlockEnd']; - /** - * The horizontal padding (left and right) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingInline: BoxProps['paddingInline']; - /** - * The padding at the left in left-to-right languages, or at the right in right-to-left languages. - */ accessor paddingInlineStart: BoxProps['paddingInlineStart']; - /** - * The padding at the right in left-to-right languages, or at the left in right-to-left languages. - */ accessor paddingInlineEnd: BoxProps['paddingInlineEnd']; - /** - * Applies a border using shorthand syntax to specify width, color, and style in a single property. - */ accessor border: BoxProps['border']; - /** - * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property. - */ accessor borderWidth: BoxProps['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. - */ accessor borderStyle: BoxProps['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. - */ accessor borderColor: BoxProps['borderColor']; - /** - * Controls the roundedness of the element's corners using the design system's radius scale. - */ accessor borderRadius: BoxProps['borderRadius']; - /** - * The accessibility label for screen readers. - */ accessor accessibilityLabel: BoxProps['accessibilityLabel']; - /** - * Controls the visibility of the box for both visual and assistive technology users. Use `hidden` to hide from screen readers or `exclusive` to hide visually but announce to screen readers. - */ accessor accessibilityVisibility: BoxProps['accessibilityVisibility']; - /** - * Controls how the box is displayed in the layout, such as block, inline, or none. - */ accessor display: BoxProps['display']; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { - /** The child elements to render inside this element. */ + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A box is a container component that provides control over layout, spacing, and styling. + * Configure the following properties on the box component. + * @publicDocs */ declare class Box extends BoxElement implements BoxProps { constructor(); @@ -518,15 +433,11 @@ declare module 'preact' { } declare const tagName = 's-box'; -/** - * The properties for the box component when it's used in JSX. - * @publicDocs - */ export interface BoxJSXProps extends Partial, Pick { /** - * The child elements to render inside the box. + * The content displayed within the box component, which serves as a flexible container for organizing and styling other components. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Button.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Button.d.ts index 605f4a20eb..70dbea29c0 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Button.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Button.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -12,20 +12,30 @@ import type { ButtonProps$1, IconType, InteractionProps, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements. + * 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 = Event & { - /** - * The element that the event listener is attached to, strongly typed based on the element's tag name. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type. + * 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 = @@ -34,57 +44,95 @@ export type CallbackEventListener = }) | null; /** - * The base properties for Preact elements without children. Provides `key`, `ref`, and `slot` properties for element identification, DOM access, and slot-based positioning. + * 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 { /** - * A unique identifier for the element when used in lists. Preact uses keys for efficient rendering and reconciliation when lists change. + * 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 with `useRef()` to access the element directly for imperative operations like focusing or measuring. + * 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; /** - * The named slot this element should be placed in when used within a web component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * 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; } /** - * The base properties for Preact elements with children. Extends `PreactBaseElementProps` with the ability to render child elements. + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { /** - * The child elements to render within this component. + * The child elements to be rendered within this component. */ children?: preact.ComponentChildren; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 configuration for icons used within Button components. Defines the visual appearance, size, and semantic meaning of icons displayed in buttons. - * @publicDocs + * Configure the following properties on the icon component. */ export interface IconProps - extends Pick< - IconProps$1, - 'type' | 'tone' | 'color' | 'size' | 'interestFor' + extends Required< + Pick > { /** - * Specifies the type of icon that will be displayed. + * The icon to display from the icon library. + * + * Set to a valid icon name to display that icon. To hide the icon completely, + * use an empty string `''`. To reserve the icon's space without displaying an icon, + * use `'empty'`. */ type: '' | IconType | 'empty'; /** - * Determines the color used for the icon based on semantic meaning. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'neutral'` - Gray styling for general information. - * - `'info'` - Blue styling for informational content. - * - `'success'` - Green styling for positive states. - * - `'caution'` - Yellow styling for situations that need attention. - * - `'warning'` - Orange styling for important notices. - * - `'critical'` - Red styling for errors and urgent issues. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `caution`: Advisory notices that need attention. * * @default 'auto' */ @@ -93,25 +141,25 @@ export interface IconProps 'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical' >; /** - * Controls the visual prominence of the icon. Available options: - * - `'base'` - Standard color intensity for normal emphasis. - * - `'subdued'` - Reduced color intensity for less emphasis. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. * * @default 'base' */ color: Extract; /** - * Determines the size of the icon. Available options: - * - `'small'` - Smaller icon size for compact layouts. - * - `'base'` - Standard icon size for most use cases. + * The size of the icon. * - * @default 'base' + * - `small`: Smaller icon suitable for inline use within text or compact UI elements. + * - `base`: Default size that works well for standalone icons and standard use cases. */ size: Extract; } /** - * The button-specific properties extracted from the base button props type, used internally for type safety. + * Represents button props that are specific to button-type elements only. Extracts the subset of `ButtonProps` that includes the `type` property. * @publicDocs */ export type ButtonOnlyProps = Extract< @@ -121,7 +169,7 @@ export type ButtonOnlyProps = Extract< } >; /** - * The base required properties for the button component, including all essential button configuration options. This type ensures all button properties have default values. + * Represents the base button props with all properties marked as required. * @publicDocs */ export type ButtonBaseProps = Required< @@ -141,138 +189,69 @@ export type ButtonBaseProps = Required< | 'target' | 'href' | 'download' + | 'inlineSize' > >; /** - * The properties for the button component. Buttons trigger actions or navigation when clicked, with customizable visual styles, states, and optional icons. - * @publicDocs + * Configure the following properties on the button component. */ export interface ButtonProps extends ButtonBaseProps { /** - * Determines the visual appearance and semantic meaning of the button. Buttons rely on the tone system for semantic meaning, so using custom styling might not clearly convey intent to merchants. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'neutral'` - Standard styling for general actions without specific semantic meaning. - * - `'critical'` - Red styling for destructive actions that can't be undone, such as deleting data. + * The semantic meaning and color treatment of the component. + * + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. * * @default 'auto' */ tone: Extract; /** - * The icon to display inside the button. Accepts any valid icon type or an empty string to display no icon. + * An icon displayed inside the button, typically positioned before the button text. + * Use icons to help users quickly identify the button's action or to improve scannability. + * Accepts any icon name from the icon library or a custom string identifier. * * @default '' */ icon: IconProps['type']; -} - -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. + * 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. */ - ctrlKey: boolean; + accessibilityLabel: Required['accessibilityLabel']; /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). + * The visual appearance of the button component. + * + * - `auto`: The variant is automatically determined by the button component's context. + * - `primary`: High emphasis button for the primary action on the page. Should be used sparingly. + * - `secondary`: Medium emphasis button for secondary actions. + * - `tertiary`: Low emphasis button for less important actions. + * + * @default 'auto' */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { + variant: Required['variant']; /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. + * 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). */ - sourceEvent?: ActivationEventEsque; + lang: Required['lang']; } -/** - * 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); /** @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 interactions via commands. These properties enable buttons to control other components like modals, popovers, and dialogs using declarative commands. - * @publicDocs - */ export interface PreactOverlayControlProps extends Pick { /** - * Sets the action the [command](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this button is activated. Available options: - * - `'--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. + * The action that [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. + * - `--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' */ @@ -281,78 +260,59 @@ export interface PreactOverlayControlProps '--show' | '--hide' | '--toggle' | '--auto' >; /** - * Sets the element ID that the [commandFor](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor) should act on when this button is activated. References another component by its `id` attribute. + * 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; /** - * Sets the element ID that the [interestFor](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code) should act on when this button is activated. Used for interest-based interactions with other components. + * 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; } -/** - * The base class for the button component, combining Preact custom element functionality with overlay control capabilities. - */ -declare const Button_base: (abstract new ( - args_0: RenderImpl, -) => PreactCustomElement & PreactOverlayControlProps) & - Pick; -/** - * The button custom element class that renders interactive buttons in the Shopify admin interface. This component triggers actions or navigation when clicked, with customizable visual styles, states, and optional icons. - */ -declare class Button extends Button_base implements ButtonProps { - /** - * Whether the button is disabled, preventing any interaction. When `true`, the button appears visually disabled and doesn't respond to user clicks. - */ +declare const ButtonBase_base: (abstract new ( + renderImpl: Omit, +) => PolarisCustomElement & PreactOverlayControlProps) & + Pick; +declare abstract class ButtonBase + extends ButtonBase_base + implements + Pick< + ButtonProps, + | 'disabled' + | 'loading' + | 'target' + | 'href' + | 'download' + | 'type' + | 'accessibilityLabel' + | 'inlineSize' + > +{ accessor disabled: ButtonProps['disabled']; - /** - * The icon to display inside the button. Accepts any valid icon type from the admin icon set, or an empty string to display no icon. - */ - accessor icon: ButtonProps['icon']; - /** - * Whether the button is in a loading state. When `true`, displays a loading indicator and prevents interaction to show that an action is in progress. - */ accessor loading: ButtonProps['loading']; - /** - * The visual style variant of the button that determines its emphasis. Available options: `'primary'`, `'secondary'`, `'tertiary'`, or `'plain'`. - */ - accessor variant: ButtonProps['variant']; - /** - * The tone that determines the button's visual appearance and semantic meaning. Available options: `'auto'`, `'neutral'`, or `'critical'`. - */ - accessor tone: ButtonProps['tone']; - /** - * Specifies where to open the linked document when the button acts as a link. Available options: `''`, `'_blank'`, `'_self'`, `'_parent'`, or `'_top'`. - */ accessor target: ButtonProps['target']; - /** - * A URL that the button should navigate to when clicked. When provided, the button behaves as a link. - */ accessor href: ButtonProps['href']; - /** - * Prompts the user to save the linked URL as a file with the specified filename. Only works when `href` is provided. - */ accessor download: ButtonProps['download']; - /** - * A callback that's invoked when the button is clicked. Receives the click event as an argument. - */ - accessor onclick: CallbackEventListener | null; - /** - * A callback that's invoked when the button loses focus. Receives the blur event as an argument. - */ - accessor onblur: CallbackEventListener | null; - /** - * A callback that's invoked when the button receives focus. Receives the focus event as an argument. - */ - accessor onfocus: CallbackEventListener | null; - /** - * The button's behavior in forms. Available options: `'button'`, `'submit'`, or `'reset'`. - */ accessor type: ButtonProps['type']; - /** - * A text description of the button's purpose for screen readers. This is essential for accessibility when the button doesn't have visible text. - */ accessor accessibilityLabel: ButtonProps['accessibilityLabel']; + accessor inlineSize: ButtonProps['inlineSize']; + accessor onclick: CallbackEventListener | null; + accessor onblur: CallbackEventListener | null; + accessor onfocus: CallbackEventListener | null; + abstract icon: string; + abstract variant: string; + abstract tone: string; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the button component. + * @publicDocs + */ +declare class Button extends ButtonBase implements ButtonProps { + accessor icon: ButtonProps['icon']; + accessor variant: ButtonProps['variant']; + accessor tone: ButtonProps['tone']; constructor(); } declare global { @@ -369,95 +329,25 @@ declare module 'preact' { } declare const tagName = 's-button'; -/** - * The JSX props for the button component. These properties extend `ButtonProps` with event callbacks and additional options for rendering buttons in JSX. - * @publicDocs - */ export interface ButtonJSXProps extends Partial, Pick { /** - * The text label or content to display inside the button. Can be plain text or other components. + * The label text or elements displayed inside the button component, describing the action that will be performed when clicked. */ children?: ComponentChildren; /** - * Callback function that's invoked when the button is clicked. Receives the click event as an argument. + * A callback fired when the button is clicked. */ onClick?: ((event: CallbackEvent) => void) | null; /** - * Callback function that's invoked when the button receives focus. Receives the focus event as an argument. + * A callback fired when the button receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * Callback function that's invoked when the button loses focus. Receives the blur event as an argument. + * A callback fired when the button loses focus. */ onBlur?: ((event: CallbackEvent) => 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; - /** - * Prevents the button from being clicked when set to `true`. The button appears visually disabled and doesn't respond to user interaction. - * - * @default false - */ - disabled?: boolean; - /** - * Displays a loading indicator and prevents interaction when set to `true`. Use this to show that an action triggered by the button is in progress. - * - * @default false - */ - loading?: boolean; - /** - * Determines the visual style and emphasis of the button. Available options: - * - `'primary'` - Highest emphasis for the main action on a screen. - * - `'secondary'` - Medium emphasis for secondary actions. - * - `'tertiary'` - Lowest emphasis for less important actions. - * - `'plain'` - Text-only appearance for subtle actions that don't need visual weight. - * - * @default 'secondary' - */ - variant?: ButtonProps['variant']; - /** - * Specifies where to open the linked document when the button 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?: ButtonProps['target']; - /** - * A URL that the button should navigate to when clicked. When provided, the button behaves as a link. - * - * @default '' - */ - href?: ButtonProps['href']; - /** - * Prompts the user to save the linked URL as a file with the specified filename. Only works when `href` is provided. - * - * @default '' - */ - download?: ButtonProps['download']; - /** - * Specifies the button's behavior in forms. Available options: - * - `'button'` - A standard button with no default behavior. - * - `'submit'` - Submits the form data to the server. - * - `'reset'` - Resets all form controls to their initial values. - * - * @default 'button' - */ - type?: ButtonProps['type']; - /** - * The language of the button's content, specified as a BCP 47 language tag (such as `'en'` or `'fr'`). This helps assistive technologies pronounce content correctly. - * - * @default '' - */ - lang?: ButtonProps['lang']; } export {Button}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/ButtonGroup.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ButtonGroup.d.ts index 812d0bad41..a462a3122f 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ButtonGroup.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ButtonGroup.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,157 +6,132 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, ButtonGroupProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + ButtonGroupProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * Properties for rendering a button group that arranges multiple buttons together with consistent spacing and semantic grouping. - * @publicDocs - */ -export interface ButtonGroupProps - extends Required> {} - -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs + * Configure the following properties on the button group component. */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; - /** - * Whether the Control key was held down during the interaction. - */ - ctrlKey: boolean; +export interface ButtonGroupProps + extends Required> { /** - * The mouse button that was pressed during the interaction. + * 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. + * + * @implementation Used as a hidden heading or an aria-label on the wrapping element. */ - button: number; -} -/** - * Options for influencing how a programmatic click behaves. - * @publicDocs - */ -export interface ClickOptions { + accessibilityLabel: Required['accessibilityLabel']; /** - * 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. + * The spacing between buttons in the group. + * + * - `base`: Standard spacing that provides clear visual separation between buttons. + * - `none`: No spacing, creating a connected button group. + * + * @default 'base' */ - sourceEvent?: ActivationEventEsque; + gap: Required['gap']; } -/** - * 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); /** @private */ connectedCallback(): void; /** @private */ - disconnectedCallback(): void; - /** @private */ adoptedCallback(): void; +} + +declare abstract class ButtonGroupBase + extends PolarisCustomElement + implements Pick +{ + accessor gap: ButtonGroupProps['gap']; + accessor accessibilityLabel: ButtonGroupProps['accessibilityLabel']; + constructor(renderImpl: RenderImpl); /** - * 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. + * Actions whose translucent fill can't paint over a seam, so the neighbour + * has to be told not to draw it. The foundation resolves the list. * @private - * @param options */ - click({sourceEvent}?: ClickOptions): void; + setInertActions(actions: ReadonlyArray): void; + /** @private */ + disconnectedCallback(): void; } /** - * 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 { /** - * 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; /** - * 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; } - /** - * 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 extends PreactBaseElementProps { /** - * The child elements or content that will be rendered inside this element. + * The child elements to be rendered within this component. */ children?: preact.ComponentChildren; } /** - * A button group that arranges multiple buttons together with consistent spacing and semantic grouping for related actions. + * Configure the following properties on the button group component. + * @publicDocs */ -declare class ButtonGroup - extends PreactCustomElement - implements ButtonGroupProps -{ - /** - * The amount of spacing between buttons in the group, affecting the visual separation of actions. - */ - accessor gap: ButtonGroupProps['gap']; - - /** - * A label that's only visible to screen readers, describing the purpose of this group of buttons. - */ - accessor accessibilityLabel: ButtonGroupProps['accessibilityLabel']; - +declare class ButtonGroup extends ButtonGroupBase implements ButtonGroupProps { constructor(); } declare global { @@ -177,28 +152,25 @@ declare module 'preact' { } declare const tagName = 's-button-group'; - -/** - * Properties for using the button group component in JSX with React-style props. - * @publicDocs - */ export interface ButtonGroupJSXProps extends Partial, Pick { /** - * The buttons that should be grouped together, provided as Button components. + * The buttons displayed within the button group component, which are arranged together as a cohesive set of related actions. */ children?: ComponentChildren; /** - * A single primary action button that's visually emphasized as the most important action in the group. + * The main action for this group, displayed with high visual emphasis. + * Accepts a single button with `variant="primary"`. * - * Accepts a single Button element with a `variant` of `primary`. Can't be used when `gap` is set to `none`. + * Use this for the primary action you want users to take. This can't be used when `gap="none"`. */ primaryAction?: ComponentChildren; /** - * One or more secondary action buttons that provide alternative or less prominent actions. + * Supporting actions displayed with less emphasis than the primary action. + * Accepts one or more button components with `variant="secondary"` or `variant="auto"`. * - * Accepts Button elements with a `variant` of `secondary` or `auto`. + * Use these for alternative or less critical actions. */ secondaryActions?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Checkbox.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Checkbox.d.ts index 9ffb8f8199..92dea30555 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Checkbox.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Checkbox.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,21 +9,30 @@ import type { TextFieldProps, CheckboxProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event that includes a strongly-typed reference to the element that triggered it. + * 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 = Event & { - /** - * The element that the event handler was attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A function that handles events for a specific element type, or null if no handler is set. + * 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 = @@ -31,170 +40,113 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs - */ -export interface PreactBaseElementProps { - /** - * 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. - */ - 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. - */ - ref?: preact.Ref; - /** - * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns. - */ - slot?: Lowercase; -} - /** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. */ -export type Styles = string; +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} /** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} /** - * Information about modifier keys and mouse buttons that were active during an interaction. + * 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 ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; +export interface PreactBaseElementProps { /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. + * 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. */ - metaKey: boolean; + key?: preact.Key; /** - * Whether the Control key was held down during the interaction. + * A reference to access the underlying DOM element directly. + * Typically created using `useRef()` to interact with the element imperatively or measure its properties. */ - ctrlKey: boolean; + ref?: preact.Ref; /** - * The mouse button that was pressed during the interaction. + * The named slot to which this element is assigned in the parent component's shadow DOM. + * + * Used for advanced component composition with web components. */ - button: number; + slot?: Lowercase; } -/** - * Options for influencing how a programmatic click behaves. - * @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; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The core properties that all input elements need to function within forms. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * Base class for input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** - * Indicates that this element can participate in form submission. - */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's triggered when the input's value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's triggered when the input's value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * A unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name that identifies this input when the form is submitted. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } -/** - * Properties that are common to checkbox-style components. - * @publicDocs - */ export interface PreactCheckboxProps extends Required< Pick< @@ -211,20 +163,15 @@ export interface PreactCheckboxProps > > { /** - * The value that's submitted with the form when the checkbox is checked. + * The value used in form data when the checkbox is checked. */ value: Required['value']; } -/** - * Base class for checkbox-style elements that can be toggled on and off. - */ declare class PreactCheckboxElement extends PreactInputElement implements PreactCheckboxProps { - /** - * Whether the checkbox is currently checked. - */ + accessor onblur: CallbackEventListener<'input'>; get checked(): boolean; set checked(checked: PreactCheckboxProps['checked']); /** @@ -232,29 +179,11 @@ declare class PreactCheckboxElement */ get value(): string; set value(value: string); - /** - * Whether the checkbox should be checked when it's first rendered. - */ accessor defaultChecked: PreactCheckboxProps['defaultChecked']; - /** - * A label that's only visible to screen readers, used when the visual label isn't descriptive enough. - */ accessor accessibilityLabel: PreactCheckboxProps['accessibilityLabel']; - /** - * Additional text to provide context or guidance for the checkbox. - */ accessor details: PreactCheckboxProps['details']; - /** - * An error message that's displayed below the checkbox when validation fails. - */ accessor error: PreactCheckboxProps['error']; - /** - * The text that describes what the checkbox is for. - */ accessor label: PreactCheckboxProps['label']; - /** - * Whether the checkbox must be checked before the form can be submitted. - */ accessor required: PreactCheckboxProps['required']; /** @private */ formResetCallback(): void; @@ -263,33 +192,69 @@ declare class PreactCheckboxElement } /** - * Properties for rendering a checkbox that supports checked, unchecked, and indeterminate states for complex selection scenarios. - * @publicDocs + * Configure the following properties on the checkbox component. */ export interface CheckboxProps extends PreactCheckboxProps { /** - * Whether the checkbox is in an indeterminate state, showing a dash instead of a checkmark to represent a partial selection. + * Whether the checkbox displays in an indeterminate state (neither checked nor unchecked), + * typically used to indicate partial selection in hierarchical lists. + * + * This visual state takes priority over the `checked` prop in appearance only. + * The form submission value is still determined by the `checked` prop. + * + * If `indeterminate` has not been explicitly set and hasn't been modified by user interaction, + * it returns the value of `defaultIndeterminate`. */ indeterminate: Required['indeterminate']; /** - * Whether the checkbox should be in an indeterminate state when it's first rendered, useful for partial selection scenarios. + * The initial indeterminate state for uncontrolled components. Use this when you want the checkbox to start + * in an indeterminate state but don't need to control it afterward. + * + * This value applies until `indeterminate` is explicitly set or the user changes the checkbox state by clicking. + * + * @default false */ defaultIndeterminate: Required['defaultIndeterminate']; -} - -/** - * A checkbox that lets users select or deselect an option, with support for an indeterminate state. - */ -declare class Checkbox extends PreactCheckboxElement implements CheckboxProps { /** - * Whether the checkbox is in an indeterminate state, showing a dash instead of a checkmark. + * Whether the field needs a value. This requirement adds semantic value + * to the field, but it will not cause an error to appear automatically. + * If you want to present an error when this field is empty, you can do + * so with the `error` property. + * + * @default false */ - get indeterminate(): CheckboxProps['indeterminate']; - set indeterminate(indeterminate: CheckboxProps['indeterminate']); + required: Required['required']; /** - * Whether the checkbox should be in an indeterminate state when it's first rendered. + * Changes the visibility of the component's label. + * + * - `visible`: the label is visible to all users. + * - `exclusive`: the label is visually hidden but remains in the accessibility tree. + * + * @default 'visible' */ + labelAccessibilityVisibility: Required['labelAccessibilityVisibility']; +} + +declare abstract class CheckboxBase + extends PreactCheckboxElement + implements + Pick< + CheckboxProps, + 'defaultIndeterminate' | 'indeterminate' | 'labelAccessibilityVisibility' + > +{ + get indeterminate(): CheckboxProps['indeterminate']; + set indeterminate(indeterminate: CheckboxProps['indeterminate']); accessor defaultIndeterminate: CheckboxProps['defaultIndeterminate']; + accessor labelAccessibilityVisibility: CheckboxProps['labelAccessibilityVisibility']; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the checkbox component. + * @publicDocs + */ +declare class Checkbox extends CheckboxBase implements CheckboxProps { constructor(); } declare global { @@ -300,27 +265,27 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: CheckboxJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-checkbox'; -/** - * Props for using the checkbox component in JSX with React-style event handlers. - * @publicDocs - */ export interface CheckboxJSXProps - extends Partial, - Pick { + extends Partial>, + Pick, + FieldSlotInternalReactProps { /** - * A callback that's triggered when the checkbox's checked state changes and it loses focus. + * A callback fired when the checkbox state changes and the user has finished interacting with it. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the checkbox's checked state changes. + * A callback fired when the checkbox state changes, including intermediate states during user interaction. */ onInput?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; } export {Checkbox}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Chip.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Chip.d.ts index 6401010a8a..3c99bca9d5 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Chip.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Chip.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.38.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -12,34 +12,135 @@ import type { PreactCustomElement, RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -export interface ChipProps - extends Required> {} - -declare class PolarisCustomElement extends PreactCustomElement { - constructor(renderImpl: Omit); -} - -/** Used when an element does not have children. * @publicDocs +/** + * 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 = 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 = + | (EventListener & { + (event: CallbackEvent): void; + }) + | null; +/** + * 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 { - /** Assigns a unique key to this element. */ + /** + * 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; - /** Assigns a ref (generally from `useRef()`) to this element. */ + /** + * 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; - /** Assigns this element to a parent's slot. */ + /** + * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * Configure the following properties on the chip component. + */ +export interface ChipProps + extends Required< + Pick + > { + /** + * The color emphasis level that controls visual intensity. + * + * @default 'base' + */ + color: Required['color']; + /** + * 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. + */ + accessibilityLabel: Required['accessibilityLabel']; +} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +/** + * Configure the following properties on the chip component. + * @publicDocs + */ declare class Chip extends PolarisCustomElement implements ChipProps { accessor color: ChipProps['color']; accessor accessibilityLabel: ChipProps['accessibilityLabel']; + accessor removable: ChipProps['removable']; + accessor onremove: CallbackEventListener | null; constructor(); } declare global { @@ -61,13 +162,14 @@ export interface ChipJSXProps extends Partial, Pick { /** - * The content of the chip. + * The text label displayed within the chip component, typically representing a selected filter, tag, or removable item. */ children?: ComponentChildren; /** - * An optional icon to display at the start of the chip. Accepts only Icon components. + * An optional icon to display at the start of the chip. Accepts only icon components. */ graphic?: ComponentChildren; + onRemove?: ((event: CallbackEvent) => void) | null; } export {Chip}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Choice.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Choice.d.ts index 63cbb9998e..f2630acac6 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Choice.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Choice.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,11 +6,50 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, ChoiceProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + ChoiceProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * Properties for rendering a single choice within a choice list that can be selected using a radio button or checkbox. - * @publicDocs + * The choice component creates individual selectable options within a choice list. Use choice to define each option that merchants can select, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes. + * + * Choice components support labels, help text, and custom content through slots, providing flexible option presentation within choice lists. */ export interface ChoiceProps extends Required< @@ -24,146 +63,77 @@ export interface ChoiceProps > > {} -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; -/** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; - /** - * Whether the Control key was held down during the interaction. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the interaction. - */ - button: number; -} -/** - * Options for influencing how a programmatic click behaves. - * @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; -} -/** - * 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); /** @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; } -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A single choice within a choice list that can be selected with a radio button or checkbox. + * The choice component creates individual selectable options within a choice list. Use choice to define each option that merchants can select, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes. + * + * Choice components support labels, help text, and custom content through slots, providing flexible option presentation within choice lists. + * @publicDocs */ -declare class Choice extends PreactCustomElement implements ChoiceProps { +declare class Choice extends PolarisCustomElement implements ChoiceProps { /** - * Whether the choice is disabled and can't be selected. + * Whether the checkbox is disabled, preventing user interaction. Disabled checkboxes appear dimmed and their values aren't submitted with forms. */ accessor disabled: ChoiceProps['disabled']; /** - * Whether the choice is currently selected. + * Whether the option is currently selected. Use this for controlled components where you manage the selection state. */ get selected(): boolean; + /** + * Whether the option is currently selected. Use this for controlled components where you manage the selection state. + */ set selected(selected: ChoiceProps['selected']); /** - * The value that's submitted with the form when this choice is selected. + * The value submitted with the form when this checkbox is checked. If not specified, the default value is "on". */ accessor value: ChoiceProps['value']; /** - * A label that's only visible to screen readers, used when the visual label isn't descriptive enough. + * 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. */ accessor accessibilityLabel: ChoiceProps['accessibilityLabel']; /** - * Whether the choice should be selected when it's first rendered. + * The initial selected state for uncontrolled components. Use this when you want the option to start selected but don't need to control its state afterward. */ accessor defaultSelected: ChoiceProps['defaultSelected']; constructor(); @@ -180,34 +150,39 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: Omit & + [tagName]: Omit & PreactBaseElementPropsWithChildren; } } } declare const tagName = 's-choice'; -/** - * Properties for using the choice component in JSX with React-style props. - * @publicDocs - */ export interface ChoiceJSXProps extends Partial, Pick { /** - * The content that's used as the choice label, extracted as plain text from any provided markup. + * The label that identifies this selectable choice option to users. * - * The label is produced by extracting and concatenating the text nodes from the provided content; any markup or element structure is ignored. + * The label is produced by extracting and + * concatenating the text nodes from the provided content; + * any markup or element structure is ignored. */ children?: ComponentChildren; /** - * Additional text that provides context or guidance for the input, displayed alongside the choice label. + * Additional text to provide context or guidance for the input. * - * This text is displayed along with the input and its label to offer more information or instructions to the user. + * This text is displayed along with the input and its label + * to offer more information or instructions to the user. * * @implementation this content should be linked to the input with an `aria-describedby` attribute. */ details?: ComponentChildren; + /** + * Additional content to display below the choice label. + * Can include rich content like TextFields, Buttons, or other interactive components. + * Event handlers on React components are preserved. + */ + secondaryContent?: ComponentChildren; } export {Choice}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/ChoiceList.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ChoiceList.d.ts index 4d2a9acc76..51bd369908 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ChoiceList.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ChoiceList.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,33 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, ChoiceListProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + ChoiceListProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event that includes a strongly-typed reference to the element that triggered it. + * 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 = Event & { - /** - * The element that the event handler was attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A function that handles events for a specific element type, or null if no handler is set. + * 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 = @@ -27,32 +40,73 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * Properties for rendering a list of choices that lets users select one or more options using radio buttons or checkboxes. - * @publicDocs + * Configure the following properties on the choice list component. */ export interface ChoiceListProps extends Required< @@ -67,159 +121,100 @@ export interface ChoiceListProps | 'name' | 'values' > - > {} - -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; -/** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs - */ -export interface ActivationEventEsque { + > { /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; - /** - * Whether the Control key was held down during the interaction. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the interaction. + * Whether the field is disabled, preventing any user interaction. When `true`, the `disabled` property on any child choices is ignored. + * + * @default false */ - button: number; -} -/** - * Options for influencing how a programmatic click behaves. - * @publicDocs - */ -export interface ClickOptions { + disabled: Required['disabled']; /** - * 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 multiple choices can be selected. + * + * @default false */ - sourceEvent?: ActivationEventEsque; + multiple: Required['multiple']; } -/** - * 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$1: typeof globalThis.HTMLElement; -declare abstract class PreactCustomElement extends BaseClass$1 { - /** @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); /** @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; } declare const internals: unique symbol; -/** - * Base class for form-associated custom elements. - */ -declare class BaseClass extends PreactCustomElement { - /** - * Indicates that this element can participate in form submission. - */ +declare class BaseClass extends PolarisCustomElement { static formAssociated: boolean; constructor(renderImpl: RenderImpl); /** @private */ [internals]: ElementInternals; } /** - * A list of choices that lets users select one or more options using radio buttons or checkboxes. + * Configure the following properties on the choice list component. + * @publicDocs */ declare class ChoiceList extends BaseClass implements ChoiceListProps { /** - * Whether all choices in the list are disabled and can't be selected. + * Wraps change and input event listeners so they only fire when the event + * was dispatched directly on this ChoiceList (event.eventPhase === Event.AT_TARGET). + * + * This prevents form events from elements inside secondary content (e.g. + * TextField, native ) from being mistakenly treated as ChoiceList + * value-change events, while still allowing those events to bubble normally + * through the DOM (preserving React's event delegation). + * @private */ + addEventListener( + type: string, + callback: EventListenerOrEventListenerObject | null, + options?: AddEventListenerOptions | boolean, + ): void; + + /** @private */ + removeEventListener( + type: string, + callback: EventListenerOrEventListenerObject | null, + options?: EventListenerOptions | boolean, + ): void; + accessor disabled: ChoiceListProps['disabled']; /** - * The name that identifies this choice list when the form is submitted. + * The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form. */ accessor name: ChoiceListProps['name']; /** - * An error message that's displayed below the choice list when validation fails. + * An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers. */ accessor error: ChoiceListProps['error']; /** - * Additional text to provide context or guidance for the choice list. + * Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers. */ accessor details: ChoiceListProps['details']; - /** - * Whether users can select more than one choice at a time. - */ accessor multiple: ChoiceListProps['multiple']; /** - * The text that describes what the choice list is for. + * The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide. */ accessor label: ChoiceListProps['label']; - /** - * A callback that's triggered when the selected choices change and the choice list loses focus. - */ accessor onchange: CallbackEventListener | null; - /** - * A callback that's triggered when the selected choices change. - */ accessor oninput: CallbackEventListener | null; /** * Controls whether the label is visible to all users or only to screen readers. + * + * - `visible`: The label is shown to everyone (default). + * - `exclusive`: The label is visually hidden but still announced by screen readers. + * + * Use `exclusive` when the surrounding context makes the label redundant visually, but screen reader users still need it for clarity. */ accessor labelAccessibilityVisibility: ChoiceListProps['labelAccessibilityVisibility']; /** - * The values of the currently selected choices. + * An array of `value` attributes for the currently selected options. When provided, this property automatically sets the `selected` state on child option components that have matching `value` attributes. Options with values included in this array will be marked as selected, while others will be unselected. */ get values(): ChoiceListProps['values']; + /** + * An array of `value` attributes for the currently selected options. When provided, this property automatically sets the `selected` state on child option components that have matching `value` attributes. Options with values included in this array will be marked as selected, while others will be unselected. + */ set values(values: ChoiceListProps['values']); /** @private */ formResetCallback(): void; @@ -244,25 +239,21 @@ declare module 'preact' { } declare const tagName = 's-choice-list'; -/** - * Properties for using the choice list component in JSX with React-style event handlers. - * @publicDocs - */ export interface ChoiceListJSXProps extends Partial, Pick { /** - * The choices that a user can select from, provided as Choice components. + * The choices a user can select from. * - * Accepts Choice components. + * Accepts choice components. */ children?: ComponentChildren; /** - * A callback that's triggered when the selected choices change and the choice list loses focus. + * A callback fired when the user has finished changing the value. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the selected choices change as the user interacts with them. + * A callback fired when the user makes any changes to the value. */ onInput?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Clickable.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Clickable.d.ts index 03852fa1e4..196697e2d6 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Clickable.d.ts +++ b/packages/ui-extensions/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 = 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 = | (EventListener & { (event: CallbackEvent): 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** * @publicDocs + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 | `@container${string}`; /** @@ -75,7 +138,24 @@ export type MakeResponsivePick = { [P in TProperty]: MakeResponsive; }; +/** + * Represents the box component props with all properties marked as required. + * @publicDocs + */ export type RequiredBoxProps = Required; +/** + * 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; /** - * 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 | Extract; /** - * 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; /** - * 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, - ClickableBaseProps {} -/** * @publicDocs + * Configure the following properties on the clickable component. */ -export type Styles = string; -export type RenderImpl = Omit & { - 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, 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['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['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['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); /** @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 { /** - * 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; /** - * 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; } -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; +/** + * 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 | null; accessor onblur: CallbackEventListener | null; accessor onfocus: CallbackEventListener | 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, Pick { /** - * 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) => 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) => 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) => 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}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/ClickableChip.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ClickableChip.d.ts index 3c66e4eeaf..4055137a77 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ClickableChip.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ClickableChip.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,20 +10,30 @@ import type { ComponentChildren, ClickableChipProps$1, InteractionProps, + 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 = 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 = @@ -32,38 +42,72 @@ export type CallbackEventListener = }) | 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { /** - * The child elements to render inside this element. + * The child elements to be rendered within this component. */ children?: preact.ComponentChildren; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 clickable chip component. These properties define an interactive chip that can be clicked or removed. - * @publicDocs + * Configure the following properties on the clickable chip component. */ export interface ClickableChipProps extends Required< @@ -79,115 +123,48 @@ export interface ClickableChipProps | 'commandFor' | 'interestFor' > - > {} - -/** - * A string containing CSS styles for the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with Preact. - * @publicDocs - */ -export type RenderImpl = Omit & { + > { /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An event-like object that contains activation information for synthetic clicks. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during activation. - */ - shiftKey: boolean; - /** - * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during activation. + * Whether the chip is hidden from view. When using controlled component pattern with `removable` chips, update this property when the `remove` event fires. For non-removable chips, manually toggle this property to show or hide the chip. + * + * @default false */ - metaKey: boolean; + hidden: Required['hidden']; /** - * Whether the control key was pressed during activation. + * Whether the chip is disabled, preventing any user interaction. + * + * @default false */ - ctrlKey: boolean; + disabled: Required['disabled']; /** - * The mouse button that was pressed during activation. + * 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. */ - button: number; -} -/** - * Options for customizing synthetic click behavior. - * @publicDocs - */ -export interface ClickOptions { + href: Required['href']; /** - * 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 chip displays a remove button for dismissal. When clicked, the `remove` callback fires. + * + * @default false */ - sourceEvent?: ActivationEventEsque; + removable: Required['removable']; } -/** - * 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); /** @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; } -/** - * Props for controlling overlay components like popovers and dialogs. - * @publicDocs - */ export interface PreactOverlayControlProps extends Pick { /** - * 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' */ @@ -196,62 +173,53 @@ export interface PreactOverlayControlProps '--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 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; /** - * Sets the element 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; } -declare const ClickableChip_base: (abstract new ( - args_0: RenderImpl, -) => PreactCustomElement & PreactOverlayControlProps) & - Pick; -/** - * A custom element for displaying interactive chips that can be clicked or removed. - */ -declare class ClickableChip - extends ClickableChip_base - implements ClickableChipProps +declare const ClickableChipBase_base: (abstract new ( + renderImpl: Omit, +) => PolarisCustomElement & PreactOverlayControlProps) & + Pick; +declare abstract class ClickableChipBase< + TTagName extends keyof HTMLElementTagNameMap, + > + extends ClickableChipBase_base + implements + Pick< + ClickableChipProps, + 'accessibilityLabel' | 'removable' | 'hidden' | 'disabled' | 'href' + > { - /** - * The color of the chip. - */ - accessor color: ClickableChipProps['color']; - /** - * A text description of the chip for screen readers. - */ accessor accessibilityLabel: ClickableChipProps['accessibilityLabel']; - /** - * Whether the chip can be removed by the user. - */ accessor removable: ClickableChipProps['removable']; - /** - * Whether the chip is hidden from view. - */ accessor hidden: ClickableChipProps['hidden']; - /** - * Whether the chip is disabled and can't be clicked. - */ accessor disabled: ClickableChipProps['disabled']; - /** - * The URL to navigate to when the chip is clicked. - */ accessor href: ClickableChipProps['href']; + accessor onclick: CallbackEventListener | null; + accessor onremove: CallbackEventListener | null; + accessor onafterhide: CallbackEventListener | null; + abstract accessor color: string; + constructor(renderImpl: Omit); +} + +/** + * Configure the following properties on the clickable chip component. + * @publicDocs + */ +declare class ClickableChip + extends ClickableChipBase + implements ClickableChipProps +{ /** - * A callback that's fired when the chip is clicked. - */ - accessor onclick: CallbackEventListener | null; - /** - * A callback that's fired when the chip is removed. - */ - accessor onremove: CallbackEventListener | null; - /** - * A callback that's fired after the chip finishes hiding. + * The color emphasis level that controls visual intensity. */ - accessor onafterhide: CallbackEventListener | null; + accessor color: ClickableChipProps['color']; constructor(); } declare global { @@ -269,31 +237,27 @@ declare module 'preact' { } declare const tagName = 's-clickable-chip'; -/** - * The JSX properties for the clickable chip component. These properties define how a clickable chip is rendered in Preact or JSX. - * @publicDocs - */ export interface ClickableChipJSXProps extends Partial, Pick { /** - * The content of the chip. + * The text label displayed within the chip, which represents an interactive filter, tag, or selectable item. */ children?: ComponentChildren; /** - * An optional icon to display at the start of the chip. Accepts only Icon components. + * An optional icon to display at the start of the chip. Accepts only icon components. */ graphic?: ComponentChildren; /** - * A callback that's fired when the chip is clicked. + * A callback fired when the chip is clicked. */ onClick?: ((event: CallbackEvent) => void) | null; /** - * A callback that's fired when the chip is removed. + * A callback fired when the user clicks the remove button on the chip. */ onRemove?: ((event: CallbackEvent) => void) | null; /** - * A callback that's fired after the chip finishes hiding. + * A callback fired when the chip is completely hidden, after any hide animations have completed. */ onAfterHide?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/ColorField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ColorField.d.ts index ddfc2ccc4e..f37e9482cd 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ColorField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ColorField.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,218 +9,164 @@ import type { TextFieldProps, ColorFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event object with a strongly-typed currentTarget property that references the specific HTML element type. + * 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 = Event & { - /** - * The DOM element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function or null that receives a typed callback event. + * 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 = | (EventListener & { - /** - * The callback function that's invoked when the event fires. - */ (event: CallbackEvent): void; }) | null; -/** - * The React-style event handler props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's triggered when the field's value changes as the user types. + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field's value changes and the field loses focus. + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field receives focus. + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field loses focus. + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles to be applied to the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An object containing information about keyboard and mouse button states during an activation event. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the Meta (Command on Mac, Windows key on PC) key was pressed during the event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the event. - */ - button: number; -} -/** - * The options for programmatically triggering a click event on an element. - * @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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The required props for input elements that all form controls must implement. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * The base class for form input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** @private */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * The callback that's triggered when the input value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the input value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * The unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name of the input, used when submitting form data. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; - /** - * The current value of the input. - */ set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The common props shared by all form field components in the admin UI. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -239,17 +185,17 @@ export type PreactFieldProps = > > & { /** - * A hint about the intended content of the field for browser autofill. + * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * - * Alternatively, you can provide a value which describes the - * specific data you'd like to be entered into this field during autofill. + * Alternatively, you can provide value which describes the + * specific data you would like to be entered into this field during autofill. * * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers. * @@ -260,63 +206,27 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** - * The base class for form field elements that includes label, error, and validation support. - */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * The callback that's triggered when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint about the intended content of the field for browser autofill. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value of the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * The additional text displayed below the field to provide helpful context. - */ accessor details: PreactFieldProps['details']; - /** - * The error message displayed when the field validation fails. - */ accessor error: PreactFieldProps['error']; - /** - * The text label displayed above the field. - */ accessor label: PreactFieldProps['label']; - /** - * The visibility of the label for accessibility purposes. Available values: `hidden`, `visible`. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The hint text displayed inside the field when it's empty. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only and can't be edited by the user. - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before the form can be submitted. - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically * ignore keystrokes originating from within input elements. Unfortunately, - * these never account for a custom element being the input element. + * these never account for a Custom Element being the input element. * - * To fix this, we spoof getAttribute and hasAttribute to make a PreactFieldElement + * To fix this, we spoof getAttribute & hasAttribute to make a PreactFieldElement * appear as a contentEditable "input" when it contains a focused input element. * @private technically not private, but we don't want to expose this as public API */ @@ -326,8 +236,8 @@ declare class PreactFieldElement */ hasAttribute(qualifiedName: string): boolean; /** - * Checks if the shadow tree contains a focused input (input, textarea, select, contentEditable element). - * Note: this doesn't return true for focused non-field form elements like buttons. + * Checks if the shadow tree contains a focused input (input, textarea, select, ). + * Note: this does _not_ return true for focussed non-field form elements like buttons. * @private */ get isContentEditable(): boolean; @@ -339,39 +249,35 @@ declare class PreactFieldElement } /** - * The properties for the color field component. These properties configure an input field that allows merchants to select colors using an integrated visual color picker with text input, hex color format, and optional alpha (transparency) channel support. + * Represents the props for color input field components. Extends `PreactFieldProps` with autocomplete support for color-related fields. * @publicDocs */ -export type ColorFieldProps = Omit< - PreactFieldProps['autocomplete']>, - 'value' | 'defaultValue' +export type ColorFieldProps = PreactFieldProps< + Required['autocomplete'] > & Required>; -/** - * The color field custom element class that renders a color input field with integrated visual picker in the Shopify admin interface. This component allows merchants to select colors by typing hex values or using an interactive color picker, with optional support for transparency (alpha channel). - */ -declare class ColorField +declare abstract class ColorFieldBase extends PreactFieldElement - implements ColorFieldProps + implements Pick { - /** - * Whether the color picker includes an alpha (transparency) channel for selecting semi-transparent colors. - * - * @default false - */ accessor alpha: ColorFieldProps['alpha']; - /** - * The current color value, formatted as a hex color string (e.g., `#FF0000` or `#FF0000FF` with alpha). - */ get value(): string; set value(value: string); /** @private */ formResetCallback(): void; - constructor(); + constructor(renderImpl: RenderImpl); /** @private */ setInternalValue(value: string, normalize: boolean): void; } + +/** + * Configure the following properties on the color field component. + * @publicDocs + */ +declare class ColorField extends ColorFieldBase implements ColorFieldProps { + constructor(); +} declare global { interface HTMLElementTagNameMap { [tagName]: ColorField; @@ -380,30 +286,20 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: ColorFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-color-field'; -/** - * The JSX props for the color field component. These properties extend `ColorFieldProps` with JSX-specific event callbacks for React-style event handling when used in Preact, including callbacks for color changes as the merchant interacts with the picker. - * @publicDocs - */ export interface ColorFieldJSXProps - extends Partial< - Omit - >, - Pick, - Required>, - FieldReactProps { - /** - * A callback that's triggered when the color value changes as the user interacts with the picker. - */ + extends Partial>, + Pick, + FieldReactProps, + FieldSlotInternalReactProps { onInput?: (event: CallbackEvent) => void; - /** - * A callback that's triggered when the color value changes and the field loses focus. - */ onChange?: (event: CallbackEvent) => void; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/ColorPicker.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ColorPicker.d.ts index 9ef02b1a60..fc81417f05 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ColorPicker.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ColorPicker.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,200 +6,155 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ColorPickerProps$1, ComponentChildren} from './shared.d.ts'; +import type { + ColorPickerProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event object with a strongly-typed `currentTarget` property that references the specific HTML element type. + * 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 = Event & { - /** - * The DOM element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function or null that receives a typed callback event. + * 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 = | (EventListener & { - /** - * The callback function that's invoked when the event fires. - */ (event: CallbackEvent): 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 { /** - * 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; /** - * 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; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * Properties for rendering a color picker that provides a visual interface for selecting colors with optional transparency control. - * @publicDocs + * Configure the following properties on the color picker component. */ export interface ColorPickerProps extends Required< Pick - > {} - -/** - * A string containing CSS styles to be applied to the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { + > { /** - * A function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; -}; -/** - * An object containing information about keyboard and mouse button states during an activation event. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the Meta (Command on Mac, Windows key on PC) key was pressed during the event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the event. + * The currently selected color value. Accepts multiple input formats: + * + * - Hex: `#RGB`, `#RRGGBB`, `#RRGGBBAA` (3, 6, or 8 digits) + * - RGB/RGBA: `rgb(255, 0, 0)` or `rgb(255 0 0)` (comma or space-separated) + * - HSL/HSLA: `hsl(0, 100%, 50%)` or `hsl(0 100% 50%)` + * + * Returns an empty string if the value is invalid. The `change` event always emits values in hex format. */ - ctrlKey: boolean; + value: Required['value']; /** - * The mouse button that was pressed during the event. + * The initial color value when the field first loads. Unlike `placeholder`, this is a real value that the user can edit and that gets submitted with the form. Once the user starts interacting, their input replaces it. Changing this property after the field has loaded has no effect. To update the field value at any time, use `value` instead. */ - button: number; -} -/** - * The options for programmatically triggering a click event on an element. - * @publicDocs - */ -export interface ClickOptions { + defaultValue: Required['defaultValue']; /** - * 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 to enable alpha (transparency) channel selection in the color picker, allowing users to choose semi-transparent colors. + * + * @default false */ - sourceEvent?: ActivationEventEsque; + alpha: Required['alpha']; } -/** - * 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$1: typeof globalThis.HTMLElement; -declare abstract class PreactCustomElement extends BaseClass$1 { - /** @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); /** @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; } declare const internals: unique symbol; -/** - * The base class for form-associated components that can participate in form submission. - */ -declare class BaseClass extends PreactCustomElement { - /** - * Whether this element can participate in form submission. - */ +declare class BaseClass extends PolarisCustomElement { static formAssociated: boolean; constructor(renderImpl: RenderImpl); /** @private */ [internals]: ElementInternals; } /** - * A visual color picker component that allows users to select colors from a color spectrum interface. + * Configure the following properties on the color picker component. + * @publicDocs */ declare class ColorPicker extends BaseClass implements ColorPickerProps { - /** - * Whether the color picker includes an alpha (transparency) channel for selecting semi-transparent colors. - * - * @default false - */ accessor alpha: boolean; - /** - * The callback that's triggered when the selected color changes and the picker loses focus. - */ accessor onchange: CallbackEventListener | null; - /** - * The callback that's triggered when the selected color changes as the user interacts with the picker. - */ accessor oninput: CallbackEventListener | null; /** - * The name of the picker, used when submitting form data. + * The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form. */ accessor name: string; - /** - * The initial color value when the picker first renders, formatted as a hex color string (e.g., `#FF0000` or `#FF0000FF` with alpha). - */ accessor defaultValue: string; - /** - * The current color value, formatted as a hex color string (e.g., `#FF0000` or `#FF0000FF` with alpha). - */ get value(): string; + set value(value: string); /** - * The current color value, formatted as a hex color string (e.g., `#FF0000` or `#FF0000FF` with alpha). + * A callback that fires when the containing form is reset (using the form's `reset()` method or a reset button). When triggered, the component's `value` reverts to its `defaultValue`. */ - set value(value: string); - /** @private */ formResetCallback(): void; constructor(); } @@ -217,23 +172,13 @@ declare module 'preact' { } declare const tagName = 's-color-picker'; -/** - * The JSX props interface for the color picker component when used in React/Preact. - * @publicDocs - */ export interface ColorPickerJSXProps extends Partial, Pick< ColorPickerProps$1, 'id' | 'alpha' | 'value' | 'defaultValue' | 'name' > { - /** - * A callback that's triggered when the selected color changes as the user interacts with the picker. - */ onInput?: (event: CallbackEvent) => void | null; - /** - * A callback that's triggered when the selected color changes and the picker loses focus. - */ onChange?: (event: CallbackEvent) => void | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/DateField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/DateField.d.ts index c5da934007..5d228d9367 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/DateField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/DateField.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,196 +10,146 @@ import type { TextFieldProps, DateAutocompleteField, DateFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event object with a strongly-typed currentTarget property that references the specific HTML element type. + * 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 = Event & { - /** - * The DOM element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function or null that receives a typed callback event. + * 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 = | (EventListener & { - /** - * The callback function that's invoked when the event fires. - */ (event: CallbackEvent): void; }) | null; /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles to be applied to the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An object containing information about keyboard and mouse button states during an activation event. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the Meta (Command on Mac, Windows key on PC) key was pressed during the event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the event. - */ - button: number; -} -/** - * The options for programmatically triggering a click event on an element. - * @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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The required props for input elements that all form controls must implement. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * The base class for form input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** @private */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * The callback that's triggered when the input value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the input value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * The unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name of the input, used when submitting form data. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; - /** - * The current value of the input. - */ set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The common props shared by all form field components in the admin UI. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -218,18 +168,19 @@ export type PreactFieldProps = > > & { /** - * Controls browser autofill behavior for the field. + * A hint as to the intended content of the field. * - * Basic values: - * - `on` - Enables autofill without specifying content type (default) - * - `off` - Disables autofill for sensitive data or one-time codes + * When set to `on` (the default), this property indicates that the field should support + * autofill, but you do not have any more semantic information on the intended + * contents. * - * Specific field values describe the expected data type. You can optionally prefix these with: - * - `section-${string}` - Scopes autofill to a specific form section (when multiple forms exist on the same page) - * - `shipping` or `billing` - Indicates whether the data is for shipping or billing purposes - * - Both section and group (for example, `section-primary shipping email`) + * When set to `off`, you are indicating that this field contains sensitive + * information, or contents that are never saved, like one-time codes. * - * Providing a specific autofill token helps browsers suggest more relevant saved data. Learn more about [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens). + * Alternatively, you can provide value which describes the + * specific data you would like to be entered into this field during autofill. + * + * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers. * * @default 'tel' for PhoneField * @default 'email' for EmailField @@ -238,63 +189,27 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** - * The base class for form field elements that includes label, error, and validation support. - */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * The callback that's triggered when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint about the intended content of the field for browser autofill. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value of the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * The additional text displayed below the field to provide helpful context. - */ accessor details: PreactFieldProps['details']; - /** - * The error message displayed when the field validation fails. - */ accessor error: PreactFieldProps['error']; - /** - * The text label displayed above the field. - */ accessor label: PreactFieldProps['label']; - /** - * The visibility of the label for accessibility purposes. Available values: `hidden`, `visible`. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The hint text displayed inside the field when it's empty. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only and can't be edited by the user. - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before the form can be submitted. - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically * ignore keystrokes originating from within input elements. Unfortunately, - * these never account for a custom element being the input element. + * these never account for a Custom Element being the input element. * - * To fix this, we spoof getAttribute and hasAttribute to make a PreactFieldElement + * To fix this, we spoof getAttribute & hasAttribute to make a PreactFieldElement * appear as a contentEditable "input" when it contains a focused input element. * @private technically not private, but we don't want to expose this as public API */ @@ -304,8 +219,8 @@ declare class PreactFieldElement */ hasAttribute(qualifiedName: string): boolean; /** - * Checks if the shadow tree contains a focused input (input, textarea, select, contentEditable element). - * Note: this doesn't return true for focused non-field form elements like buttons. + * Checks if the shadow tree contains a focused input (input, textarea, select, ). + * Note: this does _not_ return true for focussed non-field form elements like buttons. * @private */ get isContentEditable(): boolean; @@ -317,14 +232,10 @@ declare class PreactFieldElement } /** - * The properties for the date field component. These properties configure an input field that allows merchants to select dates using an integrated calendar picker with optional text input, date constraints, and day-of-week restrictions. - * @publicDocs + * Configure the following properties on the date field component. */ export interface DateFieldProps - extends Omit< - PreactFieldProps, - 'value' | 'defaultValue' - >, + extends PreactFieldProps, Required< Pick< DateFieldProps$1, @@ -337,51 +248,51 @@ export interface DateFieldProps | 'view' | 'defaultView' > - > {} - -/** - * The date field custom element class that renders a date input field with integrated calendar picker in the Shopify admin interface. This component allows merchants to select dates by typing or using a visual calendar, with support for date range restrictions and day-of-week constraints. - */ -declare class DateField - extends PreactFieldElement - implements DateFieldProps -{ + > { /** - * The dates that are allowed to be selected, specified as ISO 8601 date strings or date ranges. + * The currently selected date in `YYYY-MM-DD` format. An empty string means no date is selected. + * + * @default "" */ - accessor allow: DateFieldProps['allow']; + value: Required['value']; /** - * The dates that aren't allowed to be selected, specified as ISO 8601 date strings or date ranges. + * The initial date value when the field first renders, in `YYYY-MM-DD` format. An empty string means no date is initially selected. + * + * @default "" */ + defaultValue: Required['defaultValue']; +} + +declare abstract class DateFieldBase + extends PreactFieldElement + implements + Pick< + DateFieldProps, + | 'allow' + | 'disallow' + | 'allowDays' + | 'disallowDays' + | 'view' + | 'defaultView' + > +{ + accessor allow: DateFieldProps['allow']; accessor disallow: DateFieldProps['disallow']; - /** - * The days of the week that are allowed to be selected. Available values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. - */ accessor allowDays: DateFieldProps['allowDays']; - /** - * The days of the week that aren't allowed to be selected. Available values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. - */ accessor disallowDays: DateFieldProps['disallowDays']; - /** - * The currently visible month and year in the calendar picker, formatted as an ISO 8601 date string. - */ set view(view: string); - /** - * The currently visible month and year in the calendar picker, formatted as an ISO 8601 date string. - */ get view(): string; - /** - * The initial month and year shown when the calendar picker first opens, formatted as an ISO 8601 date string. - */ accessor defaultView: DateFieldProps['defaultView']; - /** - * The callback that's triggered when the visible month or year in the calendar changes. - */ - accessor onviewchange: CallbackEventListener | null; - /** - * The callback that's triggered when the user attempts to enter an invalid date. - */ - accessor oninvalid: CallbackEventListener | null; + accessor onviewchange: CallbackEventListener<'s-date-field'> | null; + accessor oninvalid: CallbackEventListener<'s-date-field'> | null; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the date field component. + * @publicDocs + */ +declare class DateField extends DateFieldBase implements DateFieldProps { constructor(); } declare global { @@ -392,41 +303,40 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: DateFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-date-field'; -/** - * The JSX props for the date field component. These properties extend `DateFieldProps` with JSX-specific event callbacks for React-style event handling when used in Preact, including specialized callbacks for view changes and invalid date attempts. - * @publicDocs - */ export interface DateFieldJSXProps - extends Partial>, - Pick { + extends Partial>, + Pick, + FieldSlotInternalReactProps { /** - * A callback that's triggered when the field loses focus. + * A callback fired when the date field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field's value changes and the field loses focus. + * A callback fired when the user has finished editing the date and the field value changes. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field receives focus. + * A callback fired when the date field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field's value changes as the user types or selects. + * A callback fired when the user makes any changes to the date value. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the user attempts to enter an invalid date. + * A callback fired when the field contains an invalid date. */ onInvalid?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the visible month or year in the calendar changes. + * A callback fired when the calendar view changes, such as when navigating between months. */ onViewChange?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/DatePicker.d.ts b/packages/ui-extensions/src/surfaces/admin/components/DatePicker.d.ts index b2ea3c327d..0290909f02 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/DatePicker.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/DatePicker.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,11 +6,16 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {DatePickerProps$1, ComponentChildren} from './shared.d.ts'; +import type { + DatePickerProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * The properties for the date picker component. These properties configure a standalone calendar interface for selecting single dates or date ranges, with support for date constraints, day-of-week restrictions, and month/year navigation. - * @publicDocs + * Configure the following properties on the date picker component. */ export interface DatePickerProps extends Required< @@ -36,231 +41,227 @@ export interface DatePickerProps * @default "single" */ type: Extract; + /** + * The currently selected date(s). An empty string means no date is selected. + * + * - Single date in `YYYY-MM-DD` format when `type` is set to `"single"` + * - Date range in `YYYY-MM-DD--YYYY-MM-DD` format (inclusive) when `type` is set to `"range"` + * + * @default "" + */ + value: Required['value']; + /** + * The initially selected date(s) when the component first renders. An empty string means no date is initially selected. + * + * - Single date in `YYYY-MM-DD` format when `type` is set to `"single"` + * - Date range in `YYYY-MM-DD--YYYY-MM-DD` format (inclusive) when `type` is set to `"range"` + * + * @default "" + */ + defaultValue: Required['defaultValue']; + /** + * Specifies which dates can be selected as a comma-separated list. An empty string (default) allows all dates. + * + * **Formats:** + * - `YYYY-MM-DD`: Single date + * - `YYYY-MM`: Whole month + * - `YYYY`: Whole year + * - `start--end`: Date range (inclusive, unbounded if start/end omitted) + * + * **Examples:** + * - `2024-02--2025`: February 2024 through end of 2025 + * - `2024-05-09, 2024-05-11`: Only May 9th and 11th, 2024 + * + * @default "" + */ + allow: Required['allow']; + /** + * Specifies which days of the week can be selected as a comma-separated list. Further restricts dates from `allow` and `disallow`. An empty string (default) has no effect. + * + * **Valid days**: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` + * + * **Example:** `saturday, sunday` (only weekends) + * + * @default "" + */ + allowDays: Required['allowDays']; + /** + * Specifies which dates can't be selected as a comma-separated list. These dates are excluded from those specified in `allow`. An empty string (default) has no effect. + * + * **Formats:** + * - `YYYY-MM-DD`: Single date + * - `YYYY-MM`: Whole month + * - `YYYY`: Whole year + * - `start--end`: Date range (inclusive, unbounded if start/end omitted) + * + * **Examples:** + * - `--2024-02`: All dates before February 2024 + * - `2024-05-09, 2024-05-11`: May 9th and 11th, 2024 + * + * @default "" + */ + disallow: Required['disallow']; + /** + * Specifies which days of the week can't be selected as a comma-separated list. Excludes days from `allowDays` and intersects with `allow` and `disallow`. An empty string (default) has no effect. + * + * **Valid days**: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` + * + * **Example:** `saturday, sunday` (no weekends) + * + * @default "" + */ + disallowDays: Required['disallowDays']; + /** + * The currently displayed month in `YYYY-MM` format. When changed, the `viewchange` callback is triggered. Defaults to `defaultView`. + */ + view: Required['view']; + /** + * The default month to display in `YYYY-MM` format. Used until the `view` callback is set by user interaction or programmatically. Defaults to the current month in the user's locale. + */ + defaultView: Required['defaultView']; + /** + * Controls how many months are displayed. + * + * - `'auto'`: Context-driven. Today this renders a single month, matching `'1'`. + * - `'1'`: Renders one month at a time. + * - `'2'`: Renders two consecutive months side-by-side. + * + * @default 'auto' + */ + visibleMonths: 'auto' | '1' | '2'; +} + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } } /** - * An event object with a strongly-typed currentTarget property that references the specific HTML element type. + * 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 = Event & { - /** - * The DOM element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function or null that receives a typed callback event. + * 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 = | (EventListener & { - /** - * The callback function that's invoked when the event fires. - */ (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles to be applied to the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; -}; -/** - * An object containing information about keyboard and mouse button states during an activation event. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the Meta (Command on Mac, Windows key on PC) key was pressed during the event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the event. - */ - button: number; -} -/** - * The options for programmatically triggering a click event on an element. - * @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; -} -/** - * 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$1: typeof globalThis.HTMLElement; -declare abstract class PreactCustomElement extends BaseClass$1 { - /** @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); /** @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; } declare const internals: unique symbol; declare const dirtyStateSymbol: unique symbol; -/** - * The base class for form-associated components that can participate in form submission. - */ -declare class BaseClass extends PreactCustomElement { - /** - * Whether this element can participate in form submission. - */ +declare abstract class DatePickerBase< + TagName extends 's-date-picker' | 's-internal-date-picker', + > + extends PolarisCustomElement + implements DatePickerProps +{ static formAssociated: boolean; constructor(renderImpl: RenderImpl); /** @private */ [internals]: ElementInternals; -} -/** - * The date picker custom element class that renders a standalone calendar interface in the Shopify admin. This component allows merchants to select single dates or date ranges using an interactive calendar with month/year navigation, date constraints, and day-of-week restrictions. - */ -declare class DatePicker extends BaseClass implements DatePickerProps { - /** - * The initial month and year shown when the calendar first renders, formatted as an ISO 8601 date string. - */ accessor defaultView: string; - /** - * The currently visible month and year in the calendar, formatted as an ISO 8601 date string. - */ set view(view: string); - /** - * The currently visible month and year in the calendar, formatted as an ISO 8601 date string. - */ get view(): string; - /** - * The dates that are allowed to be selected, specified as ISO 8601 date strings or date ranges. - */ accessor allow: DatePickerProps['allow']; - /** - * The dates that aren't allowed to be selected, specified as ISO 8601 date strings or date ranges. - */ accessor disallow: DatePickerProps['disallow']; - /** - * The days of the week that are allowed to be selected. Available values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. - */ accessor allowDays: DatePickerProps['allowDays']; - /** - * The days of the week that aren't allowed to be selected. Available values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. - */ accessor disallowDays: DatePickerProps['disallowDays']; - /** - * The type of date selection allowed. Available values: `single`, `range`. - */ accessor type: DatePickerProps['type']; - /** - * The initial selected date or date range when the picker first renders, formatted as an ISO 8601 date string. - */ accessor defaultValue: DatePickerProps['defaultValue']; - /** - * The name of the picker, used when submitting form data. - */ accessor name: DatePickerProps['name']; - /** - * The currently selected date or date range, formatted as an ISO 8601 date string. - */ + accessor visibleMonths: DatePickerProps['visibleMonths']; set value(value: string); - /** - * The currently selected date or date range, formatted as an ISO 8601 date string. - */ get value(): string; /** @private */ [dirtyStateSymbol]: boolean; /** @private */ formResetCallback(): void; - /** - * The callback that's triggered when the visible month or year in the calendar changes. - */ - accessor onviewchange: CallbackEventListener | null; - /** - * The callback that's triggered when the picker receives focus. - */ - accessor onfocus: CallbackEventListener | null; - /** - * The callback that's triggered when the picker loses focus. - */ - accessor onblur: CallbackEventListener | null; - /** - * The callback that's triggered when the selected date changes as the user interacts with the picker. - */ - accessor oninput: CallbackEventListener | null; - /** - * The callback that's triggered when the selected date changes and the picker loses focus. - */ - accessor onchange: CallbackEventListener | null; + accessor onviewchange: CallbackEventListener | null; + accessor onfocus: CallbackEventListener | null; + accessor onblur: CallbackEventListener | null; + accessor oninput: CallbackEventListener | null; + accessor onchange: CallbackEventListener | null; +} + +/** + * Configure the following properties on the date picker component. + * @publicDocs + */ +declare class DatePicker + extends DatePickerBase + implements DatePickerProps +{ constructor(); } declare global { @@ -277,31 +278,27 @@ declare module 'preact' { } declare const tagName = 's-date-picker'; -/** - * The JSX props for the date picker component. These properties extend `DatePickerProps` with JSX-specific event callbacks for React-style event handling when used in Preact, including callbacks for date selection, focus events, and view changes. - * @publicDocs - */ export interface DatePickerJSXProps extends Partial, Pick { /** - * A callback that's triggered when the visible month or year in the calendar changes. + * A callback fired when the calendar view changes, such as when navigating between months. */ onViewChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the picker receives focus. + * A callback fired when the date picker receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the picker loses focus. + * A callback fired when the date picker loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the selected date changes as the user interacts with the picker. + * A callback fired when the user makes any changes to the selected date. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the selected date changes and the picker loses focus. + * A callback fired when the user has finished selecting a date and the value changes. */ onChange?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Divider.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Divider.d.ts index ad68c7fa47..4ae760fffa 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Divider.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Divider.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,11 +6,16 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {DividerProps$1, ComponentChildren} from './shared.d.ts'; +import type { + DividerProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * The properties for the divider component. A divider creates a visual separator to distinguish different sections of content. - * @publicDocs + * Configure the following properties on the divider component. */ export interface DividerProps extends Pick { @@ -34,143 +39,74 @@ export interface DividerProps color: Extract; } -/** - * 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 & { - /** - * The function that renders the shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to apply to the shadow root. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An interface representing the properties of an activation event, such as a click or keypress. - * @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 PC) 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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * A divider is a visual separator that creates a line between different sections of content. + * Configure the following properties on the divider component. + * @publicDocs */ -declare class Divider extends PreactCustomElement implements DividerProps { - /** - * The orientation of the divider line, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). - * - * - `inline`: Horizontal divider for separating vertically stacked content - * - `block`: Vertical divider for separating horizontally arranged content - * - * @default 'inline' - */ +declare class Divider extends PolarisCustomElement implements DividerProps { accessor direction: DividerProps['direction']; - /** - * The visual prominence of the divider line. - * - * - `base`: Standard divider for most separations (default) - * - `strong`: More prominent divider for major section breaks - * - * @default 'base' - */ accessor color: DividerProps['color']; constructor(); } @@ -188,10 +124,6 @@ declare module 'preact' { } declare const tagName = 's-divider'; -/** - * The properties for the divider component when it's used in JSX. - * @publicDocs - */ export interface DividerJSXProps extends Partial, Pick {} diff --git a/packages/ui-extensions/src/surfaces/admin/components/DropZone.d.ts b/packages/ui-extensions/src/surfaces/admin/components/DropZone.d.ts index 81f2200ff1..86a973a1b2 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/DropZone.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/DropZone.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.38.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -12,32 +12,70 @@ import type { PreactCustomElement, RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +/** + * 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 = 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 = | (EventListener & { (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs +/** + * 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 { - /** Assigns a unique key to this element. */ + /** + * 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; - /** Assigns a ref (generally from `useRef()`) to this element. */ + /** + * 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; - /** Assigns this element to a parent's slot. */ + /** + * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** * @publicDocs + +/** + * Configure the following properties on the drop zone component. */ export interface DropZoneProps extends Required< @@ -55,12 +93,80 @@ export interface DropZoneProps | 'required' | 'value' > - > {} + > { + /** + * A label that describes the purpose or contents of the item. When set, + * it will be announced to buyers using assistive technologies and will + * provide them with more context. + */ + accessibilityLabel: Required['accessibilityLabel']; + /** + * Whether multiple files can be selected or dropped at once. + * + * @default false + */ + multiple: Required['multiple']; + /** + * A string representing the types of files that are accepted by the drop zone. + * This string is a comma-separated list of unique file type specifiers which can be one of the following: + * - A file extension starting with a period (".") character (e.g. .jpg, .pdf, .doc) + * - A valid MIME type string with no extensions + * + * If omitted, all file types are accepted. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept + * @default '' + */ + accept: Required['accept']; +} + +export type ReadOnlyPropKeys = Config extends { + readonly readOnlyProps: ReadonlyArray; +} + ? Extract + : never; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} declare class PolarisCustomElement extends PreactCustomElement { constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; } -/** * @publicDocs + +/** + * A utility type that replaces occurrences of one type with another within a union type. Useful for type transformations where you need to swap out specific types. + * @publicDocs */ export type ReplaceType = Exclude | TTo; @@ -79,8 +185,23 @@ declare abstract class DropZoneBase extends PolarisCustomElement { accessor multiple: DropZoneProps['multiple']; accessor name: DropZoneProps['name']; accessor required: DropZoneProps['required']; + /** + * A callback fired when the user selects files through the file picker or drops valid + * files onto the drop zone. Access the selected files through `event.currentTarget.files`. + * Use to process uploads, generate previews, or validate file contents. + */ accessor onchange: CallbackEventListener; + /** + * A callback fired when files are selected or dropped. Similar to `onChange` but may + * fire more frequently during drag operations. Use when you need immediate feedback as + * files are being dragged over the drop zone. + */ accessor oninput: CallbackEventListener; + /** + * A callback fired when dropped or selected files don't match the `accept` criteria. + * Use to display error messages explaining which file types are allowed. Rejected files + * are not added to the `files` array. + */ accessor ondroprejected: CallbackEventListener; get value(): string; /** This sets the input value for a file type, which cannot be set programatically, so it can only be reset. */ @@ -103,6 +224,10 @@ declare abstract class DropZoneBase extends PolarisCustomElement { constructor(renderImpl: RenderImpl); } +/** + * Configure the following properties on the drop zone component. + * @publicDocs + */ declare class DropZone extends DropZoneBase implements DropZoneProps { constructor(); } @@ -114,8 +239,12 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: DropZoneJSXProps & - PreactBaseElementPropsWithChildren; + [tagName]: Omit< + DropZoneJSXProps, + ReadOnlyPropKeys + > & { + value?: '' | null; + } & PreactBaseElementPropsWithChildren; } } } @@ -125,13 +254,25 @@ export interface DropZoneJSXProps extends Partial, Pick { /** - * Content to include inside the DropZone container + * The content to include inside the drop zone container */ children?: ComponentChildren; + /** + * A callback fired when the user has finished selecting files and the value changes. + */ onChange?: ((event: CallbackEvent) => void) | null; + /** + * A callback fired when files are selected or dropped. + */ onInput?: ((event: CallbackEvent) => void) | null; + /** + * A callback fired when a dropped file is rejected due to file type or size restrictions. + */ onDropRejected?: ((event: CallbackEvent) => void) | null; } +declare const reactWrapperConfig: { + readonly readOnlyProps: readonly ['files', 'value']; +}; export {DropZone}; export type {DropZoneJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/EmailField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/EmailField.d.ts index 5ffc176491..29303aefc8 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/EmailField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/EmailField.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,21 +9,30 @@ import type { TextFieldProps, EmailFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event with a strongly-typed currentTarget property for 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 = Event & { - /** - * The element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A callback function that receives a strongly-typed event for 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 = @@ -31,189 +40,133 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** - * The React-style event callback props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's invoked when the user makes any changes in the field. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles for the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a Preact component in a shadow root. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's Preact elements into the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the shadow root. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * The properties from an event that indicate how the user activated an element. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down when the event occurred. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on macOS) was held down when the event occurred. - */ - metaKey: boolean; - /** - * Whether the Control key was held down when the event occurred. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed when the event occurred. A value of 0 indicates the primary button (usually left), 1 indicates the middle button, and 2 indicates the secondary button (usually right). - */ - button: number; -} -/** - * The options for influencing a programmatic 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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The base properties for an input element that participates in form submission. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** @private */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the user makes any changes in the field. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the field is disabled, disallowing any interaction. - * - * @default false - */ accessor disabled: PreactInputProps['disabled']; - /** - * An identifier for the field. - */ accessor id: PreactInputProps['id']; - /** - * An identifier for the field that's unique within the nearest containing form. - */ accessor name: PreactInputProps['name']; - /** - * The current value for the field. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The base properties for form field elements that support labels, validation, and autocomplete. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -235,10 +188,10 @@ export type PreactFieldProps = * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * * Alternatively, you can provide value which describes the @@ -253,58 +206,20 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** @private */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * A callback that's invoked when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint as to the intended content of the field for autocomplete purposes. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value for the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * Additional descriptive text to display below the field that provides supplementary information. - */ accessor details: PreactFieldProps['details']; - /** - * An error message to display below the field, indicating validation failure or other issues. - */ accessor error: PreactFieldProps['error']; - /** - * The text label to display for the field, describing what the user should enter. - */ accessor label: PreactFieldProps['label']; - /** - * Controls the visibility of the label for accessibility purposes. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The placeholder text that's displayed inside the field when it's empty, providing a hint about expected input. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only, preventing edits while still allowing focus and selection. - * - * @default false - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before form submission. - * - * @default false - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically @@ -334,7 +249,7 @@ declare class PreactFieldElement } /** - * The properties for the email field component. These properties configure a specialized text input field for entering email addresses with built-in validation and appropriate keyboard support. + * Represents the props for email input field components. Extends `PreactFieldProps` with autocomplete support for email-related fields. * @publicDocs */ export type EmailFieldProps = PreactFieldProps< @@ -342,32 +257,21 @@ export type EmailFieldProps = PreactFieldProps< > & Required>; -/** - * The email field custom element class that renders an email input field in the Shopify admin interface. This component allows merchants to enter email addresses with automatic validation and optimized mobile keyboard layouts. - */ -declare class EmailField +declare abstract class EmailFieldBase extends PreactFieldElement - implements EmailFieldProps + implements Pick { - /** - * A hint as to the intended content of the field for autocomplete purposes. - * - * @default 'email' - */ accessor autocomplete: EmailFieldProps['autocomplete']; - /** - * The maximum number of characters the user can enter in the field. - */ accessor maxLength: EmailFieldProps['maxLength']; - /** - * The minimum number of characters required in the field for validation. - */ accessor minLength: EmailFieldProps['minLength']; - /** - * The current email address value in the field. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. The field validates this value as an email address format when the user finishes editing. - */ - get value(): string; - set value(value: string); + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the email field component. + * @publicDocs + */ +declare class EmailField extends EmailFieldBase implements EmailFieldProps { constructor(); } declare global { @@ -378,20 +282,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: EmailFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-email-field'; -/** - * The JSX props for the email field component. These properties extend `EmailFieldProps` with JSX-specific event callbacks for React-style event handling. - * @publicDocs - */ export interface EmailFieldJSXProps - extends Partial>, + extends Partial>, Pick, - FieldReactProps {} + FieldReactProps, + FieldSlotInternalReactProps {} export {EmailField}; export type {EmailFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/EmptyState.d.ts b/packages/ui-extensions/src/surfaces/admin/components/EmptyState.d.ts new file mode 100644 index 0000000000..cea022edc7 --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/components/EmptyState.d.ts @@ -0,0 +1,144 @@ +/** VERSION: 2.23.0 **/ +/* eslint-disable import/extensions */ + +/* eslint-disable @typescript-eslint/no-namespace */ + +// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment +/// +import type { + ComponentChildren, + EmptyStateProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export interface EmptyStateProps + extends Required> {} + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * 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 { + /** + * 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 access the underlying DOM element directly. + * Typically created using `useRef()` to interact with the element imperatively or measure its properties. + */ + ref?: preact.Ref; + /** + * 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; +} +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs + */ +export interface PreactBaseElementPropsWithChildren + extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ + children?: preact.ComponentChildren; +} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +/** + * Configure the following properties on the empty state component. + * @publicDocs + */ +declare class EmptyState + extends PolarisCustomElement + implements EmptyStateProps +{ + constructor(); + accessor heading: EmptyStateProps['heading']; +} +declare global { + interface HTMLElementTagNameMap { + [tagName]: EmptyState; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: Omit< + EmptyStateJSXProps, + 'primaryAction' | 'secondaryActions' | 'graphic' | 'subheading' + > & + PreactBaseElementPropsWithChildren; + } + } +} + +declare const tagName = 's-empty-state'; +export interface EmptyStateJSXProps + extends Partial, + Pick { + /** + * The main call to action, rendered below the text content. Accepts a single `Button` with a `variant` of `primary`; anything else is ignored with a development warning. + */ + primaryAction?: ComponentChildren; + /** + * An alternative action, rendered beside the primary one. Accepts a single `Button` with a `variant` of `secondary` or `auto` — despite the plural name, only one is rendered. + */ + secondaryActions?: ComponentChildren; + /** + * An illustration or symbol shown above the heading. Accepts a single `Image` or `Icon`, either directly or as the only child of a wrapping element. + */ + graphic?: ComponentChildren; + /** + * Supporting text below the heading, explaining what's missing or what to do next. Accepts `Text` and `Link` components. + */ + subheading?: ComponentChildren; +} + +export {EmptyState}; +export type {EmptyStateJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Form.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Form.d.ts index 6eea6ca729..776c8e93ce 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Form.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Form.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -8,22 +8,28 @@ import type { ExtendableEvent, FormProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; /** - * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements. + * 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 = Event & { - /** - * The element that the event listener is attached to, strongly typed based on the element's tag name. - */ currentTarget: HTMLElementTagNameMap[T]; }; - /** - * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type. + * 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 = @@ -31,18 +37,12 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; - -/** - * A callback event that includes the `waitUntil` method for extending asynchronous operations. This allows you to delay form submission until promises resolve, enabling async validation or data processing before the form completes its action. - * @publicDocs - */ export interface CallbackExtendableEvent< TTagName extends keyof HTMLElementTagNameMap, > extends CallbackEvent, Pick {} - /** - * An event listener function type for extendable callback events. This combines strong typing with the ability to extend the event lifecycle using `waitUntil`. + * A function that handles extendable events from UI components. This type represents an event listener callback that can use `waitUntil` to extend the event lifetime. * @publicDocs */ export type CallbackExtendableEventListener< @@ -54,135 +54,42 @@ export type CallbackExtendableEventListener< | null; /** - * The properties for the form component. These properties configure the form's identifier for targeting and referencing within the admin extension. - * @publicDocs + * Configure the following properties on the form component. */ export interface FormProps extends Pick {} declare const tagName = 's-form'; - -/** - * The JSX props for the form component. These properties extend `FormProps` with event callbacks for form submission and reset actions in JSX rendering. - * @publicDocs - */ export interface FormJSXProps extends Partial { /** - * A callback that's invoked when the form is submitted. Use the event's `waitUntil` method to perform async operations like validation or data processing before the submission completes. + * A callback that is run when the form is submitted. */ onSubmit?: ((event: CallbackExtendableEvent) => void) | null; /** - * A callback that's invoked when the form is reset, restoring all form fields to their initial values. + * A callback that is run when the form is reset. */ onReset?: ((event: CallbackEvent) => void) | null; } -/** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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 form custom element class that renders a form container in the Shopify admin interface. This component manages form submission, validation, and reset behavior for collecting merchant input. + * Configure the following properties on the form component. + * @publicDocs */ -declare class Form extends PreactCustomElement implements FormProps { +declare class Form extends PolarisCustomElement implements FormProps { constructor(); - /** - * A callback that's invoked when the form is submitted. Use the event's `waitUntil` method to perform async operations like validation, data processing, or API calls before the submission completes. + * A callback that is run when the form is submitted. */ accessor onsubmit: CallbackExtendableEventListener | null; - /** - * A callback that's invoked when the form is reset, restoring all form fields to their initial values. + * A callback that is run when the form is reset. */ accessor onreset: CallbackEventListener | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/FunctionSettings.d.ts b/packages/ui-extensions/src/surfaces/admin/components/FunctionSettings.d.ts index e482de9ee3..466e106044 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/FunctionSettings.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/FunctionSettings.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -8,22 +8,27 @@ import type { FunctionSettingsProps$1, ExtendableEvent, - ComponentChildren, + PreactCustomElement, } from './shared.d.ts'; /** - * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements. + * 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 = Event & { - /** - * The element that the event listener is attached to, strongly typed based on the element's tag name. - */ currentTarget: HTMLElementTagNameMap[T]; }; - /** - * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type. + * 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 = @@ -31,9 +36,8 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; - /** - * An event listener function type for error events that includes an `error` property. This is used for handling validation errors and submission failures in forms. + * A function that handles error events from UI components. This type represents an event listener callback that receives both the event and an error object. * @publicDocs */ export type CallbackErrorEventListener< @@ -43,26 +47,17 @@ export type CallbackErrorEventListener< | (EventListener & { ( event: CallbackEvent & { - /** - * The error that occurred during the operation. - */ error: TError; }, ): void; }) | null; - -/** - * A callback event that includes the `waitUntil` method for extending asynchronous operations. This allows you to delay event completion until promises resolve, enabling async operations during event handling. - * @publicDocs - */ export interface CallbackExtendableEvent< TTagName extends keyof HTMLElementTagNameMap, > extends CallbackEvent, Pick {} - /** - * An event listener function type for extendable callback events. This combines strong typing with the ability to extend the event lifecycle using `waitUntil`. + * A function that handles extendable events from UI components. This type represents an event listener callback that can use `waitUntil` to extend the event lifetime. * @publicDocs */ export type CallbackExtendableEventListener< @@ -74,24 +69,18 @@ export type CallbackExtendableEventListener< | null; /** - * The properties for the function settings component. These properties configure the form's identifier for configuring Shopify Function settings in the admin interface. - * @publicDocs + * Configure the following properties on the function settings component. */ export interface FunctionSettingsProps extends Pick {} declare const tagName = 's-function-settings'; - -/** - * The JSX props for the function settings component. These properties extend `FunctionSettingsProps` with event callbacks for form submission, reset, and error handling in JSX rendering. - * @publicDocs - */ export interface FunctionSettingsJSXProps extends Partial< FunctionSettingsProps & Pick > { /** - * An optional callback function that'll be run by the admin when the user + * 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 @@ -100,115 +89,21 @@ export interface FunctionSettingsJSXProps */ onSubmit?: ((event: CallbackExtendableEvent) => void) | null; /** - * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values. + * A callback that is run when the function settings form is reset. */ onReset?: ((event: CallbackEvent) => void) | null; } /** - * The CSS styles as a string, used for styling web components within their shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The render function that returns Preact/JSX elements to display in the component's shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to inject into the component's shadow DOM. - */ - styles?: Styles; -}; -/** - * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the activation event. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the activation event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click). - */ - button: number; -} -/** - * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs. - * @publicDocs - */ -export interface ClickOptions { - /** - * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab. - */ - 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; -} - -/** - * The error event type that's passed to the `onError` callback of function settings. This event contains validation errors that occurred when committing function settings to Shopify's servers. + * Represents the event type for function settings errors. Extracted from the parameters of the `onFunctionSettingsError` callback. * @publicDocs */ export type FunctionSettingsErrorEvent = Parameters< NonNullable >[0]; - /** - * The function settings custom element class that renders a specialized form for configuring Shopify Function settings in the admin interface. This component manages function configuration submission, validation, and error handling. + * Configure the following properties on the function settings component. + * @publicDocs */ declare class FunctionSettings extends PreactCustomElement @@ -216,7 +111,7 @@ declare class FunctionSettings { constructor(); /** - * An optional callback function that'll be run by the admin when the user + * 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 @@ -224,13 +119,12 @@ declare class FunctionSettings * using the `message` property of the error you reject with. */ accessor onsubmit: CallbackExtendableEventListener | null; - /** - * An optional callback function that'll be run by the admin when + * 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's an `AggregateError` object. This object 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 won't be reported here. + * 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 @@ -242,7 +136,7 @@ declare class FunctionSettings > | null; /** - * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values. + * A callback that is run when the function settings form is reset. */ accessor onreset: CallbackEventListener | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Grid.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Grid.d.ts index 30c3d95d3f..c786ed25be 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Grid.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Grid.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -17,10 +17,45 @@ import type { JustifyItemsKeyword, AlignContentKeyword, JustifyContentKeyword, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * A type that allows a value to be responsive using container query syntax. + * 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 | `@container${string}`; @@ -46,12 +81,21 @@ export type MakeResponsivePick = { }; /** - * A version of the box properties with all fields required. + * Represents the box component props with all properties marked as required. * @publicDocs */ export type RequiredBoxProps = Required; /** - * The allowed border radius values for a box component. + * 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< @@ -66,7 +110,12 @@ export type BoxBorderRadii = Extract< | 'large-200' >; /** - * The allowed border style values for a box component. + * 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< @@ -74,7 +123,9 @@ export type BoxBorderStyles = Extract< 'none' | 'solid' | 'dashed' | 'auto' >; /** - * The box properties that support responsive values through container queries. + * Represents box props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveBoxProps = MakeResponsivePick< @@ -109,7 +160,7 @@ export interface BoxProps | 'overflow' > { /** - * The background color of the grid container. + * The background color of the component. * * @default 'transparent' */ @@ -118,10 +169,13 @@ export interface BoxProps 'transparent' | 'base' | 'subdued' | 'strong' >; /** - * Controls the thickness of the border on all sides. + * A border applied using shorthand syntax to specify width, color, and style in a single property. * - * When set, this overrides the width 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 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 */ @@ -134,10 +188,7 @@ export interface BoxProps > | Extract; /** - * 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 */ @@ -145,10 +196,7 @@ export interface BoxProps | MaybeAllValuesShorthandProperty | Extract; /** - * 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 */ @@ -157,101 +205,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 corners or fully rounded elements. + * The roundedness of the element's corners using the design system's radius scale. * * @default 'none' */ borderRadius: MaybeAllValuesShorthandProperty; /** - * The padding applied to all edges of the grid container. - * - * [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](/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](/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](/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](/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](/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](/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](/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. @@ -260,7 +292,7 @@ export interface BoxProps */ display: ResponsiveBoxProps['display']; /** - * The vertical size of the grid 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. @@ -271,31 +303,44 @@ 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 grid container. + * 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 grid container. + * 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 grid container. + * 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 grid container. + * 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 grid container. + * 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' */ @@ -303,12 +348,14 @@ export interface BoxProps } /** - * A version of the grid properties with all fields required. + * Represents the grid component props with all properties marked as required. * @publicDocs */ export type RequiredAlignedProps = Required; /** - * The grid properties that support responsive values through container queries. + * Represents grid props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveGridProps = MakeResponsivePick< @@ -316,8 +363,7 @@ export type ResponsiveGridProps = MakeResponsivePick< 'rowGap' | 'columnGap' | 'gap' | 'gridTemplateColumns' | 'gridTemplateRows' >; /** - * The properties for the grid component. A grid provides precise control over rows and columns, with powerful alignment and sizing options for both individual items and the entire grid structure. - * @publicDocs + * Configure the following properties on the grid component. */ export interface GridProps extends BoxProps, @@ -333,37 +379,37 @@ export interface GridProps > > { /** - * The alignment of grid items along the block axis (vertical in horizontal writing modes). You can choose values like `'start'`, `'center'`, `'end'`, or `'stretch'` to control how items are positioned within their grid areas. + * Aligns the grid items along the block axis. * * @default '' - meaning no override */ alignItems: AlignItemsKeyword | ''; /** - * The alignment of grid items along the inline axis (horizontal in left-to-right languages). You can choose values like `'start'`, `'center'`, or `'end'` to control how items are positioned within their grid areas. + * Aligns the grid items along the inline axis. * * @default '' - meaning no override */ justifyItems: JustifyItemsKeyword | ''; /** - * A shorthand property for setting both `justifyItems` and `alignItems` at once. You can provide either a single value (which applies to both axes) or two values separated by a space (the first for `alignItems`, the second for `justifyItems`). + * A shorthand property for `justify-items` and `align-items`. * * @default 'normal normal' */ placeItems: `${AlignItemsKeyword} ${JustifyItemsKeyword}` | AlignItemsKeyword; /** - * The alignment of the entire grid along the block axis when there's extra space in the grid container. This property overrides the block-axis value set by the `placeContent` property. + * Aligns the grid along the block axis. This overrides the block value of `placeContent`. * * @default '' - meaning no override */ alignContent: AlignContentKeyword | ''; /** - * The alignment of the entire grid along the inline axis when there's extra space in the grid container. This property overrides the inline-axis value set by the `placeContent` property. + * Aligns the grid along the inline axis. This overrides the inline value of `placeContent`. * * @default '' - meaning no override */ justifyContent: JustifyContentKeyword | ''; /** - * A shorthand property for setting both `justifyContent` and `alignContent` at once. You can provide either a single value (which applies to both axes) or two values separated by a space (the first for `alignContent`, the second for `justifyContent`). + * A shorthand property for `justify-content` and `align-content`. * * @default 'normal normal' */ @@ -371,31 +417,52 @@ export interface GridProps | `${AlignContentKeyword} ${JustifyContentKeyword}` | AlignContentKeyword; /** - * The spacing between grid rows and columns. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value to apply the same spacing to both axes (for example, `'large-100'`), or a pair of values (for example, `'large-100 large-500'`) to set different spacing for rows and columns. This property also accepts [responsive values](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value applied to both axes, such as `large-100` + * - A pair of values, such as `large-100 large-500`, to set the inline and block axes respectively + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default 'none' */ gap: ResponsiveGridProps['gap']; /** - * The spacing between grid rows. This property overrides the row spacing set by the `gap` property. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value (for example, `'large-100'`), or a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements in the block axis. This overrides the row value of `gap`. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value, such as `large-100` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default '' - meaning no override */ rowGap: ResponsiveGridProps['rowGap']; /** - * The spacing between grid columns. This property overrides the column spacing set by the `gap` property. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value (for example, `'large-100'`), or a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements in the inline axis. This overrides the column value of `gap`. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value, such as `large-100` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default '' - meaning no override */ columnGap: ResponsiveGridProps['columnGap']; /** - * The number of columns and their sizes. You can use [track sizing values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout#fixed_and_flexible_track_sizes) (for example, `'1fr auto'` or `'repeat(3, 1fr)'`) to define the grid structure. This property also accepts [responsive values](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * The columns in the grid and their sizes. + * + * Accepts: + * - [Track sizing values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout#fixed_and_flexible_track_sizes), such as `1fr auto` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported track sizing values as a query value * * @default 'none' */ gridTemplateColumns: ResponsiveGridProps['gridTemplateColumns']; /** - * The number of rows and their sizes. You can use [track sizing values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout#fixed_and_flexible_track_sizes) (for example, `'1fr auto'` or `'repeat(3, 100px)'`) to define the grid structure. This property also accepts [responsive values](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * The rows in the grid and their sizes. + * + * Accepts: + * - [Track sizing values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout#fixed_and_flexible_track_sizes), such as `1fr auto` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported track sizing values as a query value * * @default 'none' */ @@ -403,288 +470,91 @@ export interface GridProps } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { - children?: preact.ComponentChildren; -} - -/** - * 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 & { - /** - * The function that renders the shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An interface representing the properties of an activation event, such as a click or keypress. - * @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 PC) 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. + * The child elements to be rendered within this component. */ - sourceEvent?: ActivationEventEsque; + children?: preact.ComponentChildren; } -/** - * 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); /** @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 base element class for Box components with all Box properties as accessors. - */ -declare class BoxElement extends PreactCustomElement implements BoxProps { +declare class BoxElement extends PolarisCustomElement implements BoxProps { constructor(renderImpl: RenderImpl); - /** - * The ARIA role that defines the semantic meaning of the grid for assistive technologies. - */ accessor accessibilityRole: BoxProps['accessibilityRole']; - /** - * The background color of the grid using the design system's color scale. Choose from `transparent`, `subdued`, `base`, or `strong`. - */ accessor background: BoxProps['background']; - /** - * The height of the grid in horizontal writing modes, or width in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor blockSize: BoxProps['blockSize']; - /** - * The minimum height of the grid in horizontal writing modes, or minimum width in vertical writing modes. - * Prevents the grid from shrinking below this size. - */ accessor minBlockSize: BoxProps['minBlockSize']; - /** - * The maximum height of the grid in horizontal writing modes, or maximum width in vertical writing modes. - * Prevents the grid from growing beyond this size. - */ accessor maxBlockSize: BoxProps['maxBlockSize']; - /** - * The width of the grid in horizontal writing modes, or height in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor inlineSize: BoxProps['inlineSize']; - /** - * The minimum width of the grid in horizontal writing modes, or minimum height in vertical writing modes. - * Prevents the grid from shrinking below this size. - */ accessor minInlineSize: BoxProps['minInlineSize']; - /** - * The maximum width of the grid in horizontal writing modes, or maximum height in vertical writing modes. - * Prevents the grid from growing beyond this size. - */ accessor maxInlineSize: BoxProps['maxInlineSize']; - /** - * Controls how content that exceeds the grid's boundaries is displayed. Use `hidden` to clip overflow or `visible` to allow content to extend beyond boundaries. - */ accessor overflow: BoxProps['overflow']; - /** - * The padding on all sides of the grid. - */ accessor padding: BoxProps['padding']; - /** - * The vertical padding (top and bottom) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingBlock: BoxProps['paddingBlock']; - /** - * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes. - */ accessor paddingBlockStart: BoxProps['paddingBlockStart']; - /** - * The padding at the bottom in horizontal writing modes, or at the end edge in vertical writing modes. - */ accessor paddingBlockEnd: BoxProps['paddingBlockEnd']; - /** - * The horizontal padding (left and right) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingInline: BoxProps['paddingInline']; - /** - * The padding at the left in left-to-right languages, or at the right in right-to-left languages. - */ accessor paddingInlineStart: BoxProps['paddingInlineStart']; - /** - * The padding at the right in left-to-right languages, or at the left in right-to-left languages. - */ accessor paddingInlineEnd: BoxProps['paddingInlineEnd']; - /** - * Applies a border using shorthand syntax to specify width, color, and style in a single property. - */ accessor border: BoxProps['border']; - /** - * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property. - */ accessor borderWidth: BoxProps['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. - */ accessor borderStyle: BoxProps['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. - */ accessor borderColor: BoxProps['borderColor']; - /** - * Controls the roundedness of the element's corners using the design system's radius scale. - */ accessor borderRadius: BoxProps['borderRadius']; - /** - * A text description of the grid for screen readers, used when the visual context isn't sufficient for understanding. - */ accessor accessibilityLabel: BoxProps['accessibilityLabel']; - /** - * Controls the visibility of the grid for both visual and assistive technology users. Use `hidden` to hide from screen readers or `exclusive` to hide visually but announce to screen readers. - */ accessor accessibilityVisibility: BoxProps['accessibilityVisibility']; - /** - * Controls how the grid is displayed in the layout, such as block, inline, or none. - */ accessor display: BoxProps['display']; } /** - * A grid is a layout component that arranges its children in rows and columns with precise control over sizing and alignment. + * Configure the following properties on the grid component. + * @publicDocs */ declare class Grid extends BoxElement implements GridProps { constructor(); - /** - * The template that defines the grid columns. - */ accessor gridTemplateColumns: GridProps['gridTemplateColumns']; - /** - * The template that defines the grid rows. - */ accessor gridTemplateRows: GridProps['gridTemplateRows']; - /** - * The alignment of grid items along the inline axis. - */ accessor justifyItems: GridProps['justifyItems']; - /** - * The alignment of grid items along the block axis. - */ accessor alignItems: GridProps['alignItems']; - /** - * A shorthand for setting both `alignItems` and `justifyItems`. - */ accessor placeItems: GridProps['placeItems']; - /** - * The alignment of the grid along the inline axis. - */ accessor justifyContent: GridProps['justifyContent']; - /** - * The alignment of the grid along the block axis. - */ accessor alignContent: GridProps['alignContent']; - /** - * A shorthand for setting both `alignContent` and `justifyContent`. - */ accessor placeContent: GridProps['placeContent']; - /** - * The spacing between grid rows and columns. - */ accessor gap: GridProps['gap']; - /** - * The spacing between grid rows. - */ accessor rowGap: GridProps['rowGap']; - /** - * The spacing between grid columns. - */ accessor columnGap: GridProps['columnGap']; } declare global { @@ -701,15 +571,11 @@ declare module 'preact' { } declare const tagName = 's-grid'; -/** - * The properties for the grid component when it's used in JSX. - * @publicDocs - */ export interface GridJSXProps extends Partial, Pick { /** - * The child elements to render inside the grid. + * The child elements displayed within the grid component, which are arranged in a flexible grid layout with configurable columns, rows, and spacing. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/GridItem.d.ts b/packages/ui-extensions/src/surfaces/admin/components/GridItem.d.ts index 935472b66c..5dfb3e9cb4 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/GridItem.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/GridItem.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -14,10 +14,45 @@ import type { SizeUnitsOrAuto, SizeUnits, SizeUnitsOrNone, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * A type that allows a value to be responsive using container query syntax. + * 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 | `@container${string}`; @@ -43,12 +78,21 @@ export type MakeResponsivePick = { }; /** - * A version of the box properties with all fields required. + * Represents the box component props with all properties marked as required. * @publicDocs */ export type RequiredBoxProps = Required; /** - * The allowed border radius values for a box component. + * 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< @@ -63,7 +107,12 @@ export type BoxBorderRadii = Extract< | 'large-200' >; /** - * The allowed border style values for a box component. + * 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< @@ -71,7 +120,9 @@ export type BoxBorderStyles = Extract< 'none' | 'solid' | 'dashed' | 'auto' >; /** - * The box properties that support responsive values through container queries. + * Represents box props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveBoxProps = MakeResponsivePick< @@ -106,7 +157,7 @@ export interface BoxProps | 'overflow' > { /** - * The background color of the grid item. + * The background color of the component. * * @default 'transparent' */ @@ -115,16 +166,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. - * - * - `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. + * A border applied using shorthand syntax to specify width, color, and style in a single 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 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 */ @@ -137,7 +185,7 @@ export interface BoxProps > | Extract; /** - * The visual style of the border (solid, dashed, auto, or none). + * 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 */ @@ -145,7 +193,7 @@ export interface BoxProps | MaybeAllValuesShorthandProperty | Extract; /** - * The color of the border using the design system's color scale. + * 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 */ @@ -154,99 +202,85 @@ export interface BoxProps 'subdued' | 'base' | 'strong' | '' >; /** - * The roundedness of the corners using the design system's radius scale. + * The roundedness of the element's corners using the design system's radius scale. * * @default 'none' */ borderRadius: MaybeAllValuesShorthandProperty; /** - * The padding applied to all edges of the grid item. - * - * [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. @@ -255,7 +289,7 @@ export interface BoxProps */ display: ResponsiveBoxProps['display']; /** - * The vertical size of the grid item 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. @@ -266,31 +300,44 @@ 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 grid item. + * 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 grid item. + * 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 grid item. + * 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 grid item. + * 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 grid item. + * 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' */ @@ -298,273 +345,114 @@ export interface BoxProps } /** - * A version of the grid item properties with all fields required. + * Represents the grid item component props with all properties marked as required. * @publicDocs */ export type RequiredGridItemProps = Required; /** - * The properties for the grid item component. A grid item can be positioned within specific rows and columns of a grid, with control over how many rows or columns it spans. - * @publicDocs + * The grid item component represents a single cell within a grid layout, allowing you to control how content is positioned and sized within the grid. Use grid item as a child of grid to specify column span, row span, and positioning for individual content areas. + * + * Grid item supports precise placement control through column and row properties, enabling you to create complex layouts where different items occupy varying amounts of space or appear in specific grid positions. */ export interface GridItemProps extends BoxProps, Required> { /** - * The column position and span of the grid item. You can specify a starting column number, an ending column number, or both (for example, `'1 / 3'` starts at column 1 and ends before column 3, spanning 2 columns). You can also use `'span 2'` to make the item span 2 columns. + * The number of columns the item will span across. + * + * Learn more about the [grid-column property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column). + * + * @default 'auto' */ gridColumn: RequiredGridItemProps['gridColumn']; /** - * The row position and span of the grid item. You can specify a starting row number, an ending row number, or both (for example, `'1 / 3'` starts at row 1 and ends before row 3, spanning 2 rows). You can also use `'span 2'` to make the item span 2 rows. + * The number of rows the item will span across. + * + * Learn more about the [grid-row property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row). + * + * @default 'auto' */ gridRow: RequiredGridItemProps['gridRow']; } -/** - * 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 & { - /** - * The function that renders the shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An interface representing the properties of an activation event, such as a click or keypress. - * @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 PC) 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); /** @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 base element class for Box components with all Box properties as accessors. - */ -declare class BoxElement extends PreactCustomElement implements BoxProps { +declare class BoxElement extends PolarisCustomElement implements BoxProps { constructor(renderImpl: RenderImpl); - /** - * The ARIA role that defines the semantic meaning of the grid item for assistive technologies. - */ accessor accessibilityRole: BoxProps['accessibilityRole']; - /** - * The background color of the grid item using the design system's color scale. Choose from `transparent`, `subdued`, `base`, or `strong`. - */ accessor background: BoxProps['background']; - /** - * The height of the grid item in horizontal writing modes, or width in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor blockSize: BoxProps['blockSize']; - /** - * The minimum height of the grid item in horizontal writing modes, or minimum width in vertical writing modes. - * Prevents the grid item from shrinking below this size. - */ accessor minBlockSize: BoxProps['minBlockSize']; - /** - * The maximum height of the grid item in horizontal writing modes, or maximum width in vertical writing modes. - * Prevents the grid item from growing beyond this size. - */ accessor maxBlockSize: BoxProps['maxBlockSize']; - /** - * The width of the grid item in horizontal writing modes, or height in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor inlineSize: BoxProps['inlineSize']; - /** - * The minimum width of the grid item in horizontal writing modes, or minimum height in vertical writing modes. - * Prevents the grid item from shrinking below this size. - */ accessor minInlineSize: BoxProps['minInlineSize']; - /** - * The maximum width of the grid item in horizontal writing modes, or maximum height in vertical writing modes. - * Prevents the grid item from growing beyond this size. - */ accessor maxInlineSize: BoxProps['maxInlineSize']; - /** - * Controls how content that exceeds the grid item's boundaries is displayed. Use `hidden` to clip overflow or `visible` to allow content to extend beyond boundaries. - */ accessor overflow: BoxProps['overflow']; - /** - * The spacing applied inside the grid item on all sides, creating distance between the item's edges and its content. - */ accessor padding: BoxProps['padding']; - /** - * The vertical padding (top and bottom) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingBlock: BoxProps['paddingBlock']; - /** - * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes. - */ accessor paddingBlockStart: BoxProps['paddingBlockStart']; - /** - * The padding at the bottom in horizontal writing modes, or at the end edge in vertical writing modes. - */ accessor paddingBlockEnd: BoxProps['paddingBlockEnd']; - /** - * The horizontal padding (left and right) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingInline: BoxProps['paddingInline']; - /** - * The padding at the left in left-to-right languages, or at the right in right-to-left languages. - */ accessor paddingInlineStart: BoxProps['paddingInlineStart']; - /** - * The padding at the right in left-to-right languages, or at the left in right-to-left languages. - */ accessor paddingInlineEnd: BoxProps['paddingInlineEnd']; - /** - * Applies a border using shorthand syntax to specify width, color, and style in a single property. - */ accessor border: BoxProps['border']; - /** - * The width of the border. - */ accessor borderWidth: BoxProps['borderWidth']; - /** - * The style of the border. - */ accessor borderStyle: BoxProps['borderStyle']; - /** - * The color of the border. - */ accessor borderColor: BoxProps['borderColor']; - /** - * The radius of the border corners. - */ accessor borderRadius: BoxProps['borderRadius']; - /** - * A text description of the grid item for screen readers, used when the visual context isn't sufficient for understanding. - */ accessor accessibilityLabel: BoxProps['accessibilityLabel']; - /** - * Controls the visibility of the grid item for both visual and assistive technology users. Use `hidden` to hide from screen readers or `exclusive` to hide visually but announce to screen readers. - */ accessor accessibilityVisibility: BoxProps['accessibilityVisibility']; - /** - * Controls how the grid item is displayed in the layout, such as block, inline, or none. - */ accessor display: BoxProps['display']; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A grid item is a child of a grid that can be positioned within specific rows and columns. + * The grid item component represents a single cell within a grid layout, allowing you to control how content is positioned and sized within the grid. Use grid item as a child of grid to specify column span, row span, and positioning for individual content areas. + * + * Grid item supports precise placement control through column and row properties, enabling you to create complex layouts where different items occupy varying amounts of space or appear in specific grid positions. + * @publicDocs */ declare class GridItem extends BoxElement implements GridItemProps { - /** - * The column position and span of the grid item. - */ accessor gridColumn: GridItemProps['gridColumn']; - /** - * The row position and span of the grid item. - */ accessor gridRow: GridItemProps['gridRow']; constructor(); } @@ -583,15 +471,11 @@ declare module 'preact' { } declare const tagName = 's-grid-item'; -/** - * The properties for the grid item component when it's used in JSX. - * @publicDocs - */ export interface GridItemJSXProps extends Partial, Pick { /** - * The child elements to render inside the grid item. + * The content displayed within the grid item component, which represents a single cell in the grid layout and can span multiple columns or rows. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Heading.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Heading.d.ts index f013a2971d..6a552a0e0a 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Heading.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Heading.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,11 +6,60 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, HeadingProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + HeadingProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare const headingFontSizes: readonly [ + 'auto', + 'small', + 'base', + 'large', + 'large-100', + 'large-200', + 'large-300', + 'large-400', +]; +export type HeadingFontSize = (typeof headingFontSizes)[number]; /** - * The properties for the heading component. These properties define hierarchical section titles and headings with appropriate semantic meaning and visual hierarchy. - * @publicDocs + * Configure the following properties on the heading component. */ export interface HeadingProps extends Required< @@ -18,146 +67,101 @@ export interface HeadingProps HeadingProps$1, 'accessibilityRole' | 'accessibilityVisibility' | 'lineClamp' > - > {} - -/** - * A string containing CSS styles. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow DOM. - */ - styles?: Styles; -}; -/** - * An object that represents the state of modifier keys and mouse button - * during an activation event like a click. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the meta (Command on Mac, Windows key on PC) key was pressed. - */ - 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; -} -/** - * Options for customizing click behavior on an element. - * @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; -} -/** - * 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 + * The font size of the heading. The named values also apply their matching + * line-height and letter-spacing: + * + * - 'small' maps to headingXs + * - 'base' maps to headingSm + * - 'large' / 'large-100' maps to headingMd + * - 'large-200' maps to headingLg + * - 'large-300' maps to headingXl + * - 'large-400' maps to heading2xl + * + * @default 'auto' */ - queueRender(): void; + fontSize: HeadingFontSize; /** - * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`. + * The semantic meaning of the component’s content. When set, + * the role will be used by assistive technologies to help users + * navigate the page. * - * 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 + * - `heading`: Identifies the element as a heading for assistive technologies. + * - `none`: Removes semantic meaning from the heading element. + * - `presentation`: Removes semantic meaning from the heading element. + * + * @default 'heading' + * + * @implementation The `heading` role doesn't need to be applied if + * the host applies it for you; for example, an HTML host rendering + * an `

` element should not apply the `heading` role. */ - click({sourceEvent}?: ClickOptions): void; + accessibilityRole: Required['accessibilityRole']; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** - * A custom element for displaying hierarchical section titles and headings with appropriate semantic meaning and visual styling. Use Heading to structure your content with proper heading levels for both visual hierarchy and accessibility. - */ -declare class Heading extends PreactCustomElement implements HeadingProps { - /** - * The ARIA role for the heading. Set to `'heading'` (the default) for standard heading semantics, or `'presentation'` / `'none'` to remove heading semantics for decorative use. - */ +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +declare abstract class HeadingBase + extends PolarisCustomElement + implements + Pick< + HeadingProps, + 'accessibilityRole' | 'accessibilityVisibility' | 'fontSize' | 'lineClamp' + > +{ + accessor fontSize: HeadingProps['fontSize']; accessor accessibilityRole: HeadingProps['accessibilityRole']; - /** - * The maximum number of lines to display before the text is truncated with an ellipsis. - */ accessor lineClamp: HeadingProps['lineClamp']; - /** - * The visibility of the element to assistive technologies. - */ accessor accessibilityVisibility: HeadingProps['accessibilityVisibility']; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the heading component. + * @publicDocs + */ +declare class Heading extends HeadingBase implements HeadingProps { constructor(); } declare global { @@ -174,15 +178,11 @@ declare module 'preact' { } declare const tagName = 's-heading'; -/** - * The JSX properties for the heading component. These properties define how a heading is rendered in Preact or JSX. - * @publicDocs - */ export interface HeadingJSXProps extends Partial, Pick { /** - * The content of the heading. + * The heading text displayed within the heading component, which provides a title or section header for content. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Icon.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Icon.d.ts index 0169812a82..ab2f0bbdd4 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Icon.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Icon.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,19 +6,71 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {IconProps$1, IconType, ComponentChildren} from './shared.d.ts'; +import type { + IconProps$1, + IconType, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * Configure the following properties on the icon component. + */ export interface IconProps - extends Pick< - IconProps$1, - 'type' | 'tone' | 'color' | 'size' | 'interestFor' + extends Required< + Pick > { /** - * The type of icon that will be displayed. You can specify an icon name from the available icon set, or use an empty string to show no icon. + * The icon to display from the icon library. + * + * Set to a valid icon name to display that icon. To hide the icon completely, + * use an empty string `''`. To reserve the icon's space without displaying an icon, + * use `'empty'`. */ type: '' | IconType | 'empty'; /** - * The color tone of the icon based on its semantic meaning. Choose from `'auto'` to let the icon inherit its context, `'neutral'` for standard icons, `'info'` for informational content, `'success'` for positive actions, `'caution'` or `'warning'` for warnings, or `'critical'` for errors. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `caution`: Advisory notices that need attention. * * @default 'auto' */ @@ -27,159 +79,73 @@ export interface IconProps 'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical' >; /** - * The color emphasis of the icon. Use `'base'` for the standard color intensity, or `'subdued'` for a lighter, less prominent appearance. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. * * @default 'base' */ color: Extract; /** - * The size of the icon. Use `'small'` for compact layouts, or `'base'` for standard sizing. + * The size of the icon. * - * @default 'base' + * - `small`: Smaller icon suitable for inline use within text or compact UI elements. + * - `base`: Default size that works well for standalone icons and standard use cases. */ size: Extract; } -/** - * A string containing CSS styles for the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with Preact. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * 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 activation. - */ - shiftKey: boolean; - /** - * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during activation. - */ - metaKey: boolean; - /** - * Whether the control key was pressed during activation. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during activation. - */ - button: number; -} -/** - * The options for customizing synthetic click behavior. - * @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); /** @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; +} + +declare abstract class IconBase + extends PolarisCustomElement + implements Pick +{ + accessor color: IconProps['color']; + accessor size: IconProps['size']; + accessor interestFor: IconProps['interestFor']; + abstract tone: string; + abstract type: string; + constructor(renderImpl: RenderImpl); } /** - * 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 { /** - * 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; /** - * 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; } /** - * An icon displays a graphical symbol from the icon library. + * Configure the following properties on the icon component. + * @publicDocs */ -declare class Icon extends PreactCustomElement implements IconProps { - /** - * The color emphasis of the icon. - */ - accessor color: IconProps['color']; - /** - * The color tone of the icon based on its semantic meaning. - */ +declare class Icon extends IconBase implements IconProps { accessor tone: IconProps['tone']; - /** - * The type of icon to display. - */ accessor type: IconProps['type']; - /** - * The size of the icon. - */ - accessor size: IconProps['size']; - /** - * The element that this icon should show interest for when activated. - */ - accessor interestFor: string; constructor(); } declare global { @@ -196,10 +162,6 @@ declare module 'preact' { } declare const tagName = 's-icon'; -/** - * The properties for the icon component when it's used in JSX. - * @publicDocs - */ export interface IconJSXProps extends Partial, Pick {} diff --git a/packages/ui-extensions/src/surfaces/admin/components/Image.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Image.d.ts index 638f688c5e..aed8f39d17 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Image.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Image.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -13,21 +13,30 @@ import type { SizeUnitsOrAuto, SizeUnits, SizeUnitsOrNone, - ComponentChildren, + 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. This type provides access to the element that triggered the event. + * 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 = 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 = @@ -36,26 +45,61 @@ export type CallbackEventListener = }) | 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 { /** - * 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; /** - * 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; } +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 value responsive by allowing container query strings. + * 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 | `@container${string}`; @@ -81,12 +125,21 @@ export type MakeResponsivePick = { }; /** - * The box properties with all fields marked as required. + * Represents the box component props with all properties marked as required. * @publicDocs */ export type RequiredBoxProps = Required; /** - * The available border radius values for Box components. + * 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< @@ -101,7 +154,12 @@ export type BoxBorderRadii = Extract< | 'large-200' >; /** - * The available border style values for Box components. + * 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< @@ -109,7 +167,9 @@ export type BoxBorderStyles = Extract< 'none' | 'solid' | 'dashed' | 'auto' >; /** - * The box properties that support responsive values through container queries. + * Represents box props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveBoxProps = MakeResponsivePick< @@ -144,7 +204,7 @@ export interface BoxProps | 'overflow' > { /** - * The background color of the image container. + * The background color of the component. * * @default 'transparent' */ @@ -153,16 +213,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 */ @@ -175,7 +232,7 @@ export interface BoxProps > | Extract; /** - * The visual style of the border (solid, dashed, auto, or none). + * 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 */ @@ -183,7 +240,7 @@ export interface BoxProps | MaybeAllValuesShorthandProperty | Extract; /** - * The color of the border using the design system's color scale. + * 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 */ @@ -192,99 +249,85 @@ export interface BoxProps 'subdued' | 'base' | 'strong' | '' >; /** - * The roundedness of the corners using the design system's radius scale. + * The roundedness of the element's corners using the design system's radius scale. * * @default 'none' */ borderRadius: MaybeAllValuesShorthandProperty; /** - * The padding applied to all edges of the image container. - * - * [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. @@ -293,7 +336,7 @@ export interface BoxProps */ display: ResponsiveBoxProps['display']; /** - * The vertical size of the image 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. @@ -304,31 +347,44 @@ 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 image. + * 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 image. + * 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 image. + * 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 image. + * 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 image. + * 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' */ @@ -336,8 +392,7 @@ export interface BoxProps } /** - * The properties for the image component. An image displays pictures with configurable sizing, loading behavior, and borders. Properties include `src` for the image URL, `alt` for accessibility text, `aspectRatio` for sizing, `loading` for lazy loading, and border styling options. - * @publicDocs + * Configure the following properties on the image component. */ export interface ImageProps extends Required< @@ -365,227 +420,141 @@ export interface ImageProps > > { /** - * The URL of the image to display. You can provide an absolute or relative URL pointing to the image file. - */ - src: ImageProps$1['src']; - /** - * A set of source images with different sizes for responsive loading. Use this to provide multiple image sizes for different screen resolutions (for example, `'image-320w.jpg 320w, image-640w.jpg 640w'`). - */ - srcSet: ImageProps$1['srcSet']; - /** - * The sizes of the image at different viewport widths. Use this with `srcSet` to tell the browser which image to load (for example, `'(max-width: 320px) 280px, 640px'`). - */ - sizes: ImageProps$1['sizes']; - /** - * 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: ImageProps$1['alt']; - /** - * The aspect ratio of the image as a width-to-height ratio (for example, `'16/9'` or `'1'`). This helps prevent layout shifts while the image loads. - */ - aspectRatio: ImageProps$1['aspectRatio']; - /** - * How the image should be resized to fit its container. Choose `'cover'` to fill the container while maintaining aspect ratio (cropping if needed), or `'contain'` to fit the entire image within the container. - */ - objectFit: ImageProps$1['objectFit']; - /** - * When the image should be loaded. Use `'lazy'` to defer loading until the image is near the viewport, or `'eager'` to load immediately. - */ - loading: ImageProps$1['loading']; - /** - * The accessibility role for the image. Set this to provide semantic meaning for screen readers. - */ - accessibilityRole: ImageProps$1['accessibilityRole']; - /** - * The inline size (width in horizontal writing modes) of the image. You can use size units like `'100px'` or `'50%'`. - */ - inlineSize: ImageProps$1['inlineSize']; - /** - * Whether to show a border around the image. Set to `true` to display a border, or `false` to hide it. - */ - border: BoxProps['border']; - /** - * The width of the border around the image. You can use a single value to apply the same width to all sides, or use the 1-to-4-value syntax to control individual sides. - */ - borderWidth: BoxProps['borderWidth']; - /** - * The style of the border around the image. You can use a single value to apply the same style to all sides, or use the 1-to-4-value syntax to control individual sides. - */ - borderStyle: BoxProps['borderStyle']; - /** - * The color of the border around the image. Choose from `'subdued'`, `'base'`, or `'strong'` to control the visual emphasis. - */ - borderColor: BoxProps['borderColor']; - /** - * The radius of the border corners around the image. You can use a single value to apply the same radius to all corners, or use the 1-to-4-value syntax to control individual corners. - */ - borderRadius: BoxProps['borderRadius']; -} - -/** - * 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 & { - /** - * 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. + * The loading strategy for the image. + * + * - `eager`: Immediately loads the image, irrespective of its position within the visible viewport. + * - `lazy`: Delays loading the image until it approaches a specified distance from the viewport. + * + * Learn more about the [loading attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading). + * + * @default 'eager' */ - shiftKey: boolean; + loading: Required['loading']; /** - * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during the event. + * The semantic meaning of the component’s content. When set, + * the role will be used by assistive technologies to help users + * navigate the page. + * + * - `none`: Completely hides the element and its content from assistive technologies + * - `presentation`: Removes semantic meaning, making the image purely decorative and ignored by screen readers. + * - `img`: Identifies the element as an image that conveys meaningful information to users. + * + * @default 'img' + * + * @implementation The `img` role doesn't need to be applied if + * the host applies it for you; for example, an HTML host rendering + * an `` element should not apply the `img` role. */ - metaKey: boolean; + accessibilityRole: Required['accessibilityRole']; /** - * Whether the control key was pressed during the event. + * The displayed inline width of the image. + * + * - `fill`: the image will take up 100% of the available inline size. + * - `auto`: the image will be displayed at its natural size. + * + * Learn more about the [width attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width). + * + * @default 'fill' */ - ctrlKey: boolean; + inlineSize: Required['inlineSize']; /** - * The mouse button that was pressed (0 for left, 1 for middle, 2 for right). + * The aspect ratio of the image. + * + * The rendering of the image will depend on the `inlineSize` value: + * + * - `inlineSize="fill"`: the aspect ratio will be respected and the image will take the necessary space. + * - `inlineSize="auto"`: the image will not render until it has loaded and the aspect ratio will be ignored. + * + * For example, if the value is set as `50 / 100`, the getter returns `50 / 100`. + * If the value is set as `0.5`, the getter returns `0.5 / 1`. + * + * Learn more about the [aspect-ratio property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio). + * + * @default '1/1' */ - button: number; -} -/** - * The options for triggering a synthetic click event. - * @publicDocs - */ -export interface ClickOptions { + aspectRatio: Required['aspectRatio']; /** - * 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. + * The image resizing behavior to fit within its container. + * + * - `contain`: Scales the image to fit within the container while maintaining its aspect ratio. The entire image is visible, but might leave empty space. + * - `cover`: Scales the image to fill the entire container while maintaining its aspect ratio. The image might be cropped to fit. + * + * The image is always positioned in the center of the container. + * + * Learn more about the [object-fit property](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit). + * + * @default 'contain' */ - sourceEvent?: ActivationEventEsque; + objectFit: Required['objectFit']; } -/** - * 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); /** @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; } /** - * An image displays pictures with configurable sizing, loading behavior, and borders. + * Configure the following properties on the image component. + * @publicDocs */ -declare class Image extends PreactCustomElement implements ImageProps { +declare class Image extends PolarisCustomElement implements ImageProps { /** - * The URL of the image to display. + * 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: ImageProps['src']; /** - * A set of source images with different sizes for responsive loading. + * A set of image sources and their width or pixel density descriptors. This overrides the `src` property. + * + * Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). */ accessor srcSet: ImageProps['srcSet']; /** - * The sizes of the image at different viewport widths. + * A set of media conditions and their corresponding sizes. + * + * Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes). */ accessor sizes: ImageProps['sizes']; /** - * 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: ImageProps['alt']; - /** - * The aspect ratio of the image as a width-to-height ratio. - */ accessor aspectRatio: ImageProps['aspectRatio']; - /** - * How the image should be resized to fit its container. - */ accessor objectFit: ImageProps['objectFit']; - /** - * When the image should be loaded. - */ accessor loading: ImageProps['loading']; - /** - * The accessibility role for the image. - */ accessor accessibilityRole: ImageProps['accessibilityRole']; - /** - * The inline size (width in horizontal writing modes) of the image. - */ accessor inlineSize: ImageProps['inlineSize']; /** - * Whether to show a border around the image. + * A border applied around the image using shorthand syntax to specify width, color, and style in a single property. */ accessor border: ImageProps['border']; /** - * The width of the border around the image. + * The thickness of the border around the image. When set, this overrides the width value specified in the `border` property. */ accessor borderWidth: ImageProps['borderWidth']; /** - * The style of the border around the image. + * The visual style of the border around the image, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property. */ accessor borderStyle: ImageProps['borderStyle']; /** - * The color of the border around the image. + * The color of the border around the image using the design system's color scale. When set, this overrides the color value specified in the `border` property. */ accessor borderColor: ImageProps['borderColor']; /** - * The radius of the border corners around the image. + * The roundedness of the image's corners using the design system's radius scale. */ accessor borderRadius: ImageProps['borderRadius']; - /** - * A callback that's fired when the image has loaded successfully. - */ accessor onload: CallbackEventListener | null; - /** - * A callback that's fired when the image fails to load. - */ accessor onerror: OnErrorEventHandler; constructor(); } @@ -603,19 +572,15 @@ declare module 'preact' { } declare const tagName = 's-image'; -/** - * The properties for the image component when it's used in JSX. - * @publicDocs - */ export interface ImageJSXProps extends Partial, Pick { /** - * A callback that's fired when the image fails to load. + * A callback fired when the image fails to load. */ onError?: ((event: CallbackEvent) => void) | null; /** - * A callback that's fired when the image has loaded successfully. + * A callback fired when the image loads successfully. */ onLoad?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Link.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Link.d.ts index d2d2d883c8..dd9ae98374 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Link.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Link.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,45 +10,111 @@ import type { ComponentChildren, LinkProps$1, InteractionProps, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +/** + * 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 = 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 = | (EventListener & { (event: CallbackEvent): 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** * @publicDocs + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * Represents the link component props with all properties marked as required. + * @publicDocs */ export type RequiredLinkProps = Required; +/** + * Represents the base link props with all core properties marked as required. + * @publicDocs + */ export type LinkBaseProps = Required< Pick< LinkProps$1, @@ -64,95 +130,46 @@ export type LinkBaseProps = Required< > >; /** - * The properties for the link component. These properties define a clickable link that navigates users to different pages or sections with customizable visual styles and semantic meaning. - * @publicDocs + * Configure the following properties on the link component. */ export interface LinkProps extends LinkBaseProps { /** - * The visual appearance and semantic meaning of the link. Links rely on the tone system for semantic meaning, so using custom styling might not clearly convey intent to merchants. Available options: - * - `'auto'` - The system automatically chooses the appropriate tone based on context. - * - `'neutral'` - Standard styling for general navigation without specific semantic meaning. - * - `'critical'` - Red styling for links that lead to destructive actions or important warnings. + * The semantic meaning and color treatment of the component. + * + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. * * @default 'auto' */ tone: Extract; -} -/** * @publicDocs - */ -export type Styles = string; -export type RenderImpl = Omit & { - ShadowRoot: (element: any) => ComponentChildren; - styles?: Styles; -}; -export interface ActivationEventEsque { - shiftKey: boolean; - metaKey: boolean; - ctrlKey: boolean; - button: number; -} -/** * - * @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. + * 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. + */ + accessibilityLabel: Required['accessibilityLabel']; + /** + * 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). */ - sourceEvent?: ActivationEventEsque; + lang: Required['lang']; } -/** - * 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); /** @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 { /** - * 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' */ @@ -161,27 +178,48 @@ export interface PreactOverlayControlProps '--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 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; /** - * Sets the element 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; } -declare const Link_base: (abstract new ( - args_0: RenderImpl, -) => PreactCustomElement & PreactOverlayControlProps) & - Pick; -declare class Link extends Link_base implements LinkProps { - accessor tone: LinkProps['tone']; +declare const LinkBase_base: (abstract new ( + renderImpl: Omit, +) => PolarisCustomElement & PreactOverlayControlProps) & + Pick; +declare abstract class LinkBase + extends LinkBase_base + implements + Pick< + LinkProps, + | 'accessibilityLabel' + | 'interestFor' + | 'href' + | 'target' + | 'download' + | 'lang' + > +{ accessor accessibilityLabel: LinkProps['accessibilityLabel']; accessor href: LinkProps['href']; accessor target: LinkProps['target']; accessor download: LinkProps['download']; accessor lang: LinkProps['lang']; - accessor onclick: CallbackEventListener | null; + accessor onclick: CallbackEventListener | null; + abstract tone: string; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the link component. + * @publicDocs + */ +declare class Link extends LinkBase implements LinkProps { + accessor tone: LinkProps['tone']; constructor(); } declare global { @@ -198,56 +236,17 @@ declare module 'preact' { } declare const tagName = 's-link'; -/** - * The JSX properties for the link component. These properties define how a link is rendered in Preact or JSX. - * @publicDocs - */ export interface LinkJSXProps extends Partial, Pick { /** - * The text or content to display inside the link. This typically describes the destination or action the link performs. + * The text or elements displayed within the link component, which navigates users to a different location when activated. */ children?: ComponentChildren; /** - * A callback function that's invoked when the link is clicked. It receives the click event as an argument. + * A callback fired when the link is clicked. */ onClick?: ((event: CallbackEvent) => 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; - /** - * The URL that the link navigates to when clicked. This is the primary property that defines where the link leads. - * - * @default '' - */ - href?: LinkProps['href']; - /** - * Where to open the linked document. 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?: LinkProps['target']; - /** - * The filename to save the linked URL as when downloaded. When provided, clicking the link will download the resource instead of navigating to it. - * - * @default '' - */ - download?: LinkProps['download']; - /** - * The language of the link's content, specified as a BCP 47 language tag (such as `'en'` or `'fr'`). This helps assistive technologies pronounce content correctly. - * - * @default '' - */ - lang?: string; } export {Link}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/ListItem.d.ts b/packages/ui-extensions/src/surfaces/admin/components/ListItem.d.ts index 97aa9cec52..ed72a75bfa 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/ListItem.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/ListItem.d.ts @@ -1,146 +1,111 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, ListItemProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + ListItemProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * The properties that you can set on a list item component. - * @publicDocs - */ -export interface ListItemProps extends ListItemProps$1 {} - -/** - * A string that contains CSS styles. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the shadow DOM. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An object that represents the state of modifier keys and mouse button - * during an activation event like a click. - * @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). - */ - button: number; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } + /** - * The options for customizing how a synthetic click is performed. - * @publicDocs + * The list item component represents a single entry within an ordered list or unordered list. Use list item to structure individual points, steps, or items within a list, with each item automatically receiving appropriate list markers (bullets or numbers) from its parent list. + * + * List item must be used as a direct child of ordered list or unordered list components. Each list item can contain text, inline formatting, or other components to create rich list content. */ -export interface ClickOptions { +export interface ListItemProps extends ListItemProps$1 { /** - * 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. + * The content displayed within the list item, which represents a single entry in an ordered or unordered list. */ - sourceEvent?: ActivationEventEsque; + children?: ListItemProps$1['children']; } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A component that represents a single item within an ordered list or unordered list. + * The list item component represents a single entry within an ordered list or unordered list. Use list item to structure individual points, steps, or items within a list, with each item automatically receiving appropriate list markers (bullets or numbers) from its parent list. * - * Use list item as a child of ordered list or unordered list to create properly structured and accessible list content. + * List item must be used as a direct child of ordered list or unordered list components. Each list item can contain text, inline formatting, or other components to create rich list content. + * @publicDocs */ -declare class ListItem extends PreactCustomElement implements ListItemProps { +declare class ListItem extends PolarisCustomElement implements ListItemProps { constructor(); } declare global { @@ -158,15 +123,11 @@ declare module 'preact' { } declare const tagName = 's-list-item'; -/** - * The JSX properties you can set on a list item component. - * @publicDocs - */ export interface ListItemJSXProps extends Partial, Pick { /** - * The content to display inside the list item. + * The content displayed within the list item, which represents a single entry in an ordered or unordered list. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Menu.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Menu.d.ts index c712bf293b..aae3ad963a 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Menu.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Menu.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,152 +9,106 @@ import type { ComponentChildren, MenuProps$1, + PreactCustomElement, + RenderImpl, InteractionProps, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 menu component. - * @publicDocs + * Configure the following properties on the menu component. */ export interface MenuProps - extends Required> {} + extends Required> { + /** + * 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. + */ + accessibilityLabel: Required['accessibilityLabel']; +} /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { - 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 & { - /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; /** - * The CSS styles to apply to the component. + * The child elements to be rendered within this 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). - */ - 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); /** @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 { /** - * 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' */ @@ -163,11 +117,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; /** - * 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; } @@ -175,43 +129,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 { @@ -219,15 +167,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; @@ -236,16 +180,11 @@ declare class PreactOverlayElement extends PreactCustomElement { } /** - * A component that displays a contextual list of actions or options, which is typically triggered by a button or other activator element. + * Configure the following properties on the menu component. + * @publicDocs */ declare class Menu extends PreactOverlayElement implements MenuProps { - /** - * A label that describes the menu for assistive technologies. - */ accessor accessibilityLabel: string; - /** - * Creates a new Menu instance. - */ constructor(); /** @private */ connectedCallback(): void; @@ -265,19 +204,12 @@ declare module 'preact' { } } -/** - * The custom element tag name for the menu component. - */ declare const tagName = 's-menu'; -/** - * The JSX properties you can set on a menu component. - * @publicDocs - */ export interface MenuJSXProps extends Partial, Pick { /** - * The menu items to display, which should include button and section components. + * The items displayed within the menu. Only accepts button and section components. Use button for individual menu actions and section to group related items. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Modal.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Modal.d.ts index df93219efe..11ee2c4e8b 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Modal.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Modal.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.38.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -13,34 +13,107 @@ import type { RenderImpl, InteractionProps, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +/** + * 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 = 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 = | (EventListener & { (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs +/** + * 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 { - /** Assigns a unique key to this element. */ + /** + * 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; - /** Assigns a ref (generally from `useRef()`) to this element. */ + /** + * 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; - /** Assigns this element to a parent's slot. */ + /** + * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** * @publicDocs + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * Represents the modal component props with all properties marked as required. + * @publicDocs */ export type RequiredAlignedModalProps = Required; +/** + * Configure the following properties on the modal component. + */ export interface ModalProps extends Pick< RequiredAlignedModalProps, @@ -53,30 +126,56 @@ export interface ModalProps | 'toggleOverlay' > { /** - * Adjust the size of the Modal. + * The size of the modal component, controlling its width and height. Larger sizes provide more space for content while smaller sizes are more compact. */ size: Extract< ModalProps$1['size'], 'small-100' | 'small' | 'base' | 'large' | 'large-100' >; + /** + * A title that describes the content of the modal. + * + */ + heading: RequiredAlignedModalProps['heading']; + /** + * A label that describes the purpose of the modal. When set, + * it will be announced to users using assistive technologies and will + * provide them with more context. + * + * This overrides the `heading` prop for screen readers. + */ + accessibilityLabel: RequiredAlignedModalProps['accessibilityLabel']; + /** + * Adjust the padding around the modal content. + * + * `base`: applies padding that is appropriate for the element. + * + * `none`: removes all padding from the element. This can be useful when elements inside the modal need to span + * to the edge of the modal. For example, a full-width image. In this case, rely on box with a padding of 'base' + * to bring back the desired padding for the rest of the content. + * + * @default 'base' + */ + padding: RequiredAlignedModalProps['padding']; } declare class PolarisCustomElement extends PreactCustomElement { constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; } -/** * @publicDocs - */ + export interface PreactOverlayControlProps extends Pick { /** - * 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. + * 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' */ @@ -85,11 +184,11 @@ export interface PreactOverlayControlProps '--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. + * 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; /** - * 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. + * 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; } @@ -108,11 +207,19 @@ declare const overlayHidden: unique symbol; */ declare const overlayActivator: unique symbol; declare const overlayHideFrameId: unique symbol; +/** + * 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 & { source: HTMLElement | null | undefined; command: PreactOverlayControlProps['command']; rootActivator?: HTMLElement | null; }; +/** + * Represents a polyfill command event for overlay controls. Used in environments where native command events are not available. + * @publicDocs + */ export type PolyfillCommandEvent = Event & { source: PolyfillCommandEventInit['source']; command: PolyfillCommandEventInit['command']; @@ -130,6 +237,8 @@ declare global { declare class PreactOverlayElement extends PolarisCustomElement { constructor(renderImpl: RenderImpl); /** @private */ + disconnectedCallback(): void; + /** @private */ [overlayHidden]: boolean; /** @private */ [overlayActivator]: HTMLElement | null | undefined; @@ -148,11 +257,19 @@ declare const focusedElement: unique symbol; declare const rootActivator: unique symbol; declare const onEscape: unique symbol; declare const nestedModals: unique symbol; +declare const onKeyUp: unique symbol; +declare const onBackdropMouseDown: unique symbol; +declare const onBackdropMouseUp: unique symbol; declare const onBackdropClick: unique symbol; +declare const backdropMouseDownOnDialog: unique symbol; +declare const backdropMouseUpOnDialog: unique symbol; declare const abortController: unique symbol; declare const onChildModalChange: unique symbol; declare const childrenRerenderObserver: unique symbol; declare const shadowDomRerenderObserver: unique symbol; +declare const focusTrapController: unique symbol; +declare const escapeKeyUpController: unique symbol; +declare const ensureDialogRef: unique symbol; declare abstract class ModalBase extends PreactOverlayElement implements @@ -162,9 +279,25 @@ declare abstract class ModalBase accessor heading: ModalProps['heading']; accessor padding: ModalProps['padding']; accessor size: ModalProps['size']; + /** + * A callback fired when the modal closes. + * Use to perform cleanup or trigger side effects when the modal is dismissed. + */ accessor onhide: CallbackEventListener | null; + /** + * A callback fired when the modal starts to open, before any entrance animation begins. + * Use to prepare content or fetch data needed for the modal. + */ accessor onshow: CallbackEventListener | null; + /** + * A callback fired after the modal has fully closed and any exit animation completes. + * Use to reset form state, clear temporary data, or update the page after dismissal. + */ accessor onafterhide: CallbackEventListener | null; + /** + * A callback fired after the modal has fully opened and any entrance animation completes. + * Use to focus an input field or initialize content once the modal is visible. + */ accessor onaftershow: CallbackEventListener | null; /** @private */ [abortController]: AbortController; @@ -175,17 +308,74 @@ declare abstract class ModalBase /** @private */ [rootActivator]: HTMLElement | null; /** @private */ - [nestedModals]: Map, boolean>; + [nestedModals]: Map; /** @private */ [childrenRerenderObserver]: MutationObserver; /** @private */ [shadowDomRerenderObserver]: MutationObserver; + /** + * Focus trap keydown handler reference, stored for cleanup. + * + * The focus trap is managed imperatively here in ModalBase rather than + * via a Preact useEffect in foundation.tsx. This is because aftershow + * (fired after CSS animations complete) and useEffect (fired after + * Preact's async effect scheduling) are independent async chains with + * no synchronization — the useEffect could run before or after + * aftershow, making tests non-deterministic. + * + * By attaching the focus trap in the same .then() chain as aftershow, + * we guarantee it is active before aftershow dispatches. + * + * Lifecycle (mirrors the old useEffect's isActiveModal dependency): + * - Attached: in aftershow chain, right before aftershow dispatches + * - Detached: on dismiss(), disconnectedCallback(), or child modal open + * - Re-attached: when all child modals close + * @private + */ + [focusTrapController]: AbortController | null; + /** + * Holds the in-flight document keyup suppressor below so a second Escape + * close replaces it instead of stacking another one. + * @private + */ + [escapeKeyUpController]: AbortController | null; /** @private */ [onEscape]: (event: KeyboardEvent) => void; /** @private */ + [onKeyUp]: (event: KeyboardEvent) => void; + /** + * Whether the most recent mousedown / mouseup on the dialog landed on the + * backdrop area (the `` element itself, outside its content box) + * rather than inside the modal content. + * + * Used by [onBackdropClick] to distinguish a true backdrop click from a + * `click` event whose target is the dialog only because the user dragged + * across the content/backdrop boundary. Reset on every backdrop + * interaction (or when no click follows). + * @private + */ + [backdropMouseDownOnDialog]: boolean; + /** @private */ + [backdropMouseUpOnDialog]: boolean; + /** @private */ + [onBackdropMouseDown]: (event: MouseEvent) => void; + /** @private */ + [onBackdropMouseUp]: (event: MouseEvent) => void; + /** @private */ [onBackdropClick]: (event: MouseEvent) => void; /** @private */ [onChildModalChange]: EventListenerOrEventListenerObject; + /** + * Ensures `this[dialog]` is set by synchronously querying the shadow DOM + * and attaching event listeners if needed. + * Works around a Safari timing issue where the MutationObserver callback + * (which normally sets `this[dialog]`) may not have fired yet when + * `show()` / `dismiss()` run — especially when `heading` or + * `accessibilityLabel` adds child custom-elements whose own lifecycle + * microtasks can delay the observer. + * @private + */ + [ensureDialogRef](): void; /** @private */ get [isOpen](): boolean; /** @private */ @@ -203,9 +393,13 @@ declare abstract class ModalBase connectedCallback(): void; /** @private */ disconnectedCallback(): void; - constructor(renderImpl: RenderImpl, tagName: string); + constructor(renderImpl: RenderImpl); } +/** + * Configure the following properties on the modal component. + * @publicDocs + */ declare class Modal extends ModalBase implements ModalProps { constructor(); } @@ -228,24 +422,36 @@ export interface ModalJSXProps extends Partial, Pick { /** - * The content of the Modal. + * The content displayed within the modal component, typically including form fields, information, or interactive elements. */ children?: ComponentChildren; /** - * The primary action to perform. + * The main action button displayed in the modal footer, representing the primary action users should take. * - * Only a `Button` with a variant of `primary` is allowed. + * Only accepts a single button component with a `variant` of `primary`. This action should align with the modal's main purpose. */ primaryAction?: ComponentChildren; /** - * The secondary actions to perform. + * Additional action buttons displayed in the modal footer, providing alternative or supporting actions. * - * Only `Button` elements with a variant of `secondary` or `auto` are allowed. + * Only accepts button components with a `variant` of `secondary` or `auto`. These are visually de-emphasized to establish clear hierarchy. */ secondaryActions?: ComponentChildren; + /** + * A callback fired immediately when the modal starts to hide. + */ onHide?: ((event: CallbackEvent) => void) | null; + /** + * A callback fired immediately when the modal starts to show. + */ onShow?: ((event: CallbackEvent) => void) | null; + /** + * A callback fired when the modal is completely hidden, after any hide animations have completed. + */ onAfterHide?: ((event: CallbackEvent) => void) | null; + /** + * A callback fired when the modal is completely shown, after any show animations have completed. + */ onAfterShow?: ((event: CallbackEvent) => void) | null; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/MoneyField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/MoneyField.d.ts index 83709220ae..669497c750 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/MoneyField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/MoneyField.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,21 +9,30 @@ import type { TextFieldProps, MoneyFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event with a strongly-typed currentTarget property for 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 = Event & { - /** - * The element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A callback function that receives a strongly-typed event for 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 = @@ -31,189 +40,133 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** - * The React-style event callback props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's invoked when the user makes any changes in the field. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles for the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a Preact component in a shadow root. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's Preact elements into the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the shadow root. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * The properties from an event that indicate how the user activated an element. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down when the event occurred. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on macOS) was held down when the event occurred. - */ - metaKey: boolean; - /** - * Whether the Control key was held down when the event occurred. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed when the event occurred. A value of 0 indicates the primary button (usually left), 1 indicates the middle button, and 2 indicates the secondary button (usually right). - */ - button: number; -} -/** - * The options for influencing a programmatic 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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The base properties for an input element that participates in form submission. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** @private */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the user makes any changes in the field. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the field is disabled, disallowing any interaction. - * - * @default false - */ accessor disabled: PreactInputProps['disabled']; - /** - * An identifier for the field. - */ accessor id: PreactInputProps['id']; - /** - * An identifier for the field that's unique within the nearest containing form. - */ accessor name: PreactInputProps['name']; - /** - * The current value for the field. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The base properties for form field elements that support labels, validation, and autocomplete. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -235,10 +188,10 @@ export type PreactFieldProps = * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * * Alternatively, you can provide value which describes the @@ -253,58 +206,20 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** @private */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * A callback that's invoked when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint as to the intended content of the field for autocomplete purposes. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value for the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * Additional descriptive text to display below the field that provides supplementary information. - */ accessor details: PreactFieldProps['details']; - /** - * An error message to display below the field, indicating validation failure or other issues. - */ accessor error: PreactFieldProps['error']; - /** - * The text label to display for the field, describing what the user should enter. - */ accessor label: PreactFieldProps['label']; - /** - * Controls the visibility of the label for accessibility purposes. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The placeholder text that's displayed inside the field when it's empty, providing a hint about expected input. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only, preventing edits while still allowing focus and selection. - * - * @default false - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before form submission. - * - * @default false - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically @@ -334,43 +249,36 @@ declare class PreactFieldElement } /** - * The required properties from the `MoneyFieldProps$1` definition. This type ensures all properties from the shared definition are marked as required. + * Represents the money field component props with all properties marked as required. * @publicDocs */ export type RequiredMoneyFieldProps = Required; /** - * The properties for the money field component. These properties configure a specialized input field for entering monetary amounts with automatic currency formatting, decimal handling, and range validation. - * @publicDocs + * Configure the following properties on the money field component. */ export interface MoneyFieldProps extends Omit, - Pick { - /** - * The current monetary value for the field, represented as a string. - */ + Pick { value: Required['value']; } -/** - * The money field custom element class that renders a monetary input field in the Shopify admin interface. This component allows merchants to enter currency amounts with automatic formatting, decimal precision, and validation against minimum and maximum values. - */ -declare class MoneyField +declare abstract class MoneyFieldBase extends PreactFieldElement - implements MoneyFieldProps + implements Pick { - /** - * The maximum monetary value allowed in the field. - */ accessor max: MoneyFieldProps['max']; - /** - * The minimum monetary value allowed in the field. - */ accessor min: MoneyFieldProps['min']; - /** - * The current monetary value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. The value should be a numeric string representing the amount in the store's currency. - */ + accessor currencyCode: MoneyFieldProps['currencyCode']; get value(): string; set value(value: string); + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the money field component. + * @publicDocs + */ +declare class MoneyField extends MoneyFieldBase implements MoneyFieldProps { constructor(); } declare global { @@ -381,20 +289,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: MoneyFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-money-field'; -/** - * The JSX props for the money field component. These properties extend `MoneyFieldProps` with JSX-specific event callbacks for React-style event handling when used in Preact. - * @publicDocs - */ export interface MoneyFieldJSXProps - extends Partial, + extends Partial>, FieldReactProps, - Pick {} + Pick, + FieldSlotInternalReactProps {} export {MoneyField}; export type {MoneyFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Number.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Number.d.ts new file mode 100644 index 0000000000..45a58caa1a --- /dev/null +++ b/packages/ui-extensions/src/surfaces/admin/components/Number.d.ts @@ -0,0 +1,193 @@ +/** VERSION: 2.23.0 **/ +/* eslint-disable import/extensions */ +/* eslint-disable @typescript-eslint/ban-types */ +/* eslint-disable @typescript-eslint/no-namespace */ +/* eslint-disable @typescript-eslint/member-ordering */ + +// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment +/// +import type { + ComponentChildren, + TextProps, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare const typographyFontWeights: readonly [ + 'auto', + 'base', + 'medium', + 'semibold', + 'bold', +]; +export type TypographyFontWeight = (typeof typographyFontWeights)[number]; +declare const bodyFontSizes: readonly [ + 'auto', + 'small-200', + 'small-100', + 'small', + 'base', + 'large', + 'large-100', +]; +export type BodyFontSize = (typeof bodyFontSizes)[number]; + +export type NumberFontSize = BodyFontSize; +export type NumberFontWeight = TypographyFontWeight; +export interface NumberProps + extends Required> { + /** + * The semantic tone that's applied to the number, which changes its color to convey meaning. + * + * - `info`: Informational content or helpful tips (blue). + * - `success`: Positive outcomes or successful states (green). + * - `warning`: Important warnings about potential issues (orange). + * - `critical`: Urgent problems or destructive actions (red). + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent (gray). + * - `caution`: Advisory notices that need attention (yellow). + * + * @default 'auto' + */ + tone: Extract< + TextProps['tone'], + 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'caution' | 'critical' + >; + /** + * The color emphasis applied to the number. + * + * - `base`: Standard emphasis for numeric content. + * - `subdued`: Deemphasized color for secondary or supporting numeric content. + * + * @default 'base' + */ + color: Extract; + /** + * Font size of the number. The named values also apply their matching + * line-height and letter-spacing. + * + * @default 'auto' + */ + fontSize: NumberFontSize; + /** + * Font weight of the number. + * + * @default 'auto' + */ + fontWeight: NumberFontWeight; +} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +/** + * 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 { + /** + * 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 access the underlying DOM element directly. + * Typically created using `useRef()` to interact with the element imperatively or measure its properties. + */ + ref?: preact.Ref; + /** + * 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; +} +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs + */ +export interface PreactBaseElementPropsWithChildren + extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ + children?: preact.ComponentChildren; +} + +/** + * Configure the following properties on the number component. + * @publicDocs + */ +declare class Number extends PolarisCustomElement implements NumberProps { + accessor tone: NumberProps['tone']; + accessor color: NumberProps['color']; + accessor fontSize: NumberProps['fontSize']; + accessor fontWeight: NumberProps['fontWeight']; + accessor dir: NumberProps['dir']; + accessor accessibilityVisibility: NumberProps['accessibilityVisibility']; + constructor(); +} +declare global { + interface HTMLElementTagNameMap { + [tagName]: Number; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: NumberJSXProps & PreactBaseElementPropsWithChildren; + } + } +} + +declare const tagName = 's-number'; + +export interface NumberJSXProps + extends Partial, + Pick { + /** + * The number to display. The component styles the value you pass in — typography, tone, and color — and renders it as given, so format and localize it yourself. + */ + children?: ComponentChildren; +} + +export {Number}; +export type {NumberJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/NumberField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/NumberField.d.ts index 270ef3a9de..f1cf718f18 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/NumberField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/NumberField.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,21 +9,30 @@ import type { TextFieldProps, NumberFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event with a strongly-typed currentTarget property for 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 = Event & { - /** - * The element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A callback function that receives a strongly-typed event for 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 = @@ -31,189 +40,133 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** - * The React-style event callback props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's invoked when the user makes any changes in the field. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles for the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a Preact component in a shadow root. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's Preact elements into the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the shadow root. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * The properties from an event that indicate how the user activated an element. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down when the event occurred. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on macOS) was held down when the event occurred. - */ - metaKey: boolean; - /** - * Whether the Control key was held down when the event occurred. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed when the event occurred. A value of 0 indicates the primary button (usually left), 1 indicates the middle button, and 2 indicates the secondary button (usually right). - */ - button: number; -} -/** - * The options for influencing a programmatic 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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The base properties for an input element that participates in form submission. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** @private */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the user makes any changes in the field. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the field is disabled, disallowing any interaction. - * - * @default false - */ accessor disabled: PreactInputProps['disabled']; - /** - * An identifier for the field. - */ accessor id: PreactInputProps['id']; - /** - * An identifier for the field that's unique within the nearest containing form. - */ accessor name: PreactInputProps['name']; - /** - * The current value for the field. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The base properties for form field elements that support labels, validation, and autocomplete. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -235,10 +188,10 @@ export type PreactFieldProps = * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * * Alternatively, you can provide value which describes the @@ -253,58 +206,20 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** @private */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * A callback that's invoked when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint as to the intended content of the field for autocomplete purposes. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value for the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * Additional descriptive text to display below the field that provides supplementary information. - */ accessor details: PreactFieldProps['details']; - /** - * An error message to display below the field, indicating validation failure or other issues. - */ accessor error: PreactFieldProps['error']; - /** - * The text label to display for the field, describing what the user should enter. - */ accessor label: PreactFieldProps['label']; - /** - * Controls the visibility of the label for accessibility purposes. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The placeholder text that's displayed inside the field when it's empty, providing a hint about expected input. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only, preventing edits while still allowing focus and selection. - * - * @default false - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before form submission. - * - * @default false - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically @@ -334,8 +249,7 @@ declare class PreactFieldElement } /** - * The properties for the number field component. These properties configure a specialized input field for entering numeric values with support for validation, formatting, range constraints, and optimized mobile input modes. - * @publicDocs + * Configure the following properties on the number field component. */ export interface NumberFieldProps extends Omit< @@ -348,51 +262,44 @@ export interface NumberFieldProps 'inputMode' | 'max' | 'min' | 'prefix' | 'step' | 'suffix' > > { + value: Required['value']; /** - * The current value for the field, represented as a string. + * The type of virtual keyboard to display on mobile devices. + * + * - `decimal`: Shows a numeric keyboard with a decimal point, suitable for prices or measurements. + * - `numeric`: Shows a numeric keyboard without a decimal point, suitable for whole numbers like quantities. + * + * Learn more about the [inputmode attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode). + * + * @default 'decimal' */ - value: Required['value']; + inputMode: Required['inputMode']; } -/** - * The number field custom element class that renders a numeric input field in the Shopify admin interface. This component allows merchants to enter numbers with automatic validation and prefix/suffix display. - */ -declare class NumberField +declare abstract class NumberFieldBase extends PreactFieldElement - implements NumberFieldProps + implements + Pick< + NumberFieldProps, + 'inputMode' | 'step' | 'max' | 'min' | 'prefix' | 'suffix' | 'value' + > { - /** - * The current numeric value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. The value should be a numeric string (decimal or integer). - */ get value(): string; set value(value: string); - /** - * The input mode hint for mobile keyboards. Available values include: - * - `numeric`: Shows a numeric keypad optimized for entering numbers - * - `decimal`: Shows a numeric keypad with decimal point support - * - `tel`: Shows a telephone keypad - */ accessor inputMode: NumberFieldProps['inputMode']; - /** - * The granularity that the value must adhere to, or the keyword `any`. This controls the increment/decrement step size. - */ accessor step: NumberFieldProps['step']; - /** - * The maximum numeric value allowed in the field. - */ accessor max: NumberFieldProps['max']; - /** - * The minimum numeric value allowed in the field. - */ accessor min: NumberFieldProps['min']; - /** - * Text or content to display before the user's input, such as a currency symbol. - */ accessor prefix: NumberFieldProps['prefix']; - /** - * Text or content to display after the user's input, such as a unit of measurement. - */ accessor suffix: NumberFieldProps['suffix']; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the number field component. + * @publicDocs + */ +declare class NumberField extends NumberFieldBase implements NumberFieldProps { constructor(); } declare global { @@ -403,20 +310,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: NumberFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-number-field'; -/** - * The JSX props for the number field component. These properties extend `NumberFieldProps` with JSX-specific event callbacks for React-style event handling when used in Preact. - * @publicDocs - */ export interface NumberFieldJSXProps - extends Partial, + extends Partial>, Pick, - FieldReactProps {} + FieldReactProps, + FieldSlotInternalReactProps {} export {NumberField}; export type {NumberFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Option.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Option.d.ts index e93938a1ee..d3e1ef75b3 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Option.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Option.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,152 +6,115 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, OptionProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + OptionProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * Properties for rendering a single option within a select dropdown that users can choose from. - * @publicDocs + * Represents a single option within a select component. Use only as a child of s-select components. */ export interface OptionProps extends Required< Pick > {} -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; -/** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; - /** - * Whether the Control key was held down during the interaction. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the interaction. - */ - button: number; -} -/** - * Options for influencing how a programmatic click behaves. - * @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; -} -/** - * 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); /** @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; } -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A single option within a select dropdown that users can choose. + * Represents a single option within a select component. Use only as a child of s-select components. + * @publicDocs */ -declare class Option extends PreactCustomElement implements OptionProps { +declare class Option extends PolarisCustomElement implements OptionProps { /** - * Whether the option is currently selected. + * Whether the option is currently selected. Use this for controlled components where you manage the selection state. */ accessor selected: OptionProps['selected']; /** - * Whether the option should be selected when it's first rendered. + * The initial selected state for uncontrolled components. Use this when you want the option to start selected but don't need to control its state afterward. */ accessor defaultSelected: OptionProps['defaultSelected']; /** - * The value that's submitted with the form when this option is selected. + * The value submitted with the form when this checkbox is checked. If not specified, the default value is "on". */ accessor value: OptionProps['value']; /** - * Whether the option is disabled and can't be selected. + * Whether the checkbox is disabled, preventing user interaction. Disabled checkboxes appear dimmed and their values aren't submitted with forms. */ accessor disabled: OptionProps['disabled']; constructor(); @@ -170,15 +133,11 @@ declare module 'preact' { } declare const tagName = 's-option'; -/** - * Properties for using the option component in JSX with React-style props. - * @publicDocs - */ export interface OptionJSXProps extends Partial, Pick { /** - * The content that's used as the option label, displayed in the dropdown list. + * The text or elements displayed as the option label, which identifies the selectable choice to users in a dropdown or selection list. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/OptionGroup.d.ts b/packages/ui-extensions/src/surfaces/admin/components/OptionGroup.d.ts index 48a02513bc..a83f7c59bb 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/OptionGroup.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/OptionGroup.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,146 +6,114 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, OptionGroupProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + OptionGroupProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * Properties for rendering a group of related options within a select dropdown, organized under a shared label. - * @publicDocs - */ -export interface OptionGroupProps - extends Required> {} - -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs + * Represents a group of options within a select component. Use only as a child of `s-select` components. */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; +export interface OptionGroupProps + extends Required> { /** - * Whether the Control key was held down during the interaction. + * Whether the options within this group can be selected or not. + * + * @default false */ - ctrlKey: boolean; + disabled: Required['disabled']; /** - * The mouse button that was pressed during the interaction. + * The user-facing label for this group of options. */ - button: number; + label: Required['label']; } -/** - * Options for influencing how a programmatic click behaves. - * @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; -} -/** - * 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); /** @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; } -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A group of related options within a select dropdown, displayed with a label. + * Represents a group of options within a select component. Use only as a child of `s-select` components. + * @publicDocs */ declare class OptionGroup - extends PreactCustomElement + extends PolarisCustomElement implements OptionGroupProps { - /** - * Whether all options in the group are disabled and can't be selected. - */ accessor disabled: OptionGroupProps['disabled']; - /** - * The text that describes what this group of options represents. - */ accessor label: OptionGroupProps['label']; constructor(); } @@ -164,10 +132,6 @@ declare module 'preact' { } declare const tagName = 's-option-group'; -/** - * Properties for using the option group component in JSX with React-style props. - * @publicDocs - */ export interface OptionGroupJSXProps extends Partial, Pick { diff --git a/packages/ui-extensions/src/surfaces/admin/components/OrderedList.d.ts b/packages/ui-extensions/src/surfaces/admin/components/OrderedList.d.ts index ac6838ca9a..6691a70eca 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/OrderedList.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/OrderedList.d.ts @@ -1,145 +1,103 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, OrderedListProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + OrderedListProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * The properties for the ordered list component. These properties define a numbered list of items with automatic numbering and proper list semantics. - * @publicDocs + * Configure the following properties on the ordered list component. */ export interface OrderedListProps extends OrderedListProps$1 {} -/** - * A string containing CSS styles. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow DOM. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An object that represents the state of modifier keys and mouse button - * during an activation event like a click. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the meta (Command on Mac, Windows key on PC) key was pressed. - */ - 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; -} -/** - * Options for customizing click behavior on an element. - * @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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A custom element for displaying a numbered list of items with automatic numbering and proper list semantics. Use ordered list when the sequence or order of items matters, such as instructions, rankings, or step-by-step processes. + * Configure the following properties on the ordered list component. + * @publicDocs */ declare class OrderedList - extends PreactCustomElement + extends PolarisCustomElement implements OrderedListProps { constructor(); @@ -159,15 +117,11 @@ declare module 'preact' { } declare const tagName = 's-ordered-list'; -/** - * The JSX properties for the ordered list component. These properties define how an ordered list is rendered in Preact or JSX. - * @publicDocs - */ export interface OrderedListJSXProps extends Partial, Pick { /** - * The items in the ordered list. Only list item components are accepted. + * The list entries displayed within the ordered list, where each item is numbered sequentially. Only accepts list item components as children. Each list item represents a single numbered entry in the sequence. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Page.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Page.d.ts index 8d307eb57e..ab3787d519 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Page.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Page.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.38.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -12,31 +12,99 @@ import type { PreactCustomElement, RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +/** + * Use as the outer wrapper of a page. + */ export interface PageProps extends Required> { + /** + * The inline size of the page + * - `base` corresponds to a set default inline size + * - `large` full width with whitespace + * + * @default 'base' + */ inlineSize: Extract; + /** + * The main page heading + */ + heading: Required['heading']; } -/** Used when an element does not have children. * @publicDocs +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +/** + * 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 { - /** Assigns a unique key to this element. */ + /** + * 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; - /** Assigns a ref (generally from `useRef()`) to this element. */ + /** + * 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; - /** Assigns this element to a parent's slot. */ + /** + * 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; } -/** Used when an element has children. * @publicDocs +/** + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. + * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } declare class PolarisCustomElement extends PreactCustomElement { constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; } declare abstract class PageBase @@ -52,6 +120,10 @@ declare abstract class PageBase disconnectedCallback(): void; } +/** + * Use as the outer wrapper of a page. + * @publicDocs + */ declare class Page extends PageBase implements PageProps { constructor(); } @@ -65,7 +137,11 @@ declare module 'preact' { interface IntrinsicElements { [tagName]: Omit< PageJSXProps, - 'aside' | 'primaryAction' | 'secondaryActions' | 'breadcrumbActions' + | 'aside' + | 'primaryAction' + | 'secondaryActions' + | 'breadcrumbActions' + | 'supplementalStart' > & PreactBaseElementPropsWithChildren; } @@ -77,7 +153,7 @@ export interface PageJSXProps extends Partial, Pick { /** - * The content of the Page. + * The main page content displayed within the page component, which serves as the primary container for the page's information and interface elements. */ children?: ComponentChildren; /** @@ -89,22 +165,26 @@ export interface PageJSXProps /** * The primary action for the page. * - * Only accepts a single `Button` component with a `variant` of `primary`. + * Only accepts a single button component with a `variant` of `primary`. * */ primaryAction?: ComponentChildren; /** - * Secondary actions for the page. + * The secondary actions for the page. * - * Only accepts `ButtonGroup` and `Button` components with a `variant` of `secondary` or `auto`. + * Only accepts button group and button components with a `variant` of `secondary` or `auto`. */ secondaryActions?: ComponentChildren; /** - * Navigations back actions for the page. + * The navigation back actions for the page. * - * Only accepts `Link` components. + * Only accepts link components. */ breadcrumbActions?: ComponentChildren; + /** + * A slot for content that comes before the main content, such as an `s-banner`. + */ + supplementalStart?: ComponentChildren; } export {Page}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Paragraph.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Paragraph.d.ts index 380678507d..1ca9689af3 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Paragraph.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Paragraph.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,11 +6,69 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, ParagraphProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + ParagraphProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare const typographyFontWeights: readonly [ + 'auto', + 'base', + 'medium', + 'semibold', + 'bold', +]; +export type TypographyFontWeight = (typeof typographyFontWeights)[number]; +declare const bodyFontSizes: readonly [ + 'auto', + 'small-200', + 'small-100', + 'small', + 'base', + 'large', + 'large-100', +]; +export type BodyFontSize = (typeof bodyFontSizes)[number]; + +export type ParagraphFontSize = BodyFontSize; +export type ParagraphFontWeight = TypographyFontWeight; /** - * The properties for the paragraph component. These properties define blocks of text content with consistent spacing and styling for readable body copy. - * @publicDocs + * Configure the following properties on the paragraph component. */ export interface ParagraphProps extends Required< @@ -24,6 +82,7 @@ export interface ParagraphProps | 'lineClamp' > > { + color: Extract; /** * The semantic tone that's applied to the paragraph text, which changes its color to convey meaning. * @@ -35,173 +94,106 @@ export interface ParagraphProps */ tone: Extract< ParagraphProps$1['tone'], - 'info' | 'success' | 'caution' | 'warning' | 'critical' + 'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical' >; /** - * The color of the paragraph text. Available options: - * - `'base'` - The default text color. - * - `'subdued'` - A lighter text color for secondary information. - */ - color: Extract; -} - -/** - * A string containing CSS styles. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow DOM. - */ - styles?: Styles; -}; -/** - * An object that represents the state of modifier keys and mouse button - * during an activation event like a click. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the meta (Command on Mac, Windows key on PC) key was pressed. - */ - 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). + * Font size of the paragraph. The named values also apply their matching + * line-height and letter-spacing. + * + * @default 'auto' */ - button: number; -} -/** - * Options for customizing click behavior on an element. - * @publicDocs - */ -export interface ClickOptions { + fontSize: ParagraphFontSize; /** - * 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; -} -/** - * 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 + * Font weight of the paragraph. + * + * @default 'auto' */ - queueRender(): void; + fontWeight: ParagraphFontWeight; /** - * 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 + * @deprecated Use `Number` for inline numeric values instead. */ - click({sourceEvent}?: ClickOptions): void; + fontVariantNumeric: Extract< + ParagraphProps$1['fontVariantNumeric'], + 'auto' | 'normal' | 'tabular-nums' + >; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** - * A custom element for displaying blocks of text content with consistent spacing and styling for readable body copy. Use Paragraph to render longer text content with proper line height and spacing between paragraphs. - */ -declare class Paragraph extends PreactCustomElement implements ParagraphProps { +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +declare abstract class ParagraphBase + extends PolarisCustomElement + implements + Pick< + ParagraphProps, + | 'fontVariantNumeric' + | 'fontSize' + | 'fontWeight' + | 'lineClamp' + | 'color' + | 'dir' + | 'accessibilityVisibility' + > +{ + accessor fontSize: ParagraphProps['fontSize']; + accessor fontWeight: ParagraphProps['fontWeight']; /** - * The numeric font variant for the paragraph text. + * @deprecated Use `Number` for inline numeric values instead. */ accessor fontVariantNumeric: ParagraphProps['fontVariantNumeric']; - /** - * The maximum number of lines to display before the text is truncated with an ellipsis. - */ accessor lineClamp: ParagraphProps['lineClamp']; - /** - * The semantic tone that's applied to the paragraph text, which changes its color to convey meaning. - * - * - `info`: Informational content or helpful tips (blue). - * - `success`: Positive outcomes or successful states (green). - * - `warning`: Important warnings about potential issues (orange). - * - `critical`: Urgent problems or destructive actions (red). - * - `caution`: Advisory notices that need attention (yellow). - */ - accessor tone: ParagraphProps['tone']; - - /** - * The color of the paragraph text. - */ + abstract tone: string; accessor color: ParagraphProps['color']; - /** - * The text direction (left-to-right or right-to-left). - */ accessor dir: ParagraphProps['dir']; - /** - * The visibility of the element to assistive technologies. - */ accessor accessibilityVisibility: ParagraphProps['accessibilityVisibility']; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the paragraph component. + * @publicDocs + */ +declare class Paragraph extends ParagraphBase implements ParagraphProps { + accessor tone: ParagraphProps['tone']; constructor(); } declare global { @@ -219,15 +211,11 @@ declare module 'preact' { } declare const tagName = 's-paragraph'; -/** - * The JSX properties for the paragraph component. These properties define how a paragraph is rendered in Preact or JSX. - * @publicDocs - */ export interface ParagraphJSXProps extends Partial, Pick { /** - * The content of the paragraph. + * The paragraph text content displayed within the paragraph component, which presents a block of related text with appropriate styling. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/PasswordField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/PasswordField.d.ts index 804b72dca8..bd00440ce3 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/PasswordField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/PasswordField.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,218 +9,164 @@ import type { TextFieldProps, PasswordFieldProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event object with a strongly-typed currentTarget property that references the specific HTML element type. + * 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 = Event & { - /** - * The DOM element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function or null that receives a typed callback event. + * 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 = | (EventListener & { - /** - * The callback function that's invoked when the event fires. - */ (event: CallbackEvent): void; }) | null; -/** - * The React-style event handler props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's triggered when the field's value changes as the user types. + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field's value changes and the field loses focus. + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field receives focus. + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field loses focus. + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles to be applied to the component. - * @publicDocs - */ -export type Styles = string; -/** - * The implementation details for rendering a custom element with a shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * An object containing information about keyboard and mouse button states during an activation event. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the Meta (Command on Mac, Windows key on PC) key was pressed during the event. - */ - metaKey: boolean; - /** - * Whether the Control key was pressed during the event. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the event. - */ - button: number; -} -/** - * The options for programmatically triggering a click event on an element. - * @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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The required props for input elements that all form controls must implement. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * The base class for form input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** @private */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * The callback that's triggered when the input value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the input value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * The unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name of the input, used when submitting form data. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; - /** - * The current value of the input. - */ set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The common props shared by all form field components in the admin UI. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -239,17 +185,17 @@ export type PreactFieldProps = > > & { /** - * A hint about the intended content of the field for browser autofill. + * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * - * Alternatively, you can provide a value which describes the - * specific data you'd like to be entered into this field during autofill. + * Alternatively, you can provide value which describes the + * specific data you would like to be entered into this field during autofill. * * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers. * @@ -260,63 +206,27 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** - * The base class for form field elements that includes label, error, and validation support. - */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * The callback that's triggered when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * The callback that's triggered when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint about the intended content of the field for browser autofill. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value of the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * The additional text displayed below the field to provide helpful context. - */ accessor details: PreactFieldProps['details']; - /** - * The error message displayed when the field validation fails. - */ accessor error: PreactFieldProps['error']; - /** - * The text label displayed above the field. - */ accessor label: PreactFieldProps['label']; - /** - * The visibility of the label for accessibility purposes. Available values: `hidden`, `visible`. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The hint text displayed inside the field when it's empty. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only and can't be edited by the user. - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before the form can be submitted. - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically * ignore keystrokes originating from within input elements. Unfortunately, - * these never account for a custom element being the input element. + * these never account for a Custom Element being the input element. * - * To fix this, we spoof getAttribute and hasAttribute to make a PreactFieldElement + * To fix this, we spoof getAttribute & hasAttribute to make a PreactFieldElement * appear as a contentEditable "input" when it contains a focused input element. * @private technically not private, but we don't want to expose this as public API */ @@ -326,8 +236,8 @@ declare class PreactFieldElement */ hasAttribute(qualifiedName: string): boolean; /** - * Checks if the shadow tree contains a focused input (input, textarea, select, contentEditable element). - * Note: this doesn't return true for focused non-field form elements like buttons. + * Checks if the shadow tree contains a focused input (input, textarea, select, ). + * Note: this does _not_ return true for focussed non-field form elements like buttons. * @private */ get isContentEditable(): boolean; @@ -339,7 +249,7 @@ declare class PreactFieldElement } /** - * The properties for the password field component. These properties configure a secure input field that collects sensitive password input from merchants with masked characters. + * Represents the props for password input field components. Extends `PreactFieldProps` with autocomplete support for password-related fields. * @publicDocs */ export type PasswordFieldProps = PreactFieldProps< @@ -364,26 +274,23 @@ export type PasswordFieldProps = PreactFieldProps< > >; +declare abstract class PasswordFieldBase + extends PreactFieldElement + implements Pick +{ + accessor maxLength: PasswordFieldProps['maxLength']; + accessor minLength: PasswordFieldProps['minLength']; + constructor(renderImpl: RenderImpl); +} + /** - * The password field custom element class that renders a password input field in the Shopify admin interface. This component allows merchants to enter passwords securely with characters automatically masked for privacy. + * Configure the following properties on the password field component. + * @publicDocs */ declare class PasswordField - extends PreactFieldElement + extends PasswordFieldBase implements PasswordFieldProps { - /** - * The maximum number of characters allowed in the password. - */ - accessor maxLength: PasswordFieldProps['maxLength']; - /** - * The minimum number of characters required in the password. - */ - accessor minLength: PasswordFieldProps['minLength']; - /** - * The current password value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. The value is masked in the UI for security. - */ - get value(): string; - set value(value: string); constructor(); } declare global { @@ -394,20 +301,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: PasswordFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-password-field'; -/** - * The JSX props for the password field component. These properties extend `PasswordFieldProps` with JSX-specific event callbacks for React-style event handling when used in Preact. - * @publicDocs - */ export interface PasswordFieldJSXProps - extends Partial, + extends Partial>, Pick, - FieldReactProps {} + FieldReactProps, + FieldSlotInternalReactProps {} export {PasswordField}; export type {PasswordFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Popover.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Popover.d.ts index cf37b233ca..eff5e16999 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Popover.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Popover.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 2.19.1 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -44,6 +44,11 @@ export type CallbackToggleEvent< * 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 = @@ -223,6 +228,19 @@ declare class PreactOverlayElement extends PolarisCustomElement { export type MakeResponsive = T | `@container${string}`; /** * Makes a property's value potentially responsive. + * + * @example + * type Example = { + * color: boolean; + * margin: string; + * padding: number; + * } + * type Result = MakeResponsivePick; + * // Result = { + * color: boolean | `@container${string}`; + * margin: string | `@container${string}`; + * padding: number | `@container${string}`; + * } * @publicDocs */ export type MakeResponsivePick = { @@ -370,7 +388,7 @@ export interface BoxProps * * **Examples:** `base`, `large none`, `base large-100 base small` * - * Use `auto` to inherit padding from the nearest container with removed padding. Also accepts a [responsive value](/docs/api/polaris/using-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' */ @@ -382,7 +400,7 @@ export interface BoxProps * * **Example:** `large none` applies `large` to the top and `none` to the bottom. * - * Overrides the block value from `padding`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ @@ -390,7 +408,7 @@ export interface BoxProps /** * The block-start padding (top in horizontal writing modes). * - * Overrides the block-start value from `paddingBlock`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ @@ -398,7 +416,7 @@ export interface BoxProps /** * The block-end padding (bottom in horizontal writing modes). * - * Overrides the block-end value from `paddingBlock`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ @@ -410,7 +428,7 @@ export interface BoxProps * * **Example:** `large none` applies `large` to the left and `none` to the right. * - * Overrides the inline value from `padding`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ @@ -418,7 +436,7 @@ export interface BoxProps /** * The inline-start padding (left in LTR writing modes, right in RTL). * - * Overrides the inline-start value from `paddingInline`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ @@ -426,7 +444,7 @@ export interface BoxProps /** * The inline-end padding (right in LTR writing modes, left in RTL). * - * Overrides the inline-end value from `paddingInline`. Also accepts a [responsive value](/docs/api/polaris/using-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 */ diff --git a/packages/ui-extensions/src/surfaces/admin/components/QueryContainer.d.ts b/packages/ui-extensions/src/surfaces/admin/components/QueryContainer.d.ts index cbaf96ca3b..4e0ab47702 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/QueryContainer.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/QueryContainer.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,152 +6,120 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, QueryContainerProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + QueryContainerProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { - 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 & { - /** - * 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. + * The child elements to be rendered within this component. */ - 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). - */ - 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. + * Configure the following properties on the query container component. */ -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; +export interface QueryContainerProps + extends Required> { /** - * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`. + * An identifier for this container that you can reference in CSS container queries to apply styles based on this specific container's size. * - * 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 + * All query container components automatically receive a container name of `s-default`. You can omit the container name in your queries, so `@container (inline-size <= 300px)` is equivalent to `@container s-default (inline-size <= 300px)`. + * + * When you provide a custom `containerName`, it's added alongside `s-default`. For example, `containerName="product-card"` results in `s-default product-card` being set on the `container-name` CSS property, allowing you to target this container with `@container product-card (inline-size <= 300px)`. + * + * Learn more about the [container-name property](https://developer.mozilla.org/en-US/docs/Web/CSS/container-name). + * + * @default '' + * + * @implementation You must always have a CSS `container-name` of `s-default` for this component. */ - click({sourceEvent}?: ClickOptions): void; + containerName: Required['containerName']; } /** - * The properties you can set on a query container component. + * Configure the following properties on the query container component. * @publicDocs */ -export interface QueryContainerProps - extends Required> {} - -/** - * A component that sets up a container query context, which lets child elements style themselves based on the container's size instead of the viewport size. - */ declare class QueryContainer - extends PreactCustomElement + extends PolarisCustomElement implements QueryContainerProps { - /** - * The name of the container, which you can reference in CSS container queries. - */ accessor containerName: QueryContainerProps['containerName']; /** @private */ static globalStylesApplied: boolean; - /** - * Creates a new QueryContainer instance. - */ constructor(); } declare global { @@ -168,19 +136,12 @@ declare module 'preact' { } } -/** - * The custom element tag name for the query container component. - */ declare const tagName = 's-query-container'; -/** - * The JSX properties you can set on a query container component. - * @publicDocs - */ export interface QueryContainerJSXProps extends Partial, Pick { /** - * The content to display inside the container. + * The content displayed within the query container component, which enables container queries for responsive styling based on the container's size rather than the viewport. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/SearchField.d.ts b/packages/ui-extensions/src/surfaces/admin/components/SearchField.d.ts index f7ecc9aef7..7dbf240c1e 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/SearchField.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/SearchField.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 /// -import type {TextFieldProps, ComponentChildren} from './shared.d.ts'; +import type { + TextFieldProps, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event that includes a strongly-typed reference to the element that triggered it. + * 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 = Event & { - /** - * The element that the event handler was attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A function that handles events for a specific element type, or null if no handler is set. + * 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 = @@ -27,190 +39,133 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** - * Event handlers for field interactions in React-style syntax. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's triggered when the field's value changes as the user types. + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field's value changes and the field loses focus. + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field receives focus. + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the field loses focus. + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } -/** Used when an element does not have children. * @publicDocs - */ -export interface PreactBaseElementProps { - /** - * 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. - */ - 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. - */ - ref?: preact.Ref; - /** - * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns. - */ - slot?: Lowercase; -} - /** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. */ -export type Styles = string; +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} /** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} /** - * Information about modifier keys and mouse buttons that were active during an interaction. + * 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 ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; +export interface PreactBaseElementProps { /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. + * 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. */ - metaKey: boolean; + key?: preact.Key; /** - * Whether the Control key was held down during the interaction. + * A reference to access the underlying DOM element directly. + * Typically created using `useRef()` to interact with the element imperatively or measure its properties. */ - ctrlKey: boolean; + ref?: preact.Ref; /** - * The mouse button that was pressed during the interaction. + * The named slot to which this element is assigned in the parent component's shadow DOM. + * + * Used for advanced component composition with web components. */ - button: number; + slot?: Lowercase; } -/** - * Options for influencing how a programmatic click behaves. - * @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; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The core properties that all input elements need to function within forms. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * Base class for input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** - * Indicates that this element can participate in form submission. - */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's triggered when the input's value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's triggered when the input's value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * A unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name that identifies this input when the form is submitted. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * Properties that are common to all text-based field components. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -250,56 +205,20 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** - * Base class for text-based field elements that support labels, errors, and other form field features. - */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * A callback that's triggered when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * A callback that's triggered when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint about what kind of information should go in the field for autofill purposes. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value that the field should display when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * Additional text to provide context or guidance for the input. - */ accessor details: PreactFieldProps['details']; - /** - * An error message that's displayed below the field when validation fails. - */ accessor error: PreactFieldProps['error']; - /** - * The text that describes what the field is for. - */ accessor label: PreactFieldProps['label']; - /** - * Controls whether the label is visible to all users or only to screen readers. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * Text that appears in the field when it's empty to provide a hint about what to enter. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field can be edited by the user. - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled in before the form can be submitted. - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically @@ -329,7 +248,7 @@ declare class PreactFieldElement } /** - * Properties for rendering a search field that lets users enter search queries with validation constraints and autofill support. + * Represents the props for search input field components. Extends `PreactFieldProps` for search-specific functionality. * @publicDocs */ export type SearchFieldProps = PreactFieldProps< @@ -357,26 +276,20 @@ export type SearchFieldProps = PreactFieldProps< > >; -/** - * A search field that lets users enter search queries with a search-specific input type. - */ -declare class SearchField +declare abstract class SearchFieldBase extends PreactFieldElement - implements SearchFieldProps + implements Pick { - /** - * The maximum number of characters that can be entered in the field. - */ accessor maxLength: SearchFieldProps['maxLength']; - /** - * The minimum number of characters that must be entered for the field to be valid. - */ accessor minLength: SearchFieldProps['minLength']; - /** - * The current search query value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. - */ - get value(): string; - set value(value: string); + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the search field component. + * @publicDocs + */ +declare class SearchField extends SearchFieldBase implements SearchFieldProps { constructor(); } declare global { @@ -387,20 +300,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: SearchFieldJSXProps & PreactBaseElementProps; + [tagName]: Omit & + FieldSlotPreactProps & + PreactBaseElementProps; } } } declare const tagName = 's-search-field'; -/** - * Props for using the search field component in JSX with React-style event handlers. - * @publicDocs - */ export interface SearchFieldJSXProps - extends Partial, + extends Partial>, Pick, - FieldReactProps {} + FieldReactProps, + FieldSlotInternalReactProps {} export {SearchField}; export type {SearchFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Section.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Section.d.ts index ee569d8643..dc57c5ddd2 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Section.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Section.d.ts @@ -1,20 +1,57 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, SectionProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + SectionProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * A version of the section properties with all fields required. + * Represents the section component props with all properties marked as required. * @publicDocs */ export type RequiredSectionProps = Required; /** - * The properties for the section component. A section groups related content together with an optional heading, providing semantic structure and visual separation. - * @publicDocs + * Configure the following properties on the section component. */ export interface SectionProps extends Pick< @@ -22,163 +59,98 @@ export interface SectionProps 'accessibilityLabel' | 'heading' | 'padding' > { /** - * An accessibility label for screen readers that provides additional context when the heading isn't descriptive enough on its own. + * 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. */ accessibilityLabel: RequiredSectionProps['accessibilityLabel']; /** - * The heading text that appears at the top of the section, helping users understand what content the section contains. + * The heading text displayed at the top of the section. This heading provides a title for the section's content and automatically uses the appropriate semantic heading level (h2, h3, h4) based on nesting depth to maintain proper document structure. */ heading: RequiredSectionProps['heading']; /** - * Whether the section has padding around its content. Set to `true` to add padding, or `false` to remove it. - */ - padding: RequiredSectionProps['padding']; -} - -/** - * 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 & { - /** - * The function that renders the shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An interface representing the properties of an activation event, such as a click or keypress. - * @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 PC) 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; - /** @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 + * Supporting text that expands on the heading, rendered beneath it in a subdued treatment. + * + * This is not a heading: it adds no entry to the document outline, doesn't change the heading level of the section's children, and isn't announced as part of the heading. Keep whatever distinguishes this section from another in `heading`, since that is what someone navigating by heading hears. */ - queueRender(): void; + subheading: string; /** - * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`. + * The padding applied to all edges of the element's content. * - * 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 + * - `base`: applies padding that is appropriate for the element. Note that it might result in no padding if + * this is the right design decision in a particular context. + * - `none`: removes all padding from the element's content. This can be useful when elements inside the section + * need to span to the edge of the section. For example, a full-width image. In this case, rely on `s-box` with a + * padding of 'base' to bring back the desired padding for the rest of the content. The `heading` and header + * actions keep their padding, so they can be combined with `none`. + * + * @default 'base' */ - click({sourceEvent}?: ClickOptions): void; + padding: RequiredSectionProps['padding']; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** - * A section is a container that groups related content together with an optional heading. - */ -declare class Section extends PreactCustomElement implements SectionProps { - constructor(); +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @private */ connectedCallback(): void; - /** - * The accessibility label for screen readers. - */ + /** @private */ + adoptedCallback(): void; +} + +declare abstract class SectionBase + extends PolarisCustomElement + implements SectionProps +{ + constructor(renderImpl: RenderImpl); + /** @private */ + connectedCallback(): void; + /** @private */ + disconnectedCallback(): void; accessor accessibilityLabel: SectionProps['accessibilityLabel']; - /** - * The heading text for the section. - */ accessor heading: SectionProps['heading']; - /** - * Whether the section has padding. - */ + accessor subheading: SectionProps['subheading']; accessor padding: SectionProps['padding']; } + +/** + * Configure the following properties on the section component. + * @publicDocs + */ +declare class Section extends SectionBase implements SectionProps { + constructor(); +} declare global { interface HTMLElementTagNameMap { [tagName]: Section; @@ -187,23 +159,55 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: SectionJSXProps & PreactBaseElementPropsWithChildren
; + [tagName]: Omit< + SectionJSXProps, + | 'primaryAction' + | 'secondaryActions' + | 'graphic' + | 'accessory' + | 'supplemental' + > & + PreactBaseElementPropsWithChildren
; } } } declare const tagName = 's-section'; -/** - * The properties for the section component when it's used in JSX. - * @publicDocs - */ export interface SectionJSXProps extends Partial, Pick { /** - * The child elements to render inside the section. + * The content displayed within the section component, which groups related elements together in a logical unit with an optional heading. */ children?: ComponentChildren; + /** + * The primary action button or link, representing the main or most important action available in this context. Typically displayed with higher visual prominence than secondary actions to establish clear hierarchy. + */ + primaryAction?: ComponentChildren; + /** + * Additional action buttons or links that provide alternative or supporting actions. Visually de-emphasized compared to the primary action. + * + * A ButtonGroup holding an action and the icon-only activator for its Menu renders as one segmented group with a chevron activator. The group needs an `accessibilityLabel`, and must hold exactly one Button with text followed by one Button with no text that has an `accessibilityLabel` and a `commandFor` opening a Menu, both with a `variant` of `secondary` or `auto`. + */ + secondaryActions?: ComponentChildren; + /** + * A decorative visual that reinforces the heading, rendered before it. + * + * Accepts a single icon-only Badge (`icon` set, no text content) with a `size` of `large`. The heading identifies the section, so this content is not announced by assistive technologies, and it is not rendered at all when the section has no `heading`. + */ + graphic?: ComponentChildren; + /** + * Additional contextual information that qualifies the heading, rendered inline beside the heading text. + * + * Only accepts Badge, Icon, Button, Menu, Text, Avatar, and Thumbnail elements. Text must use `tone`, `fontSize`, and `fontWeight` of `auto`; Icon, Avatar, and Thumbnail must use `size="base"`; Badge must use `size="base"` and `color="base"`; Button must use `inlineSize="auto"`. + */ + accessory?: ComponentChildren; + /** + * Status or metadata that describes the section as a whole rather than qualifying its heading, rendered at the inline-end of the header before any actions. + * + * This is not an action. Only accepts Badge, Avatar, Text, Icon, and Thumbnail elements, under the same prop constraints as `accessory`. + */ + supplemental?: ComponentChildren; } export {Section}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Select.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Select.d.ts index 48728757c0..0cdb298f3d 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Select.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Select.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -11,21 +11,31 @@ import type { TextFieldProps, IconProps$1, SelectProps$1, + PreactCustomElement, + RenderImpl, IconType, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event that includes a strongly-typed reference to the element that triggered it. + * 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 = Event & { - /** - * The element that the event handler was attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A function that handles events for a specific element type, or null if no handler is set. + * 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 = @@ -33,205 +43,176 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs - */ -export interface PreactBaseElementProps { - /** - * 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. - */ - 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. - */ - ref?: preact.Ref; - /** - * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns. - */ - slot?: Lowercase; -} -/** Used when an element has children. * @publicDocs - */ -export interface PreactBaseElementPropsWithChildren - extends PreactBaseElementProps { - children?: preact.ComponentChildren; -} - /** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. */ -export type Styles = string; +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} /** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; -}; +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} /** - * Information about modifier keys and mouse buttons that were active during an interaction. + * 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 ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; +export interface PreactBaseElementProps { /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. + * 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. */ - metaKey: boolean; + key?: preact.Key; /** - * Whether the Control key was held down during the interaction. + * A reference to access the underlying DOM element directly. + * Typically created using `useRef()` to interact with the element imperatively or measure its properties. */ - ctrlKey: boolean; + ref?: preact.Ref; /** - * The mouse button that was pressed during the interaction. + * The named slot to which this element is assigned in the parent component's shadow DOM. + * + * Used for advanced component composition with web components. */ - button: number; + slot?: Lowercase; } /** - * Options for influencing how a programmatic click behaves. + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. * @publicDocs */ -export interface ClickOptions { +export interface PreactBaseElementPropsWithChildren + extends PreactBaseElementProps { /** - * 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. + * The child elements to be rendered within this component. */ - 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; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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; } declare const internals: unique symbol; /** - * The core properties that all input elements need to function within forms. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * Base class for input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** - * Indicates that this element can participate in form submission. - */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's triggered when the input's value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's triggered when the input's value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * A unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name that identifies this input when the form is submitted. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * Properties for displaying an icon within a component. - * @publicDocs + * Configure the following properties on the icon component. */ export interface IconProps - extends Pick< - IconProps$1, - 'type' | 'tone' | 'color' | 'size' | 'interestFor' + extends Required< + Pick > { /** - * Specifies the type of icon that will be displayed. + * The icon to display from the icon library. + * + * Set to a valid icon name to display that icon. To hide the icon completely, + * use an empty string `''`. To reserve the icon's space without displaying an icon, + * use `'empty'`. */ type: '' | IconType | 'empty'; /** - * The semantic meaning of the icon, which affects its color. + * The semantic meaning and color treatment of the component. + * + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `caution`: Advisory notices that need attention. + * + * @default 'auto' */ tone: Extract< IconProps$1['tone'], 'auto' | 'neutral' | 'info' | 'success' | 'caution' | 'warning' | 'critical' >; /** - * The visual prominence of the icon. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. + * + * @default 'base' */ color: Extract; /** * The size of the icon. + * + * - `small`: Smaller icon suitable for inline use within text or compact UI elements. + * - `base`: Default size that works well for standalone icons and standard use cases. */ size: Extract; } /** - * Properties for rendering a select dropdown that lets users choose one option from a list with optional icon and label customization. - * @publicDocs + * Configure the following properties on the select component. */ export interface SelectProps extends Omit, @@ -249,59 +230,39 @@ export interface SelectProps | 'labelAccessibilityVisibility' > > { - /** - * The value of the currently selected option, matching one of the `value` properties from the available options. - */ value: Required['value']; - /** - * An icon that's displayed at the start of the select field to provide visual context for the selection. - */ icon: IconProps['type']; } declare const usedFirstOptionSymbol: unique symbol; declare const hasInitialValueSymbol: unique symbol; -/** - * A select dropdown that lets users choose one option from a list. - */ -declare class Select extends PreactInputElement implements SelectProps { - /** - * An icon that's displayed at the start of the select field. - */ +declare abstract class SelectBase + extends PreactInputElement + implements + Pick< + SelectProps, + | 'icon' + | 'details' + | 'error' + | 'label' + | 'placeholder' + | 'required' + | 'labelAccessibilityVisibility' + > +{ accessor icon: SelectProps['icon']; - /** - * Additional text to provide context or guidance for the select. - */ accessor details: SelectProps['details']; - /** - * An error message that's displayed below the select when validation fails. - */ accessor error: SelectProps['error']; - /** - * The text that describes what the select is for. - */ accessor label: SelectProps['label']; - /** - * Text that appears in the select when no option is selected to provide a hint about what to choose. - */ accessor placeholder: SelectProps['placeholder']; - /** - * Whether an option must be selected before the form can be submitted. - */ accessor required: SelectProps['required']; - /** - * Controls whether the label is visible to all users or only to screen readers. - */ accessor labelAccessibilityVisibility: SelectProps['labelAccessibilityVisibility']; /** @private */ connectedCallback(): void; - /** - * A lifecycle callback that fires when the component is removed from the DOM. Performs cleanup operations. - * @private - */ + /** @private */ disconnectedCallback(): void; - constructor(); + constructor(renderImpl: RenderImpl); /** * used to determine if no value or defaultValue was set, in which case the first non-disabled option was used * @@ -313,14 +274,19 @@ declare class Select extends PreactInputElement implements SelectProps { * @private */ [hasInitialValueSymbol]: boolean; - /** - * The value of the currently selected option. When setting this property programmatically, it updates which option appears selected in the dropdown. When reading it, you get the `value` attribute of the currently selected Option component. - */ get value(): string; set value(value: string); /** @private */ formResetCallback(): void; } + +/** + * Configure the following properties on the select component. + * @publicDocs + */ +declare class Select extends SelectBase implements SelectProps { + constructor(); +} declare global { interface HTMLElementTagNameMap { [tagName]: Select; @@ -329,40 +295,25 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: SelectJSXProps & PreactBaseElementPropsWithChildren; } } } declare const tagName = 's-select'; -/** - * Properties for using the select component in JSX with React-style event handlers. - * @publicDocs - */ export interface SelectJSXProps - extends Partial, - Pick { + extends Partial>, + Pick, + FieldSlotInternalReactProps { /** - * The selectable options displayed in the dropdown list. - * - * Accepts option components for individual selectable items, and option group components to organize related options into logical groups with labels. + * The selectable options displayed in the dropdown list. Accepts option components for individual selectable items, and option group components to organize related options into logical groups with labels. */ children?: ComponentChildren; - /** - * A callback that's triggered when the selected option changes and the select loses focus. - */ onChange?: (event: CallbackEvent) => void; - /** - * A callback that's triggered when the selected option changes as the user interacts with the dropdown. - */ onInput?: (event: CallbackEvent) => void; - /** - * A callback that's triggered when the select loses focus after the user interacts with it. - */ onBlur?: (event: CallbackEvent) => void; - /** - * A callback that's triggered when the select receives focus from the user. - */ onFocus?: (event: CallbackEvent) => void; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Spinner.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Spinner.d.ts index e9112a50cc..63c8805753 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Spinner.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Spinner.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,148 +6,102 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {SpinnerProps$1, ComponentChildren} from './shared.d.ts'; +import type { + SpinnerProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 spinner component. - * @publicDocs + * Configure the following properties on the spinner component. */ export interface SpinnerProps extends Required> { /** - * The size of the spinner. Use `base` for the standard size, `large` for a larger spinner, or `large-100` for a full-width large spinner. + * The size of the loading spinner. + * + * - `base`: Default size suitable for inline loading indicators or standard UI contexts. + * - `large`: Larger spinner for more prominent loading states. + * - `large-100`: Extra large spinner for full-page or emphasized loading states. */ size: Extract; -} - -/** - * 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 & { - /** - * 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). - */ - 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. + * 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. */ - sourceEvent?: ActivationEventEsque; + accessibilityLabel: Required['accessibilityLabel']; } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * A component that displays an animated loading indicator to show that content is currently being processed. + * Configure the following properties on the spinner component. + * @publicDocs */ -declare class Spinner extends PreactCustomElement implements SpinnerProps { - /** - * A label that describes the spinner for assistive technologies. - */ +declare class Spinner extends PolarisCustomElement implements SpinnerProps { accessor accessibilityLabel: string; - /** - * The size of the spinner. - */ accessor size: SpinnerProps['size']; - /** - * Creates a new Spinner instance. - */ constructor(); } declare global { @@ -163,14 +117,7 @@ declare module 'preact' { } } -/** - * The custom element tag name for the spinner component. - */ declare const tagName = 's-spinner'; -/** - * The JSX properties you can set on a spinner component. - * @publicDocs - */ export interface SpinnerJSXProps extends Partial, Pick {} diff --git a/packages/ui-extensions/src/surfaces/admin/components/Stack.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Stack.d.ts index 4d4b9aa3e4..b46d1e0c8c 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Stack.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Stack.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -16,10 +16,45 @@ import type { JustifyContentKeyword, AlignItemsKeyword, AlignContentKeyword, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} /** - * A type that allows a value to be responsive using container query syntax. + * 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 | `@container${string}`; @@ -45,12 +80,21 @@ export type MakeResponsivePick = { }; /** - * A version of the box properties with all fields required. + * Represents the box component props with all properties marked as required. * @publicDocs */ export type RequiredBoxProps = Required; /** - * The allowed border radius values for a box component. + * 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< @@ -65,7 +109,12 @@ export type BoxBorderRadii = Extract< | 'large-200' >; /** - * The allowed border style values for a box component. + * 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< @@ -73,7 +122,9 @@ export type BoxBorderStyles = Extract< 'none' | 'solid' | 'dashed' | 'auto' >; /** - * The box properties that support responsive values through container queries. + * Represents box props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveBoxProps = MakeResponsivePick< @@ -108,7 +159,7 @@ export interface BoxProps | 'overflow' > { /** - * The background color of the stack container. + * The background color of the component. * * @default 'transparent' */ @@ -117,10 +168,13 @@ export interface BoxProps 'transparent' | 'base' | 'subdued' | 'strong' >; /** - * Controls the thickness of the border on all sides. + * A border applied using shorthand syntax to specify width, color, and style in a single property. * - * When set, this overrides the width 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 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 */ @@ -133,10 +187,7 @@ export interface BoxProps > | Extract; /** - * 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 */ @@ -144,10 +195,7 @@ export interface BoxProps | MaybeAllValuesShorthandProperty | Extract; /** - * 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 */ @@ -156,101 +204,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 corners or fully rounded elements. + * The roundedness of the element's corners using the design system's radius scale. * * @default 'none' */ borderRadius: MaybeAllValuesShorthandProperty; /** - * The padding applied to all edges of the stack container. - * - * [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](/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](/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](/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](/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](/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](/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](/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. @@ -259,7 +291,7 @@ export interface BoxProps */ display: ResponsiveBoxProps['display']; /** - * The vertical size of the stack 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. @@ -270,31 +302,44 @@ 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 stack container. + * 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 stack container. + * 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 stack container. + * 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 stack container. + * 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 stack container. + * 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' */ @@ -302,12 +347,14 @@ export interface BoxProps } /** - * A version of the stack properties with all fields required. + * Represents the stack component props with all properties marked as required. * @publicDocs */ export type AlignedStackProps = Required; /** - * The stack properties that support responsive values through container queries. + * Represents stack props with responsive capabilities for layout properties. + * + * This enables conditional styling based on container queries. * @publicDocs */ export type ResponsiveStackProps = MakeResponsivePick< @@ -315,8 +362,7 @@ export type ResponsiveStackProps = MakeResponsivePick< 'gap' | 'rowGap' | 'columnGap' | 'direction' >; /** - * The properties for the stack component. A stack arranges its children in a single direction with controlled spacing and alignment along both axes. - * @publicDocs + * Configure the following properties on the stack component. */ export interface StackProps extends BoxProps, @@ -349,300 +395,132 @@ export interface StackProps */ alignContent: AlignContentKeyword; /** - * The spacing between children in the stack. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value to apply the same spacing to both axes (for example, `'large-100'`), or a pair of values (for example, `'large-100 large-500'`) to set different spacing for the block and inline axes. This property also accepts [responsive values](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value applied to both axes, such as `large-100` + * - A pair of values, such as `large-100 large-500`, to set the inline and block axes respectively + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default 'none' */ gap: ResponsiveStackProps['gap']; /** - * The spacing between children in the block axis (vertical in horizontal writing modes). This property overrides the row spacing set by the `gap` property. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value (for example, `'large-100'`), or a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements in the block axis. This overrides the row value of `gap`. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value, such as `large-100` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default '' - meaning no override */ rowGap: ResponsiveStackProps['rowGap']; /** - * The spacing between children in the inline axis (horizontal in left-to-right languages). This property overrides the column spacing set by the `gap` property. You can provide a single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value (for example, `'large-100'`), or a [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * Adjusts spacing between elements in the inline axis. This overrides the column value of `gap`. + * + * Accepts: + * - A single [`SpacingKeyword`](/docs/api/polaris/using-polaris-web-components#scale) value, such as `large-100` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported SpacingKeyword as a query value * * @default '' - meaning no override */ columnGap: ResponsiveStackProps['columnGap']; /** - * The direction in which the stack's children are laid out. Use `'inline'` to arrange children horizontally (with wrapping enabled), or `'block'` to arrange them vertically (without wrapping). This property also accepts [responsive values](/docs/api/polaris/using-polaris-web-components#responsive-values) using container query syntax. + * The direction in which the stack's children are placed within the stack. + * + * Accepts: + * - A single value, either `inline` or `block` + * - A [responsive value](/docs/api/polaris/using-polaris-web-components#responsive-values) string with the supported direction values as a query value * * @default 'block' * - * @implementation The content will wrap if the direction is `'inline'`, and won't wrap if the direction is `'block'`. + * @implementation the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' */ direction: ResponsiveStackProps['direction']; } -/** - * 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 & { - /** - * The function that renders the shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The optional CSS styles to apply to the shadow root. - */ - styles?: Styles; -}; -/** - * An interface representing the properties of an activation event, such as a click or keypress. - * @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 PC) 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); /** @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 base element class for Box components with all Box properties as accessors. - */ -declare class BoxElement extends PreactCustomElement implements BoxProps { +declare class BoxElement extends PolarisCustomElement implements BoxProps { constructor(renderImpl: RenderImpl); - /** - * The ARIA role that defines the semantic meaning of the stack for assistive technologies. - */ accessor accessibilityRole: BoxProps['accessibilityRole']; - /** - * The background color of the stack using the design system's color scale. Choose from `transparent`, `subdued`, `base`, or `strong`. - */ accessor background: BoxProps['background']; - /** - * The height of the stack in horizontal writing modes, or width in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor blockSize: BoxProps['blockSize']; - /** - * The minimum height of the stack in horizontal writing modes, or minimum width in vertical writing modes. - * Prevents the stack from shrinking below this size. - */ accessor minBlockSize: BoxProps['minBlockSize']; - /** - * The maximum height of the stack in horizontal writing modes, or maximum width in vertical writing modes. - * Prevents the stack from growing beyond this size. - */ accessor maxBlockSize: BoxProps['maxBlockSize']; - /** - * The width of the stack in horizontal writing modes, or height in vertical writing modes. - * Use this for flow-relative sizing that adapts to text direction. - */ accessor inlineSize: BoxProps['inlineSize']; - /** - * The minimum width of the stack in horizontal writing modes, or minimum height in vertical writing modes. - * Prevents the stack from shrinking below this size. - */ accessor minInlineSize: BoxProps['minInlineSize']; - /** - * The maximum width of the stack in horizontal writing modes, or maximum height in vertical writing modes. - * Prevents the stack from growing beyond this size. - */ accessor maxInlineSize: BoxProps['maxInlineSize']; - /** - * Controls how content that exceeds the stack's boundaries is displayed. Use `hidden` to clip overflow or `visible` to allow content to extend beyond boundaries. - */ accessor overflow: BoxProps['overflow']; - /** - * The spacing applied inside the stack on all sides, creating distance between the stack's edges and its content. - */ accessor padding: BoxProps['padding']; - /** - * The vertical padding (top and bottom) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingBlock: BoxProps['paddingBlock']; - /** - * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes. - */ accessor paddingBlockStart: BoxProps['paddingBlockStart']; - /** - * The padding at the bottom in horizontal writing modes, or at the end edge in vertical writing modes. - */ accessor paddingBlockEnd: BoxProps['paddingBlockEnd']; - /** - * The horizontal padding (left and right) in horizontal writing modes. - * Use this for flow-relative padding that adapts to text direction. - */ accessor paddingInline: BoxProps['paddingInline']; - /** - * The padding at the left in left-to-right languages, or at the right in right-to-left languages. - */ accessor paddingInlineStart: BoxProps['paddingInlineStart']; - /** - * The padding at the right in left-to-right languages, or at the left in right-to-left languages. - */ accessor paddingInlineEnd: BoxProps['paddingInlineEnd']; - /** - * Applies a border using shorthand syntax to specify width, color, and style in a single property. - */ accessor border: BoxProps['border']; - /** - * Controls the thickness of the border on all sides. When set, this overrides the width value specified in the `border` property. - */ accessor borderWidth: BoxProps['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. - */ accessor borderStyle: BoxProps['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. - */ accessor borderColor: BoxProps['borderColor']; - /** - * Controls the roundedness of the element's corners using the design system's radius scale. - */ accessor borderRadius: BoxProps['borderRadius']; - /** - * A text description of the stack for screen readers, used when the visual context isn't sufficient for understanding. - */ accessor accessibilityLabel: BoxProps['accessibilityLabel']; - /** - * Controls the visibility of the stack for both visual and assistive technology users. Use `hidden` to hide from screen readers or `exclusive` to hide visually but announce to screen readers. - */ accessor accessibilityVisibility: BoxProps['accessibilityVisibility']; - /** - * Controls how the stack is displayed in the layout, such as block, inline, or none. - */ accessor display: BoxProps['display']; } /** - * 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A stack is a layout component that arranges its children in a single direction with controlled spacing and alignment. + * Configure the following properties on the stack component. + * @publicDocs */ declare class Stack extends BoxElement implements StackProps { constructor(); - /** - * The direction in which the stack's children are arranged. - */ accessor direction: StackProps['direction']; - /** - * Controls the distribution of children along the inline axis (horizontally in horizontal writing modes). - */ accessor justifyContent: StackProps['justifyContent']; - /** - * Controls the alignment of children along the block axis (vertically in horizontal writing modes). - */ accessor alignItems: StackProps['alignItems']; - /** - * Controls the distribution of lines along the block axis when content wraps into multiple lines. - */ accessor alignContent: StackProps['alignContent']; - /** - * The spacing between the stack's children. - */ accessor gap: StackProps['gap']; - /** - * The spacing between rows in the stack. - */ accessor rowGap: StackProps['rowGap']; - /** - * The spacing between columns in the stack. - */ accessor columnGap: StackProps['columnGap']; } declare global { @@ -659,15 +537,11 @@ declare module 'preact' { } declare const tagName = 's-stack'; -/** - * The properties for the stack component when it's used in JSX. - * @publicDocs - */ export interface StackJSXProps extends Partial, Pick { /** - * The child elements to render inside the stack. + * The child elements displayed within the stack component, which are arranged vertically or horizontally with consistent spacing. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Switch.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Switch.d.ts index b2b54ae266..8a24eb573b 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Switch.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Switch.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,21 +10,30 @@ import type { TextFieldProps, CheckboxProps, SwitchProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event that includes a strongly-typed reference to the element that triggered it. + * 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 = Event & { - /** - * The element that the event handler was attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A function that handles events for a specific element type, or null if no handler is set. + * 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 = @@ -32,170 +41,93 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** Used when an element does not have children. * @publicDocs +/** + * 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 { /** - * 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; /** - * 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; } -/** - * CSS styles that will be applied to the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * Configuration for rendering a custom element with Preact and shadow DOM. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * A function that renders the component's content inside the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * CSS styles that will be applied to the shadow DOM. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * Information about modifier keys and mouse buttons that were active during an interaction. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down during the interaction. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on Mac, Windows key on PC) was held down during the interaction. - */ - metaKey: boolean; - /** - * Whether the Control key was held down during the interaction. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed during the interaction. - */ - button: number; -} -/** - * Options for influencing how a programmatic click behaves. - * @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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The core properties that all input elements need to function within forms. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** - * Base class for input elements that participate in form submission. - */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { - /** - * Indicates that this element can participate in form submission. - */ static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's triggered when the input's value changes and the field loses focus. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's triggered when the input's value changes as the user types. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the input is disabled and can't be interacted with. - */ accessor disabled: PreactInputProps['disabled']; - /** - * A unique identifier for the input element. - */ accessor id: PreactInputProps['id']; - /** - * The name that identifies this input when the form is submitted. - */ accessor name: PreactInputProps['name']; - /** - * The current value of the input. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } -/** - * Properties that are common to checkbox-style components. - * @publicDocs - */ export interface PreactCheckboxProps extends Required< Pick< @@ -212,20 +144,15 @@ export interface PreactCheckboxProps > > { /** - * The value that's submitted with the form when the checkbox is checked. + * The value used in form data when the checkbox is checked. */ value: Required['value']; } -/** - * Base class for checkbox-style elements that can be toggled on and off. - */ declare class PreactCheckboxElement extends PreactInputElement implements PreactCheckboxProps { - /** - * Whether the checkbox is currently checked. - */ + accessor onblur: CallbackEventListener<'input'>; get checked(): boolean; set checked(checked: PreactCheckboxProps['checked']); /** @@ -233,29 +160,11 @@ declare class PreactCheckboxElement */ get value(): string; set value(value: string); - /** - * Whether the checkbox should be checked when it's first rendered. - */ accessor defaultChecked: PreactCheckboxProps['defaultChecked']; - /** - * A label that's only visible to screen readers, used when the visual label isn't descriptive enough. - */ accessor accessibilityLabel: PreactCheckboxProps['accessibilityLabel']; - /** - * Additional text to provide context or guidance for the checkbox. - */ accessor details: PreactCheckboxProps['details']; - /** - * An error message that's displayed below the checkbox when validation fails. - */ accessor error: PreactCheckboxProps['error']; - /** - * The text that describes what the checkbox is for. - */ accessor label: PreactCheckboxProps['label']; - /** - * Whether the checkbox must be checked before the form can be submitted. - */ accessor required: PreactCheckboxProps['required']; /** @private */ formResetCallback(): void; @@ -264,21 +173,25 @@ declare class PreactCheckboxElement } /** - * Properties for rendering a switch that lets users toggle a setting on or off with a sliding control interface. - * @publicDocs + * Configure the following properties on the switch component. */ export interface SwitchProps extends PreactCheckboxProps, Required> {} +declare abstract class SwitchBase + extends PreactCheckboxElement + implements Pick +{ + accessor labelAccessibilityVisibility: SwitchProps['labelAccessibilityVisibility']; + constructor(renderImpl: RenderImpl); +} + /** - * A switch that lets users toggle a setting on or off with a sliding control. + * Configure the following properties on the switch component. + * @publicDocs */ -declare class Switch extends PreactCheckboxElement implements SwitchProps { - /** - * Controls whether the label is visible to all users or only to screen readers. - */ - accessor labelAccessibilityVisibility: SwitchProps['labelAccessibilityVisibility']; +declare class Switch extends SwitchBase implements SwitchProps { constructor(); } declare global { @@ -295,21 +208,18 @@ declare module 'preact' { } declare const tagName = 's-switch'; -/** - * Properties for using the switch component in JSX with React-style event handlers. - * @publicDocs - */ export interface SwitchJSXProps extends Partial, Pick { /** - * A callback that's triggered when the switch's checked state changes and it loses focus. + * A callback fired when the switch state changes and the user has finished interacting with it. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's triggered when the switch's checked state changes as the user interacts with it. + * A callback fired when the switch state changes, including intermediate states during user interaction. */ onInput?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; } export {Switch}; diff --git a/packages/ui-extensions/src/surfaces/admin/components/Table.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Table.d.ts index 10149dc1f5..da30f7b584 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Table.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Table.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,11 +10,46 @@ import type { ComponentChildren, TableProps$1, TableHeaderProps$1, + 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'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 table component. - * @publicDocs + * Configure the following properties on the table component. */ export interface TableProps extends Required< @@ -24,13 +59,23 @@ export interface TableProps > > { /** - * The display variant of the table. Use `list` to force a list view, or `auto` to automatically switch between table and list based on the available space. + * The layout variant of the table component. + * + * - `list`: Always displays as a list layout. + * - `auto`: Automatically displays as a table on wide screens and as a list on narrow screens. + * + * @default 'auto' */ variant: Extract; } /** - * The format type for a table header, which determines how the cell content is displayed. + * Represents the format options for table headers that control styling and alignment of column content. + * + * Available values: + * - `base`: Standard format for text columns + * - `currency`: Right-aligned format for monetary values + * - `numeric`: Right-aligned format for numeric values * @publicDocs */ export type HeaderFormat = Extract< @@ -38,203 +83,66 @@ export type HeaderFormat = Extract< 'base' | 'currency' | 'numeric' >; /** - * The properties you can set on a table header component. - * @publicDocs + * The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting. + * + * Table header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body. */ export interface TableHeaderProps extends Pick { /** - * The slot where this header's data appears in list view. The options include `primary` for the main content, `secondary` for supporting text, `labeled` for labeled data, `kicker` for small text above the primary content, or `inline` for inline content. + * The content designation for this column when the table displays in list variant on mobile devices. + * + * @default 'labeled' */ listSlot: Extract< TableHeaderProps$1['listSlot'], 'primary' | 'secondary' | 'labeled' | 'kicker' | 'inline' >; /** - * The format of the header, which affects how the cell content is aligned and displayed. Use `base` for standard text, `currency` for monetary values, or `numeric` for numbers. + * The format of the column that controls styling and alignment of cell content. + * + * @default 'base' */ format: HeaderFormat; } +declare const actualTableVariantSymbol: unique symbol; +declare const tableHeadersSharedDataSymbol: unique symbol; /** - * 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 & { - /** - * 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). - */ - button: number; -} -/** - * The options for customizing how a synthetic click is performed. + * Represents the actual rendered variant of a table component. + * - `table`: Displays as a traditional table layout. + * - `list`: Displays as a list layout. * @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; -} -/** - * 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); +export type ActualTableVariant = 'table' | 'list'; +declare const elementInternals: unique symbol; - /** @private */ - setAttribute(name: string, value: string): void; - /** @private */ - attributeChangedCallback(name: string): void; +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); /** @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; -} - -/** - * A context object that provides a default value of a specific type. - * @publicDocs - */ -export interface Context { - /** - * The default value for this context. - */ - readonly defaultValue: T; -} -/** - * An extended context class that provides event-based updates when the context value changes. - */ -declare class AddedContext extends EventTarget { - /** - * Creates a new context with the given default value. - */ - constructor(defaultValue: T); - /** - * The current value of the context. - */ - get value(): T; - /** - * Sets a new value for the context. - */ - set value(value: T); } /** - * A callback that a context requester provides, which is called with the value that satisfies the request. - * Context providers can call this callback multiple times as the requested value changes. - * @publicDocs - */ -export type ContextCallback = (value: T) => void; -/** - * An event that a context requester fires to signal it wants a named context. + * An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. * - * A provider should inspect the `context` property of the event to see if it has a value that can satisfy the request, and if so, call the `callback` with the requested value. - */ -declare class ContextRequestEvent extends Event { - /** - * The context that's being requested. - */ - readonly context: Context; - /** - * The callback to call with the requested context value. - */ - readonly callback: ContextCallback; - /** - * Creates a new context request event with the given context and callback. - */ - constructor(context: Context, callback: ContextCallback); -} -declare global { - interface HTMLElementEventMap { - /** - * A 'context-request' event can be emitted by any element which desires - * a context value to be injected by an external provider. - */ - 'context-request': ContextRequestEvent; - } -} - -/** @private */ -declare const actualTableVariantSymbol: unique symbol; -/** @private */ -declare const tableHeadersSharedDataSymbol: unique symbol; -/** - * The actual display variant of the table, which is either a traditional table or a list. - * @publicDocs - */ -export type ActualTableVariant = 'table' | 'list'; - -/** - * An event that includes a strongly typed `currentTarget` property based on the element tag name. + * This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event. * @publicDocs */ export type CallbackEvent = Event & { - /** - * The element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * An event listener function that receives a strongly typed callback event, or `null` if no listener is attached. + * 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 = @@ -243,71 +151,63 @@ export type CallbackEventListener = }) | 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } /** - * A component that displays data in a structured table format that automatically adapts to the available space. + * Configure the following properties on the table component. + * @publicDocs */ -declare class Table extends PreactCustomElement implements TableProps { - /** - * The display variant of the table. - */ +declare class Table extends PolarisCustomElement implements TableProps { + /** @private */ + [elementInternals]: ElementInternals; accessor variant: TableProps['variant']; /** - * Whether the table is currently in a loading state. + * Whether the table is in a loading state, such as during initial page load or when loading the next page in a paginated table. When `true`, the table might be in an inert state that prevents user interaction. */ accessor loading: TableProps['loading']; - /** - * Whether the pagination controls are displayed. - */ accessor paginate: TableProps['paginate']; - /** - * Whether there's a previous page of data that the user can navigate to. - */ accessor hasPreviousPage: TableProps['hasPreviousPage']; - /** - * Whether there's a next page of data that the user can navigate to. - */ accessor hasNextPage: TableProps['hasNextPage']; - /** - * The event listener that's called when the user navigates to the previous page. - */ accessor onpreviouspage: CallbackEventListener | null; - /** - * The event listener that's called when the user navigates to the next page. - */ accessor onnextpage: CallbackEventListener | null; /** * @private * The actual table variant, which is either 'table' or 'list'. */ - [actualTableVariantSymbol]: AddedContext; + [actualTableVariantSymbol]: _shopify_admin_web_component_foundations.AddedContext; /** @private */ - [tableHeadersSharedDataSymbol]: AddedContext< + [tableHeadersSharedDataSymbol]: _shopify_admin_web_component_foundations.AddedContext< { listSlot: TableHeaderProps['listSlot']; textContent: string; @@ -315,9 +215,6 @@ declare class Table extends PreactCustomElement implements TableProps { }[] >; - /** - * Creates a new Table instance. - */ constructor(); } declare global { @@ -334,23 +231,16 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table component. - */ declare const tagName = 's-table'; -/** - * The JSX properties you can set on a table component. - * @publicDocs - */ export interface TableJSXProps extends Partial, Pick { /** - * The content to display inside the table, which should include table header row, table body, and table row components. + * The table structure displayed within the table component, including table headers, rows, and cells that organize data in a grid format. */ children?: ComponentChildren; /** - * Additional filters to display in the table. For example, you can use the search field component to filter the table data. + * Additional filters to display in the table, such as search fields or other input components that allow users to narrow down the displayed data. */ filters?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TableBody.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TableBody.d.ts index 225275d073..380c3412fd 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TableBody.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TableBody.d.ts @@ -1,146 +1,116 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, TableBodyProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + TableBodyProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * The properties you can set on a table body component. - * @publicDocs - */ -export interface TableBodyProps extends TableBodyProps$1 {} - -/** - * 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 & { - /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * 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). - */ - button: number; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } + /** - * The options for customizing how a synthetic click is performed. - * @publicDocs + * The table body component represents the main content area of a table, containing the data rows. Use table body as a child of table to structure your table data, with each table row within the body representing a single record or entry. + * + * Table body must contain table row components, which in turn contain table cell components for the actual data values. */ -export interface ClickOptions { +export interface TableBodyProps extends TableBodyProps$1 { /** - * 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. + * The rows containing the main data content of the table. + * In the `table` variant, this represents the semantic table body. In the `list` variant, this might not have semantic meaning but still contains the data rows. */ - sourceEvent?: ActivationEventEsque; + children?: TableBodyProps$1['children']; } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +declare const elementInternals: unique symbol; + /** - * A component that wraps the body content of a table, which contains the data rows. + * The table body component represents the main content area of a table, containing the data rows. Use table body as a child of table to structure your table data, with each table row within the body representing a single record or entry. + * + * Table body must contain table row components, which in turn contain table cell components for the actual data values. + * @publicDocs */ -declare class TableBody extends PreactCustomElement implements TableBodyProps { - /** - * Creates a new TableBody instance. - */ +declare class TableBody extends PolarisCustomElement implements TableBodyProps { + /** @private */ + [elementInternals]: ElementInternals; constructor(); } declare global { @@ -157,19 +127,13 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table body component. - */ declare const tagName = 's-table-body'; -/** - * The JSX properties you can set on a table body component. - * @publicDocs - */ export interface TableBodyJSXProps extends Partial, Pick { /** - * The body content of the table, which should include table row components. This content might not have any semantic meaning when the table uses the `list` variant. + * The rows containing the main data content of the table. + * In the `table` variant, this represents the semantic table body. In the `list` variant, this might not have semantic meaning but still contains the data rows. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TableCell.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TableCell.d.ts index c3ffea3cf3..2cc40e0463 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TableCell.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TableCell.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,140 +9,106 @@ import type { ComponentChildren, TableCellProps$1, TableHeaderProps, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * The properties you can set on a table cell component. - * @publicDocs - */ -export interface TableCellProps extends TableCellProps$1 {} - -/** - * 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 & { - /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * 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). - */ - button: number; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } + /** - * The options for customizing how a synthetic click is performed. - * @publicDocs + * The table cell component represents a single data cell within a table row. Use table cell as a child of table row to display individual data values, with each cell corresponding to a column in the table. + * + * Table cell automatically inherits styling and alignment from its parent table structure and supports text content or other inline components. */ -export interface ClickOptions { +export interface TableCellProps extends TableCellProps$1 { /** - * 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. + * The content displayed within the table cell, which represents a single data point in the table's grid structure. */ - sourceEvent?: ActivationEventEsque; + children?: TableCellProps$1['children']; } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** @private */ declare const headerFormatSymbol: unique symbol; /** - * The format type for a table header, which determines how the cell content is displayed. + * Represents the format options for table headers that control styling and alignment of column content. + * + * Available values: + * - `base`: Standard format for text columns + * - `currency`: Right-aligned format for monetary values + * - `numeric`: Right-aligned format for numeric values * @publicDocs */ export type HeaderFormat = Extract< @@ -150,13 +116,17 @@ export type HeaderFormat = Extract< 'base' | 'currency' | 'numeric' >; +declare const elementInternals: unique symbol; + /** - * A component that represents a single cell in a table row, which displays data in a format that's determined by its column header. + * The table cell component represents a single data cell within a table row. Use table cell as a child of table row to display individual data values, with each cell corresponding to a column in the table. + * + * Table cell automatically inherits styling and alignment from its parent table structure and supports text content or other inline components. + * @publicDocs */ -declare class TableCell extends PreactCustomElement implements TableCellProps { - /** - * Creates a new TableCell instance. - */ +declare class TableCell extends PolarisCustomElement implements TableCellProps { + /** @private */ + [elementInternals]: ElementInternals; constructor(); /** @private */ get [headerFormatSymbol](): HeaderFormat; @@ -177,19 +147,12 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table cell component. - */ declare const tagName = 's-table-cell'; -/** - * The JSX properties you can set on a table cell component. - * @publicDocs - */ export interface TableCellJSXProps extends Partial, Pick { /** - * The content to display inside the table cell. + * The content displayed within the table cell, which represents a single data point in the table's grid structure. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TableHeader.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TableHeader.d.ts index bbcd13d604..c67cec5444 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TableHeader.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TableHeader.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,10 +6,53 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, TableHeaderProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + TableHeaderProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 format type for a table header, which determines how the cell content is displayed. + * Represents the format options for table headers that control styling and alignment of column content. + * + * Available values: + * - `base`: Standard format for text columns + * - `currency`: Right-aligned format for monetary values + * - `numeric`: Right-aligned format for numeric values * @publicDocs */ export type HeaderFormat = Extract< @@ -17,163 +60,87 @@ export type HeaderFormat = Extract< 'base' | 'currency' | 'numeric' >; /** - * The properties you can set on a table header component. - * @publicDocs + * The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting. + * + * Table header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body. */ export interface TableHeaderProps extends Pick { /** - * The slot where this header's data appears in list view. The options include `primary` for the main content, `secondary` for supporting text, `labeled` for labeled data, `kicker` for small text above the primary content, or `inline` for inline content. + * The content designation for this column when the table displays in list variant on mobile devices. + * + * @default 'labeled' */ listSlot: Extract< TableHeaderProps$1['listSlot'], 'primary' | 'secondary' | 'labeled' | 'kicker' | 'inline' >; /** - * The format of the header, which affects how the cell content is aligned and displayed. Use `base` for standard text, `currency` for monetary values, or `numeric` for numbers. + * The format of the column that controls styling and alignment of cell content. + * + * @default 'base' */ format: HeaderFormat; } -/** - * 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 & { - /** - * 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). - */ - 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; -} -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +declare const elementInternals: unique symbol; + /** - * A component that defines a column header in a table, which specifies both the header label and how the column's data should be formatted. + * The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting. + * + * Table header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body. + * @publicDocs */ declare class TableHeader - extends PreactCustomElement + extends PolarisCustomElement implements TableHeaderProps { - /** - * The slot where this header's data appears when the table is shown in list view. - */ + /** @private */ + [elementInternals]: ElementInternals; accessor listSlot: TableHeaderProps['listSlot']; - /** - * The format of the header and its corresponding cells. - */ accessor format: TableHeaderProps['format']; - /** - * Creates a new TableHeader instance. - */ constructor(); } declare global { @@ -190,19 +157,12 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table header component. - */ declare const tagName = 's-table-header'; -/** - * The JSX properties you can set on a table header component. - * @publicDocs - */ export interface TableHeaderJSXProps extends Partial, Pick { /** - * The heading of the column when the table uses the `table` variant, and the label of its data when the table uses the `list` variant. + * The heading of the column in the `table` variant, and the label of its data in `list` variant. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TableHeaderRow.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TableHeaderRow.d.ts index c19fbc593a..81bc04bdc0 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TableHeaderRow.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TableHeaderRow.d.ts @@ -1,149 +1,119 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, TableHeaderRowProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + TableHeaderRowProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * The properties you can set on a table header row component. - * @publicDocs - */ -export interface TableHeaderRowProps extends TableHeaderRowProps$1 {} - -/** - * 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 & { - /** - * 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 + * The table header row component represents the header row of a table, containing column headings. Use table header row as the first child of table (before table body) to define the table structure and provide column labels. + * + * Table header row must contain table header components for each column. These headers provide context for the data columns and can support sorting functionality. */ -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; +export interface TableHeaderRowProps extends TableHeaderRowProps$1 { /** - * 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 header cells that define the columns of the table. + * Only accepts table header components as children, with each header representing a column and providing its label. */ - button: number; + children?: TableHeaderRowProps$1['children']; } -/** - * 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; + +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +declare const elementInternals: unique symbol; + /** - * A component that wraps the header row of a table, which contains the table header components that define the column structure. + * The table header row component represents the header row of a table, containing column headings. Use table header row as the first child of table (before table body) to define the table structure and provide column labels. + * + * Table header row must contain table header components for each column. These headers provide context for the data columns and can support sorting functionality. + * @publicDocs */ declare class TableHeaderRow - extends PreactCustomElement + extends PolarisCustomElement implements TableHeaderRowProps { - /** - * Creates a new TableHeaderRow instance. - */ + /** @private */ + [elementInternals]: ElementInternals; constructor(); /** @private */ connectedCallback(): void; @@ -164,19 +134,13 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table header row component. - */ declare const tagName = 's-table-header-row'; -/** - * The JSX properties you can set on a table header row component. - * @publicDocs - */ export interface TableHeaderRowJSXProps extends Partial, Pick { /** - * The content to display inside the table header row, which should include table header components. + * The header cells that define the columns of the table. + * Only accepts table header components as children, with each header representing a column and providing its label. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TableRow.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TableRow.d.ts index 83acd96ae5..40a0777e78 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TableRow.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TableRow.d.ts @@ -1,151 +1,129 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 2.23.0 **/ /* eslint-disable import/extensions */ /* eslint-disable @typescript-eslint/no-namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, TableRowProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + TableRowProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; -/** - * The properties you can set on a table row component. - * @publicDocs - */ -export interface TableRowProps - extends Pick {} - -/** - * 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 & { - /** - * The function that renders the component's shadow root content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the component. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + /** - * An object that resembles an activation event, containing information about which modifier keys were pressed and which mouse button was used. - * @publicDocs + * The table row component represents a single row of data within a table body. Use table row as a child of table body to structure individual records or entries in the table. + * + * Table row must contain table cell components, with each cell representing a data value for the corresponding column. The number of cells should match the number of headers in the table. */ -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; +export interface TableRowProps + extends Pick { /** - * 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 data cells displayed within this table row, with each cell containing content for its corresponding column. + * Only accepts table cell components as children. */ - button: number; -} -/** - * The options for customizing how a synthetic click is performed. - * @publicDocs - */ -export interface ClickOptions { + children?: TableRowProps$1['children']; /** - * 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. + * The ID of an interactive element, such as `s-link`, in the row that will be the target of the click when the row is clicked. + * This is the primary action for the row; it should not be used for secondary actions. + * + * This is a click-only affordance, and does not introduce any keyboard or screen reader affordances. + * Which is why the target element must be in the table; so that keyboard and screen reader users can interact with it normally. + * + * @implementation no focus or keyboard affordances are introduced by this property. No aria attributes need to be added to the table row. + * @implementation the row and/or delegate should have some affordance that indicates it is clickable. This may be a background color, a border, or a hover effect */ - sourceEvent?: ActivationEventEsque; + clickDelegate?: TableRowProps$1['clickDelegate']; } -/** - * 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); /** @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 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 { /** - * 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; /** - * 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; } /** - * 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 extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } +declare const elementInternals: unique symbol; + /** - * A component that represents a single row in a table, which contains the data cells. + * The table row component represents a single row of data within a table body. Use table row as a child of table body to structure individual records or entries in the table. + * + * Table row must contain table cell components, with each cell representing a data value for the corresponding column. The number of cells should match the number of headers in the table. + * @publicDocs */ -declare class TableRow extends PreactCustomElement implements TableRowProps { - /** - * Creates a new TableRow instance. - */ +declare class TableRow extends PolarisCustomElement implements TableRowProps { + /** @private */ + [elementInternals]: ElementInternals; constructor(); - /** - * A CSS selector for a child element that should handle clicks on the entire row. When you set this property, clicking anywhere on the row will trigger a click on the element that matches the selector. - */ accessor clickDelegate: string; } declare global { @@ -162,19 +140,13 @@ declare module 'preact' { } } -/** - * The custom element tag name for the table row component. - */ declare const tagName = 's-table-row'; -/** - * The JSX properties you can set on a table row component. - * @publicDocs - */ export interface TableRowJSXProps extends Partial, Pick { /** - * The content to display inside the row, which should include table cell components. + * The data cells displayed within this table row, with each cell containing content for its corresponding column. + * Only accepts table cell components as children. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/Text.d.ts b/packages/ui-extensions/src/surfaces/admin/components/Text.d.ts index 97743fdf19..da61dc2570 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/Text.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/Text.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,15 +6,69 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {ComponentChildren, TextProps$1} from './shared.d.ts'; +import type { + ComponentChildren, + TextProps$1, + PreactCustomElement, + RenderImpl, +} from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `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 {} + } +} + +declare const typographyFontWeights: readonly [ + 'auto', + 'base', + 'medium', + 'semibold', + 'bold', +]; +export type TypographyFontWeight = (typeof typographyFontWeights)[number]; +declare const bodyFontSizes: readonly [ + 'auto', + 'small-200', + 'small-100', + 'small', + 'base', + 'large', + 'large-100', +]; +export type BodyFontSize = (typeof bodyFontSizes)[number]; + +export type TextFontSize = BodyFontSize; +export type TextFontWeight = TypographyFontWeight; /** - * The properties for the text component. These properties define inline or small blocks of text content with various visual styles and semantic meanings. - * @publicDocs - */ -/** - * @publicDocs - * @publicDocs + * Configure the following properties on the text component. */ export interface TextProps extends Required< @@ -29,16 +83,11 @@ export interface TextProps | 'interestFor' > > { - /** - * The color of the text. Available options: - * - `'base'` - The default text color. - * - `'subdued'` - A lighter text color for secondary information. - */ color: Extract; /** * The semantic type and styling treatment for the text content. * - * Other presentation properties on Text override the default styling. + * Other presentation properties on text override the default styling. * * - `strong`: Emphasizes the text with strong importance, typically displayed in bold. * - `generic`: Standard text with no special semantic meaning or styling. @@ -49,7 +98,7 @@ export interface TextProps */ type: Extract< TextProps$1['type'], - 'strong' | 'generic' | 'address' | 'redundant' + 'address' | 'redundant' | 'strong' | 'generic' >; /** * The semantic tone that's applied to the text, which changes its color to convey meaning. @@ -66,193 +115,108 @@ export interface TextProps */ tone: Extract< TextProps$1['tone'], - 'info' | 'success' | 'warning' | 'critical' | 'auto' | 'neutral' | 'caution' + 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'caution' | 'critical' >; /** - * The numeric font variant for the text. Available options: - * - `'auto'` - The font variant is automatically determined. - * - `'normal'` - Standard numeric rendering. - * - `'tabular-nums'` - Monospaced numbers for better alignment in tables. + * @deprecated Use `Number` for inline numeric values instead. */ fontVariantNumeric: Extract< TextProps$1['fontVariantNumeric'], 'auto' | 'normal' | 'tabular-nums' >; -} - -/** - * A string containing CSS styles. - * @publicDocs - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a custom element with a shadow DOM. - * @publicDocs - * @publicDocs - */ -export type RenderImpl = Omit & { /** - * The function that renders the component's shadow DOM content. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * Optional CSS styles to apply to the shadow DOM. - */ - styles?: Styles; -}; -/** - * An object that represents the state of modifier keys and mouse button - * during an activation event like a click. - * @publicDocs - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the shift key was pressed during the event. - */ - shiftKey: boolean; - /** - * Whether the meta (Command on Mac, Windows key on PC) key was pressed. - */ - 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; -} -/** - * Options for customizing click behavior on an element. - * @publicDocs - * @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; -} -/** - * 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 + * Font size of the text. The named values also apply their matching + * line-height and letter-spacing. + * + * @default 'auto' */ - queueRender(): void; + fontSize: TextFontSize; /** - * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`. + * Font weight of the text. * - * 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 + * @default 'auto' */ - click({sourceEvent}?: ClickOptions): void; + fontWeight: TextFontWeight; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. - * @publicDocs + * 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 { /** - * 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; /** - * 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; } /** - * The base properties for Preact elements that have children, extending the base element properties to include child content. - * @publicDocs + * Base props for Preact custom elements with children support. Extends PreactBaseElementProps with the ability to render child elements. * @publicDocs */ export interface PreactBaseElementPropsWithChildren extends PreactBaseElementProps { + /** + * The child elements to be rendered within this component. + */ children?: preact.ComponentChildren; } -/** - * A custom element for displaying inline or small blocks of text with various visual styles and semantic meanings. Use Text to render short pieces of content with appropriate styling, emphasis, and color treatment. - */ -declare class Text extends PreactCustomElement implements TextProps { +declare class PolarisCustomElement extends PreactCustomElement { + constructor(renderImpl: Omit); + /** @private */ + connectedCallback(): void; + /** @private */ + adoptedCallback(): void; +} + +declare abstract class TextBase + extends PolarisCustomElement + implements + Pick< + TextProps, + | 'fontVariantNumeric' + | 'fontSize' + | 'fontWeight' + | 'color' + | 'type' + | 'dir' + | 'accessibilityVisibility' + | 'interestFor' + > +{ + accessor fontSize: TextProps['fontSize']; + accessor fontWeight: TextProps['fontWeight']; /** - * The numeric font variant for the text. + * @deprecated Use `Number` for inline numeric values instead. */ accessor fontVariantNumeric: TextProps['fontVariantNumeric']; - /** - * The color of the text. - */ accessor color: TextProps['color']; - /** - * The semantic tone that's applied to the text, which changes its color to convey meaning. - * - * - `info`: Informational content or helpful tips (blue). - * - `success`: Positive outcomes or successful states (green). - * - `warning`: Important warnings about potential issues (orange). - * - `critical`: Urgent problems or destructive actions (red). - * - `auto`: Automatically determined based on context. - * - `neutral`: General information without specific intent (gray). - * - `caution`: Advisory notices that need attention (yellow). - */ - accessor tone: TextProps['tone']; - /** - * The semantic type and styling treatment for the text content. - * - * - `strong`: Emphasizes the text with strong importance, typically displayed in bold. - * - `generic`: Standard text with no special semantic meaning or styling. - * - `address`: Marks the text as contact information, such as a physical or email address. - * - `redundant`: Indicates the text is redundant or duplicated information for screen reader context. - */ accessor type: TextProps['type']; - /** - * The text direction (left-to-right or right-to-left). - */ accessor dir: TextProps['dir']; - /** - * The visibility of the element to assistive technologies. - */ accessor accessibilityVisibility: TextProps['accessibilityVisibility']; - /** - * The ID of an element this text provides contextual information for. - */ accessor interestFor: string; + abstract tone: string; + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the text component. + * @publicDocs + */ +declare class Text extends TextBase implements TextProps { + accessor tone: TextProps['tone']; constructor(); } declare global { @@ -269,16 +233,11 @@ declare module 'preact' { } declare const tagName = 's-text'; -/** - * The JSX properties for the text component. These properties define how text is rendered in Preact or JSX. - * @publicDocs - * @publicDocs - */ export interface TextJSXProps extends Partial, Pick { /** - * The content of the text. + * The text content displayed within the text component, which applies semantic meaning and styling appropriate to the specified text type. */ children?: ComponentChildren; } diff --git a/packages/ui-extensions/src/surfaces/admin/components/TextArea.d.ts b/packages/ui-extensions/src/surfaces/admin/components/TextArea.d.ts index a4898d0158..edba50be5a 100644 --- a/packages/ui-extensions/src/surfaces/admin/components/TextArea.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components/TextArea.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,21 +9,30 @@ import type { TextFieldProps, TextAreaProps$1, - ComponentChildren, + PreactCustomElement, + RenderImpl, } from './shared.d.ts'; +import * as preact$1 from 'preact'; +import {ReactNode, RefAttributes} from 'react'; /** - * An event with a strongly-typed currentTarget property for 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 = Event & { - /** - * The element that the event listener is attached to. - */ currentTarget: HTMLElementTagNameMap[T]; }; /** - * A callback function that receives a strongly-typed event for 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 = @@ -31,189 +40,133 @@ export type CallbackEventListener = (event: CallbackEvent): void; }) | null; -/** - * The React-style event callback props for form field components. - * @publicDocs - */ export interface FieldReactProps { /** - * A callback that's invoked when the user makes any changes in the field. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * A callback fired when the user makes changes to the field value. This fires before `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * A callback fired when the user has finished editing the field, such as when they blur the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). + * A callback fired when the field receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * A callback that's invoked when the field loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * A callback fired when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; } /** - * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management. + * Props for field slot content (label, error, details) that accept + * either a string or JSX content in the React wrapper. + * + * Internal use only — not exported publicly. External consumers receive + * string-only types via FieldSlotPreactProps. + */ +export interface FieldSlotInternalReactProps { + error?: preact.ComponentChildren; + details?: preact.ComponentChildren; +} +/** + * Preact JSX string-only versions of field slot props. + * Used in Preact module declarations after Omit-ing the ComponentChildren + * versions (required by force-omit-react-slots lint rule). + */ +export interface FieldSlotPreactProps { + error?: string; + details?: string; +} +/** + * 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 { /** - * 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; /** - * 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; } -/** - * A string containing CSS styles for the component's shadow DOM. - * @publicDocs - */ -export type Styles = string; -/** - * The configuration for rendering a Preact component in a shadow root. - * @publicDocs - */ -export type RenderImpl = Omit & { - /** - * The function that renders the component's Preact elements into the shadow root. - */ - ShadowRoot: (element: any) => ComponentChildren; - /** - * The CSS styles to apply to the shadow root. - */ - styles?: Styles; +export type ReactIntrinsicElementChildren = + 'children' extends keyof PreactProps + ? { + children?: ReactNode; + } + : Record; +export type ReactIntrinsicElementProps< + PreactProps extends object, + ElementType, +> = Omit & + ReactIntrinsicElementChildren & + RefAttributes & { + slot?: Lowercase; + }; +export type ReactIntrinsicElements = { + [Tag in Exclude< + Extract, + `s-test-${string}` + >]: ReactIntrinsicElementProps< + preact$1.createElement.JSX.IntrinsicElements[Tag], + Tag extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[Tag] + : HTMLElement + >; }; -/** - * The properties from an event that indicate how the user activated an element. - * @publicDocs - */ -export interface ActivationEventEsque { - /** - * Whether the Shift key was held down when the event occurred. - */ - shiftKey: boolean; - /** - * Whether the Meta key (Command on macOS) was held down when the event occurred. - */ - metaKey: boolean; - /** - * Whether the Control key was held down when the event occurred. - */ - ctrlKey: boolean; - /** - * The mouse button that was pressed when the event occurred. A value of 0 indicates the primary button (usually left), 1 indicates the middle button, and 2 indicates the secondary button (usually right). - */ - button: number; -} -/** - * The options for influencing a programmatic 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; +declare module 'react' { + namespace JSX { + interface IntrinsicElements extends ReactIntrinsicElements {} + } } -/** - * 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); /** @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; } declare const internals: unique symbol; /** - * The base properties for an input element that participates in form submission. + * Represents the essential input props required for Preact-based input elements. Includes properties like `disabled`, `id`, `name`, and `value`. * @publicDocs */ export type PreactInputProps = Required< Pick >; -/** @private */ declare class PreactInputElement - extends PreactCustomElement + extends PolarisCustomElement implements PreactInputProps { static formAssociated: boolean; /** @private */ [internals]: ElementInternals; - /** - * A callback that's invoked when the user has finished editing the field, such as when they blur the field. - */ accessor onchange: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the user makes any changes in the field. - */ accessor oninput: CallbackEventListener<'input'>; - /** - * Whether the field is disabled, disallowing any interaction. - * - * @default false - */ accessor disabled: PreactInputProps['disabled']; - /** - * An identifier for the field. - */ accessor id: PreactInputProps['id']; - /** - * An identifier for the field that's unique within the nearest containing form. - */ accessor name: PreactInputProps['name']; - /** - * The current value for the field. - */ get value(): PreactInputProps['value']; set value(value: PreactInputProps['value']); constructor(renderImpl: RenderImpl); } /** - * The base properties for form field elements that support labels, validation, and autocomplete. + * Represents the props for Preact-based form field components with autocomplete support. The generic type parameter allows specifying the valid autocomplete values for the field. * @publicDocs */ export type PreactFieldProps = @@ -235,10 +188,10 @@ export type PreactFieldProps = * A hint as to the intended content of the field. * * When set to `on` (the default), this property indicates that the field should support - * autofill, but you don't have any more semantic information on the intended + * autofill, but you do not have any more semantic information on the intended * contents. * - * When set to `off`, you're indicating that this field contains sensitive + * When set to `off`, you are indicating that this field contains sensitive * information, or contents that are never saved, like one-time codes. * * Alternatively, you can provide value which describes the @@ -253,58 +206,20 @@ export type PreactFieldProps = */ autocomplete: Autocomplete; }; -/** @private */ declare class PreactFieldElement extends PreactInputElement implements PreactFieldProps { - /** - * A callback that's invoked when the field loses focus. - */ accessor onblur: CallbackEventListener<'input'>; - /** - * A callback that's invoked when the field receives focus. - */ accessor onfocus: CallbackEventListener<'input'>; - /** - * A hint as to the intended content of the field for autocomplete purposes. - */ accessor autocomplete: PreactFieldProps['autocomplete']; - /** - * The initial value for the field when it's first rendered. - */ accessor defaultValue: PreactFieldProps['defaultValue']; - /** - * Additional descriptive text to display below the field that provides supplementary information. - */ accessor details: PreactFieldProps['details']; - /** - * An error message to display below the field, indicating validation failure or other issues. - */ accessor error: PreactFieldProps['error']; - /** - * The text label to display for the field, describing what the user should enter. - */ accessor label: PreactFieldProps['label']; - /** - * Controls the visibility of the label for accessibility purposes. - */ accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility']; - /** - * The placeholder text that's displayed inside the field when it's empty, providing a hint about expected input. - */ accessor placeholder: PreactFieldProps['placeholder']; - /** - * Whether the field is read-only, preventing edits while still allowing focus and selection. - * - * @default false - */ accessor readOnly: PreactFieldProps['readOnly']; - /** - * Whether the field must be filled out before form submission. - * - * @default false - */ accessor required: PreactFieldProps['required']; /** * Global keyboard event handlers for things like key bindings typically @@ -334,7 +249,7 @@ declare class PreactFieldElement } /** - * The properties for the text area component. These properties configure a multi-line text input field that allows merchants to enter and edit longer text content. + * Represents the props for textarea components. Extends `PreactFieldProps` for multi-line text input functionality. * @publicDocs */ export type TextAreaProps = PreactFieldProps< @@ -342,30 +257,21 @@ export type TextAreaProps = PreactFieldProps< > & Required>; -/** - * The text area custom element class that renders a multi-line text input field in the Shopify admin interface. This component allows merchants to enter and edit longer text content with support for labels, validation, and length constraints. - */ -declare class TextArea +declare abstract class TextAreaBase extends PreactFieldElement - implements TextAreaProps + implements Pick { - /** - * The maximum number of characters the user can enter in the field. - */ accessor maxLength: TextAreaProps['maxLength']; - /** - * The minimum number of characters required in the field for validation. - */ accessor minLength: TextAreaProps['minLength']; - /** - * The number of visible text lines for the field, controlling its initial height. - */ accessor rows: TextAreaProps['rows']; - /** - * The current text value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input. - */ - get value(): string; - set value(value: string); + constructor(renderImpl: RenderImpl); +} + +/** + * Configure the following properties on the text area component. + * @publicDocs + */ +declare class TextArea extends TextAreaBase implements TextAreaProps { constructor(); } declare global { @@ -376,20 +282,19 @@ declare global { declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: TextAreaJSXProps & PreactBaseElementProps