Improve descriptions for layout and structure components

Author: mcvinci

packages/ui-extensions/src/surfaces/checkout/components/BlockLayout/BlockLayout.ts

@@ -5,43 +5,28 @@ import type {Rows} from '../shared';
 import type {GridProps} from '../Grid/Grid';
 
 /**
- * BlockLayout is used to lay out content over multiple rows.
-
-By default, all rows fill the available block space, sharing it equally.
  * @publicDocs
  */
 export interface BlockLayoutProps extends Omit<GridProps, 'columns' | 'rows'> {
   /**
-   * Sizes for each row of the layout.
-   *
-   *
-   * `auto`: intrinsic size of the element.
-   *
-   * `fill`: fills the remaining available space. When multiple elements are set to `fill`, the remaining space is shared equally.
-   *
-   * `` `${number}%` ``: size in percentages.
-   *
-   * `` `${number}fr` ``: size in fractions.
-   *
-   * `number`: size in pixels.
-   *
-   *
-   * - When the sum of the defined sizes is larger than the available space, elements will shrink to avoid overflow.
-   *
-   * - When the size of an element is not explicitly set, it will fill the remaining space available.
+   * The sizes for each row of the layout.
    *
-   * - When only one size is set and outside of an array, all elements of the layout will take that size.
+   * - `auto`: The intrinsic size of the element.
+   * - `fill`: Fills the remaining available space. When multiple elements use `fill`, the space is shared equally.
+   * - `` `${number}%` ``: A percentage of the container's block size.
+   * - `` `${number}fr` ``: A fractional unit of the available space.
+   * - `number`: A fixed size in pixels.
    *
+   * When the sum of defined sizes exceeds the available space, elements shrink to avoid overflow. Elements without an explicit size fill the remaining space. A single value outside an array applies to all rows.
    *
    * @defaultValue 'fill'
    */
   rows?: MaybeResponsiveConditionalStyle<Rows>;
 }
 
 /**
- * BlockLayout is used to lay out content over multiple rows.
- *
- * By default, all rows fill the available block space, sharing it equally.
+ * BlockLayout arranges content over multiple rows. By default, all rows
+ * fill the available block space, sharing it equally.
  */
 export const BlockLayout = createRemoteComponent<
   'BlockLayout',

packages/ui-extensions/src/surfaces/checkout/components/BlockSpacer/BlockSpacer.ts

@@ -4,25 +4,21 @@ import type {MaybeResponsiveConditionalStyle} from '../../style/types';
 import type {IdProps, Spacing} from '../shared';
 
 /**
- * BlockSpacer is used to create empty block space, typically when variable spacing is needed between multiple elements.
-
-Note that you should favor BlockStack when spacing between all elements is the same.
  * @publicDocs
  */
 export interface BlockSpacerProps extends IdProps {
   /**
-   * Adjust size of the spacer
+   * The size of the spacer.
    *
    * @defaultValue 'base'
    **/
   spacing?: MaybeResponsiveConditionalStyle<Spacing>;
 }
 
 /**
- * BlockSpacer is used to create empty block space, typically when variable spacing
- * is needed between multiple elements.
- *
- * Note that you should favor BlockStack when spacing between all elements is the same.
+ * BlockSpacer creates empty block-axis space, typically when variable spacing
+ * is needed between elements. Use BlockStack instead when spacing between all
+ * elements is the same.
  */
 export const BlockSpacer = createRemoteComponent<
   'BlockSpacer',

packages/ui-extensions/src/surfaces/checkout/components/BlockStack/BlockStack.ts

