Skip to content

Commit 086e8c6

Browse files
mcvincimcvinci
committed
Improve descriptions for layout and structure components
Update section component descriptions
1 parent 5661d02 commit 086e8c6

File tree

12 files changed

+607
-283
lines changed

12 files changed

+607
-283
lines changed

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

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
2828
* @publicDocs
2929
*/
3030
export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
31-
/** @publicDocs */
31+
/**
32+
* 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.
33+
* @publicDocs
34+
*/
3235
export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
3336
/**
3437
* Used when an element does not have children.
@@ -48,16 +51,43 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
4851
}
4952

5053
declare const tagName = "s-box";
51-
/**
52-
* The box component provides a generic, flexible container for custom designs and layouts. Use box to apply styling like backgrounds, padding, borders, or border radius when existing components don't meet your needs, or to nest and group other components.
53-
*
54-
* Box contents maintain their natural size, making it especially useful within layout components that would otherwise stretch their children. For structured layouts, use [stack](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/stack) or [grid](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/grid).
55-
* @publicDocs
56-
*/
54+
/** @publicDocs */
5755
export interface BoxProps 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'> {
56+
/**
57+
* The background color of the box.
58+
*
59+
* - `base`: The standard background color for general content areas.
60+
* - `subdued`: A muted background for secondary or supporting content.
61+
* - `transparent`: No background color (the default).
62+
*
63+
* @default 'transparent'
64+
*/
5865
background?: Extract<BoxProps$1['background'], 'transparent' | 'subdued' | 'base'>;
66+
/**
67+
* A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`) can override values set here.
68+
*
69+
* @default 'none'
70+
*/
5971
border?: BorderShorthand;
72+
/**
73+
* 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`.
74+
*
75+
* @default '' - meaning no override
76+
*/
6077
borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
78+
/**
79+
* The roundedness of the box's corners.
80+
*
81+
* - `none`: Sharp corners with no rounding.
82+
* - `small-100` / `small`: Subtle rounding for compact elements.
83+
* - `base`: Standard rounding for most use cases.
84+
* - `large` / `large-100`: More pronounced rounding for prominent containers.
85+
* - `max`: Maximum rounding, creating a pill or circular shape.
86+
*
87+
* Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
88+
*
89+
* @default 'none'
90+
*/
6191
borderRadius?: MaybeAllValuesShorthandProperty<Extract<BoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
6292
}
6393
/** @publicDocs */

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

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,7 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
2828
}
2929

3030
declare const tagName = "s-divider";
31-
/**
32-
* The divider component creates clear visual separation between elements in the interface. Use divider to separate distinct content groups in forms, settings panels, lists, or page sections, helping users scan and understand content organization.
33-
*
34-
* Dividers support both horizontal and vertical orientations, along with different visual strengths for varying levels of emphasis. For more structured content grouping with headings, use [section](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/section).
35-
* @publicDocs
36-
*/
31+
/** @publicDocs */
3732
export interface DividerProps extends Pick<DividerProps$1, 'direction' | 'id'> {
3833
}
3934
/** @publicDocs */

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

Lines changed: 124 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,61 @@
1010
/// <reference lib="DOM" />
1111
import type {GridProps$1,MaybeResponsive, MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,AlignContentKeyword, AlignItemsKeyword, JustifyContentKeyword, JustifyItemsKeyword,ColorKeyword} from './components-shared.d.ts';
1212

