From c5be7ac5a49b2ff4a9facd85bafe6b9811a38aec Mon Sep 17 00:00:00 2001 From: Britta Evans-Fenton Date: Thu, 4 Dec 2025 18:15:19 -0700 Subject: [PATCH] WIP - adding link, switch and tabs --- .../surfaces/point-of-sale/components.d.ts | 5576 +++++++++-------- .../point-of-sale/components/Link.d.ts | 65 + .../point-of-sale/components/Switch.d.ts | 59 + .../point-of-sale/components/Tab.d.ts | 49 + .../point-of-sale/components/TabList.d.ts | 49 + .../point-of-sale/components/TabPanel.d.ts | 49 + .../point-of-sale/components/Tabs.d.ts | 59 + .../components/targets/StandardComponents.ts | 5 + 8 files changed, 3409 insertions(+), 2502 deletions(-) create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Link.d.ts create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Switch.d.ts create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Tab.d.ts create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/TabList.d.ts create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/TabPanel.d.ts create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Tabs.d.ts diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts index e6f8ceb7ac..e45e74e613 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts @@ -12,101 +12,84 @@ * TODO: Update `any` type here after this is resolved * https://github.com/Shopify/ui-api-design/issues/139 */ -/** - * Represents any valid child content that can be rendered within a component. - */ export type ComponentChildren = any; -/** - * Represents text-only child content. - */ export type StringChildren = string; -/** - * Properties that are available on all components. - */ export interface GlobalProps { /** - * A unique identifier for the element within the document. This ID is used for multiple purposes: targeting the element from JavaScript code, creating relationships between elements (using `commandFor`, `interestFor`, ARIA attributes), linking labels to form controls, enabling fragment navigation with URL anchors (for example, `#section-id`), and applying element-specific styles. The ID must be unique across the entire page—duplicate IDs will cause unexpected behavior and accessibility issues. Use descriptive, semantic IDs that indicate the element's purpose (for example, `"checkout-button"`, `"main-nav"`, `"product-details-modal"`) rather than generic numbers or arbitrary strings. IDs are case-sensitive and should only contain letters, digits, hyphens, and underscores. If you don't need to reference the element externally, you can omit the ID. + * A unique identifier for the element. */ id?: string; } -/** - * Provides slots for primary and secondary action elements. - */ export interface ActionSlots { /** - * The primary action element to display, typically a `Button` or clickable link representing the most important action the user can take in the current context. This action should align with the user's primary goal or the main purpose of the interface. For example, "Save changes", "Checkout", "Add to cart", or "Submit order". The primary action typically receives visual emphasis through styling to draw user attention. Only one primary action should be provided to avoid confusion about the main call-to-action. If no primary action is needed, omit this property rather than providing an empty or placeholder action. + * The primary action to perform, provided as a button or link type element. */ primaryAction?: ComponentChildren; /** - * Secondary action elements to display, typically `Button` or clickable link elements representing alternative or supporting actions that are less important than the primary action. These might include "Cancel", "Save draft", "Skip", "Learn more", or other optional actions. Secondary actions receive less visual prominence than the primary action to maintain clear hierarchy. Multiple secondary actions can be provided and will typically be displayed together, often in a different visual style or position than the primary action. If no secondary actions are needed, omit this property. The order of actions in the array may affect their display order depending on the component. + * The secondary actions to perform, provided as button or link type elements. */ secondaryActions?: ComponentChildren; } -/** - * Properties for overlay lifecycle callbacks. - */ export interface BaseOverlayProps { /** - * Called when the overlay begins to appear, immediately after `showOverlay()` is called or the `hidden` property changes to `false`, but before any show animations start. The element may not be visible yet. Use this for initializing overlay content, fetching data needed for display, setting focus on the first interactive element, or tracking analytics events for when users begin viewing the overlay. Avoid layout calculations here as the element may not have final dimensions yet. + * Callback fired after the overlay is shown. */ onShow?: (event: Event) => void; /** - * Called after the overlay is fully visible and all show animations have completed. At this point, the overlay is completely rendered with final dimensions and positioning. Use this for operations that require the overlay to be fully displayed, such as focusing specific elements after animations complete, measuring rendered content dimensions, triggering secondary animations, or initializing interactive features that depend on final layout. This is the safest place for DOM measurements and layout-dependent operations. + * Callback fired when the overlay is shown **after** any animations to show the overlay have finished. */ onAfterShow?: (event: Event) => void; /** - * Called when the overlay begins to hide, immediately after `hideOverlay()` is called or the `hidden` property changes to `true`, but before any hide animations start. The element is still visible. Use this for cleanup operations, saving overlay state before it disappears, canceling pending requests, or preparing for the post-hide state. This is your last opportunity to interact with the visible overlay before animations begin. + * Callback fired after the overlay is hidden. */ onHide?: (event: Event) => void; /** - * Called after the overlay is completely hidden and all hide animations have finished. The element is no longer visible or interactive. Use this for final cleanup, focusing the element that triggered the overlay, navigating to another view, freeing resources, or performing operations that should only occur after the overlay is completely dismissed. This is the appropriate place for post-dismissal navigation or state updates that would be jarring if they occurred during animations. + * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished. */ onAfterHide?: (event: Event) => void; } /** - * Methods for controlling overlay visibility. These methods are required (not optional) because: + * Shared interfaces for web component methods. + * + * Methods are required (not optional) because: * - Components implementing this interface must provide all methods - * - Unlike props/attributes, methods aren't rendered in HTML but are JavaScript APIs + * - Unlike props/attributes, methods are not rendered in HTML but are JavaScript APIs * - Consumers expect these methods to be consistently available on all instances */ export interface BaseOverlayMethods { /** - * Programmatically displays the overlay element. When called, the overlay becomes visible and triggers any associated `onShow` and `onAfterShow` callbacks. Use this method to open modals, dialogs, or other overlay components in response to user actions or application state changes. + * Method to show an overlay. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ showOverlay: () => void; /** - * Programmatically hides the overlay element. When called, the overlay becomes hidden and triggers any associated `onHide` and `onAfterHide` callbacks. Use this method to close modals, dismiss dialogs, or hide overlay components programmatically rather than waiting for user interaction. + * Method to hide an overlay. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ hideOverlay: () => void; /** - * Programmatically toggles the overlay's visibility state. If currently visible, the overlay will be hidden; if currently hidden, it will be shown. This triggers the appropriate show/hide callbacks based on the resulting state. Use this method to create toggle buttons or cycle through overlay visibility states. + * Method to toggle the visiblity of an overlay. * * @implementation This is a method to be called on the element and not a callback and should hence be camelCase */ toggleOverlay: () => void; } -/** - * Properties for focus event callbacks. - */ export interface FocusEventProps { /** - * Called when focus is removed from the element, either by the user moving to another field (tabbing, clicking elsewhere) or programmatically using `blur()`. This event fires before `onChange` for modified fields. The event contains information about which element is receiving focus next (`relatedTarget`). Use this for triggering validation, saving in-progress changes, hiding related UI elements like autocomplete dropdowns, or tracking field interaction analytics. Common pattern: validate and show errors on blur to avoid disrupting users while they're still typing. + * Callback when the element loses focus. * - * Learn more about [blur events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event */ onBlur?: (event: FocusEvent) => void; /** - * Called when the element receives focus through user interaction (clicking, tabbing) or programmatic methods like `focus()`. This event fires before any input occurs. The event contains information about which element previously had focus (`relatedTarget`). Use this for showing helper text, highlighting the active field, displaying related UI like autocomplete suggestions, preselecting content, or tracking which fields users interact with. Common pattern: clear errors on focus to provide a fresh start when users re-attempt input after validation failure. Learn more about [focus events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). + * Callback when the element receives focus. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event */ onFocus?: (event: FocusEvent) => void; } -/** - * Defines the available size options for icons using a semantic scale. Provides granular control over icon dimensions from compact inline sizes to prominent display sizes. - */ export type SizeKeyword = | 'small-500' | 'small-400' @@ -121,27 +104,23 @@ export type SizeKeyword = | 'large-300' | 'large-400' | 'large-500'; -/** - * Defines the available color intensity options for icons. Controls the visual prominence and contrast of icon elements within the interface. - */ export type ColorKeyword = 'subdued' | 'base' | 'strong'; -/** - * A background color keyword including transparent option. - */ export type BackgroundColorKeyword = 'transparent' | ColorKeyword; -/** - * Properties for controlling the background color of an element. - */ export interface BackgroundProps { /** - * Sets the background color intensity of the element. Controls how the element stands out from its surroundings. + * Adjust the background of the element. * * @default 'transparent' */ background?: BackgroundColorKeyword; } /** - * Defines the semantic tone options for icons. Controls the color and visual emphasis based on the information type and importance being communicated. + * Tone is a property for defining the color treatment of a component. + * + * A tone can apply a grouping of colors to a component. For example, + * critical may have a specific text color and background color. + * + * In some cases, like for Banner, the tone may also affect the semantic and accessibility treatment of the component. * * @default 'auto' */ @@ -704,29 +683,17 @@ declare const privateIconArray: readonly [ 'x-circle', 'x-circle-filled', ]; -/** - * A valid icon identifier from the available icon set. - */ export type IconType = (typeof privateIconArray)[number]; /** * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type. */ export type ExtractStrict = Extract; -/** - * A utility type for properties that support [1-to-4-value shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box). - */ export type MaybeAllValuesShorthandProperty = | T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`; -/** - * Defines a shorthand property that accepts either a single value or two space-separated values for directional properties like padding and spacing. - */ export type MaybeTwoValuesShorthandProperty = T | `${T} ${T}`; -/** - * A utility type for values that can be responsive using container queries. - */ export type MaybeResponsive = T | `@container${string}`; /** * Prevents widening string literal types in a union to `string`. @@ -738,42 +705,41 @@ export type MaybeResponsive = T | `@container${string}`; */ export type AnyString = string & {}; /** - * A utility type that allows optional spacing in string literal values. + * This is purely to give the ability + * to have a space or not in the string literal types. * - * For example, in the `aspectRatio` property, `16/9` and `16 / 9` are both valid. + * For example in the `aspectRatio` property, `16/9` and `16 / 9` are both valid. */ export type optionalSpace = '' | ' '; export interface BadgeProps extends GlobalProps { /** - * The child elements to render within this component. + * The content of the Badge. */ children?: ComponentChildren; /** - * The semantic tone of the badge, based on the intention of the information being conveyed. Affects color and styling to communicate meaning. Badges rely on the tone system for semantic meaning, so using custom styling may not clearly convey meaning to merchants. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ tone?: ToneKeyword; /** - * The color intensity of the badge. Controls how prominent or subtle the badge appears within the interface. + * Modify the color to be more or less intense. * * @default 'base' */ color?: ColorKeyword; /** - * The icon identifier specifying which icon to display within the badge. Accepts any valid icon name from the icon set. + * The type of icon to be displayed in the badge. * * @default '' */ icon?: IconType | AnyString; /** - * The position of the icon relative to the badge text content: - * - `'start'`: Icon appears before the text - * - `'end'`: Icon appears after the text + * The position of the icon in relation to the text. */ iconPosition?: 'start' | 'end'; /** - * Adjusts the size of the badge and its icon. Available sizes range from `'small-500'` (smallest) through `'base'` (default) to `'large-500'` (largest), allowing you to match badge size to your interface hierarchy. + * Adjusts the size. * * @default 'base' */ @@ -781,46 +747,60 @@ export interface BadgeProps extends GlobalProps { } export interface BannerProps extends GlobalProps, ActionSlots { /** - * The title text displayed prominently at the top of the banner. This is the only property for text content—body text content isn't supported. You can't place `` or other text elements as children. + * The title of the banner. * * @default '' */ heading?: string; /** - * The child elements to render within this component. + * The content of the Banner. */ children?: ComponentChildren; /** - * Sets the visual appearance and accessibility behavior of the banner. The tone determines both the color scheme and how screen readers announce the banner. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context - * - `'success'` - Green styling for positive outcomes and successful operations. Creates an informative live region for screen readers - * - `'info'` - Blue styling for general information and neutral updates. Creates an informative live region for screen readers - * - `'warning'` - Orange styling for important notices that require attention. Creates an informative live region for screen readers - * - `'critical'` - Red styling for errors and urgent issues requiring immediate action. Creates an assertive live region that is announced immediately by screen readers. + * Sets the tone of the Banner, based on the intention of the information being conveyed. + * + * The banner is a live region and the type of status will be dictated by the Tone selected. * - * Learn more about [ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), [alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role), and [status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) on MDN. + * - `critical` creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately. + * - `neutral`, `info`, `success`, `warning` and `caution` creates an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message. + * + * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions + * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role + * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role * * @default 'auto' */ tone?: ToneKeyword; /** - * Whether the banner content can be collapsed and expanded. When `true`, the banner displays a collapse/expand toggle control and child elements are initially hidden. Users can click the toggle to reveal or hide the content. Use for lengthy banners or supplementary information that users can choose to view. Collapsed state persists during the component lifecycle but resets on re-render. + * Makes the content collapsible. + * A collapsible banner will conceal child elements initially, but allow the user to expand the banner to see them. * * @default false */ collapsible?: boolean; /** - * Whether a close button is displayed in the banner. When `true`, a close (X) button appears allowing users to permanently dismiss the banner. Once dismissed, the banner triggers the `onDismiss` callback and remains hidden until the component is re-rendered or the `hidden` property is changed. Use for non-critical notifications or messages that users can choose to dismiss after reading. + * Determines whether the close button of the banner is present. + * + * When the close button is pressed, the `dismiss` event will fire, + * then `hidden` will be true, + * any animation will complete, + * and the `afterhide` event will fire. * * @default false */ dismissible?: boolean; /** - * Called when the user dismisses the banner by clicking the close (X) button. This only fires for user-initiated dismissals through the UI close button, not when the banner is hidden programmatically using the `hidden` property. The callback fires after the user clicks but before hide animations begin. Use this for tracking dismissal metrics, saving user preferences to avoid showing the banner again, performing cleanup when banners are dismissed, or triggering follow-up actions. The banner remains in the DOM after dismissal (just hidden) until re-rendered—to completely remove it, control rendering at the component level based on dismissal state. + * Event handler when the banner is dismissed by the user. + * + * This does not fire when setting `hidden` manually. + * + * The `hidden` property will be `false` when this event fires. */ onDismiss?: (event: Event) => void; /** - * Called after the element is fully hidden and all hide animations have completed. + * Event handler when the banner has fully hidden. + * + * The `hidden` property will be `true` when this event fires. * * @implementation If implementations animate the hiding of the banner, * this event must fire after the banner has fully hidden. @@ -828,30 +808,35 @@ export interface BannerProps extends GlobalProps, ActionSlots { */ onAfterHide?: (event: Event) => void; /** - * Whether the banner is visible or hidden. When set to `true`, the banner is completely hidden from view and removed from the accessibility tree, meaning screen readers won't announce it. Changing this value triggers hide/show animations if configured. Unlike temporary dismissal with the close button, this provides programmatic control for conditional visibility based on application state, user permissions, or other dynamic conditions. + * Determines whether the banner is hidden. + * + * If this property is being set on each framework render (as in 'controlled' usage), + * and the banner is `dismissible`, + * ensure you update app state for this property when the `dismiss` event fires. + * + * If the banner is not `dismissible`, it can still be hidden by setting this property. * * @default false */ hidden?: boolean; } -/** - * Properties for controlling the display behavior of an element. - */ export interface DisplayProps { /** - * Sets the outer display type controlling the element's participation in flow layout. Use `'auto'` for default behavior or `'none'` to hide the element and remove it from the accessibility tree. - * Learn more about the [CSS display property on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/display). + * Sets the outer 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. * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display * @default 'auto' */ display?: MaybeResponsive<'auto' | 'none'>; } -/** - * Properties for defining the semantic role of an element for assistive technologies. - */ export interface AccessibilityRoleProps { /** - * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. + * Sets the semantic meaning of the component’s content. When set, + * the role will be used by assistive technologies to help users + * navigate the page. * * @implementation Although, in HTML hosts, this property changes the element used, * changing this property must not impact the visual styling of inside or outside of the box. @@ -941,7 +926,7 @@ export type AccessibilityRole = */ | 'separator' /** - * Used to define a live region containing advisory information for the user that isn't important enough to be an alert. + * Used to define a live region containing advisory information for the user that is not important enough to be an alert. * * In an HTML host `status` will render as `
`. * Learn more about the [`status` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) in the MDN web docs. @@ -955,48 +940,44 @@ export type AccessibilityRole = */ | 'alert' /** - * Used to create a container element with no specific semantic meaning. + * Used to create a nameless container element which has no semantic meaning on its own. * * In an HTML host `generic'` will render a `
` element. * Learn more about the [`generic` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) in the MDN web docs. */ | 'generic' /** - * Used to remove semantic meaning from an element while preserving its visual styling. + * Used to strip the semantic meaning of an element, but leave the visual styling intact. * * Synonym for `none` * Learn more about the [`presentation` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) in the MDN web docs. */ | 'presentation' /** - * Used to remove semantic meaning from an element while preserving its visual styling. + * Used to strip the semantic meaning of an element, but leave the visual styling intact. * * Synonym for `presentation` * Learn more about the [`none` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) in the MDN web docs. */ | 'none'; -/** - * Properties for controlling visibility to assistive technologies. - */ export interface AccessibilityVisibilityProps { /** - * Controls visibility for assistive technologies: - * - `'visible'`: Announced normally by screen readers - * - `'hidden'`: Hidden from screen readers while remaining visually visible - * - `'exclusive'`: Only this element is announced to screen readers, hiding other content + * Changes the visibility of the element. + * + * - `visible`: the element is visible to all users. + * - `hidden`: the element is removed from the accessibility tree but remains visible. + * - `exclusive`: the element is visually hidden but remains in the accessibility tree. * * @default 'visible' */ accessibilityVisibility?: 'visible' | 'hidden' | 'exclusive'; } -/** - * Properties for controlling the visibility of field labels to screen readers. - */ export interface LabelAccessibilityVisibilityProps { /** - * Controls whether the label is announced to screen readers: - * - `'visible'`: Label is announced normally by screen readers - * - `'exclusive'`: Only the label is announced, hiding other related content from screen readers + * 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' */ @@ -1005,35 +986,35 @@ export interface LabelAccessibilityVisibilityProps { 'visible' | 'exclusive' >; } -/** - * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system. - */ export type PaddingKeyword = SizeKeyword | 'none'; -/** - * Properties for controlling the padding (internal spacing) of an element. - */ export interface PaddingProps { /** - * The padding applied to all edges of the container. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Shorthand_properties#edges_of_a_box) using flow-relative values in the order: + * Adjust the padding of all edges. + * + * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is + * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is: * * - 4 values: `block-start inline-end block-end inline-start` * - 3 values: `block-start inline block-end` * - 2 values: `block inline` * * 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`. * - * An `auto` value inherits the default padding from the closest container that has removed its usual padding. + * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. * * @default 'none' */ padding?: MaybeResponsive>; /** - * The block-axis padding for the container. Overrides the block value of the `padding` property. + * Adjust the block-padding. + * + * - `large none` means block-start padding is `large`, block-end padding is `none`. + * + * This overrides the block value of `padding`. * * @default '' - meaning no override */ @@ -1041,19 +1022,27 @@ export interface PaddingProps { MaybeTwoValuesShorthandProperty | '' >; /** - * The block-start padding for the container. Overrides the block-start value of the `paddingBlock` property. + * Adjust the block-start padding. + * + * This overrides the block-start value of `paddingBlock`. * * @default '' - meaning no override */ paddingBlockStart?: MaybeResponsive; /** - * The block-end padding for the container. Overrides the block-end value of the `paddingBlock` property. + * Adjust the block-end padding. + * + * This overrides the block-end value of `paddingBlock`. * * @default '' - meaning no override */ paddingBlockEnd?: MaybeResponsive; /** - * The inline-axis padding for the container. Supports two-value syntax where `large none` sets inline-start to `large` and inline-end to `none`. Overrides the inline value of the `padding` property. + * Adjust the inline padding. + * + * - `large none` means inline-start padding is `large`, inline-end padding is `none`. + * + * This overrides the inline value of `padding`. * * @default '' - meaning no override */ @@ -1061,87 +1050,82 @@ export interface PaddingProps { MaybeTwoValuesShorthandProperty | '' >; /** - * The inline-start padding for the container. Overrides the inline-start value of the `paddingInline` property. + * Adjust the inline-start padding. + * + * This overrides the inline-start value of `paddingInline`. * * @default '' - meaning no override */ paddingInlineStart?: MaybeResponsive; /** - * The inline-end padding for the container. Overrides the inline-end value of the `paddingInline` property. + * Adjust the inline-end padding. + * + * This overrides the inline-end value of `paddingInline`. * * @default '' - meaning no override */ paddingInlineEnd?: MaybeResponsive; } -/** - * Defines exact size measurements without automatic or unconstrained options. Limited to specific pixel values, percentages, or zero. - */ export type SizeUnits = `${number}px` | `${number}%` | `0`; -/** - * Defines size values that can be specified as exact measurements or automatic sizing. Supports pixel values, percentages, zero, or automatic sizing based on content. - */ export type SizeUnitsOrAuto = SizeUnits | 'auto'; -/** - * Defines size values that can be specified as exact measurements or no constraint. Supports pixel values, percentages, zero, or no maximum limit. - */ export type SizeUnitsOrNone = SizeUnits | 'none'; -/** - * Properties for controlling the dimensions of an element. - */ export interface SizingProps { /** - * The block size of the container. Auto automatically sizes based on the container's children. + * Adjust the block size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size * * @default 'auto' */ blockSize?: MaybeResponsive; /** - * The minimum block size constraint for the container. + * Adjust the minimum block size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size * * @default '0' */ minBlockSize?: MaybeResponsive; /** - * The maximum block size constraint for the container. + * Adjust the maximum block size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size * * @default 'none' */ maxBlockSize?: MaybeResponsive; /** - * The inline size of the container. Auto automatically sizes based on the container's children. + * Adjust the inline size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size * * @default 'auto' */ inlineSize?: MaybeResponsive; /** - * The minimum inline size constraint for the container. + * Adjust the minimum inline size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size * * @default '0' */ minInlineSize?: MaybeResponsive; /** - * The maximum inline size constraint for the container. + * Adjust the maximum inline size. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size * * @default 'none' */ maxInlineSize?: MaybeResponsive; } -/** - * A border line style keyword. - */ export type BorderStyleKeyword = | 'none' | 'solid' | 'dashed' | 'dotted' | 'auto'; -/** - * A border thickness keyword. - */ export type BorderSizeKeyword = SizeKeyword | 'none'; -/** - * A border radius keyword including maximum rounding option. - */ export type BorderRadiusKeyword = SizeKeyword | 'max' | 'none'; /** * Represents a shorthand for defining a border. It can be a combination of size, optionally followed by color, optionally followed by style. @@ -1150,12 +1134,17 @@ export type BorderShorthand = | BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`; -/** - * Properties for controlling the border styling of an element. - */ export interface BorderProps { /** - * Sets the border style, width, and color using shorthand syntax. Accepts a size keyword, optionally followed by a color keyword, optionally followed by a style keyword. + * Set the border via the shorthand property. + * + * This can be a size, optionally followed by a color, optionally followed by a style. + * + * If the color is not specified, it will be `base`. + * + * If the style is not specified, it will be `auto`. + * + * Values can be overridden by `borderWidth`, `borderStyle`, and `borderColor`. * * @example * // The following are equivalent: @@ -1166,49 +1155,82 @@ export interface BorderProps { */ border?: BorderShorthand; /** - * Sets the thickness of the border using size keywords. 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 edge. + * Set the width of the border. + * + * If set, it takes precedence over the `border` property's width. + * + * Like CSS, up to 4 values can be specified. + * + * If one value is specified, it applies to all sides. + * + * If two values are specified, they apply to the block sides and inline sides respectively. + * + * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively. + * + * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively. * * @default '' - meaning no override */ borderWidth?: MaybeAllValuesShorthandProperty | ''; /** - * Sets the line style of the border. Controls the visual pattern of the border lines (for example, solid, dashed, dotted). 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 edge. + * Set the style of the border. + * + * If set, it takes precedence over the `border` property's style. + * + * Like CSS, up to 4 values can be specified. + * + * If one value is specified, it applies to all sides. + * + * If two values are specified, they apply to the block sides and inline sides respectively. + * + * If three values are specified, they apply to the block-start, both inline sides, and block-end respectively. + * + * If four values are specified, they apply to the block-start, block-end, inline-start, and inline-end sides respectively. * * @default '' - meaning no override */ borderStyle?: MaybeAllValuesShorthandProperty | ''; /** - * Sets the color intensity of the border. Controls how prominent the border appears. + * Set the color of the border. + * + * If set, it takes precedence over the `border` property's color. * * @default '' - meaning no override */ borderColor?: ColorKeyword | ''; /** - * Sets the corner rounding radius of the 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 radii per corner. + * Set the radius of the border. + * + * [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) is + * supported. Note that, contrary to the CSS, it uses flow-relative values and the order is: + * + * - 4 values: `start-start start-end end-end end-start` + * - 3 values: `start-start (start-end & end-start) start-end` + * - 2 values: `(start-start & end-end) (start-end & end-start)` + * + * For example: + * - `small-100` means start-start, start-end, end-end and end-start border radii are `small-100`. + * - `small-100 none` means start-start and end-end border radii are `small-100`, start-end and end-start border radii are `none`. + * - `small-100 none large-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `none`. + * - `small-100 none large-100 small-100` means start-start border radius is `small-100`, start-end border radius is `none`, end-end border radius is `large-100` and end-start border radius is `small-100`. * * @defaultValue 'none' */ borderRadius?: MaybeAllValuesShorthandProperty; } -/** - * Properties for controlling overflow behavior when content exceeds container bounds. - */ export interface OverflowProps { /** - * Controls how the container handles content that exceeds its dimensions: - * - `'visible'`: Content extends beyond the container's boundaries without clipping or scrolling. Overflow content is fully visible and may overlap other elements. This is the default behavior and works well for containers that should expand to fit their content naturally. - * - `'hidden'`: Content that exceeds the container is clipped and hidden from view—users can't see or access the overflow content. No scrollbars appear. Use this for intentionally limiting visible content, creating masked effects, or preventing content from breaking layouts. Be cautious with accessibility—hidden content may include important information users can't access. - * - `'auto'`: Adds scrollbars automatically when content exceeds the container, allowing users to scroll to view overflow content. Scrollbars only appear when needed. Use for scrollable regions, content lists, or any container where users should access all content but space is limited. + * Sets the overflow behavior of the element. * - * Setting overflow establishes a new block formatting context, which affects layout behaviors like margin collapsing and positioning. + * - `hidden`: clips the content when it is larger than the element’s container. + * The element will not be scrollable and the users will not be able + * to access the clipped content by dragging or using a scroll wheel on a mouse. + * - `visible`: the content that extends beyond the element’s container is visible. * * @default 'visible' */ overflow?: 'hidden' | 'visible'; } -/** - * Base properties for box-like container elements. - */ export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, @@ -1218,396 +1240,400 @@ export interface BaseBoxProps BorderProps, OverflowProps { /** - * The child elements to render within this component. + * The content of the Box. */ children?: ComponentChildren; /** - * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. + * A label that describes the purpose or contents of the element. + * When set, it will be announced to users using assistive technologies and will provide them with more context. + * + * Only use this when the element's content is not enough context for users using assistive technologies. */ accessibilityLabel?: string; } -/** - * Base properties for box-like container elements with semantic role support. - */ export interface BaseBoxPropsWithRole extends BaseBoxProps, AccessibilityRoleProps {} -/** - * Properties for button-like interactive elements with form-related behavior. - */ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** - * The semantic meaning of the button action within a form context: - * - `'button'`: A standard button with no default form behavior - * - `'submit'`: Submits the containing form when activated - * - `'reset'`: Resets the containing form to its initial values when activated + * The behavior of the Button. + * + * - `submit`: Used to indicate the component acts as a submit button, meaning it submits the closest form. + * - `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). + * + * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set. * * @default 'button' */ type?: 'submit' | 'button' | 'reset'; /** - * Called when the element is clicked or activated. + * Callback when the Button is activated. + * This will be called before the action indicated by `type`. * - * Learn more about [click events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event). + * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event */ onClick?: (event: Event) => void; /** - * Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies. + * Disables the Button meaning it cannot be clicked or receive focus. * * @default false */ disabled?: boolean; /** - * Indicates whether the button action is currently in progress. When `true`, replaces all button content with a loading spinner and prevents additional clicks to avoid duplicate submissions. The button remains visually enabled but unresponsive to interaction. Set to `true` when starting an async operation (for example, API call, navigation) and back to `false` when the operation completes or fails. This provides user feedback during long-running operations and prevents race conditions from multiple rapid clicks. Custom loading indicators or partial content updates aren't supported. + * Replaces content with a loading indicator while a background action is being performed. + * + * This also disables the Button. * * @default false */ loading?: boolean; } -/** - * Properties for link-like interactive elements with navigation behavior. - */ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps { /** - * The URL to navigate to when the element is clicked or activated. Supports absolute URLs (for example, `https://shopify.com`), relative URLs (for example, `/products`), and anchor links (for example, `#section-id`). Navigation is triggered after the `onClick` event completes, allowing you to cancel navigation by preventing the default event action. The actual navigation behavior depends on the `target` property—same page, new tab, or external navigation. For security, browsers may block navigation to certain protocols or untrusted origins. Use this to create navigational links, external resource links, or in-app routing. + * The URL to link to. + * + * - If set, it will navigate to the location specified by `href` after executing the `click` event. + * - If a `commandFor` is set, the `command` will be executed instead of the navigation. */ href?: string; /** - * Specifies where to display the linked URL: - * - `'auto'`: The target is automatically determined based on the origin of the URL (typically behaves as `'_self'` but surfaces may handle cross-origin URLs differently). - * - `'_blank'`: Opens the URL in a new tab or window. - * - `'_self'`: Opens the URL in the same browsing context. - * - `'_parent'`: Opens the URL in the parent browsing context. - * - `'_top'`: Opens the URL in the topmost browsing context. - * - Custom string: Any other valid target name. + * Specifies where to display the linked URL. * - * Learn more about the [`target` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target). + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target + * + * 'auto': The target is automatically determined based on the origin of the URL. * * @implementation Surfaces can set specific rules on how they handle each URL. - * @implementation It's expected that the behavior of `auto` is as `_self` except in specific cases. + * @implementation It’s expected that the behavior of `auto` is as `_self` except in specific cases. * @implementation For example, a surface could decide to open cross-origin URLs in a new window (as `_blank`). * * @default 'auto' */ target?: 'auto' | '_blank' | '_self' | '_parent' | '_top' | AnyString; /** - * Treats the link as a file download instead of navigation. When set, clicking the link downloads the resource at the `href` URL rather than navigating to it. The value becomes the suggested filename shown in the download dialog or used by the browser's default save behavior (for example, `download="receipt.pdf"` saves as "receipt.pdf"). If the value is an empty string, the browser determines the filename from the URL or server headers. This only works for same-origin URLs (your app's domain) or `blob:` and `data:` URLs for security reasons—cross-origin URLs will navigate normally. Learn more about the [`download` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download). + * Causes the browser to treat the linked URL as a download with the string being the file name. + * Download only works for same-origin URLs or the `blob:` and `data:` schemes. + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download */ download?: string; /** - * Called when the element is clicked or activated. + * Callback when the link is activated. + * This will be called before navigating to the location specified by `href`. * - * Learn more about [click events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event). + * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event */ onClick?: (event: Event) => void; } -/** - * Properties for controlling interactions between elements using commands. - */ export interface InteractionProps { /** - * The ID of the target element that should respond when this element is clicked or activated. This creates a relationship where clicking this control (button, clickable) triggers an action on another element in the DOM. The target element must have a matching `id` attribute. Use with the `command` property to specify what action should occur (show, hide, toggle). This enables declarative element control without writing custom click handlers, improving accessibility and reducing JavaScript. Common use cases include: opening modals from buttons, toggling content visibility, showing/hiding sidebars, or controlling overlay states. If both `commandFor` and `onClick` are present, both will execute—the command action occurs first, then the click handler. - * Learn more about [`commandfor` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor). + * ID of a component that should respond to activations (e.g. clicks) on this component. + * + * See `command` for how to control the behavior of the target. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor */ commandFor?: string; /** - * The action to perform on the target element specified by `commandFor`: - * - `'--auto'`: Execute the target element's default action (typically show for overlays, or the element's primary interaction). - * - `'--show'`: Make the target element visible by calling its `showOverlay()` method or setting appropriate visibility properties. - * - `'--hide'`: Hide the target element by calling its `hideOverlay()` method or setting appropriate visibility properties. - * - `'--toggle'`: Switch the target element's visibility state—if visible, hide it; if hidden, show it. - * - `'--copy'`: Copy content to the clipboard (requires the target to be a compatible element with copy functionality). + * Sets the action the `commandFor` should take when this clickable is activated. + * + * See the documentation of particular components for the actions they support. * - * The command executes when this element is clicked, before any `onClick` handlers fire. If the target element doesn't support the specified command, the action may fail silently. - * Learn more about [button commands on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command). + * - `--auto`: a default action for the target component. + * - `--show`: shows the target component. + * - `--hide`: hides the target component. + * - `--toggle`: toggles the target component. + * - `--copy`: copies the target ClipboardItem. * * @default '--auto' + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy'; /** - * The ID of a target element that should respond to hover and focus events on this element, creating an "interest" relationship. When the user hovers over or focuses this element, the target element receives corresponding interest events, allowing it to preview or prepare content. This is useful for implementing tooltip-like previews, image zoom on hover, showing additional details before clicking, or loading content speculatively when the user shows interest. The target element must have a matching `id` and listen for interest events. Unlike `commandFor` which responds to clicks, this responds to hover and focus, providing earlier user intent signals. + * ID of a component that should respond to interest (e.g. hover and focus) on this component. */ interestFor?: string; } -/** - * Combined properties for elements that can behave as both buttons and links. - */ export interface BaseClickableProps extends ButtonBehaviorProps, LinkBehaviorProps {} export interface ButtonProps extends GlobalProps, BaseClickableProps { /** - * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. + * A label that describes the purpose or contents of the Button. It will be read to users using assistive technologies such as screen readers. + * + * Use this when using only an icon or the Button text is not enough context + * for users using assistive technologies. */ accessibilityLabel?: string; /** - * The child elements to render within this component. Button content must be plain text. + * The content of the Button. */ children?: ComponentChildren; /** - * The icon identifier specifying which icon to display. Accepts any valid icon name from the icon set. + * The type of icon to be displayed in the Button. * * @default '' */ icon?: IconType | AnyString; /** - * Controls how the element's width adapts to its container and content. + * The displayed inline width of the Button. + * + * - `auto`: the size of the button depends on the surface and context. + * - `fill`: the button will takes up 100% of the available inline size. + * - `fit-content`: the button will take up the minimum inline-size required to fit its content. * * @default 'auto' */ inlineSize?: 'auto' | 'fill' | 'fit-content'; /** - * Changes the visual appearance and prominence of the button: - * - `'auto'`: The variant is automatically determined by context - * - `'primary'`: Creates a prominent call-to-action button with high visual emphasis for the most important action on a screen - * - `'secondary'`: Provides a less prominent button appearance for supporting actions and secondary interactions - * - `'tertiary'`: Provides the least prominent button appearance for tertiary or optional actions + * Changes the visual appearance of the Button. * - * @default 'auto' + * @default 'auto' - the variant is automatically determined by the Button's context */ variant?: 'auto' | 'primary' | 'secondary' | 'tertiary'; /** - * Sets the tone of the button, based on the intention of the action being performed: - * - `'auto'`: Automatically determines the appropriate tone based on context - * - `'neutral'`: The standard tone for general actions and interactions - * - `'caution'`: Indicates actions that require careful consideration - * - `'warning'`: Alerts users to potential issues or important information - * - `'critical'`: Used for destructive actions like deleting or removing content + * Sets the tone of the Button based on the intention of the information being conveyed. * * @default 'auto' */ tone?: ToneKeyword; /** - * Indicates the language of the text content. Useful when text is in a different language than the rest of the page, allowing assistive technologies to invoke correct pronunciation. [Reference of language subtag values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). + * Indicate the text language. Useful when the text is in a different language than the rest of the page. + * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. + * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) */ lang?: string; } -/** - * Base properties for all form input elements. - */ export interface BaseInputProps { /** - * An identifier for the field that is unique within the nearest containing form. This name is used as the key when the form data is submitted. If omitted, the field's value won't be included in form submissions. Use meaningful names that describe the data being collected (for example, `"email"`, `"quantity"`, `"customer-note"`). + * An identifier for the field that is unique within the nearest containing form. */ name?: string; /** - * Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies. + * Disables the field, disallowing any interaction. * * @default false */ disabled?: boolean; } -/** - * Properties for controlled form input elements with value and change callbacks. - */ export interface InputProps extends BaseInputProps { /** - * Called when the user has committed a value change, typically triggered when the field loses focus (blur) after the value has been modified. Unlike `onInput`, this fires only once after editing is complete, not during typing. The event contains the finalized value. Use this for validation, saving data, or triggering actions that should occur after the user finishes editing rather than during typing. For controlled components, update the `value` prop in this callback. This is ideal for expensive operations like API calls that shouldn't happen on every keystroke. - * Learn more about [change events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * Callback when the user has **finished editing** a field, e.g. once they have blurred the field. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event */ onChange?: (event: Event) => void; /** - * Called immediately when the user makes any change to the field value. Fires on every keystroke, paste, or other input modification before the field loses focus. The event contains the current field value. Use this for real-time validation, character counting, formatting input as users type, or implementing autocomplete/search-as-you-type features. For controlled components, update the `value` prop in this callback to keep state in sync. Be cautious with expensive operations here as this fires frequently during typing. - * Learn more about [input events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * Callback when the user makes any changes in the field. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event */ onInput?: (event: Event) => void; /** - * The current value of the field. When provided, this creates a controlled component where this value must be updated in response to user input using `onChange` or `onInput` callbacks. The format and valid values depend on the specific field type. If both `value` and `defaultValue` are provided, `value` takes precedence. + * The current value for the field. If omitted, the field will be empty. */ value?: string; /** - * The default value used when the field is first rendered. Only applies if no `value` prop is provided, creating an uncontrolled component where the browser manages the field state internally. After initial render, the component handles its own state and you can read the current value from the DOM. Use this for forms where you don't need to control every state change but want to set initial values. For controlled components with full state management, use `value` instead. + * The default value for the field. * * @implementation `defaultValue` reflects to the `value` attribute. */ defaultValue?: string; } -/** - * Properties for form inputs that support multiple selections. - */ export interface MultipleInputProps extends BaseInputProps { /** - * Called when the user has finished editing the field, typically triggered on blur after the value has changed. - * Learn more about [change events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). + * Callback when the user has selected option(s). + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event */ onChange?: (event: Event) => void; /** - * Called when the user makes any change to the field value. Fires on each keystroke or interaction. - * Learn more about [input events on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). + * Callback when the user has selected option(s). + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event */ onInput?: (event: Event) => void; /** - * An array containing the values of currently selected options in a multi-select choice list. When provided, this creates a controlled component where this array must be updated in response to user selections using the `onChange` callback. The array should contain the `value` properties of selected child `Choice` components. For single-select lists (`multiple={false}`), this array should contain zero or one items. For multi-select lists, it can contain multiple items. This is a convenience property that automatically sets the `selected` state on matching child choices based on their `value` properties. When a choice's value appears in this array, it's automatically marked as selected. Update this array immutably in callbacks (create new arrays rather than mutating). + * An array of the `value`s of the selected options. + * + * This is a convenience prop for setting the `selected` prop on child options. */ values?: string[]; } -/** - * Properties for displaying field validation errors. - */ export interface FieldErrorProps { /** - * An error message to display when the field contains invalid data or fails validation. When set, the field receives error styling (typically a red border and error icon) and the message appears below the field to guide users toward fixing the issue. The error is announced to screen readers for accessibility. Clear the error by setting this to an empty string or `undefined`. Display errors after validation fails, typically on blur or form submission. + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ error?: string; } -/** - * Basic properties for form fields including labels, validation requirements, and error states. - */ export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisibilityProps { /** - * Whether the field must have a value before form submission. When `true`, the field is marked as required (typically with an asterisk), announced as required to screen readers, and triggers browser validation on form submit. This property adds semantic meaning but doesn't prevent submission on its own - validation logic must be implemented and the `error` property to display validation messages. + * 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 */ required?: boolean; /** - * The text label that describes what information the field is requesting from the user. Labels are always visible (unlike placeholders which disappear on input) and are announced by screen readers, making them critical for accessibility. Labels typically appear above or beside the field and remain visible while the user interacts with the field. Use clear, concise labels that describe the expected input (for example, "Email address", "Quantity", "Customer note"). Required fields should be indicated in the label or use the `required` property for semantic marking. + * Content to use as the field label. */ label?: string; } -/** - * Properties for adding supplementary help text to form fields. - */ export interface FieldDetailsProps { /** - * Supplementary help text that provides additional context, instructions, or constraints for the field. This text typically appears below the label in a smaller, subdued style and remains visible at all times (unlike placeholders). Screen readers announce this text along with the label to provide complete field context. Use for format requirements (for example, "Use YYYY-MM-DD format"), character limits (for example, "Maximum 500 characters"), helpful hints (for example, "This will be shown on the receipt"), or clarifying instructions (for example, "Leave blank to use default shipping address"). Avoid duplicating information already in the label or placeholder. + * Additional text to provide context or guidance for the field. + * This text is displayed along with the field and its label + * to offer more information or instructions to the user. + * + * This will also be exposed to screen reader users. */ details?: string; } -/** - * Complete properties for standard form fields including value, label, placeholder, validation, and callbacks. - */ export interface FieldProps extends BasicFieldProps, InputProps, FocusEventProps, FieldDetailsProps { /** - * A short hint that provides guidance about the expected value or format of the field. Displayed when the field is empty and disappears once the user starts typing. Placeholders should supplement the label, not replace it - always provide a `label` as well since placeholders may not be accessible to all screen readers. Use for format examples (for example, "YYYY-MM-DD"), helpful hints (for example, "Leave blank for default"), or clarifying expected input (for example, "Enter SKU or product name"). + * A short hint that describes the expected value of the field. */ placeholder?: string; } -/** - * Base properties for text-based input fields including placeholder and read-only state. - */ export interface BaseTextFieldProps extends FieldProps { /** - * Indicates whether the field can be edited. When `true`, the field is focusable and announced by screen readers but can't be modified by the user. Unlike `disabled`, read-only fields can still receive focus, be copied, and participate in form submission. Use read-only for data that users need to see and interact with but shouldn't change, such as calculated values or reference information. + * The field cannot be edited by the user. It is focusable will be announced by screen readers. * * @default false */ readOnly?: boolean; } -/** - * Properties for adding decorative elements like icons, prefixes, suffixes, and accessories to form fields. - */ export interface FieldDecorationProps { /** - * Static text displayed immediately after the editable portion of the field, typically inside the field border. This text is non-interactive and purely decorative—users can't edit it and it's not included in the field's value when submitted. The suffix remains visible at all times, even when the field is empty. Common uses include domain suffixes (for example, "@shopify.com" for email fields), units of measurement (for example, "kg", "%", "USD"), or clarifying context (for example, "/month" for subscription pricing). Choose between suffix and prefix based on natural reading order for your use case. + * A value to be displayed immediately after the editable portion of the field. + * + * This is useful for displaying an implied part of the value, such as "@shopify.com", or "%". + * + * This cannot be edited by the user, and it isn't included in the value of the field. + * + * It may not be displayed until the user has interacted with the input. + * For example, an inline label may take the place of the suffix until the user focuses the input. * * @default '' */ suffix?: string; /** - * Static text displayed immediately before the editable portion of the field, typically inside the field border. This text is non-interactive and purely decorative—users can't edit it and it's not included in the field's value when submitted. The prefix remains visible at all times, even when the field is empty. Common uses include currency symbols (for example, "$", "€", "£"), protocol indicators (for example, "https://"), measurement prefixes (for example, "#", "@"), or fixed identifiers. The prefix helps users understand the expected format without consuming characters from maxLength limits. + * A value to be displayed immediately before the editable portion of the field. + * + * This is useful for displaying an implied part of the value, such as "https://" or "+353". + * + * This cannot be edited by the user, and it isn't included in the value of the field. + * + * It may not be displayed until the user has interacted with the input. + * For example, an inline label may take the place of the prefix until the user focuses the input. * * @default '' */ prefix?: string; /** - * The icon identifier specifying which icon to display in the field, typically positioned at the start of the field before the input area. The icon is decorative and helps users quickly identify the field's purpose through visual recognition. The icon is announced to screen readers along with the field's accessible name. Use icons that clearly communicate the field's purpose (for example, search icon for search fields, calendar icon for date fields, lock icon for password fields). The icon doesn't affect the field's functionality but improves visual recognition and scannability in forms. Avoid using both icon and prefix simultaneously as this can create visual clutter. + * The type of icon to be displayed in the field. * * @default '' */ icon?: IconType | AnyString; /** - * Additional interactive content displayed within the field, typically positioned at the end of the field after the input area. Only text-only `Button` and `Clickable` components are supported—no icons or complex content. Use the `slot="accessory"` attribute to place elements here. Common uses include action buttons (for example, "Copy" button, "Generate" button, "Clear" button), toggle visibility controls (for example, "Show password" button), or quick actions related to the field (for example, "Paste from clipboard"). The accessory must not interfere with the field's primary input functionality. Ensure sufficient contrast and touch target sizes for mobile usability. + * Additional content to be displayed in the field. + * Commonly used to display an icon that activates a tooltip providing more information. */ accessory?: ComponentChildren; } -/** - * Properties for defining numeric value constraints and controls. - */ export interface NumberConstraintsProps { /** - * The highest decimal or integer value that the field accepts. When used with `stepper` controls, the increment button becomes disabled at this value and attempting to increment rounds down to max. When users type values using keyboard, they can enter numbers above max—browser validation will flag these as invalid but won't prevent entry, so implement your own validation in `onChange` or before form submission. Use this to enforce business rules like maximum quantities, price caps, or valid ranges. Set to `Infinity` (default) for no upper limit. + * The highest decimal or integer to be accepted for the field. + * When used with `step` the value will round down to the max number. + * + * Note: a user will still be able to use the keyboard to input a number higher than + * the max. It is up to the developer to add appropriate validation. * * @default Infinity */ max?: number; /** - * The lowest decimal or integer value that the field accepts. When used with `stepper` controls, the decrement button becomes disabled at this value and attempting to decrement rounds up to min. When users type values using keyboard, they can enter numbers below min—browser validation will flag these as invalid but won't prevent entry, so implement your own validation in `onChange` or before form submission. Use this to enforce business rules like minimum quantities, preventing negative values, or valid ranges. Set to `-Infinity` (default) for no lower limit. + * The lowest decimal or integer to be accepted for the field. + * When used with `step` the value will round up to the min number. + * + * Note: a user will still be able to use the keyboard to input a number lower than + * the min. It is up to the developer to add appropriate validation. * * @default -Infinity */ min?: number; /** - * The increment/decrement amount for adjusting the numeric value. Determines how much the value changes when users click stepper buttons or press keyboard arrow keys (up/down). For example, `step="0.01"` allows currency precision, `step="5"` for quantities in increments of 5, or `step="0.25"` for quarter-hour time intervals. The browser may also use this for validation, flagging values that aren't valid steps from the `min` value. Decimals are supported unless using `stepper` controls which only accept integers. + * The amount the value can increase or decrease by. This can be an integer or decimal. + * If a `max` or `min` is specified with `step` when increasing/decreasing the value + * via the buttons, the final value will always round to the `max` or `min` + * rather than the closest valid amount. * * @default 1 */ step?: number; /** - * The type of controls displayed for the field: + * Sets the type of controls displayed in the field. * - * - `'auto'` - An automatic setting where the presence of controls depends on the surface and context. The system determines the most appropriate control type based on the usage scenario. - * - `'stepper'` - Displays increment (+) and decrement (-) buttons for adjusting the numeric value. When `stepper` controls are enabled, the field behavior is constrained: it accepts only integer values, always contains a value (never empty), and automatically validates against `min` and `max` bounds. The `label`, `details`, `placeholder`, `error`, `required`, and `inputMode` properties aren't supported with `stepper` controls. - * - `'none'` - A control type with no visible controls where users must input the value manually using the keyboard. + * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property. + * Appropriate mouse and [keyboard interactions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role#keyboard_interactions) to control the value of the field are enabled. + * - `none`: no controls are displayed and users must input the value manually. Arrow keys and scroll wheels can’t be used either to avoid accidental changes. + * - `auto`: the presence of the controls depends on the surface and context. * * @default 'auto' */ controls?: 'auto' | 'stepper' | 'none'; } -/** - * Properties for defining minimum and maximum character length constraints on text inputs. - */ export interface MinMaxLengthProps { /** - * The maximum number of characters allowed in the text field. The browser prevents users from typing or pasting beyond this limit—additional characters are automatically truncated. The character count includes all characters (letters, numbers, spaces, special characters). This provides immediate feedback by blocking input rather than showing validation errors. Use this for enforcing hard limits like database column sizes, API constraints, or UX requirements. Commonly combined with character counter displays to show remaining space (for example, "45/100 characters"). + * Specifies the maximum number of characters allowed. * * @default Infinity */ maxLength?: number; /** - * The minimum number of characters required for the field value to be considered valid. Unlike `maxLength`, this doesn't prevent users from entering fewer characters—instead, browser validation marks the field as invalid if the value is too short. Validation typically occurs on form submission or blur. The field can be empty unless also marked `required`. Use this for ensuring sufficient input quality, like minimum password lengths, meaningful descriptions, or codes with fixed lengths. Combine with the `error` property to display user-friendly validation messages. + * Specifies the min number of characters allowed. * * @default 0 */ minLength?: number; } -/** - * Base properties for selectable options including value, disabled state, and accessibility labels. - */ export interface BaseSelectableProps { /** - * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. + * A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced. + * This can also be used to display a control without a visual label, while still providing context to users using screen readers. */ accessibilityLabel?: string; /** - * Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies. + * Disables the control, disallowing any interaction. * * @default false */ disabled?: boolean; /** - * The unique value associated with this selectable option. This value is what gets submitted with forms when the option is selected, and is used to identify which options are selected in the parent `ChoiceList`'s `values` array. The value should be unique among siblings within the same choice list to avoid selection ambiguity. When a choice is selected, this value appears in form data and in the parent's `values` array. Use meaningful, stable values that identify the choice semantically (for example, `"small"`, `"express-shipping"`, `"agree-to-terms"`) rather than display text which may change or be localized. The value isn't displayed to users—use the choice's `children` or label for visible text. + * The value used in form data when the control is checked. */ value?: string; } -/** - * Properties for individual options within choice lists, including selection state management. - */ export interface BaseOptionProps extends BaseSelectableProps { /** - * Whether the choice control is currently active or selected. This creates a controlled component - this value must be updated in response to user interactions using `onChange` handlers. When `true`, the choice appears selected with appropriate visual styling and is included in form submissions. Use this for controlled selection state where you manage the selected state in your application. If both `selected` and `defaultSelected` are provided, `selected` takes precedence. + * Whether the control is active. * * @default false */ selected?: boolean; /** - * Indicates whether the control is selected by default when first rendered. This creates an uncontrolled component where the browser manages selection state internally. Use this when you want initial selection state but don't need to control every state change. The component will handle selection internally after the initial render. Prefer `selected` for controlled components where you need full control over selection state. + * Whether the control is active by default. * * @implementation `defaultSelected` reflects to the `selected` attribute. * @@ -1615,12 +1641,48 @@ export interface BaseOptionProps extends BaseSelectableProps { */ defaultSelected?: boolean; } -/** - * Properties for a single choice option including label, details, selection state, and additional content. - */ +export interface BaseCheckableProps + extends BaseSelectableProps, + InteractionProps { + /** + * Visual content to use as the control label. + */ + label?: string; + /** + * Whether the control is active. + * + * @default false + */ + checked?: boolean; + /** + * Whether the control is active by default. + * + * @implementation `defaultChecked` reflects to the `checked` attribute. + * + * @default false + */ + defaultChecked?: boolean; + /** + * An identifier for the control that is unique within the nearest + * containing `Form` component. + */ + name?: string; + /** + * A callback that is run whenever the control is changed. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event + */ + onChange?: (event: Event) => void; + /** + * A callback that is run whenever the control is changed. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event + */ + onInput?: (event: Event) => void; +} export interface ChoiceProps extends GlobalProps, BaseOptionProps { /** - * The label content for the choice option. + * Content to use as the choice label. * * @implementation (StringChildren) The label is produced by extracting and * concatenating the text nodes from the provided content; any markup or @@ -1632,57 +1694,64 @@ export interface ChoiceProps extends GlobalProps, BaseOptionProps { */ children?: ComponentChildren | StringChildren; /** - * Additional text or content that provides context or guidance for the choice option. Displayed alongside the option label to offer more information or instructions to the user. Also exposed to screen reader users. + * 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. * * @implementation this content should be linked to the input with an `aria-describedby` attribute. */ details?: ComponentChildren; /** - * An error state indicator for the choice option. When `true`, the option will be given specific stylistic treatment to communicate validation issues. + * Set to `true` to associate a choice with the error passed to `ChoiceList` * * @default false */ error?: boolean; /** - * The additional content displayed alongside the primary choice label. Useful for providing supplementary information or context. + * Secondary content for a choice. */ secondaryContent?: ComponentChildren; /** - * The content displayed only when the option is selected. Useful for showing additional details or confirmation information. + * Content to display when the option is selected. + * + * This can be used to provide additional information or options related to the choice. */ selectedContent?: ComponentChildren; } -/** - * Properties for a list of choice options with support for single or multiple selection modes. - */ export interface ChoiceListProps extends GlobalProps, Pick, MultipleInputProps, FieldDetailsProps { /** - * Whether multiple choices can be selected simultaneously. When `true`, users can select multiple options and the `values` array will contain all selected values. When `false`, only one option can be selected at a time and selecting a new option automatically deselects the previous one. + * Whether multiple choices can be selected. * * @default false */ multiple?: boolean; /** - * The child elements to render within this component. Within `ChoiceList`, use only `Choice` components as children. Other component types can't be used as options within the choice list. + * The choices a user can select from. + * + * Accepts `Choice` components. */ children?: ComponentChildren; /** - * Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies. + * Disables the field, disallowing any interaction. + * + * `disabled` on any child choices is ignored when this is true. * * @default false */ disabled?: MultipleInputProps['disabled']; /** - * Controls the visual layout and presentation style of the choice options: - * - `'auto'`: The layout is automatically determined based on context - * - `'list'`: Displays choices in a vertical list format - * - `'inline'`: Displays choices in a horizontal inline format - * - `'block'`: Displays choices as block-level button-like elements - * - `'grid'`: Displays choices in a grid layout + * The variant of the choice grid. + * + * - `auto`: The variant is determined by the context. + * - `list`: The choices are displayed in a list. + * - `inline`: The choices are displayed on the inline axis. + * - `block`: The choices are displayed on the block axis. + * - `grid`: The choices are displayed in a grid. * * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the * discretion of each surface. @@ -1696,28 +1765,49 @@ export interface ClickableProps BaseBoxProps, BaseClickableProps { /** - * Indicates whether the action is currently in progress. When `true`, typically displays a loading indicator and may disable interaction. + * Disables the clickable, and indicates to assistive technology that the loading is in progress. + * + * This also disables the clickable. */ loading?: BaseClickableProps['loading']; /** - * Whether the element is disabled, preventing user interaction. Use when temporarily unavailable due to application state, permissions, or dependencies. Child elements can still receive focus and be interacted with. + * Disables the clickable, meaning it cannot be clicked or receive focus. + * + * In this state, onClick will not fire. + * If the click event originates from a child element, the event will immediately stop propagating from this element. + * + * However, items within the clickable can still receive focus and be interacted with. + * + * This has no impact on the visual state by default, + * but developers are encouraged to style the clickable accordingly. */ disabled?: BaseClickableProps['disabled']; /** - * Specifies the language of text content using an [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag (for example, `"en"` for English, `"fr"` for French, `"es-MX"` for Mexican Spanish, `"zh-Hans"` for Simplified Chinese). This enables assistive technologies to use correct pronunciation and language-specific text rendering. + * Indicate the text language. Useful when the text is in a different language than the rest of the page. + * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. + * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) * * @default '' */ lang?: string; } -/** - * Properties for enabling browser autocomplete functionality on form fields. - */ export interface AutocompleteProps< AutocompleteField extends AnyAutocompleteField, > { /** - * Specifies the type of data expected in the field to enable browser autocomplete functionality. When set to a specific field type (for example, `'email'`, `'name'`, `'address-line1'`), browsers offer suggestions from previously entered or saved information, improving data entry speed and accuracy. Set to `'on'` to enable generic autocomplete without specifying data type. Set to `'off'` to disable autocomplete entirely for sensitive fields (for example, one-time codes, PINs, credit card security codes). The browser respects user preferences and privacy settings, so autocomplete suggestions may not always appear even when enabled. Prefix field types with section identifiers (`section-shipping`) or groups (`billing`, `shipping`) to disambiguate when multiple similar fields exist on the same page. Accepts standard [HTML autocomplete tokens per the WHATWG specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens). + * 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 do not have any more semantic information on the intended + * contents. + * + * 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 + * 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 @@ -1733,18 +1823,19 @@ export interface AutocompleteProps< | 'off'; } /** - * A section prefix that scopes the autocomplete data to a specific area of the page. + * The “section” scopes the autocomplete data that should be inserted + * to a specific area of the page. * * Commonly used when there are multiple fields with the same autocomplete needs * in the same page. For example: 2 shipping address forms in the same page. */ export type AutocompleteSection = `section-${string}`; /** - * The contact information category that autocomplete data should be sourced from. + * The contact information group the autocomplete data should be sourced from. */ export type AutocompleteGroup = 'shipping' | 'billing'; /** - * The contact information subcategory that autocomplete data should be sourced from. + * The contact information subgroup the autocomplete data should be sourced from. */ export type AutocompleteAddressGroup = 'fax' | 'home' | 'mobile' | 'pager'; export type AnyAutocompleteField = @@ -1812,9 +1903,6 @@ export type AnyAutocompleteField = | `${AutocompleteAddressGroup} tel-local-suffix` | `${AutocompleteAddressGroup} tel-local` | `${AutocompleteAddressGroup} tel-national`; -/** - * Autocomplete field types applicable to text input fields. - */ export type TextAutocompleteField = ExtractStrict< AnyAutocompleteField, | 'additional-name' @@ -1848,15 +1936,12 @@ export type TextAutocompleteField = ExtractStrict< | 'cc-family-name' | 'cc-type' >; -/** - * Properties for an interactive date picker component with single, multiple, or range selection modes. - */ export interface DatePickerProps extends GlobalProps, InputProps, FocusEventProps { /** - * The default month to display in `YYYY-MM` format when the picker is first shown. + * Default month to display in `YYYY-MM` format. * * This value is used until `view` is set, either directly or as a result of user interaction. * @@ -1864,35 +1949,74 @@ export interface DatePickerProps */ defaultView?: string; /** - * The currently displayed month in `YYYY-MM` format. Controls which month is visible in the date picker. + * Displayed month in `YYYY-MM` format. + * + * `onViewChange` is called when this value changes. + * + * Defaults to `defaultView`. */ view?: string; /** - * Called when the visible month displayed in the date picker changes, either through user navigation (clicking next/previous month buttons) or programmatic updates to the `view` property. The callback receives the new month as a string in `YYYY-MM` format (for example, `"2024-05"`). Use this to track which month users are viewing, load month-specific data (like availability or pricing), sync the view with external state, or implement custom navigation controls. For controlled date pickers, update the `view` property in this callback to keep the displayed month in sync with your application state. The callback fires after the month has changed but before the new month's dates are fully rendered, making it ideal for triggering data fetches. + * Called whenever the month to display changes. + * + * @param view The new month to display in `YYYY-MM` format. */ onViewChange?: (view: string) => void; /** - * Controls the selection mode of the date picker: - * - `'single'`: Allows selecting one date - * - `'multiple'`: Allows selecting multiple individual dates - * - `'range'`: Allows selecting a continuous range of dates + * The type of selection the date picker allows. + * + * - `single` allows selecting a single date. + * - `multiple` allows selecting multiple non-contiguous dates. + * - `range` allows selecting a single range of dates. * * @default "single" */ type?: 'single' | 'multiple' | 'range'; /** - * Specifies allowed date values or ranges for selection. Uses ISO date format (YYYY-MM-DD) or partial dates (YYYY-MM, YYYY). Supports range syntax with `--` separator and comma-separated values. + * Dates that can be selected. + * + * A comma-separated list of dates, date ranges. Whitespace is allowed after commas. + * + * The default `''` allows all dates. + * + * - Dates in `YYYY-MM-DD` format allow a single date. + * - Dates in `YYYY-MM` format allow a whole month. + * - Dates in `YYYY` format allow a whole year. + * - Ranges are expressed as `start--end`. + * - Ranges are inclusive. + * - If either `start` or `end` is omitted, the range is unbounded in that direction. + * - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. + * So `2024--` is equivalent to `2024-01-01--`. + * - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. + * So `--2024` is equivalent to `--2024-12-31`. + * - Whitespace is allowed either side of `--`. * * @default "" * * @example * `2024-02--2025` // allow any date from February 2024 to the end of 2025 - * `2024-02--` // allow any date from February 2024 onwards + * `2024-02--` // allow any date from February 2024 to the end of the month * `2024-05-09, 2024-05-11` // allow only the 9th and 11th of May 2024 */ allow?: string; /** - * Specifies disallowed date values or ranges that can't be selected. Uses ISO date format (YYYY-MM-DD) or partial dates (YYYY-MM, YYYY). Supports range syntax with `--` separator and comma-separated values. Takes precedence over `allow`. + * Dates that cannot be selected. These subtract from `allow`. + * + * A comma-separated list of dates, date ranges. Whitespace is allowed after commas. + * + * The default `''` has no effect on `allow`. + * + * - Dates in `YYYY-MM-DD` format disallow a single date. + * - Dates in `YYYY-MM` format disallow a whole month. + * - Dates in `YYYY` format disallow a whole year. + * - Ranges are expressed as `start--end`. + * - Ranges are inclusive. + * - If either `start` or `end` is omitted, the range is unbounded in that direction. + * - If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. + * So `2024--` is equivalent to `2024-01-01--`. + * - If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. + * So `--2024` is equivalent to `--2024-12-31`. + * - Whitespace is allowed either side of `--`. * * @default "" * @@ -1902,49 +2026,82 @@ export interface DatePickerProps */ disallow?: string; /** - * Specifies which days of the week can be selected. Accepts comma-separated day names (case-insensitive). Further restricts dates within the result of `allow` and `disallow`. + * Days of the week that can be selected. These intersect with the result of `allow` and `disallow`. + * + * A comma-separated list of days. Whitespace is allowed after commas. + * + * The default `''` has no effect on the result of `allow` and `disallow`. + * + * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. * * @default "" * * @example - * 'saturday, sunday' // allow only weekends - * 'monday, wednesday, friday' // allow only specific weekdays + * 'saturday, sunday' // allow only weekends within the result of `allow` and `disallow`. */ allowDays?: string; /** - * Specifies which days of the week can't be selected. Accepts comma-separated day names (case-insensitive). Further restricts dates within the result of `allow` and `disallow`. + * Days of the week that cannot be selected. This subtracts from `allowDays`, and intersects with the result of `allow` and `disallow`. + * + * A comma-separated list of days. Whitespace is allowed after commas. + * + * The default `''` has no effect on `allowDays`. + * + * Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. * * @default "" * * @example - * 'saturday, sunday' // disallow weekends - * 'monday' // disallow Mondays + * 'saturday, sunday' // disallow weekends within the result of `allow` and `disallow`. */ disallowDays?: string; /** - * The default date value used when the field is first rendered, in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no default date. For date ranges, use comma-separated dates. Only applies if no `value` prop is provided. + * Default selected value. + * + * The default means no date is selected. + * + * If the provided value is invalid, no date is selected. + * + * - If `type="single"`, this is a date in `YYYY-MM-DD` format. + * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. + * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. * * @default "" */ defaultValue?: string; /** - * The currently selected date value in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DD`, for example, `"2024-05-15"`). An empty string means no date is selected. For date ranges, use comma-separated dates (for example, `"2024-05-15,2024-05-20"`). Other date formats require conversion before setting this property. The selection mode (`type` property) is inferred from the value format: single date for one value, multiple dates for comma-separated values without a range, and range for two comma-separated dates when `type` is set to 'range'. + * Current selected value. + * + * The default means no date is selected. + * + * If the provided value is invalid, no date is selected. + * + * Otherwise: + * + * - If `type="single"`, this is a date in `YYYY-MM-DD` format. + * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. + * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. * * @default "" */ value?: string; /** - * Called when the user makes any change to the field value. Fires on each keystroke or interaction. + * Callback when any date is selected. + * + * - If `type="single"`, fires when a date is selected and happens before `onChange`. + * - If `type="multiple"`, fires when a date is selected before `onChange`. + * - If `type="range"`, fires when a first date is selected (with the partial value formatted as `YYYY-MM-DD--`), and when the last date is selected before `onChange`. */ onInput?: (event: Event) => void; /** - * Called when the user has finished editing the field, typically triggered on blur after the value has changed. + * Callback when the value is committed. + * + * - If `type="single"`, fires when a date is selected after `onInput`. + * - If `type="multiple"`, fires when a date is selected after `onInput`. + * - If `type="range"`, fires when a range is completed by selecting the end date after `onInput`. */ onChange?: (event: Event) => void; } -/** - * Properties for a text-based date input field with validation and autocomplete support. - */ export interface DateFieldProps extends GlobalProps, BaseTextFieldProps, @@ -1952,6 +2109,7 @@ export interface DateFieldProps DatePickerProps, | 'view' | 'defaultView' + | 'value' | 'defaultValue' | 'allow' | 'disallow' @@ -1961,7 +2119,19 @@ export interface DateFieldProps >, AutocompleteProps { /** - * Called when the user enters an invalid value. Fires after change validation fails. + * Callback when the field has an invalid date. + * This callback will be called, if the date typed is invalid or disabled. + * + * Dates that don’t exist or have formatting errors are considered invalid. Some examples of invalid dates are: + * - 2021-02-31: February doesn’t have 31 days + * - 2021-02-00: The day can’t be 00 + * + * Disallowed dates are considered invalid. + * + * It’s important to note that this callback will be called only when the user **finishes editing** the date, + * and it’s called right after the `onChange` callback. + * The field is **not** validated on every change to the input. Once the buyer has signalled that + * they have finished editing the field (typically, by blurring the field), the field gets validated and the callback is run if the value is invalid. */ onInvalid?: (event: Event) => void; } @@ -1975,9 +2145,6 @@ export type DateAutocompleteField = ExtractStrict< | 'cc-expiry-month' | 'cc-expiry-year' >; -/** - * Properties for a spinner-style date selector with increment/decrement controls. - */ export interface DateSpinnerProps extends GlobalProps, Pick< @@ -1985,116 +2152,102 @@ export interface DateSpinnerProps 'defaultValue' | 'value' | 'onInput' | 'onChange' | 'onBlur' | 'onFocus' > { /** - * The default date value used when the field is first rendered, in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no default date. Only applies if no `value` prop is provided. + * Default selected value for the spinner. + * + * This uses a date in `YYYY-MM-DD` format. * * @default "" */ defaultValue?: string; /** - * The currently selected date value in ISO date format (YYYY-MM-DD, for example, `"2024-05-15"`). An empty string means no date is selected. + * Current selected value for the spinner. + * + * This uses a date in `YYYY-MM-DD` format. * * @default "" */ value?: string; /** - * Called when the user makes any change to the field value. Fires on each keystroke or interaction. + * Callback after the wheels have finished spinning and the value has + * settled. + * + * Fires once when inertial/momentum scrolling stops and the selection snaps + * into place. */ onInput?: (event: Event) => void; /** - * Called when the user has finished editing the field, typically triggered on blur after the value has changed. Date validation occurs when the user finishes editing (on blur), rather than on every keystroke. + * Callback when the selection has been confirmed by the user. + * + * Fires only when the user explicitly commits the selection (for example, by + * pressing a confirmation control). */ onChange?: (event: Event) => void; } -/** - * Properties for a visual divider line that separates content sections. - */ export interface DividerProps extends GlobalProps { /** - * The direction of the divider using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). An inline divider runs horizontally across the content flow, while a block divider runs vertically along the content flow. - * - * Available options: - * - `'inline'`: A horizontal divider that runs perpendicular to the text direction, creating separation between vertically stacked content sections. - * - `'block'`: A vertical divider that runs parallel to the text direction, creating separation between horizontally arranged content sections. + * Specify the direction of the divider. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). * * @default 'inline' */ direction?: 'inline' | 'block'; /** - * The color intensity of the divider. Controls how prominent or subtle the divider appears. + * Modify the color to be more or less intense. * * @default 'base' */ color?: ColorKeyword; } -/** - * Properties for an email address input field with validation and autocomplete support. - */ export interface EmailFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps {} -/** - * Autocomplete field types applicable to email input fields. - */ export type EmailAutocompleteField = ExtractStrict< AnyAutocompleteField, 'email' | `${AutocompleteAddressGroup} email` >; -/** - * A spacing size keyword including the option for no spacing. - */ export type SpacingKeyword = SizeKeyword | 'none'; -/** - * Properties for controlling the spacing between child elements in a container. - */ export interface GapProps { /** - * The spacing between child elements. A single value applies to both axes. Two values (for example, `large-100 large-500`) set the block axis (first value) and inline axis (second value) respectively. + * Adjust spacing between elements. + * + * A single value applies to both axes. + * A pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively. * * @default 'none' */ gap?: MaybeResponsive>; /** - * The spacing between child elements along the block axis (typically vertical). Overrides the block axis value from `gap`. + * Adjust spacing between elements in the block axis. + * + * This overrides the row value of `gap`. * * @default '' - meaning no override */ rowGap?: MaybeResponsive; /** - * The spacing between child elements along the inline axis (typically horizontal). Overrides the inline axis value from `gap`. + * Adjust spacing between elements in the inline axis. + * + * This overrides the column value of `gap`. * * @default '' - meaning no override */ columnGap?: MaybeResponsive; } -/** - * A baseline alignment position keyword. - */ export type BaselinePosition = 'baseline' | 'first baseline' | 'last baseline'; -/** - * A content distribution strategy keyword for spacing. - */ export type ContentDistribution = | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'; -/** - * A content position alignment keyword. - */ export type ContentPosition = 'center' | 'start' | 'end'; -/** - * A content position with optional overflow safety modifier. - */ export type OverflowPosition = | `unsafe ${ContentPosition}` | `safe ${ContentPosition}`; /** - * A type that defines how children are aligned along the cross axis. - * Sets the align-self value on all direct children as a group. + * Align items sets the align-self value on all direct children as a group. * - * Learn more about [`align-items` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items). + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items */ export type AlignItemsKeyword = | 'normal' @@ -2103,9 +2256,9 @@ export type AlignItemsKeyword = | OverflowPosition | ContentPosition; /** - * A type that defines how the browser distributes space between and around content items along the main-axis of a flex container, and the inline axis of a grid container. + * Justify content defines how the browser distributes space between and around content items along the main-axis of a flex container, and the inline axis of a grid container. * - * Learn more about [`justify-content` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content). + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content */ export type JustifyContentKeyword = | 'normal' @@ -2113,9 +2266,9 @@ export type JustifyContentKeyword = | OverflowPosition | ContentPosition; /** - * A type that defines the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis. + *Align content sets the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis. * - * Learn more about [`align-content` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content). + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content */ export type AlignContentKeyword = | 'normal' @@ -2123,90 +2276,90 @@ export type AlignContentKeyword = | ContentDistribution | OverflowPosition | ContentPosition; -/** - * Base properties for text styling and appearance. - */ export interface BaseTypographyProps { /** - * The color intensity of the text. Controls how prominent or subtle the text appears within the interface. + * Modify the color to be more or less intense. * * @default 'base' */ color?: ColorKeyword; /** - * The semantic tone of the text, based on the intention of the information being conveyed. Affects color and styling to communicate meaning. + * Sets the tone of the component, based on the intention of the information being conveyed. * * @default 'auto' */ tone?: ToneKeyword; /** - * Controls how numbers are displayed in the text: - * - `'auto'`: Inherits the setting from the parent element. - * - `'normal'`: Uses the default number rendering for the font. - * - `'tabular-nums'`: Uses fixed-width numbers for better alignment in tables and lists. + * Set the numeric properties of the font. * - * Learn more about [`font-variant-numeric` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric). + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric * - * @default 'auto' + * @default 'auto' - inherit from the parent element */ fontVariantNumeric?: 'auto' | 'normal' | 'tabular-nums'; /** - * Specifies the language of text content using an [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag (for example, `"en"` for English, `"fr"` for French, `"es-MX"` for Mexican Spanish, `"zh-Hans"` for Simplified Chinese). This enables assistive technologies to use correct pronunciation and language-specific text rendering. + * Indicate the text language. Useful when the text is in a different language than the rest of the page. + * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. + * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) + * + * It is recommended to combine it with the `dir` attribute to ensure the text is rendered correctly if the surrounding content’s direction is different. * * @default '' */ lang?: string; /** - * Indicates the directionality of the element's text: - * - `ltr`: languages written from left to right (for example, English). - * - `rtl`: languages written from right to left (for example, Arabic). - * - `auto`: the user agent determines the direction based on the content. - * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute). + * Indicates the directionality of the element’s text. * - * Learn more about the [`dir` attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir). + * - `ltr`: languages written from left to right (e.g. English) + * - `rtl`: languages written from right to left (e.g. Arabic) + * - `auto`: the user agent determines the direction based on the content + * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute) + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir * * @default '' */ dir?: 'ltr' | 'rtl' | 'auto' | ''; } -/** - * Properties for controlling multi-line text behavior and truncation. - */ export interface BlockTypographyProps { /** - * Limits the text content to a specified number of visible lines. When text exceeds this limit, it's truncated and an ellipsis (`…`) appears at the end of the last visible line to indicate more content exists. The truncation happens automatically based on the container's width, font size, and line height—narrow containers or large fonts will show fewer words per line. For example, `lineClamp={3}` allows maximum three lines of text regardless of total content length. Users can't access the hidden text unless an expansion mechanism (like a "Read more" button) or tooltip is provided. Commonly applied to maintain consistent layout heights in cards, lists, or grids where varying text lengths would disrupt visual alignment. Common values include 1-2 for titles/labels, 2-3 for descriptions, and 4-6 for preview text. The actual text content remains in the DOM and is accessible to screen readers (full text is announced), search engines, and selection—only the visual display is truncated. Learn more about [`line-clamp` on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp). + * Truncates the text content to the specified number of lines. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp * * @default Infinity - no truncation is applied */ lineClamp?: number; } -/** - * Properties for heading text elements with semantic structure and line clamping. - */ export interface HeadingProps extends GlobalProps, AccessibilityVisibilityProps, BlockTypographyProps { /** - * The child elements to render within this component. Use plain text or simple inline elements only for heading content. Rich text format isn't supported. + * The content of the Heading. */ children?: ComponentChildren; /** - * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. + * Sets the semantic meaning of the component’s content. When set, + * the role will be used by assistive technologies to help users + * navigate the page. + * + * - `heading`: defines the element as a heading to a page or section. + * - `presentation`: the heading level will be stripped, + * and will prevent the element’s implicit ARIA semantics from + * being exposed to the accessibility tree. + * - `none`: a synonym for the `presentation` role. * * @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 shouldn't apply the `heading` role. + * an `

` element should not apply the `heading` role. */ accessibilityRole?: | 'heading' | ExtractStrict; } -/** - * Properties for icon elements including type, size, color, and tone. - */ export interface IconProps extends GlobalProps, Pick { @@ -2217,162 +2370,207 @@ export interface IconProps */ tone?: ToneKeyword; /** - * Modify the color to be more or less intense. Use `'subdued'` for secondary icons, `'base'` for standard visibility, or `'strong'` for emphasized icons that need to stand out. + * Modify the color to be more or less intense. * * @default 'base' */ color?: ColorKeyword; /** - * Adjusts the size of the icon. Available sizes range from `'small-500'` (smallest) through `'base'` (default) to `'large-500'` (largest), allowing you to match icon size to your interface hierarchy. + * Adjusts the size of the icon. * * @default 'base' */ size?: SizeKeyword; - /** - * The type of icon to display. - */ type?: IconType | AnyString; } -/** - * Base properties for image elements including source URLs and alternative text. - */ export interface BaseImageProps { /** - * Alternative text that describes the image content for users who can't see the image. This text is announced by screen readers, displayed when images fail to load or are blocked, and used by search engines for image indexing. Write concise, descriptive alt text that conveys the image's purpose and content (for example, "Product photo of blue running shoes" not "image" or "photo"). For decorative images that don't convey information, use an empty string (`alt=""`) to hide them from screen readers. For images containing text, include that text in the alt description. For complex images like charts or diagrams, consider providing a longer description elsewhere and summarizing in alt text. Alt text is required for accessibility compliance and should describe what users would miss if they couldn't see the image. + * An alternative text description that describe the image for the reader to + * understand what it is about. It is extremely useful for both users using + * assistive technology and sighted users. A well written description + * provides people with visual impairments the ability to participate in + * consuming non-text content. When a screen readers encounters an `s-image`, + * the description is read and announced aloud. If an image fails to load, + * potentially due to a poor connection, the `alt` is displayed on + * screen instead. This has the benefit of letting a sighted buyer know an + * image was meant to load here, but as an alternative, they’re still able to + * consume the text content. Read + * [considerations when writing alternative text](https://www.shopify.com/ca/blog/image-alt-text#4) + * to learn more. * * @default `''` - * Learn more about [`alt` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt). + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt */ alt?: string; /** - * Defines the image sizes for different viewport widths to help the browser select the optimal image from `srcSet`. This is a comma-separated list of media conditions and corresponding sizes (for example, `"(max-width: 600px) 480px, 800px"`). The browser uses this with `srcSet` to determine which image variant to download based on the device's screen size and pixel density, improving performance by loading appropriately-sized images. For example, mobile devices receive smaller images while desktops get larger, higher-resolution versions. When `srcSet` provides multiple image sizes, `sizes` tells the browser the rendered size at different viewport widths. If omitted, the browser assumes `100vw` (full viewport width). This only affects which image is selected, not how it's displayed—use CSS or `inlineSize` for display sizing. + * A set of media conditions and their corresponding sizes. * - * Learn more about [`sizes` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes). + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes */ sizes?: string; /** - * The image source URL (remote URL or local file resource). When loading or no src is provided, a placeholder is rendered. Ensure URLs are properly formatted and properly formatted. + * The image source (either a remote URL or a local file resource). + * + * When the image is loading or no `src` is provided, a placeholder will be rendered. + * + * @implementation Surfaces may choose the style of the placeholder, but the space the image occupies should be + * reserved, except in cases where the image area does not have a contextual inline or block size, which should be rare. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src */ src?: string; /** - * A set of image source URLs with descriptors for responsive image selection. Provides multiple image variants at different widths or pixel densities, allowing browsers to choose the most appropriate image for the user's device and screen. Format: comma-separated list of `URL descriptor` pairs where descriptors are either width (`w`) or pixel density (`x`). For example: `"small.jpg 480w, medium.jpg 800w, large.jpg 1200w"` for different widths, or `"standard.jpg 1x, retina.jpg 2x"` for different pixel densities. The browser considers the device's screen size, resolution, network speed, and user preferences when selecting which image to download. This improves performance (smaller images on mobile) and quality (high-DPI images on retina displays). When used with `sizes`, enables fully responsive images. The `src` property serves as fallback for browsers that don't support `srcSet`. + * A set of image sources and their width or pixel density descriptors. * - * Learn more about [`src` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src).set + * This overrides the `src` property. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset */ srcSet?: string; } -/** - * Properties for image elements including size, aspect ratio, loading behavior, and border styling. - */ export interface ImageProps extends GlobalProps, BaseImageProps, BorderProps { /** - * Sets the semantic role for assistive technologies. Helps screen reader users navigate and understand page structure. + * Sets the semantic meaning of the component’s content. When set, + * the role will be used by assistive technologies to help users + * navigate the page. * * @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 shouldn't apply the `img` role. + * an `` element should not apply the `img` role. */ accessibilityRole?: | 'img' | ExtractStrict; /** - * Controls the displayed width of the image. Choose based on your layout requirements. For mobile interfaces, consider using `'fill'` with defined container dimensions to ensure consistent image display, as dynamic container heights can cause layout inconsistencies in scrollable views. + * The displayed inline width of the image. * - * - `'auto'` - Displays the image at its natural size. The image will not render until it has loaded, and the aspect ratio will be ignored. Use for images where maintaining original dimensions is important. - * - `'fill'` - Makes the image take up 100% of the available inline size. The aspect ratio will be respected and the image will take the necessary space. Use for responsive layouts and flexible image containers. + * - `fill`: the image will takes up 100% of the available inline size. + * - `auto`: the image will be displayed at its natural size. * * @default 'fill' + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width */ inlineSize?: 'fill' | 'auto'; /** - * The aspect ratio of the image, expressed as width divided by height. + * 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 won't render until it has loaded and the aspect ratio will be ignored. + * - `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`. * * @default '1/1' + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio */ aspectRatio?: | `${number}${optionalSpace}/${optionalSpace}${number}` | `${number}`; /** - * Controls how the image content is resized within its container. - * - * - `'contain'` - Scales the image to fit within the container while maintaining aspect ratio. The entire image will be visible, but there may be empty space. Use when showing the complete image is important. - * - `'cover'` - Scales the image to fill the entire container while maintaining aspect ratio. Parts of the image may be cropped. Use when filling the container completely is more important than showing the entire image. + * Determines how the content of the image is resized to fit its container. + * The image is positioned in the center of the container. * * @default 'contain' + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit */ objectFit?: 'contain' | 'cover'; /** - * Controls when the browser should begin loading the image resource: - * - `'eager'`: Loads the image immediately when the page loads, regardless of whether it's visible in the viewport. The image downloads in parallel with other page resources. Use for above-the-fold images, critical product photos, or images that will definitely be viewed. This ensures images are ready when needed but increases initial page load bandwidth. - * - `'lazy'`: Defers image loading until the image is approaching the viewport (typically a few hundred pixels before becoming visible). The browser only downloads the image when the user is likely to see it soon. Use for below-the-fold images, gallery images, or images in scrollable lists. This improves initial page load performance and saves bandwidth for images users may never scroll to. The browser maintains a buffer distance so images load before users reach them, preventing visible loading delays. - * - * Lazy loading is most effective for pages with many images, long scrollable content, or mobile users on limited bandwidth. Modern browsers support native lazy loading—older browsers ignore this and load eagerly. + * Determines the loading behavior of 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. * * @default 'eager' - * Learn more about [`loading` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading). + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading */ loading?: 'eager' | 'lazy'; /** - * Called when the image finishes loading successfully and is ready to display. This fires after the browser has downloaded the image data and decoded it, but may fire before the image is actually painted to the screen. Use this for hiding loading indicators, triggering dependent actions that require the image (like image processing), tracking image load metrics, or executing layout operations that depend on image dimensions. For performance tracking, compare timestamps between navigation start and this callback. Note that cached images may trigger this callback synchronously (immediately), so handle both async and sync invocation in your code. This won't fire if the image fails to load—listen to `onError` for failures. + * Invoked when load completes successfully. * - * Learn more about [`onload` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload). + * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload */ onLoad?: (event: Event) => void; /** - * Called when the image fails to load due to network errors, invalid URLs, unsupported formats, [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) issues, or server errors (for example, 404, 500). The event contains limited error details for security reasons—the browser console provides specific failure reasons. Common operations include displaying fallback images (`event.target.src = 'fallback.jpg'`), showing error messages to users, logging failures for monitoring, hiding broken image icons, or providing alternative content when images are unavailable. A common pattern involves attempting to load a fallback image, and if that fails too, hiding the image container entirely. For critical images like product photos, a placeholder SVG or icon may be shown instead of a broken image indicator. This callback doesn't fire for images that are blocked by browser content policies or ad blockers. + * Invoked on load error. * - * Learn more about [`onerror` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror). + * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror */ onError?: (event: Event) => void; } -/** - * Properties for modal overlay dialogs including size, padding, actions, and lifecycle callbacks. - */ +export interface LinkProps extends GlobalProps, LinkBehaviorProps { + /** + * The content of the Link. + */ + children?: ComponentChildren; + /** + * Sets the tone of the Link, based on the intention of the information being conveyed. + * + * @default 'auto' + */ + tone?: ToneKeyword; + /** + * A label that describes the purpose or contents of the Link. It will be read to users using assistive technologies such as screen readers. + * + * Use this when using only an icon or the content of the link is not enough context + * for users using assistive technologies. + */ + accessibilityLabel?: string; + /** + * Indicate the text language. Useful when the text is in a different language than the rest of the page. + * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. + * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) ("subtag" label) + */ + lang?: string; +} export interface ModalProps extends GlobalProps, BaseOverlayProps, BaseOverlayMethods, ActionSlots { /** - * A label that describes the purpose or contents of the element. Announced to users with assistive technologies such as screen readers to provide context. + * 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?: string; /** - * The title text displayed in the modal header. If omitted and no actions are provided, the modal will be rendered without a header. + * A title that describes the content of the Modal. + * */ heading?: string; /** - * The padding applied to all edges of the modal content. + * 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?: 'base' | 'none'; /** - * Controls the display size of the modal: - * - Size keywords (for example, `'small'`, `'base'`, `'large'`): Fixed size options. - * - `'max'`: Modal expands to fill the maximum available space. + * Adjust the size of the Modal. + * + * `max`: expands the Modal to its maximum size as defined by the host application, on both the horizontal and vertical axes. * * @default 'base' */ size?: SizeKeyword | 'max'; /** - * The child elements to render within this component. + * The content of the Modal. */ children?: ComponentChildren; } -/** - * Properties for numeric input fields with validation, constraints, and optional stepper controls. - */ export interface NumberFieldProps extends GlobalProps, BaseTextFieldProps, @@ -2380,71 +2578,64 @@ export interface NumberFieldProps NumberConstraintsProps, FieldDecorationProps { /** - * The virtual keyboard layout that the field displays for numeric input. This property isn't supported when using `stepper` controls. - * - * - `'decimal'` - A keyboard layout that includes decimal point support for entering fractional numbers, prices, or measurements with decimal precision. - * - `'numeric'` - A keyboard layout optimized for integer-only entry without decimal point support, ideal for quantities, counts, or whole number values. + * Sets the virtual keyboard. * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode * @default 'decimal' */ inputMode?: 'decimal' | 'numeric'; } -/** - * Autocomplete field types applicable to number input fields. - */ export type NumberAutocompleteField = ExtractStrict< AnyAutocompleteField, 'one-time-code' | 'cc-number' | 'cc-csc' >; -/** - * Properties for page-level layouts including header, breadcrumbs, actions, and sidebar content. - */ export interface PageProps extends GlobalProps, ActionSlots { /** - * The child elements to render within this component. + * The content of the Page. */ children?: ComponentChildren; /** - * The title text displayed in the page header. If omitted and no actions are provided, the page will be rendered without a header. + * The main page heading */ heading?: string; /** - * A secondary page heading displayed under the main heading in the action bar. + * The text to be used as subtitle. */ subheading?: string; /** - * The additional content displayed in the header area. Commonly used to display clickable text or action elements. Only `Button` and `Clickable` components with text content only are supported in this slot. Use the `slot="accessory"` attribute to place elements in this area. + * Additional contextual information about the page. */ accessory?: ComponentChildren; /** - * The navigation breadcrumb links displayed in the page header as link elements. These show the hierarchical path to the current page. + * The breadcrumb actions to perform, provided as link elements. */ breadcrumbActions?: ComponentChildren; /** - * The content to display in the page's sidebar. This area is for content that is tangentially related to the main content, such as navigation or contextual information. Use the `slot="aside"` attribute to place content in this area. - * + * The aside element is section of a page that contains content that is tangentially related to the content around the aside element, and which could be considered separate from that content. + * Such sections are often represented as sidebars in printed typography. * @implementation surfaces built ontop of the web platform should implement this using the