@startsimpli/ui 0.4.113 → 0.4.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.113",
+  "version": "0.4.115",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,9 +47,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.58"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -123,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.3"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/ui/__tests__/table-scroll.test.tsx

@@ -0,0 +1,153 @@
+/**
+ * Guards for the table's horizontal-scroll affordance (startsim-5pq7h).
+ *
+ * The defect these come from is PURELY VISUAL — "there is no sliding bar so it
+ * makes it difficult to see all the columns" — and jsdom has no layout, so
+ * NOTHING here proves a scrollbar is visible on screen. That claim is carried
+ * by browser measurement (headed Chrome + headed WebKit on macOS: 0px of
+ * scrollbar layout height before, 10px after, 0px when the table fits).
+ *
+ * What these DO guard is the two things a later edit can silently break:
+ *  - the CSS that produces the bar, including the `scrollbar-width` rule that
+ *    measurably DELETES it, and
+ *  - the "no decoration when nothing overflows" contract.
+ */
+import { render, screen } from '@testing-library/react'
+import { renderHook, act } from '@testing-library/react'
+import { useRef } from 'react'
+import { Table, TableBody, TableCell, TableRow } from '../table'
+import {
+  TABLE_SCROLL_CSS,
+  TABLE_SCROLL_STYLE_ID,
+  TABLE_SCROLLER_CLASS,
+  useScrollEdges,
+} from '../table-scroll'
+
+describe('TABLE_SCROLL_CSS', () => {
+  it('styles the webkit scrollbar, which is what gives the bar layout height', () => {
+    expect(TABLE_SCROLL_CSS).toContain(`.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar`)
+    expect(TABLE_SCROLL_CSS).toMatch(/height:\s*10px/)
+  })
+
+  /**
+   * The finding this test exists for. MEASURED in headed Chrome on macOS:
+   *
+   *   ::-webkit-scrollbar { height: 10px }                 -> 10px of layout height
+   *   the same rule PLUS scrollbar-width / scrollbar-color ->  0px (overlay again)
+   *
+   * Chromium honours the standard properties instead of the custom scrollbar
+   * and reverts to a zero-height overlay bar. Every "cross-browser scrollbar"
+   * snippet on the web tells you to add them, and doing so here would silently
+   * undo the fix with no visible error anywhere. Firefox on macOS gains nothing
+   * from them either (measured 0px with the property confirmed applied), so
+   * there is no browser to trade away.
+   */
+  it('does NOT set scrollbar-width or scrollbar-color, which would revert Chromium to an overlay bar', () => {
+    expect(TABLE_SCROLL_CSS).not.toMatch(/scrollbar-width/)
+    expect(TABLE_SCROLL_CSS).not.toMatch(/scrollbar-color/)
+  })
+
+  /**
+   * `overflow: auto` is what makes the bar conditional on real overflow. Under
+   * `overflow: scroll` every narrow table in the fleet would grow a dead 10px
+   * bar — a regression, not a fix.
+   */
+  it('leaves the scroller on overflow:auto so the bar is conditional on real overflow', () => {
+    expect(TABLE_SCROLL_CSS).not.toMatch(/overflow\s*:\s*scroll/)
+  })
+})
+
+describe('Table', () => {
+  const renderTable = (props: Record<string, unknown> = {}) =>
+    render(
+      <Table {...props}>
+        <TableBody>
+          <TableRow>
+            <TableCell>cell</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    )
+
+  it('marks its scroll container so the scrollbar rules can find it', () => {
+    renderTable()
+    const table = screen.getByRole('table')
+    expect(table.parentElement).toHaveClass(TABLE_SCROLLER_CLASS)
+    expect(table.parentElement).toHaveClass('overflow-auto')
+  })
+
+  it('injects the stylesheet once, however many tables are on the page', () => {
+    render(
+      <>
+        <Table />
+        <Table />
+        <Table />
+      </>
+    )
+    expect(document.querySelectorAll(`#${TABLE_SCROLL_STYLE_ID}`)).toHaveLength(1)
+    expect(document.getElementById(TABLE_SCROLL_STYLE_ID)?.textContent).toBe(
+      TABLE_SCROLL_CSS
+    )
+  })
+
+  it('sends containerClassName to the scrolling box and className to the table', () => {
+    renderTable({ containerClassName: 'max-h-96', className: 'my-table' })
+    const table = screen.getByRole('table')
+    expect(table).toHaveClass('my-table')
+    expect(table.parentElement).toHaveClass('max-h-96')
+    expect(table).not.toHaveClass('max-h-96')
+  })
+})
+
+describe('useScrollEdges', () => {
+  /** jsdom has no layout, so geometry has to be stated outright. */
+  const harness = (clientWidth: number, scrollWidth: number, scrollLeft: number) => {
+    const scroller = document.createElement('div')
+    const table = document.createElement('table')
+    scroller.appendChild(table)
+    document.body.appendChild(scroller)
+    Object.defineProperty(scroller, 'clientWidth', { value: clientWidth, configurable: true })
+    Object.defineProperty(scroller, 'scrollWidth', { value: scrollWidth, configurable: true })
+    scroller.scrollLeft = scrollLeft
+    return { scroller, table }
+  }
+
+  const run = (clientWidth: number, scrollWidth: number, scrollLeft = 0) => {
+    const { scroller, table } = harness(clientWidth, scrollWidth, scrollLeft)
+    const { result } = renderHook(() => {
+      const ref = useRef<HTMLTableElement | null>(table)
+      return useScrollEdges(ref)
+    })
+    return { edges: result.current, scroller, result }
+  }
+
+  it('reports no edge at all when the table fits — a hint under a table that fits is the same defect as a bar under one', () => {
+    expect(run(846, 846).edges).toEqual({ left: false, right: false })
+  })
+
+  it('ignores a sub-pixel overhang rather than decorating a table that visually fits', () => {
+    expect(run(846, 847).edges).toEqual({ left: false, right: false })
+  })
+
+  it('reports the right edge when columns are unreached to the right', () => {
+    expect(run(846, 1014).edges).toEqual({ left: false, right: true })
+  })
+
+  it('reports the left edge once scrolled away from the start', () => {
+    expect(run(846, 1014, 84).edges).toEqual({ left: true, right: true })
+  })
+
+  it('drops the right edge at the end of the scroll range', () => {
+    expect(run(846, 1014, 168).edges).toEqual({ left: true, right: false })
+  })
+
+  it('re-reads geometry when the scroller is scrolled', () => {
+    const { scroller, result } = run(846, 1014)
+    expect(result.current).toEqual({ left: false, right: true })
+    act(() => {
+      scroller.scrollLeft = 168
+      scroller.dispatchEvent(new Event('scroll'))
+    })
+    expect(result.current).toEqual({ left: true, right: false })
+  })
+})

