@duro-app/ui 3.0.0 → 3.1.0

package/package.json

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

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

@@ -2,11 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'CSS grid layout. Fixed column count (1-6), responsive auto-fit via minColumnWidth, or a named split layout (list/detail, nav/content) that collapses below the md breakpoint.',
+    '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 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',
@@ -42,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,4 +1,5 @@
 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'
@@ -19,6 +20,7 @@ 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']},
@@ -41,6 +43,12 @@ const localStyles = css.create({
     fontSize: typography.fontSizeXs,
     color: colors.textMuted,
   },
+  frame: (width: number) => ({
+    width,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    borderColor: colors.border,
+  }),
 })
 
 const Cell = ({children}: {children: string}) => (
@@ -89,7 +97,8 @@ export const Split: Story = {
   render: () => (
     <Stack gap="sm">
       <html.span style={localStyles.label}>
-        layout=&quot;split&quot; — list ≥ 240px beside the detail, one column below md
+        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>
@@ -103,6 +112,79 @@ export const Split: Story = {
   ),
 }
 
+/**
+ * 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,18 +1,29 @@
-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); both collapse to one
-   * column below the `md` breakpoint. Wins over `columns` / `minColumnWidth`.
+   * `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
@@ -29,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,
@@ -43,14 +56,111 @@ const layoutMap = {
   '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)
-      : columns
+      : typeof columns === 'number'
         ? columnsMap[columns]
-        : undefined
+        : 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}
+}

package/src/components/Grid/styles.css.ts

@@ -2,9 +2,15 @@ import {css} from 'react-strict-dom'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {breakpoints} from '@duro-app/tokens/tokens/breakpoints.css'
 
-// Where a split collapses to one column. A defineConsts string, inlined into
-// the @media text at build time.
-const SPLIT_BP = breakpoints.md
+// Where a split collapses to one column — measured on the split's OWN
+// container, not the viewport. A split nested in another split (a list/detail
+// board inside a nav/content shell) has far less room than the window: at a
+// 768px viewport the shell leaves ~408px for its content column, and a
+// viewport-keyed inner split would still open there and squeeze its detail
+// pane to ~150px. Container queries collapse each split on what it actually
+// has. defineConsts strings, inlined into the @container text at build time.
+const SPLIT_WIDE_BP = breakpoints.md // 280px rail + real content
+const SPLIT_BP = breakpoints.sm // 240px list + ≥ 384px detail
 
 export const styles = css.create({
   base: {
@@ -19,22 +25,34 @@ export const styles = css.create({
   autoFit: (minWidth: string) => ({
     gridTemplateColumns: `repeat(auto-fill, minmax(${minWidth}, 1fr))`,
   }),
+  // Hosts the @container query for a named layout. A container cannot query
+  // itself, so the grid sits inside this wrapper (the Table.rootContainer
+  // pattern). Only `layout` grids get it: counted and weighted grids keep
+  // their DOM exactly as before.
+  splitContainer: {
+    containerType: 'inline-size',
+  },
   // Asymmetric list/detail splits: a bounded first column, the rest for the
-  // detail; one column below the md breakpoint. Static entries rather than a
-  // parameter because the pair (widths + collapse point) is the design
-  // decision — a screen picks a split, it does not tune one.
+  // detail; one column when the container is narrower than the breakpoint.
+  // Static entries rather than a parameter because the pair (widths +
+  // collapse point) is the design decision — a screen picks a split, it does
+  // not tune one.
   split: {
     gridTemplateColumns: {
       default: '1fr',
-      [`@media (min-width: ${SPLIT_BP})`]: 'minmax(240px, 1fr) minmax(0, 2fr)',
+      [`@container (min-width: ${SPLIT_BP})`]: 'minmax(240px, 1fr) minmax(0, 2fr)',
     },
   },
   splitWide: {
     gridTemplateColumns: {
       default: '1fr',
-      [`@media (min-width: ${SPLIT_BP})`]: 'minmax(280px, 1fr) minmax(0, 3fr)',
+      [`@container (min-width: ${SPLIT_WIDE_BP})`]: 'minmax(280px, 1fr) minmax(0, 3fr)',
     },
   },
+  // Weighted columns: `[1, 2]` → `1fr 2fr` (see columns.ts).
+  template: (tracks: string) => ({
+    gridTemplateColumns: tracks,
+  }),
   gapXs: {gap: spacing.xs},
   gapSm: {gap: spacing.sm},
   gapMs: {gap: spacing.ms},
@@ -43,4 +61,50 @@ export const styles = css.create({
   gapXl: {gap: spacing.xl},
   gapXxl: {gap: spacing.xxl},
   gapXxxl: {gap: spacing.xxxl},
+
+  // --- native only (see NativeGrid in Grid.tsx) -----------------------------
+  // React Native honours `display: 'flex'` only, and RSD gives it web flex
+  // semantics, so the row direction is explicit.
+  nativeRow: {
+    display: 'flex',
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'stretch',
+    // A definite width so percentage bases resolve in Yoga's measure pass;
+    // against an auto width the line breaks come out wrong and the container
+    // under-reports its height (verified on the iOS simulator).
+    width: '100%',
+  },
+  // border-box is explicit: react-strict-dom mirrors the web default
+  // (content-box) on native, which adds the gap padding on top of the basis
+  // and overflows the row so every cell wraps.
+  nativeCell: (basis: string) => ({
+    flexBasis: basis,
+    flexShrink: 0,
+    boxSizing: 'border-box',
+  }),
+  // Auto-fit approximation: start at the minimum width, grow to fill. flexGrow
+  // is fine here: this style is native-only, so RSD-web's forced flex-grow: 0
+  // never applies.
+  nativeMinCell: (minWidth: string) => ({
+    flexBasis: minWidth,
+    flexGrow: 1,
+    boxSizing: 'border-box',
+  }),
+  cellGapLeftXs: {paddingLeft: spacing.xs},
+  cellGapLeftSm: {paddingLeft: spacing.sm},
+  cellGapLeftMs: {paddingLeft: spacing.ms},
+  cellGapLeftMd: {paddingLeft: spacing.md},
+  cellGapLeftLg: {paddingLeft: spacing.lg},
+  cellGapLeftXl: {paddingLeft: spacing.xl},
+  cellGapLeftXxl: {paddingLeft: spacing.xxl},
+  cellGapLeftXxxl: {paddingLeft: spacing.xxxl},
+  cellGapTopXs: {paddingTop: spacing.xs},
+  cellGapTopSm: {paddingTop: spacing.sm},
+  cellGapTopMs: {paddingTop: spacing.ms},
+  cellGapTopMd: {paddingTop: spacing.md},
+  cellGapTopLg: {paddingTop: spacing.lg},
+  cellGapTopXl: {paddingTop: spacing.xl},
+  cellGapTopXxl: {paddingTop: spacing.xxl},
+  cellGapTopXxxl: {paddingTop: spacing.xxxl},
 })