@startsimpli/ui 0.4.120 → 0.4.122

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

@@ -69,6 +69,58 @@ describe('TABLE_SCROLL_CSS', () => {
    * shape here; the visible-shading claim itself is carried by the pixel diff
    * in examples/workflow-studio/scripts/measure-scrollers.mjs (delta 3 -> 35).
    */
+  /**
+   * startsim-xe1uo.1, and the single rule the whole fix turns on.
+   *
+   * The shell used to get its clipping from a Tailwind `overflow-x-auto` in
+   * DataTableCore, which made it a SCROLL CONTAINER — and `position: sticky`
+   * resolves against the nearest scroll container, so the rail was pinned to
+   * the bottom of the table, i.e. precisely where the unreachable bar already
+   * was. MEASURED in Chromium, a 1600px table in a 400px flex line scrolled so
+   * the shell ends 1.4k px below the fold:
+   *
+   *   auto                -> rail bottom 2022 (off screen), shell 400px wide
+   *   hidden              -> rail bottom 2022 (off screen)
+   *   clip                -> rail bottom  614 (stuck), shell 1602px  <-- blown out
+   *   clip + min-width:0  -> rail bottom  614 (stuck), shell  400px  <-- both
+   *
+   * `min-width: auto` collapses to zero only for a SCROLL CONTAINER, and a clip
+   * container is not one, so `clip` on its own stops the shell shrinking and
+   * pushes its flex parent wide. Both declarations are load-bearing and they
+   * fail in opposite directions — hence a guard on each.
+   */
+  it('clips the shell without making it a scroll container, and keeps it shrinkable', () => {
+    const shellRule = TABLE_SCROLL_CSS.slice(
+      TABLE_SCROLL_CSS.indexOf('.ss-table-shell'),
+      TABLE_SCROLL_CSS.indexOf('.ss-table-edge {')
+    )
+    expect(shellRule).toMatch(/overflow-x:\s*clip/)
+    expect(shellRule).toMatch(/min-width:\s*0/)
+    // `hidden` is the pre-`clip` fallback and must stay BEHIND `clip`, or every
+    // modern engine gets a scroll container again and the rail stops sticking.
+    expect(shellRule.indexOf('overflow-x: clip')).toBeGreaterThan(
+      shellRule.indexOf('overflow-x: hidden')
+    )
+    expect(shellRule).not.toMatch(/overflow-x:\s*auto/)
+  })
+
+  /**
+   * The rail is a SECOND horizontal scrollbar, pinned to the bottom of the
+   * viewport while the table's own one is off screen — measured 2,741-5,994px
+   * below the truncated header on the live tenant. Without `sticky`/`bottom` it
+   * is just another bar at the bottom of the table and buys nothing.
+   */
+  it('pins the rail to the bottom of the viewport', () => {
+    const railRule = TABLE_SCROLL_CSS.slice(TABLE_SCROLL_CSS.indexOf('.ss-table-rail {'))
+    expect(railRule).toMatch(/position:\s*sticky/)
+    expect(railRule).toMatch(/bottom:\s*0/)
+    expect(railRule).toMatch(/overflow-x:\s*auto/)
+  })
+
+  it('gives the rail the same custom scrollbar as the scroller it stands in for', () => {
+    expect(TABLE_SCROLL_CSS).toContain('.ss-table-rail::-webkit-scrollbar')
+  })
+
   it('shades the edge hint instead of trying to match an unknowable background', () => {
     const edgeRules = TABLE_SCROLL_CSS.slice(TABLE_SCROLL_CSS.indexOf('.ss-table-edge-right'))
     expect(edgeRules).toMatch(/linear-gradient/)

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

@@ -1,6 +1,6 @@
 'use client'
 
-import { useEffect, useState, type RefObject } from 'react'
+import { useEffect, useRef, useState, type RefObject } from 'react'
 
 /**
  * The table's share of the scroll affordance (startsim-5pq7h).
@@ -20,6 +20,8 @@ export {
   TABLE_EDGE_CLASS,
   TABLE_EDGE_LEFT_CLASS,
   TABLE_EDGE_RIGHT_CLASS,
+  TABLE_RAIL_CLASS,
+  TABLE_RAIL_TRACK_CLASS,
   useScrollAffordance,
 } from '../../lib/scroll-affordance'
 
@@ -47,47 +49,226 @@ export function useScrollEdges(
 ): ScrollEdges {
   const [edges, setEdges] = useState<ScrollEdges>({ left: false, right: false })
 
+  useScrollerWatch(tableRef, (scroller) => {
+    // 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
+    )
+  })
+
+  return edges
+}
+
+/**
+ * Everything that can change a table's horizontal-scroll state, in one place.
+ *
+ * `useScrollEdges` and {@link useScrollRail} both need exactly this set, and
+ * both are mounted on every DataTableCore — so they share one watcher rather
+ * than each attaching its own ResizeObserver to the same two nodes.
+ *
+ * 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
+ * affordance stale. `window` scroll is in the set because the rail's whole
+ * question — is the real scrollbar off screen? — is answered by where the page
+ * is, and nothing else fires when that changes.
+ */
+function useScrollerWatch(
+  tableRef: RefObject<HTMLTableElement | null>,
+  onUpdate: (scroller: HTMLElement) => void
+): void {
+  // The callback is re-created on every render; keeping it in a ref stops the
+  // effect from tearing every listener down and rebuilding it each time.
+  const latest = useRef(onUpdate)
+  latest.current = onUpdate
+
   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
-      )
-    }
+    const update = () => latest.current(scroller)
 
     update()
     scroller.addEventListener('scroll', update, { passive: true })
+    window.addEventListener('scroll', update, { passive: true })
+    window.addEventListener('resize', update)
 
     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('scroll', update)
       window.removeEventListener('resize', update)
       observer?.disconnect()
     }
   }, [tableRef])