package/src/components/ui/table-scroll.ts

@@ -0,0 +1,157 @@
+'use client'
+
+import { useEffect, useState, type RefObject } from 'react'
+
+export const TABLE_SCROLL_STYLE_ID = 'ss-table-scroll-affordance'
+
+/** The element that actually scrolls: the wrapper `Table` puts around `<table>`. */
+export const TABLE_SCROLLER_CLASS = 'ss-table-scroller'
+/** A non-scrolling box around the scroller, so the edge hints can be pinned to it. */
+export const TABLE_SHELL_CLASS = 'ss-table-shell'
+export const TABLE_EDGE_CLASS = 'ss-table-edge'
+export const TABLE_EDGE_LEFT_CLASS = 'ss-table-edge-left'
+export const TABLE_EDGE_RIGHT_CLASS = 'ss-table-edge-right'
+
+/**
+ * Wide tables scroll, but on macOS nothing says so (startsim-5pq7h).
+ *
+ * A reviewer reported "there is no sliding bar so it makes it difficult to see
+ * all the columns". The container did scroll the whole time; macOS renders an
+ * OVERLAY scrollbar that occupies no layout height and is invisible at rest, so
+ * the affordance was missing, not the scrolling.
+ *
+ * MEASURED 2026-09-07, headed Google Chrome and headed WebKit on macOS, on a
+ * 400px box holding 900px of content (`offsetHeight - clientHeight`, borders
+ * subtracted):
+ *
+ *   no scrollbar CSS                                       0px   (overlay)
+ *   scrollbar-width: thin                                  0px
+ *   scrollbar-color: <thumb> <track>                       0px
+ *   ::-webkit-scrollbar { height: 10px }                  10px   <-- this one
+ *   ::-webkit-scrollbar + scrollbar-width/-color           0px   <-- see below
+ *   ::-webkit-scrollbar, content NARROWER than the box      0px   (no regression)
+ *
+ * TWO RESULTS THAT ARE EASY TO UNDO BY ACCIDENT:
+ *
+ * 1. DO NOT ADD `scrollbar-width` OR `scrollbar-color` HERE. Every snippet on
+ *    the web pairs them with the -webkit- rules "for Firefox". Measured: when
+ *    the standard properties are set at the same specificity, Chromium honours
+ *    them INSTEAD of the custom scrollbar and reverts the element to a
+ *    zero-height overlay bar — i.e. adding them silently deletes this fix.
+ *    Firefox on macOS gains nothing from them anyway (measured 0px with
+ *    `scrollbar-width: thin` applied and confirmed in the computed style), so
+ *    there is no Firefox branch to lose. Firefox users are served by the edge
+ *    hint below instead.
+ *
+ * 2. The bar costs layout height ONLY while the element overflows — that is
+ *    `overflow: auto`, not something this stylesheet decides — so it never
+ *    appears under a table that fits. Keep the scroller on `auto`, never
+ *    `scroll`, or every narrow table in the fleet grows a dead bar.
+ *
+ * On Windows/Linux this REPLACES the ~15px classic bar with a 10px one; it does
+ * not reserve a second gutter, so no platform guard is needed. Nothing here
+ * animates or transitions, so `prefers-reduced-motion` has nothing to honour.
+ */
+export const TABLE_SCROLL_CSS = `
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar {
+  height: 10px;
+  width: 10px;
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-track {
+  background: transparent;
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb {
+  border-radius: 9999px;
+  background-color: color-mix(in srgb, currentColor 22%, transparent);
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb:hover {
+  background-color: color-mix(in srgb, currentColor 45%, transparent);
+}
+.${TABLE_SHELL_CLASS} {
+  position: relative;
+}
+.${TABLE_EDGE_CLASS} {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 24px;
+  pointer-events: none;
+}
+.${TABLE_EDGE_RIGHT_CLASS} {
+  right: 0;
+  background-image: linear-gradient(to left, hsl(var(--background)), hsl(var(--background) / 0));
+}
+.${TABLE_EDGE_LEFT_CLASS} {
+  left: 0;
+  background-image: linear-gradient(to right, hsl(var(--background)), hsl(var(--background) / 0));
+}
+`.trim()
+
+export interface ScrollEdges {
+  /** There is content scrolled off to the left. */
+  left: boolean
+  /** There is content still unreached to the right. */
+  right: boolean
+}
+
+/**
+ * Which horizontal edges of a table's scroller still hide content.
+ *
+ * The persistent scrollbar above sits at the bottom of the scroller, and the
+ * scroller is the FULL HEIGHT of the table — measured 3061-5698px below the
+ * fold on every content view of the marketing-agents tenant at 900px tall. So a
+ * reader looking at the header row never sees it, and needs a hint that travels
+ * with them. This drives that hint.
+ *
+ * Pass a ref to the `<table>`, not to the scroller: `Table` forwards its ref to
+ * the table element, and the scroller is its parent.
+ */
+export function useScrollEdges(
+  tableRef: RefObject<HTMLTableElement | null>
+): ScrollEdges {
+  const [edges, setEdges] = useState<ScrollEdges>({ left: false, right: false })
+
+  useEffect(() => {
+    const table = tableRef.current
+    const scroller = table?.parentElement
+    if (!table || !scroller) return
+
+    const update = () => {
+      // 1px of slack: sub-pixel column widths leave scrollWidth a hair above
+      // clientWidth on tables that visually fit, and a hint under a table that
+      // fits is the same defect as a scrollbar under one.
+      const max = scroller.scrollWidth - scroller.clientWidth
+      const next: ScrollEdges = {
+        left: max > 1 && scroller.scrollLeft > 1,
+        right: max > 1 && scroller.scrollLeft < max - 1,
+      }
+      setEdges((prev) =>
+        prev.left === next.left && prev.right === next.right ? prev : next
+      )
+    }
+
+    update()
+    scroller.addEventListener('scroll', update, { passive: true })
+
+    let observer: ResizeObserver | undefined
+    if (typeof ResizeObserver !== 'undefined') {
+      // Observe the TABLE, not just the scroller. The scroller is `w-full`, so
+      // its own box does NOT change when a column is toggled, a filter narrows
+      // the data, or a page of rows re-sizes the auto-laid-out columns — only
+      // the table's box does. Watching the scroller alone misses every one of
+      // those and leaves the hint stale.
+      observer = new ResizeObserver(update)
+      observer.observe(table)
+      observer.observe(scroller)
+    }
+    window.addEventListener('resize', update)
+
+    return () => {
+      scroller.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+      observer?.disconnect()
+    }
+  }, [tableRef])
+
+  return edges
+}

