From b9981471d91e01d125096b4a4432b59bd1982a14 Mon Sep 17 00:00:00 2001 From: Richard Gajda Date: Fri, 18 Sep 2026 12:21:06 -0400 Subject: [PATCH 1/2] docs(pos): correct component contracts and input examples --- .changeset/pos-component-contract-docs.md | 5 + .../surfaces/point-of-sale/components.d.ts | 4187 ++++++++++------- .../examples/controls-constraints.jsx | 2 +- .../Switch/examples/event-handling.html | 5 - .../Switch/examples/event-handling.jsx | 7 + .../TimeField/examples/default.html | 5 +- .../TimeField/examples/event-handling.jsx | 4 +- .../TimePicker/examples/command-system.jsx | 6 +- .../TimePicker/examples/default.html | 9 +- .../TimePicker/examples/event-handling.jsx | 4 +- 10 files changed, 2441 insertions(+), 1793 deletions(-) create mode 100644 .changeset/pos-component-contract-docs.md delete mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.html create mode 100644 packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.jsx diff --git a/.changeset/pos-component-contract-docs.md b/.changeset/pos-component-contract-docs.md new file mode 100644 index 0000000000..2489a01e6c --- /dev/null +++ b/.changeset/pos-component-contract-docs.md @@ -0,0 +1,5 @@ +--- +'@shopify/ui-extensions': patch +--- + +Correct POS date and time component callback types to accept null, preserve inherited component declarations during generation, and update component contract documentation and examples. 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 915a32f478..d45368682b 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 @@ -20,11 +20,6 @@ export interface GlobalProps { */ id?: string; } - -/** - * Components with ActionSlots support passing primary and secondary action content. - * @publicDocs - */ export interface ActionSlots { /** * The primary action to perform, provided as a button or link type element. @@ -700,22 +695,17 @@ declare const privateIconArray: readonly [ 'x-circle', 'x-circle-filled', ]; -/** @publicDocs */ export type IconType = (typeof privateIconArray)[number]; /** * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type. - * @publicDocs */ export type ExtractStrict = Extract; -/** @publicDocs */ export type MaybeAllValuesShorthandProperty = | T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`; -/** @publicDocs */ export type MaybeTwoValuesShorthandProperty = T | `${T} ${T}`; -/** @publicDocs */ export type MaybeResponsive = T | `@container${string}`; /** * Prevents widening string literal types in a union to `string`. @@ -724,7 +714,6 @@ export type MaybeResponsive = T | `@container${string}`; * // ^? string * type PropName = 'foo' | 'bar' | (string & {}) * // ^? 'foo' | 'bar' | (string & {}) - * @publicDocs */ export type AnyString = string & {}; /** @@ -732,16 +721,15 @@ export type AnyString = string & {}; * 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. - * @publicDocs */ export type optionalSpace = '' | ' '; export interface BadgeProps extends GlobalProps { /** - * The content of the badge. + * The content of the Badge. */ children?: ComponentChildren; /** - * Sets the tone of the badge, based on the intention of the information being conveyed. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -777,11 +765,11 @@ export interface BannerProps extends GlobalProps, ActionSlots { */ heading?: string; /** - * The content of the banner. + * The content of the Banner. */ children?: ComponentChildren; /** - * Sets the tone of the banner, based on the intention of the information being conveyed. + * 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. * @@ -893,7 +881,7 @@ export type AccessibilityRole = | 'footer' /** * Used to indicate a generic section. - * Sections should always have a heading or an accessible name provided in the `accessibilityLabel` property. + * Sections should always have a `Heading` or an accessible name provided in the `accessibilityLabel` property. * * In an HTML host `section` will render a `
` element. * Learn more about the [`
` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) in the MDN web docs. @@ -1264,7 +1252,7 @@ export interface BaseBoxProps BorderProps, OverflowProps { /** - * The content of the box. + * The content of the Box. */ children?: ComponentChildren; /** @@ -1280,7 +1268,7 @@ export interface BaseBoxPropsWithRole AccessibilityRoleProps {} export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** - * The behavior of the button. + * 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. @@ -1292,14 +1280,14 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { */ type?: 'submit' | 'button' | 'reset'; /** - * Callback when the button is activated. + * Callback when the Button is activated. * This will be called before the action indicated by `type`. * * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event */ onClick?: (event: Event) => void; /** - * Disables the button meaning it cannot be clicked or receive focus. + * Disables the Button meaning it cannot be clicked or receive focus. * * @default false */ @@ -1307,7 +1295,7 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** * Replaces content with a loading indicator while a background action is being performed. * - * This also disables the button. + * This also disables the Button. * * @default false */ @@ -1384,24 +1372,24 @@ export interface BaseClickableProps LinkBehaviorProps {} export interface ButtonProps extends GlobalProps, BaseClickableProps { /** - * A label that describes the purpose or contents of the button. It will be read to users using assistive technologies such as screen readers. + * 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 + * Use this when using only an icon or the Button text is not enough context * for users using assistive technologies. */ accessibilityLabel?: string; /** - * The content of the button. + * The content of the Button. */ children?: ComponentChildren; /** - * The type of icon to be displayed in the button. + * The type of icon to be displayed in the Button. * * @default '' */ icon?: IconType | AnyString; /** - * The displayed inline width of the button. + * 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. @@ -1411,13 +1399,13 @@ export interface ButtonProps extends GlobalProps, BaseClickableProps { */ inlineSize?: 'auto' | 'fill' | 'fit-content'; /** - * Changes the visual appearance of the button. + * 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 information being conveyed. + * Sets the tone of the Button based on the intention of the information being conveyed. * * @default 'auto' */ @@ -1727,7 +1715,7 @@ export interface ChoiceProps extends GlobalProps, BaseOptionProps { */ details?: ComponentChildren; /** - * Set to `true` to associate a choice with the error passed to ChoiceList + * Set to `true` to associate a choice with the error passed to `ChoiceList` * * @default false */ @@ -1757,7 +1745,7 @@ export interface ChoiceListProps /** * The choices a user can select from. * - * Accepts choice components. + * Accepts `Choice` components. */ children?: ComponentChildren; /** @@ -2263,7 +2251,7 @@ export interface EmbedProps extends GlobalProps, SizingProps { */ src?: string; /** - * A label that describes the purpose or contents of the embed. It will be read to users + * A label that describes the purpose or contents of the Embed. It will be read to users * using assistive technologies such as screen readers. * * @implementation for web-based implementations, this should map to the [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute @@ -2272,15 +2260,15 @@ export interface EmbedProps extends GlobalProps, SizingProps { } export interface EmptyStateProps extends GlobalProps, ActionSlots { /** - * The heading of the empty state. + * The heading of the EmptyState. */ heading?: string; /** - * The subheading of the empty state. + * The subheading of the EmptyState. */ subheading?: ComponentChildren | StringChildren; /** - * The graphic to display in the empty state. The only supported components are Image and Icon. + * The graphic to display in the EmptyState. The only supported components are `Image` and `Icon`. */ graphic?: ComponentChildren; } @@ -2414,7 +2402,7 @@ export interface HeadingProps AccessibilityVisibilityProps, BlockTypographyProps { /** - * The content of the heading. + * The content of the Heading. */ children?: ComponentChildren; /** @@ -2583,17 +2571,17 @@ export interface ImageProps extends GlobalProps, BaseImageProps, BorderProps { } export interface LinkProps extends GlobalProps, LinkBehaviorProps { /** - * The content of the link. + * The content of the Link. */ children?: ComponentChildren; /** - * Sets the tone of the link, based on the intention of the information being conveyed. + * 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. + * 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. @@ -2620,32 +2608,32 @@ export interface ModalProps */ accessibilityLabel?: string; /** - * A title that describes the content of the modal. + * A title that describes the content of the Modal. * */ heading?: string; /** - * Adjust the padding around 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' + * `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'; /** - * Adjust the size of the modal. + * 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. + * `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 content of the modal. + * The content of the Modal. */ children?: ComponentChildren; } @@ -2684,7 +2672,7 @@ export type NumberAutocompleteField = ExtractStrict< >; export interface PageProps extends GlobalProps, ActionSlots { /** - * The content of the page. + * The content of the Page. */ children?: ComponentChildren; /** @@ -2850,14 +2838,14 @@ export interface SearchFieldProps export type SearchAutocompleteField = TextAutocompleteField; export interface SectionProps extends GlobalProps, ActionSlots { /** - * The content of the section. + * The content of the Section. */ children?: ComponentChildren; /** * A label used to describe the section that will be announced by assistive technologies. * - * When no `heading` property is provided or included as a children of the section, you **must** provide an - * `accessibilityLabel` to describe the section. This is important as it allows assistive technologies to provide + * When no `heading` property is provided or included as a children of the Section, you **must** provide an + * `accessibilityLabel` to describe the Section. This is important as it allows assistive technologies to provide * the right context to users. */ accessibilityLabel?: string; @@ -2870,8 +2858,8 @@ export interface SectionProps extends GlobalProps, ActionSlots { * * - `base`: applies padding that is appropriate for the element. Note that it may result in no padding if * this is the right design decision in a particular context. - * - `none`: removes all padding from the element. This can be useful when elements inside the section need to span - * to the edge of the section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base' + * - `none`: removes all padding from the element. This can be useful when elements inside the Section need to span + * to the edge of the Section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base' * to bring back the desired padding for the rest of the content. * * @default 'base' @@ -2899,11 +2887,11 @@ export interface StackProps BaseBoxPropsWithRole, GapProps { /** - * The content of the stack. + * The content of the Stack. */ children?: ComponentChildren; /** - * Sets how the children are placed within the stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). + * Sets how the children are placed within the Stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). * * @default 'block' * @@ -2911,21 +2899,21 @@ export interface StackProps */ direction?: MaybeResponsive<'block' | 'inline'>; /** - * Aligns the stack along the main axis. + * Aligns the Stack along the main axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * @default 'normal' */ justifyContent?: MaybeResponsive; /** - * Aligns the stack's children along the cross axis. + * Aligns the Stack's children along the cross axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items * @default 'normal' */ alignItems?: MaybeResponsive; /** - * Aligns the stack along the cross axis. + * Aligns the Stack along the cross axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content * @default 'normal' @@ -2940,7 +2928,7 @@ export interface SwitchProps FieldErrorProps {} export interface TabProps extends GlobalProps { /** - * Corresponds to the `id` property of the tab panel component that will be displayed when selected + * Corresponds to the `id` property of the TabPanel component that will be displayed when selected */ controls?: string; /** @@ -2964,18 +2952,18 @@ export interface TabProps extends GlobalProps { } export interface TabListProps extends GlobalProps { /** - * Accepts only tabs components. + * Accepts only `Tabs` components. */ children?: ComponentChildren; } export interface TabPanelProps extends GlobalProps { /** - * The id of the tab panel used for identification in the tabs component. - * Must match the `controls` prop of the corresponding tab component. + * The id of the TabPanel used for identification in the Tabs component. + * Must match the `controls` prop of the corresponding Tab component. */ id?: string; /** - * The content of the tab panel. + * The content of the TabPanel. */ children?: ComponentChildren; } @@ -2988,20 +2976,20 @@ export interface TabsProps */ accessibilityLabel?: string; /** - * Accepts only tab list and tab panel components. + * Accepts only `TabList` and `TabPanel` components. */ children?: ComponentChildren; /** * The value of the selected tab. * - * This should match the `id` prop of one of the tab panel components. + * This should match the `id` prop of one of the TabPanel components. * If not provided, the first tab will be selected by default. */ value?: string; /** * The default value of the selected tab. * - * This should match the `id` prop of one of the tab panel components. + * This should match the `id` prop of one of the TabPanel components. * If not provided, the first tab will be selected by default. * * Reflects to the `value` attribute @@ -3141,7 +3129,7 @@ export interface TileProps extends GlobalProps, Pick { /** - * A title that describes the content of the tile. + * A title that describes the content of the Tile. * * @default '' */ @@ -3153,7 +3141,7 @@ export interface TileProps */ subheading?: string; /** - * A numeric indicator rendered within the tile (for example, a count or a step number). + * A numeric indicator rendered within the Tile (for example, a count or a step number). * * - When provided, the indicator is displayed inside the tile. * - Intended for small integers. It may clamp, truncate, or abbreviate larger values. @@ -3161,7 +3149,7 @@ export interface TileProps */ itemCount?: number; /** - * Sets the tone of the tile, based on the intention of the information being conveyed. + * Sets the tone of the Tile, based on the intention of the information being conveyed. * @default 'auto' */ tone?: ExtractStrict; @@ -3489,20 +3477,27 @@ interface BaseElementPropsWithChildren type IntrinsicElementProps = T & BaseElementPropsWithChildren; type HtmlElementTagNameProps = T & HTMLElement; -interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; +type ElementForTag = T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; cancelable?: boolean; composed?: boolean; detail?: any; eventPhase: number; - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } -declare const tagName$E = 's-badge'; +declare const tagName$K = 's-badge'; +/** + * Displays compact status text with optional semantic tone. + * @publicDocs + */ interface BadgeJSXProps extends Pick { /** - * Sets the tone of the badge, based on the intention of the information being conveyed. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -3511,24 +3506,28 @@ interface BadgeJSXProps extends Pick { 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution' >; /** - * The content of the badge. + * The content of the Badge. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$E]: HtmlElementTagNameProps; + [tagName$K]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$E]: IntrinsicElementProps; + [tagName$K]: IntrinsicElementProps; } } } -declare const tagName$D = 's-banner'; +declare const tagName$J = 's-banner'; +/** + * Shows prominent status and messaging content with optional actions. + * @publicDocs + */ interface BannerJSXProps extends Pick { /** * Determines whether the banner is hidden. @@ -3537,7 +3536,7 @@ interface BannerJSXProps extends Pick { */ hidden?: BannerProps['hidden']; /** - * Sets the tone of the banner, based on the intention of the information being conveyed. + * Sets the tone of the Banner, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -3546,30 +3545,39 @@ interface BannerJSXProps extends Pick { 'auto' | 'success' | 'info' | 'warning' | 'critical' >; /** - * The action taken when the banner is pressed. + * The primary action for the banner, provided as a button element in the `primary-action` slot. + * + * The POS renderer displays the action only when the slotted button has both text content and an + * `onClick` handler; otherwise the action is dropped. */ primaryAction?: ComponentChild; /** - * The content of the banner. + * The content of the Banner. + * + * The POS renderer currently doesn't render banner children; use `heading` for the message text. */ children?: ComponentChildren; } -type ElementProps$c = Omit; +type ElementProps$9 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$D]: HtmlElementTagNameProps; + [tagName$J]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$D]: IntrinsicElementProps; + [tagName$J]: IntrinsicElementProps; } } } -declare const tagName$C = 's-box'; +declare const tagName$I = 's-box'; type PaddingKeyword$2 = SizeKeyword | 'none'; +/** + * Provides a generic layout container with sizing and spacing controls. + * @publicDocs + */ interface BoxJSXProps { /** * A unique identifier for the element. @@ -3627,8 +3635,6 @@ interface BoxJSXProps { * - `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`. * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; @@ -3685,24 +3691,28 @@ interface BoxJSXProps { */ paddingInlineEnd?: PaddingKeyword$2 | ''; /** - * The content of the box. + * The content of the Box. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$C]: HtmlElementTagNameProps; + [tagName$I]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$C]: IntrinsicElementProps; + [tagName$I]: IntrinsicElementProps; } } } -declare const tagName$B = 's-button'; +declare const tagName$H = 's-button'; +/** + * Triggers actions when selected by the merchant. + * @publicDocs + */ interface ButtonJSXProps extends Pick< ButtonProps, @@ -3727,7 +3737,7 @@ interface ButtonJSXProps '--auto' | '--show' | '--hide' | '--toggle' >; /** - * Sets the tone of the button, based on the intention of the information being conveyed. + * Sets the tone of the Button, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -3736,7 +3746,7 @@ interface ButtonJSXProps 'auto' | 'critical' | 'neutral' | 'warning' | 'caution' >; /** - * Changes the visual appearance of the button. + * Changes the visual appearance of the Button. * * @default 'auto' */ @@ -3744,213 +3754,334 @@ interface ButtonJSXProps /** * Called when the button is activated. */ - onClick?: (event: CallbackEvent) => void; + onClick?: (event: CallbackEvent) => void; /** - * The content of the button. + * The content of the Button. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$B]: HtmlElementTagNameProps; + [tagName$H]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$B]: IntrinsicElementProps; + [tagName$H]: IntrinsicElementProps; } } } -declare const tagName$A = 's-choice'; +declare const tagName$G = 's-choice'; +/** + * Represents a selectable option within a choice list. + * @publicDocs + */ interface ChoiceJSXProps extends Pick { + /** + * The value that identifies this choice in the `ChoiceList` `values` prop and + * in selection events. + * + * A choice needs a `value` to be selectable. Use a unique value for each choice + * in the list; choices that share a value can't be selected independently. + */ + value?: ChoiceProps['value']; + /** + * Whether the choice is selected. + * + * Selection can also be set with the `values` prop on the `ChoiceList`; the two + * are combined. + * + * @default false + */ + selected?: ChoiceProps['selected']; + /** + * The content of the choice. + */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$A]: HtmlElementTagNameProps; + [tagName$G]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$A]: IntrinsicElementProps; + [tagName$G]: IntrinsicElementProps; } } } -declare const tagName$z = 's-choice-list'; +declare const tagName$F = 's-choice-list'; +/** + * Groups one or more selectable choices. + * @publicDocs + */ interface ChoiceListJSXProps extends Pick { + /** + * The values of the selected choices. + * + * When `values` is set, update it from `onChange` or `onInput` to control the + * selection. When `values` is not set, the list manages its own state, starting + * from choices that have `selected` set. Selections from `values` and from + * `selected` choices are combined. + * + * Use a unique `value` for each choice. Choices that share a value can't be + * selected independently. + */ + values?: ChoiceListProps['values']; /** * Callback when the user changes a choice. Fires simultaneously with onChange. + * The event's `currentTarget.values` is always an array of selected choice + * values, even when `multiple` is `false`. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** * Callback when the user changes a choice. Fires simultaneously with onInput. + * The event's `currentTarget.values` is always an array of selected choice + * values; in single-selection mode, only the first entry is rendered as selected. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** - * The content of the choice list. Should be one or more choice elements. + * The content of the ChoiceList. Should be one or more Choice elements. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$z]: HtmlElementTagNameProps; + [tagName$F]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$z]: IntrinsicElementProps; + [tagName$F]: IntrinsicElementProps; } } } -declare const tagName$y = 's-clickable'; +declare const tagName$E = 's-clickable'; +/** + * Makes contained content interactive and clickable. + * @publicDocs + */ interface ClickableJSXProps extends Pick { /** * Callback when the element is activated. */ - onClick?: (event: CallbackEvent) => void; + onClick?: (event: CallbackEvent) => void; /** - * The content of the clickable. + * The content of the Clickable. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$y]: HtmlElementTagNameProps; + [tagName$E]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$y]: IntrinsicElementProps; + [tagName$E]: IntrinsicElementProps; } } } -declare const tagName$x = 's-date-field'; +declare const tagName$D = 's-date-field'; +/** + * Collects date input as text. + * @publicDocs + */ interface DateFieldJSXProps extends Pick< DateFieldProps, 'id' | 'label' | 'details' | 'value' | 'disabled' | 'error' | 'required' > { /** - * Callback when the user makes any changes in the field. + * The current value for the field, as a date in `YYYY-MM-DD` format (for + * example, `"2024-05-15"`). If omitted or empty, the field is empty. + * + * Values are interpreted in the device's local timezone. Out-of-range calendar + * dates (for example, `2024-02-30`) currently roll over to a valid date instead + * of being rejected. */ - onInput?: ((event: CallbackEvent) => void) | null; + value?: DateFieldProps['value']; /** - * Callback after editing completes (typically on blur). + * Callback when the user confirms a date in the picker. Fires together with + * `onChange` at selection time. */ - onChange?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback when the element loses focus. + * Callback when the user confirms a date in the picker. Fires together with + * `onInput` at selection time, not on blur. + */ + onChange?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; } -type ElementProps$b = Omit; +type ElementProps$8 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$x]: HtmlElementTagNameProps; + [tagName$D]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$x]: IntrinsicElementProps; + [tagName$D]: IntrinsicElementProps; } } } -declare const tagName$w = 's-date-picker'; +declare const tagName$C = 's-date-picker'; +/** + * Lets merchants select one or more dates from a calendar. + * @publicDocs + */ interface DatePickerJSXProps extends Pick { /** - * Callback when the user selects a date from the picker. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: DatePickerProps['id']; + /** + * The current selected value. + * + * The default `''` means no date is selected. + * + * The value must be a date in `YYYY-MM-DD` format. Values are interpreted in + * the device's local timezone. Values that can't be parsed as a date are + * treated as no selection; out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * + * @default "" + */ + value?: DatePickerProps['value']; + /** + * Callback when the user selects a date from the picker. Fires after `onChange`. */ - onInput?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback when the user selects a date from the picker that is different to the current value. + * Callback when the user selects a date from the picker that is different to the current value. Fires before `onInput`. */ - onChange?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the date picker is dismissed. */ - onBlur?: (event: CallbackEvent) => void | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the date picker is revealed. */ - onFocus?: (event: CallbackEvent) => void | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName$w]: HtmlElementTagNameProps; + [tagName$C]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$w]: IntrinsicElementProps; + [tagName$C]: IntrinsicElementProps; } } } -declare const tagName$v = 's-date-spinner'; +declare const tagName$B = 's-date-spinner'; +/** + * Lets merchants select a date using spinner controls. + * @publicDocs + */ interface DateSpinnerJSXProps extends Pick { /** - * Callback when the user makes a selection. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: DateSpinnerProps['id']; + /** + * The current selected value for the spinner, as a date in `YYYY-MM-DD` format. + * + * The default `''` means no date is selected. Values are interpreted in the + * device's local timezone. Out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * + * @default "" + */ + value?: DateSpinnerProps['value']; + /** + * Callback when the user makes a selection. Fires after `onChange`. */ - onInput?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback when the value changes. Only called when a different value is selected. + * Callback when the value changes. Only called when a different value is selected. Fires before `onInput`. */ - onChange?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the date spinner is dismissed. */ - onBlur?: (event: CallbackEvent) => void | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the date spinner is revealed. */ - onFocus?: (event: CallbackEvent) => void | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName$v]: HtmlElementTagNameProps; + [tagName$B]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$v]: IntrinsicElementProps; + [tagName$B]: IntrinsicElementProps; } } } -declare const tagName$u = 's-divider'; +declare const tagName$A = 's-divider'; +/** + * Displays a visual separator between content sections. + * @publicDocs + */ interface DividerJSXProps extends Pick {} declare global { interface HTMLElementTagNameMap { - [tagName$u]: HtmlElementTagNameProps; + [tagName$A]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$u]: IntrinsicElementProps; + [tagName$A]: IntrinsicElementProps; } } } -declare const tagName$t = 's-email-field'; +declare const tagName$z = 's-email-field'; +/** + * Collects and validates email address input. + * @publicDocs + */ interface EmailFieldJSXProps$1 extends Pick< EmailFieldProps, @@ -3964,62 +4095,73 @@ interface EmailFieldJSXProps$1 | 'maxLength' | 'details' > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: EmailFieldProps['value']; /** * Callback when the user makes any changes in the field. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; /** * Additional content to be displayed in the field. Commonly used to display clickable text. */ accessory?: ComponentChild; } -type ElementProps$a = Omit; +type ElementProps$7 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$t]: HtmlElementTagNameProps; + [tagName$z]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$t]: IntrinsicElementProps; + [tagName$z]: IntrinsicElementProps; } } } -declare const tagName$s = 's-heading'; +declare const tagName$y = 's-heading'; +/** + * Displays heading text for grouping and hierarchy. + * @publicDocs + */ interface HeadingJSXProps extends Pick { /** - * The content of the heading. + * The content of the Heading. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$s]: HtmlElementTagNameProps; + [tagName$y]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$s]: IntrinsicElementProps; + [tagName$y]: IntrinsicElementProps; } } } -declare const tagName$r = 's-icon'; +declare const tagName$x = 's-icon'; type SupportedIconNames = Extract< IconProps['type'], | 'alert-circle' @@ -4148,6 +4290,10 @@ type SupportedIconNames = Extract< | 'x' | 'x-circle' >; +/** + * Displays a predefined icon glyph. + * @publicDocs + */ interface IconJSXProps extends Pick { /** @@ -4159,19 +4305,23 @@ interface IconJSXProps } declare global { interface HTMLElementTagNameMap { - [tagName$r]: HtmlElementTagNameProps; + [tagName$x]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$r]: IntrinsicElementProps; + [tagName$x]: IntrinsicElementProps; } } } -declare const tagName$q = 's-image'; -interface ImageJSXProps extends Pick { +declare const tagName$w = 's-image'; +/** + * Displays an image with sizing and fit controls. + * @publicDocs + */ +interface ImageJSXProps$1 extends Pick { /** * The displayed inline width of the image. * @@ -4195,81 +4345,80 @@ interface ImageJSXProps extends Pick { * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src */ src?: ImageProps['src']; - /** - * Border radius for the image corners. - * - * [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 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) end-end` - * - 2 values: `(start-start & end-end) (start-end & end-start)` - * - * For example: - * - `base` means all corners have `base` radius - * - `base none` means start-start and end-end corners are `base`, start-end and end-start corners are `none` - * - `base none large` means start-start is `base`, start-end and end-start are `none`, end-end is `large` - * - `base none large small` means start-start is `base`, start-end is `none`, end-end is `large`, end-start is `small` - * - * @default 'none' - */ - borderRadius?: MaybeAllValuesShorthandProperty; } declare global { interface HTMLElementTagNameMap { - [tagName$q]: HtmlElementTagNameProps; + [tagName$w]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$q]: IntrinsicElementProps; + [tagName$w]: IntrinsicElementProps; } } } -declare const tagName$p = 's-modal'; +declare const tagName$v = 's-modal'; +/** + * The modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context. + * + * Modals block interaction with the underlying interface until the merchant resolves the modal content. + * + * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/feedback-and-status-indicators/modal#events). + * @publicDocs + */ interface ModalJSXProps extends Pick { /** - * Callback when the modal is hidden. + * A unique identifier for the element. + * + * Required to control visibility: a button or link with `commandFor` set to this `id` shows, hides, or toggles the modal. + */ + id?: string; + /** + * Callback when the modal starts to hide. Fired when a `commandFor` command requests the modal to close, before the closing transition completes. */ - onHide?: (event: CallbackEvent) => void | null; + onHide?: (event: CallbackEvent) => void | null; /** - * Callback when the modal is shown. + * Callback when the modal starts to show. Fired when a `commandFor` command requests the modal to open, before the opening transition completes. */ - onShow?: (event: CallbackEvent) => void | null; + onShow?: (event: CallbackEvent) => void | null; /** * The primary action button displayed in the modal. * * The tone of the button is used to define the tone of the modal. * - * If omitted, the modal will default to an 'info' tone, and show an 'OK' button, translated according to the user's locale. + * If omitted, the modal uses the default tone and shows a 'Close' button, translated according to the user's locale. */ primaryAction?: ComponentChild; /** - * The secondary action buttons displayed in the modal. + * The secondary action buttons displayed in the modal. At most two secondary actions are rendered. */ secondaryActions?: ComponentChild; /** - * The content of the modal. + * The content of the Modal. */ children?: ComponentChildren; } -type ElementProps$9 = Omit; +type ElementProps$6 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$p]: HtmlElementTagNameProps; + [tagName$v]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$p]: IntrinsicElementProps; + [tagName$v]: IntrinsicElementProps; } } } -declare const tagName$o = 's-number-field'; +declare const tagName$u = 's-number-field'; +/** + * Collects numeric input with optional stepper controls. + * @publicDocs + */ interface NumberFieldJSXProps extends Pick< NumberFieldProps, @@ -4285,6 +4434,32 @@ interface NumberFieldJSXProps | 'min' | 'controls' > { + /** + * The current value for the field, as a string. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + * In stepper mode the field is always populated: an empty or unparsable value is + * treated as `0`. + */ + value?: NumberFieldProps['value']; + /** + * The highest value accepted for the field. + * + * In text mode, the field clamps an out-of-bounds value to `max` when editing + * finishes and delivers the clamped value through `onInput`. + * + * @default Infinity + */ + max?: NumberFieldProps['max']; + /** + * The lowest value accepted for the field. + * + * In text mode, the field clamps an out-of-bounds value to `min` when editing + * finishes and delivers the clamped value through `onInput`. + * + * @default -Infinity + */ + min?: NumberFieldProps['min']; /** * Content to use as the field label. * @@ -4307,9 +4482,9 @@ interface NumberFieldJSXProps * If you want to present an error when this field is empty, you can do * so with the `error` property. * - * @default false - * * Required is not supported when using Stepper controls + * + * @default false */ required?: NumberFieldProps['required']; /** @@ -4343,46 +4518,55 @@ interface NumberFieldJSXProps /** * Sets the type of controls displayed for the field. * - * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property. Note that in POS + * - `stepper`: displays buttons to increase or decrease the value of the field in steps of 1. Note that in POS * adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically * validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls. * * - `none`: no controls are displayed and users must input the value manually. * - `auto`: the presence of the controls depends on the surface and context. + * + * @default 'auto' */ controls?: NumberFieldProps['controls']; /** - * Callback when the user makes any changes in the field. + * Callback when the user makes any changes in the field. In stepper mode, fires + * on every stepper button tap, together with `onChange`. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. In stepper mode, fires on every stepper + * button tap, together with `onInput`. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; } -type ElementProps$8 = Omit; +type ElementProps$5 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$o]: HtmlElementTagNameProps; + [tagName$u]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$o]: IntrinsicElementProps; + [tagName$u]: IntrinsicElementProps; } } } -declare const tagName$n = 's-page'; +declare const tagName$t = 's-page'; +/** + * Provides the top-level page layout for extension content. + * @publicDocs + */ interface PageJSXProps extends Pick { /** * The main page heading, displayed in the action bar at the top of the page. @@ -4403,25 +4587,29 @@ interface PageJSXProps extends Pick { */ aside?: ComponentChild; /** - * The content of the page. + * The content of the Page. */ children?: ComponentChildren; } -type ElementProps$7 = Omit; +type ElementProps$4 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$n]: HtmlElementTagNameProps; + [tagName$t]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$n]: IntrinsicElementProps; + [tagName$t]: IntrinsicElementProps; } } } -declare const tagName$m = 's-pos-block'; +declare const tagName$s = 's-pos-block'; +/** + * Displays content in a POS block container with optional heading. + * @publicDocs + */ interface PosBlockJSXProps extends Pick { /** * The secondary actions to perform, provided as button or link type elements. @@ -4432,37 +4620,42 @@ interface PosBlockJSXProps extends Pick { */ children?: ComponentChildren; } -type ElementProps$6 = Omit; +type ElementProps$3 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$m]: HtmlElementTagNameProps; + [tagName$s]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$m]: IntrinsicElementProps; + [tagName$s]: IntrinsicElementProps; } } } -declare const tagName$l = 's-qr-code'; +declare const tagName$r = 's-qr-code'; +/** @private */ interface QrCodeJSXProps extends Pick {} declare global { interface HTMLElementTagNameMap { - [tagName$l]: HtmlElementTagNameProps; + [tagName$r]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$l]: IntrinsicElementProps; + [tagName$r]: IntrinsicElementProps; } } } type PaddingKeyword$1 = SizeKeyword | 'none'; -declare const tagName$k = 's-scroll-box'; +declare const tagName$q = 's-scroll-box'; +/** + * Provides a scrollable container for overflowing content. + * @publicDocs + */ interface ScrollBoxJSXProps extends Pick { /** * Adjust the block size. @@ -4516,8 +4709,6 @@ interface ScrollBoxJSXProps extends Pick { * - `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`. * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; @@ -4574,57 +4765,73 @@ interface ScrollBoxJSXProps extends Pick { */ paddingInlineEnd?: PaddingKeyword$1 | ''; /** - * The content of the scroll box. + * The content of the ScrollBox. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$k]: HtmlElementTagNameProps; + [tagName$q]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$k]: IntrinsicElementProps; + [tagName$q]: IntrinsicElementProps; } } } -declare const tagName$j = 's-search-field'; +declare const tagName$p = 's-search-field'; +/** + * Collects search queries for filtering and lookup workflows. + * @publicDocs + */ interface SearchFieldJSXProps extends Pick { /** - * Callback when the user changes the value in the field. + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: SearchFieldProps['value']; + /** + * Callback when the user changes the value in the field. Also fires with an empty + * string when the user clears the field with the clear button; clearing the field + * doesn't fire `onChange`. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** * Callback when the field loses focus after the user changes the value in the field. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the field loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the field is focused. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName$j]: HtmlElementTagNameProps; + [tagName$p]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$j]: IntrinsicElementProps; + [tagName$p]: IntrinsicElementProps; } } } -declare const tagName$i = 's-section'; +declare const tagName$o = 's-section'; +/** + * Groups related content into a titled section. + * @publicDocs + */ interface SectionJSXProps extends Pick { /** * A title that describes the content of the section. @@ -4637,25 +4844,25 @@ interface SectionJSXProps extends Pick { */ secondaryActions?: ComponentChild; /** - * The content of the section. + * The content of the Section. */ children?: ComponentChildren; } -type ElementProps$5 = Omit; +type ElementProps$2 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$i]: HtmlElementTagNameProps; + [tagName$o]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$i]: IntrinsicElementProps; + [tagName$o]: IntrinsicElementProps; } } } -declare const tagName$h = 's-stack'; +declare const tagName$n = 's-stack'; type PaddingKeyword = SizeKeyword | 'none'; type PickedProps = Pick< StackProps, @@ -4674,6 +4881,10 @@ type PickedProps = Pick< | 'justifyContent' | 'rowGap' >; +/** + * Arranges children in a horizontal or vertical stack. + * @publicDocs + */ interface StackJSXProps extends PickedProps { /** * Adjust the padding of all edges. @@ -4691,8 +4902,6 @@ interface StackJSXProps extends PickedProps { * - `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`. * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; @@ -4794,16 +5003,16 @@ interface StackJSXProps extends PickedProps { */ minInlineSize?: SizeUnits; /** - * Aligns the stack's children along the cross axis. + * Aligns the Stack's children along the cross axis. */ alignItems?: AlignItemsKeyword; /** - * Aligns the stack along the cross axis. + * Aligns the Stack along the cross axis. */ alignContent?: AlignContentKeyword; /** * 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. + * A single value applies to both axes. A pair of values (for example, `large-100 large-500`) sets the block (row) and inline (column) axes respectively, matching the CSS `gap` shorthand order. * * @default 'none' */ @@ -4815,7 +5024,7 @@ interface StackJSXProps extends PickedProps { */ columnGap?: SpacingKeyword | ''; /** - * Sets how the children are placed within the stack. This uses logical properties. + * Sets how the children are placed within the Stack. This uses logical properties. * * @default 'block' * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' @@ -4829,7 +5038,7 @@ interface StackJSXProps extends PickedProps { */ inlineSize?: SizeUnitsOrAuto; /** - * Aligns the stack along the main axis. + * Aligns the Stack along the main axis. * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * * @default 'normal' @@ -4842,24 +5051,28 @@ interface StackJSXProps extends PickedProps { */ rowGap?: SpacingKeyword | ''; /** - * The content of the stack. + * The content of the Stack. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName$h]: HtmlElementTagNameProps; + [tagName$n]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$h]: IntrinsicElementProps; + [tagName$n]: IntrinsicElementProps; } } } -declare const tagName$g = 's-text'; +declare const tagName$m = 's-text'; +/** + * Renders styled textual content. + * @publicDocs + */ interface TextJSXProps extends Pick { /** * Modify the color to be more or less intense. @@ -4891,18 +5104,22 @@ interface TextJSXProps extends Pick { } declare global { interface HTMLElementTagNameMap { - [tagName$g]: HtmlElementTagNameProps; + [tagName$m]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$g]: IntrinsicElementProps; + [tagName$m]: IntrinsicElementProps; } } } -declare const tagName$f = 's-text-area'; +declare const tagName$l = 's-text-area'; +/** + * Collects multi-line text input from the merchant. + * @publicDocs + */ interface TextAreaJSXProps$1 extends Pick< TextAreaProps, @@ -4917,42 +5134,62 @@ interface TextAreaJSXProps$1 | 'maxLength' | 'rows' > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: TextAreaProps['value']; + /** + * A number of visible text lines. + * + * Sets the visible height of the field only; it doesn't limit how many lines of + * text can be entered. Values are clamped between 1 and 8. + * + * @default 2 + */ + rows?: TextAreaProps['rows']; /** * Callback when the user makes any changes in the field. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur. Fires only when the value + * changed since the field received focus. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; /** * Additional content to be displayed in the field. Commonly used to display clickable text. */ accessory?: ComponentChild; } -type ElementProps$4 = Omit; +type ElementProps$1 = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$f]: HtmlElementTagNameProps; + [tagName$l]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$f]: IntrinsicElementProps; + [tagName$l]: IntrinsicElementProps; } } } -declare const tagName$e = 's-text-field'; +declare const tagName$k = 's-text-field'; +/** + * Collects single-line text input. + * @publicDocs + */ interface TextFieldJSXProps extends Pick< TextFieldProps, @@ -4966,140 +5203,200 @@ interface TextFieldJSXProps | 'required' | 'maxLength' > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: TextFieldProps['value']; /** * Callback when the user makes any changes in the field. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; /** * Additional content to be displayed in the field. Commonly used to display clickable text. */ accessory?: ComponentChild; } -type ElementProps$3 = Omit; +type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName$e]: HtmlElementTagNameProps; + [tagName$k]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$e]: IntrinsicElementProps; + [tagName$k]: IntrinsicElementProps; } } } -declare const tagName$d = 's-tile'; +declare const tagName$j = 's-tile'; +/** + * Displays tappable content in a compact tile layout. + * @publicDocs + */ interface TileJSXProps extends Pick< TileProps, 'heading' | 'id' | 'itemCount' | 'tone' | 'subheading' > { /** - * Disables the tile meaning it cannot be clicked or receive focus. + * Disables the Tile meaning it cannot be clicked or receive focus. * * @default false */ disabled?: TileProps['disabled']; /** - * Callback when the tile is activated. + * Callback when the Tile is activated. */ - onClick?: (event: CallbackEvent) => void; + onClick?: (event: CallbackEvent) => void; } declare global { interface HTMLElementTagNameMap { - [tagName$d]: HtmlElementTagNameProps; + [tagName$j]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$d]: IntrinsicElementProps; + [tagName$j]: IntrinsicElementProps; } } } -declare const tagName$c = 's-time-field'; +declare const tagName$i = 's-time-field'; +/** + * Collects a time value. + * @publicDocs + */ interface TimeFieldJSXProps extends Pick< TimeFieldProps, 'id' | 'label' | 'disabled' | 'value' | 'error' | 'details' | 'required' > { /** - * Callback when the user makes any changes in the field. + * The current value for the field, as a 24-hour time in `HH:mm:ss` format with + * leading zeros (for example, `"09:05:00"`). If omitted or empty, the field is + * empty. + * + * Seconds aren't captured: emitted values always end in `:00`, and seconds in a + * provided value are ignored. Values are interpreted in the device's local + * timezone. The field displays times in 12-hour AM/PM format. */ - onInput?: ((event: CallbackEvent) => void) | null; + value?: TimeFieldProps['value']; /** - * Callback after editing completes (typically on blur). + * Callback when the user confirms a time in the picker. Fires together with + * `onChange` at selection time. */ - onChange?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback when the element loses focus. + * Callback when the user confirms a time in the picker. Fires together with + * `onInput` at selection time, not on blur. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. + */ + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName$c]: HtmlElementTagNameProps; + [tagName$i]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$c]: IntrinsicElementProps; + [tagName$i]: IntrinsicElementProps; } } } -declare const tagName$b = 's-time-picker'; +declare const tagName$h = 's-time-picker'; +/** + * Lets merchants select a time from a picker. + * @publicDocs + */ interface TimePickerJSXProps extends Pick { /** - * Callback when the user selects a time from the picker. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. */ - onInput?: (event: CallbackEvent) => void | null; + id?: TimePickerProps['id']; /** - * Callback when the user selects a time from the picker that is different to the current value. + * The current selected value. + * + * The default `''` means no time is selected. + * + * The value must be a 24-hour time in `HH:mm:ss` format, with leading zeros + * (for example, `"09:05:00"`). Seconds aren't captured: emitted values always + * end in `:00`, and seconds in a provided value are ignored. Values are + * interpreted in the device's local timezone. + * + * @default '' */ - onChange?: (event: CallbackEvent) => void | null; + value?: TimePickerProps['value']; /** - * Callback when the time picker is dismissed. + * Callback when the user selects a time from the picker. Fires after `onChange`. */ - onBlur?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback when the time picker is revealed. + * Callback when the user selects a time from the picker that is different to the current value. Fires before `onInput`. */ - onFocus?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the time picker is dismissed. + */ + onBlur?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the time picker is revealed. + */ + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName$b]: HtmlElementTagNameProps; + [tagName$h]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName$b]: IntrinsicElementProps; + [tagName$h]: IntrinsicElementProps; } } } -declare const tagName$a = 's-link'; +declare const tagName$g = 's-link'; +/** + * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content. + * + * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/actions/button) instead. + * @publicDocs + */ interface LinkJSXProps extends Pick< LinkProps, @@ -5108,29 +5405,20 @@ interface LinkJSXProps /** * Called when the link is activated. */ - onClick?: (event: CallbackEvent) => void; + onClick?: (event: CallbackEvent) => void; /** - * The link content. + * The Link content. */ children?: ComponentChildren; } -declare global { - interface HTMLElementTagNameMap { - [tagName$a]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$a]: IntrinsicElementProps; - } - } -} -declare const tagName$9 = 's-empty-state'; +/** + * Displays an empty-state message with optional actions and supporting graphics. + * @publicDocs + */ interface EmptyStateJSXProps extends Pick { /** - * The subheading of the empty state. + * The subheading of the EmptyState. */ subheading?: string; /** @@ -5142,28 +5430,25 @@ interface EmptyStateJSXProps extends Pick { */ secondaryActions?: ComponentChild; /** - * The graphic to display in the empty state. The only supported components is Icon, with a type of `alert-circle`, `search`, `info`, or `circle-info`. + * The graphic to display in the EmptyState. The only supported component is `Icon`, with a type of `alert-circle`, `search`, or `info`. */ graphic?: ComponentChild; } -type ElementProps$2 = Omit< - EmptyStateJSXProps, - 'primaryAction' | 'secondaryActions' | 'graphic' ->; -declare global { - interface HTMLElementTagNameMap { - [tagName$9]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$9]: IntrinsicElementProps; - } - } -} -declare const tagName$8 = 's-embed'; +/** + * The embed component displays a preview of printable content from a specified source URL. Use it to show merchants what will be printed before triggering the actual print operation. + * + * Embed works in conjunction with the Print API to provide complete print functionality from preview to execution. + * + * The supported document types are the content types accepted by the `type` property: + * + * - **HTML documents** (`text/html`) - Receipts, invoices, and formatted reports with CSS styling and embedded images. + * - **Text files** (`text/plain`) - Plain text content such as simple receipts and data exports. + * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. PDF handling varies by platform; on Android, PDF content is downloaded and opened in an external viewer. + * + * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). + * @publicDocs + */ interface EmbedJSXProps extends Pick< EmbedProps, @@ -5214,36 +5499,19 @@ interface EmbedJSXProps */ maxInlineSize?: SizeUnitsOrNone; } -declare global { - interface HTMLElementTagNameMap { - [tagName$8]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$8]: IntrinsicElementProps; - } - } -} -declare const tagName$7 = 's-spinner'; +/** + * Displays a loading indicator while content or actions are in progress. + * @publicDocs + */ interface SpinnerJSXProps extends Pick {} -declare global { - interface HTMLElementTagNameMap { - [tagName$7]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$7]: IntrinsicElementProps; - } - } -} -declare const tagName$6 = 's-switch'; +declare const tagName$f = 's-switch'; +/** + * Allows merchants to toggle a setting on or off. + * @publicDocs + */ interface SwitchJSXProps extends Pick< SwitchProps, @@ -5257,94 +5525,104 @@ interface SwitchJSXProps | 'error' | 'labelAccessibilityVisibility' > { - onInput?: ((event: CallbackEvent) => void) | null; - onChange?: ((event: CallbackEvent) => void) | null; -} -declare global { - interface HTMLElementTagNameMap { - [tagName$6]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$6]: IntrinsicElementProps; - } - } + /** + * A string value attached to the element. + * + * Use `checked` for the switch state. A string `value` stays attached to the + * element and can be read back in event callbacks; it doesn't affect the switch + * state and isn't submitted with any form. + */ + value?: SwitchProps['value']; + /** + * Whether the switch is on. + * + * When `checked` is set, update it from `onChange` or `onInput` to keep the + * switch controlled. When `checked` isn't set, the switch manages its own + * state, starting from `defaultChecked`. + * + * @default false + */ + checked?: SwitchProps['checked']; + /** + * Whether the switch is on when it first renders. + * + * Applies only to the initial render; later changes to `defaultChecked` are + * ignored. Use `checked` to control the state after the first render. + * + * @default false + */ + defaultChecked?: SwitchProps['defaultChecked']; + /** + * Callback when the user toggles the switch. Fires together with `onChange`, + * after it. Read the new state from `event.currentTarget.checked`. + */ + onInput?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the user toggles the switch. Fires together with `onInput`; + * `onChange` fires first. Read the new state from `event.currentTarget.checked`. + */ + onChange?: ((event: CallbackEvent) => void) | null; } -declare const tagName$5 = 's-tabs'; +declare const tagName$e = 's-tabs'; +/** + * Groups related content into selectable tabbed views. + * @publicDocs + */ interface TabsJSXProps extends Pick { + /** + * The value of the selected tab. + * + * This should match the `id` prop of one of the TabPanel components. + * When neither `value` nor `defaultValue` is provided, the first rendered tab panel is selected. + */ + value?: string; + /** + * The default value of the selected tab. + * + * This should match the `id` prop of one of the TabPanel components. + * Sets the initial selected tab in uncontrolled usage. Setting `value` afterwards overrides it. + */ + defaultValue?: string; children?: ComponentChildren; - onChange?: ((event: CallbackEvent) => void) | null; -} -declare global { - interface HTMLElementTagNameMap { - [tagName$5]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$5]: IntrinsicElementProps; - } - } + /** + * Callback fired when the selected tab changes. + * + * Fires on every tab selection, including when the current tab is selected again. + */ + onChange?: ((event: CallbackEvent) => void) | null; } -declare const tagName$4 = 's-tab-list'; -/** @publicDocs */ +/** + * Presents the list of selectable tabs within a tabs component. Accepts only tab components as children. + * @publicDocs + */ interface TabListJSXProps extends Pick { children?: ComponentChildren; } -declare global { - interface HTMLElementTagNameMap { - [tagName$4]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$4]: IntrinsicElementProps; - } - } -} -declare const tagName$3 = 's-tab'; +/** + * Represents an individual tab inside a tabs component. + * @publicDocs + */ interface TabJSXProps extends Pick { children?: StringChildren; } -declare global { - interface HTMLElementTagNameMap { - [tagName$3]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$3]: IntrinsicElementProps; - } - } -} -declare const tagName$2 = 's-tab-panel'; +/** + * Represents content associated with a selected tab. + * @publicDocs + */ interface TabPanelJSXProps extends Pick { children?: ComponentChildren; } -declare global { - interface HTMLElementTagNameMap { - [tagName$2]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$2]: IntrinsicElementProps; - } - } -} -declare const tagName$1 = 's-text-area'; +declare const tagName$d = 's-text-area'; +/** + * Collects multi-line text input from the merchant. + * @publicDocs + */ interface TextAreaJSXProps extends Pick< TextAreaProps, @@ -5359,38 +5637,45 @@ interface TextAreaJSXProps | 'maxLength' | 'rows' > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: TextAreaProps['value']; + /** + * A number of visible text lines. + * + * Sets the visible height of the field only; it doesn't limit how many lines of + * text can be entered. Values are clamped between 1 and 8. + * + * @default 2 + */ + rows?: TextAreaProps['rows']; /** * Callback when the user makes any changes in the field. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur. Fires only when the value + * changed since the field received focus. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; -} -type ElementProps$1 = Omit; -declare global { - interface HTMLElementTagNameMap { - [tagName$1]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName$1]: IntrinsicElementProps; - } - } + onFocus?: ((event: CallbackEvent) => void) | null; } -declare const tagName = 's-email-field'; +declare const tagName$c = 's-email-field'; +/** + * Collects and validates email address input. + * @publicDocs + */ interface EmailFieldJSXProps extends Pick< EmailFieldProps, @@ -5404,49 +5689,265 @@ interface EmailFieldJSXProps | 'maxLength' | 'details' > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: EmailFieldProps['value']; /** * Callback when the user makes any changes in the field. */ - onInput?: ((event: CallbackEvent) => void) | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Callback after editing completes (typically on blur). + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. */ - onChange?: ((event: CallbackEvent) => void) | null; + onChange?: ((event: CallbackEvent) => void) | null; /** * Callback when the element loses focus. */ - onBlur?: ((event: CallbackEvent) => void) | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** * Callback when the element receives focus. */ - onFocus?: ((event: CallbackEvent) => void) | null; -} -type ElementProps = EmailFieldJSXProps; -declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } -} -declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } - } + onFocus?: ((event: CallbackEvent) => void) | null; } -export type { - BadgeJSXProps, - BannerJSXProps, - BoxJSXProps, - ButtonJSXProps, - ChoiceJSXProps, - ChoiceListJSXProps, - ClickableJSXProps, - DateFieldJSXProps, - DatePickerJSXProps, - DateSpinnerJSXProps, - DividerJSXProps, +/** + * Displays an image with sizing and fit controls. + * @publicDocs + */ +interface ImageJSXProps extends Pick { + /** + * The displayed inline width of the image. + * + * - `fill`: the image will take up 100% of the available inline size. + * - `auto`: the image is displayed in a square (1:1 aspect ratio) container at the full available + * inline size. The POS translator doesn't render the image at its natural size. + * + * **Mobile surfaces:** Always wrap your image in a box with a set width and height. + * ScrollViews on mobile have a dynamic height, which can cause images to appear + * inconsistently without defined dimensions. + * + * @default 'fill' + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width + */ + inlineSize?: ImageProps['inlineSize']; + /** + * The image source, which should be a remote URL. + * + * When no `src` is provided or the image fails to load, a placeholder is rendered. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src + */ + src?: ImageProps['src']; + /** + * Border radius for the image corners. + * + * [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 CSS, it uses flow-relative values and the order is: + * + * - 4 values: `start-start inline-end end-end inline-start` + * - 3 values: `start-start inline end-end` + * - 2 values: `block inline` + * + * For example: + * - `base` means all corners have `base` radius + * - `base none` means start-start and end-end corners are `base`, inline-end and inline-start corners are `none` + * - `base none large` means start-start is `base`, inline-end and inline-start are `none`, end-end is `large` + * - `base none large small` means start-start is `base`, inline-end is `none`, end-end is `large`, inline-start is `small` + * + * Supports size keywords from the design system scale: + * - Size scale: `small-500`, `small-400`, `small-300`, `small-200`, `small-100`, `small`, `base`, `large`, `large-100`, `large-200`, `large-300`, `large-400`, `large-500` + * - Special values: `max`, `none` + * + * @default 'none' + */ + borderRadius?: MaybeAllValuesShorthandProperty; +} + +declare const tagName$b = 's-image'; +declare global { + interface HTMLElementTagNameMap { + [tagName$b]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$b]: IntrinsicElementProps; + } + } +} + +declare const tagName$a = 's-link'; +declare global { + interface HTMLElementTagNameMap { + [tagName$a]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$a]: IntrinsicElementProps; + } + } +} + +declare const tagName$9 = 's-empty-state'; +declare global { + interface HTMLElementTagNameMap { + [tagName$9]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$9]: IntrinsicElementProps; + } + } +} + +declare const tagName$8 = 's-embed'; +declare global { + interface HTMLElementTagNameMap { + [tagName$8]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$8]: IntrinsicElementProps; + } + } +} + +declare const tagName$7 = 's-spinner'; +declare global { + interface HTMLElementTagNameMap { + [tagName$7]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$7]: IntrinsicElementProps; + } + } +} + +declare const tagName$6 = 's-switch'; +declare global { + interface HTMLElementTagNameMap { + [tagName$6]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$6]: IntrinsicElementProps; + } + } +} + +declare const tagName$5 = 's-tabs'; +declare global { + interface HTMLElementTagNameMap { + [tagName$5]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$5]: IntrinsicElementProps; + } + } +} + +declare const tagName$4 = 's-tab-list'; +declare global { + interface HTMLElementTagNameMap { + [tagName$4]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$4]: IntrinsicElementProps; + } + } +} + +declare const tagName$3 = 's-tab'; +declare global { + interface HTMLElementTagNameMap { + [tagName$3]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$3]: IntrinsicElementProps; + } + } +} + +declare const tagName$2 = 's-tab-panel'; +declare global { + interface HTMLElementTagNameMap { + [tagName$2]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$2]: IntrinsicElementProps; + } + } +} + +declare const tagName$1 = 's-text-area'; +declare global { + interface HTMLElementTagNameMap { + [tagName$1]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName$1]: IntrinsicElementProps; + } + } +} + +declare const tagName = 's-email-field'; +declare global { + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } +} +declare module 'preact' { + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; + } + } +} + +export type { + BadgeJSXProps, + BannerJSXProps, + BoxJSXProps, + ButtonJSXProps, + ChoiceJSXProps, + ChoiceListJSXProps, + ClickableJSXProps, + DateFieldJSXProps, + DatePickerJSXProps, + DateSpinnerJSXProps, + DividerJSXProps, EmailFieldJSXProps, EmbedJSXProps, EmptyStateJSXProps, @@ -5478,30 +5979,19 @@ export type { }; /** - * The link component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The button component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface LinkEvents { - /** Called when the link is activated. */ - click?: (event: CallbackEvent) => void; +interface ButtonEvents { + /** Called when the button is activated. */ + click?: (event: CallbackEvent) => void; } /** - * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content. - * - * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/polaris-web-components/actions/button) instead. + * Triggers actions when selected by the merchant. * @publicDocs */ -interface Link { - /** A unique identifier for the element. */ - id?: string; - /** - * 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 ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor - */ - commandFor?: string; +interface Button { /** * Sets the action the `commandFor` should take when this clickable is activated. * @@ -5511,353 +6001,686 @@ interface Link { * - `--show`: shows the target component. * - `--hide`: hides the target component. * - `--toggle`: toggles the target component. - * - `--copy`: copies the target ClipboardItem. * @default '--auto' * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ - command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy'; + command?: '--auto' | '--show' | '--hide' | '--toggle'; + /** + * Sets the tone of the Button, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: 'auto' | 'neutral' | 'caution' | 'warning' | 'critical'; /** - * A label that describes the purpose or contents of the link. It will be read to users using assistive technologies such as screen readers. + * Changes the visual appearance of the Button. + * @default 'auto' + */ + variant?: 'auto' | 'primary' | 'secondary'; + /** A unique identifier for the element. */ + id?: string; + /** + * Disables the Button meaning it cannot be clicked or receive focus. + * @default false + */ + disabled?: boolean; + /** + * ID of a component that should respond to activations (e.g. clicks) on this component. * - * Use this when using only an icon or the content of the link is not enough context - * for users using assistive technologies. + * See `command` for how to control the behavior of the target. + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor */ - accessibilityLabel?: string; + commandFor?: string; + /** + * Replaces content with a loading indicator while a background action is being performed. + * + * This also disables the Button. + * @default false + */ + loading?: boolean; } /** - * The empty state component supports slots for adding graphics and actions. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * Renders styled textual content. * @publicDocs */ -interface EmptyStateSlots { - /** The primary action to perform, provided as a button or link type element. */ - 'primary-action'?: HTMLElement; - /** The secondary actions to perform, provided as button or link type elements. */ - 'secondary-actions'?: HTMLElement; - /** The graphic to display in the empty state. The only supported components is Icon, with a type of `alert-circle`, `search`, `info`, or `circle-info`. */ - graphic?: HTMLElement; +interface Text { + /** + * Modify the color to be more or less intense. + * @default 'base' + */ + color?: ColorKeyword; + /** + * Provide semantic meaning and default styling to the text. + * + * Other presentation properties on Text override the default styling. + * @default 'generic' + */ + type?: 'strong' | 'small' | 'generic'; + /** + * Sets the tone of the component, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: + | 'auto' + | 'neutral' + | 'info' + | 'success' + | 'caution' + | 'warning' + | 'critical'; + /** A unique identifier for the element. */ + id?: string; } /** - * Displays an empty-state message with optional actions and supporting graphics. + * Provides a scrollable container for overflowing content. * @publicDocs */ -interface EmptyState { - /** The subheading of the empty state. */ +interface ScrollBox { + /** + * Adjust the block size. + * @default 'auto' + */ + blockSize?: SizeUnitsOrAuto; + /** + * Adjust the inline size. + * @default 'auto' + */ + inlineSize?: SizeUnitsOrAuto; + /** + * Adjust the maximum block size. + * @default 'none' + */ + maxBlockSize?: SizeUnitsOrNone; + /** + * Adjust the maximum inline size. + * @default 'none' + */ + maxInlineSize?: SizeUnitsOrNone; + /** + * Adjust the minimum block size. + * @default '0' + */ + minBlockSize?: SizeUnits; + /** + * Adjust the minimum inline size. + * @default '0' + */ + minInlineSize?: SizeUnits; + /** + * 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`. + * @default 'none' + */ + padding?: MaybeAllValuesShorthandProperty; + /** + * 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 + */ + paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + /** + * Adjust the block-start padding. + * + * This overrides the block-start value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockStart?: '' | PaddingKeyword; + /** + * Adjust the block-end padding. + * + * This overrides the block-end value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockEnd?: '' | PaddingKeyword; + /** + * 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 + */ + paddingInline?: '' | MaybeTwoValuesShorthandProperty; + /** + * Adjust the inline-start padding. + * + * This overrides the inline-start value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineStart?: '' | PaddingKeyword; + /** + * Adjust the inline-end padding. + * + * This overrides the inline-end value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineEnd?: '' | PaddingKeyword; + /** A unique identifier for the element. */ + id?: string; +} + +/** + * The tile component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * @publicDocs + */ +interface TileEvents { + /** Callback when the Tile is activated. */ + click?: (event: CallbackEvent) => void; +} + +/** + * Displays tappable content in a compact tile layout. + * @publicDocs + */ +interface Tile { + /** + * Disables the Tile meaning it cannot be clicked or receive focus. + * @default false + */ + disabled?: boolean; + /** + * A title that describes the content of the Tile. + * @default '' + */ + heading?: string; + /** A unique identifier for the element. */ + id?: string; + /** + * A numeric indicator rendered within the Tile (for example, a count or a step number). + * + * - When provided, the indicator is displayed inside the tile. + * - Intended for small integers. It may clamp, truncate, or abbreviate larger values. + */ + itemCount?: number; + /** + * Sets the tone of the Tile, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: ExtractStrict; + /** + * Supporting text displayed below the heading. + * @default '' + */ subheading?: string; - /** The heading of the empty state. */ +} + +/** + * The banner component supports slots for additional content placement within the banner. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * @publicDocs + */ +interface BannerSlots { + /** + * The primary action for the banner, provided as a button element in the `primary-action` slot. + * + * The POS renderer displays the action only when the slotted button has both text content and an + * `onClick` handler; otherwise the action is dropped. + */ + 'primary-action'?: HTMLElement; +} + +/** + * Shows prominent status and messaging content with optional actions. + * @publicDocs + */ +interface Banner { + /** + * Determines whether the banner is hidden. + * @default false + */ + hidden?: boolean; + /** + * Sets the tone of the Banner, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: 'auto' | 'info' | 'success' | 'warning' | 'critical'; + /** + * The title of the banner. + * @default '' + */ heading?: string; + /** A unique identifier for the element. */ + id?: string; } /** - * The embed component displays a preview of printable content from a specified source URL. Use it to show users what will be printed before triggering the actual print operation. - * - * Embed works in conjunction with the Print API to provide complete print functionality from preview to execution. - * - * Supported document types: - * - * - **HTML documents** (`.html`, `.htm`) - Best printing experience with full CSS styling, embedded images, and complex layouts. Use for receipts, invoices, and formatted reports. - * - * - **Text files** (`.txt`, `.csv`) - Plain text with basic content and tabular data support. Use for simple receipts and data exports. - * - * - **PDF files** (`.pdf`) - Behavior varies by platform: prints directly on iOS/desktop, but downloads to external viewer on Android. Use for complex documents and compliance requirements. - * - * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). + * Provides a generic layout container with sizing and spacing controls. * @publicDocs */ -interface Embed { +interface Box { + /** A unique identifier for the element. */ + id?: string; + /** + * Adjust the block size. + * @default 'auto' + */ + blockSize?: SizeUnitsOrAuto; + /** + * Adjust the inline size. + * @default 'auto' + */ + inlineSize?: SizeUnitsOrAuto; + /** + * Adjust the maximum block size. + * @default 'none' + */ + maxBlockSize?: SizeUnitsOrNone; + /** + * Adjust the maximum inline size. + * @default 'none' + */ + maxInlineSize?: SizeUnitsOrNone; + /** + * Adjust the minimum block size. + * @default '0' + */ + minBlockSize?: SizeUnits; + /** + * Adjust the minimum inline size. + * @default '0' + */ + minInlineSize?: SizeUnits; + /** + * 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`. + * @default 'none' + */ + padding?: MaybeAllValuesShorthandProperty; + /** + * 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 + */ + paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + /** + * Adjust the block-start padding. + * + * This overrides the block-start value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockStart?: '' | PaddingKeyword; + /** + * Adjust the block-end padding. + * + * This overrides the block-end value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockEnd?: '' | PaddingKeyword; + /** + * 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 + */ + paddingInline?: '' | MaybeTwoValuesShorthandProperty; + /** + * Adjust the inline-start padding. + * + * This overrides the inline-start value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineStart?: '' | PaddingKeyword; + /** + * Adjust the inline-end padding. + * + * This overrides the inline-end value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineEnd?: '' | PaddingKeyword; +} + +/** + * Displays a predefined icon glyph. + * @publicDocs + */ +interface Icon { + /** + * The type of icon to display. + * @default '' + */ + type?: SupportedIconNames; + /** A unique identifier for the element. */ + id?: string; + /** + * Sets the tone of the icon, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: ToneKeyword; + /** + * Modify the color to be more or less intense. + * @default 'base' + */ + color?: ColorKeyword; + /** + * Adjusts the size of the icon. + * @default 'base' + */ + size?: SizeKeyword; +} + +/** + * Arranges children in a horizontal or vertical stack. + * @publicDocs + */ +interface Stack { + /** + * 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`. + * @default 'none' + */ + padding?: MaybeAllValuesShorthandProperty; + /** + * 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 + */ + paddingBlock?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; + /** + * Adjust the block-start padding. + * + * This overrides the block-start value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockStart?: '' | PaddingKeyword; + /** + * Adjust the block-end padding. + * + * This overrides the block-end value of `paddingBlock`. + * @default '' - meaning no override + */ + paddingBlockEnd?: '' | PaddingKeyword; + /** + * 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 + */ + paddingInline?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; + /** + * Adjust the inline-start padding. + * + * This overrides the inline-start value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineStart?: '' | PaddingKeyword; + /** + * Adjust the inline-end padding. + * + * This overrides the inline-end value of `paddingInline`. + * @default '' - meaning no override + */ + paddingInlineEnd?: '' | PaddingKeyword; /** * Adjust the block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * @see ://developer.mozilla.org/en-US/docs/Web/CSS/block-size * @default 'auto' */ blockSize?: SizeUnitsOrAuto; - /** - * Adjust the minimum block size. - * @default '0' - */ - minBlockSize?: SizeUnits; /** * Adjust the maximum block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size * @default 'none' */ maxBlockSize?: SizeUnitsOrNone; - /** - * Adjust the inline size. - * @default 'auto' - */ - inlineSize?: SizeUnitsOrAuto; - /** - * Adjust the minimum inline size. - * @default '0' - */ - minInlineSize?: SizeUnits; /** * Adjust the maximum inline size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size * @default 'none' */ maxInlineSize?: SizeUnitsOrNone; /** - * The content type of the file to display. - * @default 'text/html' - */ - type?: 'text/html' | 'text/plain' | 'application/pdf'; - /** - * The source of the file to preview. - * - * The value must be either: - * - A relative path that will be appended to your app's `application_url`. - * - A full URL to your app's backend that will be used to return the file. - * - * Supported file types: - * - HTML files - * - Text files - * - PDF files - * @implementation If this value is omitted, the component should render an empty state or nothing. - */ - src?: string; - /** - * A label that describes the purpose or contents of the embed. It will be read to users - * using assistive technologies such as screen readers. - * @implementation for web-based implementations, this should map to the [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute - */ - accessibilityLabel?: string; -} - -/** - * Displays a loading indicator while content or actions are in progress. - * @publicDocs - */ -interface Spinner { - /** A unique identifier for the element. */ - id?: string; - /** - * A label that describes the purpose of the progress. When set, - * it will be announced to users using assistive technologies and will - * provide them with more context. Providing an `accessibilityLabel` is - * recommended if there is no accompanying text describing that something - * is loading. + * Adjust the minimum block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size + * @default '0' */ - accessibilityLabel?: string; -} - -/** - * The switch component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface SwitchEvents { - input?: (event: CallbackEvent) => void; - change?: (event: CallbackEvent) => void; -} - -/** - * Allows merchants to toggle a setting on or off. - * @publicDocs - */ -interface Switch { - /** The value used in form data when the control is checked. */ - value?: string; + minBlockSize?: SizeUnits; /** - * Whether the control is active by default. - * @implementation `defaultChecked` reflects to the `checked` attribute. - * @default false + * Adjust the minimum inline size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size + * @default '0' */ - defaultChecked?: boolean; + minInlineSize?: SizeUnits; + /** Aligns the Stack's children along the cross axis. */ + alignItems?: AlignItemsKeyword; + /** Aligns the Stack along the cross axis. */ + alignContent?: AlignContentKeyword; /** - * Disables the control, disallowing any interaction. - * @default false + * Adjust spacing between elements. + * A single value applies to both axes. A pair of values (for example, `large-100 large-500`) sets the block (row) and inline (column) axes respectively, matching the CSS `gap` shorthand order. + * @default 'none' */ - disabled?: boolean; + gap?: MaybeTwoValuesShorthandProperty; /** - * 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. + * Adjust spacing between elements in the inline axis. This overrides the column value of gap. + * @default '' - meaning no override */ - accessibilityLabel?: string; + columnGap?: '' | SpacingKeyword; /** - * Whether the control is active. - * @default false + * Sets how the children are placed within the Stack. This uses logical properties. + * @default 'block' + * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' */ - checked?: boolean; - /** Visual content to use as the control label. */ - label?: string; + direction?: 'block' | 'inline'; /** - * 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. + * Adjust the inline size. + * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size + * @default 'auto' */ - details?: string; + inlineSize?: SizeUnitsOrAuto; /** - * Indicate an error to the user. The field will be given a specific stylistic treatment - * to communicate problems that have to be resolved immediately. + * Aligns the Stack along the main axis. + * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content + * @default 'normal' */ - error?: string; + justifyContent?: JustifyContentKeyword; /** - * 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' + * Adjust spacing between elements in the block axis. This overrides the row value of gap. + * @default '' - meaning no override */ - labelAccessibilityVisibility?: ExtractStrict< - 'visible' | 'hidden' | 'exclusive', - 'visible' | 'exclusive' - >; + rowGap?: '' | SpacingKeyword; + /** A unique identifier for the element. */ + id?: string; } /** - * The tabs component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * Displays compact status text with optional semantic tone. * @publicDocs */ -interface TabsEvents { - change?: (event: CallbackEvent) => void; +interface Badge { + /** + * Sets the tone of the Badge, based on the intention of the information being conveyed. + * @default 'auto' + */ + tone?: + | 'auto' + | 'neutral' + | 'info' + | 'success' + | 'caution' + | 'warning' + | 'critical'; + /** A unique identifier for the element. */ + id?: string; } /** - * Groups related content into selectable tabbed views. + * The choice list component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface Tabs { +interface ChoiceListEvents { /** - * The value of the selected tab. - * - * This should match the `id` prop of one of the tab panel components. - * If not provided, the first tab will be selected by default. + * Callback when the user changes a choice. Fires simultaneously with onChange. + * The event's `currentTarget.values` is always an array of selected choice + * values, even when `multiple` is `false`. */ - value?: string; + input?: (event: CallbackEvent) => void; /** - * The default value of the selected tab. - * - * This should match the `id` prop of one of the tab panel components. - * If not provided, the first tab will be selected by default. - * - * Reflects to the `value` attribute + * Callback when the user changes a choice. Fires simultaneously with onInput. + * The event's `currentTarget.values` is always an array of selected choice + * values; in single-selection mode, only the first entry is rendered as selected. */ - defaultValue?: string; - /** Disables all tabs and prevents user interaction. */ - disabled?: boolean; + change?: (event: CallbackEvent) => void; } /** - * Represents an individual tab inside a tabs component. + * Groups one or more selectable choices. * @publicDocs */ -interface Tab { - /** Corresponds to the `id` property of the tab panel component that will be displayed when selected */ - controls?: string; +interface ChoiceList { /** - * Disables the control, disallowing any interaction. - * @default false + * The values of the selected choices. + * + * When `values` is set, update it from `onChange` or `onInput` to control the + * selection. When `values` is not set, the list manages its own state, starting + * from choices that have `selected` set. Selections from `values` and from + * `selected` choices are combined. + * + * Use a unique `value` for each choice. Choices that share a value can't be + * selected independently. */ - disabled?: boolean; -} - -/** - * Represents content associated with a selected tab. - * @publicDocs - */ -interface TabPanel { + values?: string[]; + /** A unique identifier for the element. */ + id?: string; /** - * The id of the tab panel used for identification in the tabs component. - * Must match the `controls` prop of the corresponding tab component. + * Whether multiple choices can be selected. + * @default false */ - id?: string; -} - -/** - * The text area component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface TextAreaEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + multiple?: boolean; } /** - * Collects multi-line text input from the merchant. + * Represents a selectable option within a choice list. * @publicDocs */ -interface TextArea { - /** A unique identifier for the element. */ - id?: string; - /** Content to use as the field label. */ - label?: string; +interface Choice { /** - * 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. + * The value that identifies this choice in the `ChoiceList` `values` prop and + * in selection events. * - * This will also be exposed to screen reader users. + * A choice needs a `value` to be selectable. Use a unique value for each choice + * in the list; choices that share a value can't be selected independently. */ - details?: string; - /** The current value for the field. If omitted, the field will be empty. */ value?: string; - /** A short hint that describes the expected value of the field. */ - placeholder?: string; - /** - * Disables the field, disallowing any interaction. - * @default false - */ - disabled?: boolean; - /** - * 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; /** - * 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. + * Whether the choice is selected. + * + * Selection can also be set with the `values` prop on the `ChoiceList`; the two + * are combined. * @default false */ - required?: boolean; - /** - * Specifies the maximum number of characters allowed. - * @default Infinity - */ - maxLength?: number; + selected?: boolean; + /** A unique identifier for the element. */ + id?: string; /** - * A number of visible text lines. - * @default 2 + * Disables the control, disallowing any interaction. + * @default false */ - rows?: number; + disabled?: boolean; } /** - * The email field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The date field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface EmailFieldEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; +interface DateFieldEvents { + /** + * Callback when the user confirms a date in the picker. Fires together with + * `onChange` at selection time. + */ + input?: (event: CallbackEvent) => void; + /** + * Callback when the user confirms a date in the picker. Fires together with + * `onInput` at selection time, not on blur. + */ + change?: (event: CallbackEvent) => void; + /** + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. + */ + blur?: (event: CallbackEvent) => void; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: (event: CallbackEvent) => void; } /** - * Collects and validates email address input. + * Collects date input as text. * @publicDocs */ -interface EmailField { +interface DateField { + /** + * The current value for the field, as a date in `YYYY-MM-DD` format (for + * example, `"2024-05-15"`). If omitted or empty, the field is empty. + * + * Values are interpreted in the device's local timezone. Out-of-range calendar + * dates (for example, `2024-02-30`) currently roll over to a valid date instead + * of being rejected. + */ + value?: string; /** A unique identifier for the element. */ id?: string; /** Content to use as the field label. */ label?: string; - /** The current value for the field. If omitted, the field will be empty. */ - value?: string; - /** A short hint that describes the expected value of the field. */ - placeholder?: string; + /** + * 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; /** * Disables the field, disallowing any interaction. * @default false @@ -5876,1782 +6699,1606 @@ interface EmailField { * @default false */ required?: boolean; - /** - * Specifies the maximum number of characters allowed. - * @default Infinity - */ - maxLength?: number; - /** - * 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; } /** - * The button component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The modal component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface ButtonEvents { - /** Called when the button is activated. */ - click?: (event: CallbackEvent) => void; +interface ModalEvents { + /** Callback when the modal starts to hide. Fired when a `commandFor` command requests the modal to close, before the closing transition completes. */ + hide?: (event: CallbackEvent) => void | null; + /** Callback when the modal starts to show. Fired when a `commandFor` command requests the modal to open, before the opening transition completes. */ + show?: (event: CallbackEvent) => void | null; } /** - * Triggers actions when selected by the merchant. + * The modal component supports slots for additional content placement within the modal. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface Button { - /** - * Sets the action the `commandFor` should take when this clickable is activated. - * - * See the documentation of particular components for the actions they support. - * - * - `--auto`: a default action for the target component. - * - `--show`: shows the target component. - * - `--hide`: hides the target component. - * - `--toggle`: toggles the target component. - * @default '--auto' - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command - */ - command?: '--auto' | '--show' | '--hide' | '--toggle'; - /** - * Sets the tone of the button, based on the intention of the information being conveyed. - * @default 'auto' - */ - tone?: 'auto' | 'neutral' | 'caution' | 'warning' | 'critical'; - /** - * Changes the visual appearance of the button. - * @default 'auto' - */ - variant?: 'auto' | 'primary' | 'secondary'; - /** A unique identifier for the element. */ - id?: string; - /** - * Disables the button meaning it cannot be clicked or receive focus. - * @default false - */ - disabled?: boolean; +interface ModalSlots { /** - * ID of a component that should respond to activations (e.g. clicks) on this component. + * The primary action button displayed in the modal. * - * See `command` for how to control the behavior of the target. - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor - */ - commandFor?: string; - /** - * Replaces content with a loading indicator while a background action is being performed. + * The tone of the button is used to define the tone of the modal. * - * This also disables the button. - * @default false + * If omitted, the modal uses the default tone and shows a 'Close' button, translated according to the user's locale. */ - loading?: boolean; + 'primary-action'?: HTMLElement; + /** The secondary action buttons displayed in the modal. At most two secondary actions are rendered. */ + 'secondary-actions'?: HTMLElement; } /** - * Renders styled textual content. + * The modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context. + * + * Modals block interaction with the underlying interface until the merchant resolves the modal content. + * + * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/feedback-and-status-indicators/modal#events). * @publicDocs */ -interface Text { - /** - * Modify the color to be more or less intense. - * @default 'base' - */ - color?: ColorKeyword; +interface Modal { /** - * Provide semantic meaning and default styling to the text. + * A unique identifier for the element. * - * Other presentation properties on Text override the default styling. - * @default 'generic' - */ - type?: 'strong' | 'small' | 'generic'; - /** - * Sets the tone of the component, based on the intention of the information being conveyed. - * @default 'auto' + * Required to control visibility: a button or link with `commandFor` set to this `id` shows, hides, or toggles the modal. */ - tone?: - | 'auto' - | 'neutral' - | 'info' - | 'success' - | 'caution' - | 'warning' - | 'critical'; - /** A unique identifier for the element. */ id?: string; + /** A title that describes the content of the Modal. */ + heading?: string; } /** - * Provides a scrollable container for overflowing content. + * The text field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface ScrollBox { - /** - * Adjust the block size. - * @default 'auto' - */ - blockSize?: SizeUnitsOrAuto; - /** - * Adjust the inline size. - * @default 'auto' - */ - inlineSize?: SizeUnitsOrAuto; - /** - * Adjust the maximum block size. - * @default 'none' - */ - maxBlockSize?: SizeUnitsOrNone; - /** - * Adjust the maximum inline size. - * @default 'none' - */ - maxInlineSize?: SizeUnitsOrNone; - /** - * Adjust the minimum block size. - * @default '0' - */ - minBlockSize?: SizeUnits; - /** - * Adjust the minimum inline size. - * @default '0' - */ - minInlineSize?: SizeUnits; +interface TextFieldEvents { + /** Callback when the user makes any changes in the field. */ + input?: (event: CallbackEvent) => void; /** - * 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`. - * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * @default 'none' + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. */ - padding?: MaybeAllValuesShorthandProperty; + change?: (event: CallbackEvent) => void; + /** Callback when the element loses focus. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the element receives focus. */ + focus?: (event: CallbackEvent) => void; +} + +/** + * The text field component supports slots for additional content placement within the text field. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * @publicDocs + */ +interface TextFieldSlots { + /** Additional content to be displayed in the field. Commonly used to display clickable text. */ + accessory?: HTMLElement; +} + +/** + * Collects single-line text input. + * @publicDocs + */ +interface TextField { /** - * Adjust the block-padding. - * - * - `large none` means block-start padding is `large`, block-end padding is `none`. + * The current value for the field. If omitted, the field manages its own state. * - * This overrides the block value of `padding`. - * @default '' - meaning no override + * Set `value` and update it from `onInput` or `onChange` to control the field. */ - paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + value?: string; + /** A unique identifier for the element. */ + id?: string; + /** Content to use as the field label. */ + label?: string; /** - * Adjust the block-start padding. + * 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 overrides the block-start value of `paddingBlock`. - * @default '' - meaning no override + * This will also be exposed to screen reader users. */ - paddingBlockStart?: '' | PaddingKeyword; + details?: string; + /** A short hint that describes the expected value of the field. */ + placeholder?: string; /** - * Adjust the block-end padding. - * - * This overrides the block-end value of `paddingBlock`. - * @default '' - meaning no override + * Disables the field, disallowing any interaction. + * @default false */ - paddingBlockEnd?: '' | PaddingKeyword; + disabled?: boolean; /** - * 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 + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ - paddingInline?: '' | MaybeTwoValuesShorthandProperty; + error?: string; /** - * Adjust the inline-start padding. - * - * This overrides the inline-start value of `paddingInline`. - * @default '' - meaning no override + * 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 */ - paddingInlineStart?: '' | PaddingKeyword; + required?: boolean; /** - * Adjust the inline-end padding. - * - * This overrides the inline-end value of `paddingInline`. - * @default '' - meaning no override + * Specifies the maximum number of characters allowed. + * @default Infinity */ - paddingInlineEnd?: '' | PaddingKeyword; - /** A unique identifier for the element. */ - id?: string; + maxLength?: number; } /** - * The tile component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The search field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface TileEvents { - /** Callback when the tile is activated. */ - click?: (event: CallbackEvent) => void; +interface SearchFieldEvents { + /** + * Callback when the user changes the value in the field. Also fires with an empty + * string when the user clears the field with the clear button; clearing the field + * doesn't fire `onChange`. + */ + input?: (event: CallbackEvent) => void; + /** Callback when the field loses focus after the user changes the value in the field. */ + change?: (event: CallbackEvent) => void; + /** Callback when the field loses focus. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the field is focused. */ + focus?: (event: CallbackEvent) => void; } /** - * Displays tappable content in a compact tile layout. + * Collects search queries for filtering and lookup workflows. * @publicDocs */ -interface Tile { - /** - * Disables the tile meaning it cannot be clicked or receive focus. - * @default false - */ - disabled?: boolean; +interface SearchField { /** - * A title that describes the content of the tile. - * @default '' + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. */ - heading?: string; + value?: string; /** A unique identifier for the element. */ id?: string; /** - * A numeric indicator rendered within the tile (for example, a count or a step number). - * - * - When provided, the indicator is displayed inside the tile. - * - Intended for small integers. It may clamp, truncate, or abbreviate larger values. - */ - itemCount?: number; - /** - * Sets the tone of the tile, based on the intention of the information being conveyed. - * @default 'auto' - */ - tone?: ExtractStrict; - /** - * Supporting text displayed below the heading. - * @default '' + * Disables the field, disallowing any interaction. + * @default false */ - subheading?: string; + disabled?: boolean; + /** A short hint that describes the expected value of the field. */ + placeholder?: string; } /** - * The banner component supports slots for additional content placement within the banner. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * The clickable component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface BannerSlots { - /** The action taken when the banner is pressed. */ - 'primary-action'?: HTMLElement; +interface ClickableEvents { + /** Callback when the element is activated. */ + click?: (event: CallbackEvent) => void; } /** - * Shows prominent status and messaging content with optional actions. + * Makes contained content interactive and clickable. * @publicDocs */ -interface Banner { - /** - * Determines whether the banner is hidden. - * @default false - */ - hidden?: boolean; - /** - * Sets the tone of the banner, based on the intention of the information being conveyed. - * @default 'auto' - */ - tone?: 'auto' | 'info' | 'success' | 'warning' | 'critical'; - /** - * The title of the banner. - * @default '' - */ - heading?: string; +interface Clickable { /** A unique identifier for the element. */ id?: string; + /** + * 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?: boolean; } /** - * Provides a generic layout container with sizing and spacing controls. + * The time field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface Box { - /** A unique identifier for the element. */ - id?: string; - /** - * Adjust the block size. - * @default 'auto' - */ - blockSize?: SizeUnitsOrAuto; - /** - * Adjust the inline size. - * @default 'auto' - */ - inlineSize?: SizeUnitsOrAuto; - /** - * Adjust the maximum block size. - * @default 'none' - */ - maxBlockSize?: SizeUnitsOrNone; - /** - * Adjust the maximum inline size. - * @default 'none' - */ - maxInlineSize?: SizeUnitsOrNone; - /** - * Adjust the minimum block size. - * @default '0' - */ - minBlockSize?: SizeUnits; +interface TimeFieldEvents { /** - * Adjust the minimum inline size. - * @default '0' + * Callback when the user confirms a time in the picker. Fires together with + * `onChange` at selection time. */ - minInlineSize?: SizeUnits; + input?: (event: CallbackEvent) => void; /** - * 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`. - * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * @default 'none' + * Callback when the user confirms a time in the picker. Fires together with + * `onInput` at selection time, not on blur. */ - padding?: MaybeAllValuesShorthandProperty; + change?: (event: CallbackEvent) => void; /** - * 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 + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. */ - paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + blur?: (event: CallbackEvent) => void; + /** Callback when the element receives focus. */ + focus?: (event: CallbackEvent) => void; +} + +/** + * Collects a time value. + * @publicDocs + */ +interface TimeField { /** - * Adjust the block-start padding. + * The current value for the field, as a 24-hour time in `HH:mm:ss` format with + * leading zeros (for example, `"09:05:00"`). If omitted or empty, the field is + * empty. * - * This overrides the block-start value of `paddingBlock`. - * @default '' - meaning no override + * Seconds aren't captured: emitted values always end in `:00`, and seconds in a + * provided value are ignored. Values are interpreted in the device's local + * timezone. The field displays times in 12-hour AM/PM format. */ - paddingBlockStart?: '' | PaddingKeyword; + value?: string; + /** A unique identifier for the element. */ + id?: string; + /** Content to use as the field label. */ + label?: string; /** - * Adjust the block-end padding. - * - * This overrides the block-end value of `paddingBlock`. - * @default '' - meaning no override + * Disables the field, disallowing any interaction. + * @default false */ - paddingBlockEnd?: '' | PaddingKeyword; + disabled?: boolean; /** - * 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 + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ - paddingInline?: '' | MaybeTwoValuesShorthandProperty; + error?: string; /** - * Adjust the inline-start padding. + * 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 overrides the inline-start value of `paddingInline`. - * @default '' - meaning no override + * This will also be exposed to screen reader users. */ - paddingInlineStart?: '' | PaddingKeyword; + details?: string; /** - * Adjust the inline-end padding. - * - * This overrides the inline-end value of `paddingInline`. - * @default '' - meaning no override + * 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 */ - paddingInlineEnd?: '' | PaddingKeyword; + required?: boolean; } /** - * Displays a predefined icon glyph. + * The number field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface Icon { - /** - * The type of icon to display. - * @default '' - */ - type?: SupportedIconNames; - /** A unique identifier for the element. */ - id?: string; - /** - * Sets the tone of the icon, based on the intention of the information being conveyed. - * @default 'auto' - */ - tone?: ToneKeyword; +interface NumberFieldEvents { /** - * Modify the color to be more or less intense. - * @default 'base' + * Callback when the user makes any changes in the field. In stepper mode, fires + * on every stepper button tap, together with `onChange`. */ - color?: ColorKeyword; + input?: (event: CallbackEvent) => void; /** - * Adjusts the size of the icon. - * @default 'base' + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. In stepper mode, fires on every stepper + * button tap, together with `onInput`. */ - size?: SizeKeyword; + change?: (event: CallbackEvent) => void; + /** Callback when the element loses focus. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the element receives focus. */ + focus?: (event: CallbackEvent) => void; } /** - * Arranges children in a horizontal or vertical stack. + * The number field component supports slots for additional content placement within the number field. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface Stack { - /** - * 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`. - * - * A padding value of `auto` will use the default padding for the closest container that has had its usual padding removed. - * @default 'none' - */ - padding?: MaybeAllValuesShorthandProperty; - /** - * 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 - */ - paddingBlock?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; - /** - * Adjust the block-start padding. - * - * This overrides the block-start value of `paddingBlock`. - * @default '' - meaning no override - */ - paddingBlockStart?: '' | PaddingKeyword; +interface NumberFieldSlots { /** - * Adjust the block-end padding. + * Additional content to be displayed in the field. Commonly used to display clickable text. * - * This overrides the block-end value of `paddingBlock`. - * @default '' - meaning no override + * > Note: Accessory is not supported when using Stepper controls */ - paddingBlockEnd?: '' | PaddingKeyword; + accessory?: HTMLElement; +} + +/** + * Collects numeric input with optional stepper controls. + * @publicDocs + */ +interface NumberField { /** - * Adjust the inline padding. + * The current value for the field, as a string. If omitted, the field manages its own state. * - * - `large none` means inline-start padding is `large`, inline-end padding is `none`. - * - * This overrides the inline value of `padding`. - * @default '' - meaning no override + * Set `value` and update it from `onInput` or `onChange` to control the field. + * In stepper mode the field is always populated: an empty or unparsable value is + * treated as `0`. */ - paddingInline?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; + value?: string; /** - * Adjust the inline-start padding. + * The highest value accepted for the field. * - * This overrides the inline-start value of `paddingInline`. - * @default '' - meaning no override + * In text mode, the field clamps an out-of-bounds value to `max` when editing + * finishes and delivers the clamped value through `onInput`. + * @default Infinity */ - paddingInlineStart?: '' | PaddingKeyword; + max?: number; /** - * Adjust the inline-end padding. + * The lowest value accepted for the field. * - * This overrides the inline-end value of `paddingInline`. - * @default '' - meaning no override - */ - paddingInlineEnd?: '' | PaddingKeyword; - /** - * Adjust the block size. - * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. - * @see ://developer.mozilla.org/en-US/docs/Web/CSS/block-size - * @default 'auto' - */ - blockSize?: SizeUnitsOrAuto; - /** - * Adjust the maximum block size. - * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. - * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size - * @default 'none' + * In text mode, the field clamps an out-of-bounds value to `min` when editing + * finishes and delivers the clamped value through `onInput`. + * @default -Infinity */ - maxBlockSize?: SizeUnitsOrNone; + min?: number; /** - * Adjust the maximum inline size. - * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. - * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size - * @default 'none' + * Content to use as the field label. + * + * Label is not supported when using Stepper controls */ - maxInlineSize?: SizeUnitsOrNone; + label?: string; /** - * Adjust the minimum block size. - * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. - * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size - * @default '0' + * 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 are not supported when using Stepper controls */ - minBlockSize?: SizeUnits; + details?: string; /** - * Adjust the minimum inline size. - * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. - * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size - * @default '0' + * 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. + * + * Required is not supported when using Stepper controls + * @default false */ - minInlineSize?: SizeUnits; - /** Aligns the stack's children along the cross axis. */ - alignItems?: AlignItemsKeyword; - /** Aligns the stack along the cross axis. */ - alignContent?: AlignContentKeyword; + required?: boolean; /** - * 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' + * 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 is not supported when using Stepper controls */ - gap?: MaybeTwoValuesShorthandProperty; + error?: string; /** - * Adjust spacing between elements in the inline axis. This overrides the column value of gap. - * @default '' - meaning no override + * Sets the virtual keyboard. + * + * Input mode is not supported when using Stepper controls + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode + * @default 'decimal' */ - columnGap?: '' | SpacingKeyword; + inputMode?: 'decimal' | 'numeric'; /** - * Sets how the children are placed within the stack. This uses logical properties. - * @default 'block' - * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' + * A short hint that describes the expected value of the field. + * + * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones. */ - direction?: 'block' | 'inline'; + placeholder?: string; /** - * Adjust the inline size. - * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size + * Sets the type of controls displayed for the field. + * + * - `stepper`: displays buttons to increase or decrease the value of the field in steps of 1. Note that in POS + * adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically + * validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls. + * + * - `none`: no controls are displayed and users must input the value manually. + * - `auto`: the presence of the controls depends on the surface and context. * @default 'auto' */ - inlineSize?: SizeUnitsOrAuto; - /** - * Aligns the stack along the main axis. - * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content - * @default 'normal' - */ - justifyContent?: JustifyContentKeyword; - /** - * Adjust spacing between elements in the block axis. This overrides the row value of gap. - * @default '' - meaning no override - */ - rowGap?: '' | SpacingKeyword; + controls?: 'auto' | 'stepper' | 'none'; /** A unique identifier for the element. */ id?: string; -} - -/** - * Displays compact status text with optional semantic tone. - * @publicDocs - */ -interface Badge { /** - * Sets the tone of the badge, based on the intention of the information being conveyed. - * @default 'auto' + * Disables the field, disallowing any interaction. + * @default false */ - tone?: - | 'auto' - | 'neutral' - | 'info' - | 'success' - | 'caution' - | 'warning' - | 'critical'; - /** A unique identifier for the element. */ - id?: string; + disabled?: boolean; } /** - * The choice list component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The date picker component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface ChoiceListEvents { - /** Callback when the user changes a choice. Fires simultaneously with onChange. */ - input?: (event: CallbackEvent) => void; - /** Callback when the user changes a choice. Fires simultaneously with onInput. */ - change?: (event: CallbackEvent) => void; +interface DatePickerEvents { + /** Callback when the user selects a date from the picker. Fires after `onChange`. */ + input?: (event: CallbackEvent) => void; + /** Callback when the user selects a date from the picker that is different to the current value. Fires before `onInput`. */ + change?: (event: CallbackEvent) => void; + /** Callback when the date picker is dismissed. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the date picker is revealed. */ + focus?: (event: CallbackEvent) => void; } /** - * Groups one or more selectable choices. + * Lets merchants select one or more dates from a calendar. * @publicDocs */ -interface ChoiceList { - /** A unique identifier for the element. */ - id?: string; +interface DatePicker { /** - * An array of the `value`s of the selected options. + * A unique identifier for the element. * - * This is a convenience prop for setting the `selected` prop on child options. + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. */ - values?: string[]; + id?: string; /** - * Whether multiple choices can be selected. - * @default false + * The current selected value. + * + * The default `''` means no date is selected. + * + * The value must be a date in `YYYY-MM-DD` format. Values are interpreted in + * the device's local timezone. Values that can't be parsed as a date are + * treated as no selection; out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * @default "" */ - multiple?: boolean; + value?: string; } /** - * Represents a selectable option within a choice list. + * The date spinner component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface Choice { - /** A unique identifier for the element. */ - id?: string; - /** The value used in form data when the control is checked. */ - value?: string; +interface DateSpinnerEvents { + /** Callback when the user makes a selection. Fires after `onChange`. */ + input?: (event: CallbackEvent) => void; + /** Callback when the value changes. Only called when a different value is selected. Fires before `onInput`. */ + change?: (event: CallbackEvent) => void; + /** Callback when the date spinner is dismissed. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the date spinner is revealed. */ + focus?: (event: CallbackEvent) => void; +} + +/** + * Lets merchants select a date using spinner controls. + * @publicDocs + */ +interface DateSpinner { /** - * Disables the control, disallowing any interaction. - * @default false + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. */ - disabled?: boolean; + id?: string; /** - * Whether the control is active. - * @default false + * The current selected value for the spinner, as a date in `YYYY-MM-DD` format. + * + * The default `''` means no date is selected. Values are interpreted in the + * device's local timezone. Out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * @default "" */ - selected?: boolean; + value?: string; } /** - * The date field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The section component supports slots for additional content placement within the section. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface DateFieldEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; +interface SectionSlots { + /** Button element to display in the section heading. A single button is supported. */ + 'secondary-actions'?: HTMLElement; } /** - * Collects date input as text. + * Groups related content into a titled section. * @publicDocs */ -interface DateField { - /** A unique identifier for the element. */ - id?: string; - /** Content to use as the field label. */ - label?: string; +interface Section { /** - * 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. + * A title that describes the content of the section. * - * This will also be exposed to screen reader users. - */ - details?: string; - /** The current value for the field. If omitted, the field will be empty. */ - value?: string; - /** - * Disables the field, disallowing any interaction. - * @default false - */ - disabled?: boolean; - /** - * 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; - /** - * 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 + * If omitted, and no secondaryActions are provided, the section will be rendered without a header. */ - required?: boolean; + heading?: string; + /** A unique identifier for the element. */ + id?: string; +} + +/** + * Displays heading text for grouping and hierarchy. + * @publicDocs + */ +interface Heading { + /** A unique identifier for the element. */ + id?: string; } /** - * The modal component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The time picker component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface ModalEvents { - /** Callback when the modal is hidden. */ - hide?: (event: CallbackEvent) => void | null; - /** Callback when the modal is shown. */ - show?: (event: CallbackEvent) => void | null; +interface TimePickerEvents { + /** Callback when the user selects a time from the picker. Fires after `onChange`. */ + input?: (event: CallbackEvent) => void; + /** Callback when the user selects a time from the picker that is different to the current value. Fires before `onInput`. */ + change?: (event: CallbackEvent) => void; + /** Callback when the time picker is dismissed. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the time picker is revealed. */ + focus?: (event: CallbackEvent) => void; } /** - * The modal component supports slots for additional content placement within the modal. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * Lets merchants select a time from a picker. * @publicDocs */ -interface ModalSlots { +interface TimePicker { /** - * The primary action button displayed in the modal. + * A unique identifier for the element. * - * The tone of the button is used to define the tone of the modal. + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: string; + /** + * The current selected value. * - * If omitted, the modal will default to an 'info' tone, and show an 'OK' button, translated according to the user's locale. + * The default `''` means no time is selected. + * + * The value must be a 24-hour time in `HH:mm:ss` format, with leading zeros + * (for example, `"09:05:00"`). Seconds aren't captured: emitted values always + * end in `:00`, and seconds in a provided value are ignored. Values are + * interpreted in the device's local timezone. + * @default '' */ - 'primary-action'?: HTMLElement; - /** The secondary action buttons displayed in the modal. */ - 'secondary-actions'?: HTMLElement; + value?: string; } /** - * The modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context. - * - * Modals block interaction with the underlying interface until the merchant resolves the modal content. - * - * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/polaris-web-components/feedback-and-status-indicators/modal#events). + * Displays an image with sizing and fit controls. * @publicDocs */ -interface Modal { +interface Image { + /** + * The displayed inline width of the image. + * + * - `fill`: the image will take up 100% of the available inline size. + * - `auto`: the image is displayed in a square (1:1 aspect ratio) container at the full available + * inline size. The POS translator doesn't render the image at its natural size. + * + * **Mobile surfaces:** Always wrap your image in a box with a set width and height. + * ScrollViews on mobile have a dynamic height, which can cause images to appear + * inconsistently without defined dimensions. + * @default 'fill' + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width + */ + inlineSize?: 'fill' | 'auto'; + /** + * The image source, which should be a remote URL. + * + * When no `src` is provided or the image fails to load, a placeholder is rendered. + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src + */ + src?: string; + /** + * Border radius for the image corners. + * + * [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 CSS, it uses flow-relative values and the order is: + * + * - 4 values: `start-start inline-end end-end inline-start` + * - 3 values: `start-start inline end-end` + * - 2 values: `block inline` + * + * For example: + * - `base` means all corners have `base` radius + * - `base none` means start-start and end-end corners are `base`, inline-end and inline-start corners are `none` + * - `base none large` means start-start is `base`, inline-end and inline-start are `none`, end-end is `large` + * - `base none large small` means start-start is `base`, inline-end is `none`, end-end is `large`, inline-start is `small` + * + * Supports size keywords from the design system scale: + * - Size scale: `small-500`, `small-400`, `small-300`, `small-200`, `small-100`, `small`, `base`, `large`, `large-100`, `large-200`, `large-300`, `large-400`, `large-500` + * - Special values: `max`, `none` + * @default 'none' + */ + borderRadius?: MaybeAllValuesShorthandProperty; /** A unique identifier for the element. */ id?: string; - /** A title that describes the content of the modal. */ - heading?: string; + /** + * 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 ://developer.mozilla.org/en-US/docs/Web/CSS/object-fit + */ + objectFit?: 'contain' | 'cover'; + /** + * 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 `''` + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt + */ + alt?: string; } /** - * The text field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The page component supports slots for additional content placement within the page. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface TextFieldEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; +interface PageSlots { + /** Button element to display in the action bar. Only a single button is supported. */ + 'secondary-actions'?: HTMLElement; + /** Content to display in the page's sidebar. */ + aside?: HTMLElement; } /** - * The text field component supports slots for additional content placement within the field. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * Provides the top-level page layout for extension content. * @publicDocs */ -interface TextFieldSlots { - /** Additional content to be displayed in the field. Commonly used to display clickable text. */ - accessory?: HTMLElement; +interface Page { + /** + * The main page heading, displayed in the action bar at the top of the page. + * @default : '' + */ + heading?: string; + /** A secondary page heading, displayed under the main heading in the action bar. */ + subheading?: string; + /** A unique identifier for the element. */ + id?: string; } /** - * Collects single-line text input. + * The pos block component supports slots for additional content placement within the pos block. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface TextField { +interface PosBlockSlots { + /** The secondary actions to perform, provided as button or link type elements. */ + 'secondary-actions'?: HTMLElement; +} + +/** + * Displays content in a POS block container with optional heading. + * @publicDocs + */ +interface PosBlock { /** A unique identifier for the element. */ id?: string; - /** Content to use as the field label. */ - label?: string; /** - * 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. + * The heading to display within the POSBlock. * - * This will also be exposed to screen reader users. - */ - details?: string; - /** The current value for the field. If omitted, the field will be empty. */ - value?: string; - /** A short hint that describes the expected value of the field. */ - placeholder?: string; - /** - * Disables the field, disallowing any interaction. - * @default false - */ - disabled?: boolean; - /** - * 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; - /** - * 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; - /** - * Specifies the maximum number of characters allowed. - * @default Infinity + * If not provided, the description of the extension will be used when a heading is appropriate. */ - maxLength?: number; + heading?: string; } -/** - * The search field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface SearchFieldEvents { - /** Callback when the user changes the value in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback when the field loses focus after the user changes the value in the field. */ - change?: (event: CallbackEvent) => void; - /** Callback when the field loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the field is focused. */ - focus?: (event: CallbackEvent) => void; +/** @private */ +interface QrCode { + /** A unique identifier for the element. */ + id?: string; + /** + * The content to be encoded in the QR code, which can be any string such as a URL, email address, plain text, etc. + * Specific string formatting can trigger actions on the user's device when scanned, like opening geolocation + * coordinates on a map, opening a preferred app or app store entry, preparing an email, text message, and more. + */ + content?: string; } /** - * Collects search queries for filtering and lookup workflows. + * Displays a visual separator between content sections. * @publicDocs */ -interface SearchField { +interface Divider { /** A unique identifier for the element. */ id?: string; /** - * Disables the field, disallowing any interaction. - * @default false + * 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' */ - disabled?: boolean; - /** A short hint that describes the expected value of the field. */ - placeholder?: string; - /** The current value for the field. If omitted, the field will be empty. */ - value?: string; + direction?: 'inline' | 'block'; } /** - * The clickable component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The link component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface ClickableEvents { - /** Callback when the element is activated. */ - click?: (event: CallbackEvent) => void; +interface LinkEvents { + /** Called when the link is activated. */ + click?: (event: CallbackEvent) => void; } /** - * Makes contained content interactive and clickable. + * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content. + * + * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/actions/button) instead. * @publicDocs */ -interface Clickable { +interface Link { /** A unique identifier for the element. */ id?: string; /** - * Disables the clickable, meaning it cannot be clicked or receive focus. + * ID of a component that should respond to activations (e.g. clicks) on this component. * - * 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. + * See `command` for how to control the behavior of the target. + * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor + */ + commandFor?: string; + /** + * Sets the action the `commandFor` should take when this clickable is activated. * - * However, items within the clickable can still receive focus and be interacted with. + * See the documentation of particular components for the actions they support. * - * This has no impact on the visual state by default, - * but developers are encouraged to style the clickable accordingly. + * - `--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 ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ - disabled?: boolean; + command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy'; + /** + * 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; } /** - * The time field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * The empty state component supports slots for additional content placement within the empty state. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ -interface TimeFieldEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; +interface EmptyStateSlots { + /** The primary action to perform, provided as a button or link type element. */ + 'primary-action'?: HTMLElement; + /** The secondary actions to perform, provided as button or link type elements. */ + 'secondary-actions'?: HTMLElement; + /** The graphic to display in the EmptyState. The only supported component is `Icon`, with a type of `alert-circle`, `search`, or `info`. */ + graphic?: HTMLElement; } /** - * Collects a time value. + * Displays an empty-state message with optional actions and supporting graphics. + * @publicDocs + */ +interface EmptyState { + /** The subheading of the EmptyState. */ + subheading?: string; + /** The heading of the EmptyState. */ + heading?: string; +} + +/** + * The embed component displays a preview of printable content from a specified source URL. Use it to show merchants what will be printed before triggering the actual print operation. + * + * Embed works in conjunction with the Print API to provide complete print functionality from preview to execution. + * + * The supported document types are the content types accepted by the `type` property: + * + * - **HTML documents** (`text/html`) - Receipts, invoices, and formatted reports with CSS styling and embedded images. + * - **Text files** (`text/plain`) - Plain text content such as simple receipts and data exports. + * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. PDF handling varies by platform; on Android, PDF content is downloaded and opened in an external viewer. + * + * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). * @publicDocs */ -interface TimeField { - /** A unique identifier for the element. */ - id?: string; - /** Content to use as the field label. */ - label?: string; +interface Embed { /** - * Disables the field, disallowing any interaction. - * @default false + * Adjust the block size. + * @default 'auto' */ - disabled?: boolean; + blockSize?: SizeUnitsOrAuto; /** - * Current selected value. - * - * The default, `''`, means no time is selected. - * - * The value must be a 24-hour time in `HH:mm:ss` format, with leading zeros. - * - * Examples: `"00:00:00"`, `"09:05:00"`, `"23:59:00"`, `"14:03:30"`. - * - * This follows the HTML time input value format, which is always 24-hour with - * leading zeros regardless of UI presentation. - * - * See: https://developer.mozilla.org/docs/Web/HTML/Element/input/time + * Adjust the minimum block size. + * @default '0' */ - value?: string; + minBlockSize?: SizeUnits; /** - * Indicate an error to the user. The field will be given a specific stylistic treatment - * to communicate problems that have to be resolved immediately. + * Adjust the maximum block size. + * @default 'none' */ - error?: string; + maxBlockSize?: SizeUnitsOrNone; /** - * 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. + * Adjust the inline size. + * @default 'auto' + */ + inlineSize?: SizeUnitsOrAuto; + /** + * Adjust the minimum inline size. + * @default '0' + */ + minInlineSize?: SizeUnits; + /** + * Adjust the maximum inline size. + * @default 'none' + */ + maxInlineSize?: SizeUnitsOrNone; + /** + * The content type of the file to display. + * @default 'text/html' + */ + type?: 'text/html' | 'text/plain' | 'application/pdf'; + /** + * The source of the file to preview. * - * This will also be exposed to screen reader users. + * The value must be either: + * - A relative path that will be appended to your app's `application_url`. + * - A full URL to your app's backend that will be used to return the file. + * + * Supported file types: + * - HTML files + * - Text files + * - PDF files + * @implementation If this value is omitted, the component should render an empty state or nothing. */ - details?: string; + src?: string; /** - * 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 + * A label that describes the purpose or contents of the Embed. It will be read to users + * using assistive technologies such as screen readers. + * @implementation for web-based implementations, this should map to the [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute */ - required?: boolean; + accessibilityLabel?: string; } /** - * The number field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). + * Displays a loading indicator while content or actions are in progress. * @publicDocs */ -interface NumberFieldEvents { - /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; - /** Callback after editing completes (typically on blur). */ - change?: (event: CallbackEvent) => void; - /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; - /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; +interface Spinner { + /** A unique identifier for the element. */ + id?: string; + /** + * A label that describes the purpose of the progress. When set, + * it will be announced to users using assistive technologies and will + * provide them with more context. Providing an `accessibilityLabel` is + * recommended if there is no accompanying text describing that something + * is loading. + */ + accessibilityLabel?: string; } /** - * The number field component supports slots for additional content placement within the field. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * The switch component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface NumberFieldSlots { +interface SwitchEvents { /** - * Additional content to be displayed in the field. Commonly used to display clickable text. - * - * > Note: Accessory is not supported when using Stepper controls + * Callback when the user toggles the switch. Fires together with `onChange`, + * after it. Read the new state from `event.currentTarget.checked`. */ - accessory?: HTMLElement; + input?: (event: CallbackEvent) => void; + /** + * Callback when the user toggles the switch. Fires together with `onInput`; + * `onChange` fires first. Read the new state from `event.currentTarget.checked`. + */ + change?: (event: CallbackEvent) => void; } /** - * Collects numeric input with optional stepper controls. + * Allows merchants to toggle a setting on or off. * @publicDocs */ -interface NumberField { +interface Switch { /** - * Content to use as the field label. + * A string value attached to the element. * - * Label is not supported when using Stepper controls + * Use `checked` for the switch state. A string `value` stays attached to the + * element and can be read back in event callbacks; it doesn't affect the switch + * state and isn't submitted with any form. */ - label?: string; + value?: string; /** - * 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. + * Whether the switch is on. * - * Details are not supported when using Stepper controls - */ - details?: string; - /** - * 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. + * When `checked` is set, update it from `onChange` or `onInput` to keep the + * switch controlled. When `checked` isn't set, the switch manages its own + * state, starting from `defaultChecked`. * @default false - * - * Required is not supported when using Stepper controls */ - required?: boolean; + checked?: boolean; /** - * Indicate an error to the user. The field will be given a specific stylistic treatment - * to communicate problems that have to be resolved immediately. + * Whether the switch is on when it first renders. * - * Error is not supported when using Stepper controls + * Applies only to the initial render; later changes to `defaultChecked` are + * ignored. Use `checked` to control the state after the first render. + * @default false */ - error?: string; + defaultChecked?: boolean; /** - * Sets the virtual keyboard. - * - * Input mode is not supported when using Stepper controls - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode - * @default 'decimal' + * Disables the control, disallowing any interaction. + * @default false */ - inputMode?: 'decimal' | 'numeric'; + disabled?: boolean; /** - * A short hint that describes the expected value of the field. - * - * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones. + * 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. */ - placeholder?: string; + accessibilityLabel?: string; + /** Visual content to use as the control label. */ + label?: string; /** - * Sets the type of controls displayed for the field. - * - * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property. Note that in POS - * adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically - * validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls. + * 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. * - * - `none`: no controls are displayed and users must input the value manually. - * - `auto`: the presence of the controls depends on the surface and context. - */ - controls?: 'auto' | 'stepper' | 'none'; - /** A unique identifier for the element. */ - id?: string; - /** The current value for the field. If omitted, the field will be empty. */ - value?: string; - /** - * Disables the field, disallowing any interaction. - * @default false + * This will also be exposed to screen reader users. */ - disabled?: boolean; + details?: string; /** - * 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 + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ - max?: number; + error?: string; /** - * The lowest decimal or integer to be accepted for the field. - * When used with `step` the value will round up to the min number. + * Changes the visibility of the component's label. * - * 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 + * - `visible`: the label is visible to all users. + * - `exclusive`: the label is visually hidden but remains in the accessibility tree. + * @default 'visible' */ - min?: number; -} - -/** - * The date picker component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface DatePickerEvents { - /** Callback when the user selects a date from the picker. */ - input?: (event: CallbackEvent) => void | null; - /** Callback when the user selects a date from the picker that is different to the current value. */ - change?: (event: CallbackEvent) => void | null; - /** Callback when the date picker is dismissed. */ - blur?: (event: CallbackEvent) => void | null; - /** Callback when the date picker is revealed. */ - focus?: (event: CallbackEvent) => void | null; + labelAccessibilityVisibility?: ExtractStrict< + 'visible' | 'hidden' | 'exclusive', + 'visible' | 'exclusive' + >; } /** - * Lets merchants select one or more dates from a calendar. + * The tabs component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface DatePicker { - /** A unique identifier for the element. */ - id?: string; +interface TabsEvents { /** - * Current selected value. - * - * The default means no date is selected. - * - * If the provided value is invalid, no date is selected. - * - * Otherwise: + * Callback fired when the selected tab changes. * - * - 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 "" + * Fires on every tab selection, including when the current tab is selected again. */ - value?: string; -} - -/** - * The date spinner component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface DateSpinnerEvents { - /** Callback when the user makes a selection. */ - input?: (event: CallbackEvent) => void | null; - /** Callback when the value changes. Only called when a different value is selected. */ - change?: (event: CallbackEvent) => void | null; - /** Callback when the date spinner is dismissed. */ - blur?: (event: CallbackEvent) => void | null; - /** Callback when the date spinner is revealed. */ - focus?: (event: CallbackEvent) => void | null; + change?: (event: CallbackEvent) => void; } /** - * Lets merchants select a date using spinner controls. + * Groups related content into selectable tabbed views. * @publicDocs */ -interface DateSpinner { - /** A unique identifier for the element. */ - id?: string; +interface Tabs { /** - * Current selected value for the spinner. + * The value of the selected tab. * - * This uses a date in `YYYY-MM-DD` format. - * @default "" + * This should match the `id` prop of one of the TabPanel components. + * When neither `value` nor `defaultValue` is provided, the first rendered tab panel is selected. */ value?: string; + /** + * The default value of the selected tab. + * + * This should match the `id` prop of one of the TabPanel components. + * Sets the initial selected tab in uncontrolled usage. Setting `value` afterwards overrides it. + */ + defaultValue?: string; + /** Disables all tabs and prevents user interaction. */ + disabled?: boolean; } /** - * The section component supports slots for additional content placement within the section. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * Presents the list of selectable tabs within a tabs component. Accepts only tab components as children. * @publicDocs */ -interface SectionSlots { - /** Button element to display in the section heading. A single button is supported. */ - 'secondary-actions'?: HTMLElement; -} +interface TabList {} /** - * Groups related content into a titled section. + * Represents an individual tab inside a tabs component. * @publicDocs */ -interface Section { +interface Tab { + /** Corresponds to the `id` property of the TabPanel component that will be displayed when selected */ + controls?: string; /** - * A title that describes the content of the section. - * - * If omitted, and no secondaryActions are provided, the section will be rendered without a header. + * Disables the control, disallowing any interaction. + * @default false */ - heading?: string; - /** A unique identifier for the element. */ - id?: string; + disabled?: boolean; } /** - * Displays heading text for grouping and hierarchy. + * Represents content associated with a selected tab. * @publicDocs */ -interface Heading { - /** A unique identifier for the element. */ +interface TabPanel { + /** + * The id of the TabPanel used for identification in the Tabs component. + * Must match the `controls` prop of the corresponding Tab component. + */ id?: string; } /** - * The time picker component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). - * @publicDocs - */ -interface TimePickerEvents { - /** Callback when the user selects a time from the picker. */ - input?: (event: CallbackEvent) => void | null; - /** Callback when the user selects a time from the picker that is different to the current value. */ - change?: (event: CallbackEvent) => void | null; - /** Callback when the time picker is dismissed. */ - blur?: (event: CallbackEvent) => void | null; - /** Callback when the time picker is revealed. */ - focus?: (event: CallbackEvent) => void | null; -} - -/** - * Lets merchants select a time from a picker. + * The text area component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface TimePicker { - /** A unique identifier for the element. */ - id?: string; +interface TextAreaEvents { + /** Callback when the user makes any changes in the field. */ + input?: (event: CallbackEvent) => void; /** - * Current selected value. - * - * The default, `''`, means no time is selected. - * - * The value must be a 24-hour time in `HH:mm:ss` format, with leading zeros. - * - * Examples: `"00:00:00"`, `"09:05:00"`, `"23:59:00"`, `"14:03:30"`. - * - * This follows the HTML time input value format, which is always 24-hour with - * leading zeros regardless of UI presentation. - * - * See: https://developer.mozilla.org/docs/Web/HTML/Element/input/time - * - * If the provided value is invalid, '' is used as the value. - * @default '' + * Callback after editing completes, on blur. Fires only when the value + * changed since the field received focus. */ - value?: string; + change?: (event: CallbackEvent) => void; + /** Callback when the element loses focus. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the element receives focus. */ + focus?: (event: CallbackEvent) => void; } /** - * Displays an image with sizing and fit controls. + * Collects multi-line text input from the merchant. * @publicDocs */ -interface Image { +interface TextArea { /** - * The displayed inline width of the image. - * - * - `fill`: the image will takes up 100% of the available inline size. - * - `auto`: the image will be displayed at its natural size. + * The current value for the field. If omitted, the field manages its own state. * - * **Mobile surfaces:** Always wrap your image in a box with a set width and height. - * ScrollViews on mobile have a dynamic height, which can cause images to appear - * inconsistently without defined dimensions. - * @default 'fill' - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width + * Set `value` and update it from `onInput` or `onChange` to control the field. */ - inlineSize?: 'fill' | 'auto'; + value?: string; /** - * The image source, which should be a remote URL. + * A number of visible text lines. * - * When the image is loading or no `src` is provided, a placeholder will be rendered. - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src + * Sets the visible height of the field only; it doesn't limit how many lines of + * text can be entered. Values are clamped between 1 and 8. + * @default 2 */ - src?: string; + rows?: number; /** A unique identifier for the element. */ id?: string; + /** Content to use as the field label. */ + label?: string; /** - * 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 ://developer.mozilla.org/en-US/docs/Web/CSS/object-fit + * 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. */ - objectFit?: 'contain' | 'cover'; + details?: string; + /** A short hint that describes the expected value of the field. */ + placeholder?: string; /** - * 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 `''` - * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt + * Disables the field, disallowing any interaction. + * @default false */ - alt?: string; + disabled?: boolean; /** - * Border radius for the image corners. - * - * [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 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) end-end` - * - 2 values: `(start-start & end-end) (start-end & end-start)` - * - * For example: - * - `base` means all corners have `base` radius - * - `base none` means start-start and end-end corners are `base`, start-end and end-start corners are `none` - * - `base none large` means start-start is `base`, start-end and end-start are `none`, end-end is `large` - * - `base none large small` means start-start is `base`, start-end is `none`, end-end is `large`, end-start is `small` - * - * @default 'none' + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ - borderRadius?: MaybeAllValuesShorthandProperty; -} - -/** - * The page component supports slots for additional content placement within the page. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). - * @publicDocs - */ -interface PageSlots { - /** Button element to display in the action bar. Only a single button is supported. */ - 'secondary-actions'?: HTMLElement; - /** Content to display in the page's sidebar. */ - aside?: HTMLElement; -} - -/** - * Provides the top-level page layout for extension content. - * @publicDocs - */ -interface Page { + error?: string; /** - * The main page heading, displayed in the action bar at the top of the page. - * @default : '' + * 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 */ - heading?: string; - /** A secondary page heading, displayed under the main heading in the action bar. */ - subheading?: string; - /** A unique identifier for the element. */ - id?: string; + required?: boolean; + /** + * Specifies the maximum number of characters allowed. + * @default Infinity + */ + maxLength?: number; } /** - * The POS block component supports slots for additional content placement within the block. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * The email field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ -interface PosBlockSlots { - /** The secondary actions to perform, provided as button or link type elements. */ - 'secondary-actions'?: HTMLElement; +interface EmailFieldEvents { + /** Callback when the user makes any changes in the field. */ + input?: (event: CallbackEvent) => void; + /** + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. + */ + change?: (event: CallbackEvent) => void; + /** Callback when the element loses focus. */ + blur?: (event: CallbackEvent) => void; + /** Callback when the element receives focus. */ + focus?: (event: CallbackEvent) => void; } /** - * Displays content in a POS block container with optional heading. + * Collects and validates email address input. * @publicDocs */ -interface PosBlock { - /** A unique identifier for the element. */ - id?: string; +interface EmailField { /** - * The heading to display within the POSBlock. + * The current value for the field. If omitted, the field manages its own state. * - * If not provided, the description of the extension will be used when a heading is appropriate. + * Set `value` and update it from `onInput` or `onChange` to control the field. */ - heading?: string; -} - -/** - * Renders a QR code from provided content. - * @publicDocs - */ -interface QrCode { + value?: string; /** A unique identifier for the element. */ id?: string; + /** Content to use as the field label. */ + label?: string; + /** A short hint that describes the expected value of the field. */ + placeholder?: string; /** - * The content to be encoded in the QR code, which can be any string such as a URL, email address, plain text, etc. - * Specific string formatting can trigger actions on the user's device when scanned, like opening geolocation - * coordinates on a map, opening a preferred app or app store entry, preparing an email, text message, and more. + * Disables the field, disallowing any interaction. + * @default false */ - content?: string; -} - -/** - * Displays a visual separator between content sections. - * @publicDocs - */ -interface Divider { - /** A unique identifier for the element. */ - id?: string; + disabled?: boolean; /** - * 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' + * Indicate an error to the user. The field will be given a specific stylistic treatment + * to communicate problems that have to be resolved immediately. */ - direction?: 'inline' | 'block'; + error?: string; + /** + * 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; + /** + * Specifies the maximum number of characters allowed. + * @default Infinity + */ + maxLength?: number; + /** + * 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; +} +declare module 'react' { + namespace JSX { + interface IntrinsicElements { + [tagName$K]: IntrinsicElementProps; + } + } +} +declare global { + namespace JSX { + interface IntrinsicElements { + [tagName$K]: IntrinsicElementProps; + } + } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$E]: IntrinsicElementProps; + [tagName$J]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$E]: IntrinsicElementProps; + [tagName$J]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$D]: IntrinsicElementProps; + [tagName$I]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$D]: IntrinsicElementProps; + [tagName$I]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$C]: IntrinsicElementProps; + [tagName$H]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$C]: IntrinsicElementProps; + [tagName$H]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$B]: IntrinsicElementProps; + [tagName$G]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$B]: IntrinsicElementProps; + [tagName$G]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$A]: IntrinsicElementProps; + [tagName$F]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$A]: IntrinsicElementProps; + [tagName$F]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$z]: IntrinsicElementProps; + [tagName$E]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$z]: IntrinsicElementProps; + [tagName$E]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$y]: IntrinsicElementProps; + [tagName$D]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$y]: IntrinsicElementProps; + [tagName$D]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$x]: IntrinsicElementProps; + [tagName$C]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$x]: IntrinsicElementProps; + [tagName$C]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$w]: IntrinsicElementProps; + [tagName$B]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$w]: IntrinsicElementProps; + [tagName$B]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$v]: IntrinsicElementProps; + [tagName$A]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$v]: IntrinsicElementProps; + [tagName$A]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$u]: IntrinsicElementProps; + [tagName$z]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$u]: IntrinsicElementProps; + [tagName$z]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$t]: IntrinsicElementProps; + [tagName$y]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$t]: IntrinsicElementProps; + [tagName$y]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$s]: IntrinsicElementProps; + [tagName$x]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$s]: IntrinsicElementProps; + [tagName$x]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$r]: IntrinsicElementProps; + [tagName$w]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$r]: IntrinsicElementProps; + [tagName$w]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$q]: IntrinsicElementProps; + [tagName$v]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$q]: IntrinsicElementProps; + [tagName$v]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$p]: IntrinsicElementProps; + [tagName$u]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$p]: IntrinsicElementProps; + [tagName$u]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$o]: IntrinsicElementProps; + [tagName$t]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$o]: IntrinsicElementProps; + [tagName$t]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$n]: IntrinsicElementProps; + [tagName$s]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$n]: IntrinsicElementProps; + [tagName$s]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$m]: IntrinsicElementProps; + [tagName$r]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$m]: IntrinsicElementProps; + [tagName$r]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$l]: IntrinsicElementProps; + [tagName$q]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$l]: IntrinsicElementProps; + [tagName$q]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$k]: IntrinsicElementProps; + [tagName$p]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$k]: IntrinsicElementProps; + [tagName$p]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$j]: IntrinsicElementProps; + [tagName$o]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$j]: IntrinsicElementProps; + [tagName$o]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$i]: IntrinsicElementProps; + [tagName$n]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$i]: IntrinsicElementProps; + [tagName$n]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$h]: IntrinsicElementProps; + [tagName$m]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$h]: IntrinsicElementProps; + [tagName$m]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$g]: IntrinsicElementProps; + [tagName$l]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$g]: IntrinsicElementProps; + [tagName$l]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$f]: IntrinsicElementProps; + [tagName$k]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$f]: IntrinsicElementProps; + [tagName$k]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$e]: IntrinsicElementProps; + [tagName$j]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$e]: IntrinsicElementProps; + [tagName$j]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$d]: IntrinsicElementProps; + [tagName$i]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$d]: IntrinsicElementProps; + [tagName$i]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$c]: IntrinsicElementProps; + [tagName$h]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$c]: IntrinsicElementProps; + [tagName$h]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$b]: IntrinsicElementProps; + [tagName$b]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$b]: IntrinsicElementProps; + [tagName$b]: IntrinsicElementProps; } } } @@ -7672,14 +8319,14 @@ declare global { declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$9]: IntrinsicElementProps; + [tagName$9]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$9]: IntrinsicElementProps; + [tagName$9]: IntrinsicElementProps; } } } @@ -7784,28 +8431,28 @@ declare global { declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName$1]: IntrinsicElementProps; + [tagName$1]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName$1]: IntrinsicElementProps; + [tagName$1]: IntrinsicElementProps; } } } declare module 'react' { namespace JSX { interface IntrinsicElements { - [tagName]: IntrinsicElementProps; + [tagName]: IntrinsicElementProps; } } } declare global { namespace JSX { interface IntrinsicElements { - [tagName]: IntrinsicElementProps; + [tagName]: IntrinsicElementProps; } } } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/examples/controls-constraints.jsx b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/examples/controls-constraints.jsx index 63863a6214..13b2b257e9 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/examples/controls-constraints.jsx +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField/examples/controls-constraints.jsx @@ -3,7 +3,7 @@ value="5" min={1} max={100} - controls + controls="stepper" onInput={(event) => console.log('Input:', event.currentTarget.value)} onChange={(event) => console.log('Change:', event.currentTarget.value)} />; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.html b/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.html deleted file mode 100644 index 96b6265623..0000000000 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.html +++ /dev/null @@ -1,5 +0,0 @@ - console.log('Switch toggled:', event.currentTarget.checked)} -/> diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.jsx b/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.jsx new file mode 100644 index 0000000000..3285a8da42 --- /dev/null +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch/examples/event-handling.jsx @@ -0,0 +1,7 @@ + + console.log('Switch toggled:', event.currentTarget.checked) + } +/>; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/default.html b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/default.html index eb9d8a2324..511103c518 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/default.html +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/default.html @@ -1,4 +1 @@ - \ No newline at end of file + diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/event-handling.jsx b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/event-handling.jsx index 0a1a5378c6..7e26b27b89 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/event-handling.jsx +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField/examples/event-handling.jsx @@ -1,8 +1,8 @@ console.log('Input:', event.currentTarget.value)} onChange={(event) => console.log('Change:', event.currentTarget.value)} onFocus={(event) => console.log('Focused')} onBlur={(event) => console.log('Blurred')} -/> \ No newline at end of file +/>; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/command-system.jsx b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/command-system.jsx index 9c434f44f4..c27ec36ca2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/command-system.jsx +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/command-system.jsx @@ -4,7 +4,9 @@ console.log('Time selected:', event.currentTarget.value)} + value="14:30:00" + onChange={(event) => + console.log('Time selected:', event.currentTarget.value) + } /> ; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/default.html b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/default.html index cdda01f557..9dfbb6cc3f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/default.html +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/default.html @@ -1,7 +1,2 @@ - - Show - - \ No newline at end of file +Show + diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/event-handling.jsx b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/event-handling.jsx index e2bdb4135e..521ebcac81 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/event-handling.jsx +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker/examples/event-handling.jsx @@ -1,7 +1,7 @@ console.log('Input:', event.currentTarget.value)} onChange={(event) => console.log('Change:', event.currentTarget.value)} onFocus={(event) => console.log('Focused')} onBlur={(event) => console.log('Blurred')} -/> \ No newline at end of file +/>; From 4cdf999f605714b3c6eecc8302c9d4f1efb80cc7 Mon Sep 17 00:00:00 2001 From: Richard Gajda Date: Mon, 28 Sep 2026 16:02:01 -0400 Subject: [PATCH 2/2] Align POS API contracts and regenerate complete component declarations --- .changeset/pos-component-contract-docs.md | 2 + packages/ui-extensions/src/api.ts | 8 +- packages/ui-extensions/src/shared.ts | 2 + .../api/action-api/action-api.ts | 2 +- .../api/camera-api/camera-api.ts | 7 +- .../point-of-sale/api/cart-api/cart-api.ts | 39 +- .../api/cash-drawer-api/cash-drawer-api.ts | 2 + .../api/connectivity-api/connectivity-api.ts | 4 +- .../api/device-api/device-api.ts | 5 +- .../api/locale-api/locale-api.ts | 2 +- .../api/navigation-api/navigation-api.ts | 11 - .../surfaces/point-of-sale/api/pin-pad-api.ts | 2 + .../point-of-sale/api/print-api/print-api.ts | 10 +- .../api/printing-api/printing-api.ts | 32 +- .../product-search-api/product-search-api.ts | 6 +- .../api/session-api/session-api.ts | 8 +- .../surfaces/point-of-sale/components.d.ts | 636 +++++++++--------- .../point-of-sale/components/Badge.d.ts | 42 +- .../point-of-sale/components/Banner.d.ts | 51 +- .../point-of-sale/components/Box.d.ts | 83 +-- .../point-of-sale/components/Button.d.ts | 99 +-- .../point-of-sale/components/Choice.d.ts | 51 +- .../point-of-sale/components/ChoiceList.d.ts | 88 +-- .../point-of-sale/components/Clickable.d.ts | 70 +- .../point-of-sale/components/DateField.d.ts | 89 +-- .../point-of-sale/components/DatePicker.d.ts | 104 ++- .../point-of-sale/components/DateSpinner.d.ts | 101 ++- .../point-of-sale/components/Divider.d.ts | 31 +- .../point-of-sale/components/EmailField.d.ts | 124 ++-- .../point-of-sale/components/Embed.d.ts | 152 +++-- .../point-of-sale/components/EmptyState.d.ts | 58 +- .../point-of-sale/components/Heading.d.ts | 33 +- .../point-of-sale/components/Icon.d.ts | 35 +- .../point-of-sale/components/Image.d.ts | 100 +-- .../point-of-sale/components/Link.d.ts | 93 +-- .../point-of-sale/components/Modal.d.ts | 91 +-- .../point-of-sale/components/NumberField.d.ts | 153 +++-- .../point-of-sale/components/Page.d.ts | 42 +- .../point-of-sale/components/PosBlock.d.ts | 36 +- .../point-of-sale/components/QrCode.d.ts | 26 +- .../point-of-sale/components/ScrollBox.d.ts | 83 +-- .../point-of-sale/components/SearchField.d.ts | 82 +-- .../point-of-sale/components/Section.d.ts | 40 +- .../point-of-sale/components/Spinner.d.ts | 51 +- .../point-of-sale/components/Stack.d.ts | 125 ++-- .../point-of-sale/components/Switch.d.ts | 122 +++- .../point-of-sale/components/Tab.d.ts | 58 +- .../point-of-sale/components/TabList.d.ts | 49 +- .../point-of-sale/components/TabPanel.d.ts | 49 +- .../point-of-sale/components/Tabs.d.ts | 95 ++- .../point-of-sale/components/Text.d.ts | 51 +- .../point-of-sale/components/TextArea.d.ts | 134 ++-- .../point-of-sale/components/TextField.d.ts | 84 +-- .../point-of-sale/components/Tile.d.ts | 70 +- .../point-of-sale/components/TimeField.d.ts | 89 +-- .../point-of-sale/components/TimePicker.d.ts | 104 ++- .../components/components-shared.d.ts | 271 ++------ .../src/surfaces/point-of-sale/types/cart.ts | 48 +- .../surfaces/point-of-sale/types/device.ts | 2 +- .../surfaces/point-of-sale/types/payment.ts | 5 + .../surfaces/point-of-sale/types/pin-pad.ts | 2 +- .../surfaces/point-of-sale/types/storage.ts | 13 +- 62 files changed, 1961 insertions(+), 2196 deletions(-) diff --git a/.changeset/pos-component-contract-docs.md b/.changeset/pos-component-contract-docs.md index 2489a01e6c..1aac4b5880 100644 --- a/.changeset/pos-component-contract-docs.md +++ b/.changeset/pos-component-contract-docs.md @@ -3,3 +3,5 @@ --- Correct POS date and time component callback types to accept null, preserve inherited component declarations during generation, and update component contract documentation and examples. + +Align POS API descriptions with version-specific cart mutation outcomes, storage errors, session and localization behavior, hardware requests, and navigation. diff --git a/packages/ui-extensions/src/api.ts b/packages/ui-extensions/src/api.ts index 5661de42c6..8a2b73a704 100644 --- a/packages/ui-extensions/src/api.ts +++ b/packages/ui-extensions/src/api.ts @@ -5,6 +5,10 @@ export interface I18nTranslate { /** * Returns a translated string matching a key in a locale file. Use this to display localized text in your extension based on the merchant's language preferences. Supports interpolation with replacement values and pluralization with the `count` option. Returns a string when replacements are primitives, or an array when replacements include UI components. * + * In POS extensions, translation lookup doesn't expose a separate success or error result. A missing key, a missing required plural form, or a missing pluralization count can produce diagnostic text as the return value, along with a console warning. A missing interpolation value leaves the unresolved placeholder in the returned text and emits a warning. Check the development console and test each locale, plural category, and interpolation key before displaying translated content. Don't rely on diagnostic message wording as a stable API contract. + * + * In POS extensions, pass the `count` option as a number for a pluralized translation key. Zero is a valid count. A numeric string doesn't select a plural form, and omitting the count or passing `undefined` produces a missing-count diagnostic for a pluralized key. + * * @param key - The translation key from your locale file (for example, "banner.title") * @param options - Optional replacement values for interpolation or the special `count` property for pluralization * @@ -38,7 +42,9 @@ export interface I18n { /** * Returns a localized currency value formatted according to the user's locale and currency conventions. Use this to display prices, totals, or financial amounts in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. Uses the current user's locale by default. * - * @param number - The currency amount to format + * In POS extensions, pass an amount in major currency units and provide `options.currency` as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. For example, `formatCurrency(10, {currency: 'CAD'})` formats ten Canadian dollars. The function doesn't convert currencies or divide an integer minor-unit amount. Omitting the currency while using the currency style throws synchronously. Formatting errors from invalid Intl options are synchronous exceptions, not rejected promises. + * + * @param number - The currency amount to format, in major currency units * @param options.inExtensionLocale - If true, use the extension's default locale instead of the user's locale * @param options - Additional Intl.NumberFormatOptions for customizing the currency format, such as the currency code */ diff --git a/packages/ui-extensions/src/shared.ts b/packages/ui-extensions/src/shared.ts index a03bb9af91..0f54cf68de 100644 --- a/packages/ui-extensions/src/shared.ts +++ b/packages/ui-extensions/src/shared.ts @@ -976,6 +976,8 @@ export interface ReadonlySignalLike { readonly value: T; /** * Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value. + * + * Read `value` when you need the initial snapshot. A subscription callback can also receive the current value during subscription setup, particularly when you use the `@shopify/ui-extensions/preact` integration, so a callback firing isn't proof that a new host event occurred. Save the returned unsubscribe function and call it during component cleanup. */ subscribe(fn: (value: T) => void): () => void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts index dfcd1675cf..a59e3295e1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/action-api/action-api.ts @@ -3,7 +3,7 @@ */ export interface ActionApiContent { /** - * Presents the corresponding action (modal) target on top of the current view as a full-screen modal. For example, calling this method from `pos.purchase.post.action.menu-item.render` presents `pos.purchase.post.action.render`. Use to launch detailed workflows, complex forms, or multi-step processes that require more screen space than simple components provide. + * Presents the corresponding action (modal) target on top of the current view as a full-screen modal. The companion modal target must be registered in the same extension. Calling this method from a menu item or block target presents the companion `.action.render` target for that target group; for example, calling it from `pos.purchase.post.action.menu-item.render` presents `pos.purchase.post.action.render`. Calling it from a tile target presents the companion `.modal.render` target; for example, calling it from `pos.home.tile.render` presents `pos.home.modal.render`. Use to launch detailed workflows, complex forms, or multi-step processes that require more screen space than simple components provide. */ presentModal(): void; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts index 59a6581791..3cbdf5c0e1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts @@ -11,18 +11,18 @@ export interface CameraMediaOptions { */ facingMode?: 'user' | 'environment'; /** - * The maximum width (1 to 1920) of the image in pixels. Resizes the image to this width if it is larger. + * The requested maximum width of the captured image in pixels. Resizes the image to this width if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `width` on the returned `CameraMediaResponse` is the actual captured image width. * @defaultValue 1080 */ maxWidth?: number; /** - * The maximum height (1 to 1920) of the image in pixels. Resizes the image to this height if it is larger. + * The requested maximum height of the captured image in pixels. Resizes the image to this height if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `height` on the returned `CameraMediaResponse` is the actual captured image height. * @defaultValue 1080 */ maxHeight?: number; /** * The quality of the image returned. - * Percentile value between 0 (lowest quality/highest compression) and 1 (highest quality/lowest compression). + * A value between 0 (lowest quality, highest compression) and 1 (highest quality, lowest compression). `takePhoto` rejects values outside this range. * @defaultValue 0.9 */ quality?: number; @@ -59,6 +59,7 @@ export interface CameraApiContent { * @throws {Error} when the user cancels the photo capture * @throws {Error} when the device has no available camera * @throws {Error} when the camera API is already in use + * @throws {Error} when `options` are invalid, such as a `quality` outside the 0 to 1 range */ takePhoto: (options?: CameraMediaOptions) => Promise; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts index fbaf469a6b..ac8cf10ec1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cart-api/cart-api.ts @@ -47,12 +47,16 @@ export type LineItemDiscountType = 'Percentage' | 'FixedAmount'; export interface ReadonlyCartApiContent { /** * Provides read-only access to the current cart state and allows subscribing to cart changes. The `value` property provides the current cart state, and `subscribe` allows listening to changes with improved performance and memory management. + * + * While POS is in a return, exchange, or refund flow, this signal exposes an empty, non-editable cart (`editable: false`). The lines being returned or exchanged aren't exposed through this signal. */ current: ReadonlySignalLike; } /** * Cart and line item write operations. + * + * Each mutation returns a promise that resolves once POS has processed the operation. On every API version, a mutation rejects the promise when the cart isn't editable (during a return, exchange, or refund flow) or when the underlying POS operation fails. On API version 2026-10 and later, most mutations also reject when POS refuses the write or can't confirm that it succeeded; on earlier API versions, the promise can resolve in that case. Some methods resolve without confirming the write on every API version: `removeCartDiscount`, `clearCart`, `addCartProperties`, `removeCartProperties`, `setAttributedStaff`, and `setAttributedStaffToLineItem`. After a mutation, read `shopify.cart.current` to confirm the cart state changed. * @publicDocs */ export interface MutableCartApiContent { @@ -65,11 +69,13 @@ export interface MutableCartApiContent { bulkCartUpdate(cartState: CartUpdateInput): Promise; /** - * Apply a cart-level discount with the specified type (`'Percentage'`, `'FixedAmount'`, or `'Code'`), title, and optional amount. For discount codes, omit the `amount` parameter. Enhanced validation ensures proper discount application. + * Apply a cart-level discount with the specified type (`'Percentage'`, `'FixedAmount'`, or `'Code'`), title, and optional amount. + * + * For type `'Code'`, pass the discount code itself as `title` (it must be non-empty) and omit `amount`. For validated code redemption with availability checks, use `addCartCodeDiscount` instead. For `'Percentage'` and `'FixedAmount'`, `amount` is required; omitting it submits a zero-value discount. * * @param type the type of discount applied (example: 'Percentage') - * @param title the title attributed with the discount - * @param amount the percentage or fixed monetary amount deducted with the discount. Pass in `undefined` if using discount codes. + * @param title the title attributed with the discount. For type `'Code'`, the discount code to redeem + * @param amount the percentage or fixed monetary amount deducted with the discount. Required for `'Percentage'` and `'FixedAmount'`; pass `undefined` for discount codes */ applyCartDiscount( type: CartDiscountType, @@ -78,7 +84,9 @@ export interface MutableCartApiContent { ): Promise; /** - * Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents with improved error messaging. + * Apply a discount code to the cart. POS validates the code against the shop's discount rules and applies the appropriate discount if the code is valid and applicable to the current cart contents. + * + * On API version 2026-10 and later, the returned promise rejects if the code is invalid or can't be applied. On earlier API versions, an invalid or inapplicable code can fail without rejecting the promise; check `shopify.cart.current` to confirm the discount was applied. * * @param code the code for the discount to add to the cart */ @@ -122,14 +130,14 @@ export interface MutableCartApiContent { addCustomSale(customSale: CustomSale): Promise; /** - * Add a product variant to the cart by its numeric `ID` with the specified quantity. Returns the `UUID` of the newly added line item, or an empty string if the user dismissed an oversell guard modal. Throws an error if POS fails to add the line item due to validation or system errors. + * Add a product variant to the cart by its numeric `ID` with the specified quantity. Returns the `UUID` of the new line item, or the `UUID` of the existing line item if POS merged the quantity into a matching line. Throws an error if the variant can't be found or POS fails to add the line item. * - * Pass `options` to attach line-item properties in the same operation, instead of following up with a separate `addLineItemProperties` call. + * Pass `options` to attach line-item properties in the same operation, instead of following up with a separate `addLineItemProperties` call. The `'RFID Tag'` property key is reserved and isn't applied to the line item. * * @param variantId the product variant's numeric ID to add to the cart * @param quantity the number of this variant to add to the cart * @param options optional line-item properties to apply to the new line item in the same operation - * @returns {string} the UUID of the line item added, or the empty string if the user dismissed an oversell guard modal + * @returns {string} the UUID of the line item added or merged into * @throws {Error} if POS fails to add the line item */ addLineItem( @@ -176,7 +184,7 @@ export interface MutableCartApiContent { /** * Add custom properties to a specific line item using its `UUID`. Properties are merged with existing line item properties for metadata storage and tracking with enhanced validation. * - * @param uuid the uuid of the line item to which the properties should be stringd + * @param uuid the uuid of the line item to which the properties should be added * @param properties the custom key to value object to attribute to the line item */ addLineItemProperties( @@ -204,10 +212,12 @@ export interface MutableCartApiContent { /** * Apply a discount to a specific line item using its `UUID`. Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value with improved discount allocation tracking. `FixedAmount` discounts use per-unit amounts. For example, passing `'5.00'` on a line item with quantity 2 results in a $10.00 total discount. * + * On API versions earlier than 2026-07, `FixedAmount` amounts apply to the whole line instead: POS divides the total across the line's quantity, which can introduce a one-cent rounding difference (for example, `'2.00'` on a quantity of 3 becomes `'0.67'` per unit). + * * @param uuid the uuid of the line item that should receive a discount * @param type the type of discount applied (example: 'Percentage') * @param title the title attributed with the discount - * @param amount the percentage or fixed monetary amount deducted with the discout + * @param amount the percentage or fixed monetary amount deducted with the discount */ setLineItemDiscount( uuid: string, @@ -219,14 +229,16 @@ export interface MutableCartApiContent { /** * Apply discounts to multiple line items simultaneously. Each input specifies the line item `UUID` and discount details for efficient bulk discount operations with enhanced validation and allocation tracking. `FixedAmount` discounts use per-unit amounts. For example, passing `'5.00'` on a line item with quantity 2 results in a $10.00 total discount. * - * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input. + * On API versions earlier than 2026-07, `FixedAmount` amounts apply to the whole line instead: POS divides the total across the line's quantity, which can introduce a one-cent rounding difference (for example, `'2.00'` on a quantity of 3 becomes `'0.67'` per unit). + * + * @param lineItemDiscounts an array of discount inputs to apply. Each entry pairs the target line item's `UUID` (`lineItemUuid`) with the discount to apply to it (`lineItemDiscount`). */ bulkSetLineItemDiscounts( lineItemDiscounts: SetLineItemDiscountInput[], ): Promise; /** - * Set the attributed staff member for all line items in the cart using the staff `ID`. Pass `undefined` to clear staff attribution from all line items with enhanced staff validation and tracking. + * Set the attributed staff member for all line items in the cart using the staff `ID`. Gift card line items are excluded from staff attribution and keep their current attribution. Pass `undefined` to clear staff attribution from all line items. * * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items. */ @@ -272,10 +284,9 @@ export interface MutableCartApiContent { updateDefaultAddress(addressId: number): Promise; /** - * Add a selling plan to a line item in the cart using the line item `UUID`, selling plan `ID`, and selling plan name. Optionally provide delivery interval and interval count for improved performance, otherwise POS will fetch them after syncing the cart. + * Add a selling plan to a line item in the cart. * - * @param uuid the uuid of the line item that should receive the selling plan - * @param sellingPlanId the ID of the selling plan to add to the line item + * @param input the selling plan assignment, containing the target line item's `UUID` (`lineItemUuid`), the selling plan `ID` (`sellingPlanId`), and an optional display name (`sellingPlanName`) */ addLineItemSellingPlan(input: SetLineItemSellingPlanInput): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts index 4e2841ca70..4e2e073041 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/cash-drawer-api/cash-drawer-api.ts @@ -6,6 +6,8 @@ export interface CashDrawerApiContent { /** * Opens the connected cash drawer device. The drawer will automatically open if a compatible cash drawer is connected to the POS device. Use for manual cash drawer operations, implementing custom payment workflows, or providing explicit cash drawer access in register management interfaces. * + * The returned promise resolves once the open command has been passed to the native printer bridge. It doesn't confirm that the drawer physically opened, and later hardware failures (such as a jammed drawer) aren't reported. Errors while sending the command reject the promise. + * * @returns Void */ open(): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts index 5ce2b2b01e..5d1f8d785d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts @@ -11,7 +11,7 @@ export type ConnectivityStateSeverity = 'Connected' | 'Disconnected'; */ export interface ConnectivityState { /** - * The Internet connection status of the POS device. + * The Internet connection status of the POS device. The state defaults to `'Connected'` until POS has confirmed connectivity, and a confirmed outage is required before `'Disconnected'` is reported. */ internetConnected: ConnectivityStateSeverity; } @@ -22,7 +22,7 @@ export interface ConnectivityState { */ export interface ConnectivityApiContent { /** - * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling. + * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling. The state defaults to `Connected` until POS has confirmed connectivity, so an initial `Connected` value doesn't guarantee that the device is online. */ current: ReadonlySignalLike; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts index 7219339e3a..181fbec386 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/device-api/device-api.ts @@ -4,7 +4,7 @@ */ export interface DeviceApiContent { /** - * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful. + * The operating system device name (for example, the iPad name set in system settings). For the merchant-assigned register name configured in POS settings, use `registerName`. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful. */ name: string; /** @@ -13,6 +13,9 @@ export interface DeviceApiContent { registerName: string; /** * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations. + * + * This identifier differs from the numeric device ID available as `shopify.session.deviceId` and as `device.deviceId` on event data. + * * Note: While Shopify POS attempts to maintain a stable identifier, it is not guaranteed to be permanent and may change. */ getDeviceId(): Promise; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts index b386a6e18e..c498a99ef1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/locale-api/locale-api.ts @@ -6,7 +6,7 @@ import type {ReadonlySignalLike} from '../../../../shared'; */ export interface LocaleApiContent { /** - * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings. + * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings. At cold start, the value can briefly reflect the device locale before the POS app locale is applied. */ current: ReadonlySignalLike; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts index 69787040b6..35c5f4ad36 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts @@ -86,14 +86,3 @@ export interface Window { */ close(): void; } - -/** - * The global `window` object provides control over the extension modal lifecycle. Access these properties and methods directly through the global `window` object to manage the modal interface programmatically. - * @publicDocs - */ -export interface Window { - /** - * Closes the extension screen and dismisses the modal interface. Use to programmatically close the modal after completing a workflow, canceling an operation, or when user action is no longer required. This provides the same behavior as the user dismissing the modal through the UI. - */ - close(): void; -} diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts index dadb3ec743..b439fc893b 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/pin-pad-api.ts @@ -12,6 +12,8 @@ export interface PinPadApiContent { * * • **When rejected**: Displays the optional `errorMessage` and keeps the modal open. * + * An uncaught error from `onSubmit` rejects the PIN with the raw error text shown to the merchant. Catch errors inside `onSubmit` and return `{result: 'reject', errorMessage}` with a message that's safe to display. + * * Use for implementing secure authentication workflows, access control, or PIN-based verification systems. */ showPinPad( diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts index f95ea29816..eff17890bf 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts @@ -10,12 +10,16 @@ export interface PrintApiContent { * * • A relative path that will be appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration) * - * • A full URL to your app's backend that will be used to return the document to print + * • A full URL to your app's backend that will be used to return the document to print. For API version 2026-07 and later, the URL must be an `https:` URL on the same origin as your app's `application_url` (Shopify-developed apps can also use `https://cdn.shopify.com`). Earlier API versions accept any `http:` or `https:` URL. * - * Returns a promise that resolves when content is ready and the native print dialog appears. Use for printing custom documents, receipts, labels, or reports. + * On Android, a PDF source is downloaded without showing a print dialog. For API version 2026-07 and later, the promise resolves without printing; on earlier API versions the promise rejects instead once POS has handled the file, and a call made while the file is still loading can remain unsettled. + * + * A new print job replaces a previous job that's still being prepared. On API version 2026-07 and later, the replaced job's promise rejects; on earlier API versions, the replaced call can remain unsettled. Content preparation is asynchronous, so jobs aren't necessarily replaced in the order `print()` was called. Serialize `print()` calls when print order matters. + * + * Use for printing custom documents, receipts, labels, or reports. * * @param src the source URL of the content to print. - * @returns Promise that resolves when content is ready and native print dialog appears. + * @returns Promise that resolves when content is ready and the native print dialog appears. On Android, a PDF source resolves after the file downloads, without a print dialog (API version 2026-07 and later; earlier API versions reject instead). */ print(src: string): Promise; } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/printing-api/printing-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/printing-api/printing-api.ts index 3ed54272d2..e34e81c915 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/printing-api/printing-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/printing-api/printing-api.ts @@ -23,6 +23,8 @@ export interface PrintingApiContent { * When no hardware printers are available, returns an empty array. * The system print dialog is not included in this list — it is the * default behavior when no `printer` option is provided to `print()`. + * POS currently exposes at most one hardware printer: the default + * connected receipt printer. * * @see {@link https://github.com/WICG/web-printing | WICG Web Printing} * for the emerging web standard this aligns with. @@ -36,27 +38,37 @@ export interface PrintingApiContent { * When called without a `printer` option, opens the device's system * print dialog (e.g., AirPrint on iOS, Android print service). When * a `printer` reference is provided (from `getPrinters()`), sends - * the content directly to that printer without showing a dialog. + * the content directly to the current default receipt printer without + * showing a dialog. POS doesn't validate the specific printer identity. * * The `src` parameter accepts either: * - A relative path that will be appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration) - * - A full URL to your app's backend + * - A full URL to your app's backend. The URL must be an `https:` URL on the same origin as your app's `application_url` (Shopify-developed apps can also use `https://cdn.shopify.com`) * * The content at the URL is fetched with the extension's session token * for authentication. HTML, PDFs, and images are supported content types. - * PDFs can only be printed via the system print dialog: selecting a + * PDFs are handled per platform: on iOS they print through the system + * print dialog; on Android, POS downloads the PDF without showing a + * print dialog and the promise resolves without printing. Selecting a * `printer` with a PDF `src` throws, because hardware (receipt) printers * render HTML and image content only. * + * A new print job replaces a previous job that's still being prepared, + * and the replaced job's promise rejects. Content preparation is + * asynchronous, so jobs aren't necessarily replaced in the order + * `print()` was called. Serialize `print()` calls when print order + * matters. + * * @param src the source URL of the content to print. * @param options optional configuration for the print operation. * @returns A promise that resolves when the print job has been - * successfully sent. For hardware printers, this means the rasterized - * content has been dispatched — it does not wait for physical printing + * successfully sent. For hardware printers, this means the content has + * been sent to the printer bridge — it does not wait for physical printing * to complete. For the system print dialog, this resolves when the - * content is ready and the dialog appears. + * content is ready and the dialog appears. On Android, a PDF source + * resolves after the file downloads, without a print dialog. * @throws {Error} when the content cannot be fetched from `src`. - * @throws {Error} when the specified `printer` is not connected. + * @throws {Error} when a `printer` is selected but no receipt printer is connected. * @throws {Error} when `src` is a PDF and a `printer` is selected, since * receipt printers render HTML and image content only. */ @@ -70,8 +82,10 @@ export interface PrintingApiContent { export interface PrintOptions { /** * A printer reference obtained from `getPrinters()`. When provided, - * the print job is sent directly to this printer without showing - * a system print dialog. + * the print job is sent directly to the current default receipt printer + * without showing a system print dialog. POS doesn't validate the + * printer's identity; the job fails if no receipt printer is connected + * when it runs. * * When omitted, the system print dialog is shown, allowing the * user to select a printer and configure print settings. diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts index dde9d6fc35..7da7d4df56 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts @@ -47,7 +47,9 @@ export interface ProductSearchParams extends PaginationParams { */ export interface ProductSearchApiContent { /** - * Searches for products on the POS device using text queries and sorting options. Returns paginated results with up to 50 products per page. When a query string is provided, results are sorted by relevance. Use for implementing custom search interfaces, product discovery features, or filtered product listings. + * Searches for products using text queries and sorting options. Returns paginated results with up to 50 products per page. When a query string is provided, results are sorted by relevance. Use for implementing custom search interfaces, product discovery features, or filtered product listings. + * + * POS reads from the catalog source it selects. When POS reads from the local catalog, results are limited to products synchronized to the device; remote reads can access the remote catalog. When POS uses the remote catalog source, a failed search can resolve as an empty page, so an empty result isn't proof that the read succeeded. The returned promise can also reject, for example when arguments have the wrong type or a local read fails. Handle rejections around your calls. * * @param searchParams The parameters for the product search. */ @@ -56,7 +58,7 @@ export interface ProductSearchApiContent { ): Promise>; /** - * Retrieves detailed information for a single product by its ID. Returns `undefined` if the product doesn't exist or isn't available on the POS device. Use for displaying product details, validating product availability, or building product-specific workflows. + * Retrieves detailed information for a single product by its ID. Returns `undefined` if the product doesn't exist or isn't available in the catalog source POS reads from. Use for displaying product details, validating product availability, or building product-specific workflows. * * @param productId The ID of the product to lookup. */ diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts index 0e2851caaf..ee12850fae 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/session-api/session-api.ts @@ -11,11 +11,13 @@ export interface SessionApiContent { */ currentSession: Session; /** - * Provides read-only access to the staff member currently pinned into POS and allows subscribing to staff member changes. The value is `undefined` when no staff member is pinned in. + * Provides read-only access to the staff member currently pinned into POS and allows subscribing to staff member changes. The value is `undefined` when no staff member is pinned in, or while the pinned staff member is still loading. */ staffMember: ReadonlySignalLike; /** - * Generates a fresh session token for secure communication with your app's backend service. Returns `undefined` when the authenticated user lacks proper app permissions. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member. + * Generates a fresh session token for secure communication with your app's backend service. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member. + * + * Returns `undefined` when the token can't be minted, such as when the authenticated user lacks proper app permissions, the token service returns an empty response, or the request times out or fails. The promise can still reject on transport or lifecycle errors. Treat any falsy resolved value as a failure. */ getSessionToken: () => Promise; /** @@ -25,7 +27,7 @@ export interface SessionApiContent { * * @example 123456 * @see [Global IDs documentation](https://shopify.dev/docs/api/usage/gids) for more about GID format and structure - * @see [device.getDeviceId()](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/device-api) for physical device identifier (UUID format) + * @see [device.getDeviceId()](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/device-api) for the physical device identifier string */ deviceId: number; } 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 d45368682b..a257aa3aac 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 @@ -3493,7 +3493,6 @@ interface CallbackEvent { declare const tagName$K = 's-badge'; /** * Displays compact status text with optional semantic tone. - * @publicDocs */ interface BadgeJSXProps extends Pick { /** @@ -3526,7 +3525,6 @@ declare module 'preact' { declare const tagName$J = 's-banner'; /** * Shows prominent status and messaging content with optional actions. - * @publicDocs */ interface BannerJSXProps extends Pick { /** @@ -3576,7 +3574,6 @@ declare const tagName$I = 's-box'; type PaddingKeyword$2 = SizeKeyword | 'none'; /** * Provides a generic layout container with sizing and spacing controls. - * @publicDocs */ interface BoxJSXProps { /** @@ -3711,7 +3708,6 @@ declare module 'preact' { declare const tagName$H = 's-button'; /** * Triggers actions when selected by the merchant. - * @publicDocs */ interface ButtonJSXProps extends Pick< @@ -3776,7 +3772,6 @@ declare module 'preact' { declare const tagName$G = 's-choice'; /** * Represents a selectable option within a choice list. - * @publicDocs */ interface ChoiceJSXProps extends Pick { @@ -3818,7 +3813,6 @@ declare module 'preact' { declare const tagName$F = 's-choice-list'; /** * Groups one or more selectable choices. - * @publicDocs */ interface ChoiceListJSXProps extends Pick { @@ -3867,7 +3861,6 @@ declare module 'preact' { declare const tagName$E = 's-clickable'; /** * Makes contained content interactive and clickable. - * @publicDocs */ interface ClickableJSXProps extends Pick { /** @@ -3895,7 +3888,6 @@ declare module 'preact' { declare const tagName$D = 's-date-field'; /** * Collects date input as text. - * @publicDocs */ interface DateFieldJSXProps extends Pick< @@ -3947,8 +3939,7 @@ declare module 'preact' { declare const tagName$C = 's-date-picker'; /** - * Lets merchants select one or more dates from a calendar. - * @publicDocs + * Lets merchants select a date from a calendar. */ interface DatePickerJSXProps extends Pick { /** @@ -4006,7 +3997,6 @@ declare module 'preact' { declare const tagName$B = 's-date-spinner'; /** * Lets merchants select a date using spinner controls. - * @publicDocs */ interface DateSpinnerJSXProps extends Pick { /** @@ -4061,7 +4051,6 @@ declare module 'preact' { declare const tagName$A = 's-divider'; /** * Displays a visual separator between content sections. - * @publicDocs */ interface DividerJSXProps extends Pick {} declare global { @@ -4079,8 +4068,7 @@ declare module 'preact' { declare const tagName$z = 's-email-field'; /** - * Collects and validates email address input. - * @publicDocs + * Collects email address input. */ interface EmailFieldJSXProps$1 extends Pick< @@ -4140,7 +4128,6 @@ declare module 'preact' { declare const tagName$y = 's-heading'; /** * Displays heading text for grouping and hierarchy. - * @publicDocs */ interface HeadingJSXProps extends Pick { /** @@ -4292,7 +4279,6 @@ type SupportedIconNames = Extract< >; /** * Displays a predefined icon glyph. - * @publicDocs */ interface IconJSXProps extends Pick { @@ -4319,7 +4305,6 @@ declare module 'preact' { declare const tagName$w = 's-image'; /** * Displays an image with sizing and fit controls. - * @publicDocs */ interface ImageJSXProps$1 extends Pick { /** @@ -4365,8 +4350,7 @@ declare const tagName$v = 's-modal'; * * Modals block interaction with the underlying interface until the merchant resolves the modal content. * - * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/feedback-and-status-indicators/modal#events). - * @publicDocs + * Modals don't automatically handle state management or persistence, so control visibility programmatically with the `command` and `commandFor` attributes. The events notify your code when the modal starts to show or hide. */ interface ModalJSXProps extends Pick { /** @@ -4386,7 +4370,7 @@ interface ModalJSXProps extends Pick { /** * The primary action button displayed in the modal. * - * The tone of the button is used to define the tone of the modal. + * Setting the button's tone to `critical` presents the modal with destructive styling for irreversible actions; other tones don't change the modal's appearance. * * If omitted, the modal uses the default tone and shows a 'Close' button, translated according to the user's locale. */ @@ -4417,7 +4401,6 @@ declare module 'preact' { declare const tagName$u = 's-number-field'; /** * Collects numeric input with optional stepper controls. - * @publicDocs */ interface NumberFieldJSXProps extends Pick< @@ -4565,7 +4548,6 @@ declare module 'preact' { declare const tagName$t = 's-page'; /** * Provides the top-level page layout for extension content. - * @publicDocs */ interface PageJSXProps extends Pick { /** @@ -4608,7 +4590,6 @@ declare module 'preact' { declare const tagName$s = 's-pos-block'; /** * Displays content in a POS block container with optional heading. - * @publicDocs */ interface PosBlockJSXProps extends Pick { /** @@ -4654,7 +4635,6 @@ type PaddingKeyword$1 = SizeKeyword | 'none'; declare const tagName$q = 's-scroll-box'; /** * Provides a scrollable container for overflowing content. - * @publicDocs */ interface ScrollBoxJSXProps extends Pick { /** @@ -4785,7 +4765,6 @@ declare module 'preact' { declare const tagName$p = 's-search-field'; /** * Collects search queries for filtering and lookup workflows. - * @publicDocs */ interface SearchFieldJSXProps extends Pick { @@ -4830,7 +4809,6 @@ declare module 'preact' { declare const tagName$o = 's-section'; /** * Groups related content into a titled section. - * @publicDocs */ interface SectionJSXProps extends Pick { /** @@ -4883,7 +4861,6 @@ type PickedProps = Pick< >; /** * Arranges children in a horizontal or vertical stack. - * @publicDocs */ interface StackJSXProps extends PickedProps { /** @@ -5071,7 +5048,6 @@ declare module 'preact' { declare const tagName$m = 's-text'; /** * Renders styled textual content. - * @publicDocs */ interface TextJSXProps extends Pick { /** @@ -5118,7 +5094,6 @@ declare module 'preact' { declare const tagName$l = 's-text-area'; /** * Collects multi-line text input from the merchant. - * @publicDocs */ interface TextAreaJSXProps$1 extends Pick< @@ -5188,7 +5163,6 @@ declare module 'preact' { declare const tagName$k = 's-text-field'; /** * Collects single-line text input. - * @publicDocs */ interface TextFieldJSXProps extends Pick< @@ -5248,7 +5222,6 @@ declare module 'preact' { declare const tagName$j = 's-tile'; /** * Displays tappable content in a compact tile layout. - * @publicDocs */ interface TileJSXProps extends Pick< @@ -5282,7 +5255,6 @@ declare module 'preact' { declare const tagName$i = 's-time-field'; /** * Collects a time value. - * @publicDocs */ interface TimeFieldJSXProps extends Pick< @@ -5335,7 +5307,6 @@ declare module 'preact' { declare const tagName$h = 's-time-picker'; /** * Lets merchants select a time from a picker. - * @publicDocs */ interface TimePickerJSXProps extends Pick { /** @@ -5395,7 +5366,6 @@ declare const tagName$g = 's-link'; * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content. * * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/actions/button) instead. - * @publicDocs */ interface LinkJSXProps extends Pick< @@ -5414,7 +5384,6 @@ interface LinkJSXProps /** * Displays an empty-state message with optional actions and supporting graphics. - * @publicDocs */ interface EmptyStateJSXProps extends Pick { /** @@ -5444,10 +5413,9 @@ interface EmptyStateJSXProps extends Pick { * * - **HTML documents** (`text/html`) - Receipts, invoices, and formatted reports with CSS styling and embedded images. * - **Text files** (`text/plain`) - Plain text content such as simple receipts and data exports. - * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. PDF handling varies by platform; on Android, PDF content is downloaded and opened in an external viewer. + * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. On Android, the component shows a placeholder instead of a PDF preview. * * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). - * @publicDocs */ interface EmbedJSXProps extends Pick< @@ -5502,7 +5470,6 @@ interface EmbedJSXProps /** * Displays a loading indicator while content or actions are in progress. - * @publicDocs */ interface SpinnerJSXProps extends Pick {} @@ -5510,7 +5477,6 @@ interface SpinnerJSXProps declare const tagName$f = 's-switch'; /** * Allows merchants to toggle a setting on or off. - * @publicDocs */ interface SwitchJSXProps extends Pick< @@ -5567,7 +5533,6 @@ interface SwitchJSXProps declare const tagName$e = 's-tabs'; /** * Groups related content into selectable tabbed views. - * @publicDocs */ interface TabsJSXProps extends Pick { @@ -5596,7 +5561,6 @@ interface TabsJSXProps /** * Presents the list of selectable tabs within a tabs component. Accepts only tab components as children. - * @publicDocs */ interface TabListJSXProps extends Pick { children?: ComponentChildren; @@ -5604,7 +5568,6 @@ interface TabListJSXProps extends Pick { /** * Represents an individual tab inside a tabs component. - * @publicDocs */ interface TabJSXProps extends Pick { children?: StringChildren; @@ -5612,7 +5575,6 @@ interface TabJSXProps extends Pick { /** * Represents content associated with a selected tab. - * @publicDocs */ interface TabPanelJSXProps extends Pick { children?: ComponentChildren; @@ -5621,7 +5583,6 @@ interface TabPanelJSXProps extends Pick { declare const tagName$d = 's-text-area'; /** * Collects multi-line text input from the merchant. - * @publicDocs */ interface TextAreaJSXProps extends Pick< @@ -5673,8 +5634,7 @@ interface TextAreaJSXProps declare const tagName$c = 's-email-field'; /** - * Collects and validates email address input. - * @publicDocs + * Collects email address input. */ interface EmailFieldJSXProps extends Pick< @@ -5716,7 +5676,6 @@ interface EmailFieldJSXProps /** * Displays an image with sizing and fit controls. - * @publicDocs */ interface ImageJSXProps extends Pick { /** @@ -5984,7 +5943,7 @@ export type { */ interface ButtonEvents { /** Called when the button is activated. */ - click?: (event: CallbackEvent) => void; + click?: ((event: CallbackEvent) => void) | undefined; } /** @@ -6004,38 +5963,38 @@ interface Button { * @default '--auto' * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ - command?: '--auto' | '--show' | '--hide' | '--toggle'; + command?: '--auto' | '--show' | '--hide' | '--toggle' | undefined; /** * Sets the tone of the Button, based on the intention of the information being conveyed. * @default 'auto' */ - tone?: 'auto' | 'neutral' | 'caution' | 'warning' | 'critical'; + tone?: 'auto' | 'neutral' | 'caution' | 'warning' | 'critical' | undefined; /** * Changes the visual appearance of the Button. * @default 'auto' */ - variant?: 'auto' | 'primary' | 'secondary'; + variant?: 'auto' | 'primary' | 'secondary' | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Disables the Button meaning it cannot be clicked or receive focus. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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 ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor */ - commandFor?: string; + commandFor?: string | undefined; /** * Replaces content with a loading indicator while a background action is being performed. * * This also disables the Button. * @default false */ - loading?: boolean; + loading?: boolean | undefined; } /** @@ -6047,14 +6006,14 @@ interface Text { * Modify the color to be more or less intense. * @default 'base' */ - color?: ColorKeyword; + color?: ColorKeyword | undefined; /** * Provide semantic meaning and default styling to the text. * * Other presentation properties on Text override the default styling. * @default 'generic' */ - type?: 'strong' | 'small' | 'generic'; + type?: 'strong' | 'small' | 'generic' | undefined; /** * Sets the tone of the component, based on the intention of the information being conveyed. * @default 'auto' @@ -6066,9 +6025,10 @@ interface Text { | 'success' | 'caution' | 'warning' - | 'critical'; + | 'critical' + | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -6080,32 +6040,32 @@ interface ScrollBox { * Adjust the block size. * @default 'auto' */ - blockSize?: SizeUnitsOrAuto; + blockSize?: SizeUnitsOrAuto | undefined; /** * Adjust the inline size. * @default 'auto' */ - inlineSize?: SizeUnitsOrAuto; + inlineSize?: SizeUnitsOrAuto | undefined; /** * Adjust the maximum block size. * @default 'none' */ - maxBlockSize?: SizeUnitsOrNone; + maxBlockSize?: SizeUnitsOrNone | undefined; /** * Adjust the maximum inline size. * @default 'none' */ - maxInlineSize?: SizeUnitsOrNone; + maxInlineSize?: SizeUnitsOrNone | undefined; /** * Adjust the minimum block size. * @default '0' */ - minBlockSize?: SizeUnits; + minBlockSize?: SizeUnits | undefined; /** * Adjust the minimum inline size. * @default '0' */ - minInlineSize?: SizeUnits; + minInlineSize?: SizeUnits | undefined; /** * Adjust the padding of all edges. * @@ -6123,7 +6083,7 @@ interface ScrollBox { * - `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`. * @default 'none' */ - padding?: MaybeAllValuesShorthandProperty; + padding?: MaybeAllValuesShorthandProperty | undefined; /** * Adjust the block-padding. * @@ -6132,21 +6092,24 @@ interface ScrollBox { * This overrides the block value of `padding`. * @default '' - meaning no override */ - paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + paddingBlock?: + | '' + | MaybeTwoValuesShorthandProperty + | undefined; /** * Adjust the block-start padding. * * This overrides the block-start value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockStart?: '' | PaddingKeyword; + paddingBlockStart?: '' | PaddingKeyword | undefined; /** * Adjust the block-end padding. * * This overrides the block-end value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockEnd?: '' | PaddingKeyword; + paddingBlockEnd?: '' | PaddingKeyword | undefined; /** * Adjust the inline padding. * @@ -6155,23 +6118,26 @@ interface ScrollBox { * This overrides the inline value of `padding`. * @default '' - meaning no override */ - paddingInline?: '' | MaybeTwoValuesShorthandProperty; + paddingInline?: + | '' + | MaybeTwoValuesShorthandProperty + | undefined; /** * Adjust the inline-start padding. * * This overrides the inline-start value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineStart?: '' | PaddingKeyword; + paddingInlineStart?: '' | PaddingKeyword | undefined; /** * Adjust the inline-end padding. * * This overrides the inline-end value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineEnd?: '' | PaddingKeyword; + paddingInlineEnd?: '' | PaddingKeyword | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -6180,7 +6146,7 @@ interface ScrollBox { */ interface TileEvents { /** Callback when the Tile is activated. */ - click?: (event: CallbackEvent) => void; + click?: ((event: CallbackEvent) => void) | undefined; } /** @@ -6192,31 +6158,31 @@ interface Tile { * Disables the Tile meaning it cannot be clicked or receive focus. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * A title that describes the content of the Tile. * @default '' */ - heading?: string; + heading?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * A numeric indicator rendered within the Tile (for example, a count or a step number). * * - When provided, the indicator is displayed inside the tile. * - Intended for small integers. It may clamp, truncate, or abbreviate larger values. */ - itemCount?: number; + itemCount?: number | undefined; /** * Sets the tone of the Tile, based on the intention of the information being conveyed. * @default 'auto' */ - tone?: ExtractStrict; + tone?: ExtractStrict | undefined; /** * Supporting text displayed below the heading. * @default '' */ - subheading?: string; + subheading?: string | undefined; } /** @@ -6242,19 +6208,19 @@ interface Banner { * Determines whether the banner is hidden. * @default false */ - hidden?: boolean; + hidden?: boolean | undefined; /** * Sets the tone of the Banner, based on the intention of the information being conveyed. * @default 'auto' */ - tone?: 'auto' | 'info' | 'success' | 'warning' | 'critical'; + tone?: 'auto' | 'info' | 'success' | 'warning' | 'critical' | undefined; /** * The title of the banner. * @default '' */ - heading?: string; + heading?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -6263,37 +6229,37 @@ interface Banner { */ interface Box { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Adjust the block size. * @default 'auto' */ - blockSize?: SizeUnitsOrAuto; + blockSize?: SizeUnitsOrAuto | undefined; /** * Adjust the inline size. * @default 'auto' */ - inlineSize?: SizeUnitsOrAuto; + inlineSize?: SizeUnitsOrAuto | undefined; /** * Adjust the maximum block size. * @default 'none' */ - maxBlockSize?: SizeUnitsOrNone; + maxBlockSize?: SizeUnitsOrNone | undefined; /** * Adjust the maximum inline size. * @default 'none' */ - maxInlineSize?: SizeUnitsOrNone; + maxInlineSize?: SizeUnitsOrNone | undefined; /** * Adjust the minimum block size. * @default '0' */ - minBlockSize?: SizeUnits; + minBlockSize?: SizeUnits | undefined; /** * Adjust the minimum inline size. * @default '0' */ - minInlineSize?: SizeUnits; + minInlineSize?: SizeUnits | undefined; /** * Adjust the padding of all edges. * @@ -6311,7 +6277,7 @@ interface Box { * - `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`. * @default 'none' */ - padding?: MaybeAllValuesShorthandProperty; + padding?: MaybeAllValuesShorthandProperty | undefined; /** * Adjust the block-padding. * @@ -6320,21 +6286,24 @@ interface Box { * This overrides the block value of `padding`. * @default '' - meaning no override */ - paddingBlock?: '' | MaybeTwoValuesShorthandProperty; + paddingBlock?: + | '' + | MaybeTwoValuesShorthandProperty + | undefined; /** * Adjust the block-start padding. * * This overrides the block-start value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockStart?: '' | PaddingKeyword; + paddingBlockStart?: '' | PaddingKeyword | undefined; /** * Adjust the block-end padding. * * This overrides the block-end value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockEnd?: '' | PaddingKeyword; + paddingBlockEnd?: '' | PaddingKeyword | undefined; /** * Adjust the inline padding. * @@ -6343,21 +6312,24 @@ interface Box { * This overrides the inline value of `padding`. * @default '' - meaning no override */ - paddingInline?: '' | MaybeTwoValuesShorthandProperty; + paddingInline?: + | '' + | MaybeTwoValuesShorthandProperty + | undefined; /** * Adjust the inline-start padding. * * This overrides the inline-start value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineStart?: '' | PaddingKeyword; + paddingInlineStart?: '' | PaddingKeyword | undefined; /** * Adjust the inline-end padding. * * This overrides the inline-end value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineEnd?: '' | PaddingKeyword; + paddingInlineEnd?: '' | PaddingKeyword | undefined; } /** @@ -6369,24 +6341,24 @@ interface Icon { * The type of icon to display. * @default '' */ - type?: SupportedIconNames; + type?: SupportedIconNames | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Sets the tone of the icon, based on the intention of the information being conveyed. * @default 'auto' */ - tone?: ToneKeyword; + tone?: ToneKeyword | undefined; /** * Modify the color to be more or less intense. * @default 'base' */ - color?: ColorKeyword; + color?: ColorKeyword | undefined; /** * Adjusts the size of the icon. * @default 'base' */ - size?: SizeKeyword; + size?: SizeKeyword | undefined; } /** @@ -6411,7 +6383,7 @@ interface Stack { * - `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`. * @default 'none' */ - padding?: MaybeAllValuesShorthandProperty; + padding?: MaybeAllValuesShorthandProperty | undefined; /** * Adjust the block-padding. * @@ -6420,21 +6392,23 @@ interface Stack { * This overrides the block value of `padding`. * @default '' - meaning no override */ - paddingBlock?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; + paddingBlock?: + | MaybeTwoValuesShorthandProperty<'' | PaddingKeyword> + | undefined; /** * Adjust the block-start padding. * * This overrides the block-start value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockStart?: '' | PaddingKeyword; + paddingBlockStart?: '' | PaddingKeyword | undefined; /** * Adjust the block-end padding. * * This overrides the block-end value of `paddingBlock`. * @default '' - meaning no override */ - paddingBlockEnd?: '' | PaddingKeyword; + paddingBlockEnd?: '' | PaddingKeyword | undefined; /** * Adjust the inline padding. * @@ -6443,96 +6417,98 @@ interface Stack { * This overrides the inline value of `padding`. * @default '' - meaning no override */ - paddingInline?: MaybeTwoValuesShorthandProperty<'' | PaddingKeyword>; + paddingInline?: + | MaybeTwoValuesShorthandProperty<'' | PaddingKeyword> + | undefined; /** * Adjust the inline-start padding. * * This overrides the inline-start value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineStart?: '' | PaddingKeyword; + paddingInlineStart?: '' | PaddingKeyword | undefined; /** * Adjust the inline-end padding. * * This overrides the inline-end value of `paddingInline`. * @default '' - meaning no override */ - paddingInlineEnd?: '' | PaddingKeyword; + paddingInlineEnd?: '' | PaddingKeyword | undefined; /** * Adjust the block size. * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. * @see ://developer.mozilla.org/en-US/docs/Web/CSS/block-size * @default 'auto' */ - blockSize?: SizeUnitsOrAuto; + blockSize?: SizeUnitsOrAuto | undefined; /** * Adjust the maximum block size. * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size * @default 'none' */ - maxBlockSize?: SizeUnitsOrNone; + maxBlockSize?: SizeUnitsOrNone | undefined; /** * Adjust the maximum inline size. * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. * @see ://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size * @default 'none' */ - maxInlineSize?: SizeUnitsOrNone; + maxInlineSize?: SizeUnitsOrNone | undefined; /** * Adjust the minimum block size. * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size * @default '0' */ - minBlockSize?: SizeUnits; + minBlockSize?: SizeUnits | undefined; /** * Adjust the minimum inline size. * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. * @see ://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size * @default '0' */ - minInlineSize?: SizeUnits; + minInlineSize?: SizeUnits | undefined; /** Aligns the Stack's children along the cross axis. */ - alignItems?: AlignItemsKeyword; + alignItems?: AlignItemsKeyword | undefined; /** Aligns the Stack along the cross axis. */ - alignContent?: AlignContentKeyword; + alignContent?: AlignContentKeyword | undefined; /** * Adjust spacing between elements. * A single value applies to both axes. A pair of values (for example, `large-100 large-500`) sets the block (row) and inline (column) axes respectively, matching the CSS `gap` shorthand order. * @default 'none' */ - gap?: MaybeTwoValuesShorthandProperty; + gap?: MaybeTwoValuesShorthandProperty | undefined; /** * Adjust spacing between elements in the inline axis. This overrides the column value of gap. * @default '' - meaning no override */ - columnGap?: '' | SpacingKeyword; + columnGap?: '' | SpacingKeyword | undefined; /** * Sets how the children are placed within the Stack. This uses logical properties. * @default 'block' * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' */ - direction?: 'block' | 'inline'; + direction?: 'block' | 'inline' | undefined; /** * Adjust the inline size. * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size * @default 'auto' */ - inlineSize?: SizeUnitsOrAuto; + inlineSize?: SizeUnitsOrAuto | undefined; /** * Aligns the Stack along the main axis. * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * @default 'normal' */ - justifyContent?: JustifyContentKeyword; + justifyContent?: JustifyContentKeyword | undefined; /** * Adjust spacing between elements in the block axis. This overrides the row value of gap. * @default '' - meaning no override */ - rowGap?: '' | SpacingKeyword; + rowGap?: '' | SpacingKeyword | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -6551,9 +6527,10 @@ interface Badge { | 'success' | 'caution' | 'warning' - | 'critical'; + | 'critical' + | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -6566,13 +6543,16 @@ interface ChoiceListEvents { * The event's `currentTarget.values` is always an array of selected choice * values, even when `multiple` is `false`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback when the user changes a choice. Fires simultaneously with onInput. * The event's `currentTarget.values` is always an array of selected choice * values; in single-selection mode, only the first entry is rendered as selected. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; } /** @@ -6591,14 +6571,14 @@ interface ChoiceList { * Use a unique `value` for each choice. Choices that share a value can't be * selected independently. */ - values?: string[]; + values?: string[] | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Whether multiple choices can be selected. * @default false */ - multiple?: boolean; + multiple?: boolean | undefined; } /** @@ -6613,7 +6593,7 @@ interface Choice { * A choice needs a `value` to be selectable. Use a unique value for each choice * in the list; choices that share a value can't be selected independently. */ - value?: string; + value?: string | undefined; /** * Whether the choice is selected. * @@ -6621,14 +6601,14 @@ interface Choice { * are combined. * @default false */ - selected?: boolean; + selected?: boolean | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Disables the control, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; } /** @@ -6640,19 +6620,22 @@ interface DateFieldEvents { * Callback when the user confirms a date in the picker. Fires together with * `onChange` at selection time. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback when the user confirms a date in the picker. Fires together with * `onInput` at selection time, not on blur. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** * Callback when the element loses focus. Also fires right after a picker * selection is confirmed, and when the picker is dismissed without a selection. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -6668,11 +6651,11 @@ interface DateField { * dates (for example, `2024-02-30`) currently roll over to a valid date instead * of being rejected. */ - value?: string; + value?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** Content to use as the field label. */ - label?: string; + label?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -6680,17 +6663,17 @@ interface DateField { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + error?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -6698,7 +6681,7 @@ interface DateField { * so with the `error` property. * @default false */ - required?: boolean; + required?: boolean | undefined; } /** @@ -6707,9 +6690,9 @@ interface DateField { */ interface ModalEvents { /** Callback when the modal starts to hide. Fired when a `commandFor` command requests the modal to close, before the closing transition completes. */ - hide?: (event: CallbackEvent) => void | null; + hide?: ((event: CallbackEvent) => void | null) | undefined; /** Callback when the modal starts to show. Fired when a `commandFor` command requests the modal to open, before the opening transition completes. */ - show?: (event: CallbackEvent) => void | null; + show?: ((event: CallbackEvent) => void | null) | undefined; } /** @@ -6720,7 +6703,7 @@ interface ModalSlots { /** * The primary action button displayed in the modal. * - * The tone of the button is used to define the tone of the modal. + * Setting the button's tone to `critical` presents the modal with destructive styling for irreversible actions; other tones don't change the modal's appearance. * * If omitted, the modal uses the default tone and shows a 'Close' button, translated according to the user's locale. */ @@ -6734,7 +6717,7 @@ interface ModalSlots { * * Modals block interaction with the underlying interface until the merchant resolves the modal content. * - * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/feedback-and-status-indicators/modal#events). + * Modals don't automatically handle state management or persistence, so control visibility programmatically with the `command` and `commandFor` attributes. The events notify your code when the modal starts to show or hide. * @publicDocs */ interface Modal { @@ -6743,9 +6726,9 @@ interface Modal { * * Required to control visibility: a button or link with `commandFor` set to this `id` shows, hides, or toggles the modal. */ - id?: string; + id?: string | undefined; /** A title that describes the content of the Modal. */ - heading?: string; + heading?: string | undefined; } /** @@ -6754,16 +6737,19 @@ interface Modal { */ interface TextFieldEvents { /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback after editing completes, on blur or submit. Fires only when the value * changed since the field received focus. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -6785,11 +6771,11 @@ interface TextField { * * Set `value` and update it from `onInput` or `onChange` to control the field. */ - value?: string; + value?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** Content to use as the field label. */ - label?: string; + label?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -6797,19 +6783,19 @@ interface TextField { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; /** A short hint that describes the expected value of the field. */ - placeholder?: string; + placeholder?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + error?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -6817,12 +6803,12 @@ interface TextField { * so with the `error` property. * @default false */ - required?: boolean; + required?: boolean | undefined; /** * Specifies the maximum number of characters allowed. * @default Infinity */ - maxLength?: number; + maxLength?: number | undefined; } /** @@ -6835,13 +6821,16 @@ interface SearchFieldEvents { * string when the user clears the field with the clear button; clearing the field * doesn't fire `onChange`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the field loses focus after the user changes the value in the field. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the field loses focus. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the field is focused. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -6854,16 +6843,16 @@ interface SearchField { * * Set `value` and update it from `onInput` or `onChange` to control the field. */ - value?: string; + value?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** A short hint that describes the expected value of the field. */ - placeholder?: string; + placeholder?: string | undefined; } /** @@ -6872,7 +6861,7 @@ interface SearchField { */ interface ClickableEvents { /** Callback when the element is activated. */ - click?: (event: CallbackEvent) => void; + click?: ((event: CallbackEvent) => void) | undefined; } /** @@ -6881,7 +6870,7 @@ interface ClickableEvents { */ interface Clickable { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Disables the clickable, meaning it cannot be clicked or receive focus. * @@ -6893,7 +6882,7 @@ interface Clickable { * This has no impact on the visual state by default, * but developers are encouraged to style the clickable accordingly. */ - disabled?: boolean; + disabled?: boolean | undefined; } /** @@ -6905,19 +6894,22 @@ interface TimeFieldEvents { * Callback when the user confirms a time in the picker. Fires together with * `onChange` at selection time. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback when the user confirms a time in the picker. Fires together with * `onInput` at selection time, not on blur. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** * Callback when the element loses focus. Also fires right after a picker * selection is confirmed, and when the picker is dismissed without a selection. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -6934,21 +6926,21 @@ interface TimeField { * provided value are ignored. Values are interpreted in the device's local * timezone. The field displays times in 12-hour AM/PM format. */ - value?: string; + value?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** Content to use as the field label. */ - label?: string; + label?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + error?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -6956,7 +6948,7 @@ interface TimeField { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -6964,7 +6956,7 @@ interface TimeField { * so with the `error` property. * @default false */ - required?: boolean; + required?: boolean | undefined; } /** @@ -6976,17 +6968,20 @@ interface NumberFieldEvents { * Callback when the user makes any changes in the field. In stepper mode, fires * on every stepper button tap, together with `onChange`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback after editing completes, on blur or submit. Fires only when the value * changed since the field received focus. In stepper mode, fires on every stepper * button tap, together with `onInput`. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -7014,7 +7009,7 @@ interface NumberField { * In stepper mode the field is always populated: an empty or unparsable value is * treated as `0`. */ - value?: string; + value?: string | undefined; /** * The highest value accepted for the field. * @@ -7022,7 +7017,7 @@ interface NumberField { * finishes and delivers the clamped value through `onInput`. * @default Infinity */ - max?: number; + max?: number | undefined; /** * The lowest value accepted for the field. * @@ -7030,13 +7025,13 @@ interface NumberField { * finishes and delivers the clamped value through `onInput`. * @default -Infinity */ - min?: number; + min?: number | undefined; /** * Content to use as the field label. * * Label is not supported when using Stepper controls */ - label?: string; + label?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -7046,7 +7041,7 @@ interface NumberField { * * Details are not supported when using Stepper controls */ - details?: string; + details?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -7056,14 +7051,14 @@ interface NumberField { * Required is not supported when using Stepper controls * @default false */ - required?: boolean; + required?: boolean | undefined; /** * 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 is not supported when using Stepper controls */ - error?: string; + error?: string | undefined; /** * Sets the virtual keyboard. * @@ -7071,13 +7066,13 @@ interface NumberField { * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode * @default 'decimal' */ - inputMode?: 'decimal' | 'numeric'; + inputMode?: 'decimal' | 'numeric' | undefined; /** * A short hint that describes the expected value of the field. * * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones. */ - placeholder?: string; + placeholder?: string | undefined; /** * Sets the type of controls displayed for the field. * @@ -7089,14 +7084,14 @@ interface NumberField { * - `auto`: the presence of the controls depends on the surface and context. * @default 'auto' */ - controls?: 'auto' | 'stepper' | 'none'; + controls?: 'auto' | 'stepper' | 'none' | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; } /** @@ -7105,17 +7100,20 @@ interface NumberField { */ interface DatePickerEvents { /** Callback when the user selects a date from the picker. Fires after `onChange`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the user selects a date from the picker that is different to the current value. Fires before `onInput`. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the date picker is dismissed. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the date picker is revealed. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** - * Lets merchants select one or more dates from a calendar. + * Lets merchants select a date from a calendar. * @publicDocs */ interface DatePicker { @@ -7127,7 +7125,7 @@ interface DatePicker { * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't * be shown. */ - id?: string; + id?: string | undefined; /** * The current selected value. * @@ -7139,7 +7137,7 @@ interface DatePicker { * `2024-02-30`) currently roll over to a valid date instead of being rejected. * @default "" */ - value?: string; + value?: string | undefined; } /** @@ -7148,13 +7146,16 @@ interface DatePicker { */ interface DateSpinnerEvents { /** Callback when the user makes a selection. Fires after `onChange`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the value changes. Only called when a different value is selected. Fires before `onInput`. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the date spinner is dismissed. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the date spinner is revealed. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -7170,7 +7171,7 @@ interface DateSpinner { * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't * be shown. */ - id?: string; + id?: string | undefined; /** * The current selected value for the spinner, as a date in `YYYY-MM-DD` format. * @@ -7179,7 +7180,7 @@ interface DateSpinner { * `2024-02-30`) currently roll over to a valid date instead of being rejected. * @default "" */ - value?: string; + value?: string | undefined; } /** @@ -7201,9 +7202,9 @@ interface Section { * * If omitted, and no secondaryActions are provided, the section will be rendered without a header. */ - heading?: string; + heading?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -7212,7 +7213,7 @@ interface Section { */ interface Heading { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -7221,13 +7222,16 @@ interface Heading { */ interface TimePickerEvents { /** Callback when the user selects a time from the picker. Fires after `onChange`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the user selects a time from the picker that is different to the current value. Fires before `onInput`. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the time picker is dismissed. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the time picker is revealed. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -7243,7 +7247,7 @@ interface TimePicker { * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't * be shown. */ - id?: string; + id?: string | undefined; /** * The current selected value. * @@ -7255,7 +7259,7 @@ interface TimePicker { * interpreted in the device's local timezone. * @default '' */ - value?: string; + value?: string | undefined; } /** @@ -7276,14 +7280,14 @@ interface Image { * @default 'fill' * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width */ - inlineSize?: 'fill' | 'auto'; + inlineSize?: 'fill' | 'auto' | undefined; /** * The image source, which should be a remote URL. * * When no `src` is provided or the image fails to load, a placeholder is rendered. * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src */ - src?: string; + src?: string | undefined; /** * Border radius for the image corners. * @@ -7305,16 +7309,18 @@ interface Image { * - Special values: `max`, `none` * @default 'none' */ - borderRadius?: MaybeAllValuesShorthandProperty; + borderRadius?: + | MaybeAllValuesShorthandProperty + | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * 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 ://developer.mozilla.org/en-US/docs/Web/CSS/object-fit */ - objectFit?: 'contain' | 'cover'; + objectFit?: 'contain' | 'cover' | undefined; /** * 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 @@ -7331,7 +7337,7 @@ interface Image { * @default `''` * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt */ - alt?: string; + alt?: string | undefined; } /** @@ -7354,11 +7360,11 @@ interface Page { * The main page heading, displayed in the action bar at the top of the page. * @default : '' */ - heading?: string; + heading?: string | undefined; /** A secondary page heading, displayed under the main heading in the action bar. */ - subheading?: string; + subheading?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; } /** @@ -7376,25 +7382,25 @@ interface PosBlockSlots { */ interface PosBlock { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * The heading to display within the POSBlock. * * If not provided, the description of the extension will be used when a heading is appropriate. */ - heading?: string; + heading?: string | undefined; } /** @private */ interface QrCode { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * The content to be encoded in the QR code, which can be any string such as a URL, email address, plain text, etc. * Specific string formatting can trigger actions on the user's device when scanned, like opening geolocation * coordinates on a map, opening a preferred app or app store entry, preparing an email, text message, and more. */ - content?: string; + content?: string | undefined; } /** @@ -7403,12 +7409,12 @@ interface QrCode { */ interface Divider { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * 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'; + direction?: 'inline' | 'block' | undefined; } /** @@ -7417,7 +7423,7 @@ interface Divider { */ interface LinkEvents { /** Called when the link is activated. */ - click?: (event: CallbackEvent) => void; + click?: ((event: CallbackEvent) => void) | undefined; } /** @@ -7428,14 +7434,14 @@ interface LinkEvents { */ interface Link { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * 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 ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor */ - commandFor?: string; + commandFor?: string | undefined; /** * Sets the action the `commandFor` should take when this clickable is activated. * @@ -7449,14 +7455,14 @@ interface Link { * @default '--auto' * @see ://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ - command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy'; + command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy' | undefined; /** * 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; + accessibilityLabel?: string | undefined; } /** @@ -7478,9 +7484,9 @@ interface EmptyStateSlots { */ interface EmptyState { /** The subheading of the EmptyState. */ - subheading?: string; + subheading?: string | undefined; /** The heading of the EmptyState. */ - heading?: string; + heading?: string | undefined; } /** @@ -7492,7 +7498,7 @@ interface EmptyState { * * - **HTML documents** (`text/html`) - Receipts, invoices, and formatted reports with CSS styling and embedded images. * - **Text files** (`text/plain`) - Plain text content such as simple receipts and data exports. - * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. PDF handling varies by platform; on Android, PDF content is downloaded and opened in an external viewer. + * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. On Android, the component shows a placeholder instead of a PDF preview. * * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). * @publicDocs @@ -7502,37 +7508,37 @@ interface Embed { * Adjust the block size. * @default 'auto' */ - blockSize?: SizeUnitsOrAuto; + blockSize?: SizeUnitsOrAuto | undefined; /** * Adjust the minimum block size. * @default '0' */ - minBlockSize?: SizeUnits; + minBlockSize?: SizeUnits | undefined; /** * Adjust the maximum block size. * @default 'none' */ - maxBlockSize?: SizeUnitsOrNone; + maxBlockSize?: SizeUnitsOrNone | undefined; /** * Adjust the inline size. * @default 'auto' */ - inlineSize?: SizeUnitsOrAuto; + inlineSize?: SizeUnitsOrAuto | undefined; /** * Adjust the minimum inline size. * @default '0' */ - minInlineSize?: SizeUnits; + minInlineSize?: SizeUnits | undefined; /** * Adjust the maximum inline size. * @default 'none' */ - maxInlineSize?: SizeUnitsOrNone; + maxInlineSize?: SizeUnitsOrNone | undefined; /** * The content type of the file to display. * @default 'text/html' */ - type?: 'text/html' | 'text/plain' | 'application/pdf'; + type?: 'text/html' | 'text/plain' | 'application/pdf' | undefined; /** * The source of the file to preview. * @@ -7546,13 +7552,13 @@ interface Embed { * - PDF files * @implementation If this value is omitted, the component should render an empty state or nothing. */ - src?: string; + src?: string | undefined; /** * A label that describes the purpose or contents of the Embed. It will be read to users * using assistive technologies such as screen readers. * @implementation for web-based implementations, this should map to the [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute */ - accessibilityLabel?: string; + accessibilityLabel?: string | undefined; } /** @@ -7561,7 +7567,7 @@ interface Embed { */ interface Spinner { /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** * A label that describes the purpose of the progress. When set, * it will be announced to users using assistive technologies and will @@ -7569,7 +7575,7 @@ interface Spinner { * recommended if there is no accompanying text describing that something * is loading. */ - accessibilityLabel?: string; + accessibilityLabel?: string | undefined; } /** @@ -7581,12 +7587,15 @@ interface SwitchEvents { * Callback when the user toggles the switch. Fires together with `onChange`, * after it. Read the new state from `event.currentTarget.checked`. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback when the user toggles the switch. Fires together with `onInput`; * `onChange` fires first. Read the new state from `event.currentTarget.checked`. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; } /** @@ -7601,7 +7610,7 @@ interface Switch { * element and can be read back in event callbacks; it doesn't affect the switch * state and isn't submitted with any form. */ - value?: string; + value?: string | undefined; /** * Whether the switch is on. * @@ -7610,7 +7619,7 @@ interface Switch { * state, starting from `defaultChecked`. * @default false */ - checked?: boolean; + checked?: boolean | undefined; /** * Whether the switch is on when it first renders. * @@ -7618,19 +7627,19 @@ interface Switch { * ignored. Use `checked` to control the state after the first render. * @default false */ - defaultChecked?: boolean; + defaultChecked?: boolean | undefined; /** * Disables the control, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + accessibilityLabel?: string | undefined; /** Visual content to use as the control label. */ - label?: string; + label?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -7638,12 +7647,12 @@ interface Switch { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; /** * 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; + error?: string | undefined; /** * Changes the visibility of the component's label. * @@ -7651,10 +7660,12 @@ interface Switch { * - `exclusive`: the label is visually hidden but remains in the accessibility tree. * @default 'visible' */ - labelAccessibilityVisibility?: ExtractStrict< - 'visible' | 'hidden' | 'exclusive', - 'visible' | 'exclusive' - >; + labelAccessibilityVisibility?: + | ExtractStrict< + 'visible' | 'hidden' | 'exclusive' | undefined, + 'visible' | 'exclusive' + > + | undefined; } /** @@ -7667,7 +7678,10 @@ interface TabsEvents { * * Fires on every tab selection, including when the current tab is selected again. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; } /** @@ -7681,16 +7695,16 @@ interface Tabs { * This should match the `id` prop of one of the TabPanel components. * When neither `value` nor `defaultValue` is provided, the first rendered tab panel is selected. */ - value?: string; + value?: string | undefined; /** * The default value of the selected tab. * * This should match the `id` prop of one of the TabPanel components. * Sets the initial selected tab in uncontrolled usage. Setting `value` afterwards overrides it. */ - defaultValue?: string; + defaultValue?: string | undefined; /** Disables all tabs and prevents user interaction. */ - disabled?: boolean; + disabled?: boolean | undefined; } /** @@ -7705,12 +7719,12 @@ interface TabList {} */ interface Tab { /** Corresponds to the `id` property of the TabPanel component that will be displayed when selected */ - controls?: string; + controls?: string | undefined; /** * Disables the control, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; } /** @@ -7722,7 +7736,7 @@ interface TabPanel { * The id of the TabPanel used for identification in the Tabs component. * Must match the `controls` prop of the corresponding Tab component. */ - id?: string; + id?: string | undefined; } /** @@ -7731,16 +7745,19 @@ interface TabPanel { */ interface TextAreaEvents { /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback after editing completes, on blur. Fires only when the value * changed since the field received focus. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** @@ -7753,7 +7770,7 @@ interface TextArea { * * Set `value` and update it from `onInput` or `onChange` to control the field. */ - value?: string; + value?: string | undefined; /** * A number of visible text lines. * @@ -7761,11 +7778,11 @@ interface TextArea { * text can be entered. Values are clamped between 1 and 8. * @default 2 */ - rows?: number; + rows?: number | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** Content to use as the field label. */ - label?: string; + label?: string | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -7773,19 +7790,19 @@ interface TextArea { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; /** A short hint that describes the expected value of the field. */ - placeholder?: string; + placeholder?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + error?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -7793,12 +7810,12 @@ interface TextArea { * so with the `error` property. * @default false */ - required?: boolean; + required?: boolean | undefined; /** * Specifies the maximum number of characters allowed. * @default Infinity */ - maxLength?: number; + maxLength?: number | undefined; } /** @@ -7807,20 +7824,23 @@ interface TextArea { */ interface EmailFieldEvents { /** Callback when the user makes any changes in the field. */ - input?: (event: CallbackEvent) => void; + input?: ((event: CallbackEvent) => void) | null | undefined; /** * Callback after editing completes, on blur or submit. Fires only when the value * changed since the field received focus. */ - change?: (event: CallbackEvent) => void; + change?: + | ((event: CallbackEvent) => void) + | null + | undefined; /** Callback when the element loses focus. */ - blur?: (event: CallbackEvent) => void; + blur?: ((event: CallbackEvent) => void) | null | undefined; /** Callback when the element receives focus. */ - focus?: (event: CallbackEvent) => void; + focus?: ((event: CallbackEvent) => void) | null | undefined; } /** - * Collects and validates email address input. + * Collects email address input. * @publicDocs */ interface EmailField { @@ -7829,23 +7849,23 @@ interface EmailField { * * Set `value` and update it from `onInput` or `onChange` to control the field. */ - value?: string; + value?: string | undefined; /** A unique identifier for the element. */ - id?: string; + id?: string | undefined; /** Content to use as the field label. */ - label?: string; + label?: string | undefined; /** A short hint that describes the expected value of the field. */ - placeholder?: string; + placeholder?: string | undefined; /** * Disables the field, disallowing any interaction. * @default false */ - disabled?: boolean; + disabled?: boolean | undefined; /** * 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; + error?: string | undefined; /** * Whether the field needs a value. This requirement adds semantic value * to the field, but it will not cause an error to appear automatically. @@ -7853,12 +7873,12 @@ interface EmailField { * so with the `error` property. * @default false */ - required?: boolean; + required?: boolean | undefined; /** * Specifies the maximum number of characters allowed. * @default Infinity */ - maxLength?: number; + maxLength?: number | undefined; /** * Additional text to provide context or guidance for the field. * This text is displayed along with the field and its label @@ -7866,7 +7886,7 @@ interface EmailField { * * This will also be exposed to screen reader users. */ - details?: string; + details?: string | undefined; } declare module 'react' { namespace JSX { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge.d.ts index d5e2240824..4306ebd06e 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Badge.d.ts @@ -10,52 +10,34 @@ /// import type {BadgeProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-badge'; -/** @publicDocs */ +/** + * Displays compact status text with optional semantic tone. + * @publicDocs + */ export interface BadgeJSXProps extends Pick { /** - * Determines the visual appearance and semantic meaning of the badge. Badges rely on the tone system for semantic meaning, so using custom styling may not clearly convey meaning to merchants. Available options: - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'neutral'` - Gray styling for general status information that doesn't require emphasis. - * - `'info'` - Blue styling for informational content and neutral updates. - * - `'success'` - Green styling for positive states, completed actions, and successful operations. - * - `'caution'` - Yellow styling for situations that need attention but aren't urgent. - * - `'warning'` - Orange styling for important notices that require merchant awareness. - * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -64,13 +46,13 @@ export interface BadgeJSXProps extends Pick { 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution' >; /** - * The child elements to render within this component. + * The content of the Badge. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: BadgeJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner.d.ts index 31e36d27d5..0a6f262b05 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Banner.d.ts @@ -15,57 +15,40 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-banner'; -/** @publicDocs */ +/** + * Shows prominent status and messaging content with optional actions. + * @publicDocs + */ export interface BannerJSXProps extends Pick { /** - * Controls whether the banner is visible or hidden. When set to `true`, the banner will be hidden from view. Use this to programmatically show or hide banners based on application state. Default is `false`. + * Determines whether the banner is hidden. * * @default false */ hidden?: BannerProps['hidden']; /** - * Sets the visual appearance of the banner. The tone determines the color scheme. Available options: - * - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. - * - `'success'` - Green styling for positive outcomes and successful operations. - * - `'info'` - Blue styling for general information and neutral updates. - * - `'warning'` - Orange styling for important notices that require attention. - * - `'critical'` - Red styling for errors and urgent issues requiring immediate action. + * Sets the tone of the Banner, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -74,19 +57,23 @@ export interface BannerJSXProps extends Pick { 'auto' | 'success' | 'info' | 'warning' | 'critical' >; /** - * The primary action element displayed within the banner, typically a button. Use this slot to provide interactive elements that allow users to respond to the banner's message, such as "Dismiss," "Learn More," or "Retry" buttons. + * The primary action for the banner, provided as a button element in the `primary-action` slot. + * + * The POS renderer displays the action only when the slotted button has both text content and an + * `onClick` handler; otherwise the action is dropped. */ primaryAction?: ComponentChild; /** - * The child elements to render within this component. + * The content of the Banner. + * + * The POS renderer currently doesn't render banner children; use `heading` for the message text. */ children?: ComponentChildren; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Box.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Box.d.ts index 3ef8993381..4923a6d757 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Box.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Box.d.ts @@ -19,151 +19,152 @@ import type { Ref, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-box'; +export type PaddingKeyword = SizeKeyword | 'none'; /** - * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system. + * Provides a generic layout container with sizing and spacing controls. * @publicDocs */ -export type PaddingKeyword = SizeKeyword | 'none'; -/** @publicDocs */ export interface BoxJSXProps { /** - * A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features. + * A unique identifier for the element. */ id?: string; /** - * The block size of the container. Auto automatically sizes based on the container's children. + * Adjust the block size. * * @default 'auto' */ blockSize?: SizeUnitsOrAuto; /** - * The inline size of the container. Auto automatically sizes based on the container's children. + * Adjust the inline size. * * @default 'auto' */ inlineSize?: SizeUnitsOrAuto; /** - * The maximum block size constraint for the container. + * Adjust the maximum block size. * * @default 'none' */ maxBlockSize?: SizeUnitsOrNone; /** - * The maximum inline size constraint for the container. + * Adjust the maximum inline size. * * @default 'none' */ maxInlineSize?: SizeUnitsOrNone; /** - * The minimum block size constraint for the container. + * Adjust the minimum block size. * * @default '0' */ minBlockSize?: SizeUnits; /** - * The minimum inline size constraint for the container. + * Adjust the minimum inline size. * * @default '0' */ minInlineSize?: SizeUnits; /** - * 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. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; /** - * 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 */ paddingBlock?: 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?: PaddingKeyword | ''; /** - * 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?: PaddingKeyword | ''; /** - * 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 */ paddingInline?: 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?: PaddingKeyword | ''; /** - * 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?: PaddingKeyword | ''; /** - * The child elements to render within this component. + * The content of the Box. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: BoxJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button.d.ts index b7d5f998e7..f27e2873cd 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Button.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Button.d.ts @@ -10,103 +10,69 @@ /// import type {ButtonProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-button'; -/** @publicDocs */ +/** + * Triggers actions when selected by the merchant. + * @publicDocs + */ export interface ButtonJSXProps extends Pick< ButtonProps, 'id' | 'disabled' | 'command' | 'commandFor' | 'loading' > { /** - * Sets the action the `commandFor` should take when this clickable is activated: - * - `--auto`: A default action for the target component - * - `--show`: Shows the target component - * - `--hide`: Hides the target component - * - `--toggle`: Toggles the target component + * Sets the action the `commandFor` should take when this clickable is activated. + * + * See the documentation of particular components for the actions they support. + * + * - `--auto`: a default action for the target component. + * - `--show`: shows the target component. + * - `--hide`: hides the target component. + * - `--toggle`: toggles the target component. * * @default '--auto' - * Learn more about [button command on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command). + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command */ command?: Extract< ButtonProps['command'], '--auto' | '--show' | '--hide' | '--toggle' >; /** - * Sets the tone of the button, based on the intention of the information being conveyed. - * - * - `'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' */ @@ -115,26 +81,23 @@ export interface ButtonJSXProps 'auto' | 'critical' | 'neutral' | 'warning' | 'caution' >; /** - * Changes the visual appearance of the button. - * - `auto`: Automatically determines the button variant based on its 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. + * Changes the visual appearance of the Button. * * @default 'auto' */ variant?: Extract; /** - * An event that's called when the button is activated. + * Called when the button is activated. */ onClick?: (event: CallbackEvent) => void; /** - * The child elements to render within this component. + * The content of the Button. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: ButtonJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Choice.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Choice.d.ts index 99939f18ac..5dbf192e39 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Choice.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Choice.d.ts @@ -10,49 +10,58 @@ /// import type {ChoiceProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-choice'; -/** @publicDocs */ +/** + * Represents a selectable option within a choice list. + * @publicDocs + */ export interface ChoiceJSXProps extends Pick { + /** + * The value that identifies this choice in the `ChoiceList` `values` prop and + * in selection events. + * + * A choice needs a `value` to be selectable. Use a unique value for each choice + * in the list; choices that share a value can't be selected independently. + */ + value?: ChoiceProps['value']; + /** + * Whether the choice is selected. + * + * Selection can also be set with the `values` prop on the `ChoiceList`; the two + * are combined. + * + * @default false + */ + selected?: ChoiceProps['selected']; + /** + * The content of the choice. + */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: ChoiceJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList.d.ts index 36ff46be19..371bb423b7 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList.d.ts @@ -10,94 +10,78 @@ /// import type {ChoiceListProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-choice-list'; -/** @publicDocs */ +/** + * Groups one or more selectable choices. + * @publicDocs + */ export interface ChoiceListJSXProps extends Pick { /** - * Called when the user changes a choice. Fires simultaneously with `onChange`. + * The values of the selected choices. + * + * When `values` is set, update it from `onChange` or `onInput` to control the + * selection. When `values` is not set, the list manages its own state, starting + * from choices that have `selected` set. Selections from `values` and from + * `selected` choices are combined. + * + * Use a unique `value` for each choice. Choices that share a value can't be + * selected independently. + */ + values?: ChoiceListProps['values']; + /** + * Callback when the user changes a choice. Fires simultaneously with onChange. + * The event's `currentTarget.values` is always an array of selected choice + * values, even when `multiple` is `false`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * Called when the user changes a choice. Fires simultaneously with `onInput`. + * Callback when the user changes a choice. Fires simultaneously with onInput. + * The event's `currentTarget.values` is always an array of selected choice + * values; in single-selection mode, only the first entry is rendered as selected. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * The child elements to render within this component. Should be one or more choice elements. + * The content of the ChoiceList. Should be one or more Choice elements. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: ChoiceListJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable.d.ts index ab5823e185..be39d685c6 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Clickable.d.ts @@ -10,90 +10,58 @@ /// import type {ClickableProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. Returns a number indicating which phase the event is in: 1 (capturing phase), 2 (at target), or 3 (bubbling phase). This helps determine how the event is propagating through the DOM hierarchy. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-clickable'; -/** @publicDocs */ +/** + * Makes contained content interactive and clickable. + * @publicDocs + */ export interface ClickableJSXProps extends Pick { /** - * The callback when the element is activated. + * Callback when the element is activated. */ onClick?: (event: CallbackEvent) => void; /** - * The child elements to render within this component. + * The content of the Clickable. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: ClickableJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField.d.ts index 9cd4d139cc..a0530a51b0 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateField.d.ts @@ -10,103 +10,82 @@ /// import type {DateFieldProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-date-field'; -/** @publicDocs */ +/** + * Collects date input as text. + * @publicDocs + */ export interface DateFieldJSXProps extends Pick< DateFieldProps, - 'id' | 'label' | 'details' | 'value' | 'disabled' | 'error' + 'id' | 'label' | 'details' | 'value' | 'disabled' | 'error' | 'required' > { /** - * Called when the user makes any changes in the field. + * The current value for the field, as a date in `YYYY-MM-DD` format (for + * example, `"2024-05-15"`). If omitted or empty, the field is empty. + * + * Values are interpreted in the device's local timezone. Out-of-range calendar + * dates (for example, `2024-02-30`) currently roll over to a valid date instead + * of being rejected. + */ + value?: DateFieldProps['value']; + /** + * Callback when the user confirms a date in the picker. Fires together with + * `onChange` at selection time. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * Called after editing completes, typically on blur. + * Callback when the user confirms a date in the picker. Fires together with + * `onInput` at selection time, not on blur. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the element loses focus. + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the element receives focus. + * Callback when the element receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker.d.ts index 5dd5084eaa..9203479b6d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DatePicker.d.ts @@ -10,98 +10,88 @@ /// import type {DatePickerProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-date-picker'; -/** @publicDocs */ +/** + * Lets merchants select a date from a calendar. + * @publicDocs + */ export interface DatePickerJSXProps extends Pick { /** - * Called when the user selects a date from the picker. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: DatePickerProps['id']; + /** + * The current selected value. + * + * The default `''` means no date is selected. + * + * The value must be a date in `YYYY-MM-DD` format. Values are interpreted in + * the device's local timezone. Values that can't be parsed as a date are + * treated as no selection; out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * + * @default "" + */ + value?: DatePickerProps['value']; + /** + * Callback when the user selects a date from the picker. Fires after `onChange`. */ - onInput?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Called when the user selects a date from the picker that is different from the current value. + * Callback when the user selects a date from the picker that is different to the current value. Fires before `onInput`. */ - onChange?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the date picker is dismissed or closed. + * Callback when the date picker is dismissed. */ - onBlur?: (event: CallbackEvent) => void | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the date picker is revealed or opened. + * Callback when the date picker is revealed. */ - onFocus?: (event: CallbackEvent) => void | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName]: DatePickerJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner.d.ts index df0776855c..760c3d3c56 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/DateSpinner.d.ts @@ -10,98 +10,85 @@ /// import type {DateSpinnerProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-date-spinner'; -/** @publicDocs */ +/** + * Lets merchants select a date using spinner controls. + * @publicDocs + */ export interface DateSpinnerJSXProps extends Pick { /** - * Called when the user makes a selection in the spinner. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: DateSpinnerProps['id']; + /** + * The current selected value for the spinner, as a date in `YYYY-MM-DD` format. + * + * The default `''` means no date is selected. Values are interpreted in the + * device's local timezone. Out-of-range calendar dates (for example, + * `2024-02-30`) currently roll over to a valid date instead of being rejected. + * + * @default "" + */ + value?: DateSpinnerProps['value']; + /** + * Callback when the user makes a selection. Fires after `onChange`. */ - onInput?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Called when the value changes. Only called when a different value is selected. + * Callback when the value changes. Only called when a different value is selected. Fires before `onInput`. */ - onChange?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the date spinner is dismissed or closed. + * Callback when the date spinner is dismissed. */ - onBlur?: (event: CallbackEvent) => void | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the date spinner is revealed or opened. + * Callback when the date spinner is revealed. */ - onFocus?: (event: CallbackEvent) => void | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName]: DateSpinnerJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider.d.ts index 1b6efdebd7..0f5cc54dd2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Divider.d.ts @@ -10,47 +10,36 @@ /// import type {DividerProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-divider'; -/** @publicDocs */ +/** + * Displays a visual separator between content sections. + * @publicDocs + */ export interface DividerJSXProps extends Pick {} declare global { interface HTMLElementTagNameMap { - [tagName]: DividerJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField.d.ts index 615fd24437..128d45bd93 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmailField.d.ts @@ -8,75 +8,97 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {EmailFieldProps,Key, Ref} from './components-shared.d.ts'; +import type {EmailFieldProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -/** @publicDocs */ -export interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; - detail?: any; - eventPhase: number; - target: HTMLElementTagNameMap[T] | null; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; + eventPhase: number; + target: ElementForTag | null; } -declare const tagName = "s-email-field"; -/** @publicDocs */ -export interface EmailFieldJSXProps extends Pick { - /** - * Callback when the user makes any changes in the field. - */ - onInput?: ((event: CallbackEvent) => void) | null; - /** - * Callback after editing completes (typically on blur). - */ - onChange?: ((event: CallbackEvent) => void) | null; - /** - * Callback when the element loses focus. - */ - onBlur?: ((event: CallbackEvent) => void) | null; - /** - * Callback when the element receives focus. - */ - onFocus?: ((event: CallbackEvent) => void) | null; +declare const tagName$1 = 's-email-field'; +/** + * Collects email address input. + * @publicDocs + */ +export interface EmailFieldJSXProps + extends Pick< + EmailFieldProps, + | 'id' + | 'label' + | 'value' + | 'placeholder' + | 'disabled' + | 'error' + | 'required' + | 'maxLength' + | 'details' + > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: EmailFieldProps['value']; + /** + * Callback when the user makes any changes in the field. + */ + onInput?: ((event: CallbackEvent) => void) | null; + /** + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. + */ + onChange?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element loses focus. + */ + onBlur?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element receives focus. + */ + onFocus?: ((event: CallbackEvent) => void) | null; } -/** @publicDocs */ -export type ElementProps = EmailFieldJSXProps; + +declare const tagName = 's-email-field'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { EmailFieldJSXProps }; +export {tagName}; +export type {EmailFieldJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Embed.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Embed.d.ts index 1dcb8afbd2..e5a4eb3a20 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Embed.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Embed.d.ts @@ -8,83 +8,113 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {EmbedProps,SizeUnitsOrAuto, SizeUnits, SizeUnitsOrNone,Key, Ref} from './components-shared.d.ts'; +import type { + EmbedProps, + SizeUnitsOrAuto, + SizeUnits, + SizeUnitsOrNone, + Key, + Ref, +} from './components-shared.d.ts'; + +/** + * The embed component displays a preview of printable content from a specified source URL. Use it to show merchants what will be printed before triggering the actual print operation. + * + * Embed works in conjunction with the Print API to provide complete print functionality from preview to execution. + * + * The supported document types are the content types accepted by the `type` property: + * + * - **HTML documents** (`text/html`) - Receipts, invoices, and formatted reports with CSS styling and embedded images. + * - **Text files** (`text/plain`) - Plain text content such as simple receipts and data exports. + * - **PDF files** (`application/pdf`) - Complex documents and compliance requirements. On Android, the component shows a placeholder instead of a PDF preview. + * + * [Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension). + * @publicDocs + */ +export interface EmbedJSXProps + extends Pick< + EmbedProps, + | 'type' + | 'src' + | 'accessibilityLabel' + | 'blockSize' + | 'minBlockSize' + | 'maxBlockSize' + | 'inlineSize' + | 'minInlineSize' + | 'maxInlineSize' + > { + /** + * Adjust the block size. + * + * @default 'auto' + */ + blockSize?: SizeUnitsOrAuto; + /** + * Adjust the minimum block size. + * + * @default '0' + */ + minBlockSize?: SizeUnits; + /** + * Adjust the maximum block size. + * + * @default 'none' + */ + maxBlockSize?: SizeUnitsOrNone; + /** + * Adjust the inline size. + * + * @default 'auto' + */ + inlineSize?: SizeUnitsOrAuto; + /** + * Adjust the minimum inline size. + * + * @default '0' + */ + minInlineSize?: SizeUnits; + /** + * Adjust the maximum inline size. + * + * @default 'none' + */ + maxInlineSize?: SizeUnitsOrNone; +} -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -declare const tagName = "s-embed"; -/** @publicDocs */ -export interface EmbedJSXProps extends Pick { - /** - * Adjust the block size. - * - * @default 'auto' - */ - blockSize?: SizeUnitsOrAuto; - /** - * Adjust the minimum block size. - * - * @default '0' - */ - minBlockSize?: SizeUnits; - /** - * Adjust the maximum block size. - * - * @default 'none' - */ - maxBlockSize?: SizeUnitsOrNone; - /** - * Adjust the inline size. - * - * @default 'auto' - */ - inlineSize?: SizeUnitsOrAuto; - /** - * Adjust the minimum inline size. - * - * @default '0' - */ - minInlineSize?: SizeUnits; - /** - * Adjust the maximum inline size. - * - * @default 'none' - */ - maxInlineSize?: SizeUnitsOrNone; -} +declare const tagName = 's-embed'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { EmbedJSXProps }; +export {tagName}; +export type {EmbedJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmptyState.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmptyState.d.ts index 2461b0b27c..431e7119a1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/EmptyState.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/EmptyState.d.ts @@ -10,16 +10,37 @@ /// import type { EmptyStateProps, + ComponentChild, Key, Ref, - ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ +/** + * Displays an empty-state message with optional actions and supporting graphics. + * @publicDocs + */ +export interface EmptyStateJSXProps extends Pick { + /** + * The subheading of the EmptyState. + */ + subheading?: string; + /** + * The primary action to perform, provided as a button or link type element. + */ + primaryAction?: ComponentChild; + /** + * The secondary actions to perform, provided as button or link type elements. + */ + secondaryActions?: ComponentChild; + /** + * The graphic to display in the EmptyState. The only supported component is `Icon`, with a type of `alert-circle`, `search`, or `info`. + */ + graphic?: ComponentChild; +} + export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { key?: Key; @@ -28,52 +49,25 @@ export interface BaseElementProps { } /** * Used when an element has children. - * @publicDocs */ export interface BaseElementPropsWithChildren extends BaseElementProps { children?: ComponentChildren; } -/** @publicDocs */ export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-empty-state'; -/** @publicDocs */ -export interface EmptyStateJSXProps extends Pick { - /** - * The subheading of the empty state. - */ - subheading?: string; - /** - * The primary action to perform, provided as a button or link type element. - */ - primaryAction?: ComponentChild; - /** - * The secondary actions to perform, provided as button or link type elements. - */ - secondaryActions?: ComponentChild; - /** - * The graphic to display in the empty state. The only supported components is icon, with a type of `alert-circle`, `search`, `info`, or `circle-info`. - */ - graphic?: ComponentChild; -} -/** @publicDocs */ -export type ElementProps = Omit< - EmptyStateJSXProps, - 'primaryAction' | 'secondaryActions' | 'graphic' ->; declare global { interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { namespace createElement.JSX { interface IntrinsicElements { - [tagName]: IntrinsicElementProps; + [tagName]: IntrinsicElementProps; } } } diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading.d.ts index eec84417e2..7b2c9c2ac0 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Heading.d.ts @@ -10,51 +10,40 @@ /// import type {HeadingProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The content of the heading, typically text that describes the section or page it introduces. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-heading'; -/** @publicDocs */ +/** + * Displays heading text for grouping and hierarchy. + * @publicDocs + */ export interface HeadingJSXProps extends Pick { /** - * The content of the heading, typically text that describes the section or page it introduces. + * The content of the Heading. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: HeadingJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon.d.ts index 799b5dab8a..a9c7701f6f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Icon.d.ts @@ -10,45 +10,27 @@ /// import type {IconProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-icon'; -/** - * Lists all currently supported icon names available for use in the POS interface. Reference this list when selecting icons to ensure compatibility and availability. - * @publicDocs - */ export type SupportedIconNames = Extract< IconProps['type'], | 'alert-circle' @@ -177,7 +159,10 @@ export type SupportedIconNames = Extract< | 'x' | 'x-circle' >; -/** @publicDocs */ +/** + * Displays a predefined icon glyph. + * @publicDocs + */ export interface IconJSXProps extends Pick { /** @@ -189,7 +174,7 @@ export interface IconJSXProps } declare global { interface HTMLElementTagNameMap { - [tagName]: IconJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Image.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Image.d.ts index 5970f66cf5..942ceb930a 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Image.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Image.d.ts @@ -9,61 +9,41 @@ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// import type { - BorderRadiusKeyword, ImageProps, - Key, + BorderRadiusKeyword, MaybeAllValuesShorthandProperty, + Key, Ref, } from './components-shared.d.ts'; -/** @publicDocs */ -export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. + * Displays an image with sizing and fit controls. * @publicDocs */ -export interface BaseElementProps { +export interface ImageJSXProps + extends Pick { /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ - key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ - ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ - slot?: Lowercase; -} -/** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs - */ -export interface BaseElementPropsWithChildren - extends BaseElementProps { - /** - * The child elements to render within this component. - */ - children?: ComponentChildren; -} -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; - -declare const tagName = 's-image'; -/** @publicDocs */ -export interface ImageJSXProps extends Pick { - /** - * 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. + * + * - `fill`: the image will take up 100% of the available inline size. + * - `auto`: the image is displayed in a square (1:1 aspect ratio) container at the full available + * inline size. The POS translator doesn't render the image at its natural size. * - * - `'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. + * **Mobile surfaces:** Always wrap your image in a box with a set width and height. + * ScrollViews on mobile have a dynamic height, which can cause images to appear + * inconsistently without defined dimensions. * * @default 'fill' + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width */ inlineSize?: ImageProps['inlineSize']; /** - * 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, which should be a remote URL. + * + * When no `src` is provided or the image fails to load, a placeholder is rendered. + * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src */ src?: ImageProps['src']; /** @@ -72,23 +52,49 @@ export interface ImageJSXProps extends Pick { * [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 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) end-end` - * - 2 values: `(start-start & end-end) (start-end & end-start)` + * - 4 values: `start-start inline-end end-end inline-start` + * - 3 values: `start-start inline end-end` + * - 2 values: `block inline` * * For example: * - `base` means all corners have `base` radius - * - `base none` means start-start and end-end corners are `base`, start-end and end-start corners are `none` - * - `base none large` means start-start is `base`, start-end and end-start are `none`, end-end is `large` - * - `base none large small` means start-start is `base`, start-end is `none`, end-end is `large`, end-start is `small` + * - `base none` means start-start and end-end corners are `base`, inline-end and inline-start corners are `none` + * - `base none large` means start-start is `base`, inline-end and inline-start are `none`, end-end is `large` + * - `base none large small` means start-start is `base`, inline-end is `none`, end-end is `large`, inline-start is `small` + * + * Supports size keywords from the design system scale: + * - Size scale: `small-500`, `small-400`, `small-300`, `small-200`, `small-100`, `small`, `base`, `large`, `large-100`, `large-200`, `large-300`, `large-400`, `large-500` + * - Special values: `max`, `none` * * @default 'none' */ borderRadius?: MaybeAllValuesShorthandProperty; } + +export type ComponentChildren = any; +/** + * Used when an element does not have children. + */ +export interface BaseElementProps { + key?: Key; + ref?: Ref; + slot?: Lowercase; +} +/** + * Used when an element has children. + */ +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; +} +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; + +declare const tagName = 's-image'; declare global { interface HTMLElementTagNameMap { - [tagName]: ImageJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Link.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Link.d.ts index aa7225c1d3..6c58495653 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Link.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Link.d.ts @@ -8,65 +8,76 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {LinkProps,Key, Ref} from './components-shared.d.ts'; +import type {LinkProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -/** @publicDocs */ -export interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; - detail?: any; - eventPhase: number; - target: HTMLElementTagNameMap[T] | null; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; + eventPhase: number; + target: ElementForTag | null; } -declare const tagName = "s-link"; -/** @publicDocs */ -export interface LinkJSXProps extends Pick { - /** - * Called when the link is activated. - */ - onClick?: (event: CallbackEvent) => void; - /** - * The link content. - */ - children?: ComponentChildren; +declare const tagName$1 = 's-link'; +/** + * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content. + * + * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/actions/button) instead. + * @publicDocs + */ +export interface LinkJSXProps + extends Pick< + LinkProps, + 'id' | 'commandFor' | 'command' | 'accessibilityLabel' + > { + /** + * Called when the link is activated. + */ + onClick?: (event: CallbackEvent) => void; + /** + * The Link content. + */ + children?: ComponentChildren; } + +declare const tagName = 's-link'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { LinkJSXProps }; +export {tagName}; +export type {LinkJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal.d.ts index cd39e29e75..b08041cfdc 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Modal.d.ts @@ -15,106 +15,87 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * Additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-modal'; -/** @publicDocs */ +/** + * The modal component displays content in an overlay that requires merchant attention. Use modals to present critical information, confirmations, or focused tasks while maintaining page context. + * + * Modals block interaction with the underlying interface until the merchant resolves the modal content. + * + * Modals don't automatically handle state management or persistence, so control visibility programmatically with the `command` and `commandFor` attributes. The events notify your code when the modal starts to show or hide. + * @publicDocs + */ export interface ModalJSXProps extends Pick { /** - * The callback when the modal is hidden. Use this event to perform cleanup tasks, update application state, or trigger other actions when the modal is dismissed or closed. + * A unique identifier for the element. + * + * Required to control visibility: a button or link with `commandFor` set to this `id` shows, hides, or toggles the modal. + */ + id?: string; + /** + * Callback when the modal starts to hide. Fired when a `commandFor` command requests the modal to close, before the closing transition completes. */ onHide?: (event: CallbackEvent) => void | null; /** - * The callback when the modal is shown. Use this event to initialize modal content, focus specific elements, or perform setup tasks when the modal becomes visible. + * Callback when the modal starts to show. Fired when a `commandFor` command requests the modal to open, before the opening transition completes. */ onShow?: (event: CallbackEvent) => void | null; /** - * The primary action button displayed in the modal. The tone of the button is used to define the tone of the modal. If omitted, the modal will default to an `'info'` tone, and show an OK button, translated according to the user's locale. + * The primary action button displayed in the modal. + * + * Setting the button's tone to `critical` presents the modal with destructive styling for irreversible actions; other tones don't change the modal's appearance. + * + * If omitted, the modal uses the default tone and shows a 'Close' button, translated according to the user's locale. */ primaryAction?: ComponentChild; /** - * The secondary action buttons displayed in the modal. Use this slot to provide alternative actions or cancel options that give users flexibility in how they respond to the modal. + * The secondary action buttons displayed in the modal. At most two secondary actions are rendered. */ secondaryActions?: ComponentChild; /** - * The child elements to render within this component. + * The content of the Modal. */ children?: ComponentChildren; } -/** @publicDocs */ export type ElementProps = Omit< ModalJSXProps, 'primaryAction' | 'secondaryActions' >; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField.d.ts index 60d1fa26fb..367d021356 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/NumberField.d.ts @@ -15,76 +15,44 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * The additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-number-field'; -/** @publicDocs */ +/** + * Collects numeric input with optional stepper controls. + * @publicDocs + */ export interface NumberFieldJSXProps extends Pick< NumberFieldProps, @@ -101,72 +69,123 @@ export interface NumberFieldJSXProps | 'controls' > { /** - * The text content that displays as the field label, describing the numeric information being requested. This property isn't supported when using `stepper` controls. + * The current value for the field, as a string. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + * In stepper mode the field is always populated: an empty or unparsable value is + * treated as `0`. + */ + value?: NumberFieldProps['value']; + /** + * The highest value accepted for the field. + * + * In text mode, the field clamps an out-of-bounds value to `max` when editing + * finishes and delivers the clamped value through `onInput`. + * + * @default Infinity + */ + max?: NumberFieldProps['max']; + /** + * The lowest value accepted for the field. + * + * In text mode, the field clamps an out-of-bounds value to `min` when editing + * finishes and delivers the clamped value through `onInput`. + * + * @default -Infinity + */ + min?: NumberFieldProps['min']; + /** + * Content to use as the field label. + * + * Label is not supported when using Stepper controls */ label?: NumberFieldProps['label']; /** - * The 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. This property isn't supported when using `stepper` controls. + * 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 are not supported when using Stepper controls */ details?: NumberFieldProps['details']; /** - * Whether the field needs a value. This requirement adds semantic value to the field but doesn't cause an error to appear automatically. Use the `error` property to present validation errors. This property isn't supported when using `stepper` controls. + * 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. + * + * Required is not supported when using Stepper controls * * @default false */ required?: NumberFieldProps['required']; /** - * An error message that indicates a problem to the user. The field receives specific stylistic treatment to communicate issues that must be resolved immediately. This property isn't supported when using `stepper` controls. + * 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 is not supported when using Stepper controls */ error?: NumberFieldProps['error']; /** - * The virtual keyboard layout that the field displays for numeric input. This property isn't supported when using `stepper` controls. + * Sets the virtual keyboard. * - * - `'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. + * Input mode is not supported when using Stepper controls * + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode * @default 'decimal' */ inputMode?: NumberFieldProps['inputMode']; /** - * A short hint that provides guidance about the expected value of the field. This property isn't supported when using `stepper` controls due to constrained space, especially on phones. + * A short hint that describes the expected value of the field. + * + * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones. */ placeholder?: NumberFieldProps['placeholder']; /** - * The additional content to be displayed in the field. Commonly used to display clickable text or action elements. Use the `slot="accessory"` attribute to place elements in this area. This slot isn't supported when using `stepper` controls. + * Additional content to be displayed in the field. Commonly used to display clickable text. + * + * > Note: Accessory is not supported when using Stepper controls */ accessory?: ComponentChild; /** - * The type of controls displayed for the field: + * Sets the type of controls displayed for the field. + * + * - `stepper`: displays buttons to increase or decrease the value of the field in steps of 1. Note that in POS + * adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically + * validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls. * - * - `'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. + * - `none`: no controls are displayed and users must input the value manually. + * - `auto`: the presence of the controls depends on the surface and context. * * @default 'auto' */ controls?: NumberFieldProps['controls']; /** - * A callback function that executes when the user makes any changes in the field. + * Callback when the user makes any changes in the field. In stepper mode, fires + * on every stepper button tap, together with `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes after editing completes, typically on blur. + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. In stepper mode, fires on every stepper + * button tap, together with `onInput`. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes when the element loses focus. + * Callback when the element loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes when the element receives focus. + * Callback when the element receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Page.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Page.d.ts index 075c30c673..a513093984 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Page.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Page.d.ts @@ -15,71 +15,59 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-page'; -/** @publicDocs */ +/** + * Provides the top-level page layout for extension content. + * @publicDocs + */ export interface PageJSXProps extends Pick { /** - * The main page heading displayed in the action bar at the top of the page. + * The main page heading, displayed in the action bar at the top of the page. * * @default: '' */ heading?: PageProps['heading']; /** - * A secondary page heading displayed under the main heading in the action bar. + * A secondary page heading, displayed under the main heading in the action bar. */ subheading?: PageProps['subheading']; /** - * A button element to display in the action bar. Only a single button is supported. Use the `slot="secondary-actions"` attribute to place content in this area. + * Button element to display in the action bar. Only a single button is supported. */ secondaryActions?: ComponentChild; /** - * 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. + * Content to display in the page's sidebar. */ aside?: ComponentChild; /** - * The child elements to render within this component. + * The content of the Page. */ children?: ComponentChildren; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock.d.ts index c70a77a0fb..cb9468f202 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/PosBlock.d.ts @@ -15,58 +15,46 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-pos-block'; -/** @publicDocs */ +/** + * Displays content in a POS block container with optional heading. + * @publicDocs + */ export interface PosBlockJSXProps extends Pick { /** - * The secondary actions to perform, provided as button or link type elements. Use the `slot="secondary-actions"` attribute to place interactive elements that allow users to take actions related to the block's content. + * The secondary actions to perform, provided as button or link type elements. */ secondaryActions?: ComponentChild; /** - * The child elements to render within this component. + * The content of the Block. */ children?: ComponentChildren; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/QrCode.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/QrCode.d.ts index f1cac466fb..1ef38da18c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/QrCode.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/QrCode.d.ts @@ -10,46 +10,32 @@ /// import type {QRCodeProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-qr-code'; /** @private */ export interface QrCodeJSXProps extends Pick {} declare global { interface HTMLElementTagNameMap { - [tagName]: QrCodeJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox.d.ts index 9842185d7d..e4c302cc8d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/ScrollBox.d.ts @@ -20,147 +20,148 @@ import type { Ref, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type PaddingKeyword = SizeKeyword | 'none'; +declare const tagName = 's-scroll-box'; /** - * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system. + * Provides a scrollable container for overflowing content. * @publicDocs */ -export type PaddingKeyword = SizeKeyword | 'none'; -declare const tagName = 's-scroll-box'; -/** @publicDocs */ export interface ScrollBoxJSXProps extends Pick { /** - * The block size of the scrollable container. Auto automatically sizes based on the container's content and available space. + * Adjust the block size. * * @default 'auto' */ blockSize?: SizeUnitsOrAuto; /** - * The inline size of the scrollable container. Auto automatically sizes based on the container's content and available space. + * Adjust the inline size. * * @default 'auto' */ inlineSize?: SizeUnitsOrAuto; /** - * The maximum block size constraint for the scrollable container. + * Adjust the maximum block size. * * @default 'none' */ maxBlockSize?: SizeUnitsOrNone; /** - * The maximum inline size constraint for the scrollable container. + * Adjust the maximum inline size. * * @default 'none' */ maxInlineSize?: SizeUnitsOrNone; /** - * The minimum block size constraint for the scrollable container. + * Adjust the minimum block size. * * @default '0' */ minBlockSize?: SizeUnits; /** - * The minimum inline size constraint for the scrollable container. + * Adjust the minimum inline size. * * @default '0' */ minInlineSize?: SizeUnits; /** - * The padding applied to all edges of the scrollable 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. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; /** - * The block-axis padding for the scrollable 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 */ paddingBlock?: MaybeTwoValuesShorthandProperty | ''; /** - * The block-start padding for the scrollable 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?: PaddingKeyword | ''; /** - * The block-end padding for the scrollable 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?: PaddingKeyword | ''; /** - * The inline-axis padding for the scrollable 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 */ paddingInline?: MaybeTwoValuesShorthandProperty | ''; /** - * The inline-start padding for the scrollable 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?: PaddingKeyword | ''; /** - * The inline-end padding for the scrollable 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?: PaddingKeyword | ''; /** - * The child elements to render within this component. + * The content of the ScrollBox. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: ScrollBoxJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField.d.ts index e837e474c5..e51c91b275 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/SearchField.d.ts @@ -10,98 +10,74 @@ /// import type {SearchFieldProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * The additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-search-field'; -/** @publicDocs */ +/** + * Collects search queries for filtering and lookup workflows. + * @publicDocs + */ export interface SearchFieldJSXProps extends Pick { /** - * Called when the user changes the value in the field. + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: SearchFieldProps['value']; + /** + * Callback when the user changes the value in the field. Also fires with an empty + * string when the user clears the field with the clear button; clearing the field + * doesn't fire `onChange`. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * Called when the field loses focus after the user changes the value in the field. + * Callback when the field loses focus after the user changes the value in the field. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the field loses focus. + * Callback when the field loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the field is focused. + * Callback when the field is focused. */ onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName]: SearchFieldJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section.d.ts index 8170bf028c..93bc10366d 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Section.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Section.d.ts @@ -15,61 +15,51 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-section'; -/** @publicDocs */ +/** + * Groups related content into a titled section. + * @publicDocs + */ export interface SectionJSXProps extends Pick { /** - * A title that describes the content of the section. If omitted and no secondary actions are provided, the section will be rendered without a header. + * A title that describes the content of the section. + * + * If omitted, and no secondaryActions are provided, the section will be rendered without a header. */ heading?: string; /** - * A button element to display in the section heading. Only a single button is supported. Use the `slot="secondary-actions"` attribute to place action elements that relate to the entire section's content. + * Button element to display in the section heading. A single button is supported. */ secondaryActions?: ComponentChild; /** - * The child elements to render within this component. + * The content of the Section. */ children?: ComponentChildren; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Spinner.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Spinner.d.ts index b573dc3bfa..8ec499d4b3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Spinner.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Spinner.d.ts @@ -8,47 +8,48 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {SpinnerProps,Key, Ref} from './components-shared.d.ts'; +import type {SpinnerProps, Key, Ref} from './components-shared.d.ts'; + +/** + * Displays a loading indicator while content or actions are in progress. + * @publicDocs + */ +export interface SpinnerJSXProps + extends Pick {} -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -declare const tagName = "s-spinner"; -/** @publicDocs */ -export interface SpinnerJSXProps extends Pick { -} +declare const tagName = 's-spinner'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { SpinnerJSXProps }; +export {tagName}; +export type {SpinnerJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack.d.ts index b6d0325755..c77f9d1f24 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Stack.d.ts @@ -24,47 +24,28 @@ import type { Ref, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-stack'; -/** - * Defines the available padding size options using a semantic scale. Provides consistent spacing values that align with the POS design system. - * @publicDocs - */ export type PaddingKeyword = SizeKeyword | 'none'; -/** @publicDocs */ export type PickedProps = Pick< StackProps, | 'id' @@ -82,153 +63,183 @@ export type PickedProps = Pick< | 'justifyContent' | 'rowGap' >; -/** @publicDocs */ +/** + * Arranges children in a horizontal or vertical stack. + * @publicDocs + */ export interface StackJSXProps extends PickedProps { /** - * 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. - * * @default 'none' */ padding?: MaybeAllValuesShorthandProperty; /** - * 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 */ paddingBlock?: 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?: PaddingKeyword | ''; /** - * 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?: PaddingKeyword | ''; /** - * 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 */ paddingInline?: 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?: PaddingKeyword | ''; /** - * The inline-end padding for the container. + * Adjust the inline-end padding. + * * This overrides the inline-end value of `paddingInline`. * * @default '' - meaning no override */ paddingInlineEnd?: PaddingKeyword | ''; /** - * The block size of the stack component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container. + * Adjust the block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/block-size * - * Learn more about [block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * @default 'auto' */ blockSize?: SizeUnitsOrAuto; /** - * The maximum block size constraint for the stack component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container. + * Adjust the maximum block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size * - * Learn more about [max-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * @default 'none' */ maxBlockSize?: SizeUnitsOrNone; /** - * The maximum inline size constraint for the stack component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container. + * Adjust the maximum inline size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size * - * Learn more about [max-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * @default 'none' */ maxInlineSize?: SizeUnitsOrNone; /** - * The minimum block size constraint for the stack component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container. + * Adjust the minimum block size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size * - * Learn more about [min-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * @default '0' */ minBlockSize?: SizeUnits; /** - * The minimum inline size constraint for the stack component. On mobile surfaces, avoid using percentage-based sizes as they don't behave as expected when placed within a scrollable container. + * Adjust the minimum inline size. + * **Mobile surfaces:** Avoid using percentage-based sizes. They do not behave as expected when placed within a scrollable container. + * + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size * - * Learn more about [min-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * @default '0' */ minInlineSize?: SizeUnits; /** - * The alignment of the stack component's children along the cross axis. + * Aligns the Stack's children along the cross axis. */ alignItems?: AlignItemsKeyword; /** - * The alignment of the stack component along the cross axis. + * Aligns the Stack along the cross axis. */ alignContent?: AlignContentKeyword; /** - * The 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. + * Adjust spacing between elements. + * A single value applies to both axes. A pair of values (for example, `large-100 large-500`) sets the block (row) and inline (column) axes respectively, matching the CSS `gap` shorthand order. * * @default 'none' */ gap?: MaybeTwoValuesShorthandProperty; /** - * The spacing between elements in the inline axis. This overrides the column value of gap. + * Adjust spacing between elements in the inline axis. This overrides the column value of gap. * * @default '' - meaning no override */ columnGap?: SpacingKeyword | ''; /** - * The direction in which children are placed within the stack component using logical properties. Use `'block'` for vertical arrangement where children are placed along the block axis (typically top to bottom) without wrapping. Use `'inline'` for horizontal arrangement where children are placed along the inline axis (typically left to right) with automatic wrapping when space is insufficient. + * Sets how the children are placed within the Stack. This uses logical properties. * * @default 'block' + * @implementation - the content will wrap if the direction is 'inline', and not wrap if the direction is 'block' */ direction?: 'block' | 'inline'; /** - * The inline size of the stack component. + * Adjust the inline size. + * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size * - * Learn more about [inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * @default 'auto' */ inlineSize?: SizeUnitsOrAuto; /** - * The alignment of the stack component along the main axis. + * Aligns the Stack along the main axis. + * @see — https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * - * Learn more about [justify-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content). * @default 'normal' */ justifyContent?: JustifyContentKeyword; /** - * The spacing between elements in the block axis. This overrides the row value of gap. + * Adjust spacing between elements in the block axis. This overrides the row value of gap. * * @default '' - meaning no override */ rowGap?: SpacingKeyword | ''; /** - * The child elements to render within this component. + * The content of the Stack. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: StackJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch.d.ts index d5fd5f1ca9..a60e524bb2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Switch.d.ts @@ -8,59 +8,111 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {SwitchProps,Key, Ref} from './components-shared.d.ts'; +import type {SwitchProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -/** @publicDocs */ -export interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; - detail?: any; - eventPhase: number; - target: HTMLElementTagNameMap[T] | null; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; + eventPhase: number; + target: ElementForTag | null; } -declare const tagName = "s-switch"; -/** @publicDocs */ -export interface SwitchJSXProps extends Pick { - onInput?: ((event: CallbackEvent) => void) | null; - onChange?: ((event: CallbackEvent) => void) | null; +declare const tagName$1 = 's-switch'; +/** + * Allows merchants to toggle a setting on or off. + * @publicDocs + */ +export interface SwitchJSXProps + extends Pick< + SwitchProps, + | 'value' + | 'defaultChecked' + | 'disabled' + | 'accessibilityLabel' + | 'checked' + | 'label' + | 'details' + | 'error' + | 'labelAccessibilityVisibility' + > { + /** + * A string value attached to the element. + * + * Use `checked` for the switch state. A string `value` stays attached to the + * element and can be read back in event callbacks; it doesn't affect the switch + * state and isn't submitted with any form. + */ + value?: SwitchProps['value']; + /** + * Whether the switch is on. + * + * When `checked` is set, update it from `onChange` or `onInput` to keep the + * switch controlled. When `checked` isn't set, the switch manages its own + * state, starting from `defaultChecked`. + * + * @default false + */ + checked?: SwitchProps['checked']; + /** + * Whether the switch is on when it first renders. + * + * Applies only to the initial render; later changes to `defaultChecked` are + * ignored. Use `checked` to control the state after the first render. + * + * @default false + */ + defaultChecked?: SwitchProps['defaultChecked']; + /** + * Callback when the user toggles the switch. Fires together with `onChange`, + * after it. Read the new state from `event.currentTarget.checked`. + */ + onInput?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the user toggles the switch. Fires together with `onInput`; + * `onChange` fires first. Read the new state from `event.currentTarget.checked`. + */ + onChange?: ((event: CallbackEvent) => void) | null; } + +declare const tagName = 's-switch'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { SwitchJSXProps }; +export {tagName}; +export type {SwitchJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tab.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tab.d.ts index bd607f549e..3586ea7e90 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tab.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tab.d.ts @@ -8,48 +8,54 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {TabProps,StringChildren,Key, Ref} from './components-shared.d.ts'; +import type { + TabProps, + StringChildren, + Key, + Ref, +} from './components-shared.d.ts'; + +/** + * Represents an individual tab inside a tabs component. + * @publicDocs + */ +export interface TabJSXProps extends Pick { + children?: StringChildren; +} -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -declare const tagName = "s-tab"; -/** @publicDocs */ -export interface TabJSXProps extends Pick { - children?: StringChildren; -} +declare const tagName = 's-tab'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { TabJSXProps }; +export {tagName}; +export type {TabJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TabList.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TabList.d.ts index 5e1a2add1e..f5a7f7c9ba 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TabList.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TabList.d.ts @@ -8,48 +8,49 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {TabListProps,Key, Ref} from './components-shared.d.ts'; +import type {TabListProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -declare const tagName = "s-tab-list"; -/** @publicDocs */ +/** + * Presents the list of selectable tabs within a tabs component. Accepts only tab components as children. + * @publicDocs + */ export interface TabListJSXProps extends Pick { - children?: ComponentChildren; + children?: ComponentChildren; } + +declare const tagName = 's-tab-list'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { TabListJSXProps }; +export {tagName}; +export type {TabListJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TabPanel.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TabPanel.d.ts index 5ff8e7ab0b..cd24a22471 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TabPanel.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TabPanel.d.ts @@ -8,48 +8,49 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {TabPanelProps,Key, Ref} from './components-shared.d.ts'; +import type {TabPanelProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -declare const tagName = "s-tab-panel"; -/** @publicDocs */ +/** + * Represents content associated with a selected tab. + * @publicDocs + */ export interface TabPanelJSXProps extends Pick { - children?: ComponentChildren; + children?: ComponentChildren; } + +declare const tagName = 's-tab-panel'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { TabPanelJSXProps }; +export {tagName}; +export type {TabPanelJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tabs.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tabs.d.ts index 32be69f74d..68f206c2a4 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tabs.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tabs.d.ts @@ -8,59 +8,84 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {TabsProps,Key, Ref} from './components-shared.d.ts'; +import type {TabsProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -/** @publicDocs */ -export interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; - detail?: any; - eventPhase: number; - target: HTMLElementTagNameMap[T] | null; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; + eventPhase: number; + target: ElementForTag | null; } -declare const tagName = "s-tabs"; -/** @publicDocs */ -export interface TabsJSXProps extends Pick { - children?: ComponentChildren; - onChange?: ((event: CallbackEvent) => void) | null; +declare const tagName$1 = 's-tabs'; +/** + * Groups related content into selectable tabbed views. + * @publicDocs + */ +export interface TabsJSXProps + extends Pick { + /** + * The value of the selected tab. + * + * This should match the `id` prop of one of the TabPanel components. + * When neither `value` nor `defaultValue` is provided, the first rendered tab panel is selected. + */ + value?: string; + /** + * The default value of the selected tab. + * + * This should match the `id` prop of one of the TabPanel components. + * Sets the initial selected tab in uncontrolled usage. Setting `value` afterwards overrides it. + */ + defaultValue?: string; + children?: ComponentChildren; + /** + * Callback fired when the selected tab changes. + * + * Fires on every tab selection, including when the current tab is selected again. + */ + onChange?: ((event: CallbackEvent) => void) | null; } + +declare const tagName = 's-tabs'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { TabsJSXProps }; +export {tagName}; +export type {TabsJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text.d.ts index f84f8fb7ea..6ff7fdf7cf 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Text.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Text.d.ts @@ -10,69 +10,48 @@ /// import type {TextProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; declare const tagName = 's-text'; -/** @publicDocs */ +/** + * Renders styled textual content. + * @publicDocs + */ export interface TextJSXProps extends Pick { /** - * 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?: Extract; /** - * The semantic meaning and default styling of the text. Other presentation properties override the default styling provided by the type. Available options: + * Provide semantic meaning and default styling to the text. * - * - `'generic'` - The default text type for general content without specific semantic meaning or emphasis. - * - `'strong'` - A text type that provides emphasis and importance, typically rendered with increased font weight or visual prominence. - * - `'small'` - A text type for secondary or supplementary content, typically rendered with reduced size for captions, fine print, or less important information. + * Other presentation properties on Text override the default styling. * * @default 'generic' */ type?: Extract; /** - * Determines the visual appearance and semantic meaning of the text. Available options: - * - * - `'auto'` - Lets the system automatically choose the appropriate tone based on context. Use when you want the system to determine the most appropriate styling. - * - `'neutral'` - Gray styling for general status information that doesn't require emphasis. Use for general status updates and standard information. - * - `'info'` - Blue styling for informational content and neutral updates. Use for informational content that provides helpful context. - * - `'success'` - Green styling for positive states, completed actions, and successful operations. Use for positive outcomes and successful processes. - * - `'caution'` - Yellow styling for situations that need attention but aren't urgent. Use for potential issues that require awareness. - * - `'warning'` - Orange styling for important notices that require merchant awareness. Use for situations that need attention but aren't critical. - * - `'critical'` - Red styling for errors, failures, and urgent issues requiring immediate action. Use for urgent issues that need immediate merchant attention. + * Sets the tone of the component, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -81,13 +60,13 @@ export interface TextJSXProps extends Pick { 'auto' | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'caution' >; /** - * The text content. Supports nested text elements. + * The Text content. Supports nested text elements. */ children?: ComponentChildren; } declare global { interface HTMLElementTagNameMap { - [tagName]: TextJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea.d.ts index 60b2d95b88..a249f4265f 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextArea.d.ts @@ -8,75 +8,107 @@ /* eslint-disable import-x/namespace */ // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment /// -import type {TextAreaProps,Key, Ref} from './components-shared.d.ts'; +import type {TextAreaProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** * Used when an element does not have children. - * @publicDocs */ export interface BaseElementProps { - key?: Key; - ref?: Ref; - slot?: Lowercase; + key?: Key; + ref?: Ref; + slot?: Lowercase; } /** * Used when an element has children. - * @publicDocs */ -export interface BaseElementPropsWithChildren extends BaseElementProps { - children?: ComponentChildren; +export interface BaseElementPropsWithChildren + extends BaseElementProps { + children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** @publicDocs */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; export type HtmlElementTagNameProps = T & HTMLElement; -/** @publicDocs */ -export interface CallbackEvent { - currentTarget: HTMLElementTagNameMap[T]; - bubbles?: boolean; - cancelable?: boolean; - composed?: boolean; - detail?: any; - eventPhase: number; - target: HTMLElementTagNameMap[T] | null; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; + bubbles?: boolean; + cancelable?: boolean; + composed?: boolean; + detail?: any; + eventPhase: number; + target: ElementForTag | null; } -declare const tagName = "s-text-area"; -/** @publicDocs */ -export interface TextAreaJSXProps extends Pick { - /** - * Callback when the user makes any changes in the field. - */ - onInput?: ((event: CallbackEvent) => void) | null; - /** - * Callback after editing completes (typically on blur). - */ - onChange?: ((event: CallbackEvent) => void) | null; - /** - * Callback when the element loses focus. - */ - onBlur?: ((event: CallbackEvent) => void) | null; - /** - * Callback when the element receives focus. - */ - onFocus?: ((event: CallbackEvent) => void) | null; +declare const tagName$1 = 's-text-area'; +/** + * Collects multi-line text input from the merchant. + * @publicDocs + */ +export interface TextAreaJSXProps + extends Pick< + TextAreaProps, + | 'id' + | 'label' + | 'details' + | 'value' + | 'placeholder' + | 'disabled' + | 'error' + | 'required' + | 'maxLength' + | 'rows' + > { + /** + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: TextAreaProps['value']; + /** + * A number of visible text lines. + * + * Sets the visible height of the field only; it doesn't limit how many lines of + * text can be entered. Values are clamped between 1 and 8. + * + * @default 2 + */ + rows?: TextAreaProps['rows']; + /** + * Callback when the user makes any changes in the field. + */ + onInput?: ((event: CallbackEvent) => void) | null; + /** + * Callback after editing completes, on blur. Fires only when the value + * changed since the field received focus. + */ + onChange?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element loses focus. + */ + onBlur?: ((event: CallbackEvent) => void) | null; + /** + * Callback when the element receives focus. + */ + onFocus?: ((event: CallbackEvent) => void) | null; } -/** @publicDocs */ -export type ElementProps = Omit; + +declare const tagName = 's-text-area'; declare global { - interface HTMLElementTagNameMap { - [tagName]: HtmlElementTagNameProps; - } + interface HTMLElementTagNameMap { + [tagName]: HtmlElementTagNameProps; + } } declare module 'preact' { - namespace createElement.JSX { - interface IntrinsicElements { - [tagName]: IntrinsicElementProps; - } + namespace createElement.JSX { + interface IntrinsicElements { + [tagName]: IntrinsicElementProps; } + } } -export { tagName }; -export type { TextAreaJSXProps }; +export {tagName}; +export type {TextAreaJSXProps}; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField.d.ts index 844e18e11f..ef24c46e31 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TextField.d.ts @@ -15,76 +15,44 @@ import type { ComponentChild, } from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * The additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-text-field'; -/** @publicDocs */ +/** + * Collects single-line text input. + * @publicDocs + */ export interface TextFieldJSXProps extends Pick< TextFieldProps, @@ -99,31 +67,37 @@ export interface TextFieldJSXProps | 'maxLength' > { /** - * A callback function that executes when the user makes any changes in the field. + * The current value for the field. If omitted, the field manages its own state. + * + * Set `value` and update it from `onInput` or `onChange` to control the field. + */ + value?: TextFieldProps['value']; + /** + * Callback when the user makes any changes in the field. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes after editing completes, typically on blur. + * Callback after editing completes, on blur or submit. Fires only when the value + * changed since the field received focus. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes when the element loses focus. + * Callback when the element loses focus. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * A callback function that executes when the element receives focus. + * Callback when the element receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; /** - * The additional content to be displayed in the field. 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 content to be displayed in the field. Commonly used to display clickable text. */ accessory?: ComponentChild; } -/** @publicDocs */ export type ElementProps = Omit; declare global { interface HTMLElementTagNameMap { - [tagName]: ElementProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile.d.ts index 50ebb1f55d..8ea1dd6bc1 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/Tile.d.ts @@ -10,95 +10,63 @@ /// import type {TileProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents an event triggered by user interaction with the tile. Provides information about the event and access to the tile element that triggered it. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The tile element to which the event handler is attached. This always refers to the element that the event listener was added to, unlike `target` which may refer to a child element. Commonly used to access the tile's properties or manipulate the element directly. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Indicates whether the event bubbles up through the DOM tree. When `true`, parent elements can also handle this event. Commonly used to determine if the event will propagate to parent handlers. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Indicates whether the event's default action can be prevented. When `true`, calling `preventDefault()` on the event will prevent the default behavior. Commonly used to determine if you can prevent the default action programmatically. - */ cancelable?: boolean; - /** - * Indicates whether the event will propagate across shadow DOM boundaries into the standard DOM. When `true`, the event can be handled by elements outside the shadow DOM. Relevant for web component implementations. - */ composed?: boolean; - /** - * The custom data associated with the event. For custom events, this can contain any additional information about the event. For standard tile click events, this is typically undefined unless custom data is provided. - */ detail?: any; - /** - * Indicates the current phase of the event flow. Standard DOM event phase values: `0` (none), `1` (capturing), `2` (at target), or `3` (bubbling). Typically applied when implementing custom event handling logic that needs to differentiate between event phases. - */ eventPhase: number; - /** - * The element that originally triggered the event. For tiles, this is typically the same as `currentTarget` since tiles are single interactive elements. Returns `null` if the target is no longer in the document. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-tile'; -/** @publicDocs */ +/** + * Displays tappable content in a compact tile layout. + * @publicDocs + */ export interface TileJSXProps extends Pick< TileProps, 'heading' | 'id' | 'itemCount' | 'tone' | 'subheading' > { /** - * Controls whether the tile can be clicked or receive focus. When `true`, the tile appears dimmed and doesn't respond to user interactions or fire click events. Commonly used to prevent actions when conditions aren't met, such as insufficient cart contents or missing permissions. Defaults to `false`. + * Disables the Tile meaning it cannot be clicked or receive focus. * * @default false */ disabled?: TileProps['disabled']; /** - * The callback function executed when the tile is activated by user interaction. Use this to launch modal workflows with `api.action.presentModal()`, update application state, or trigger other actions. The event parameter provides details about the interaction and the tile element that was clicked. + * Callback when the Tile is activated. */ onClick?: (event: CallbackEvent) => void; } declare global { interface HTMLElementTagNameMap { - [tagName]: TileJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField.d.ts index 56096df21e..a1e9513ef2 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimeField.d.ts @@ -10,101 +10,82 @@ /// import type {TimeFieldProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * The additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-time-field'; -/** @publicDocs */ +/** + * Collects a time value. + * @publicDocs + */ export interface TimeFieldJSXProps extends Pick< TimeFieldProps, - 'id' | 'label' | 'disabled' | 'value' | 'error' | 'details' + 'id' | 'label' | 'disabled' | 'value' | 'error' | 'details' | 'required' > { /** - * Called when the user makes any changes in the field. + * The current value for the field, as a 24-hour time in `HH:mm:ss` format with + * leading zeros (for example, `"09:05:00"`). If omitted or empty, the field is + * empty. + * + * Seconds aren't captured: emitted values always end in `:00`, and seconds in a + * provided value are ignored. Values are interpreted in the device's local + * timezone. The field displays times in 12-hour AM/PM format. + */ + value?: TimeFieldProps['value']; + /** + * Callback when the user confirms a time in the picker. Fires together with + * `onChange` at selection time. */ onInput?: ((event: CallbackEvent) => void) | null; /** - * Called after editing completes, typically on blur. + * Callback when the user confirms a time in the picker. Fires together with + * `onInput` at selection time, not on blur. */ onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the element loses focus. + * Callback when the element loses focus. Also fires right after a picker + * selection is confirmed, and when the picker is dismissed without a selection. */ onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the element receives focus. + * Callback when the element receives focus. */ onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName]: TimeFieldJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker.d.ts index a6c200be80..cd2591c280 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/TimePicker.d.ts @@ -10,98 +10,88 @@ /// import type {TimePickerProps, Key, Ref} from './components-shared.d.ts'; -/** @publicDocs */ export type ComponentChildren = any; /** - * The base props for elements without children, providing key, ref, and slot properties. - * @publicDocs + * Used when an element does not have children. */ export interface BaseElementProps { - /** - * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation. - */ key?: Key; - /** - * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations. - */ ref?: Ref; - /** - * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component. - */ slot?: Lowercase; } /** - * The base props for elements with children, extending `BaseElementProps` with children support. - * @publicDocs + * Used when an element has children. */ export interface BaseElementPropsWithChildren extends BaseElementProps { - /** - * The child elements to render within this component. - */ children?: ComponentChildren; } -/** @publicDocs */ -export type IntrinsicElementProps = T & BaseElementPropsWithChildren; -/** - * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. - * @publicDocs - */ -export interface CallbackEvent { - /** - * The element that the event listener is attached to. - */ - currentTarget: HTMLElementTagNameMap[T]; - /** - * Whether the event bubbles up through the DOM tree. - */ +export type IntrinsicElementProps = T & + BaseElementPropsWithChildren; +export type HtmlElementTagNameProps = T & HTMLElement; +export type ElementForTag = + T extends keyof HTMLElementTagNameMap + ? HTMLElementTagNameMap[T] + : HTMLElement; +export interface CallbackEvent { + currentTarget: ElementForTag; bubbles?: boolean; - /** - * Whether the event can be canceled. - */ cancelable?: boolean; - /** - * Whether the event will trigger listeners outside of a shadow root. - */ composed?: boolean; - /** - * The additional data associated with the event. - */ detail?: any; - /** - * The current phase of the event flow. - */ eventPhase: number; - /** - * The element that triggered the event. - */ - target: HTMLElementTagNameMap[T] | null; + target: ElementForTag | null; } declare const tagName = 's-time-picker'; -/** @publicDocs */ +/** + * Lets merchants select a time from a picker. + * @publicDocs + */ export interface TimePickerJSXProps extends Pick { /** - * Called when the user selects a time from the picker. + * A unique identifier for the element. + * + * An `id` is required to open or close the picker with the command system (for + * example, a Button with `command="--show"` and `commandFor` set to this `id`) + * and to receive `onFocus` and `onBlur` events. A picker without an `id` can't + * be shown. + */ + id?: TimePickerProps['id']; + /** + * The current selected value. + * + * The default `''` means no time is selected. + * + * The value must be a 24-hour time in `HH:mm:ss` format, with leading zeros + * (for example, `"09:05:00"`). Seconds aren't captured: emitted values always + * end in `:00`, and seconds in a provided value are ignored. Values are + * interpreted in the device's local timezone. + * + * @default '' + */ + value?: TimePickerProps['value']; + /** + * Callback when the user selects a time from the picker. Fires after `onChange`. */ - onInput?: (event: CallbackEvent) => void | null; + onInput?: ((event: CallbackEvent) => void) | null; /** - * Called when the user selects a time from the picker that is different from the current value. + * Callback when the user selects a time from the picker that is different to the current value. Fires before `onInput`. */ - onChange?: (event: CallbackEvent) => void | null; + onChange?: ((event: CallbackEvent) => void) | null; /** - * Called when the time picker is dismissed or closed. + * Callback when the time picker is dismissed. */ - onBlur?: (event: CallbackEvent) => void | null; + onBlur?: ((event: CallbackEvent) => void) | null; /** - * Called when the time picker is revealed or opened. + * Callback when the time picker is revealed. */ - onFocus?: (event: CallbackEvent) => void | null; + onFocus?: ((event: CallbackEvent) => void) | null; } declare global { interface HTMLElementTagNameMap { - [tagName]: TimePickerJSXProps & HTMLElement; + [tagName]: HtmlElementTagNameProps; } } declare module 'preact' { diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/components-shared.d.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/components-shared.d.ts index 486c4d1053..5b0a24b8ba 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/components/components-shared.d.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/components-shared.d.ts @@ -9,19 +9,15 @@ /** * TODO: Update `any` type here after this is resolved * https://github.com/Shopify/ui-api-design/issues/139 - * @publicDocs */ export type ComponentChildren = any; -/** @publicDocs */ export type StringChildren = string; -/** @publicDocs */ export interface GlobalProps { /** * A unique identifier for the element. */ id?: string; } -/** @publicDocs */ export interface ActionSlots { /** * The primary action to perform, provided as a button or link type element. @@ -32,7 +28,6 @@ export interface ActionSlots { */ secondaryActions?: ComponentChildren; } -/** @publicDocs */ export interface BaseOverlayProps { /** * Callback fired after the overlay is shown. @@ -58,7 +53,6 @@ export interface BaseOverlayProps { * - 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 - * @publicDocs */ export interface BaseOverlayMethods { /** @@ -80,7 +74,6 @@ export interface BaseOverlayMethods { */ toggleOverlay: () => void; } -/** @publicDocs */ export interface FocusEventProps { /** * Callback when the element loses focus. @@ -95,7 +88,6 @@ export interface FocusEventProps { */ onFocus?: (event: FocusEvent) => void; } -/** @publicDocs */ export type SizeKeyword = | 'small-500' | 'small-400' @@ -110,11 +102,8 @@ export type SizeKeyword = | 'large-300' | 'large-400' | 'large-500'; -/** @publicDocs */ export type ColorKeyword = 'subdued' | 'base' | 'strong'; -/** @publicDocs */ export type BackgroundColorKeyword = 'transparent' | ColorKeyword; -/** @publicDocs */ export interface BackgroundProps { /** * Adjust the background of the element. @@ -132,7 +121,6 @@ export interface BackgroundProps { * 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' @@ -705,22 +693,17 @@ declare const privateIconArray: readonly [ 'x-circle', 'x-circle-filled', ]; -/** @publicDocs */ export type IconType = (typeof privateIconArray)[number]; /** * Like `Extract`, but ensures that the extracted type is a strict subtype of the input type. - * @publicDocs */ export type ExtractStrict = Extract; -/** @publicDocs */ export type MaybeAllValuesShorthandProperty = | T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`; -/** @publicDocs */ export type MaybeTwoValuesShorthandProperty = T | `${T} ${T}`; -/** @publicDocs */ export type MaybeResponsive = T | `@container${string}`; /** * Prevents widening string literal types in a union to `string`. @@ -729,7 +712,6 @@ export type MaybeResponsive = T | `@container${string}`; * // ^? string * type PropName = 'foo' | 'bar' | (string & {}) * // ^? 'foo' | 'bar' | (string & {}) - * @publicDocs */ export type AnyString = string & {}; /** @@ -737,17 +719,15 @@ export type AnyString = string & {}; * 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. - * @publicDocs */ export type optionalSpace = '' | ' '; -/** @publicDocs */ export interface BadgeProps extends GlobalProps { /** - * The content of the badge. + * The content of the Badge. */ children?: ComponentChildren; /** - * Sets the tone of the badge, based on the intention of the information being conveyed. + * Sets the tone of the Badge, based on the intention of the information being conveyed. * * @default 'auto' */ @@ -775,7 +755,6 @@ export interface BadgeProps extends GlobalProps { */ size?: SizeKeyword; } -/** @publicDocs */ export interface BannerProps extends GlobalProps, ActionSlots { /** * The title of the banner. @@ -784,11 +763,11 @@ export interface BannerProps extends GlobalProps, ActionSlots { */ heading?: string; /** - * The content of the banner. + * The content of the Banner. */ children?: ComponentChildren; /** - * Sets the tone of the banner, based on the intention of the information being conveyed. + * 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. * @@ -851,7 +830,6 @@ export interface BannerProps extends GlobalProps, ActionSlots { */ hidden?: boolean; } -/** @publicDocs */ export interface DisplayProps { /** * 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). @@ -864,7 +842,6 @@ export interface DisplayProps { */ display?: MaybeResponsive<'auto' | 'none'>; } -/** @publicDocs */ export interface AccessibilityRoleProps { /** * Sets the semantic meaning of the component’s content. When set, @@ -878,7 +855,6 @@ export interface AccessibilityRoleProps { */ accessibilityRole?: AccessibilityRole; } -/** @publicDocs */ export type AccessibilityRole = /** * Used to indicate the primary content. @@ -903,7 +879,7 @@ export type AccessibilityRole = | 'footer' /** * Used to indicate a generic section. - * Sections should always have a heading or an accessible name provided in the `accessibilityLabel` property. + * Sections should always have a `Heading` or an accessible name provided in the `accessibilityLabel` property. * * In an HTML host `section` will render a `
` element. * Learn more about the [`
` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section) and its [implicit role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) in the MDN web docs. @@ -994,7 +970,6 @@ export type AccessibilityRole = * 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'; -/** @publicDocs */ export interface AccessibilityVisibilityProps { /** * Changes the visibility of the element. @@ -1007,7 +982,6 @@ export interface AccessibilityVisibilityProps { */ accessibilityVisibility?: 'visible' | 'hidden' | 'exclusive'; } -/** @publicDocs */ export interface LabelAccessibilityVisibilityProps { /** * Changes the visibility of the component's label. @@ -1022,9 +996,7 @@ export interface LabelAccessibilityVisibilityProps { 'visible' | 'exclusive' >; } -/** @publicDocs */ export type PaddingKeyword = SizeKeyword | 'none'; -/** @publicDocs */ export interface PaddingProps { /** * Adjust the padding of all edges. @@ -1104,13 +1076,9 @@ export interface PaddingProps { */ paddingInlineEnd?: MaybeResponsive; } -/** @publicDocs */ export type SizeUnits = `${number}px` | `${number}%` | `0`; -/** @publicDocs */ export type SizeUnitsOrAuto = SizeUnits | 'auto'; -/** @publicDocs */ export type SizeUnitsOrNone = SizeUnits | 'none'; -/** @publicDocs */ export interface SizingProps { /** * Adjust the block size. @@ -1161,26 +1129,21 @@ export interface SizingProps { */ maxInlineSize?: MaybeResponsive; } -/** @publicDocs */ export type BorderStyleKeyword = | 'none' | 'solid' | 'dashed' | 'dotted' | 'auto'; -/** @publicDocs */ export type BorderSizeKeyword = SizeKeyword | 'none'; -/** @publicDocs */ 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. - * @publicDocs */ export type BorderShorthand = | BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`; -/** @publicDocs */ export interface BorderProps { /** * Set the border via the shorthand property. @@ -1265,7 +1228,6 @@ export interface BorderProps { */ borderRadius?: MaybeAllValuesShorthandProperty; } -/** @publicDocs */ export interface OverflowProps { /** * Sets the overflow behavior of the element. @@ -1279,7 +1241,6 @@ export interface OverflowProps { */ overflow?: 'hidden' | 'visible'; } -/** @publicDocs */ export interface BaseBoxProps extends AccessibilityVisibilityProps, BackgroundProps, @@ -1289,7 +1250,7 @@ export interface BaseBoxProps BorderProps, OverflowProps { /** - * The content of the box. + * The content of the Box. */ children?: ComponentChildren; /** @@ -1300,14 +1261,12 @@ export interface BaseBoxProps */ accessibilityLabel?: string; } -/** @publicDocs */ export interface BaseBoxPropsWithRole extends BaseBoxProps, AccessibilityRoleProps {} -/** @publicDocs */ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** - * The behavior of the button. + * 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. @@ -1319,14 +1278,14 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { */ type?: 'submit' | 'button' | 'reset'; /** - * Callback when the button is activated. + * Callback when the Button is activated. * This will be called before the action indicated by `type`. * * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event */ onClick?: (event: Event) => void; /** - * Disables the button meaning it cannot be clicked or receive focus. + * Disables the Button meaning it cannot be clicked or receive focus. * * @default false */ @@ -1334,13 +1293,12 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps { /** * Replaces content with a loading indicator while a background action is being performed. * - * This also disables the button. + * This also disables the Button. * * @default false */ loading?: boolean; } -/** @publicDocs */ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps { /** * The URL to link to. @@ -1377,24 +1335,29 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps { */ onClick?: (event: Event) => void; } -/** @publicDocs */ export interface InteractionProps { /** - * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](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; /** - * Sets the action the `commandFor` target should take when this component is activated. Available options: + * Sets the action the `commandFor` should take when this clickable is activated. * - * - `'--auto'`: Performs the default action appropriate for the target component. - * - `'--show'`: Displays the target component if it's currently hidden. - * - `'--hide'`: Conceals the target component from view. - * - `'--toggle'`: Alternates the target component between visible and hidden states. - * - `'--copy'`: Copies the target clipboard item. + * See the documentation of particular components for the actions they support. * - * The supported actions vary by target component type. Learn more about the [`command` attribute](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'; /** @@ -1402,31 +1365,29 @@ export interface InteractionProps { */ interestFor?: string; } -/** @publicDocs */ export interface BaseClickableProps extends ButtonBehaviorProps, LinkBehaviorProps {} -/** @publicDocs */ export interface ButtonProps extends GlobalProps, BaseClickableProps { /** - * A label that describes the purpose or contents of the button. It will be read to users using assistive technologies such as screen readers. + * 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 + * Use this when using only an icon or the Button text is not enough context * for users using assistive technologies. */ accessibilityLabel?: string; /** - * The content of the button. + * The content of the Button. */ children?: ComponentChildren; /** - * The type of icon to be displayed in the button. + * The type of icon to be displayed in the Button. * * @default '' */ icon?: IconType | AnyString; /** - * The displayed inline width of the button. + * 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. @@ -1436,13 +1397,13 @@ export interface ButtonProps extends GlobalProps, BaseClickableProps { */ inlineSize?: 'auto' | 'fill' | 'fit-content'; /** - * Changes the visual appearance of the button. + * 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 information being conveyed. + * Sets the tone of the Button based on the intention of the information being conveyed. * * @default 'auto' */ @@ -1454,7 +1415,6 @@ export interface ButtonProps extends GlobalProps, BaseClickableProps { */ lang?: string; } -/** @publicDocs */ export interface BaseInputProps { /** * An identifier for the field that is unique within the nearest containing form. @@ -1467,7 +1427,6 @@ export interface BaseInputProps { */ disabled?: boolean; } -/** @publicDocs */ export interface InputProps extends BaseInputProps { /** * Callback when the user has **finished editing** a field, e.g. once they have blurred the field. @@ -1492,7 +1451,6 @@ export interface InputProps extends BaseInputProps { */ defaultValue?: string; } -/** @publicDocs */ export interface MultipleInputProps extends BaseInputProps { /** * Callback when the user has selected option(s). @@ -1513,7 +1471,6 @@ export interface MultipleInputProps extends BaseInputProps { */ values?: string[]; } -/** @publicDocs */ export interface FieldErrorProps { /** * Indicate an error to the user. The field will be given a specific stylistic treatment @@ -1521,7 +1478,6 @@ export interface FieldErrorProps { */ error?: string; } -/** @publicDocs */ export interface BasicFieldProps extends FieldErrorProps, LabelAccessibilityVisibilityProps { @@ -1539,7 +1495,6 @@ export interface BasicFieldProps */ label?: string; } -/** @publicDocs */ export interface FieldDetailsProps { /** * Additional text to provide context or guidance for the field. @@ -1550,7 +1505,6 @@ export interface FieldDetailsProps { */ details?: string; } -/** @publicDocs */ export interface FieldProps extends BasicFieldProps, InputProps, @@ -1561,7 +1515,6 @@ export interface FieldProps */ placeholder?: string; } -/** @publicDocs */ export interface BaseTextFieldProps extends FieldProps { /** * The field cannot be edited by the user. It is focusable will be announced by screen readers. @@ -1570,7 +1523,6 @@ export interface BaseTextFieldProps extends FieldProps { */ readOnly?: boolean; } -/** @publicDocs */ export interface FieldDecorationProps { /** * A value to be displayed immediately after the editable portion of the field. @@ -1610,7 +1562,6 @@ export interface FieldDecorationProps { */ accessory?: ComponentChildren; } -/** @publicDocs */ export interface NumberConstraintsProps { /** * The highest decimal or integer to be accepted for the field. @@ -1653,7 +1604,6 @@ export interface NumberConstraintsProps { */ controls?: 'auto' | 'stepper' | 'none'; } -/** @publicDocs */ export interface MinMaxLengthProps { /** * Specifies the maximum number of characters allowed. @@ -1668,7 +1618,6 @@ export interface MinMaxLengthProps { */ minLength?: number; } -/** @publicDocs */ export interface BaseSelectableProps { /** * A label used for users using assistive technologies like screen readers. When set, any children or `label` supplied will not be announced. @@ -1686,7 +1635,6 @@ export interface BaseSelectableProps { */ value?: string; } -/** @publicDocs */ export interface BaseOptionProps extends BaseSelectableProps { /** * Whether the control is active. @@ -1703,7 +1651,6 @@ export interface BaseOptionProps extends BaseSelectableProps { */ defaultSelected?: boolean; } -/** @publicDocs */ export interface BaseCheckableProps extends BaseSelectableProps, InteractionProps { @@ -1743,7 +1690,6 @@ export interface BaseCheckableProps */ onInput?: (event: Event) => void; } -/** @publicDocs */ export interface ChoiceProps extends GlobalProps, BaseOptionProps { /** * Content to use as the choice label. @@ -1767,7 +1713,7 @@ export interface ChoiceProps extends GlobalProps, BaseOptionProps { */ details?: ComponentChildren; /** - * Set to `true` to associate a choice with the error passed to ChoiceList + * Set to `true` to associate a choice with the error passed to `ChoiceList` * * @default false */ @@ -1783,7 +1729,6 @@ export interface ChoiceProps extends GlobalProps, BaseOptionProps { */ selectedContent?: ComponentChildren; } -/** @publicDocs */ export interface ChoiceListProps extends GlobalProps, Pick, @@ -1798,7 +1743,7 @@ export interface ChoiceListProps /** * The choices a user can select from. * - * Accepts choice components. + * Accepts `Choice` components. */ children?: ComponentChildren; /** @@ -1825,7 +1770,6 @@ export interface ChoiceListProps */ variant?: 'auto' | 'list' | 'inline' | 'block' | 'grid'; } -/** @publicDocs */ export interface ClickableProps extends GlobalProps, BaseBoxProps, @@ -1857,7 +1801,6 @@ export interface ClickableProps */ lang?: string; } -/** @publicDocs */ export interface AutocompleteProps< AutocompleteField extends AnyAutocompleteField, > { @@ -1895,20 +1838,16 @@ export interface AutocompleteProps< * * 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. - * @publicDocs */ export type AutocompleteSection = `section-${string}`; /** * The contact information group the autocomplete data should be sourced from. - * @publicDocs */ export type AutocompleteGroup = 'shipping' | 'billing'; /** * The contact information subgroup the autocomplete data should be sourced from. - * @publicDocs */ export type AutocompleteAddressGroup = 'fax' | 'home' | 'mobile' | 'pager'; -/** @publicDocs */ export type AnyAutocompleteField = | 'additional-name' | 'address-level1' @@ -1974,7 +1913,6 @@ export type AnyAutocompleteField = | `${AutocompleteAddressGroup} tel-local-suffix` | `${AutocompleteAddressGroup} tel-local` | `${AutocompleteAddressGroup} tel-national`; -/** @publicDocs */ export type TextAutocompleteField = ExtractStrict< AnyAutocompleteField, | 'additional-name' @@ -2008,7 +1946,6 @@ export type TextAutocompleteField = ExtractStrict< | 'cc-family-name' | 'cc-type' >; -/** @publicDocs */ export interface DatePickerProps extends GlobalProps, InputProps, @@ -2175,7 +2112,6 @@ export interface DatePickerProps */ onChange?: (event: Event) => void; } -/** @publicDocs */ export interface DateFieldProps extends GlobalProps, BaseTextFieldProps, @@ -2219,7 +2155,6 @@ export interface DateFieldProps */ onInvalid?: (event: Event) => void; } -/** @publicDocs */ export type DateAutocompleteField = ExtractStrict< AnyAutocompleteField, | 'bday' @@ -2230,7 +2165,6 @@ export type DateAutocompleteField = ExtractStrict< | 'cc-expiry-month' | 'cc-expiry-year' >; -/** @publicDocs */ export interface DateSpinnerProps extends GlobalProps, Pick< @@ -2269,7 +2203,6 @@ export interface DateSpinnerProps */ onChange?: (event: Event) => void; } -/** @publicDocs */ export interface DividerProps extends GlobalProps { /** * Specify the direction of the divider. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). @@ -2284,18 +2217,15 @@ export interface DividerProps extends GlobalProps { */ color?: ColorKeyword; } -/** @publicDocs */ export interface EmailFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps {} -/** @publicDocs */ export type EmailAutocompleteField = ExtractStrict< AnyAutocompleteField, 'email' | `${AutocompleteAddressGroup} email` >; -/** @publicDocs */ export interface EmbedProps extends GlobalProps, SizingProps { /** * The content type of the file to display. @@ -2319,31 +2249,28 @@ export interface EmbedProps extends GlobalProps, SizingProps { */ src?: string; /** - * A label that describes the purpose or contents of the embed. It will be read to users + * A label that describes the purpose or contents of the Embed. It will be read to users * using assistive technologies such as screen readers. * * @implementation for web-based implementations, this should map to the [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute */ accessibilityLabel?: string; } -/** @publicDocs */ export interface EmptyStateProps extends GlobalProps, ActionSlots { /** - * The heading of the empty state. + * The heading of the EmptyState. */ heading?: string; /** - * The subheading of the empty state. + * The subheading of the EmptyState. */ subheading?: ComponentChildren | StringChildren; /** - * The graphic to display in the empty state. The only supported components are image and icon. + * The graphic to display in the EmptyState. The only supported components are `Image` and `Icon`. */ graphic?: ComponentChildren; } -/** @publicDocs */ export type SpacingKeyword = SizeKeyword | 'none'; -/** @publicDocs */ export interface GapProps { /** * Adjust spacing between elements. @@ -2371,17 +2298,13 @@ export interface GapProps { */ columnGap?: MaybeResponsive; } -/** @publicDocs */ export type BaselinePosition = 'baseline' | 'first baseline' | 'last baseline'; -/** @publicDocs */ export type ContentDistribution = | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'; -/** @publicDocs */ export type ContentPosition = 'center' | 'start' | 'end'; -/** @publicDocs */ export type OverflowPosition = | `unsafe ${ContentPosition}` | `safe ${ContentPosition}`; @@ -2389,7 +2312,6 @@ export type OverflowPosition = * Align items sets the align-self value on all direct children as a group. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items - * @publicDocs */ export type AlignItemsKeyword = | 'normal' @@ -2401,7 +2323,6 @@ export type AlignItemsKeyword = * 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. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content - * @publicDocs */ export type JustifyContentKeyword = | 'normal' @@ -2412,7 +2333,6 @@ export type JustifyContentKeyword = *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. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content - * @publicDocs */ export type AlignContentKeyword = | 'normal' @@ -2420,7 +2340,6 @@ export type AlignContentKeyword = | ContentDistribution | OverflowPosition | ContentPosition; -/** @publicDocs */ export interface BaseTypographyProps { /** * Modify the color to be more or less intense. @@ -2466,7 +2385,6 @@ export interface BaseTypographyProps { */ dir?: 'ltr' | 'rtl' | 'auto' | ''; } -/** @publicDocs */ export interface BlockTypographyProps { /** * Truncates the text content to the specified number of lines. @@ -2477,13 +2395,12 @@ export interface BlockTypographyProps { */ lineClamp?: number; } -/** @publicDocs */ export interface HeadingProps extends GlobalProps, AccessibilityVisibilityProps, BlockTypographyProps { /** - * The content of the heading. + * The content of the Heading. */ children?: ComponentChildren; /** @@ -2507,7 +2424,6 @@ export interface HeadingProps | 'heading' | ExtractStrict; } -/** @publicDocs */ export interface IconProps extends GlobalProps, Pick { @@ -2531,7 +2447,6 @@ export interface IconProps size?: SizeKeyword; type?: IconType | AnyString; } -/** @publicDocs */ export interface BaseImageProps { /** * An alternative text description that describe the image for the reader to @@ -2577,7 +2492,6 @@ export interface BaseImageProps { */ srcSet?: string; } -/** @publicDocs */ export interface ImageProps extends GlobalProps, BaseImageProps, BorderProps { /** * Sets the semantic meaning of the component’s content. When set, @@ -2653,20 +2567,19 @@ export interface ImageProps extends GlobalProps, BaseImageProps, BorderProps { */ onError?: (event: Event) => void; } -/** @publicDocs */ export interface LinkProps extends GlobalProps, LinkBehaviorProps { /** - * The content of the link. + * The content of the Link. */ children?: ComponentChildren; /** - * Sets the tone of the link, based on the intention of the information being conveyed. + * 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. + * 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. @@ -2679,7 +2592,6 @@ export interface LinkProps extends GlobalProps, LinkBehaviorProps { */ lang?: string; } -/** @publicDocs */ export interface ModalProps extends GlobalProps, BaseOverlayProps, @@ -2694,36 +2606,35 @@ export interface ModalProps */ accessibilityLabel?: string; /** - * A title that describes the content of the modal. + * A title that describes the content of the Modal. * */ heading?: string; /** - * Adjust the padding around 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' + * `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'; /** - * Adjust the size of the modal. + * 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. + * `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 content of the modal. + * The content of the Modal. */ children?: ComponentChildren; } -/** @publicDocs */ export interface NumberFieldProps extends GlobalProps, BaseTextFieldProps, @@ -2753,15 +2664,13 @@ export interface NumberFieldProps */ onInput?: (event: Event) => void; } -/** @publicDocs */ export type NumberAutocompleteField = ExtractStrict< AnyAutocompleteField, 'one-time-code' | 'cc-number' | 'cc-csc' >; -/** @publicDocs */ export interface PageProps extends GlobalProps, ActionSlots { /** - * The content of the page. + * The content of the Page. */ children?: ComponentChildren; /** @@ -2795,7 +2704,6 @@ export interface PageProps extends GlobalProps, ActionSlots { */ inlineSize?: SizeKeyword; } -/** @publicDocs */ export interface POSBlockProps extends GlobalProps, Pick { @@ -2814,7 +2722,6 @@ export interface POSBlockProps */ secondaryActions?: ComponentChildren; } -/** @private */ export interface QRCodeProps extends GlobalProps { /** * Set the border of the QR code. @@ -2860,7 +2767,6 @@ export interface QRCodeProps extends GlobalProps { */ logo?: string; } -/** @publicDocs */ export interface ScrollEventProps { /** * Callback when the scroll position reaches any edge. @@ -2901,9 +2807,7 @@ export interface ScrollEventProps { */ scrollMargin?: MaybeAllValuesShorthandProperty; } -/** @publicDocs */ export type OverflowKeyword = 'auto' | 'hidden'; -/** @publicDocs */ export interface ScrollBoxProps extends GlobalProps, ScrollEventProps, @@ -2924,25 +2828,22 @@ export interface ScrollBoxProps */ overflow?: OverflowKeyword | `${OverflowKeyword} ${OverflowKeyword}`; } -/** @publicDocs */ export interface SearchFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps {} -/** @publicDocs */ export type SearchAutocompleteField = TextAutocompleteField; -/** @publicDocs */ export interface SectionProps extends GlobalProps, ActionSlots { /** - * The content of the section. + * The content of the Section. */ children?: ComponentChildren; /** * A label used to describe the section that will be announced by assistive technologies. * - * When no `heading` property is provided or included as a children of the section, you **must** provide an - * `accessibilityLabel` to describe the section. This is important as it allows assistive technologies to provide + * When no `heading` property is provided or included as a children of the Section, you **must** provide an + * `accessibilityLabel` to describe the Section. This is important as it allows assistive technologies to provide * the right context to users. */ accessibilityLabel?: string; @@ -2955,15 +2856,14 @@ export interface SectionProps extends GlobalProps, ActionSlots { * * - `base`: applies padding that is appropriate for the element. Note that it may result in no padding if * this is the right design decision in a particular context. - * - `none`: removes all padding from the element. This can be useful when elements inside the section need to span - * to the edge of the section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base' + * - `none`: removes all padding from the element. This can be useful when elements inside the Section need to span + * to the edge of the Section. For example, a full-width image. In this case, rely on `s-box` with a padding of 'base' * to bring back the desired padding for the rest of the content. * * @default 'base' */ padding?: 'base' | 'none'; } -/** @publicDocs */ export interface SpinnerProps extends GlobalProps { /** * Adjusts the size of the spinner icon. @@ -2980,17 +2880,16 @@ export interface SpinnerProps extends GlobalProps { */ accessibilityLabel?: string; } -/** @publicDocs */ export interface StackProps extends GlobalProps, BaseBoxPropsWithRole, GapProps { /** - * The content of the stack. + * The content of the Stack. */ children?: ComponentChildren; /** - * Sets how the children are placed within the stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). + * Sets how the children are placed within the Stack. This uses [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). * * @default 'block' * @@ -2998,38 +2897,36 @@ export interface StackProps */ direction?: MaybeResponsive<'block' | 'inline'>; /** - * Aligns the stack along the main axis. + * Aligns the Stack along the main axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content * @default 'normal' */ justifyContent?: MaybeResponsive; /** - * Aligns the stack's children along the cross axis. + * Aligns the Stack's children along the cross axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items * @default 'normal' */ alignItems?: MaybeResponsive; /** - * Aligns the stack along the cross axis. + * Aligns the Stack along the cross axis. * * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content * @default 'normal' */ alignContent?: MaybeResponsive; } -/** @publicDocs */ export interface SwitchProps extends GlobalProps, BaseCheckableProps, BasicFieldProps, FieldDetailsProps, FieldErrorProps {} -/** @publicDocs */ export interface TabProps extends GlobalProps { /** - * Corresponds to the `id` property of the tab panel component that will be displayed when selected + * Corresponds to the `id` property of the TabPanel component that will be displayed when selected */ controls?: string; /** @@ -3051,26 +2948,23 @@ export interface TabProps extends GlobalProps { */ children?: StringChildren; } -/** @publicDocs */ export interface TabListProps extends GlobalProps { /** - * Accepts only tabs components. + * Accepts only `Tabs` components. */ children?: ComponentChildren; } -/** @publicDocs */ export interface TabPanelProps extends GlobalProps { /** - * The id of the tab panel used for identification in the tabs component. - * Must match the `controls` prop of the corresponding tab component. + * The id of the TabPanel used for identification in the Tabs component. + * Must match the `controls` prop of the corresponding Tab component. */ id?: string; /** - * The content of the tab panel. + * The content of the TabPanel. */ children?: ComponentChildren; } -/** @publicDocs */ export interface TabsProps extends GlobalProps, Pick { @@ -3080,20 +2974,20 @@ export interface TabsProps */ accessibilityLabel?: string; /** - * Accepts only tab list and tab panel components. + * Accepts only `TabList` and `TabPanel` components. */ children?: ComponentChildren; /** * The value of the selected tab. * - * This should match the `id` prop of one of the tab panel components. + * This should match the `id` prop of one of the TabPanel components. * If not provided, the first tab will be selected by default. */ value?: string; /** * The default value of the selected tab. * - * This should match the `id` prop of one of the tab panel components. + * This should match the `id` prop of one of the TabPanel components. * If not provided, the first tab will be selected by default. * * Reflects to the `value` attribute @@ -3110,7 +3004,6 @@ export interface TabsProps */ onChange?: (event: Event) => void; } -/** @publicDocs */ export interface TextProps extends GlobalProps, AccessibilityVisibilityProps, @@ -3130,7 +3023,6 @@ export interface TextProps */ type?: TextType; } -/** @publicDocs */ export type TextType = /** * Indicate the text is contact information. Typically used for addresses. @@ -3213,7 +3105,6 @@ export type TextType = * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span */ | 'generic'; -/** @publicDocs */ export interface TextAreaProps extends GlobalProps, BaseTextFieldProps, @@ -3226,19 +3117,17 @@ export interface TextAreaProps */ rows?: number; } -/** @publicDocs */ export interface TextFieldProps extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps, FieldDecorationProps {} -/** @publicDocs */ export interface TileProps extends GlobalProps, Pick { /** - * A title that describes the content of the tile. + * A title that describes the content of the Tile. * * @default '' */ @@ -3250,7 +3139,7 @@ export interface TileProps */ subheading?: string; /** - * A numeric indicator rendered within the tile (for example, a count or a step number). + * A numeric indicator rendered within the Tile (for example, a count or a step number). * * - When provided, the indicator is displayed inside the tile. * - Intended for small integers. It may clamp, truncate, or abbreviate larger values. @@ -3258,12 +3147,11 @@ export interface TileProps */ itemCount?: number; /** - * Sets the tone of the tile, based on the intention of the information being conveyed. + * Sets the tone of the Tile, based on the intention of the information being conveyed. * @default 'auto' */ tone?: ExtractStrict; } -/** @publicDocs */ export interface TimePickerProps extends GlobalProps, InputProps, @@ -3356,7 +3244,6 @@ export interface TimePickerProps */ step?: number; } -/** @publicDocs */ export interface TimeFieldProps extends GlobalProps, BaseTextFieldProps, @@ -3414,7 +3301,6 @@ export interface TimeFieldProps // // Preact Virtual DOM // ----------------------------------- -/** @publicDocs */ export interface VNode

{ type: ComponentType

| string; props: P & { @@ -3442,17 +3328,12 @@ export interface VNode

{ // // Preact Component interface // ----------------------------------- -/** @publicDocs */ export type Key = string | number | any; -/** @publicDocs */ export type RefObject = { current: T | null; }; -/** @publicDocs */ export type RefCallback = (instance: T | null) => void | (() => void); -/** @publicDocs */ export type Ref = RefObject | RefCallback | null; -/** @publicDocs */ export type ComponentChild = | VNode | object @@ -3463,16 +3344,13 @@ export type ComponentChild = | null | undefined; type ComponentChildren$1 = ComponentChild[] | ComponentChild; -/** @publicDocs */ export interface Attributes { key?: Key | undefined; jsx?: boolean | undefined; } -/** @publicDocs */ export interface ErrorInfo { componentStack?: string; } -/** @publicDocs */ export type RenderableProps = P & Readonly< Attributes & { @@ -3480,15 +3358,12 @@ export type RenderableProps = P & ref?: Ref; } >; -/** @publicDocs */ export type ComponentType

= ComponentClass

| FunctionComponent

; -/** @publicDocs */ export interface FunctionComponent

{ (props: RenderableProps

, context?: any): ComponentChildren$1; displayName?: string; defaultProps?: Partial

| undefined; } -/** @publicDocs */ export interface ComponentClass

{ new (props: P, context?: any): Component; displayName?: string; @@ -3500,7 +3375,6 @@ export interface ComponentClass

{ ): Partial | null; getDerivedStateFromError?(error: any): Partial | null; } -/** @publicDocs */ export interface Component

{ componentWillMount?(): void; componentDidMount?(): void; @@ -3567,18 +3441,15 @@ declare abstract class Component { // // Context // ----------------------------------- -/** @publicDocs */ export interface Consumer extends FunctionComponent<{ children: (value: T) => ComponentChildren$1; }> {} -/** @publicDocs */ export interface Provider extends FunctionComponent<{ value: T; children?: ComponentChildren$1; }> {} -/** @publicDocs */ export interface Context extends Provider { Consumer: Consumer; Provider: Provider; diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts index 4282106dae..6833aa721c 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/cart.ts @@ -9,6 +9,8 @@ import {DiscountAllocation} from './discount-allocation'; export interface Cart { /** * Indicates whether the cart is currently editable. An `undefined` value should be treated as `true` for backward compatibility. Use this to determine if cart modification operations are allowed. + * + * `editable` is `false` while POS is in a return, exchange, or refund flow. In those flows the cart signal exposes an empty cart, not the lines being returned or exchanged. `editable` remains `true` during the payment flow, where POS can still refuse cart mutations. */ editable?: boolean; /** @@ -28,27 +30,27 @@ export interface Cart { */ currency: string; /** - * The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to `undefined` to remove current note. + * The current cart note, or `undefined` if no note is set. */ note?: string; /** - * The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount. + * The cart-level discount currently applied to the cart: the first manual (percentage or fixed amount) discount, or the first discount code if no manual discount exists. `undefined` if the cart has no discount. */ cartDiscount?: Discount; /** - * An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. + * The discounts currently applied to the cart. Empty array if the cart has no discounts. */ cartDiscounts: Discount[]; /** - * The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. + * The customer currently associated with the cart, or `undefined` for a guest cart. */ customer?: Customer; /** - * An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones. + * The line items currently in the cart. */ lineItems: LineItem[]; /** - * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. + * The custom key-value properties currently set on the cart. Empty object if no properties are set. */ properties: Record; } @@ -79,7 +81,7 @@ export interface CartUpdateInput { */ lineItems: LineItem[]; /** - * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. + * The custom key-value properties to apply to the cart. Merged with existing properties—duplicate keys overwrite existing values. */ properties: Record; } @@ -113,7 +115,7 @@ export interface LineItem { */ quantity: number; /** - * The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification. + * The display title of the line item. For catalog products, this is the product title; the variant title isn't included, so use `sku` or `variantId` to distinguish between variants of the same product. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification. */ title?: string; /** @@ -161,11 +163,11 @@ export interface LineItem { */ attributedUserId?: number; /** - * Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling. + * Determines whether this line item requires a selling plan (subscription) to be purchased. Always present as a boolean on POS cart state. Use for implementing subscription-based product handling. */ requiresSellingPlan?: boolean; /** - * Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options. + * Determines whether this line item has selling plan groups (subscription options) available. Always present as a boolean on POS cart state. Use for displaying subscription options. */ hasSellingPlanGroups?: boolean; /** @@ -184,19 +186,19 @@ export interface LineItem { */ export interface LineItemComponent { /** - * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. + * The display title of this bundle component. */ title?: string; /** - * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. + * The quantity of this component in each bundle line item. */ quantity: number; /** - * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing. + * The total price of this component within the bundle line, as a number. */ price?: number; /** - * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes. + * Determines whether this component is subject to tax calculations. */ taxable: boolean; /** @@ -204,7 +206,7 @@ export interface LineItemComponent { */ taxLines: TaxLine[]; /** - * An array of discount allocations applied to this component, providing a detailed breakdown of how discounts are distributed across bundle components. Returns `undefined` if no allocations exist. + * An array of discount allocations applied to this component, providing a detailed breakdown of how discounts are distributed across bundle components. Empty array if no allocations exist. */ discountAllocations?: DiscountAllocation[]; /** @@ -227,15 +229,15 @@ export interface SellingPlan { */ id: number; /** - * The name of the POS device. + * The display name of the selling plan. */ name: string; /** - * The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges. + * The fingerprint of the applied selling plan within this cart session. Not currently populated by POS on cart state; always `undefined`. */ digest?: string; /** - * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR). + * The delivery interval of the selling plan: `'Day'`, `'Week'`, `'Month'`, or `'Year'`. `undefined` if POS can't map the plan's interval. */ deliveryInterval?: string; /** @@ -254,7 +256,7 @@ export interface Discount { */ amount: number; /** - * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. + * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code for the discount. Not currently populated on POS cart state; always `undefined`. Use `Cart.currency` for the cart's currency code. */ currency?: string; /** @@ -273,7 +275,7 @@ export interface Discount { */ export interface AddLineItemOptions { /** - * Custom key-value properties to attach to the newly created line item. Equivalent to calling `addLineItemProperties` with the returned `UUID`, but applied in the same operation. + * Custom key-value properties to attach to the newly created line item. Equivalent to calling `addLineItemProperties` with the returned `UUID`, but applied in the same operation. The `'RFID Tag'` property key is reserved and isn't applied to the line item. */ properties?: Record; } @@ -284,7 +286,7 @@ export interface AddLineItemOptions { */ export interface SetLineItemPropertiesInput { /** - * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. + * The `UUID` of the line item to update. Must match an existing line item in the cart. */ lineItemUuid: string; /** @@ -299,7 +301,7 @@ export interface SetLineItemPropertiesInput { */ export interface SetLineItemDiscountInput { /** - * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. + * The `UUID` of the line item to discount. Must match an existing line item in the cart. */ lineItemUuid: string; /** @@ -314,7 +316,7 @@ export interface SetLineItemDiscountInput { */ export interface LineItemDiscount { /** - * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. + * The display title of the discount. Appears on receipts and in cart displays. */ title: string; /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts index ca51199514..3e81c1ed40 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/device.ts @@ -8,7 +8,7 @@ export interface Device { */ name: string; /** - * The unique identifier for the POS device. + * The numeric Shopify POS device ID (the same value as `shopify.session.deviceId`). This differs from the string returned by `shopify.device.getDeviceId()`. */ deviceId: number; /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts index b6b5d8414a..a860792790 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/payment.ts @@ -1,5 +1,10 @@ /** * The available payment method types for POS transactions. + * + * Not every value is produced in every context. `Unknown` is returned only for + * sale transactions whose payment details can't be classified. On return and + * exchange transactions, unrecognized payment gateways are returned as + * `Custom`. `CardPresentRefund` isn't currently returned by POS. * @publicDocs */ export type PaymentMethod = diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts index 0bf183880e..d16967e644 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts @@ -35,7 +35,7 @@ export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10; */ export interface PinPadActionType { /** - * The content for the prompt on the pin pad. Use to provide clear instructions or context about what the PIN is being used for. + * The label of the custom action button shown between the entry view and the keypad. */ label: string; /** diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/types/storage.ts b/packages/ui-extensions/src/surfaces/point-of-sale/types/storage.ts index 62146b6765..33d0b264f3 100644 --- a/packages/ui-extensions/src/surfaces/point-of-sale/types/storage.ts +++ b/packages/ui-extensions/src/surfaces/point-of-sale/types/storage.ts @@ -47,15 +47,16 @@ export interface Storage< current: SubscribableStorage; /** - * Stores a value under the specified key, overwriting any existing value. Values must be JSON-serializable and return `StorageError` when storage limits are exceeded. Commonly used for storing user preferences, caching API responses, or passing contextual data from tiles to modals. + * Stores a value under the specified key, overwriting any existing value. Values must be JSON-serializable, and the promise rejects with an error named `'StorageError'` when storage validation or limits fail. Values are JSON-serialized on write: `undefined` properties are dropped, `NaN` and `Infinity` become `null`, and `Date` objects become ISO strings. Keys are limited to 1024 UTF-16 code units, and values to 1,048,576 code units of their JSON serialization. Commonly used for storing user preferences, caching API responses, or passing contextual data from tiles to modals. * * @param key - The key to set the value for. * @param value - The value to set for the key. - * @throws StorageError when: - * - Maximum number of records is exceeded (`code: 'RecordsCount'`) - * - Individual record size exceeds the limit (`code: 'RecordSize'`) - * - Key is not a string (`code: 'KeyType'`) - * - Key size exceeds the limit (`code: 'KeySize'`) + * @throws an error with `name` set to `'StorageError'` when: + * - Maximum number of records is exceeded + * - Individual record size exceeds the limit + * - Key is not a string + * - Key size exceeds the limit + * The rejection preserves the error's `name` and `message`, but not its `code` property. Match on `name`, not on `code` or `instanceof`, and treat the `message` as diagnostic text rather than a stable contract. Other storage or native failures can reject with a different error name. */ set< StorageTypes extends BaseStorageTypes = BaseStorageTypes,