@@ -14,7 +14,6 @@ import type {
 import type {MaybeResponsiveConditionalStyle} from '../../style/types';
 
 /**
- * BlockStack is used to vertically stack elements.
  * @publicDocs
  */
 export interface BlockStackProps
@@ -25,63 +24,43 @@ export interface BlockStackProps
     SizingProps,
     SpacingProps {
   /**
-   * Position children along the main axis
+   * The alignment of children along the inline (main) axis.
    */
   inlineAlignment?: MaybeResponsiveConditionalStyle<InlineAlignment>;
   /**
-   * Adjust spacing between children
+   * The spacing between child elements.
    *
    * @defaultValue 'base'
    */
   spacing?: MaybeResponsiveConditionalStyle<Spacing>;
   /**
-   * Sets the semantic meaning of the component’s content. When set,
-   * the role will be used by assistive technologies to help buyers
-   * navigate the page.
-   *
-   *
-   * For example:
-   *
-   * - In an HTML host a `['listItem', 'separator']` tuple will render: `<li role='separator'>`
-   *
-   * - In an HTML host a `listItem` string will render: `<li>`
+   * The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page. Accepts a single role or a tuple of two roles (for example, `['listItem', 'separator']`).
    */
   accessibilityRole?: ViewLikeAccessibilityRole;
   /**
-   * A label that describes the purpose or contents of the element. When set,
-   * it will be announced to buyers using assistive technologies and will
-   * provide them with more context.
+   * A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.
    */
   accessibilityLabel?: string;
   /**
-   * Sets the overflow behavior of the element.
-   *
-   * `hidden`: clips the content when it is larger than the element’s container.
-   * The element will not be scrollable and the users will not be able
-   * to access the clipped content by dragging or using a scroll wheel.
+   * The overflow behavior of the element.
    *
-   * `visible`: the content that extends beyond the element’s container is visible.
+   * - `visible`: Content that extends beyond the container is visible.
+   * - `hidden`: Content that extends beyond the container is clipped and not scrollable.
    *
    * @default 'visible'
    */
   overflow?: 'hidden' | 'visible';
   /**
-   * Changes the display of the component.
+   * The display mode of the component. Learn more about [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/display).
    *
-   * `auto` the component's initial value. The actual value depends on the component and context.
-   *
-   * `none` hides the component and removes it from the accessibility tree, making it invisible to screen readers.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+   * - `auto`: The initial value; the actual behavior depends on the component and context.
+   * - `none`: Hides the component and removes it from the accessibility tree.
    *
    * @defaultValue 'auto'
    */
   display?: MaybeResponsiveConditionalStyle<'auto' | 'none'>;
 }
 
-/**
- * BlockStack is used to vertically stack elements.
- */
 export const BlockStack = createRemoteComponent<'BlockStack', BlockStackProps>(
   'BlockStack',
 );

packages/ui-extensions/src/surfaces/checkout/components/Divider/Divider.ts

@@ -3,34 +3,42 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {Alignment, Direction, IdProps, Size} from '../shared';
 
 /**
- * A divider separates content and represents a thematic break between elements.
  * @publicDocs
  */
 export interface DividerProps extends IdProps {
   /**
-   * Use to create dividers with varying widths.
+   * The thickness of the divider line.
+   *
+   * - `small`: A thin, subtle line.
+   * - `base`: The standard divider thickness.
+   * - `large`: A thicker line for stronger visual separation.
+   * - `extraLarge`: The thickest available line.
    *
    * @defaultValue 'small'
    */
   size?: Extract<Size, 'small' | 'base' | 'large' | 'extraLarge'>;
 
   /**
-   * Use to specify direction of divider.
+   * The orientation of the divider, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
+   *
+   * - `inline`: A horizontal divider that separates content stacked vertically.
+   * - `block`: A vertical divider that separates content arranged horizontally.
    *
    * @defaultValue 'inline'
    */
   direction?: Direction;
 
   /**
-   * Use to specify alignment of contents of divider.
+   * The alignment of the divider's content within its container.
    *
    * @defaultValue 'center'
    */
   alignment?: Alignment;
 }
 
 /**
- * A divider separates content and represents a thematic break between elements.
+ * A visual separator that draws a line between adjacent sections of content,
+ * representing a thematic break.
  */
 export const Divider = createRemoteComponent<'Divider', DividerProps>(
   'Divider',

packages/ui-extensions/src/surfaces/checkout/components/Grid/Grid.ts

@@ -17,7 +17,6 @@ import type {
 } from '../shared';
 
 /**
- * Grid is used to lay out content in a matrix of rows and columns.
  * @publicDocs
  */
 export interface GridProps
@@ -28,115 +27,73 @@ export interface GridProps
     SizingProps,
     SpacingProps {
   /**
-   * Sizes for each column of the layout.
+   * The sizes for each column of the grid.
    *
+   * - `auto`: The intrinsic size of the content.
+   * - `fill`: Fills the remaining available space. When multiple columns use `fill`, the space is shared equally.
+   * - `` `${number}%` ``: A percentage of the container's inline size.
+   * - `` `${number}fr` ``: A fractional unit of the available space.
+   * - `number`: A fixed size in pixels.
    *
-   * `auto`: intrinsic size of the content.
-   *
-   * `fill`: fills the remaining available space. When multiple columns are set to `fill`, the remaining space is shared equally.
-   *
-   * `` `${number}%` ``: size in percentages.
-   *
-   * `` `${number}fr` ``: size in fractions.
-   *
-   * `number`: size in pixels.
-   *
-   *
-   * - When the sum of the defined sizes is larger than the available space, elements will shrink to avoid overflow.
-   * - Except when in scrollview, where the grid will fill the space with the defined sizes.
-   *
-   * - When only one size is set and outside of an array, the grid will have one column of that size.
+   * When the sum of defined sizes exceeds the available space, elements shrink to avoid overflow (except inside a ScrollView). A single value outside an array creates one column of that size.
    *
    * @defaultValue 'fill'
    */
   columns?: MaybeResponsiveConditionalStyle<Columns>;
   /**
-   * Sizes for each row of the layout.
-   *
-   *
-   * `auto`: intrinsic size of the content.
-   *
-   * `fill`: fills the remaining available space. When multiple rows are set to `fill`, the remaining space is shared equally.
-   *
-   * `` `${number}%` ``: size in percentages.
-   *
-   * `` `${number}fr` ``: size in fractions.
-   *
-   * `number`: size in pixels.
+   * The sizes for each row of the grid.
    *
+   * - `auto`: The intrinsic size of the content.
+   * - `fill`: Fills the remaining available space. When multiple rows use `fill`, the space is shared equally.
+   * - `` `${number}%` ``: A percentage of the container's block size.
+   * - `` `${number}fr` ``: A fractional unit of the available space.
+   * - `number`: A fixed size in pixels.
    *
-   * - When the sum of the defined sizes is larger than the available space, elements will shrink to avoid overflow.
-   *
-   * - When only one size is set and outside of an array, the grid will have one row of that size.
+   * When the sum of defined sizes exceeds the available space, elements shrink to avoid overflow. A single value outside an array creates one row of that size.
    *
    * @defaultValue 'fill'
    */
   rows?: MaybeResponsiveConditionalStyle<Rows>;
   /**
-   * Adjust spacing between children.
-   *
-   * - `base` means the space between rows and columns is `base`.
-   *
-   * - [`base`, `none`] means the space between rows is `base`, space between columns is `none`.
+   * The spacing between child elements. A single value applies to both the row and column axes. A pair of values (for example, `['base', 'none']`) sets the row and column spacing independently.
    *
    * @defaultValue 'none'
    **/
   spacing?: MaybeResponsiveConditionalStyle<Spacing | [Spacing, Spacing]>;
   /**
-   * Position children along the cross axis.
+   * The alignment of children along the block (cross) axis.
    */
   blockAlignment?: MaybeResponsiveConditionalStyle<BlockAlignment>;
   /**
-   * Position children along the main axis.
+   * The alignment of children along the inline (main) axis.
    */
   inlineAlignment?: MaybeResponsiveConditionalStyle<InlineAlignment>;
   /**
-   * Sets the semantic meaning of the component’s content. When set,
-   * the role will be used by assistive technologies to help buyers
-   * navigate the page.
-   *
-   *
-   * For example:
-   *
-   * - In an HTML host a `['listItem', 'separator']` tuple will render: `<li role='separator'>`
-   *
-   * - In an HTML host a `listItem` string will render: `<li>`
+   * The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page. Accepts a single role or a tuple of two roles (for example, `['listItem', 'separator']`).
    */
   accessibilityRole?: ViewLikeAccessibilityRole;
   /**
-   * A label that describes the purpose or contents of the element. When set,
-   * it will be announced to buyers using assistive technologies and will
-   * provide them with more context.
+   * A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.
    */
   accessibilityLabel?: string;
   /**
-   * Sets the overflow behavior of the element.
+   * The overflow behavior of the element.
    *
-   * `hidden`: clips the content when it is larger than the element’s container.
-   * The element will not be scrollable and the users will not be able
-   * to access the clipped content by dragging or using a scroll wheel.
-   *
-   * `visible`: the content that extends beyond the element’s container is visible.
+   * - `visible`: Content that extends beyond the container is visible.
+   * - `hidden`: Content that extends beyond the container is clipped and not scrollable.
    *
    * @default 'visible'
    */
   overflow?: 'hidden' | 'visible';
   /**
-   * Changes the display of the component.
-   *
-   *
-   * `auto` the component's initial value. The actual value depends on the component and context.
+   * The display mode of the component. Learn more about [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/display).
    *
-   * `none` hides the component and removes it from the accessibility tree, making it invisible to screen readers.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+   * - `auto`: The initial value; the actual behavior depends on the component and context.
+   * - `none`: Hides the component and removes it from the accessibility tree.
    *
    * @defaultValue 'auto'
    */
   display?: MaybeResponsiveConditionalStyle<'auto' | 'none'>;
 }
 
-/**
- * Grid is used to lay out content in a matrix of rows and columns.
- */
 export const Grid = createRemoteComponent<'Grid', GridProps>('Grid');