@duro-app/ui 2.0.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "2.0.1",
+  "version": "3.1.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^2.0.1"
+    "@duro-app/tokens": "^3.1.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ActionBar/ActionBar.stories.tsx

@@ -6,6 +6,8 @@ import {ActionBar} from './ActionBar'
 import {Button} from '../Button/Button'
 import {Checkbox} from '../Checkbox/Checkbox'
 import {Table} from '../Table/Table'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
 
 interface ActionBarStoryArgs {
   onClearSelection: () => void
@@ -40,16 +42,16 @@ const storyStyles = css.create({
   wrapper: {
     display: 'flex',
     flexDirection: 'column',
-    gap: 32,
-    padding: 24,
+    gap: spacing.xl,
+    padding: spacing.lg,
   },
   label: {
-    fontSize: '0.75rem',
-    fontWeight: 600,
+    fontSize: typography.fontSizeXs,
+    fontWeight: typography.fontWeightSemibold,
     textTransform: 'uppercase' as const,
     letterSpacing: '0.05em',
     opacity: 0.6,
-    marginBottom: 8,
+    marginBottom: spacing.sm,
   },
 })
 

package/src/components/Alert/Alert.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Alert} from './Alert'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Alert> = {
   title: 'Components/Alert',
@@ -57,7 +58,7 @@ export const NoIcon: Story = {
 }
 
 const stackStyles = css.create({
-  stack: {display: 'flex', flexDirection: 'column', gap: 12},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.ms},
 })
 
 export const AllVariants: Story = {

package/src/components/Badge/Badge.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Badge} from './Badge'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Badge> = {
   title: 'Components/Badge',
@@ -52,8 +53,8 @@ export const Small: Story = {
 }
 
 const stackStyles = css.create({
-  row: {display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap'},
-  stack: {display: 'flex', flexDirection: 'column', gap: 16},
+  row: {display: 'flex', alignItems: 'center', gap: spacing.sm, flexWrap: 'wrap'},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.md},
 })
 
 export const AllVariants: Story = {

package/src/components/Button/Button.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Button} from './Button'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Button> = {
   title: 'Components/Button',
@@ -83,8 +84,8 @@ export const Disabled: Story = {
 }
 
 const rowStyles = css.create({
-  row: {display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap'},
-  stack: {display: 'flex', flexDirection: 'column', gap: 16},
+  row: {display: 'flex', gap: spacing.ms, alignItems: 'center', flexWrap: 'wrap'},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.md},
 })
 
 export const AllVariants: Story = {

package/src/components/Callout/Callout.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Callout} from './Callout'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Callout> = {
   title: 'Components/Callout',
@@ -82,7 +83,7 @@ export const NoIcon: Story = {
 }
 
 const stackStyles = css.create({
-  stack: {display: 'flex', flexDirection: 'column', gap: 12},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.ms},
 })
 
 export const AllVariants: Story = {

package/src/components/Card/Card.stories.tsx

@@ -3,6 +3,8 @@ import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Card} from './Card'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Card> = {
   title: 'Components/Card',
@@ -85,10 +87,10 @@ const gridStyles = css.create({
   grid: {
     display: 'grid',
     gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))',
-    gap: 16,
+    gap: spacing.md,
   },
-  stack: {display: 'flex', flexDirection: 'column', gap: 16},
-  muted: {color: colors.textMuted, fontSize: '0.875rem'},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.md},
+  muted: {color: colors.textMuted, fontSize: typography.fontSizeSm},
 })
 
 export const AllVariants: Story = {

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Checkbox} from './Checkbox'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof Checkbox> = {
   title: 'Components/Checkbox',
@@ -67,7 +68,7 @@ export const WithoutLabel: Story = {
 }
 
 const stackStyles = css.create({
-  stack: {display: 'flex', flexDirection: 'column', gap: 12},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.ms},
 })
 
 export const AllVariants: Story = {

package/src/components/Cluster/Cluster.stories.tsx

@@ -2,8 +2,9 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {css, html} from 'react-strict-dom'
 import {Cluster} from './Cluster'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {SPACING_KEYS} from '@duro-app/tokens/keys'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
 
 const meta: Meta<typeof Cluster> = {
   title: 'Layout/Cluster',
@@ -35,8 +36,8 @@ const localStyles = css.create({
     paddingBottom: spacing.xs,
     paddingLeft: spacing.sm,
     paddingRight: spacing.sm,
-    borderRadius: 12,
-    fontSize: '0.75rem',
+    borderRadius: radii.md,
+    fontSize: typography.fontSizeXs,
     whiteSpace: 'nowrap',
   },
   narrow: {

package/src/components/ColorMode/ColorMode.stories.tsx

@@ -2,6 +2,7 @@ import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {ColorModeProvider, ColorModeToggle, useColorMode} from './ColorMode'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof ColorModeToggle> = {
   title: 'Components/ColorMode',
@@ -58,7 +59,7 @@ export const AllModes: Story = {
 }
 
 const readout = css.create({
-  row: {display: 'flex', alignItems: 'center', gap: 12},
+  row: {display: 'flex', alignItems: 'center', gap: spacing.ms},
 })
 
 function Readout() {

package/src/components/Field/Field.stories.tsx

@@ -3,6 +3,7 @@ import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Field} from './Field'
 import {Input} from '../Input/Input'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta = {
   title: 'Components/Field',
@@ -62,8 +63,8 @@ export const WithError: Story = {
 }
 
 const stackStyles = css.create({
-  stack: {display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 400},
-  stackWide: {display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 600},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.md, maxWidth: 400},
+  stackWide: {display: 'flex', flexDirection: 'column', gap: spacing.md, maxWidth: 600},
 })
 
 export const FormExample: Story = {

package/src/components/Grid/Grid.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'CSS grid layout. Supports fixed column count (1-6) or responsive auto-fit via minColumnWidth.',
+    'Grid layout. Columns are a count (1-6), a list of weights ([1, 2] for one-third / two-thirds), responsive auto-fit via minColumnWidth, or a named split layout (list/detail, nav/content) that collapses to one column on the width of its own container, so it is safe to nest and to place beside a DetailPanel. Weights rather than CSS template strings, so the same props render as CSS grid on web and as a wrapping flex row on native.',
   whenToUse: [
     'Card grids, dashboard layouts, multi-column forms',
     'Responsive layouts that should auto-adjust column count',
+    'A list/detail or nav/content screen — layout="split" | "split-wide", never a hand-rolled gridTemplateColumns with its own @media; a split inside a split is fine, each collapses on its own room',
   ],
   whenNotToUse: [
     'Single-column vertical layout — use Stack',
@@ -17,8 +18,19 @@ export const meta: ComponentMeta = {
       kind: 'contrast',
       relationship: 'Grid for multi-column layouts; Stack for a single vertical column',
     },
+    {
+      component: 'split-pane',
+      kind: 'composition',
+      relationship: 'Grid layout="split" with a List and a Panel is the split-pane recipe',
+    },
   ],
-  example: `// Responsive: columns auto-fit based on min width
+  example: `// Split: list ≥ 240px beside a detail pane, one column below md
+<Grid layout="split" gap="lg">
+  <List.Root>…</List.Root>
+  <Panel.Root>…</Panel.Root>
+</Grid>
+
+// Responsive: columns auto-fit based on min width
 <Grid minColumnWidth="280px" gap="md">
   <Card>A</Card>
   <Card>B</Card>
@@ -30,5 +42,11 @@ export const meta: ComponentMeta = {
   <Card>A</Card>
   <Card>B</Card>
   <Card>C</Card>
+</Grid>
+
+// Weighted: a one-third / two-thirds split (works on native too)
+<Grid columns={[1, 2]} gap="md">
+  <Card>Sidebar</Card>
+  <Card>Content</Card>
 </Grid>`,
 }

package/src/components/Grid/Grid.stories.tsx

@@ -1,11 +1,13 @@
 import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Grid} from './Grid'
 import {Stack} from '../Stack/Stack'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {SPACING_KEYS} from '@duro-app/tokens/keys'
 import {useContainerQuery} from '../../hooks/useContainerQuery'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
 
 const meta: Meta<typeof Grid> = {
   title: 'Layout/Grid',
@@ -18,8 +20,10 @@ const meta: Meta<typeof Grid> = {
     columns: {
       control: 'select',
       options: [1, 2, 3, 4, 5, 6],
+      description: 'A count, or weights such as [1, 2] for a one-third / two-thirds split',
     },
     minColumnWidth: {control: 'text'},
+    layout: {control: 'select', options: [undefined, 'split', 'split-wide']},
   },
 }
 
@@ -31,14 +35,20 @@ const localStyles = css.create({
     backgroundColor: colors.accent,
     color: colors.accentContrast,
     padding: spacing.md,
-    borderRadius: 4,
+    borderRadius: radii.xs,
     textAlign: 'center',
-    fontSize: '0.875rem',
+    fontSize: typography.fontSizeSm,
   },
   label: {
-    fontSize: '0.75rem',
+    fontSize: typography.fontSizeXs,
     color: colors.textMuted,
   },
+  frame: (width: number) => ({
+    width,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    borderColor: colors.border,
+  }),
 })
 
 const Cell = ({children}: {children: string}) => (
@@ -83,6 +93,98 @@ export const TwoColumns: Story = {
   ),
 }
 
+export const Split: Story = {
+  render: () => (
+    <Stack gap="sm">
+      <html.span style={localStyles.label}>
+        layout=&quot;split&quot; — list ≥ 240px beside the detail, one column when the container is
+        narrower than sm; split-wide collapses below md
+      </html.span>
+      <Grid layout="split" gap="lg">
+        <Cell>list</Cell>
+        <Cell>detail</Cell>
+      </Grid>
+      <Grid layout="split-wide" gap="lg">
+        <Cell>nav</Cell>
+        <Cell>content</Cell>
+      </Grid>
+    </Stack>
+  ),
+}
+
+/**
+ * A split inside a split: a list/detail board in the content column of a
+ * nav/content shell. Each collapses on its OWN container: at 1120 both split;
+ * at 900 the shell still splits (≥ md) while the board — left 588px, under
+ * sm — stacks; at 700 the shell stacks and the board, now given the whole
+ * width, splits again; at 600 both stack. Keyed on the viewport, both would
+ * open at 768 and leave the detail pane ~150px.
+ */
+export const NestedSplits: Story = {
+  render: () => (
+    <Stack gap="lg">
+      {[1120, 900, 700, 600].map((width) => (
+        <Stack key={width} gap="sm">
+          <html.span style={localStyles.label}>frame {width}px</html.span>
+          <html.div style={localStyles.frame(width)} data-testid={`frame-${width}`}>
+            <Grid layout="split-wide" gap="xl">
+              <Cell>nav</Cell>
+              <Grid layout="split" gap="md">
+                <Cell>list</Cell>
+                <Cell>detail</Cell>
+              </Grid>
+            </Grid>
+          </html.div>
+        </Stack>
+      ))}
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const tracks = (frame: HTMLElement, text: string) => {
+      const grid = canvas.getAllByText(text).find((el) => frame.contains(el))
+        ?.parentElement as HTMLElement
+      return getComputedStyle(grid).gridTemplateColumns.split(' ').length
+    }
+    const expected: Record<number, [number, number]> = {
+      1120: [2, 2],
+      900: [2, 1],
+      700: [1, 2],
+      600: [1, 1],
+    }
+    for (const [width, [outer, inner]] of Object.entries(expected)) {
+      const frame = canvas.getByTestId(`frame-${width}`)
+      await expect(tracks(frame, 'nav'), `shell at ${width}`).toBe(outer)
+      await expect(tracks(frame, 'list'), `board at ${width}`).toBe(inner)
+    }
+  },
+}
+
+/**
+ * Weighted columns: the portable form of `grid-template-columns: 1fr 2fr`.
+ * Weights are what the native Grid can honour too (as flex bases), where a
+ * CSS template string would be dropped.
+ */
+export const WeightedColumns: Story = {
+  render: () => (
+    <Grid gap="md" columns={[1, 2]}>
+      <Cell>Sidebar (1)</Cell>
+      <Cell>Content (2)</Cell>
+      <Cell>Sidebar (1)</Cell>
+      <Cell>Content (2)</Cell>
+    </Grid>
+  ),
+  play: async ({canvas}) => {
+    // The grid is the cells' parent (Storybook wraps the story in its own
+    // divs). The browser resolves `1fr 2fr` to pixel tracks, so assert the
+    // ratio rather than the string.
+    const root = canvas.getAllByText('Sidebar (1)')[0].parentElement as HTMLElement
+    const tracks = getComputedStyle(root).gridTemplateColumns.split(' ').map(Number.parseFloat)
+    await expect(tracks).toHaveLength(2)
+    // Second track is twice the first, within a pixel of rounding.
+    await expect(Math.abs(tracks[1] - 2 * tracks[0])).toBeLessThan(1.5)
+  },
+}
+
 export const WithContainerQuery: Story = {
   render: function Render() {
     const {ref, size} = useContainerQuery<HTMLDivElement>()

package/src/components/Grid/Grid.tsx

@@ -1,12 +1,31 @@
-import type {ReactNode} from 'react'
+import {Children, type ReactNode} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
+import {isNative} from '../../platform'
+import {cellBasis, cellPosition, columnWeights, gridTemplate, type GridColumns} from './columns'
 import type {SpacingToken} from '@duro-app/tokens/keys'
 
+export type GridLayout = 'split' | 'split-wide'
+
 interface GridProps {
   gap?: SpacingToken
-  columns?: 1 | 2 | 3 | 4 | 5 | 6
+  /** A column count (equal columns) or weights: `[1, 2]` gives a one-third /
+   *  two-thirds split. Weights are the portable form of a track list — a CSS
+   *  template string would be silently ignored on native. */
+  columns?: GridColumns
+  /** Responsive auto-fit: as many columns of at least this width as fit.
+   *  Wins over `columns` when both are set. On native this approximates to
+   *  cells of that minimum width that grow and wrap. */
   minColumnWidth?: string
+  /**
+   * A named responsive layout. `split` is list/detail (1:2, list ≥ 240px),
+   * `split-wide` is nav/content (1:3, nav ≥ 280px). Each collapses to one
+   * column on the width of its OWN container — `split` below `sm` (640px),
+   * `split-wide` below `md` (768px) — so a split nested inside another
+   * split, or beside an open DetailPanel, collapses when it runs out of room
+   * rather than when the window does. Wins over `columns` / `minColumnWidth`.
+   */
+  layout?: GridLayout
   children: ReactNode
 }
 
@@ -21,6 +40,8 @@ const gapMap = {
   xxxl: styles.gapXxxl,
 } as const satisfies Record<SpacingToken, unknown>
 
+// Fixed counts keep their static classes so existing web consumers emit the
+// exact CSS they did before; only weight lists go through the dynamic style.
 const columnsMap = {
   1: styles.col1,
   2: styles.col2,
@@ -30,12 +51,116 @@ const columnsMap = {
   6: styles.col6,
 } as const
 
-export function Grid({gap = 'md', columns, minColumnWidth, children}: GridProps) {
-  const columnStyle = minColumnWidth
-    ? styles.autoFit(minColumnWidth)
-    : columns
-      ? columnsMap[columns]
-      : undefined
+const layoutMap = {
+  split: styles.split,
+  'split-wide': styles.splitWide,
+} as const satisfies Record<GridLayout, unknown>
+
+// On native the named layouts are their weights; there is no media query to
+// collapse them, so a split stays a split on a phone (see NativeGrid).
+const layoutWeights = {
+  split: [1, 2],
+  'split-wide': [1, 3],
+} as const satisfies Record<GridLayout, readonly number[]>
+
+const cellGapLeftMap = {
+  xs: styles.cellGapLeftXs,
+  sm: styles.cellGapLeftSm,
+  ms: styles.cellGapLeftMs,
+  md: styles.cellGapLeftMd,
+  lg: styles.cellGapLeftLg,
+  xl: styles.cellGapLeftXl,
+  xxl: styles.cellGapLeftXxl,
+  xxxl: styles.cellGapLeftXxxl,
+} as const satisfies Record<SpacingToken, unknown>
+
+const cellGapTopMap = {
+  xs: styles.cellGapTopXs,
+  sm: styles.cellGapTopSm,
+  ms: styles.cellGapTopMs,
+  md: styles.cellGapTopMd,
+  lg: styles.cellGapTopLg,
+  xl: styles.cellGapTopXl,
+  xxl: styles.cellGapTopXxl,
+  xxxl: styles.cellGapTopXxxl,
+} as const satisfies Record<SpacingToken, unknown>
+
+export function Grid({gap = 'md', columns, minColumnWidth, layout, children}: GridProps) {
+  if (isNative) {
+    return (
+      <NativeGrid
+        gap={gap}
+        columns={layout ? layoutWeights[layout] : columns}
+        minColumnWidth={layout ? undefined : minColumnWidth}
+      >
+        {children}
+      </NativeGrid>
+    )
+  }
+
+  const columnStyle = layout
+    ? layoutMap[layout]
+    : minColumnWidth
+      ? styles.autoFit(minColumnWidth)
+      : typeof columns === 'number'
+        ? columnsMap[columns]
+        : columns
+          ? styles.template(gridTemplate(columnWeights(columns) ?? [1]))
+          : undefined
+
+  const grid = <html.div style={[styles.base, gapMap[gap], columnStyle]}>{children}</html.div>
+  // A named layout answers its container query from a wrapper: an element
+  // cannot query its own size.
+  return layout ? <html.div style={styles.splitContainer}>{grid}</html.div> : grid
+}
 
-  return <html.div style={[styles.base, gapMap[gap], columnStyle]}>{children}</html.div>
+/**
+ * React Native has no grid, so the native Grid is a wrapping flex row with
+ * each child in a cell:
+ *
+ * - Weighted / counted columns: the cell's `flexBasis` is its column's share
+ *   of the row. Percentages plus a real `gap` would overflow and wrap early,
+ *   so the gap is padding on the cell instead — left on every cell that does
+ *   not open a row, top on every row after the first. RN is border-box, so
+ *   the bases still sum to exactly 100%, and the gap stays a token.
+ * - `minColumnWidth`: cells start at that width and grow, and the row uses a
+ *   real `gap`, since here wrapping is width-driven and row membership is
+ *   not known from the index.
+ *
+ * Only this branch wraps children; on web grid children stay direct, so
+ * existing DOM trees are untouched.
+ */
+function NativeGrid({gap = 'md', columns, minColumnWidth, children}: GridProps) {
+  const items = Children.toArray(children)
+  if (minColumnWidth) {
+    return (
+      <html.div style={[styles.nativeRow, gapMap[gap]]}>
+        {items.map((child, index) => (
+          <html.div key={index} style={styles.nativeMinCell(minColumnWidth)}>
+            {child}
+          </html.div>
+        ))}
+      </html.div>
+    )
+  }
+  const weights = columnWeights(columns) ?? [1]
+  return (
+    <html.div style={styles.nativeRow}>
+      {items.map((child, index) => {
+        const {opensRow, firstRow} = cellPosition(index, weights.length)
+        return (
+          <html.div
+            key={index}
+            style={[
+              styles.nativeCell(cellBasis(weights, index)),
+              !opensRow && cellGapLeftMap[gap],
+              !firstRow && cellGapTopMap[gap],
+            ]}
+          >
+            {child}
+          </html.div>
+        )
+      })}
+    </html.div>
+  )
 }

package/src/components/Grid/columns.ts

@@ -0,0 +1,58 @@
+// Pure column arithmetic behind Grid. No react-strict-dom, no platform: this
+// is what the unit project tests, and what both the web and native renderers
+// derive their styles from.
+
+export type GridColumnCount = 1 | 2 | 3 | 4 | 5 | 6
+
+/**
+ * Column spec: a count (equal columns) or a list of weights (`[1, 2]` is a
+ * one-third / two-thirds split). Weights are the portable form of
+ * `grid-template-columns: 1fr 2fr` — the only shape both runtimes can
+ * honour, since React Native has no grid.
+ */
+export type GridColumns = GridColumnCount | readonly number[]
+
+/** Normalise a column spec to weights; `undefined` when no spec was given
+ *  (the caller then falls back to auto-fit or a single column). An invalid
+ *  weight list (empty, non-finite or non-positive entries) is a programming
+ *  error, reported in development and treated as one column. */
+export function columnWeights(columns: GridColumns | undefined): readonly number[] | undefined {
+  if (columns === undefined) return undefined
+  if (typeof columns === 'number') return Array.from({length: columns}, () => 1)
+  const valid = columns.length > 0 && columns.every((w) => Number.isFinite(w) && w > 0)
+  if (!valid) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.error(
+        `Grid: \`columns\` must be a non-empty list of positive numbers, got ${JSON.stringify(columns)}. Falling back to one column.`,
+      )
+    }
+    return [1]
+  }
+  return columns
+}
+
+/** Web track list: `[1, 2]` → `"1fr 2fr"`. */
+export function gridTemplate(weights: readonly number[]): string {
+  return weights.map((w) => `${w}fr`).join(' ')
+}
+
+/** Native cell basis for the child at `index`: its column's share of the row
+ *  as a percentage string Yoga accepts (`"33.3333%"`). Children flow into
+ *  columns in order and wrap, exactly like grid auto-placement. */
+export function cellBasis(weights: readonly number[], index: number): string {
+  const total = weights.reduce((sum, w) => sum + w, 0)
+  const share = (weights[index % weights.length] / total) * 100
+  // Four decimals keeps a row summing to 100% within Yoga's tolerance while
+  // never exceeding it (which would wrap the last cell).
+  return `${Math.floor(share * 10000) / 10000}%`
+}
+
+/** Where the child at `index` sits in an `columnCount`-wide flow: whether it
+ *  opens a row (no gap to its left) and whether it is on the first row (no
+ *  gap above). Drives the native gap-as-padding scheme. */
+export function cellPosition(
+  index: number,
+  columnCount: number,
+): {opensRow: boolean; firstRow: boolean} {
+  return {opensRow: index % columnCount === 0, firstRow: index < columnCount}
+}