@duro-app/ui 0.44.0 → 0.46.0

package/package.json

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

package/src/components/Table/SortChip.tsx

@@ -13,6 +13,13 @@ export interface SortChipProps {
   readonly onChange: (next: SortValue | null) => void
   /** Visible label preceding the sort field, e.g. "Sort by". */
   readonly label?: string
+  /**
+   * Reveal the chip regardless of the container query. Injected by
+   * `Table.Root` when it force-stacks a cramped medium-width table (headers
+   * hidden but container wider than the mobile breakpoint, so the chip's own
+   * `@container` rule hasn't fired). Not part of the public API.
+   */
+  readonly forceShow?: boolean
 }
 
 /**
@@ -24,12 +31,18 @@ export interface SortChipProps {
  * couple to @tanstack/react-table — the consumer wires `value` and
  * `onChange` from whatever sort state they manage.
  */
-export function SortChip({options, value, onChange, label = 'Sort by'}: SortChipProps) {
+export function SortChip({
+  options,
+  value,
+  onChange,
+  label = 'Sort by',
+  forceShow = false,
+}: SortChipProps) {
   const current = value ? options.find((o) => o.id === value.id) : null
   const triggerLabel = current ? `${label}: ${current.label} ${value!.desc ? '↓' : '↑'}` : label
 
   return (
-    <html.div style={styles.sortChip}>
+    <html.div style={[styles.sortChip, forceShow && styles.sortChipStacked]}>
       <Menu.Root>
         <Menu.Trigger>{triggerLabel}</Menu.Trigger>
         <Menu.Popup>

package/src/components/Table/Table.stories.tsx

@@ -1,5 +1,5 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {useState} from 'react'
 import {Table} from './Table'
@@ -1142,6 +1142,14 @@ export const SlotPropsOnRoot: Story = {
 // grid track into the next column. Cells now shrink to their track and wrap.
 const overlapWrapStyles = css.create({
   wide: {width: 760},
+  // 6 columns in 560px, above the 440px mobile breakpoint, so the @container
+  // query never fires — only the JS overflow check catches that the action
+  // buttons no longer fit their squeezed track.
+  cramped: {width: 560},
+  // 8 short-text columns with room to breathe: nothing overflows, so a
+  // wide "grants-style" table must stay tabular even though it has many
+  // columns (regression guard against the old column-count heuristic).
+  roomy: {width: 1120},
 })
 
 const LONG_EMAIL = 'a-really-long-service-account.address@subdomain.example-company.com'
@@ -1191,3 +1199,119 @@ export const ManyColumnsWrapNoOverlap: Story = {
     await expect(emailCell.scrollWidth).toBeLessThanOrEqual(emailCell.clientWidth + 2)
   },
 }
+
+// A dense table wider than the 440px mobile breakpoint but too narrow to give
+// each column a comfortable width. The @container query never fires (560 >
+// 440), so this asserts the JS ResizeObserver force-stacks it into cards:
+// 6 columns × 128px default = 768px threshold > 560px container.
+export const AutoStacksWhenCramped: Story = {
+  name: 'Auto-stacks when columns get cramped',
+  render: () => (
+    <html.div style={overlapWrapStyles.cramped}>
+      <Table.Root>
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell>Display Name</Table.HeaderCell>
+            <Table.HeaderCell>Type</Table.HeaderCell>
+            <Table.HeaderCell>Email</Table.HeaderCell>
+            <Table.HeaderCell>Status</Table.HeaderCell>
+            <Table.HeaderCell>Owner</Table.HeaderCell>
+            {/* Normal 1fr track (no max-content) so the buttons get squeezed
+                and overflow — the exact condition the auto-stack detects. */}
+            <Table.HeaderCell>Actions</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>SMTP submission service account</Table.Cell>
+            <Table.Cell>
+              <Badge>User</Badge>
+            </Table.Cell>
+            <Table.Cell>{LONG_EMAIL}</Table.Cell>
+            <Table.Cell>
+              <Badge variant="warning">No certs</Badge>
+            </Table.Cell>
+            <Table.Cell>daddy</Table.Cell>
+            <Table.Cell isActions>
+              <Button size="small">Send Cert</Button>
+              <Button size="small" variant="secondary">
+                Revoke
+              </Button>
+            </Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const grid = canvas.getByRole('table')
+    // ResizeObserver fires post-layout; wait for the stack decision to commit.
+    await waitFor(async () => {
+      // The grid collapses to a single column — one resolved track, no spaces.
+      const tracks = getComputedStyle(grid).gridTemplateColumns.trim().split(/\s+/)
+      await expect(tracks.length).toBe(1)
+    })
+    // Header group is display:none, so it drops out of the accessibility tree:
+    // no column headers remain queryable, leaving only the body rowgroup.
+    await expect(canvas.queryAllByRole('columnheader')).toHaveLength(0)
+    await expect(canvas.getAllByRole('rowgroup')).toHaveLength(1)
+    // Each body cell now surfaces its label span (label|value card rows). The
+    // hidden header 'Owner' stays in the DOM, so pick the visible <span>.
+    const ownerLabel = canvas
+      .getAllByText('Owner')
+      .find((el) => el.tagName.toLowerCase() === 'span') as HTMLElement
+    await expect(ownerLabel).toBeTruthy()
+    await expect(getComputedStyle(ownerLabel).display).toBe('block')
+  },
+}
+
+// Regression guard for the grants over-stacking bug: a table with MANY
+// columns (8) that all fit comfortably must stay tabular. The old heuristic
+// stacked purely on column count (8 × 128px = 1024px threshold), carding up a
+// table that visually fits on a laptop. Overflow-based detection keeps it
+// tabular because nothing actually overflows.
+export const ManyColumnsStayTabularWhenFitting: Story = {
+  name: 'Many columns stay tabular when they fit',
+  render: () => (
+    <html.div style={overlapWrapStyles.roomy}>
+      <Table.Root>
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell>Principal</Table.HeaderCell>
+            <Table.HeaderCell>Application</Table.HeaderCell>
+            <Table.HeaderCell>Role</Table.HeaderCell>
+            <Table.HeaderCell>Entitlement</Table.HeaderCell>
+            <Table.HeaderCell>Resource</Table.HeaderCell>
+            <Table.HeaderCell>Granted by</Table.HeaderCell>
+            <Table.HeaderCell>Expires</Table.HeaderCell>
+            <Table.HeaderCell>Status</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>alice</Table.Cell>
+            <Table.Cell>Immich</Table.Cell>
+            <Table.Cell>Editor</Table.Cell>
+            <Table.Cell>library</Table.Cell>
+            <Table.Cell>all</Table.Cell>
+            <Table.Cell>daddy</Table.Cell>
+            <Table.Cell>Never</Table.Cell>
+            <Table.Cell>
+              <Badge variant="success">Active</Badge>
+            </Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const grid = canvas.getByRole('table')
+    // Give the ResizeObserver a chance to (not) fire, then assert it stayed
+    // tabular: 8 header cells still in the a11y tree, grid keeps 8 tracks.
+    await waitFor(async () => {
+      await expect(canvas.queryAllByRole('columnheader')).toHaveLength(8)
+    })
+    const tracks = getComputedStyle(grid).gridTemplateColumns.trim().split(/\s+/)
+    await expect(tracks.length).toBe(8)
+  },
+}

package/src/components/Table/Table.tsx

@@ -3,8 +3,12 @@ import {
   type ReactNode,
   type MutableRefObject,
   createContext,
+  cloneElement,
   useContext,
+  useEffect,
+  useLayoutEffect,
   useRef,
+  useState,
   Children,
   isValidElement,
 } from 'react'
@@ -31,6 +35,43 @@ interface TableContextValue {
   labels: ReadonlyArray<string>
   /** Mutable ref: header Row writes inferred template, Root reads it */
   inferredTemplateRef: MutableRefObject<string | null>
+  /** JS-measured force-stack flag. True when Root's ResizeObserver finds the
+   *  container too narrow for its column count (cells would be crushed), so
+   *  every cell/row/header also applies its `*Stacked` variant. Independent
+   *  of the @container base, which still handles genuinely narrow widths. */
+  stacked: boolean
+}
+
+// useLayoutEffect measures + commits the stack decision before the browser
+// paints, so a client-rendered narrow table shows cards on first frame
+// rather than flashing tabular. On the server it would warn (no layout), so
+// fall back to useEffect there — SSR always emits the non-stacked markup and
+// the @container CSS covers true mobile without JS.
+const useIsoLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect
+
+// Does any column's content no longer fit its box? We sample the header row
+// plus the first body row (bounded cost). Free text wraps rather than
+// overflowing (min-width:0 + overflow-wrap), so this only trips on content
+// that genuinely can't shrink — action buttons, badges, or nowrap header
+// labels — i.e. the real "columns won't fit" signal, independent of how many
+// columns there are. Structural overflow is consistent down a column, so the
+// first body row is a faithful sample.
+function gridOverflows(grid: HTMLDivElement | null): boolean {
+  if (!grid) return false
+  const TOL = 2 // sub-pixel layout rounding slack
+  const over = (el: Element) => el.scrollWidth - el.clientWidth > TOL
+  for (const h of grid.querySelectorAll('[role="columnheader"]')) {
+    if (over(h)) return true
+  }
+  const rowgroups = grid.querySelectorAll('[role="rowgroup"]')
+  const body = rowgroups[rowgroups.length - 1] // header is first, body last
+  const firstRow = body?.querySelector('[role="row"]')
+  if (firstRow) {
+    for (const c of firstRow.querySelectorAll('[role="cell"]')) {
+      if (over(c)) return true
+    }
+  }
+  return false
 }
 
 const TableContext = createContext<TableContextValue | null>(null)
@@ -172,7 +213,7 @@ interface RootProps {
   children: ReactNode
   variant?: TableVariant
   size?: TableSize
-  /** Opt out of responsive container-query behavior. Default true. */
+  /** Opt out of responsive behavior (auto-stacking + container query). Default true. */
   responsive?: boolean
   /**
    * Optional sort UI rendered above the grid. Visible only in stack mode
@@ -201,9 +242,67 @@ export function Root({
     inferredTemplateRef.current = template
   }
 
+  // Content-aware stacking driven by ACTUAL overflow, not a width heuristic.
+  // Column count alone is a poor proxy — a table with 8 short-text columns
+  // fits fine on a laptop, while 4 columns of buttons + long emails can be
+  // crushed. So instead of guessing, we render tabular and check whether any
+  // cell's content actually overflows its box (scrollWidth > clientWidth);
+  // when it does, the columns can't fit and we card up. The @container base
+  // (styles.*: STACK_BP) still stacks true-mobile widths without JS.
+  //
+  // Oscillation guard: stacking changes the layout (cards never overflow), so
+  // we can't re-measure overflow while stacked. We latch the container width
+  // at the moment we stacked and only return to tabular once the container
+  // has grown comfortably past it (hysteresis), then re-check overflow fresh.
+  const containerRef = useRef<HTMLDivElement>(null)
+  const gridRef = useRef<HTMLDivElement>(null)
+  const [stacked, setStacked] = useState(false)
+  const stackedAtWidthRef = useRef(0)
+
+  // Re-runs whenever `stacked` flips: after we drop back to tabular the
+  // container width is unchanged, so the ResizeObserver won't fire — the
+  // effect re-running is what re-checks overflow in the fresh tabular layout.
+  useIsoLayoutEffect(() => {
+    if (!responsive) {
+      setStacked(false)
+      return
+    }
+    const el = containerRef.current
+    if (!el || typeof ResizeObserver === 'undefined') return
+
+    // Grows-back margin: only leave stack mode once we're well clear of the
+    // width that triggered it, so a 1px jiggle at the boundary can't flip-flop.
+    const HYSTERESIS = 48
+
+    const measure = (width: number) => {
+      if (width <= 0) return
+      if (!stacked) {
+        if (gridOverflows(gridRef.current)) {
+          stackedAtWidthRef.current = width
+          setStacked(true)
+        }
+      } else if (width > stackedAtWidthRef.current + HYSTERESIS) {
+        // Drop back to tabular; this effect re-runs and re-checks overflow.
+        setStacked(false)
+      }
+    }
+
+    measure(el.getBoundingClientRect().width)
+    const ro = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (!entry) return
+      const box = entry.contentBoxSize?.[0]
+      measure(box ? box.inlineSize : entry.contentRect.width)
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+    // labels.length re-runs detection when the column set changes.
+  }, [responsive, labels.length, stacked])
+
   const grid = (
     <html.div
       role="table"
+      ref={gridRef}
       style={[
         styles.root,
         // When responsive, use gridColumnsResponsive so the explicit column
@@ -218,26 +317,45 @@ export function Root({
             : styles.gridColumns(template)
           : undefined,
         responsive && styles.rootResponsive,
+        // Force-stack override — collapses the grid to one column. Applied
+        // last so its gridTemplateColumns wins over gridColumnsResponsive.
+        responsive && stacked && styles.rootStacked,
       ]}
     >
       {children}
     </html.div>
   )
 
+  // The sort chip is normally revealed only by the @container query. When
+  // JS force-stacks (headers hidden, but container wider than STACK_BP) the
+  // chip's own query hasn't fired, so inject forceShow to reveal it.
+  const sortChipEl =
+    stacked && isValidElement(sortChip)
+      ? cloneElement(sortChip as ReactElement<{forceShow?: boolean}>, {forceShow: true})
+      : sortChip
+
   // Slots render unconditionally — `responsive=false` still wants its sort/
   // pagination chrome. Only the containerType:inline-size wrapper is
   // conditional, since it only matters when @container queries fire.
   const body = (
     <>
-      {sortChip}
+      {sortChipEl}
       {grid}
       {pagination}
     </>
   )
 
   return (
-    <TableContext.Provider value={{variant, size, responsive, labels, inferredTemplateRef}}>
-      {responsive ? <html.div style={styles.rootContainer}>{body}</html.div> : body}
+    <TableContext.Provider
+      value={{variant, size, responsive, labels, inferredTemplateRef, stacked}}
+    >
+      {responsive ? (
+        <html.div ref={containerRef} style={styles.rootContainer}>
+          {body}
+        </html.div>
+      ) : (
+        body
+      )}
     </TableContext.Provider>
   )
 }
@@ -245,9 +363,10 @@ export function Root({
 // --- Header ---
 
 export function Header({children}: {children: ReactNode}) {
+  const {stacked} = useTable()
   return (
     <HeaderContext.Provider value={true}>
-      <html.div role="rowgroup" style={styles.header}>
+      <html.div role="rowgroup" style={[styles.header, stacked && styles.headerStacked]}>
         {children}
       </html.div>
     </HeaderContext.Provider>
@@ -311,7 +430,7 @@ const INTERACTIVE_SELECTOR =
   'button, a, input, select, textarea, [role="button"], [role="link"], [role="checkbox"], [role="menuitem"], [role="switch"], [role="tab"], [contenteditable="true"]'
 
 export function Row({children, onClick, 'aria-label': ariaLabel}: RowProps) {
-  const {variant} = useTable()
+  const {variant, stacked} = useTable()
   const isHeader = useContext(HeaderContext)
   const rowIndex = useContext(RowIndexContext)
   const isEvenRow = rowIndex >= 0 && rowIndex % 2 === 1
@@ -353,6 +472,9 @@ export function Row({children, onClick, 'aria-label': ariaLabel}: RowProps) {
         !isHeader && styles.bodyRow,
         !isHeader && variant === 'striped' && isEvenRow && styles.stripedEven,
         isClickable && styles.clickableRow,
+        stacked && styles.rowStacked,
+        // bodyRowStacked last so its card background wins over stripedEven.
+        !isHeader && stacked && styles.bodyRowStacked,
       ]}
     >
       {childArray.map((child, index) => (
@@ -441,7 +563,7 @@ HeaderCell.displayName = 'HeaderCell'
 // isActions=true — actions footers don't show a label.
 
 export function Cell({children, isActions}: {children: ReactNode; isActions?: boolean}) {
-  const {size, variant, labels, responsive} = useTable()
+  const {size, variant, labels, responsive, stacked} = useTable()
   const {index, total} = useContext(CellIndexContext)
   const isLast = variant === 'bordered' && index === total - 1
   const label = labels[index] ?? ''
@@ -455,10 +577,20 @@ export function Cell({children, isActions}: {children: ReactNode; isActions?: bo
         variant === 'bordered' && styles.borderedCell,
         isLast && styles.borderedCellLast,
         isActions && styles.cellActions,
+        // Force-stack: cells become a label|value grid; the actions cell then
+        // overrides its template to a single track and turns into the card's
+        // right-aligned footer. Mirrors the @container (STACK_BP) branch, so
+        // cellStacked applies for every cell and cellActionsStacked layers on
+        // top for actions (its gridTemplateColumns wins as the later entry).
+        stacked && styles.cellStacked,
+        isActions && stacked && styles.cellActionsStacked,
+        variant === 'bordered' && stacked && styles.borderedCellStacked,
       ]}
     >
       {responsive && !isActions && label !== '' ? (
-        <html.span style={styles.cellLabel}>{label}</html.span>
+        <html.span style={[styles.cellLabel, stacked && styles.cellLabelStacked]}>
+          {label}
+        </html.span>
       ) : null}
       {isActions ? children : <html.div style={styles.cellValue}>{children}</html.div>}
     </html.div>

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

@@ -320,6 +320,63 @@ export const styles = css.create({
     alignSelf: 'flex-start',
   },
 
+  // --- JS-measured force-stack variants ---
+  //
+  // A container query can only test the container's WIDTH — it can't know
+  // "6 columns won't fit here". So a dense table can be wider than STACK_BP
+  // yet still crush every cell to a few characters. Table.Root measures the
+  // container with a ResizeObserver and, when `width < columnCount ×
+  // minColumnWidth`, sets `stacked` in context; each component then also
+  // applies its `*Stacked` variant here. These mirror the values in the
+  // `@container (max-width: ${STACK_BP})` branches above, so JS-forced and
+  // CSS-driven stacking render identically. The @container base is kept as
+  // the SSR-safe path for genuinely narrow (mobile) widths — no JS, no
+  // hydration flash — while these handle the cramped medium-width case.
+  rootStacked: {
+    gridTemplateColumns: '1fr',
+    borderWidth: 0,
+    backgroundColor: 'transparent',
+    overflow: 'visible',
+    rowGap: spacing.sm,
+  },
+  headerStacked: {
+    display: 'none',
+  },
+  rowStacked: {
+    gridTemplateColumns: '1fr',
+    borderBottomWidth: 0,
+  },
+  bodyRowStacked: {
+    backgroundColor: {
+      default: colors.bgCard,
+      ':hover': colors.bgCardHover,
+    },
+    padding: spacing.sm,
+    borderRadius: radii.sm,
+    borderWidth: 1,
+  },
+  cellStacked: {
+    display: 'grid',
+    gridTemplateColumns: '1fr 2fr',
+    gap: spacing.sm,
+  },
+  cellLabelStacked: {
+    display: 'block',
+  },
+  cellActionsStacked: {
+    gridTemplateColumns: '1fr',
+    justifyContent: 'flex-end',
+    marginTop: spacing.sm,
+    paddingTop: spacing.sm,
+    borderTopWidth: 1,
+  },
+  borderedCellStacked: {
+    borderRightWidth: 0,
+  },
+  sortChipStacked: {
+    display: 'inline-flex',
+  },
+
   // Dynamic: grid columns applied on Root (non-responsive path only).
   gridColumns: (template: string) => ({
     gridTemplateColumns: template,

package/src/components/Tag/Tag.stories.tsx

@@ -49,8 +49,30 @@ export const Small: Story = {
 const layoutStyles = css.create({
   row: {display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap'},
   stack: {display: 'flex', flexDirection: 'column', gap: 16},
+  // Narrow column that a long identifier tag would overflow without `wrap`.
+  narrowCol: {width: 120, borderWidth: 1, borderStyle: 'solid', borderColor: '#333', padding: 8},
 })
 
+const LONG_CAP = 'lldap.group.member.remove'
+
+// A long identifier-style tag in a narrow column: with `wrap` it breaks
+// within the column instead of overflowing (its scrollWidth stays within the
+// box), fixing the "capability leaks into the next column" bug.
+export const WrapLongLabel: Story = {
+  render: () => (
+    <html.div style={layoutStyles.narrowCol}>
+      <Tag size="sm" wrap>
+        {LONG_CAP}
+      </Tag>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const tag = canvas.getByText(LONG_CAP)
+    // Content wraps inside the tag; the tag doesn't spill past its column.
+    await expect(tag.scrollWidth).toBeLessThanOrEqual(tag.clientWidth + 2)
+  },
+}
+
 export const AllVariants: Story = {
   render: () => (
     <html.div style={layoutStyles.stack}>

package/src/components/Tag/Tag.tsx

@@ -16,6 +16,14 @@ interface TagProps {
   /** Called when remove button is clicked. Auto-wired to TagGroup when inside one. */
   onRemove?: () => void
   disabled?: boolean
+  /**
+   * Allow the label to wrap / break instead of staying on one line. Tags are
+   * `white-space: nowrap` by default (they read as pills); set this for long
+   * identifier-style values (e.g. `lldap.group.member.remove`) sitting in a
+   * constrained column, so they break within their cell instead of leaking
+   * into the next one.
+   */
+  wrap?: boolean
   children: ReactNode
 }
 
@@ -36,6 +44,7 @@ export function Tag({
   removable: removableProp,
   onRemove: onRemoveProp,
   disabled: disabledProp = false,
+  wrap = false,
   children,
 }: TagProps) {
   const group = useTagGroup()
@@ -133,6 +142,7 @@ export function Tag({
         removable && removableSizeMap[size],
         styles[variant],
         disabled && styles.disabled,
+        wrap && styles.wrap,
       ]}
     >
       {tagContent}

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

@@ -13,6 +13,7 @@ export const styles = css.create({
     lineHeight: 1,
     borderRadius: 4,
     whiteSpace: 'nowrap',
+    minWidth: 0,
     borderWidth: 1,
     borderStyle: 'solid',
     borderColor: colors.border,
@@ -47,6 +48,17 @@ export const styles = css.create({
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
   },
+  // Opt-in wrapping for long identifier-style labels. Overrides the base
+  // nowrap so the text breaks within its container (e.g. a table cell)
+  // instead of overflowing into the next column. `anywhere` also lets the
+  // tag shrink below its content's intrinsic width so a flex/grid parent can
+  // actually give it a narrow track.
+  wrap: {
+    whiteSpace: 'normal',
+    overflowWrap: 'anywhere',
+    lineHeight: 1.35,
+    textAlign: 'start',
+  },
   // Reduce right padding when removable to keep visual balance with the button
   removableMd: {
     paddingRight: spacing.sm,

package/src/components/VirtualTable/VirtualTable.stories.tsx

@@ -1,8 +1,14 @@
 import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn, waitFor} from 'storybook/test'
 import {createColumnHelper} from '@tanstack/react-table'
+import {css, html} from 'react-strict-dom'
 import {VirtualTable} from './VirtualTable'
 
+const storyStyles = css.create({
+  // Phone-width wrapper: below VirtualTable's 640px stackBelow default.
+  narrow: {width: 400},
+})
+
 interface Item {
   id: string
   name: string
@@ -87,3 +93,26 @@ export const ScrollReportsPage: Story = {
     await expect(maxPage).toBeGreaterThan(1)
   },
 }
+
+// In a narrow (phone-width) container the table cards up: header hides and
+// each row becomes a label/value card, like Table's stack mode.
+export const StacksOnNarrow: Story = {
+  args: {data: makeData(6), onRowClick: fn(), rowLabel: (r: Item) => r.name},
+  decorators: [
+    (Story) => (
+      <html.div style={storyStyles.narrow}>
+        <Story />
+      </html.div>
+    ),
+  ],
+  play: async ({canvas}) => {
+    // Header group not rendered → no column headers in the a11y tree.
+    await waitFor(async () => {
+      await expect(canvas.queryAllByRole('columnheader')).toHaveLength(0)
+    })
+    // Each card surfaces the column labels ('Name'/'Value') next to values.
+    await expect(canvas.getAllByText('Name').length).toBe(6)
+    await expect(canvas.getByText('Row 0')).toBeInTheDocument()
+    await expect(canvas.getByText('Row 5')).toBeInTheDocument()
+  },
+}