package/src/components/ui/table.tsx

@@ -1,19 +1,49 @@
+'use client'
+
 import * as React from "react"
 
 import { cn } from "../../lib/utils"
+import { useInjectedStyle } from "../../lib/injected-style"
+import {
+  TABLE_SCROLLER_CLASS,
+  TABLE_SCROLL_CSS,
+  TABLE_SCROLL_STYLE_ID,
+} from "./table-scroll"
 
-const Table = React.forwardRef<
-  HTMLTableElement,
-  React.HTMLAttributes<HTMLTableElement>
->(({ className, ...props }, ref) => (
-  <div className="relative w-full overflow-auto">
-    <table
-      ref={ref}
-      className={cn("w-full caption-bottom text-sm", className)}
-      {...props}
-    />
-  </div>
-))
+export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
+  /**
+   * Classes for the scroll container that wraps the `<table>`. This div — not
+   * the `<table>` — is the element that actually scrolls horizontally, so
+   * anything that needs to change the scrolling box (a max-height, a different
+   * overflow) belongs here rather than in `className`.
+   */
+  containerClassName?: string
+}
+
+const Table = React.forwardRef<HTMLTableElement, TableProps>(
+  ({ className, containerClassName, ...props }, ref) => {
+    // Gives the scroller a scrollbar that is actually visible while it
+    // overflows. See table-scroll.ts for the measurements — in particular why
+    // `scrollbar-width` must NOT be added alongside it.
+    useInjectedStyle(TABLE_SCROLL_STYLE_ID, TABLE_SCROLL_CSS)
+
+    return (
+      <div
+        className={cn(
+          "relative w-full overflow-auto",
+          TABLE_SCROLLER_CLASS,
+          containerClassName
+        )}
+      >
+        <table
+          ref={ref}
+          className={cn("w-full caption-bottom text-sm", className)}
+          {...props}
+        />
+      </div>
+    )
+  }
+)
 Table.displayName = "Table"
 
 const TableHeader = React.forwardRef<

package/src/components/unified-table/UnifiedTable.tsx

@@ -11,6 +11,7 @@ import { TablePagination } from './components/TablePagination'
 import { StandardTableToolbar } from './components/Toolbar'
 import { Loader2 } from 'lucide-react'
 import { cn } from '../../utils'