+}
 
-  return edges
+export interface ScrollRail {
+  /**
+   * Put this on the rail element. It is only rendered while {@link active}, so
+   * the ref is null the rest of the time and the sync effect no-ops.
+   */
+  railRef: RefObject<HTMLDivElement | null>
+  /**
+   * Render the rail: columns ARE hidden and the table's own scrollbar is NOT on
+   * screen. False on both counts is the overwhelmingly common case, and it puts
+   * nothing in the DOM at all.
+   */
+  active: boolean
+  /**
+   * Width for the rail's strut — the table's full `scrollWidth`, so the rail
+   * overflows by exactly as much as the scroller does and its thumb is the same
+   * size and travels the same distance.
+   */
+  contentWidth: number
+}
+
+/**
+ * How far below the fold the shell has to end before a rail is worth having.
+ *
+ * Two numbers, not one, so the rail does not mount and unmount on every wheel
+ * notch while the table's bottom edge hovers around the fold: it appears once
+ * there is more than a bar's worth of table below the viewport, and stays until
+ * the bottom is genuinely on screen.
+ */
+const RAIL_ON = 24
+const RAIL_OFF = 0
+
+/** Below this, a scrollLeft difference is sub-pixel rounding, not a scroll. */
+const SCROLL_EPSILON = 1
+
+/**
+ * A horizontal scrollbar for the table that is where the reader is looking.
+ *
+ * THE PROBLEM IT SOLVES, and it is not the one startsim-5pq7h solved. That fix
+ * made the scroller's bar visible, and it works. But the scroller is the full
+ * height of the table — 3,046px on /t/draft, 6,377px on /t/topic — so a bar at
+ * its bottom padding edge renders at the bottom of the DOCUMENT: measured
+ * 2,741-5,994px below the truncated header on the live marketing-agents tenant
+ * (startsim-xe1uo). At the moment a reader can SEE that columns are cut off,
+ * there is no scrollbar anywhere on screen.
+ *
+ * That is survivable on macOS, where a trackpad swipes horizontally anywhere
+ * over the table, and it is why nobody on this team ever hit it. A Windows
+ * wheel mouse has no horizontal axis at all, so its owner is left with
+ * Shift+Wheel (undiscoverable) or dragging a bar three screens down. The edge
+ * hint added by 5pq7h — and made visible by startsim-xe1uo — says "there is
+ * more to the right"; it does not let anyone GO there.
+ *
+ * So: a second scrollbar, `position: sticky; bottom: 0`, which floats at the
+ * bottom of the viewport for as long as the table's own bar is off screen and
+ * settles into place when it is not. It is a real scrollbar, not a proxy
+ * widget: an `overflow-x: auto` box holding a strut as wide as the table, so
+ * the platform draws and drags it, and its thumb is the same size and travels
+ * the same distance as the real one.
+ *
+ * WHY IT IS NOT A max-height ON THE SCROLLER, which is how a data grid usually
+ * does this. `Table` already takes `containerClassName` for exactly that, and
+ * the existing tests pass `max-h-96` through it — so bounding the body is
+ * already available to any consumer that wants it. Making it the DEFAULT needs
+ * a viewport-relative height, and a shared primitive cannot know one: the same
+ * table renders inside a card, a dialog, a split pane and a full page across
+ * the fleet, and a `max-height` that is right for one is wrong for the rest.
+ * It would also convert page scrolling to nested scrolling for every table in
+ * eleven apps to fix a bar position. The rail changes no scrolling behaviour at
+ * all.
+ *
+ * SAFE BY DEFAULT, and that is a measurable claim rather than a hope: `active`
+ * requires BOTH horizontal overflow AND the shell's bottom below the fold, so
+ * on a table that fits, or a table short enough to see the end of, the rail is
+ * not in the DOM. `/scrollers` carries `neg-` cases for both and
+ * `scripts/measure-scrollers.mjs` fails the run if either grows one.
+ *
+ * Pass the ref to the `<table>`, as with {@link useScrollEdges} — the scroller
+ * is its parent and the shell is the scroller's parent, so nothing may be
+ * inserted between them.
+ */
+export function useScrollRail(
+  tableRef: RefObject<HTMLTableElement | null>,
+  enabled = true
+): ScrollRail {
+  const railRef = useRef<HTMLDivElement>(null)
+  const [state, setState] = useState<{ active: boolean; contentWidth: number }>({
+    active: false,
+    contentWidth: 0,
+  })
+
+  useScrollerWatch(tableRef, (scroller) => {
+    const shell = scroller.parentElement
+    if (!shell) return
+    // Same 1px of slack as the edge hints: sub-pixel column widths leave
+    // scrollWidth a hair above clientWidth on tables that visually fit.
+    const hidesColumns = scroller.scrollWidth - scroller.clientWidth > 1
+    const box = shell.getBoundingClientRect()
+    const fold = window.innerHeight
+    // BOTH ENDS MATTER, and only measuring the bottom is the mistake worth
+    // recording: a table that has not been reached yet also has its bottom
+    // below the fold, so "bottom is off screen" alone mounts a rail on every
+    // table further down the page — including short ones that need nothing.
+    // Caught by the rail-short case on /scrollers, which grew a rail while it
+    // was still 4,000px below the viewport.
+    const onScreen = box.top < fold
+    const barBelowFold = box.bottom - fold
+    setState((prev) => {
+      const active =
+        enabled &&
+        hidesColumns &&
+        onScreen &&
+        // Hysteresis: a higher bar to appear than to stay, so the rail does not
+        // flicker on every wheel notch while the table's bottom edge crosses.
+        barBelowFold > (prev.active ? RAIL_OFF : RAIL_ON)
+      const contentWidth = active ? scroller.scrollWidth : 0
+      return prev.active === active && prev.contentWidth === contentWidth
+        ? prev
+        : { active, contentWidth }
+    })
+  })
+
+  // Two-way scrollLeft sync. Deliberately NOT guarded by a re-entrancy flag:
+  // scroll events fire asynchronously, so a flag set around the assignment is
+  // already cleared by the time the event it caused arrives. Comparing the two
+  // values instead is self-terminating — the second handler finds them equal
+  // and does nothing.
+  useEffect(() => {
+    const rail = railRef.current
+    const scroller = tableRef.current?.parentElement
+    if (!rail || !scroller) return
+
+    rail.scrollLeft = scroller.scrollLeft
+
+    const fromRail = () => {
+      if (Math.abs(scroller.scrollLeft - rail.scrollLeft) > SCROLL_EPSILON) {
+        scroller.scrollLeft = rail.scrollLeft
+      }
+    }
+    const fromScroller = () => {
+      if (Math.abs(rail.scrollLeft - scroller.scrollLeft) > SCROLL_EPSILON) {
+        rail.scrollLeft = scroller.scrollLeft
+      }
+    }
+
+    rail.addEventListener('scroll', fromRail, { passive: true })
+    scroller.addEventListener('scroll', fromScroller, { passive: true })
+    return () => {
+      rail.removeEventListener('scroll', fromRail)
+      scroller.removeEventListener('scroll', fromScroller)
+    }
+  }, [tableRef, state.active, state.contentWidth])
+
+  return { railRef, active: state.active, contentWidth: state.contentWidth }
 }

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

