[Layout foundations] Clean up prop descriptions and add default values in description

.changeset/seven-bats-share.md

@@ -0,0 +1,6 @@
+---
+'@shopify/polaris': patch
+'polaris.shopify.com': patch
+---
+
+Cleaned up prop descriptions and added missing default values for `Box`, `AlphaCard`, `AlphaStack`, `Columns`, `Tiles`, `Bleed`, and `Inline`

polaris-react/src/components/AlphaCard/AlphaCard.tsx

@@ -15,7 +15,6 @@ type CardBackgroundColorTokenScale = Extract<
 >;
 
 export interface AlphaCardProps {
-  /** Elements to display inside card */
   children?: React.ReactNode;
   /** Background color
    * @default 'surface'

polaris-react/src/components/AlphaStack/AlphaStack.tsx

@@ -17,19 +17,20 @@ type Element = 'div' | 'ul' | 'ol' | 'fieldset';
 type Gap = ResponsiveProp<SpacingSpaceScale>;
 
 export interface AlphaStackProps {
+  children?: React.ReactNode;
   /** HTML Element type
    * @default 'div'
    */
   as?: Element;
-  /** Elements to display inside stack */
-  children?: React.ReactNode;
-  /** The vertical alignment of elements
+  /** Vertical alignment of children
    * @default 'start'
    */
   align?: Align;
-  /** Toggle elements to be full width */
+  /** Toggle children to be full width
+   * @default false
+   */
   fullWidth?: boolean;
-  /** The spacing between elements
+  /** The spacing between children
    * @default '4'
    */
   gap?: Gap;
@@ -39,7 +40,7 @@ export const AlphaStack = ({
   as = 'div',
   children,
   align = 'start',
-  fullWidth,
+  fullWidth = false,
   gap = '4',
 }: AlphaStackProps) => {
   const className = classNames(

polaris-react/src/components/Bleed/Bleed.tsx

@@ -6,21 +6,20 @@ import {sanitizeCustomProperties} from '../../utilities/css';
 import styles from './Bleed.scss';
 
 export interface BleedProps {
-  /** Elements to display inside tile */
-  children: React.ReactNode;
-  /** Negative horizontal space around the element
-   * * @default '5'
+  children?: React.ReactNode;
+  /** Negative horizontal space around children
+   * @default '5'
    */
   horizontal?: SpacingSpaceScale;
-  /** Negative vertical space around the element */
+  /** Negative vertical space around children */
   vertical?: SpacingSpaceScale;
-  /** Negative top space around the element */
+  /** Negative top space around children */
   top?: SpacingSpaceScale;
-  /** Negative bottom space around the element */
+  /** Negative bottom space around children */
   bottom?: SpacingSpaceScale;
-  /** Negative left space around the element */
+  /** Negative left space around children */
   left?: SpacingSpaceScale;
-  /** Negative right space around the element */
+  /** Negative right space around children */
   right?: SpacingSpaceScale;
 }
 

polaris-react/src/components/Box/Box.tsx

@@ -69,7 +69,10 @@ export type BackgroundColors =
   | ColorsSurfaceTokenAlias;
 
 export interface BoxProps {
-  /** HTML Element type */
+  children?: React.ReactNode;
+  /** HTML Element type
+   * @default 'div'
+   */
   as?: Element;
   /** Background color */
   background?: BackgroundColors;
@@ -91,7 +94,7 @@ export interface BoxProps {
   borderRadiusEndEnd?: BorderRadiusTokenScale;
   /** Vertical start horizontal start border radius */
   borderRadiusStartStart?: BorderRadiusTokenScale;
-  /** Verital start horizontal end border radius */
+  /** Vertical start horizontal end border radius */
   borderRadiusStartEnd?: BorderRadiusTokenScale;
   /** Border width */
   borderWidth?: ShapeBorderWidthScale;
@@ -147,28 +150,26 @@ export interface BoxProps {
    * paddingInlineEnd={{xs: '2', sm: '3', md: '4', lg: '5', xl: '6'}}
    */
   paddingInlineEnd?: Spacing;
-  /** Shadow */
+  /** Shadow on box */
   shadow?: DepthShadowAlias;
   /** Width of container */
   width?: string;
-  /** Elements to display inside box */
-  children?: React.ReactNode;
   // These could be moved to new layout component(s) in the future
-  /** Position of the box */
+  /** Position of box */
   position?: Position;
-  /** Top position of the box */
+  /** Top position of box */
   top?: Spacing;
-  /** Bottom position of the box */
+  /** Bottom position of box */
   right?: Spacing;
-  /** Left position of the box */
+  /** Left position of box */
   bottom?: Spacing;
-  /** Right position of the box */
+  /** Right position of box */
   left?: Spacing;
-  /** Opcity of the box */
+  /** Opacity of box */
   opacity?: string;
   /** Visually hide the contents (still announced by screenreader) */
   visuallyHidden?: boolean;
-  /** z-index of the box */
+  /** z-index of box */
   zIndex?: string;
 }
 

polaris-react/src/components/Columns/Columns.tsx

@@ -19,13 +19,12 @@ type Columns = {
 type Gap = ResponsiveProp<SpacingSpaceScale>;
 
 export interface ColumnsProps {
-  /** Elements to display inside columns */
   children?: React.ReactNode;
   /** The number of columns to display
    * @default {xs: 6, sm: 6, md: 6, lg: 6, xl: 6}
    */
   columns?: Columns;
-  /** The spacing between columns. Accepts a spacing token or an object of spacing tokens for different screen sizes.
+  /** The spacing between children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
    * @default '4'
    * @example
    * gap='2'

polaris-react/src/components/Inline/Inline.tsx

@@ -18,11 +18,12 @@ type BlockAlign = 'start' | 'center' | 'end' | 'baseline' | 'stretch';
 type Gap = ResponsiveProp<SpacingSpaceScale>;
 
 export interface InlineProps {
-  /** Adjust horizontal alignment of elements
+  children?: React.ReactNode;
+  /** Horizontal alignment of children
    * @default 'start'
    */
   align?: Align;
-  /** Adjust vertical alignment of elements
+  /** Vertical alignment of children
    * @default 'center'
    */
   blockAlign?: BlockAlign;
@@ -37,8 +38,6 @@ export interface InlineProps {
    * @default true
    */
   wrap?: boolean;
-  /** Elements to display inside stack */
-  children?: React.ReactNode;
 }
 
 export const Inline = function Inline({

polaris-react/src/components/Tiles/Tiles.tsx

@@ -15,15 +15,19 @@ type Gap = {
 };
 
 export interface TilesProps {
-  /** Elements to display inside tile */
-  children: React.ReactNode;
-  /** Adjust spacing between elements */
-  gap?: Gap;
-  /** Adjust number of columns */
+  children?: React.ReactNode;
+  /** The number of columns to display
+   * @default {xs: 6, sm: 6, md: 6, lg: 6, xl: 6}
+   */
   columns?: Columns;
+  /** The spacing between children. Accepts an object of spacing tokens for different screen sizes.
+   * @default {xs: 4, sm: 4, md: 4, lg: 4, xl: 4}
+   * @example gap={{xs: '1', sm: '2', md: '3', lg: '4', xl: '5'}}
+   */
+  gap?: Gap;
 }
 
-export const Tiles = ({children, gap, columns}: TilesProps) => {
+export const Tiles = ({children, columns, gap}: TilesProps) => {
   const style = {
     '--pc-tile-gap-xs': gap?.xs ? `var(--p-space-${gap?.xs})` : undefined,
     '--pc-tile-gap-sm': gap?.sm ? `var(--p-space-${gap?.sm})` : undefined,