+import { reconcileColumnVisibility, readStoredColumnVisibility, isForcedVisible } from './utils/columnVisibility'
 
 export function UnifiedTable<TData>({
   data,
@@ -56,31 +57,38 @@ export function UnifiedTable<TData>({
     return urlState.getURLState()
   }, []) // Only run once on mount
 
-  // Column visibility state
-  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() => {
-    // Try to load from localStorage if persistKey is set
-    if (columnVisibilityConfig?.persistKey && typeof window !== 'undefined') {
-      try {
-        const stored = localStorage.getItem(`table-columns-${columnVisibilityConfig.persistKey}`)
-        if (stored) {
-          return JSON.parse(stored)
-        }
-      } catch {
-        // Ignore localStorage errors
-      }
-    }
+  // Column visibility state.
+  //
+  // A stored map is never trusted verbatim: it is reconciled against the
+  // columns actually on screen, so an attribute declared AFTER the user last
+  // saved a choice takes `defaultVisible` instead of being pinned visible for
+  // that one browser (bd startsim-7r2ta). See utils/columnVisibility.ts for the
+  // three rules — absent takes the default, a stored `false` survives,
+  // `alwaysVisible` outranks both.
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() =>
+    reconcileColumnVisibility(
+      columns,
+      readStoredColumnVisibility(columnVisibilityConfig?.persistKey),
+      columnVisibilityConfig
+    )
+  )
 
-    // Initialize default visibility
-    const initial: ColumnVisibilityState = {}
-    columns.forEach(col => {
-      if (columnVisibilityConfig?.defaultVisible) {
-        initial[col.id] = columnVisibilityConfig.defaultVisible.includes(col.id)
-      } else {
-        initial[col.id] = true // Default all visible
-      }
-    })
-    return initial
-  })
+  // Callers that render before their schema lands (a runtime-declared entity
+  // type, a lazily loaded column set) hand us a short `columns` array for a
+  // render or two, so the reconciliation has to hold for the columns that
+  // arrive later as well. Reading through this memo rather than off state means
+  // a late column is never visible for a frame before being corrected.
+  const resolvedColumnVisibility = useMemo(
+    () => reconcileColumnVisibility(columns, columnVisibility, columnVisibilityConfig),
+    [columns, columnVisibility, columnVisibilityConfig]
+  )
+
+  useEffect(() => {
+    // Identity-stable when nothing changed, so this settles in one pass.
+    if (resolvedColumnVisibility !== columnVisibility) {
+      setColumnVisibility(resolvedColumnVisibility)
+    }
+  }, [resolvedColumnVisibility, columnVisibility])
 
   // Client-side sorting state (used when no external sorting config is provided)
   const [localSort, setLocalSort] = useState<SortState>(() => {
@@ -100,13 +108,13 @@ export function UnifiedTable<TData>({
       try {
         localStorage.setItem(
           `table-columns-${columnVisibilityConfig.persistKey}`,
-          JSON.stringify(columnVisibility)
+          JSON.stringify(resolvedColumnVisibility)
         )
       } catch {
         // Ignore localStorage errors
       }
     }
-  }, [columnVisibility, columnVisibilityConfig?.persistKey])
+  }, [resolvedColumnVisibility, columnVisibilityConfig?.persistKey])
 
   // Toggle column visibility
   const toggleColumnVisibility = useCallback((columnId: string) => {
@@ -114,9 +122,12 @@ export function UnifiedTable<TData>({
     if (columnVisibilityConfig?.alwaysVisible?.includes(columnId)) {
       return
     }
+    // Anything but an explicit `false` is on screen, so that's what a toggle
+    // has to turn off — `!prev[id]` would SHOW a column whose id the map has
+    // yet to learn, which is the very state this component used to render.
     setColumnVisibility(prev => ({
       ...prev,
-      [columnId]: !prev[columnId]
+      [columnId]: prev[columnId] === false
     }))
   }, [columnVisibilityConfig?.alwaysVisible])
 
@@ -125,8 +136,14 @@ export function UnifiedTable<TData>({
     if (!columnVisibilityConfig?.enabled) {
       return columns
     }
-    return columns.filter(col => columnVisibility[col.id] !== false)
-  }, [columns, columnVisibility, columnVisibilityConfig?.enabled])
+    return columns.filter(col =>
+      // "Cannot be hidden" is a promise to the caller, not a default: a stored
+      // map written before the column joined that list must not be able to
+      // drop it, and the picker won't offer it back.
+      isForcedVisible(col, columnVisibilityConfig.alwaysVisible) ||
+      resolvedColumnVisibility[col.id] !== false
+    )
+  }, [columns, resolvedColumnVisibility, columnVisibilityConfig?.enabled, columnVisibilityConfig?.alwaysVisible])
 
   // Get hideable columns for the dropdown
   const hideableColumns = useMemo(() => {
@@ -263,7 +280,7 @@ export function UnifiedTable<TData>({
   // Get current view state for saving
   const getCurrentViewState = useCallback((): Omit<SavedView, 'id' | 'name' | 'createdAt'> => {
     return {
-      columnVisibility: columnVisibilityConfig?.enabled ? columnVisibility : undefined,
+      columnVisibility: columnVisibilityConfig?.enabled ? resolvedColumnVisibility : undefined,
       columnOrder: columnReorderConfig?.enabled ? columnReorder.columnOrder : undefined,
       sortBy: currentSortBy,
       sortDirection: currentSortDirection,
@@ -271,7 +288,7 @@ export function UnifiedTable<TData>({
       pageSize: paginationConfig?.pageSize,
     }
   }, [
-    columnVisibility,
+    resolvedColumnVisibility,
     columnVisibilityConfig?.enabled,
     columnReorder.columnOrder,
     columnReorderConfig?.enabled,
@@ -450,7 +467,7 @@ export function UnifiedTable<TData>({
         searchDebounceMs={searchConfig?.debounceMs}
         columnVisibilityEnabled={columnVisibilityConfig?.enabled}
         hideableColumns={hideableColumns}
-        columnVisibility={columnVisibility}
+        columnVisibility={resolvedColumnVisibility}
         onToggleColumnVisibility={toggleColumnVisibility}
         exportEnabled={exportConfig?.enabled}
         exportData={sortedData}

package/src/components/unified-table/__tests__/components/DataTableCore.scroll-affordance.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * DataTableCore's edge hints (startsim-5pq7h).
+ *
+ * The persistent scrollbar restored on the `Table` primitive sits at the bottom
+ * of the scroller, and the scroller is as tall as the whole table — measured
+ * 3061-5698px BELOW THE FOLD on every content view of the marketing-agents
+ * tenant at a 900px-tall window. A reader at the header row never sees it, so
+ * the table also fades whichever edge still hides content.
+ *
+ * jsdom has no layout, so the geometry is stated outright below. These tests
+ * guard the WIRING and the "nothing overflows -> no decoration" contract; the
+ * visual claim is carried by browser measurement, not by them.
+ */
+import { render, screen } from '@testing-library/react'
+import { DataTableCore } from '../../components/DataTableCore'
+import { ColumnConfig } from '../../types'
+import { TABLE_EDGE_CLASS, TABLE_SHELL_CLASS } from '../../../ui/table-scroll'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const data: Row[] = [
+  { id: '1', name: 'Abu Dhabi Off-Plan Mortgage Guide' },
+  { id: '2', name: 'UAE Capital Markets Fee Changes' },
+]
+
+const columns: ColumnConfig<Row>[] = [
+  { id: 'name', header: 'Name', accessorKey: 'name' },
+]
+
+/** Force the scroll container's geometry, which jsdom otherwise reports as 0/0. */
+function stubGeometry(clientWidth: number, scrollWidth: number) {
+  const original = {
+    clientWidth: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth'),
+    scrollWidth: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'scrollWidth'),
+  }
+  Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+    configurable: true,
+    get() {
+      return this.tagName === 'DIV' ? clientWidth : 0
+    },
+  })
+  Object.defineProperty(HTMLElement.prototype, 'scrollWidth', {
+    configurable: true,
+    get() {
+      return this.tagName === 'DIV' ? scrollWidth : 0
+    },
+  })
+  return () => {
+    if (original.clientWidth) Object.defineProperty(HTMLElement.prototype, 'clientWidth', original.clientWidth)
+    if (original.scrollWidth) Object.defineProperty(HTMLElement.prototype, 'scrollWidth', original.scrollWidth)
+  }
+}
+
+const edges = (container: HTMLElement) =>
+  container.querySelectorAll(`.${TABLE_EDGE_CLASS}`)
+
+describe('DataTableCore horizontal-scroll affordance', () => {
+  let restore: () => void = () => {}
+  afterEach(() => restore())
+
+  it('gives the table a non-scrolling shell for the hints to pin to', () => {
+    restore = stubGeometry(846, 846)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    const table = screen.getByRole('table')
+    // The shell is the OUTER box; the element that scrolls is Table's own
+    // wrapper inside it. Pinning the hints to the scroller would make them
+    // scroll away with the content.
+    expect(container.querySelector(`.${TABLE_SHELL_CLASS}`)).toBe(
+      table.parentElement?.parentElement
+    )
+  })
+
+  it('renders no edge hint at all when every column fits', () => {
+    restore = stubGeometry(846, 846)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    expect(edges(container)).toHaveLength(0)
+  })
+
+  it('fades the right edge when columns are unreached to the right', () => {
+    // /t/topic at a 1152px window: 846 visible, 1014 needed.
+    restore = stubGeometry(846, 1014)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    const found = edges(container)
+    expect(found).toHaveLength(1)
+    expect(found[0]).toHaveClass('ss-table-edge-right')
+    // Decoration only — it must never intercept a click meant for the cell or
+    // the row-action menu underneath.
+    expect(found[0]).toHaveAttribute('aria-hidden', 'true')
+  })
+})

package/src/components/unified-table/__tests__/integration/column-visibility-persistence.test.tsx

@@ -0,0 +1,234 @@
+/**
+ * A saved column map must not force-show columns declared after it (bd startsim-7r2ta).
+ *
+ * UnifiedTable seeds `columnVisibility` from localStorage and then keeps a
+ * column whose id is missing from that map, because the filter asks
+ * `map[id] !== false` and `undefined !== false`. On a runtime-declared schema —
+ * every foundry tenant — that means every attribute added AFTER a reviewer last
+ * touched the column picker is pinned visible for that reviewer alone, and
+ * invisible to anyone checking in a clean browser.
+ *
+ * The reconciliation has to thread three needles at once:
+ *   1. an id ABSENT from the stored map falls back to `defaultVisible`,
+ *   2. a stored `false` is a deliberate hide and survives,
+ *   3. `alwaysVisible` outranks both.
+ */
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { useState } from 'react'
+import { UnifiedTable } from '../../index'
+import { ColumnConfig } from '../../types'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const rows: Row[] = [{ id: '1', name: 'Alpha' }]
+
+const NAME: ColumnConfig<Row> = { id: 'name', header: 'Name', accessorKey: 'name' }
+const STATUS: ColumnConfig<Row> = { id: 'status', header: 'Status', accessorKey: 'status' }
+const SCOPE: ColumnConfig<Row> = { id: 'scope_path', header: 'Scope path', accessorKey: 'scope_path' }
+const ACTIONS: ColumnConfig<Row> = { id: '__actions', header: 'Actions' }
+
+const PERSIST_KEY = 'records-topic'
+const STORAGE_KEY = `table-columns-${PERSIST_KEY}`
+
+function seedStoredMap(map: Record<string, boolean>) {
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(map))
+}
+
+function readStoredMap(): Record<string, boolean> {
+  return JSON.parse(window.localStorage.getItem(STORAGE_KEY) ?? '{}')
+}
+
+/** Only the headers of the rendered grid — the column picker lists them too. */
+function headers(): string[] {
+  return within(screen.getByRole('table'))
+    .getAllByRole('columnheader')
+    .map((th) => th.textContent?.trim() ?? '')
+}
+
+beforeEach(() => {
+  window.localStorage.clear()
+})
+
+describe('a stored column map is reconciled against the current columns', () => {
+  it('hides a column the stored map never heard of when defaults exclude it', () => {
+    // The reviewer saved a choice back when the type had name + status. Since
+    // then the schema grew a scope_path attribute, which the app does NOT
+    // default on.
+    seedStoredMap({ name: true, status: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('still shows an unheard-of column when the caller defaults everything on', () => {
+    // No defaultVisible => "all visible" is the documented default, so an
+    // absent id must stay visible. The fix must not turn absence into a hide.
+    seedStoredMap({ name: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{ enabled: true, persistKey: PERSIST_KEY }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+
+  it('keeps a deliberate hide the user saved', () => {
+    // status is in defaultVisible, but the stored map says false. Persistence
+    // exists precisely so that choice outlives the default.
+    seedStoredMap({ name: true, status: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name'])
+  })
+
+  it('overrides a stored hide of an always-visible column', () => {
+    // The caller added __actions to alwaysVisible after this user had hidden
+    // it (or the column was renamed into the always-visible set). An
+    // always-visible column that the table drops takes the row actions with it.
+    seedStoredMap({ name: false, status: true, __actions: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('shows an always-visible column that defaultVisible forgot', () => {
+    // Nothing stored at all: the seed path must not let a defaultVisible list
+    // that omits an always-visible id hide it.
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('keeps a hideable:false column that the defaults leave out', () => {
+    // `hideable: false` is already excluded from the column picker, so a
+    // reconciliation that hid one would strand it: off the table and off the
+    // menu that puts it back.
+    const pinned: ColumnConfig<Row> = { ...SCOPE, hideable: false }
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, pinned]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+})
+
+describe('columns that arrive after mount', () => {
+  function LateSchema() {
+    const [cols, setCols] = useState<ColumnConfig<Row>[]>([NAME])
+    return (
+      <>
+        <button onClick={() => setCols([NAME, STATUS, SCOPE])}>load schema</button>
+        <UnifiedTable<Row>
+          data={rows}
+          columns={cols}
+          tableId="records"
+          getRowId={(r) => r.id}
+          columnVisibility={{
+            enabled: true,
+            alwaysVisible: ['name'],
+            defaultVisible: ['name', 'status'],
+            persistKey: PERSIST_KEY,
+          }}
+        />
+      </>
+    )
+  }
+
+  it('reconciles a column the table had not been handed at mount', () => {
+    seedStoredMap({ name: true, status: true })
+    render(<LateSchema />)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('does not wipe a saved hide for a column that has not arrived yet', () => {
+    // Reconciling by rebuilding the map from `columns` alone would drop
+    // status:false while the schema is still in flight, and the persist effect
+    // would write that loss straight back to localStorage.
+    seedStoredMap({ name: true, status: false })
+    render(<LateSchema />)
+
+    expect(readStoredMap().status).toBe(false)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(readStoredMap().status).toBe(false)
+    expect(headers()).toEqual(['Name'])
+  })
+})

package/src/components/unified-table/__tests__/utils/column-visibility.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit cover for the reconciliation UnifiedTable applies to a stored column
+ * map (bd startsim-7r2ta). The integration test pins the rendered result; this
+ * pins the rules themselves, including the cases a rendered table can't easily
+ * show — an id the current schema no longer declares, a corrupt stored value.
+ */
+import { reconcileColumnVisibility } from '../../utils/columnVisibility'
+
+const cols = [{ id: 'name' }, { id: 'status' }, { id: 'scope_path' }]
+
+describe('reconcileColumnVisibility', () => {
+  it('falls an unknown id back to defaultVisible, not to visible', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true, status: true }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: true, scope_path: false })
+  })
+
+  it('treats "no defaultVisible" as all-visible for unknown ids', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true }, { enabled: true })
+    ).toEqual({ name: true, status: true, scope_path: true })
+  })
+
+  it('preserves a stored false even when the defaults say otherwise', () => {
+    expect(
+      reconcileColumnVisibility(cols, { status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status', 'scope_path'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+
+  it('forces an always-visible column on over a stored hide', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: false, status: false }, {
+        enabled: true,
+        alwaysVisible: ['name'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('forces an always-visible column on when defaultVisible omits it', () => {
+    expect(
+      reconcileColumnVisibility([...cols, { id: '__actions' }], null, {
+        enabled: true,
+        alwaysVisible: ['__actions'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false, __actions: true })
+  })
+
+  it('keeps a stored choice for a column the current schema has not declared', () => {
+    // Mid-flight schemas hand the table a short `columns` array. Rebuilding the
+    // map from `columns` alone would drop the hide, and the persist effect
+    // would write that loss back to localStorage.
+    expect(
+      reconcileColumnVisibility([{ id: 'name' }], { name: true, status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: false })
+  })
+
+  it('ignores non-boolean values in a corrupt stored map', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: 'yes', status: null } as never, {
+        enabled: true,
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('returns the same object when nothing needs reconciling', () => {
+    // The mount-time seed feeds this straight into setState on every columns
+    // change; a fresh object every time would loop.
+    const stored = { name: true, status: false, scope_path: false }
+    expect(
+      reconcileColumnVisibility(cols, stored, { enabled: true, defaultVisible: ['name'] })
+    ).toBe(stored)
+  })
+
+  it('forces a hideable:false column on, since the picker will not offer it back', () => {
+    // Same promise as alwaysVisible, and the one the caller is likelier to get
+    // wrong: hiding such a column leaves the user no way to restore it.
+    expect(
+      reconcileColumnVisibility(
+        [{ id: 'name' }, { id: 'status' }, { id: 'scope_path', hideable: false }],
+        { name: true, scope_path: false },
+        { enabled: true, defaultVisible: ['name'] }
+      )
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+})

package/src/components/unified-table/components/DataTableCore/index.tsx

@@ -1,7 +1,14 @@
 'use client'
 
-import { ReactNode, useState, useCallback } from 'react'
+import { ReactNode, useState, useCallback, useRef } from 'react'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../../ui/table'
+import {
+  useScrollEdges,
+  TABLE_SHELL_CLASS,
+  TABLE_EDGE_CLASS,
+  TABLE_EDGE_LEFT_CLASS,
+  TABLE_EDGE_RIGHT_CLASS,
+} from '../../../ui/table-scroll'
 import { Checkbox } from '../../../ui/checkbox'
 import { Button } from '../../../ui/button'
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger } from '../../../ui/dropdown-menu'
@@ -91,6 +98,14 @@ export function DataTableCore<TData>({
   // State for tracking if a column is being dragged (to disable sorting during drag)
   const [isDraggingColumn, setIsDraggingColumn] = useState(false)
 
+  // The scrollbar restored in `Table` sits at the bottom of the scroller, and
+  // the scroller is as tall as the whole table — thousands of pixels below the
+  // fold on a full page of rows. These flags drive a fade at whichever edge
+  // still hides content, so the reader is told at the header row, not only at
+  // the very bottom of the page (startsim-5pq7h).
+  const tableRef = useRef<HTMLTableElement>(null)
+  const scrollEdges = useScrollEdges(tableRef)
+
   // Drag handlers
   const handleDragStart = useCallback((_: DragStart) => {
     setIsDraggingColumn(true)
@@ -334,8 +349,13 @@ export function DataTableCore<TData>({
   return (
     // overflow-x-auto: a wide table scrolls horizontally inside its own border
     // instead of overflowing the page to the right (startsim column-overflow).
-    <div className={cn('rounded-md border border-border overflow-x-auto', className)}>
-      <Table>
+    // NOTE: this div is not the element that ends up scrolling — `Table`'s own
+    // `overflow-auto` wrapper inside it is, because that wrapper is `w-full`
+    // and so never makes this one overflow. That is why the scrollbar styling
+    // and the ref below both target the inner wrapper. This div stays as the
+    // non-scrolling shell the edge hints are pinned to.
+    <div className={cn('rounded-md border border-border overflow-x-auto', TABLE_SHELL_CLASS, className)}>
+      <Table ref={tableRef}>
         {renderColumnHeaders()}
 
         <TableBody>
@@ -474,6 +494,17 @@ export function DataTableCore<TData>({
           )}
         </TableBody>
       </Table>
+
+      {/* Edge hints. Rendered only while that side actually hides something, so
+          a table that fits gets no decoration at all. `pointer-events: none`
+          keeps the rightmost column's cells and the row-action menu clickable
+          underneath. */}
+      {scrollEdges.left && (
+        <div aria-hidden="true" className={cn(TABLE_EDGE_CLASS, TABLE_EDGE_LEFT_CLASS)} />
+      )}
+      {scrollEdges.right && (
+        <div aria-hidden="true" className={cn(TABLE_EDGE_CLASS, TABLE_EDGE_RIGHT_CLASS)} />
+      )}
     </div>
   )
 }

package/src/components/unified-table/utils/columnVisibility.ts

@@ -0,0 +1,105 @@
+import { ColumnVisibilityConfig, ColumnVisibilityState } from '../types'
+
+/** The two fields of a column this reconciliation reads. */
+export interface ReconcilableColumn {
+  id: string
+  /** `false` is the same promise as listing the id in `alwaysVisible`. */
+  hideable?: boolean
+}
+
+/**
+ * Column visibility persists as a map of column id -> boolean, and the table
+ * treats a MISSING id as visible (`map[id] !== false`). That is the right
+ * reading for a fresh browser, and the wrong one for a stored map: a schema
+ * declared at runtime — every foundry tenant — grows attributes after a
+ * reviewer last saved a column choice, and each new one lands outside the
+ * stored map and is therefore pinned on for that reviewer alone, invisible to
+ * anyone checking in a clean session. Bumping the persist key clears it once
+ * and the next attribute brings it back (bd startsim-7r2ta).
+ *
+ * So a stored map is reconciled against the columns actually on screen:
+ *
+ *   - an id the stored map has never heard of takes `defaultVisible`
+ *     (or stays visible when the caller declared no defaults at all),
+ *   - a stored `false` is a deliberate hide and is left alone — that is the
+ *     entire point of persisting,
+ *   - `alwaysVisible` outranks both, so neither a stale stored `false` nor a
+ *     `defaultVisible` list that forgot the id can drop the name column or the
+ *     row-actions column. `hideable: false` carries the same promise and is
+ *     forced the same way: the column picker already refuses to list such a
+ *     column, so hiding one would leave the user no way to bring it back.
+ *
+ * Ids the current `columns` no longer declare are carried through untouched.
+ * A caller that renders before its schema arrives hands us a short column list
+ * for a render or two, and rebuilding the map from `columns` alone would erase
+ * the user's saved hides in that window — and the persist effect would then
+ * write the loss back to localStorage.
+ *
+ * Returns the `stored` object itself when nothing needed changing, so callers
+ * can feed the result straight back into `setState` without looping.
+ */
+export function reconcileColumnVisibility(
+  columns: ReconcilableColumn[],
+  stored: ColumnVisibilityState | null | undefined,
+  config?: ColumnVisibilityConfig
+): ColumnVisibilityState {
+  const { defaultVisible, alwaysVisible } = config ?? {}
+
+  const next: ColumnVisibilityState = {}
+  let changed = false
+
+  // Carry the stored choices forward. A non-boolean is a corrupt entry (hand-
+  // edited storage, an older shape) and is treated as absent.
+  for (const [id, value] of Object.entries(stored ?? {})) {
+    if (typeof value === 'boolean') next[id] = value
+    else changed = true
+  }
+
+  for (const col of columns) {
+    const id = col.id
+    const desired = isForcedVisible(col, alwaysVisible)
+      ? true
+      : id in next
+        ? next[id]
+        : defaultVisible
+          ? defaultVisible.includes(id)
+          : true
+    if (next[id] !== desired) {
+      next[id] = desired
+      changed = true
+    }
+  }
+
+  return stored && !changed ? stored : next
+}
+
+/**
+ * A column the user is not allowed to hide — which therefore must not end up
+ * hidden by a stale stored map or by a `defaultVisible` list that omits it.
+ */
+export function isForcedVisible(
+  column: ReconcilableColumn,
+  alwaysVisible: string[] | undefined
+): boolean {
+  return column.hideable === false || !!alwaysVisible?.includes(column.id)
+}
+
+/**
+ * The persisted half of the above: read the map UnifiedTable wrote for
+ * `persistKey`, tolerating a browser that has no localStorage (SSR, privacy
+ * mode) and a value that no longer parses.
+ */
+export function readStoredColumnVisibility(
+  persistKey: string | undefined
+): ColumnVisibilityState | null {
+  if (!persistKey || typeof window === 'undefined') return null
+  try {
+    const stored = window.localStorage.getItem(`table-columns-${persistKey}`)
+    if (!stored) return null
+    const parsed = JSON.parse(stored)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed as ColumnVisibilityState
+  } catch {
+    return null
+  }
+}

package/src/components/unified-table/utils/index.ts

@@ -2,3 +2,4 @@ export * from './renderers'
 export * from './themes'
 export * from './validation'
 export * from './export'
+export * from './columnVisibility'

package/src/lib/injected-style.ts

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+
+/**
+ * Append a stylesheet to <head> exactly once per document, keyed by `id`.
+ *
+ * WHY THIS EXISTS instead of a .css file or Tailwind classes (startsim-5pq7h):
+ *
+ *  - @startsimpli/ui ships SOURCE (`main: ./src/index.ts`), and each consuming
+ *    app decides for itself whether Tailwind scans it. Four of the eleven apps
+ *    — crochet, recipe, workflows and raise — have no
+ *    `@source ".../@startsimpli/ui/src/**"` line in their globals.css, so a
+ *    Tailwind class written in this package emits no rule at all over there.
+ *  - The subpath CSS exports (`./gantt/styles`, `./workflows/styles`) only take
+ *    effect once the app adds an `@import`, which is a change in eleven repos.
+ *  - Pseudo-element rules (`::-webkit-scrollbar`) cannot be expressed as an
+ *    inline `style` prop.
+ *
+ * Injecting from the component is the only delivery that reaches every place
+ * the component actually renders.
+ */
+export function ensureInjectedStyle(id: string, css: string): void {
+  if (typeof document === 'undefined') return
+
+  const existing = document.getElementById(id)
+  if (existing) {
+    if (existing.textContent !== css) existing.textContent = css
+    return
+  }
+
+  const el = document.createElement('style')
+  el.id = id
+  el.textContent = css
+  document.head.appendChild(el)
+}
+
+/** React wrapper for {@link ensureInjectedStyle}. Safe to call from every instance. */
+export function useInjectedStyle(id: string, css: string): void {
+  useEffect(() => {
+    ensureInjectedStyle(id, css)
+  }, [id, css])
+}