@@ -38,6 +38,7 @@ export function UnifiedTable<TData>({
   loadingRows = new Set(),
   className,
   emptyState,
+  scrollRail,
   errorState,
 }: UnifiedTableProps<TData>) {
   const searchInputRef = useRef<HTMLInputElement | null>(null)
@@ -591,6 +592,7 @@ export function UnifiedTable<TData>({
         onRowClick={onRowClick}
         loadingRows={loadingRows}
         emptyState={emptyState}
+        scrollRail={scrollRail}
       />
 
       {/* Pagination */}

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

@@ -11,10 +11,15 @@
  * 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 { act, 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'
+import {
+  TABLE_EDGE_CLASS,
+  TABLE_RAIL_CLASS,
+  TABLE_RAIL_TRACK_CLASS,
+  TABLE_SHELL_CLASS,
+} from '../../../ui/table-scroll'
 
 interface Row {
   id: string
@@ -57,9 +62,32 @@ function stubGeometry(clientWidth: number, scrollWidth: number) {
 const edges = (container: HTMLElement) =>
   container.querySelectorAll(`.${TABLE_EDGE_CLASS}`)
 
+const rail = (container: HTMLElement) =>
+  container.querySelector<HTMLDivElement>(`.${TABLE_RAIL_CLASS}`)
+
+/**
+ * Where the shell's bottom edge is relative to the fold — the whole question
+ * the rail turns on, and the one thing jsdom cannot answer for itself.
+ * `bottom` above `window.innerHeight` (768 here) means the table's own
+ * scrollbar is off screen.
+ */
+function stubShellBox(top: number, bottom: number) {
+  const original = HTMLElement.prototype.getBoundingClientRect
+  HTMLElement.prototype.getBoundingClientRect = function () {
+    return { top, bottom, left: 0, right: 0, width: 0, height: bottom - top, x: 0, y: top, toJSON: () => ({}) } as DOMRect
+  }
+  return () => {
+    HTMLElement.prototype.getBoundingClientRect = original
+  }
+}
+
 describe('DataTableCore horizontal-scroll affordance', () => {
   let restore: () => void = () => {}
-  afterEach(() => restore())
+  let restoreBox: () => void = () => {}
+  afterEach(() => {
+    restore()
+    restoreBox()
+  })
 
   it('gives the table a non-scrolling shell for the hints to pin to', () => {
     restore = stubGeometry(846, 846)
@@ -97,3 +125,117 @@ describe('DataTableCore horizontal-scroll affordance', () => {
     expect(found[0]).toHaveAttribute('aria-hidden', 'true')
   })
 })
+
+/**
+ * The sticky rail (startsim-xe1uo.1).
+ *
+ * The edge hints above say columns are hidden. They do not let anyone reach
+ * them, and on a Windows wheel mouse — which has no horizontal axis — there was
+ * nothing else within 2,741-5,994px, because the scroller is as tall as the
+ * whole table and its bar renders at the bottom of the document.
+ *
+ * jsdom has no layout, so NOTHING here proves a bar is on screen; that claim is
+ * carried by examples/workflow-studio/scripts/measure-scrollers.mjs, which
+ * measures the rail's rect against the viewport, its bar's height against the
+ * platform's, and — the part geometry cannot see — that dragging it moves the
+ * table. What these guard is the gate (so the rail is absent whenever the
+ * defect is) and the wiring.
+ */
+describe('DataTableCore sticky scroll rail', () => {
+  let restore: () => void = () => {}
+  let restoreBox: () => void = () => {}
+  afterEach(() => {
+    restore()
+    restoreBox()
+  })
+
+  const renderCore = (props: Record<string, unknown> = {}) =>
+    render(<DataTableCore data={data} columns={columns} getRowId={(r) => r.id} {...props} />)
+
+  it('renders no rail when every column already fits', () => {
+    restore = stubGeometry(846, 846)
+    restoreBox = stubShellBox(0, 4000)
+    const { container } = renderCore()
+    expect(rail(container)).toBeNull()
+  })
+
+  /**
+   * The gate that a first attempt gets wrong, and did: "the shell's bottom is
+   * below the fold" is ALSO true of every table further down the page that
+   * nobody has scrolled to yet, and of short ones that need no rail at all.
+   * Caught on /scrollers by a two-row case growing a rail from 4,000px away.
+   */
+  it('renders no rail when the table has not been reached yet', () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(2000, 4000) // entirely below a 768px viewport
+    const { container } = renderCore()
+    expect(rail(container)).toBeNull()
+  })
+
+  it("renders no rail when the table's own scrollbar is already on screen", () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(0, 300) // the whole table fits above the fold
+    const { container } = renderCore()
+    expect(rail(container)).toBeNull()
+  })
+
+  it('renders a rail when columns are hidden and the real bar is below the fold', () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(0, 4000)
+    const { container } = renderCore()
+    const bar = rail(container)
+    expect(bar).not.toBeNull()
+    // A real scrollbar, not a widget imitating one: a strut as wide as the
+    // table, so the platform draws the thumb at the right size and drags it.
+    const strut = bar!.querySelector<HTMLDivElement>(`.${TABLE_RAIL_TRACK_CLASS}`)
+    expect(strut).not.toBeNull()
+    expect(strut!.style.width).toBe('1200px')
+    // A duplicate control for a region the table itself already exposes to the
+    // keyboard, so it is announced to nobody and is not a tab stop.
+    expect(bar).toHaveAttribute('aria-hidden', 'true')
+    expect(bar).toHaveAttribute('tabindex', '-1')
+  })
+
+  it('can be turned off by a consumer that pins its own control to the viewport', () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(0, 4000)
+    const { container } = renderCore({ scrollRail: false })
+    expect(rail(container)).toBeNull()
+  })
+
+  it('moves the table when the rail is dragged, and follows the table back', () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(0, 4000)
+    const { container } = renderCore()
+    const bar = rail(container)!
+    const scroller = screen.getByRole('table').parentElement!
+
+    act(() => {
+      bar.scrollLeft = 120
+      bar.dispatchEvent(new Event('scroll'))
+    })
+    expect(scroller.scrollLeft).toBe(120)
+
+    act(() => {
+      scroller.scrollLeft = 0
+      scroller.dispatchEvent(new Event('scroll'))
+    })
+    expect(bar.scrollLeft).toBe(0)
+  })
+
+  /**
+   * The removal this whole fix turns on. `overflow-x-auto` made the shell a
+   * scroll container, and `position: sticky` inside a scroll container resolves
+   * against IT — which pinned the rail to the bottom of the TABLE, i.e. exactly
+   * where the useless bar already was. The clipping and the `min-width: 0` it
+   * was also providing now come from `.ss-table-shell` in the injected sheet.
+   */
+  it('leaves the shell a non-scroll container, or the rail never reaches the viewport', () => {
+    restore = stubGeometry(846, 1200)
+    restoreBox = stubShellBox(0, 4000)
+    const { container } = renderCore()
+    const shell = container.querySelector(`.${TABLE_SHELL_CLASS}`)!
+    expect(shell).not.toHaveClass('overflow-x-auto')
+    expect(shell).not.toHaveClass('overflow-auto')
+  })
+})

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

@@ -4,10 +4,13 @@ import { ReactNode, useState, useCallback, useRef } from 'react'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../../ui/table'
 import {
   useScrollEdges,
+  useScrollRail,
   TABLE_SHELL_CLASS,
   TABLE_EDGE_CLASS,
   TABLE_EDGE_LEFT_CLASS,
   TABLE_EDGE_RIGHT_CLASS,
+  TABLE_RAIL_CLASS,
+  TABLE_RAIL_TRACK_CLASS,
 } from '../../../ui/table-scroll'
 import { Checkbox } from '../../../ui/checkbox'
 import { Button } from '../../../ui/button'
@@ -61,6 +64,15 @@ interface DataTableCoreProps<TData> {
   /** Shown in place of the rows when there are none. Defaults to "No results found." */
   emptyState?: ReactNode
 
+  /**
+   * The sticky horizontal scrollbar (startsim-xe1uo.1). On by default: it only
+   * renders while columns are hidden AND the table's own bar is off screen, so
+   * on everything else it puts nothing in the DOM. Turn it off for a surface
+   * that already pins its own control to the bottom of the screen, where two
+   * bars would stack.
+   */
+  scrollRail?: boolean
+
   className?: string
 }
 
@@ -90,6 +102,7 @@ export function DataTableCore<TData>({
   onRowClick,
   emptyState,
   loadingRows = new Set(),
+  scrollRail = true,
   className,
 }: DataTableCoreProps<TData>) {
   // State for tracking which cell is being edited
@@ -105,6 +118,9 @@ export function DataTableCore<TData>({
   // the very bottom of the page (startsim-5pq7h).
   const tableRef = useRef<HTMLTableElement>(null)
   const scrollEdges = useScrollEdges(tableRef)
+  // ...and the hint only SAYS there is more to the right. The rail is how a
+  // mouse with no horizontal axis actually gets there (startsim-xe1uo.1).
+  const rail = useScrollRail(tableRef, scrollRail)
 
   // Drag handlers
   const handleDragStart = useCallback((_: DragStart) => {
@@ -347,14 +363,21 @@ 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).
-    // NOTE: this div is not the element that ends up scrolling — `Table`'s own
+    // The non-scrolling shell the edge hints and the rail are pinned to.
+    //
+    // Its clipping and its `min-width: 0` now come from `.ss-table-shell` in
+    // the injected sheet, NOT from a Tailwind `overflow-x-auto` here. That
+    // class was doing three jobs by accident, one of which was making the shell
+    // a scroll container — and `position: sticky` inside a scroll container
+    // resolves against IT, which pinned the rail to the bottom of the table
+    // instead of the bottom of the screen. See lib/scroll-affordance.ts for the
+    // measurements and for why `clip` alone was not enough.
+    //
+    // NOTE: this div is not the element that scrolls — `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)}>
+    // and the ref below both target the inner wrapper.
+    <div className={cn('rounded-md border border-border', TABLE_SHELL_CLASS, className)}>
       <Table ref={tableRef}>
         {renderColumnHeaders()}
 
@@ -505,6 +528,23 @@ export function DataTableCore<TData>({
       {scrollEdges.right && (
         <div aria-hidden="true" className={cn(TABLE_EDGE_CLASS, TABLE_EDGE_RIGHT_CLASS)} />
       )}
+
+      {/* The sticky scrollbar. A real `overflow-x: auto` box holding a strut as
+          wide as the table, so the platform draws and drags it — not a widget
+          imitating one. Rendered only while columns are hidden AND the table's
+          own bar is off screen; `aria-hidden` and out of the tab order because
+          it is a duplicate control for a region that is already keyboard
+          scrollable through the table itself. */}
+      {rail.active && (
+        <div
+          ref={rail.railRef}
+          aria-hidden="true"
+          tabIndex={-1}
+          className={TABLE_RAIL_CLASS}
+        >
+          <div className={TABLE_RAIL_TRACK_CLASS} style={{ width: rail.contentWidth }} />
+        </div>
+      )}
     </div>
   )
 }

package/src/components/unified-table/types.ts

@@ -67,6 +67,13 @@ export interface UnifiedTableProps<TData> {
   className?: string
   emptyState?: ReactNode
   errorState?: ReactNode
+  /**
+   * The sticky horizontal scrollbar (startsim-xe1uo.1), on by default. It only
+   * renders while columns are hidden AND the table's own scrollbar is off
+   * screen; set false on a surface that already pins its own control to the
+   * bottom of the viewport.
+   */
+  scrollRail?: boolean
 }
 
 // Column Configuration