13-
/** @publicDocs */
13+
/**
14+
* The subset of `align-content` values available for the grid component.
15+
*
16+
* - `center`: Packs rows toward the center of the grid.
17+
* - `start`: Packs rows toward the start of the block axis.
18+
* - `end`: Packs rows toward the end of the block axis.
19+
* - `normal`: Default browser behavior.
20+
* - `space-between`: Distributes rows evenly with no space at the edges.
21+
* - `space-around`: Distributes rows evenly with equal space around each.
22+
* - `space-evenly`: Distributes rows with equal space between and at the edges.
23+
* - `stretch`: Stretches rows to fill the available space.
24+
*
25+
* @publicDocs
26+
*/
1427
export type ReducedAlignContentKeyword = Extract<AlignContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
15-
/** @publicDocs */
28+
/**
29+
* The subset of `align-items` values available for the grid component.
30+
*
31+
* - `center`: Centers items along the block axis.
32+
* - `start`: Aligns items to the start of the block axis.
33+
* - `end`: Aligns items to the end of the block axis.
34+
* - `normal`: Default browser behavior.
35+
* - `baseline`: Aligns items along their text baseline.
36+
* - `stretch`: Stretches items to fill the cell along the block axis.
37+
*
38+
* @publicDocs
39+
*/
1640
export type ReducedAlignItemsKeyword = Extract<AlignItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
17-
/** @publicDocs */
41+
/**
42+
* The subset of `justify-content` values available for the grid component.
43+
*
44+
* - `center`: Packs columns toward the center of the grid.
45+
* - `start`: Packs columns toward the start of the inline axis.
46+
* - `end`: Packs columns toward the end of the inline axis.
47+
* - `normal`: Default browser behavior.
48+
* - `space-between`: Distributes columns evenly with no space at the edges.
49+
* - `space-around`: Distributes columns evenly with equal space around each.
50+
* - `space-evenly`: Distributes columns with equal space between and at the edges.
51+
* - `stretch`: Stretches columns to fill the available space.
52+
*
53+
* @publicDocs
54+
*/
1855
export type ReducedJustifyContentKeyword = Extract<JustifyContentKeyword, 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' | 'center' | 'start' | 'end'>;
19-
/** @publicDocs */
56+
/**
57+
* The subset of `justify-items` values available for the grid component.
58+
*
59+
* - `center`: Centers items along the inline axis.
60+
* - `start`: Aligns items to the start of the inline axis.
61+
* - `end`: Aligns items to the end of the inline axis.
62+
* - `normal`: Default browser behavior.
63+
* - `baseline`: Aligns items along their text baseline.
64+
* - `stretch`: Stretches items to fill the cell along the inline axis.
65+
*
66+
* @publicDocs
67+
*/
2068
export type ReducedJustifyItemsKeyword = Extract<JustifyItemsKeyword, 'normal' | 'stretch' | 'baseline' | 'center' | 'start' | 'end'>;
2169
/**
2270
* The subset of border size values available for this component.
@@ -36,7 +84,10 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
3684
* @publicDocs
3785
*/
3886
export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
39-
/** @publicDocs */
87+
/**
88+
* 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.
89+
* @publicDocs
90+
*/
4091
export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
4192
/**
4293
* Used when an element does not have children.
@@ -56,23 +107,85 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
56107
}
57108

58109
declare const tagName = "s-grid";
59-
/**
60-
* The grid component organizes content in a matrix of rows and columns to create responsive page layouts. Use grid to build complex, multi-column layouts that adapt to different screen sizes and maintain consistent alignment.
61-
*
62-
* Grid follows the CSS grid layout pattern and supports flexible column configurations, gap spacing, and alignment properties for precise layout control. For simpler linear layouts (horizontal or vertical), use [stack](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/stack).
63-
* @publicDocs
64-
*/
110+
/** @publicDocs */
65111
export interface GridProps 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'> {
112+
/**
113+
* 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.
114+
*
115+
* @default '' - meaning no override
116+
*/
66117
alignContent?: MaybeResponsive<ReducedAlignContentKeyword | ''>;
118+
/**
119+
* Aligns grid items along the block (column) axis. Set to an empty string to use the default.
120+
*
121+
* @default '' - meaning no override
122+
*/
67123
alignItems?: MaybeResponsive<ReducedAlignItemsKeyword | ''>;
124+
/**
125+
* The background color of the grid.
126+
*
127+
* - `base`: The standard background color for general content areas.
128+
* - `subdued`: A muted background for secondary or supporting content.
129+
* - `transparent`: No background color (the default).
130+
*
131+
* @default 'transparent'
132+
*/
68133
background?: Extract<GridProps$1['background'], 'transparent' | 'subdued' | 'base'>;
134+
/**
135+
* 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.
136+
*
137+
* @default 'none'
138+
*/
69139
border?: BorderShorthand;
140+
/**
141+
* The color of the border using the design system's color scale. Overrides the color value set by `border`.
142+
*
143+
* @default '' - meaning no override
144+
*/
70145
borderColor?: ReducedColorKeyword | '';
146+
/**
147+
* 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`.
148+
*
149+
* @default '' - meaning no override
150+
*/
71151
borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
152+
/**
153+
* The roundedness of the grid's corners.
154+
*
155+
* - `none`: Sharp corners with no rounding.
156+
* - `small-100` / `small`: Subtle rounding for compact elements.
157+
* - `base`: Standard rounding for most use cases.
158+
* - `large` / `large-100`: More pronounced rounding for prominent containers.
159+
* - `max`: Maximum rounding, creating a pill or circular shape.
160+
*
161+
* Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
162+
*
163+
* @default 'none'
164+
*/
72165
borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
166+
/**
167+
* 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.
168+
*
169+
* @default '' - meaning no override
170+
*/
73171
justifyContent?: MaybeResponsive<ReducedJustifyContentKeyword | ''>;
172+
/**
173+
* Aligns grid items along the inline (row) axis. Set to an empty string to use the default.
174+
*
175+
* @default '' - meaning no override
176+
*/
74177
justifyItems?: MaybeResponsive<ReducedJustifyItemsKeyword | ''>;
178+
/**
179+
* A shorthand for `justifyContent` and `alignContent` that sets both distribution axes at once.
180+
*
181+
* @default 'normal normal'
182+
*/
75183
placeContent?: MaybeResponsive<`${ReducedAlignContentKeyword} ${ReducedJustifyContentKeyword}` | ReducedAlignContentKeyword>;
184+
/**
185+
* A shorthand for `justifyItems` and `alignItems` that sets both alignment axes at once.
186+
*
187+
* @default 'normal normal'
188+
*/
76189
placeItems?: MaybeResponsive<`${ReducedAlignItemsKeyword} ${ReducedJustifyItemsKeyword}` | ReducedAlignItemsKeyword>;
77190
}
78191
/** @publicDocs */

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

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ export type ReducedBorderSizeKeyword = Extract<BorderSizeKeyword, 'none' | 'base
2828
* @publicDocs
2929
*/
3030
export type ReducedColorKeyword = Extract<ColorKeyword, 'base'>;
31-
/** @publicDocs */
31+
/**
32+
* 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.
33+
* @publicDocs
34+
*/
3235
export type BorderShorthand = ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}`;
3336
/**
3437
* Used when an element does not have children.
@@ -48,17 +51,49 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
4851
}
4952

5053
declare const tagName = "s-grid-item";
51-
/**
52-
* The grid item component represents a single cell within a grid layout, allowing you to control how content is positioned and sized within the grid. Use grid item as a child of grid to specify column span, row span, and positioning for individual content areas.
53-
*
54-
* Grid item supports precise placement control through column and row properties, enabling you to create complex layouts where different items occupy varying amounts of space or appear in specific grid positions.
55-
* @publicDocs
56-
*/
54+
/** @publicDocs */
5755
export interface GridItemProps 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'> {
56+
/**
57+
* The background color of the grid item.
58+
*
59+
* - `base`: The standard background color for general content areas.
60+
* - `subdued`: A muted background for secondary or supporting content.
61+
* - `transparent`: No background color (the default).
62+
*
63+
* @default 'transparent'
64+
*/
5865
background?: Extract<GridItemProps$1['background'], 'transparent' | 'subdued' | 'base'>;
66+
/**
67+
* 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.
68+
*
69+
* @default 'none'
70+
*/
5971
border?: BorderShorthand;
72+
/**
73+
* The color of the border using the design system's color scale. Overrides the color value set by `border`.
74+
*
75+
* @default '' - meaning no override
76+
*/
6077
borderColor?: ReducedColorKeyword | '';
78+
/**
79+
* 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`.
80+
*
81+
* @default '' - meaning no override
82+
*/
6183
borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
84+
/**
85+
* The roundedness of the grid item's corners.
86+
*
87+
* - `none`: Sharp corners with no rounding.
88+
* - `small-100` / `small`: Subtle rounding for compact elements.
89+
* - `base`: Standard rounding for most use cases.
90+
* - `large` / `large-100`: More pronounced rounding for prominent containers.
91+
* - `max`: Maximum rounding, creating a pill or circular shape.
92+
*
93+
* Supports 1-to-4-value shorthand syntax for specifying different radii per corner.
94+
*
95+
* @default 'none'
96+
*/
6297
borderRadius?: MaybeAllValuesShorthandProperty<Extract<GridItemProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
6398
}
6499
/** @publicDocs */

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

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,7 @@ export interface QueryContainerElementProps extends Pick<QueryContainerProps$1,
3434
/** @publicDocs */
3535
export interface QueryContainerElement extends QueryContainerElementProps, Omit<HTMLElement, 'id'> {
3636
}
37-
/**
38-
* The query container component establishes a container query context for responsive design. Use query container to define an element as a containment context, enabling child components or styles to adapt based on the container's size rather than viewport width.
39-
*
40-
* Query containers support modern responsive patterns where components respond to their container dimensions, creating more flexible and reusable layouts.
41-
* @publicDocs
42-
*/
37+
/** @publicDocs */
4338
export interface QueryContainerProps extends QueryContainerElementProps {
4439
}
4540
declare global {

0 commit comments

Comments
 (0)