From dd680ffbaec6f884577e522be4b499923d21047f Mon Sep 17 00:00:00 2001 From: Kyle Durand Date: Wed, 15 Apr 2026 15:22:04 -0400 Subject: [PATCH 1/3] bump admin-ui-components 1.64.0 --- .../src/surfaces/admin/components.d.ts | 9005 +++++++++-------- .../admin/components/AdminAction.d.ts | 108 +- .../surfaces/admin/components/AdminBlock.d.ts | 107 +- .../admin/components/AdminPrintAction.d.ts | 106 +- .../src/surfaces/admin/components/Avatar.d.ts | 150 +- .../src/surfaces/admin/components/Badge.d.ts | 166 +- .../src/surfaces/admin/components/Banner.d.ts | 153 +- .../src/surfaces/admin/components/Box.d.ts | 343 +- .../src/surfaces/admin/components/Button.d.ts | 345 +- .../admin/components/ButtonGroup.d.ts | 149 +- .../surfaces/admin/components/Checkbox.d.ts | 244 +- .../src/surfaces/admin/components/Chip.d.ts | 51 +- .../src/surfaces/admin/components/Choice.d.ts | 131 +- .../surfaces/admin/components/ChoiceList.d.ts | 171 +- .../surfaces/admin/components/Clickable.d.ts | 265 +- .../admin/components/ClickableChip.d.ts | 210 +- .../surfaces/admin/components/ColorField.d.ts | 294 +- .../admin/components/ColorPicker.d.ts | 152 +- .../surfaces/admin/components/DateField.d.ts | 296 +- .../surfaces/admin/components/DatePicker.d.ts | 182 +- .../surfaces/admin/components/Divider.d.ts | 124 +- .../surfaces/admin/components/DropZone.d.ts | 58 +- .../surfaces/admin/components/EmailField.d.ts | 268 +- .../src/surfaces/admin/components/Form.d.ts | 134 +- .../admin/components/FunctionSettings.d.ts | 143 +- .../src/surfaces/admin/components/Grid.d.ts | 303 +- .../surfaces/admin/components/GridItem.d.ts | 297 +- .../surfaces/admin/components/Heading.d.ts | 149 +- .../src/surfaces/admin/components/Icon.d.ts | 149 +- .../src/surfaces/admin/components/Image.d.ts | 235 +- .../src/surfaces/admin/components/Link.d.ts | 194 +- .../surfaces/admin/components/ListItem.d.ts | 128 +- .../src/surfaces/admin/components/Menu.d.ts | 182 +- .../src/surfaces/admin/components/Modal.d.ts | 107 +- .../surfaces/admin/components/MoneyField.d.ts | 266 +- .../admin/components/NumberField.d.ts | 263 +- .../src/surfaces/admin/components/Option.d.ts | 123 +- .../admin/components/OptionGroup.d.ts | 123 +- .../admin/components/OrderedList.d.ts | 128 +- .../src/surfaces/admin/components/Page.d.ts | 8 +- .../surfaces/admin/components/Paragraph.d.ts | 189 +- .../admin/components/PasswordField.d.ts | 290 +- .../admin/components/QueryContainer.d.ts | 137 +- .../admin/components/SearchField.d.ts | 268 +- .../surfaces/admin/components/Section.d.ts | 155 +- .../src/surfaces/admin/components/Select.d.ts | 242 +- .../surfaces/admin/components/Spinner.d.ts | 127 +- .../src/surfaces/admin/components/Stack.d.ts | 303 +- .../src/surfaces/admin/components/Switch.d.ts | 211 +- .../src/surfaces/admin/components/Table.d.ts | 232 +- .../surfaces/admin/components/TableBody.d.ts | 137 +- .../surfaces/admin/components/TableCell.d.ts | 137 +- .../admin/components/TableHeader.d.ts | 141 +- .../admin/components/TableHeaderRow.d.ts | 137 +- .../surfaces/admin/components/TableRow.d.ts | 137 +- .../src/surfaces/admin/components/Text.d.ts | 195 +- .../surfaces/admin/components/TextArea.d.ts | 268 +- .../surfaces/admin/components/TextField.d.ts | 293 +- .../surfaces/admin/components/Thumbnail.d.ts | 143 +- .../surfaces/admin/components/Tooltip.d.ts | 182 +- .../surfaces/admin/components/URLField.d.ts | 287 +- .../admin/components/UnorderedList.d.ts | 134 +- .../src/surfaces/admin/components/shared.d.ts | 3438 ++++--- 63 files changed, 8968 insertions(+), 14825 deletions(-) diff --git a/packages/ui-extensions/src/surfaces/admin/components.d.ts b/packages/ui-extensions/src/surfaces/admin/components.d.ts index 8dc7f2f26f..1d78414ace 100644 --- a/packages/ui-extensions/src/surfaces/admin/components.d.ts +++ b/packages/ui-extensions/src/surfaces/admin/components.d.ts @@ -1,4 +1,4 @@ -/** VERSION: 1.25.0 **/ +/** VERSION: 1.64.0 **/ /* eslint-disable @typescript-eslint/ban-types */ /* eslint-disable @typescript-eslint/no-namespace */ @@ -10,51 +10,36 @@ * TODO: Update `any` type here after this is resolved * https://github.com/Shopify/ui-api-design/issues/139 */ -/** - * Represents any valid children that can be rendered within a component, including elements, strings, numbers, or arrays of these types. - * This is an alias for Preact's `ComponentChildren` type. - * @publicDocs - */ +import * as _shopify_admin_web_component_foundations from '@shopify/admin-web-component-foundations'; + export type ComponentChildren = preact.ComponentChildren; -/** - * Represents string-only children for components that specifically require text content. - * @publicDocs - */ export type StringChildren = string; export interface GlobalProps { /** - * A unique identifier for the element. Use this to reference the element in JavaScript, - * link labels to form controls, or target specific elements for styling or scripting. + * A unique identifier for the element. */ id?: string; } -/** @publicDocs */ export interface ActionProps { /** - * The text to use as the action modal's title. If not provided, the name of the extension will be used. + * The text to use as the Action modal’s title. If not provided, the name of the extension will be used. */ heading?: string; } -/** - * The action component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). - * @publicDocs - */ export interface ActionSlots { /** - * The primary action button or link, representing the main or most important action available in this context. - * Typically displayed with higher visual prominence than secondary actions to establish clear hierarchy. + * The primary action to perform, provided as a button or link type element. */ primaryAction?: ComponentChildren; /** - * Additional action buttons or links that provide alternative or supporting actions. - * Visually de-emphasized compared to the primary action. + * The secondary actions to perform, provided as button or link type elements. */ secondaryActions?: ComponentChildren; } interface AdminActionProps$1 extends GlobalProps, ActionProps, ActionSlots { /** - * Whether the action is in a loading state, such as during initial page load or when the action is being opened. - * When `true`, the action is in an inert state that prevents user interaction. + * Whether the action is in a loading state, such as initial page load or action opening. + * When true, the action could be in an inert state, which prevents user interaction. * * @default false */ @@ -62,161 +47,140 @@ interface AdminActionProps$1 extends GlobalProps, ActionProps, ActionSlots { } interface AdminBlockProps$1 extends GlobalProps { /** - * The text displayed as the block's title in the header. If not provided, the extension name will be used. + * The text to use as the Block title in the block header. If not provided, the name of the + * extension will be used. */ heading?: string; /** - * The summary text displayed when the app block is collapsed. Summaries longer than 30 characters will be truncated. + * The summary to display when the app block is collapsed. + * Summary longer than 30 characters will be truncated. */ collapsedSummary?: string; } interface AdminPrintActionProps$1 extends GlobalProps { /** - * The URL of the document to preview and print. Supports HTML, PDF, and image formats. + * Sets the src URL of the preview and the document to print. * If not provided, the preview will show an empty state and the print button will be disabled. + * HTML, PDFs and images are supported. */ src?: string; + /** + * Programmatically controls the loading state of the component. + * When true, displays a loading indicator. The component also shows loading automatically when fetching the preview. + * + * @default false + */ + loading?: boolean; } -/** @publicDocs */ export interface BaseOverlayProps { /** - * A callback fired immediately after the overlay is shown. + * Callback fired after the overlay is shown. */ onShow?: (event: Event) => void; /** - * A callback fired when the overlay is shown, after any show animations have completed. + * Callback fired when the overlay is shown **after** any animations to show the overlay have finished. */ onAfterShow?: (event: Event) => void; /** - * A callback fired immediately after the overlay is hidden. + * Callback fired after the overlay is hidden. */ onHide?: (event: Event) => void; /** - * A callback fired when the overlay is hidden, after any hide animations have completed. + * Callback fired when the overlay is hidden **after** any animations to hide the overlay have finished. */ onAfterHide?: (event: Event) => void; } /** - * Shared interface for web component methods that control overlay visibility. + * Shared interfaces for web component methods. * - * All methods are required (not optional) because components implementing this interface must provide - * consistent JavaScript APIs. Unlike props/attributes, methods are not rendered in HTML and consumers - * expect them to be available on all component instances. - * @publicDocs + * Methods are required (not optional) because: + * - Components implementing this interface must provide all methods + * - 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 { /** - * A method to programmatically show the overlay. + * 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; /** - * A method to programmatically hide the overlay. + * 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; /** - * A method to programmatically toggle the visibility of the overlay. + * 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; } -/** @publicDocs */ export interface FocusEventProps { /** - * A callback fired when the component loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). + * Callback when the element loses focus. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event */ onBlur?: (event: FocusEvent) => void; /** - * A callback fired when the component receives focus. Learn more about the [focus event](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; } -/** @publicDocs */ export interface ToggleEventProps { /** - * A callback fired when the element state changes, after any toggle animations have finished. + * Callback fired when the element state changes **after** any animations have finished. * * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). + * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState + * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState */ onAfterToggle?: (event: ToggleEvent$1) => void; /** - * A callback fired immediately when the element state changes, before any animations. + * Callback straight after the element state changes. * * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event + * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState + * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState */ onToggle?: (event: ToggleEvent$1) => void; } -/** - * Represents the visibility state of a toggleable element. - * - * - `open`: The element is visible or expanded. - * - `closed`: The element is hidden or collapsed. - * @publicDocs - */ export type ToggleState = 'open' | 'closed'; interface ToggleEvent$1 extends Event { - /** - * The state the element is transitioning to, either `open` or `closed`. - */ readonly newState: ToggleState; - /** - * The state the element is transitioning from, either `open` or `closed`. - */ readonly oldState: ToggleState; } -/** @publicDocs */ export interface ExtendableEvent extends Event { /** - * A method that accepts a promise signaling the duration and eventual success or failure of event-related actions. + * Provide a promise that signals the length, and eventual success or failure of actions relating to the event. + * + * This may be called many times, which adds promises to the event. * - * Can be called multiple times to add promises to the event, but must be called synchronously during event dispatch. - * Cannot be called after a `setTimeout` or within a microtask. + * However, this may only be called synchronously during the dispatch of the event. + * As in, you cannot call it after a `setTimeout` or microtask. */ waitUntil?: (promise: Promise) => void; } -/** @publicDocs */ -export interface AggregateError extends Error { - /** - * An array of individual errors that have been aggregated together. - * Each error in this array represents a separate failure that occurred. - */ +interface AggregateError$1 extends Error { errors: T[]; } -/** @publicDocs */ export interface AggregateErrorEvent extends ErrorEvent { - /** - * The aggregated error object containing multiple individual errors. - * Access the `errors` property to retrieve the array of individual error instances. - */ - error: AggregateError; + error: AggregateError$1; } -/** - * Defines component sizes using a consistent scale from extra small to extra large. - * - * - `small-500` through `small-100`: Extra small to small sizes, progressively increasing. - * - `small`: Standard small size. - * - `base`: Default medium size that works well in most contexts. - * - `large`: Standard large size. - * - `large-100` through `large-500`: Large to extra large sizes, progressively increasing. - * - * - * @default 'base' - * @publicDocs - */ export type SizeKeyword = | 'small-500' | 'small-400' @@ -231,95 +195,60 @@ export type SizeKeyword = | 'large-300' | 'large-400' | 'large-500'; -/** - * Defines the color intensity or emphasis level for text and UI elements. - * - * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. - * - `base`: Primary color for body text, standard UI elements, and general content with good readability. - * - `strong`: Emphasized color for headings, key labels, and interactive elements that need prominence. - * - * @publicDocs - */ export type ColorKeyword = 'subdued' | 'base' | 'strong'; interface AvatarProps$1 extends GlobalProps { /** - * The initials to display in the avatar when no image is provided or fails to load. - * Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe. + * Initials to display in the avatar. */ initials?: string; /** - * The URL or path to the avatar image. When provided, the image takes priority over `initials`. - * If the image fails to load or loads slowly, `initials` will be rendered as a fallback. + * The URL or path to the image. + * + * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly */ src?: string; /** - * A callback fired when the avatar image loads successfully. Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload). + * Invoked when load of provided image completes successfully. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload */ onLoad?: (event: Event) => void; /** - * A callback fired when the avatar image fails to load. Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror). + * Invoked on load error of provided image. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror */ onError?: (event: Event) => void; /** - * The size of the avatar. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default medium size that works well in most contexts. + * Size of the avatar. * * @default 'base' */ size?: SizeKeyword; /** - * Alternative text that describes the avatar for accessibility. - * - * Provides a text description of the avatar for users with assistive technology - * and serves as a fallback when the avatar fails to load. A well-written description - * enables people with visual impairments to understand non-text content. - * - * When a screen reader encounters an avatar, it reads this description aloud. - * When an avatar fails to load, this text displays on screen, helping all users - * understand what content was intended. - * - * Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4) - * and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt). + * An alternative text that describes the avatar for the reader + * to understand what it is about or identify the user the avatar belongs to. */ alt?: string; } -/** - * Defines the background color intensity or emphasis level for UI elements. - * - * - `transparent`: No background, allowing the underlying surface to show through. - * - `ColorKeyword`: Applies color intensity levels (subdued, base, strong) to create spatial emphasis and containment. - * - * @publicDocs - */ export type BackgroundColorKeyword = 'transparent' | ColorKeyword; export interface BackgroundProps { /** - * The background color of the element. Use `transparent` for no background, `subdued` for a subtle background, `base` for standard background, or `strong` for a prominent background. - * - * - `transparent`: No background, allowing the underlying surface to show through. - * - `ColorKeyword`: Applies color intensity levels (subdued, base, strong) to create spatial emphasis and containment. + * Adjust the background of the element. * * @default 'transparent' */ background?: BackgroundColorKeyword; } /** - * Defines the semantic color treatment of a component to convey specific intent or status. + * Tone is a property for defining the color treatment of a component. * - * Tones apply coordinated color schemes (text, background, icons) across the component. - * Some components, like banner, also use tone to determine accessibility attributes and screen reader announcements. + * A tone can apply a grouping of colors to a component. For example, + * critical may have a specific text color and background color. * - * - `auto`: Automatically determined based on context. - * - `neutral`: General-purpose information without specific sentiment. - * - `info`: Informational content that provides helpful details or guidance. - * - `success`: Positive outcomes, successful operations, or confirmations. - * - `caution`: Warnings about potential issues that require attention but aren't critical. - * - `warning`: Similar to caution, indicates something that needs user awareness. - * - `critical`: Errors, failures, or urgent issues that require immediate attention. - * - `accent`: Highlighted or emphasized content that doesn't fit other semantic tones. - * - `custom`: Custom color treatment defined by your theme or implementation. + * In some cases, like for Banner, the tone may also affect the semantic and accessibility treatment of the component. * * @default 'auto' - * @publicDocs */ export type ToneKeyword = | 'auto' @@ -331,674 +260,626 @@ export type ToneKeyword = | 'critical' | 'accent' | 'custom'; -declare const privateIconArray: readonly [ - 'adjust', - 'affiliate', - 'airplane', - 'alert-bubble', - 'alert-circle', - 'alert-diamond', - 'alert-location', - 'alert-octagon', - 'alert-octagon-filled', - 'alert-triangle', - 'alert-triangle-filled', - 'app-extension', - 'apps', - 'archive', - 'arrow-down', - 'arrow-down-circle', - 'arrow-down-right', - 'arrow-left', - 'arrow-left-circle', - 'arrow-right', - 'arrow-right-circle', - 'arrow-up', - 'arrow-up-circle', - 'arrow-up-right', - 'arrows-in-horizontal', - 'arrows-out-horizontal', - 'asterisk', - 'attachment', - 'automation', - 'backspace', - 'bag', - 'bank', - 'barcode', - 'battery-low', - 'bill', - 'blank', - 'blog', - 'bolt', - 'bolt-filled', - 'book', - 'book-open', - 'bug', - 'bullet', - 'business-entity', - 'button', - 'button-press', - 'calculator', - 'calendar', - 'calendar-check', - 'calendar-compare', - 'calendar-list', - 'calendar-time', - 'camera', - 'camera-flip', - 'caret-down', - 'caret-left', - 'caret-right', - 'caret-up', - 'cart', - 'cart-abandoned', - 'cart-discount', - 'cart-down', - 'cart-filled', - 'cart-sale', - 'cart-send', - 'cart-up', - 'cash-dollar', - 'cash-euro', - 'cash-pound', - 'cash-rupee', - 'cash-yen', - 'catalog-product', - 'categories', - 'channels', - 'chart-cohort', - 'chart-donut', - 'chart-funnel', - 'chart-histogram-first', - 'chart-histogram-first-last', - 'chart-histogram-flat', - 'chart-histogram-full', - 'chart-histogram-growth', - 'chart-histogram-last', - 'chart-histogram-second-last', - 'chart-horizontal', - 'chart-line', - 'chart-popular', - 'chart-stacked', - 'chart-vertical', - 'chat', - 'chat-new', - 'chat-referral', - 'check', - 'check-circle', - 'check-circle-filled', - 'checkbox', - 'chevron-down', - 'chevron-down-circle', - 'chevron-left', - 'chevron-left-circle', - 'chevron-right', - 'chevron-right-circle', - 'chevron-up', - 'chevron-up-circle', - 'circle', - 'circle-dashed', - 'clipboard', - 'clipboard-check', - 'clipboard-checklist', - 'clock', - 'clock-list', - 'clock-revert', - 'code', - 'code-add', - 'collection', - 'collection-featured', - 'collection-list', - 'collection-reference', - 'color', - 'color-none', - 'compass', - 'complete', - 'compose', - 'confetti', - 'connect', - 'content', - 'contract', - 'corner-pill', - 'corner-round', - 'corner-square', - 'credit-card', - 'credit-card-cancel', - 'credit-card-percent', - 'credit-card-reader', - 'credit-card-reader-chip', - 'credit-card-reader-tap', - 'credit-card-secure', - 'credit-card-tap-chip', - 'crop', - 'currency-convert', - 'cursor', - 'cursor-banner', - 'cursor-option', - 'data-presentation', - 'data-table', - 'database', - 'database-add', - 'database-connect', - 'delete', - 'delivered', - 'delivery', - 'desktop', - 'disabled', - 'disabled-filled', - 'discount', - 'discount-add', - 'discount-automatic', - 'discount-code', - 'discount-remove', - 'dns-settings', - 'dock-floating', - 'dock-side', - 'domain', - 'domain-landing-page', - 'domain-new', - 'domain-redirect', - 'download', - 'drag-drop', - 'drag-handle', - 'drawer', - 'duplicate', - 'edit', - 'email', - 'email-follow-up', - 'email-newsletter', - 'empty', - 'enabled', - 'enter', - 'envelope', - 'envelope-soft-pack', - 'eraser', - 'exchange', - 'exit', - 'export', - 'external', - 'eye-check-mark', - 'eye-dropper', - 'eye-dropper-list', - 'eye-first', - 'eyeglasses', - 'fav', - 'favicon', - 'file', - 'file-list', - 'filter', - 'filter-active', - 'flag', - 'flip-horizontal', - 'flip-vertical', - 'flower', - 'folder', - 'folder-add', - 'folder-down', - 'folder-remove', - 'folder-up', - 'food', - 'foreground', - 'forklift', - 'forms', - 'games', - 'gauge', - 'geolocation', - 'gift', - 'gift-card', - 'git-branch', - 'git-commit', - 'git-repository', - 'globe', - 'globe-asia', - 'globe-europe', - 'globe-lines', - 'globe-list', - 'graduation-hat', - 'grid', - 'hashtag', - 'hashtag-decimal', - 'hashtag-list', - 'heart', - 'hide', - 'hide-filled', - 'home', - 'home-filled', - 'icons', - 'identity-card', - 'image', - 'image-add', - 'image-alt', - 'image-explore', - 'image-magic', - 'image-none', - 'image-with-text-overlay', - 'images', - 'import', - 'in-progress', - 'incentive', - 'incoming', - 'incomplete', - 'info', - 'info-filled', - 'inheritance', - 'inventory', - 'inventory-edit', - 'inventory-list', - 'inventory-transfer', - 'inventory-updated', - 'iq', - 'key', - 'keyboard', - 'keyboard-filled', - 'keyboard-hide', - 'keypad', - 'label-printer', - 'language', - 'language-translate', - 'layout-block', - 'layout-buy-button', - 'layout-buy-button-horizontal', - 'layout-buy-button-vertical', - 'layout-column-1', - 'layout-columns-2', - 'layout-columns-3', - 'layout-footer', - 'layout-header', - 'layout-logo-block', - 'layout-popup', - 'layout-rows-2', - 'layout-section', - 'layout-sidebar-left', - 'layout-sidebar-right', - 'lightbulb', - 'link', - 'link-list', - 'list-bulleted', - 'list-bulleted-filled', - 'list-numbered', - 'live', - 'live-critical', - 'live-none', - 'location', - 'location-none', - 'lock', - 'map', - 'markets', - 'markets-euro', - 'markets-rupee', - 'markets-yen', - 'maximize', - 'measurement-size', - 'measurement-size-list', - 'measurement-volume', - 'measurement-volume-list', - 'measurement-weight', - 'measurement-weight-list', - 'media-receiver', - 'megaphone', - 'mention', - 'menu', - 'menu-filled', - 'menu-horizontal', - 'menu-vertical', - 'merge', - 'metafields', - 'metaobject', - 'metaobject-list', - 'metaobject-reference', - 'microphone', - 'microphone-muted', - 'minimize', - 'minus', - 'minus-circle', - 'mobile', - 'money', - 'money-none', - 'money-split', - 'moon', - 'nature', - 'note', - 'note-add', - 'notification', - 'number-one', - 'order', - 'order-batches', - 'order-draft', - 'order-filled', - 'order-first', - 'order-fulfilled', - 'order-repeat', - 'order-unfulfilled', - 'orders-status', - 'organization', - 'outdent', - 'outgoing', - 'package', - 'package-cancel', - 'package-fulfilled', - 'package-on-hold', - 'package-reassign', - 'package-returned', - 'page', - 'page-add', - 'page-attachment', - 'page-clock', - 'page-down', - 'page-heart', - 'page-list', - 'page-reference', - 'page-remove', - 'page-report', - 'page-up', - 'pagination-end', - 'pagination-start', - 'paint-brush-flat', - 'paint-brush-round', - 'paper-check', - 'partially-complete', - 'passkey', - 'paste', - 'pause-circle', - 'payment', - 'payment-capture', - 'payout', - 'payout-dollar', - 'payout-euro', - 'payout-pound', - 'payout-rupee', - 'payout-yen', - 'person', - 'person-add', - 'person-exit', - 'person-filled', - 'person-list', - 'person-lock', - 'person-remove', - 'person-segment', - 'personalized-text', - 'phablet', - 'phone', - 'phone-down', - 'phone-down-filled', - 'phone-in', - 'phone-out', - 'pin', - 'pin-remove', - 'plan', - 'play', - 'play-circle', - 'plus', - 'plus-circle', - 'plus-circle-down', - 'plus-circle-filled', - 'plus-circle-up', - 'point-of-sale', - 'point-of-sale-register', - 'price-list', - 'print', - 'product', - 'product-add', - 'product-cost', - 'product-filled', - 'product-list', - 'product-reference', - 'product-remove', - 'product-return', - 'product-unavailable', - 'profile', - 'profile-filled', - 'question-circle', - 'question-circle-filled', - 'radio-control', - 'receipt', - 'receipt-dollar', - 'receipt-euro', - 'receipt-folded', - 'receipt-paid', - 'receipt-pound', - 'receipt-refund', - 'receipt-rupee', - 'receipt-yen', - 'receivables', - 'redo', - 'referral-code', - 'refresh', - 'remove-background', - 'reorder', - 'replace', - 'replay', - 'reset', - 'return', - 'reward', - 'rocket', - 'rotate-left', - 'rotate-right', - 'sandbox', - 'save', - 'savings', - 'scan-qr-code', - 'search', - 'search-add', - 'search-list', - 'search-recent', - 'search-resource', - 'select', - 'send', - 'settings', - 'share', - 'shield-check-mark', - 'shield-none', - 'shield-pending', - 'shield-person', - 'shipping-label', - 'shipping-label-cancel', - 'shopcodes', - 'slideshow', - 'smiley-happy', - 'smiley-joy', - 'smiley-neutral', - 'smiley-sad', - 'social-ad', - 'social-post', - 'sort', - 'sort-ascending', - 'sort-descending', - 'sound', - 'split', - 'sports', - 'star', - 'star-circle', - 'star-filled', - 'star-half', - 'star-list', - 'status', - 'status-active', - 'stop-circle', - 'store', - 'store-import', - 'store-managed', - 'store-online', - 'sun', - 'table', - 'table-masonry', - 'tablet', - 'target', - 'tax', - 'team', - 'text', - 'text-align-center', - 'text-align-left', - 'text-align-right', - 'text-block', - 'text-bold', - 'text-color', - 'text-font', - 'text-font-list', - 'text-grammar', - 'text-in-columns', - 'text-in-rows', - 'text-indent', - 'text-indent-remove', - 'text-italic', - 'text-quote', - 'text-title', - 'text-underline', - 'text-with-image', - 'theme', - 'theme-edit', - 'theme-store', - 'theme-template', - 'three-d-environment', - 'thumbs-down', - 'thumbs-up', - 'tip-jar', - 'toggle-off', - 'toggle-on', - 'transaction', - 'transaction-fee-add', - 'transaction-fee-dollar', - 'transaction-fee-euro', - 'transaction-fee-pound', - 'transaction-fee-rupee', - 'transaction-fee-yen', - 'transfer', - 'transfer-in', - 'transfer-internal', - 'transfer-out', - 'truck', - 'undo', - 'unknown-device', - 'unlock', - 'upload', - 'variant', - 'variant-list', - 'video', - 'video-list', - 'view', - 'viewport-narrow', - 'viewport-short', - 'viewport-tall', - 'viewport-wide', - 'wallet', - 'wand', - 'watch', - 'wifi', - 'work', - 'work-list', - 'wrench', - 'x', - 'x-circle', - 'x-circle-filled', -]; -/** - * Represents the available icon names that can be used in icon components. - * This is derived from the complete list of supported icons in the design system. - * @publicDocs - */ -export type IconType = (typeof privateIconArray)[number]; +export type IconType = + | 'adjust' + | 'affiliate' + | 'airplane' + | 'alert-bubble' + | 'alert-circle' + | 'alert-diamond' + | 'alert-location' + | 'alert-octagon' + | 'alert-octagon-filled' + | 'alert-triangle' + | 'alert-triangle-filled' + | 'align-horizontal-centers' + | 'app-extension' + | 'apps' + | 'archive' + | 'arrow-down' + | 'arrow-down-circle' + | 'arrow-down-right' + | 'arrow-left' + | 'arrow-left-circle' + | 'arrow-right' + | 'arrow-right-circle' + | 'arrow-up' + | 'arrow-up-circle' + | 'arrow-up-right' + | 'arrows-in-horizontal' + | 'arrows-out-horizontal' + | 'asterisk' + | 'attachment' + | 'automation' + | 'backspace' + | 'bag' + | 'bank' + | 'barcode' + | 'battery-low' + | 'bill' + | 'blank' + | 'blog' + | 'bolt' + | 'bolt-filled' + | 'book' + | 'book-open' + | 'brain' + | 'bug' + | 'bullet' + | 'business-entity' + | 'button' + | 'button-press' + | 'calculator' + | 'calendar' + | 'calendar-check' + | 'calendar-compare' + | 'calendar-list' + | 'calendar-time' + | 'camera' + | 'camera-flip' + | 'caret-down' + | 'caret-left' + | 'caret-right' + | 'caret-up' + | 'cart' + | 'cart-abandoned' + | 'cart-discount' + | 'cart-down' + | 'cart-filled' + | 'cart-sale' + | 'cart-send' + | 'cart-up' + | 'cash-dollar' + | 'cash-euro' + | 'cash-pound' + | 'cash-rupee' + | 'cash-yen' + | 'catalog-product' + | 'categories' + | 'channels' + | 'channels-filled' + | 'chart-cohort' + | 'chart-donut' + | 'chart-funnel' + | 'chart-histogram-first' + | 'chart-histogram-first-last' + | 'chart-histogram-flat' + | 'chart-histogram-full' + | 'chart-histogram-growth' + | 'chart-histogram-last' + | 'chart-histogram-second-last' + | 'chart-horizontal' + | 'chart-line' + | 'chart-popular' + | 'chart-stacked' + | 'chart-vertical' + | 'chat' + | 'chat-new' + | 'chat-referral' + | 'check' + | 'check-circle' + | 'check-circle-filled' + | 'checkbox' + | 'chevron-down' + | 'chevron-down-circle' + | 'chevron-left' + | 'chevron-left-circle' + | 'chevron-right' + | 'chevron-right-circle' + | 'chevron-up' + | 'chevron-up-circle' + | 'circle' + | 'circle-dashed' + | 'clipboard' + | 'clipboard-check' + | 'clipboard-checklist' + | 'clock' + | 'clock-list' + | 'clock-revert' + | 'code' + | 'code-add' + | 'collection' + | 'collection-featured' + | 'collection-list' + | 'collection-reference' + | 'color' + | 'color-none' + | 'compass' + | 'complete' + | 'compose' + | 'confetti' + | 'connect' + | 'content' + | 'contract' + | 'corner-pill' + | 'corner-round' + | 'corner-square' + | 'credit-card' + | 'credit-card-cancel' + | 'credit-card-percent' + | 'credit-card-reader' + | 'credit-card-reader-chip' + | 'credit-card-reader-tap' + | 'credit-card-secure' + | 'credit-card-tap-chip' + | 'crop' + | 'currency-convert' + | 'cursor' + | 'cursor-banner' + | 'cursor-option' + | 'data-presentation' + | 'data-table' + | 'database' + | 'database-add' + | 'database-connect' + | 'delete' + | 'delivered' + | 'delivery' + | 'desktop' + | 'disabled' + | 'disabled-filled' + | 'discount' + | 'discount-add' + | 'discount-automatic' + | 'discount-code' + | 'discount-remove' + | 'dns-settings' + | 'dock-floating' + | 'dock-side' + | 'domain' + | 'domain-landing-page' + | 'domain-new' + | 'domain-redirect' + | 'download' + | 'drag-drop' + | 'drag-handle' + | 'drawer' + | 'duplicate' + | 'edit' + | 'email' + | 'email-follow-up' + | 'email-newsletter' + | 'empty' + | 'enabled' + | 'enter' + | 'envelope' + | 'envelope-soft-pack' + | 'eraser' + | 'exchange' + | 'exit' + | 'export' + | 'external' + | 'eye-check-mark' + | 'eye-dropper' + | 'eye-dropper-list' + | 'eye-first' + | 'eyeglasses' + | 'fav' + | 'favicon' + | 'file' + | 'file-list' + | 'filter' + | 'filter-active' + | 'flag' + | 'flip-horizontal' + | 'flip-vertical' + | 'flower' + | 'folder' + | 'folder-add' + | 'folder-down' + | 'folder-remove' + | 'folder-up' + | 'food' + | 'foreground' + | 'forklift' + | 'forms' + | 'games' + | 'gauge' + | 'geolocation' + | 'gift' + | 'gift-card' + | 'git-branch' + | 'git-commit' + | 'git-repository' + | 'globe' + | 'globe-asia' + | 'globe-europe' + | 'globe-lines' + | 'globe-list' + | 'graduation-hat' + | 'grid' + | 'hashtag' + | 'hashtag-decimal' + | 'hashtag-list' + | 'heart' + | 'hide' + | 'hide-filled' + | 'home' + | 'home-filled' + | 'icons' + | 'identity-card' + | 'image' + | 'image-add' + | 'image-alt' + | 'image-explore' + | 'image-magic' + | 'image-none' + | 'image-with-text-overlay' + | 'images' + | 'import' + | 'in-progress' + | 'incentive' + | 'incoming' + | 'incomplete' + | 'info' + | 'info-filled' + | 'inheritance' + | 'inventory' + | 'inventory-edit' + | 'inventory-list' + | 'inventory-transfer' + | 'inventory-updated' + | 'iq' + | 'key' + | 'keyboard' + | 'keyboard-filled' + | 'keyboard-hide' + | 'keypad' + | 'label-printer' + | 'language' + | 'language-translate' + | 'layout-block' + | 'layout-buy-button' + | 'layout-buy-button-horizontal' + | 'layout-buy-button-vertical' + | 'layout-column-1' + | 'layout-columns-2' + | 'layout-columns-3' + | 'layout-footer' + | 'layout-header' + | 'layout-logo-block' + | 'layout-popup' + | 'layout-rows-2' + | 'layout-section' + | 'layout-sidebar-left' + | 'layout-sidebar-right' + | 'layer' + | 'lightbulb' + | 'link' + | 'link-list' + | 'list-bulleted' + | 'list-bulleted-filled' + | 'list-numbered' + | 'live' + | 'live-critical' + | 'live-none' + | 'location' + | 'location-none' + | 'lock' + | 'map' + | 'markets' + | 'markets-euro' + | 'markets-rupee' + | 'markets-yen' + | 'maximize' + | 'measurement-size' + | 'measurement-size-list' + | 'measurement-volume' + | 'measurement-volume-list' + | 'measurement-weight' + | 'measurement-weight-list' + | 'media-receiver' + | 'megaphone' + | 'mention' + | 'menu' + | 'menu-filled' + | 'menu-horizontal' + | 'menu-vertical' + | 'merge' + | 'metafields' + | 'metaobject' + | 'metaobject-list' + | 'metaobject-reference' + | 'microphone' + | 'microphone-muted' + | 'minimize' + | 'minus' + | 'minus-circle' + | 'mobile' + | 'money' + | 'money-none' + | 'money-split' + | 'moon' + | 'nature' + | 'note' + | 'note-add' + | 'notification' + | 'number-one' + | 'order' + | 'order-batches' + | 'order-draft' + | 'order-filled' + | 'order-first' + | 'order-fulfilled' + | 'order-repeat' + | 'order-unfulfilled' + | 'orders-status' + | 'organization' + | 'outdent' + | 'outgoing' + | 'package' + | 'package-cancel' + | 'package-fulfilled' + | 'package-on-hold' + | 'package-reassign' + | 'package-returned' + | 'page' + | 'page-add' + | 'page-attachment' + | 'page-clock' + | 'page-down' + | 'page-heart' + | 'page-list' + | 'page-reference' + | 'page-remove' + | 'page-report' + | 'page-up' + | 'pagination-end' + | 'pagination-start' + | 'paint-brush-flat' + | 'paint-brush-round' + | 'paper-check' + | 'partially-complete' + | 'passkey' + | 'paste' + | 'pause-circle' + | 'payment' + | 'payment-capture' + | 'payout' + | 'payout-dollar' + | 'payout-euro' + | 'payout-pound' + | 'payout-rupee' + | 'payout-yen' + | 'person' + | 'person-add' + | 'person-exit' + | 'person-filled' + | 'person-list' + | 'person-lock' + | 'person-remove' + | 'person-segment' + | 'personalized-text' + | 'phablet' + | 'phone' + | 'phone-down' + | 'phone-down-filled' + | 'phone-in' + | 'phone-out' + | 'pin' + | 'pin-remove' + | 'plan' + | 'play' + | 'play-circle' + | 'plus' + | 'plus-circle' + | 'plus-circle-down' + | 'plus-circle-filled' + | 'plus-circle-up' + | 'point-of-sale' + | 'point-of-sale-register' + | 'price-list' + | 'print' + | 'product' + | 'product-add' + | 'product-cost' + | 'product-filled' + | 'product-list' + | 'product-reference' + | 'product-remove' + | 'product-return' + | 'product-unavailable' + | 'profile' + | 'profile-filled' + | 'question-circle' + | 'question-circle-filled' + | 'radio-control' + | 'receipt' + | 'receipt-dollar' + | 'receipt-euro' + | 'receipt-folded' + | 'receipt-paid' + | 'receipt-pound' + | 'receipt-refund' + | 'receipt-rupee' + | 'receipt-yen' + | 'receivables' + | 'redo' + | 'referral-code' + | 'refresh' + | 'remove-background' + | 'reorder' + | 'replace' + | 'replay' + | 'reset' + | 'return' + | 'reward' + | 'rocket' + | 'rotate-left' + | 'rotate-right' + | 'sandbox' + | 'save' + | 'savings' + | 'scan-qr-code' + | 'search' + | 'search-add' + | 'search-list' + | 'search-recent' + | 'search-resource' + | 'select' + | 'send' + | 'settings' + | 'share' + | 'shield-check-mark' + | 'shield-none' + | 'shield-pending' + | 'shield-person' + | 'shipping-label' + | 'shipping-label-cancel' + | 'shopcodes' + | 'slideshow' + | 'smiley-happy' + | 'smiley-joy' + | 'smiley-neutral' + | 'smiley-sad' + | 'social-ad' + | 'social-post' + | 'sort' + | 'sort-ascending' + | 'sort-descending' + | 'sound' + | 'split' + | 'sports' + | 'star' + | 'star-circle' + | 'star-filled' + | 'star-half' + | 'star-list' + | 'status' + | 'status-active' + | 'stop-circle' + | 'store' + | 'store-import' + | 'store-managed' + | 'store-online' + | 'sun' + | 'table' + | 'table-masonry' + | 'tablet' + | 'target' + | 'tax' + | 'team' + | 'text' + | 'text-align-center' + | 'text-align-left' + | 'text-align-right' + | 'text-block' + | 'text-bold' + | 'text-color' + | 'text-font' + | 'text-font-list' + | 'text-grammar' + | 'text-in-columns' + | 'text-in-rows' + | 'text-indent' + | 'text-indent-remove' + | 'text-italic' + | 'text-quote' + | 'text-title' + | 'text-underline' + | 'text-with-image' + | 'theme' + | 'theme-cart' + | 'theme-edit' + | 'theme-store' + | 'theme-template' + | 'three-d-environment' + | 'thumbs-down' + | 'thumbs-up' + | 'tip-jar' + | 'toggle-off' + | 'toggle-on' + | 'transaction' + | 'transaction-fee-add' + | 'transaction-fee-dollar' + | 'transaction-fee-euro' + | 'transaction-fee-pound' + | 'transaction-fee-rupee' + | 'transaction-fee-yen' + | 'transfer' + | 'transfer-in' + | 'transfer-internal' + | 'transfer-out' + | 'truck' + | 'undo' + | 'unknown-device' + | 'unlock' + | 'upload' + | 'variant' + | 'variant-list' + | 'video' + | 'video-list' + | 'view' + | 'viewport-narrow' + | 'viewport-short' + | 'viewport-tall' + | 'viewport-wide' + | 'wallet' + | 'wand' + | 'watch' + | 'wifi' + | 'work' + | 'work-list' + | 'wrench' + | 'x' + | 'x-circle' + | 'x-circle-filled'; /** - * A type-safe version of TypeScript's `Extract` utility that constrains the second type parameter - * to be assignable to the first. This provides compile-time validation that you're only extracting - * types that actually exist within the union, catching potential errors earlier in development. - * - * @publicDocs + * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type. */ export type ExtractStrict = Extract; -/** - * Represents CSS shorthand properties that accept one to four values. - * Supports specifying values for all four sides: top, right, bottom, and left. - * - * - `T`: Single value that applies to all four sides. - * - `${T} ${T}`: Two values for block axis (top/bottom) and inline axis (left/right). - * - `${T} ${T} ${T}`: Three values for block-start (top), inline axis (left/right), and block-end (bottom). - * - `${T} ${T} ${T} ${T}`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left). - * @publicDocs - */ export type MaybeAllValuesShorthandProperty = | T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`; -/** - * Represents CSS shorthand properties that accept one or two values. - * Supports specifying the same value for both dimensions or different values. - * - * - `T`: Single value that applies to both dimensions. - * - `${T} ${T}`: Two values for block axis (vertical) and inline axis (horizontal). - * @publicDocs - */ export type MaybeTwoValuesShorthandProperty = T | `${T} ${T}`; -/** - * Makes a property responsive by allowing it to be set conditionally based on container query conditions. - * The value can be either a base value or a container query string. - * - * - `T`: Base value that applies in all conditions. - * - `@container${string}`: Container query string for conditional responsive styling based on container size. - * @publicDocs - */ export type MaybeResponsive = T | `@container${string}`; /** - * A utility type that enables autocomplete for specific string literals while still accepting any string value. - * By intersecting `string` with an empty object type, this prevents TypeScript from widening literal types, - * preserving IDE suggestions for known values while maintaining flexibility for custom strings. - * - * @publicDocs + * Prevents widening string literal types in a union to `string`. + * @example + * type PropName = 'foo' | 'bar' | string + * // ^? string + * type PropName = 'foo' | 'bar' | (string & {}) + * // ^? 'foo' | 'bar' | (string & {}) */ export type AnyString = string & {}; /** - * A utility type representing an optional space character for use in string literal type composition. - * Allows flexible formatting of compound values where spacing is a matter of preference rather than semantic difference. + * This is purely to give the ability + * to have a space or not in the string literal types. * - * @publicDocs + * For example in the `aspectRatio` property, `16/9` and `16 / 9` are both valid. */ export type optionalSpace = '' | ' '; interface BadgeProps$1 extends GlobalProps { /** - * The text label displayed within the badge, typically a short status indicator or category label. + * The content of the Badge. */ children?: ComponentChildren; /** - * The semantic meaning and color treatment of the component. - * - * - `info`: Informational content or helpful tips. - * - `success`: Positive outcomes or successful states. - * - `warning`: Important warnings about potential issues. - * - `critical`: Urgent problems or destructive actions. - * - `auto`: Automatically determined based on context. - * - `neutral`: General information without specific intent. - * - `caution`: Advisory notices that need attention. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ tone?: ToneKeyword; /** - * Controls the visual weight and emphasis of the badge. - * - * - `base`: Standard weight with moderate emphasis, suitable for most use cases. - * - `strong`: Increased visual weight for higher emphasis and prominence. + * Modify the color to be more or less intense. * * @default 'base' */ color?: ColorKeyword; /** - * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. - * Accepts any icon name from the icon library or a custom string identifier. + * The type of icon to be displayed in the badge. * * @default '' */ icon?: IconType | AnyString; /** - * The position of the icon relative to the badge text. - * - * - `start`: Places the icon before the text (left in left-to-right languages, right in right-to-left languages). - * - `end`: Places the icon after the text (right in left-to-right languages, left in right-to-left languages). - * - * @default 'start' + * The position of the icon in relation to the text. */ iconPosition?: 'start' | 'end'; /** - * The size of the badge component. Available sizes range from `small-500` (smallest) to `large-500` (largest), with `base` providing the default medium size. + * Adjusts the size. * * @default 'base' */ @@ -1006,52 +887,58 @@ interface BadgeProps$1 extends GlobalProps { } interface BannerProps$1 extends GlobalProps, ActionSlots { /** - * The heading text displayed at the top of the banner. + * The title of the banner. * * @default '' */ heading?: string; /** - * The main message content displayed within the banner, providing important information or guidance to users. + * The content of the Banner. */ children?: ComponentChildren; /** - * The semantic meaning and color treatment of the component. + * Sets the tone of the Banner, based on the intention of the information being conveyed. * - * - `info`: Informational content or helpful tips. - * - `success`: Positive outcomes or successful states. - * - `warning`: Important warnings about potential issues. - * - `critical`: Urgent problems or destructive actions. - * - `auto`: Automatically determined based on context. + * The banner is a live region and the type of status will be dictated by the Tone selected. + * + * - `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. When true, child elements are initially hidden but can be - * revealed by the user expanding the banner. + * 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 the banner displays a close button that allows users to dismiss it. + * Determines whether the close button of the banner is present. * - * When the close button is pressed, the `dismiss` event fires, then `hidden` is set to `true`, - * any animation completes, and the `afterhide` event fires. + * 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; /** - * A callback fired when the banner is dismissed by the user clicking the close button. - * Does not fire when setting `hidden` manually. + * Event handler when the banner is dismissed by the user. + * + * This does not fire when setting `hidden` manually. * - * The `hidden` property is `false` when this event fires. + * The `hidden` property will be `false` when this event fires. */ onDismiss?: (event: Event) => void; /** - * A callback fired when the banner has fully hidden, including after any hide animations have completed. + * Event handler when the banner has fully hidden. * * The `hidden` property will be `true` when this event fires. * @@ -1061,35 +948,33 @@ interface BannerProps$1 extends GlobalProps, ActionSlots { */ onAfterHide?: (event: Event) => void; /** - * Controls whether the banner is visible or hidden. + * Determines whether the banner is hidden. * - * When using a controlled component pattern and the banner is `dismissible`, - * update this property to `true` when the `dismiss` event fires. + * 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. * - * You can hide the banner programmatically by setting this to `true` even if it's not `dismissible`. + * If the banner is not `dismissible`, it can still be hidden by setting this property. * * @default false */ hidden?: boolean; } -/** @publicDocs */ export interface DisplayProps { /** - * 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). + * 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. * - * Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display). - * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display * @default 'auto' */ display?: MaybeResponsive<'auto' | 'none'>; } -/** @publicDocs */ export interface AccessibilityRoleProps { /** - * The semantic meaning of the component’s content. When set, + * 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. * @@ -1100,63 +985,31 @@ export interface AccessibilityRoleProps { */ accessibilityRole?: AccessibilityRole; } -/** - * Defines the semantic role of a component for assistive technologies like screen readers. - * - * Accessibility roles help users with disabilities understand the purpose and structure of content. - * These roles map to HTML elements and ARIA roles, providing semantic meaning beyond visual presentation. - * - * Use these roles to: - * - Improve navigation for screen reader users - * - Provide semantic structure to your UI - * - Ensure proper interpretation by assistive technologies - * - * Learn more about [ARIA roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) in the MDN web docs. - * - * - `main`: Indicates the primary content area of the page. - * - `header`: Marks a component as a header containing introductory content or navigation. - * - `footer`: Designates content containing information like copyright, navigation links, or privacy statements. - * - `section`: Defines a generic thematic grouping of content that should have a heading or accessible label. - * - `aside`: Marks supporting content that relates to but is separate from the main content. - * - `navigation`: Identifies major groups of navigation links for moving around the site or page. - * - `ordered-list`: Represents a list where the order of items is meaningful. - * - `list-item`: Identifies an individual item within a list. - * - `list-item-separator`: Acts as a visual and semantic divider between items in a list. - * - `unordered-list`: Represents a list where the order of items is not meaningful. - * - `separator`: Creates a divider that separates and distinguishes sections of content. - * - `status`: Defines a live region for advisory information that is not urgent enough to be an alert. - * - `alert`: Marks important, time-sensitive information that requires the user's immediate attention. - * - `generic`: Creates a semantically neutral container element with no inherent meaning. - * - `presentation`: Removes semantic meaning from an element while preserving its visual appearance. - * - `none`: Synonym for `presentation`, removes semantic meaning while keeping visual styling. - * @publicDocs - */ export type AccessibilityRole = /** - * An accessibility role used to indicate the primary content. + * Used to indicate the primary content. * * In an HTML host, `main` will render a `
` element. * Learn more about the [`
` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) in the MDN web docs. */ | 'main' /** - * An accessibility role used to indicate the component is a header. + * Used to indicate the component is a header. * * In an HTML host `header` will render a `
` element. * Learn more about the [`
` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) in the MDN web docs. */ | 'header' /** - * An accessibility role used to display information such as copyright information, navigation links, and privacy statements. + * Used to display information such as copyright information, navigation links, and privacy statements. * * In an HTML host `footer` will render a `