diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Abbreviation.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Abbreviation.d.ts index 707aa53a75..74d7a26fd8 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Abbreviation.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Abbreviation.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-abbreviation"; /** - * The element props interface for the Abbreviation component. + * Configure the following properties on the abbreviation component. * @publicDocs */ export interface AbbreviationElementProps extends Pick { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts index 1c3a4d69a8..bc4cecdd2e 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts @@ -27,20 +27,18 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-chip"; /** - * The element props interface for the Chip component. + * Configure the following properties on the chip component. * @publicDocs */ export interface ChipElementProps extends Pick { } /** - * The slots interface for the Chip component. + * The chip component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ export interface ChipElementSlots { /** - * The graphic to display inside of the chip. - * - * Only `s-icon` element and its `type` attribute are supported. + * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported. */ graphic?: HTMLElement; } diff --git a/packages/ui-extensions/src/surfaces/checkout/components/ClickableChip.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/ClickableChip.d.ts index d84c37c629..dd872851bd 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/ClickableChip.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/ClickableChip.d.ts @@ -67,14 +67,12 @@ export interface ClickableChipElementEvents { remove?: CallbackEventListener; } /** - * The clickable chip component supports slots for additional content placement. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). + * The clickable chip component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots). * @publicDocs */ export interface ClickableChipElementSlots { /** - * The graphic to display inside of the chip. - * - * Only `s-icon` element and its `type` attribute are supported. + * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported. */ graphic?: HTMLElement; } diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts index 5f1aab1825..edcfc8a032 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Details.d.ts @@ -44,7 +44,7 @@ export interface ToggleArgumentsEvent { declare const tagName = "s-details"; /** - * The element props interface for the Details component. + * Configure the following properties on the details component. * @publicDocs */ export interface DetailsElementProps extends Pick { @@ -52,33 +52,30 @@ export interface DetailsElementProps extends Pick { } /** - * The events interface for the Details component. + * The details component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events). * @publicDocs */ export interface DetailsElementEvents { /** - * Callback straight after the element state changes. + * A callback fired immediately when the element state changes, before any animations. * * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event - * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState - * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState + * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and the [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). */ toggle?: CallbackEventListener; /** - * Callback fired when the element state changes **after** any animations have finished. + * A callback fired when the element state changes, after any toggle animations have finished. * * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState - * @see https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState + * Learn more about the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). */ aftertoggle?: CallbackEventListener; } diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts index 736f79c3dc..ed1e23ce2b 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Heading.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-heading"; /** - * The element props interface for the Heading component. + * Configure the following properties on the heading component. * @publicDocs */ export interface HeadingElementProps extends Pick { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/ListItem.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/ListItem.d.ts index b4d7153cc6..e9f6eeb593 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/ListItem.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/ListItem.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-list-item"; /** - * The element props interface for the ListItem component. + * Configure the following properties on the list item component. * @publicDocs */ export interface ListItemElementProps extends Pick { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/OrderedList.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/OrderedList.d.ts index 23fcd42cc4..2f964736dd 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/OrderedList.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/OrderedList.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-ordered-list"; /** - * The element props interface for the OrderedList component. + * Configure the following properties on the ordered list component. * @publicDocs */ export interface OrderedListElementProps extends OrderedListProps$1 { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts index fdf3dbe18d..a528730ade 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Paragraph.d.ts @@ -27,12 +27,23 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-paragraph"; /** - * The element props interface for the Paragraph component. + * Configure the following properties on the paragraph component. * @publicDocs */ export interface ParagraphElementProps extends Pick { color?: Extract; tone?: Extract; + /** + * The semantic type and styling treatment for the paragraph content. + * + * Other presentation properties on `s-paragraph` override the default styling. + * + * - `paragraph`: A semantic type that indicates the text is a structural grouping of related content. + * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * + * @default 'paragraph' + */ + type?: Extract; } export interface ParagraphElement extends ParagraphElementProps, Omit { } diff --git a/packages/ui-extensions/src/surfaces/checkout/components/SkeletonParagraph.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/SkeletonParagraph.d.ts index 2fcd11e7e3..e167d16f40 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/SkeletonParagraph.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/SkeletonParagraph.d.ts @@ -21,7 +21,7 @@ export interface BaseElementProps { declare const tagName = "s-skeleton-paragraph"; /** - * The element props interface for the SkeletonParagraph component. + * Configure the following properties on the skeleton paragraph component. * @publicDocs */ export interface SkeletonParagraphElementProps extends SkeletonParagraphProps$1 { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Summary.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Summary.d.ts index ace5b8d64f..2685fe080a 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Summary.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Summary.d.ts @@ -12,7 +12,7 @@ import type {SummaryProps$1} from './components-shared.d.ts'; declare const tagName = "s-summary"; /** - * The element props interface for the Summary component. + * Configure the following properties on the summary component. * @publicDocs */ export interface SummaryElementProps extends Pick { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts index 0d1c1095ff..4cafe796a8 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Text.d.ts @@ -27,12 +27,28 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-text"; /** - * The element props interface for the Text component. + * Configure the following properties on the text component. * @publicDocs */ export interface TextElementProps extends Pick { color?: Extract; tone?: Extract; + /** + * The semantic type and styling treatment for the text content. + * + * Other presentation properties on text override the default styling. + * + * - `address`: A semantic type that indicates the text is contact information. Typically used for addresses. + * - `redundant`: A semantic type that indicates the text is no longer accurate or no longer relevant. One such use-case is discounted prices. + * - `mark`: A semantic type that indicates the text is marked or highlighted and relevant to the user's current action. + * - `emphasis`: A semantic type that indicates emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text. + * - `offset`: A semantic type that indicates an offset from the normal prose of the text. + * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * - `strong`: A semantic type that indicates strong importance, seriousness, or urgency. + * - `generic`: No additional semantics or styling is applied. + * + * @default 'generic' + */ type?: Extract; } export interface TextElement extends TextElementProps, Omit { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts index d93c119b09..c36d2c843f 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/Time.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-time"; /** - * The element props interface for the Time component. + * Configure the following properties on the time component. * @publicDocs */ export interface TimeElementProps extends Pick { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/UnorderedList.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/UnorderedList.d.ts index 0217a95f61..8145960073 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/UnorderedList.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/UnorderedList.d.ts @@ -27,7 +27,7 @@ export interface BaseElementPropsWithChildren extends Base declare const tagName = "s-unordered-list"; /** - * The element props interface for the UnorderedList component. + * Configure the following properties on the unordered list component. * @publicDocs */ export interface UnorderedListElementProps extends UnorderedListProps$1 { diff --git a/packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts b/packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts index 185143ba0e..4efcbaf52f 100644 --- a/packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts +++ b/packages/ui-extensions/src/surfaces/checkout/components/components-shared.d.ts @@ -14,23 +14,21 @@ export type ComponentChildren = any; export type StringChildren = string; export interface GlobalProps { /** - * A unique identifier for the element. + * A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting. */ id?: string; } interface AbbreviationProps$1 extends GlobalProps { /** - * The content of the abbreviation or acronym. + * The abbreviated text content displayed within the abbreviation component. Pair with the `title` attribute to provide the full expansion for accessibility. */ children?: ComponentChildren; /** - * Defines the full expansion of the abbreviation or acronym. + * Defines the full expansion of the abbreviation or acronym. Helps user agents and users understand the meaning of the abbreviated text. * - * Helps user agents and users understand the meaning of the abbreviated text. + * Learn more about the [abbreviation element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr). * * @default '' - * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr */ title?: string; } @@ -102,25 +100,25 @@ export interface FocusEventProps { } export interface ToggleEventProps { /** - * A callback that fires when the element state changes, after any toggle animations have finished. + * A callback fired when the element state changes, after any toggle animations have finished. * * - If the element transitioned from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). + * Learn more about the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). */ onAfterToggle?: (event: ToggleEvent$1) => void; /** - * A callback that fires immediately when the element state changes, before any animations. + * A callback fired immediately when the element state changes, before any animations. * * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the * `newState` property will be set to `open`. * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the * `newState` will be `closed`. * - * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). + * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), the [newState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and the [oldState property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState). */ onToggle?: (event: ToggleEvent$1) => void; } @@ -907,10 +905,11 @@ 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). * - * - `auto`: the component’s initial value. The actual value depends on the component and context. - * - `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers. + * - `auto`: The component’s initial value. The actual value depends on the component and context. + * - `none`: Hides the component from display and removes it from the accessibility tree, making it invisible to screen readers. + * + * Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display). * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display * @default 'auto' */ display?: MaybeResponsive<"auto" | "none">; @@ -1060,11 +1059,11 @@ export type AccessibilityRole = | "none"; export interface AccessibilityVisibilityProps { /** - * Changes the visibility of the element. + * The visibility mode of the element for both visual and assistive technology users. * - * - `visible`: the element is visible to all users. - * - `hidden`: the element is removed from the accessibility tree but remains visible. - * - `exclusive`: the element is visually hidden but remains in the accessibility tree. + * - `visible`: The element is visible to all users (both sighted users and screen readers). + * - `hidden`: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information. + * - `exclusive`: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context. * * @default 'visible' */ @@ -1817,11 +1816,11 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro } export interface ChipProps$1 { /** - * The content of the chip. + * The text label displayed within the chip, which identifies the chip's value or category to users. */ children?: ComponentChildren; /** - * The graphic to display inside of the chip. + * An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. * * @implementation Only `s-icon` is supported. */ @@ -1831,7 +1830,10 @@ export interface ChipProps$1 { */ accessibilityLabel?: string; /** - * Modify the color to be more or less intense. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. * * @default 'base' */ @@ -1935,9 +1937,9 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps */ disabled?: BaseClickableProps["disabled"]; /** - * Indicate the text language. Useful when the text is in a different language than the rest of the page. - * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. - * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label) + * The language of the text content. Use this when the text is in a different language than the rest of the page, allowing assistive technologies such as screen readers to invoke the correct pronunciation. + * + * The value should be a valid language subtag from the [IANA language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). * * @default '' */ @@ -1945,7 +1947,7 @@ interface ClickableProps$1 extends GlobalProps, BaseBoxProps, BaseClickableProps } interface ClickableChipProps$1 extends ChipProps$1, GlobalProps { /** - * Callback when the chip is clicked. + * A callback fired when the chip is clicked. Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event). */ onClick?: (event: Event) => void; /** @@ -1953,13 +1955,13 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps { */ href?: string; /** - * Whether the chip is removable. + * Whether the chip displays a remove button, allowing users to dismiss it. When `true`, clicking the remove button fires the `remove` event. * * @default false */ removable?: boolean; /** - * Callback when the chip is removed. + * A callback fired when the chip is removed by the user clicking the remove button. */ onRemove?: (event: Event) => void; /** @@ -1975,7 +1977,7 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps { */ hidden?: boolean; /** - * Event handler when the chip has fully hidden. + * A callback fired when the chip has fully hidden after a removal animation. * * The `hidden` property will be `true` when this event fires. * @@ -1985,7 +1987,7 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps { */ onAfterHide?: (event: Event) => void; /** - * Disables the chip, disallowing any interaction. + * Disables the chip, preventing all user interaction including clicks and removal. Disabled chips are visually dimmed to indicate they are not interactive. * * @default false */ @@ -2253,37 +2255,34 @@ interface DateFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick; interface DetailsProps$1 extends GlobalProps, ToggleEventProps { /** - * The content of the details. + * The content displayed within the details component, which creates a collapsible disclosure widget. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details + * Learn more about the [details element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details). */ children?: ComponentChildren; /** - * Name of the element. - * - * This can be used to create multiple named disclosure boxes that where only one can be open at a time. + * The name attribute for the element. Use this to create multiple named disclosure groups where only one can be open at a time. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#multiple_named_disclosure_boxes + * Learn more about [multiple named disclosure boxes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#multiple_named_disclosure_boxes). */ name?: string; /** - * Whether the element is open. - * - * This does not reflect to any attribute. + * Whether the element is currently open and showing its content. Use this for controlled behavior where you manage the open state yourself. * * @default false */ open?: boolean; /** - * Indicates whether the element should be open by default. - * - * This reflects to the `open` attribute. + * Whether the element should be open when it first renders. Use this for uncontrolled behavior where the component manages its own open state after the initial render. * * @default false */ defaultOpen?: boolean; /** - * Sets the transition between the two states. + * Sets the animation transition between the open and closed states. + * + * - `none`: Disables all transition animations. + * - `auto`: Uses the default transition animation. * * @default 'auto' */ @@ -2488,29 +2487,46 @@ interface GridItemProps$1 extends GlobalProps, BaseBoxPropsWithRole { } export interface BaseTypographyProps { /** - * Modify the color to be more or less intense. + * The color emphasis level that controls visual intensity. + * + * - `base`: Primary color for body text, standard UI elements, and general content with good readability. + * - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. * * @default 'base' */ color?: ColorKeyword; /** - * Sets the tone of the component, based on the intention of the information being conveyed. + * The semantic meaning and color treatment of the component. + * + * - `auto`: Automatically determined based on context. + * - `neutral`: General information without specific intent. + * - `info`: Informational content or helpful tips. + * - `success`: Positive outcomes or successful states. + * - `caution`: Advisory notices that need attention. + * - `warning`: Important warnings about potential issues. + * - `critical`: Urgent problems or destructive actions. + * - `accent`: Highlighted or promotional content. + * - `custom`: Custom styling controlled by your theme. * * @default 'auto' */ tone?: ToneKeyword; /** - * Set the numeric properties of the font. + * The rendering style for numbers in the font. + * + * - `auto`: Inherits the setting from the parent element. + * - `normal`: Uses the font's default numeric glyphs. + * - `tabular-nums`: Uses fixed-width numeric glyphs, ensuring numbers align vertically in tables or lists. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric + * Learn more about the [font-variant-numeric property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric). * - * @default 'auto' - inherit from the parent element + * @default 'auto' */ fontVariantNumeric?: "auto" | "normal" | "tabular-nums"; /** - * Indicate the text language. Useful when the text is in a different language than the rest of the page. - * It will allow assistive technologies such as screen readers to invoke the correct pronunciation. - * [Reference of values](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) (`Subtag` label) + * The language of the text content. Use this when the text is in a different language than the rest of the page, allowing assistive technologies such as screen readers to invoke the correct pronunciation. + * + * The value should be a valid language subtag from the [IANA language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). * * It is recommended to combine it with the `dir` attribute to ensure the text is rendered correctly if the surrounding content’s direction is different. * @@ -2520,12 +2536,12 @@ export interface BaseTypographyProps { /** * Indicates the directionality of the element’s text. * - * - `ltr`: languages written from left to right (such as English) - * - `rtl`: languages written from right to left (such as Arabic) - * - `auto`: the user agent determines the direction based on the content - * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute) + * - `ltr`: The languages written from left to right (such as English). + * - `rtl`: The languages written from right to left (such as Arabic). + * - `auto`: The user agent determines the direction based on the content. + * - `""`: The direction is inherited from parent elements (equivalent to not setting the attribute). * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir + * Learn more about the [dir attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir). * * @default '' */ @@ -2533,9 +2549,9 @@ export interface BaseTypographyProps { } export interface BlockTypographyProps { /** - * Truncates the text content to the specified number of lines. + * The maximum number of lines to display before truncating the text content. * - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp + * Learn more about the [-webkit-line-clamp property](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp). * * @default Infinity - no truncation is applied */ @@ -2543,19 +2559,16 @@ export interface BlockTypographyProps { } interface HeadingProps$1 extends GlobalProps, AccessibilityVisibilityProps, BlockTypographyProps { /** - * The content of the Heading. + * The heading text displayed within the heading component, which provides a title or section header for content. */ children?: ComponentChildren; /** - * Sets the semantic meaning of the component’s content. When set, + * The semantic meaning of the component’s content. When set, * the role will be used by assistive technologies to help users * navigate the page. * - * - `heading`: defines the element as a heading to a page or section. - * - `presentation`: the heading level will be stripped, - * and will prevent the element’s implicit ARIA semantics from - * being exposed to the accessibility tree. - * - `none`: a synonym for the `presentation` role. + * - `presentation`: Removes semantic meaning, making the element purely decorative and ignored by screen readers. + * - `none`: Completely hides the element and its content from assistive technologies. * * @default 'heading' * @@ -2737,7 +2750,7 @@ interface LinkProps$1 extends GlobalProps, LinkBehaviorProps { } interface ListItemProps$1 extends GlobalProps { /** - * The content of the ListItem. + * The content displayed within the list item, which represents a single entry in an ordered or unordered list. */ children?: ComponentChildren; } @@ -2949,11 +2962,11 @@ interface OrderedListProps$1 extends GlobalProps { } interface ParagraphProps$1 extends GlobalProps, BaseTypographyProps, BlockTypographyProps, AccessibilityVisibilityProps { /** - * The content of the Text. + * The paragraph text content displayed within the paragraph component, which presents a block of related text with appropriate styling. */ children?: ComponentChildren; /** - * Provide semantic meaning and default styling to the paragraph. + * The semantic type and styling treatment for the paragraph content. * * Other presentation properties on `s-paragraph` override the default styling. * @@ -2963,20 +2976,19 @@ interface ParagraphProps$1 extends GlobalProps, BaseTypographyProps, BlockTypogr } export type ParagraphType = /** - * Indicate the text is a structural grouping of related content. + * A semantic type that indicates the text is a structural grouping of related content. * - * In an HTML host, the text will be rendered in an `

` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p + * In an HTML host, the text will be rendered in an `

` element. Learn more about the [p element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p). */ "paragraph" /** - * Indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * * It can be used for secondary content but also for disclaimers, terms and conditions, or legal information. * * Surfaces should apply a smaller font size than the default size. * - * In an HTML host, the text will be rendered in a `` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small + * In an HTML host, the text will be rendered in a `` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small). */ | "small"; interface PasswordFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps { @@ -3270,12 +3282,12 @@ interface StackProps$1 extends GlobalProps, BaseBoxPropsWithRole, GapProps { } interface SummaryProps$1 extends GlobalProps { /** - * The content to use as the label. + * The content displayed as the clickable label of the disclosure widget. This label is always visible and users interact with it to toggle the details content open or closed. * - * Interactive content is disallowed. For example, you can use a `` element for extra formatting but + * Interactive content is disallowed. For example, you can use an `s-text` element for extra formatting but * elements like buttons and fields are not allowed. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary + * Learn more about the [summary element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary). * * @implementation Surfaces may apply styling to this element. An icon suggesting the state (open or closed) of the * details element is recommended. @@ -3288,13 +3300,13 @@ interface SwitchProps$1 extends GlobalProps, BaseCheckableProps, BasicFieldProps } interface TextProps$1 extends GlobalProps, AccessibilityVisibilityProps, BaseTypographyProps, DisplayProps, Pick { /** - * The content of the Text. + * The text content displayed within the text component, which applies semantic meaning and styling appropriate to the specified text type. */ children?: ComponentChildren; /** - * Provide semantic meaning and default styling to the text. + * The semantic type and styling treatment for the text content. * - * Other presentation properties on Text override the default styling. + * Other presentation properties on text override the default styling. * * @default 'generic' */ @@ -3302,7 +3314,7 @@ interface TextProps$1 extends GlobalProps, AccessibilityVisibilityProps, BaseTyp } export type TextType = /** - * Indicate the text is contact information. Typically used for addresses. + * A semantic type that indicates the text is contact information. Typically used for addresses. * * This must have `inline` layout (despite the default being `block` in HTML hosts). * @@ -3312,65 +3324,60 @@ export type TextType = * * @implementation vertical alignment should be `baseline` (`vertical-align: baseline`) * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address + * Learn more about the [address element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address). */ "address" /** - * Indicate the text is no longer accurate or no longer relevant. One such use-case is discounted prices. + * A semantic type that indicates the text is no longer accurate or no longer relevant. One such use-case is discounted prices. * * Surfaces should apply styling to this type to suggest its content no longer applies. * - * In an HTML host, the text will be rendered in a `` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s + * In an HTML host, the text will be rendered in a `` element. Learn more about the [s element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s). */ | "redundant" /** - * Indicate the text is marked or highlighted and relevant to the user’s current action. + * A semantic type that indicates the text is marked or highlighted and relevant to the user’s current action. * One such use-case is to indicate the characters that matched a search query. * * Surfaces should apply styling to this type to draw attention to the content. * - * In an HTML host, the text will be rendered in a `` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark + * In an HTML host, the text will be rendered in a `` element. Learn more about the [mark element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark). */ | "mark" /** - * Indicate emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text. + * A semantic type that indicates emphatic stress. Typically for words that have a stressed emphasis compared to surrounding text. * * Surfaces should apply styling to this type to distinguish it from surrounding text. Italicization is a common choice, but not required. * - * In an HTML host, the text will be rendered in an `` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em + * In an HTML host, the text will be rendered in an `` element. Learn more about the [em element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em). */ | "emphasis" /** - * Indicate an offset from the normal prose of the text. Typically used to indicate - * a foreign word, fictional character thoughts, or when the text refers to the definition of a word - * instead of representing its semantic meaning. + * A semantic type that indicates an offset from the normal prose of the text. + * + * Typically used to indicate a foreign word, fictional character thoughts, or when the text refers to the definition of a word instead of representing its semantic meaning. * * Surfaces should italicize this content by default. * - * In an HTML host, the text will be rendered in a `` tag. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i + * In an HTML host, the text will be rendered in a `` tag. Learn more about the [i element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i). */ | "offset" /** - * Indicate strong importance, seriousness, or urgency. + * A semantic type that indicates strong importance, seriousness, or urgency. * * Surfaces should render this content bold by default. * - * In an HTML host, the text will be rendered in a `` tag. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong + * In an HTML host, the text will be rendered in a `` tag. Learn more about the [strong element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong). */ | "strong" /** - * Indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand. + * * It can be used for secondary content but also for disclaimers, terms and conditions, or legal information. * * Surfaces should apply a smaller font size than the default size. * - * In an HTML host, the text will be rendered in a `` element. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small + * In an HTML host, the text will be rendered in a `` element. Learn more about the [small element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small). */ | "small" /** @@ -3378,8 +3385,7 @@ export type TextType = * * Surfaces must not apply any default styling to this type. * - * In an HTML host, the text will be rendered in a `` tag. - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span + * In an HTML host, the text will be rendered in a `` tag. Learn more about the [span element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span). */ | "generic"; interface TextAreaProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps { @@ -3394,15 +3400,13 @@ interface TextFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLength } interface TimeProps$1 extends GlobalProps { /** - * The content of the Time. + * The text content displayed within the time component, representing a human-readable date or time value. */ children?: ComponentChildren; /** - * Set the time and/or date of the element. - * - * It must be a [valid date string](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values). + * The machine-readable date and/or time value for the element. Use this to provide a datetime string that browsers, search engines, and assistive technologies can parse for improved semantics and functionality. * - * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time#valid_datetime_values + * The value must be a [valid datetime string](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values), such as `2024-01-15`, `14:30`, or `2024-01-15T14:30:00`. * * @default '' */ diff --git a/packages/ui-extensions/src/surfaces/customer-account/components/OrderedList/OrderedList.doc.ts b/packages/ui-extensions/src/surfaces/customer-account/components/OrderedList/OrderedList.doc.ts index 4522b1065f..39dbbfd1a2 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/components/OrderedList/OrderedList.doc.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/components/OrderedList/OrderedList.doc.ts @@ -12,7 +12,7 @@ const data: ReferenceEntityTemplateSchema = createComponentDoc({ definitions: {properties: true}, }, bestPractices: `- Use \`s-ordered-list\` when you need to present items in a specific sequence or order. -- Each item in the list should be wrapped in a \`s-list-item\` component. +- Each item in the list should be wrapped in an \`s-list-item\` component. - Keep list items concise and consistent in length when possible. - Use \`s-ordered-list\` for step-by-step instructions, numbered procedures, or ranked items. - Consider using \`s-ordered-list\` when the order of items is important for understanding.`, diff --git a/packages/ui-extensions/src/surfaces/customer-account/components/Time/Time.doc.ts b/packages/ui-extensions/src/surfaces/customer-account/components/Time/Time.doc.ts index d8b1838341..00bdc20e65 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/components/Time/Time.doc.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/components/Time/Time.doc.ts @@ -6,11 +6,11 @@ import {createComponentDoc} from '../../../../docs/shared/component-definitions' const data: ReferenceEntityTemplateSchema = createComponentDoc({ ...sharedContent, definitions: {properties: true}, - bestPractices: `- Use the Time component for all time values to keep formatting consistent. + bestPractices: `- Use the time component for all time values to keep formatting consistent. - Show times in a clear, readable format. - Consider 24-hour format for international audiences. - Include timezone information when relevant. -- Use the Time component for time-related content to maintain clear semantics.`, +- Use the time component for time-related content to maintain clear semantics.`, }); export default data; diff --git a/packages/ui-extensions/src/surfaces/customer-account/components/UnorderedList/UnorderedList.doc.ts b/packages/ui-extensions/src/surfaces/customer-account/components/UnorderedList/UnorderedList.doc.ts index 9756c11565..201d0f6143 100644 --- a/packages/ui-extensions/src/surfaces/customer-account/components/UnorderedList/UnorderedList.doc.ts +++ b/packages/ui-extensions/src/surfaces/customer-account/components/UnorderedList/UnorderedList.doc.ts @@ -12,7 +12,7 @@ const data: ReferenceEntityTemplateSchema = createComponentDoc({ definitions: {properties: true}, }, bestPractices: `- Use \`s-unordered-list\` when you need to present a list of related items or options. -- Each item in the list should be wrapped in a \`s-list-item\` component. +- Each item in the list should be wrapped in an \`s-list-item\` component. - Keep list items concise and consistent in length when possible. - Use \`s-unordered-list\` for navigation menus, feature lists, or any collection of related items. - Consider using \`s-unordered-list\` when you want to present information in a clear, scannable format.`,