@duro-app/ui 0.46.0 → 0.48.0

package/src/components/Table/Table.tsx

@@ -3,10 +3,8 @@ import {
   type ReactNode,
   type MutableRefObject,
   createContext,
-  cloneElement,
   useContext,
   useEffect,
-  useLayoutEffect,
   useRef,
   useState,
   Children,
@@ -35,43 +33,6 @@ 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)
@@ -148,7 +109,10 @@ function unwrapElementType(t: unknown): unknown {
   return current
 }
 
-function extractColumnMeta(children: ReactNode): {
+function extractColumnMeta(
+  children: ReactNode,
+  minColumnWidth: number,
+): {
   template: string
   compactTemplate: string
   labels: string[]
@@ -167,14 +131,14 @@ function extractColumnMeta(children: ReactNode): {
         (unwrappedType as {name?: string} | null)?.name ||
         ''
       if (unwrappedType === HeaderCell || displayName === 'HeaderCell') {
-        // Default to minmax(0, 1fr) instead of plain '1fr' so each column
-        // can shrink below its content's min-content size. A plain '1fr'
-        // track has an implicit min of `auto` (= min-content), which makes
-        // the column refuse to shrink and the whole table overflow when a
-        // cell's text is wider than 1/N of the container. With minmax(0,
-        // 1fr), the cell's compact-mode `min-width: 0` + `overflow:
-        // hidden` + `text-overflow: ellipsis` can actually truncate.
-        const width = props.width || 'minmax(0, 1fr)'
+        // Default each column to `minmax(<minColumnWidth>px, 1fr)`: columns
+        // share the row evenly (1fr) but never shrink below a readable floor.
+        // That floor is what makes a dense table overflow its container
+        // instead of crushing — Root's scroll wrapper then scrolls sideways.
+        // Narrow columns (a checkbox) or naturally-wide ones (an actions
+        // cell) override this with an explicit `width` (e.g. '40px',
+        // 'max-content').
+        const width = props.width || `minmax(${minColumnWidth}px, 1fr)`
         widths.push(width)
         // `compactWidth` lets the consumer switch to a content-aware
         // layout in the compact band while staying evenly distributed
@@ -207,14 +171,71 @@ function extractColumnMeta(children: ReactNode): {
   }
 }
 
+// --- ScrollFrame ---
+//
+// Wraps the grid in the horizontal-scroll port and paints a soft fade at
+// whichever edge still has hidden columns, so a scrollable table advertises
+// that there's more to see (and stops advertising once you reach the end).
+// This is the ONLY JS the responsive Table uses, and it's purely cosmetic —
+// it reads scroll position and toggles fade opacity; it never changes layout,
+// so none of the flicker/oscillation risk of the old auto-stacking applies.
+function ScrollFrame({children}: {children: ReactNode}) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const [edges, setEdges] = useState({start: false, end: false})
+
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const update = () => {
+      const overflowing = el.scrollWidth - el.clientWidth > 1
+      setEdges({
+        start: overflowing && el.scrollLeft > 1,
+        end: overflowing && el.scrollLeft + el.clientWidth < el.scrollWidth - 1,
+      })
+    }
+    update()
+    el.addEventListener('scroll', update, {passive: true})
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(update) : null
+    ro?.observe(el)
+    return () => {
+      el.removeEventListener('scroll', update)
+      ro?.disconnect()
+    }
+  }, [])
+
+  return (
+    <html.div style={styles.scrollFrame}>
+      <html.div ref={scrollRef} style={styles.scrollX}>
+        {children}
+      </html.div>
+      <html.div
+        aria-hidden
+        style={[styles.edgeFade, styles.edgeFadeLeft, edges.start && styles.edgeFadeVisible]}
+      />
+      <html.div
+        aria-hidden
+        style={[styles.edgeFade, styles.edgeFadeRight, edges.end && styles.edgeFadeVisible]}
+      />
+    </html.div>
+  )
+}
+
 // --- Root ---
 
 interface RootProps {
   children: ReactNode
   variant?: TableVariant
   size?: TableSize
-  /** Opt out of responsive behavior (auto-stacking + container query). Default true. */
+  /** Opt out of responsive behavior (horizontal scroll + card breakpoint). Default true. */
   responsive?: boolean
+  /**
+   * Minimum width (px) each flexible column keeps before the table scrolls
+   * horizontally rather than crushing its cells. Columns still share the row
+   * evenly (`minmax(<minColumnWidth>px, 1fr)`); this is only the floor. Raise
+   * it for roomier columns (more scrolling), lower it to fit more before
+   * scrolling. Columns with an explicit `width` are unaffected. Default 120.
+   */
+  minColumnWidth?: number
   /**
    * Optional sort UI rendered above the grid. Visible only in stack mode
    * (SortChip carries its own `display: none → inline-flex` rule). Typical
@@ -233,76 +254,19 @@ export function Root({
   variant = 'default',
   size = 'md',
   responsive = true,
+  minColumnWidth = 120,
   sortChip,
   pagination,
 }: RootProps) {
   const inferredTemplateRef = useRef<string | null>(null)
-  const {template, compactTemplate, labels} = extractColumnMeta(children)
+  const {template, compactTemplate, labels} = extractColumnMeta(children, minColumnWidth)
   if (template) {
     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
@@ -317,45 +281,33 @@ 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
+  // Above the stack breakpoint the grid keeps each column ≥ minColumnWidth, so
+  // a dense table overflows this wrapper and scrolls sideways instead of
+  // crushing. Below it (@container ≤ sm) the grid is one column and there's
+  // nothing to scroll. Non-responsive tables opt out of the frame entirely.
+  const framedGrid = responsive ? <ScrollFrame>{grid}</ScrollFrame> : grid
 
   // 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.
+  // conditional, since it only matters when @container queries fire. SortChip
+  // reveals itself in card mode via its own @container rule — no JS needed.
   const body = (
     <>
-      {sortChipEl}
-      {grid}
+      {sortChip}
+      {framedGrid}
       {pagination}
     </>
   )
 
   return (
-    <TableContext.Provider
-      value={{variant, size, responsive, labels, inferredTemplateRef, stacked}}
-    >
-      {responsive ? (
-        <html.div ref={containerRef} style={styles.rootContainer}>
-          {body}
-        </html.div>
-      ) : (
-        body
-      )}
+    <TableContext.Provider value={{variant, size, responsive, labels, inferredTemplateRef}}>
+      {responsive ? <html.div style={styles.rootContainer}>{body}</html.div> : body}
     </TableContext.Provider>
   )
 }
@@ -363,10 +315,9 @@ 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, stacked && styles.headerStacked]}>
+      <html.div role="rowgroup" style={styles.header}>
         {children}
       </html.div>
     </HeaderContext.Provider>
@@ -430,7 +381,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, stacked} = useTable()
+  const {variant} = useTable()
   const isHeader = useContext(HeaderContext)
   const rowIndex = useContext(RowIndexContext)
   const isEvenRow = rowIndex >= 0 && rowIndex % 2 === 1
@@ -472,9 +423,6 @@ 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) => (
@@ -563,7 +511,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, stacked} = useTable()
+  const {size, variant, labels, responsive} = useTable()
   const {index, total} = useContext(CellIndexContext)
   const isLast = variant === 'bordered' && index === total - 1
   const label = labels[index] ?? ''
@@ -577,20 +525,10 @@ 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, stacked && styles.cellLabelStacked]}>
-          {label}
-        </html.span>
+        <html.span style={styles.cellLabel}>{label}</html.span>
       ) : null}
       {isActions ? children : <html.div style={styles.cellValue}>{children}</html.div>}
     </html.div>

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

@@ -3,13 +3,15 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+import {breakpoints} from '@duro-app/tokens/tokens/breakpoints.css'
 
-// Container-query thresholds. Picked for typical 5-7 column admin tables —
-// see Table.stories.tsx "Responsive" for the visual reasoning. Defined
-// once here so it's clear they're a design-system constant, not a magic
-// number sprinkled across files.
-const COMPACT_BP = '720px'
-const STACK_BP = '440px'
+// Container-query thresholds, from the shared breakpoint scale. `sm` (640px)
+// is the single "card up" line used across every table (Table + VirtualTable);
+// below it dense tables become cards, above it they stay tabular and scroll
+// horizontally. `md` (768px) is the compact band (tighter padding, nowrap
+// headers). These are inlined into the @container query text at build time.
+const COMPACT_BP = breakpoints.md
+const STACK_BP = breakpoints.sm
 
 export const styles = css.create({
   // Outer wrapper that hosts the @container query. Wraps SortChip + Root
@@ -68,6 +70,16 @@ export const styles = css.create({
   // always wins, so combining gridColumns + rootResponsive in one array would
   // silently drop the column template).
   rootResponsive: {
+    // Size the grid to its content so it can OVERFLOW the scroll wrapper
+    // rather than shrink: `min-content` here is the sum of each column's
+    // minimum track (the minmax() floor / its content), so a dense table
+    // grows past the container and Root's `scrollX` wrapper scrolls sideways.
+    // In stack mode the grid is a single column, so drop the floor to let the
+    // card fill the width instead of forcing a horizontal scrollbar.
+    minWidth: {
+      default: 'min-content',
+      [`@container (max-width: ${STACK_BP})`]: 0,
+    },
     // The card-list look needs the outer border to disappear in stack
     // mode — each row paints its own border.
     borderWidth: {
@@ -320,61 +332,55 @@ 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,
+  // Horizontal-scroll frame around the grid (responsive path). Above the
+  // stack breakpoint the grid keeps each column at least `minColumnWidth`
+  // wide (see the minmax() template), so a dense table overflows and this
+  // wrapper scrolls sideways instead of crushing its cells — the standard
+  // data-table behavior. In stack mode the grid collapses to one column, so
+  // nothing overflows and no scrollbar appears.
+  scrollX: {
+    overflowX: 'auto',
+    // Contain the scroll to this axis; vertical growth (rows) is natural.
+    overflowY: 'visible',
+    // Momentum scroll on touch + a stable gutter so the layout doesn't jump
+    // when the scrollbar shows.
+    WebkitOverflowScrolling: 'touch',
   },
-  cellStacked: {
-    display: 'grid',
-    gridTemplateColumns: '1fr 2fr',
-    gap: spacing.sm,
+
+  // Positioning context for the scroll-affordance edge fades, which sit on
+  // top of the scroll port (not inside it, so they don't scroll away).
+  scrollFrame: {
+    position: 'relative',
   },
-  cellLabelStacked: {
-    display: 'block',
+  // A soft fade pinned to a scroll edge that hints "there's more this way".
+  // It fades the content into the surface colour, so it reads in any theme.
+  // Toggled by opacity from JS scroll position; pointer-events off so it
+  // never eats clicks. Sits just inside the rounded frame border.
+  edgeFade: {
+    position: 'absolute',
+    top: 1,
+    bottom: 1,
+    width: spacing.xl,
+    pointerEvents: 'none',
+    opacity: 0,
+    transitionProperty: 'opacity',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
   },
-  cellActionsStacked: {
-    gridTemplateColumns: '1fr',
-    justifyContent: 'flex-end',
-    marginTop: spacing.sm,
-    paddingTop: spacing.sm,
-    borderTopWidth: 1,
+  edgeFadeLeft: {
+    left: 1,
+    borderTopLeftRadius: radii.md,
+    borderBottomLeftRadius: radii.md,
+    backgroundImage: `linear-gradient(to left, transparent, ${colors.bgCard})`,
   },
-  borderedCellStacked: {
-    borderRightWidth: 0,
+  edgeFadeRight: {
+    right: 1,
+    borderTopRightRadius: radii.md,
+    borderBottomRightRadius: radii.md,
+    backgroundImage: `linear-gradient(to right, transparent, ${colors.bgCard})`,
   },
-  sortChipStacked: {
-    display: 'inline-flex',
+  edgeFadeVisible: {
+    opacity: 1,
   },
 
   // Dynamic: grid columns applied on Root (non-responsive path only).
@@ -389,15 +395,18 @@ export const styles = css.create({
   // earlier classes (the LAST style wins per property key).
   //
   // - default: balanced multi-column layout for desktop widths
-  // - @container (max-width: COMPACT_BP): consumer-supplied "compact"
-  //   template, e.g. give a badge column max-content and let the action
-  //   column absorb the slack so its hint text fits on one line
+  // - compact band (STACK_BP < width ≤ COMPACT_BP): consumer-supplied
+  //   "compact" template. This is written as an explicit RANGE, not just
+  //   `max-width: COMPACT_BP`, so it does NOT also match below STACK_BP —
+  //   otherwise both the compact and the stack rule would set
+  //   gridTemplateColumns at card widths and StyleX's ordering could let the
+  //   (wider, 4-column) compact template shadow the single-column stack one.
   // - @container (max-width: STACK_BP): collapse to a single column so
   //   each row becomes a card
   gridColumnsResponsive: (template: string, compactTemplate: string) => ({
     gridTemplateColumns: {
       default: template,
-      [`@container (max-width: ${COMPACT_BP})`]: compactTemplate,
+      [`@container (${STACK_BP} < width <= ${COMPACT_BP})`]: compactTemplate,
       [`@container (max-width: ${STACK_BP})`]: '1fr',
     },
   }),

package/src/components/VirtualTable/VirtualTable.tsx

@@ -11,6 +11,7 @@ import {
   type Row,
 } from '@tanstack/react-table'
 import {useVirtualizer} from '@tanstack/react-virtual'
+import {breakpointsPx} from '@duro-app/tokens/tokens/breakpoints.css'
 import {styles} from './styles.css'
 
 // Measure + commit before paint on the client; no-op-safe on the server.
@@ -61,11 +62,10 @@ interface VirtualTableProps<TData> {
   virtualizeThreshold?: number
   /**
    * Below this container width (px) the table cards up: the header hides and
-   * each row becomes a label/value card (like Table's stack mode). Since the
-   * flex columns truncate rather than overflow, this is a deliberate
-   * phone-width breakpoint, not an auto content measurement. Cards disable
-   * windowing (variable heights), so keep phone lists reasonably short.
-   * Default 640. Set `responsive={false}` to disable entirely.
+   * each row becomes a label/value card (like Table's stack mode). Defaults to
+   * the shared `sm` breakpoint (640px) so every table cards up at the same
+   * line. Cards disable windowing (variable heights), so keep phone lists
+   * reasonably short. Set `responsive={false}` to disable entirely.
    */
   stackBelow?: number
   /** Opt out of the card-up-on-narrow behavior. Default true. */
@@ -98,7 +98,7 @@ export function VirtualTable<TData>({
   estimateRowHeight = 44,
   maxHeight = '70vh',
   virtualizeThreshold = 150,
-  stackBelow = 640,
+  stackBelow = breakpointsPx.sm,
   responsive = true,
   emptyLabel,
 }: VirtualTableProps<TData>) {