Improve descriptions for layout and structure components

Author: mcvinci

packages/ui-extensions/src/surfaces/checkout/components/Box.d.ts

@@ -26,6 +26,9 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
  * - `base`: The standard border color for most contexts.
  */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -44,13 +47,44 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-box";
 /**
- * The element props interface for the Box component.
  * @publicDocs
  */
 export interface BoxElementProps extends Pick<BoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the box.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<BoxProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * The roundedness of the box's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<BoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
 }
 export interface BoxElement extends BoxElementProps, Omit<HTMLElement, 'id'> {

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

@@ -26,10 +26,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-divider";
-/**
- * The element props interface for the Divider component.
- * @publicDocs
- */
+/** @publicDocs */
 export interface DividerElementProps extends Pick<DividerProps$1, 'direction' | 'id'> {
 }
 export interface DividerElement extends DividerElementProps, Omit<HTMLElement, 'id'> {

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

@@ -10,9 +10,61 @@
 /// <reference lib="DOM" />
 import type {GridProps$1,MaybeResponsive, MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,AlignContentKeyword, AlignItemsKeyword, JustifyContentKeyword, JustifyItemsKeyword,ColorKeyword} from './components-shared.d.ts';
 
+/**
+ * The subset of `align-content` values available for the grid component.
+ *
+ * - `center`: Packs rows toward the center of the grid.
+ * - `start`: Packs rows toward the start of the block axis.
+ * - `end`: Packs rows toward the end of the block axis.
+ * - `normal`: Default browser behavior.
+ * - `space-between`: Distributes rows evenly with no space at the edges.
+ * - `space-around`: Distributes rows evenly with equal space around each.
+ * - `space-evenly`: Distributes rows with equal space between and at the edges.
+ * - `stretch`: Stretches rows to fill the available space.
+ *
+ * @publicDocs
+ */
 export type ReducedAlignContentKeyword = Extract<AlignContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `align-items` values available for the grid component.
+ *
+ * - `center`: Centers items along the block axis.
+ * - `start`: Aligns items to the start of the block axis.
+ * - `end`: Aligns items to the end of the block axis.
+ * - `normal`: Default browser behavior.
+ * - `baseline`: Aligns items along their text baseline.
+ * - `stretch`: Stretches items to fill the cell along the block axis.
+ *
+ * @publicDocs
+ */
 export type ReducedAlignItemsKeyword = Extract<AlignItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `justify-content` values available for the grid component.
+ *
+ * - `center`: Packs columns toward the center of the grid.
+ * - `start`: Packs columns toward the start of the inline axis.
+ * - `end`: Packs columns toward the end of the inline axis.
+ * - `normal`: Default browser behavior.
+ * - `space-between`: Distributes columns evenly with no space at the edges.
+ * - `space-around`: Distributes columns evenly with equal space around each.
+ * - `space-evenly`: Distributes columns with equal space between and at the edges.
+ * - `stretch`: Stretches columns to fill the available space.
+ *
+ * @publicDocs
+ */
 export type ReducedJustifyContentKeyword = Extract<JustifyContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
+/**
+ * The subset of `justify-items` values available for the grid component.
+ *
+ * - `center`: Centers items along the inline axis.
+ * - `start`: Aligns items to the start of the inline axis.
+ * - `end`: Aligns items to the end of the inline axis.
+ * - `normal`: Default browser behavior.
+ * - `baseline`: Aligns items along their text baseline.
+ * - `stretch`: Stretches items to fill the cell along the inline axis.
+ *
+ * @publicDocs
+ */
 export type ReducedJustifyItemsKeyword = Extract<JustifyItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
 /**
  * The subset of border size values available for this component.
@@ -30,6 +82,9 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
  * - `base`: The standard border color for most contexts.
  */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -48,20 +103,86 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-grid";
 /**
- * The element props interface for the Grid component.
  * @publicDocs
  */
 export interface GridElementProps extends Pick<GridProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'alignContent' | 'alignItems' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'columnGap' | 'display' | 'gap' | 'gridTemplateColumns' | 'gridTemplateRows' | 'id' | 'inlineSize' | 'justifyContent' | 'justifyItems' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart' | 'placeContent' | 'placeItems' | 'rowGap'> {
+    /**
+     * Controls how the grid's rows are distributed along the block (column) axis when there is extra space. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     alignContent?: MaybeResponsive<ReducedAlignContentKeyword | ''>;
+    /**
+     * Aligns grid items along the block (column) axis. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     alignItems?: MaybeResponsive<ReducedAlignItemsKeyword | ''>;
+    /**
+     * The background color of the grid.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<GridProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The color of the border using the design system's color scale. Overrides the color value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderColor?: ReducedColorKeyword | '';
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * The roundedness of the grid's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
+    /**
+     * Controls how the grid's columns are distributed along the inline (row) axis when there is extra space. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     justifyContent?: MaybeResponsive<ReducedJustifyContentKeyword | ''>;
+    /**
+     * Aligns grid items along the inline (row) axis. Set to an empty string to use the default.
+     *
+     * @default '' - meaning no override
+     */
     justifyItems?: MaybeResponsive<ReducedJustifyItemsKeyword | ''>;
+    /**
+     * A shorthand for `justifyContent` and `alignContent` that sets both distribution axes at once.
+     *
+     * @default 'normal normal'
+     */
     placeContent?: MaybeResponsive<`${ReducedAlignContentKeyword} ${ReducedJustifyContentKeyword}` | ReducedAlignContentKeyword>;
+    /**
+     * A shorthand for `justifyItems` and `alignItems` that sets both alignment axes at once.
+     *
+     * @default 'normal normal'
+     */
     placeItems?: MaybeResponsive<`${ReducedAlignItemsKeyword} ${ReducedJustifyItemsKeyword}` | ReducedAlignItemsKeyword>;
 }
 export interface GridElement extends GridElementProps, Omit<HTMLElement, 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/GridItem.d.ts

@@ -26,6 +26,9 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
  * - `base`: The standard border color for most contexts.
  */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -44,14 +47,50 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-grid-item";
 /**
- * The element props interface for the GridItem component.
  * @publicDocs
  */
 export interface GridItemElementProps extends Pick<GridItemProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'gridColumn' | 'gridRow' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the grid item.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<GridItemProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The color of the border using the design system's color scale. Overrides the color value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderColor?: ReducedColorKeyword | '';
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
+    /**
+     * The roundedness of the grid item's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridItemProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
 }
 export interface GridItemElement extends GridItemElementProps, Omit<HTMLElement, 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/QueryContainer.d.ts

@@ -26,10 +26,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 }
 
 declare const tagName = "s-query-container";
-/**
- * The element props interface for the QueryContainer component.
- * @publicDocs
- */
+/** @publicDocs */
 export interface QueryContainerElementProps extends Pick<QueryContainerProps$1, 'containerName' | 'id'> {
 }
 export interface QueryContainerElement extends QueryContainerElementProps, Omit<HTMLElement, 'id'> {

packages/ui-extensions/src/surfaces/checkout/components/ScrollBox.d.ts

@@ -26,6 +26,9 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
  * - `base`: The standard border color for most contexts.
  */
 export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
+/**
+ * A shorthand string for specifying border properties. Accepts a size alone (`'base'`), size with color (`'base base'`), or size with color and style (`'base base dashed'`). Omitted values use their defaults.
+ */
 export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
 /**
  * Used when an element does not have children.
@@ -44,14 +47,50 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-scroll-box";
 /**
- * The element props interface for the ScrollBox component.
  * @publicDocs
  */
 export interface ScrollBoxElementProps extends Pick<ScrollBoxProps$1, 'accessibilityLabel' | 'accessibilityRole' | 'accessibilityVisibility' | 'background' | 'blockSize' | 'border' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'display' | 'id' | 'inlineSize' | 'maxBlockSize' | 'maxInlineSize' | 'minBlockSize' | 'minInlineSize' | 'overflow' | 'padding' | 'paddingBlock' | 'paddingBlockEnd' | 'paddingBlockStart' | 'paddingInline' | 'paddingInlineEnd' | 'paddingInlineStart'> {
+    /**
+     * The background color of the scroll box.
+     *
+     * - `base`: The standard background color for general content areas.
+     * - `subdued`: A muted background for secondary or supporting content.
+     * - `transparent`: No background color (the default).
+     *
+     * @default 'transparent'
+     */
     background?: Extract<ScrollBoxProps$1['background'], 'transparent' | 'subdued' | 'base'>;
+    /**
+     * A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here.
+     *
+     * @default 'none'
+     */
     border?: BorderShorthand;
+    /**
+     * The color of the border using the design system's color scale. Overrides the color value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderColor?: ReducedColorKeyword | '';
+    /**
+     * The roundedness of the scroll box's corners.
+     *
+     * - `none`: Sharp corners with no rounding.
+     * - `small-100` / `small`: Subtle rounding for compact elements.
+     * - `base`: Standard rounding for most use cases.
+     * - `large` / `large-100`: More pronounced rounding for prominent containers.
+     * - `max`: Maximum rounding, creating a pill or circular shape.
+     *
+     * Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
+     *
+     * @default 'none'
+     */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<ScrollBoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
+    /**
+     * The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`.
+     *
+     * @default '' - meaning no override
+     */
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
 }
 export interface ScrollBoxElement extends ScrollBoxElementProps, Omit<HTMLElement, 'id'> {