@startsimpli/ui 0.4.117 → 0.4.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.117",
+  "version": "0.4.119",
   "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/auth": "^0.4.35",
+    "@startsimpli/api": "^0.5.58",
     "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.58"
+    "@startsimpli/auth": "^0.4.35"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

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

@@ -55,6 +55,29 @@ describe('TABLE_SCROLL_CSS', () => {
   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/)
   })
+
+  /**
+   * startsim-xe1uo. The edge hint shipped fading to `hsl(var(--background))`,
+   * which made it INVISIBLE: it is absolutely positioned over rows whose
+   * background-color is `rgba(0,0,0,0)` all the way up, so what is actually
+   * behind it is whatever the page paints — `bg-gray-50` = rgb(249,250,251) on
+   * the marketing-agents dashboard, against a token resolving to
+   * rgb(250,250,250). Sampled from the live page: delta (1,0,1).
+   *
+   * The hint cannot know its surface, so it must SHADE rather than MATCH. Every
+   * "fade the edge" snippet reaches for the background token, so guard the
+   * shape here; the visible-shading claim itself is carried by the pixel diff
+   * in examples/workflow-studio/scripts/measure-scrollers.mjs (delta 3 -> 35).
+   */
+  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/)
+    expect(edgeRules).not.toMatch(/--background/)
+    expect(edgeRules).toMatch(/--foreground/)
+    // A fully transparent stop at the inner end, so it reads as a fade and not
+    // as a hard 24px band.
+    expect(edgeRules).toMatch(/--foreground\)\s*\/\s*0\)/)
+  })
 })
 
 describe('Table', () => {

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

@@ -257,6 +257,9 @@ export function UnifiedTable<TData>({
     initialPage: paginationConfig?.currentPage || (initialURLState?.page ?? 1),
     serverSide: paginationConfig?.serverSide || false,
     onPageChange: paginationConfig?.onPageChange,
+    // `sortedData` IS the body — every row of it is rendered below, nothing is
+    // sliced here — so it is the only honest source for "Showing X-Y".
+    renderedCount: sortedData.length,
   })
 
   // Selection hook - supports both controlled and uncontrolled modes

package/src/components/unified-table/__tests__/components/TablePagination.test.tsx

@@ -1,7 +1,40 @@
 import { render, screen, fireEvent } from '@testing-library/react'
 import { TablePagination } from '../../components/TablePagination'
+import { usePagination } from '../../hooks/usePagination'
 import { UsePaginationReturn } from '../../types'
 
+/**
+ * Drives the REAL hook.
+ *
+ * The count line is the one thing in this component that is arithmetic rather
+ * than markup, so a mocked `getDisplayRange` turns its test into a test of the
+ * mock — which is how "Showing 1-20" over a body of 50 rows survived on every
+ * table in the fleet (bd startsim-b9v6p). Mocking stays legitimate for the
+ * button/page-number blocks below, where the hook's answers are inputs to the
+ * markup rather than the thing under test.
+ */
+function RealPagination({
+  totalCount,
+  pageSize,
+  page = 1,
+  renderedCount,
+  totalFilteredCount,
+}: {
+  totalCount: number
+  pageSize: number
+  page?: number
+  renderedCount?: number
+  totalFilteredCount?: number
+}) {
+  const pagination = usePagination({
+    totalCount,
+    initialPageSize: pageSize,
+    initialPage: page,
+    renderedCount,
+  })
+  return <TablePagination pagination={pagination} totalFilteredCount={totalFilteredCount} />
+}
+
 describe('TablePagination', () => {
   const createMockPagination = (overrides?: Partial<UsePaginationReturn>): UsePaginationReturn => ({
     currentPage: 1,
@@ -22,8 +55,9 @@ describe('TablePagination', () => {
 
   describe('Display', () => {
     it('should render item count display', () => {
-      const pagination = createMockPagination()
-      const { container } = render(<TablePagination pagination={pagination} />)
+      const { container } = render(
+        <RealPagination totalCount={100} pageSize={25} renderedCount={25} />
+      )
 
       // Find the item count display div by its specific class and verify content
       const itemCountDiv = container.querySelector('.text-muted-foreground')
@@ -34,23 +68,52 @@ describe('TablePagination', () => {
       expect(itemCountDiv?.textContent).toContain('100')
     })
 
+    it('should count the rows on screen, not the declared page size', () => {
+      // A server page of 50 under a paginationConfig that declares 20 — the
+      // shape measured on every content view of the marketing-agents tenant.
+      const { container } = render(
+        <RealPagination totalCount={5485} pageSize={20} renderedCount={50} />
+      )
+
+      expect(container.querySelector('.text-muted-foreground')?.textContent).toContain('1-50')
+    })
+
+    it('should count a whole client-rendered corpus', () => {
+      const { container } = render(
+        <RealPagination totalCount={68} pageSize={20} renderedCount={68} />
+      )
+
+      expect(container.querySelector('.text-muted-foreground')?.textContent).toContain('1-68')
+    })
+
     it('should display current page and total pages', () => {
-      const pagination = createMockPagination({ currentPage: 2, totalPages: 4 })
-      render(<TablePagination pagination={pagination} />)
+      render(<RealPagination totalCount={100} pageSize={25} page={2} renderedCount={25} />)
 
       expect(screen.getByText(/Page 2 of 4/)).toBeInTheDocument()
     })
 
     it('should show filtered items indicator when totalFilteredCount differs from totalCount', () => {
-      const pagination = createMockPagination()
-      render(<TablePagination pagination={pagination} totalFilteredCount={50} />)
+      render(
+        <RealPagination
+          totalCount={100}
+          pageSize={25}
+          renderedCount={25}
+          totalFilteredCount={50}
+        />
+      )
 
       expect(screen.getByText(/filtered items/)).toBeInTheDocument()
     })
 
     it('should not show filtered indicator when counts match', () => {
-      const pagination = createMockPagination()
-      render(<TablePagination pagination={pagination} totalFilteredCount={100} />)
+      render(
+        <RealPagination
+          totalCount={100}
+          pageSize={25}
+          renderedCount={25}
+          totalFilteredCount={100}
+        />
+      )
 
       expect(screen.queryByText(/filtered items/)).not.toBeInTheDocument()
     })

package/src/components/unified-table/__tests__/hooks/usePagination.test.ts

@@ -354,6 +354,43 @@ describe('usePagination', () => {
       expect(range.start).not.toBeGreaterThan(range.end)
     })
 
+    it('should end the range at the last row rendered, not the last row of a page size', () => {
+      // The consuming table fetched 50 while declaring 20 (bd startsim-b9v6p).
+      const { result } = renderHook(() =>
+        usePagination({ totalCount: 5485, initialPageSize: 20, renderedCount: 50 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 1, end: 50 })
+    })
+
+    it('should span the whole corpus when the table rendered all of it', () => {
+      const { result } = renderHook(() =>
+        usePagination({ totalCount: 68, initialPageSize: 20, renderedCount: 68 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 1, end: 68 })
+    })
+
+    it('should never run the range past the reported total', () => {
+      // A caller whose total is below what it rendered is its own defect; the
+      // range still has to read forwards.
+      const { result } = renderHook(() =>
+        usePagination({ totalCount: 50, initialPageSize: 20, renderedCount: 68 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 1, end: 50 })
+    })
+
+    it('should fall back to the page size while the body is empty', () => {
+      // A refetch that clears `data` between pages must not flash "No items"
+      // over a table that has thousands.
+      const { result } = renderHook(() =>
+        usePagination({ ...defaultProps, renderedCount: 0 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 1, end: 25 })
+    })
+
     it('should report an empty range when the page sits past the last row', () => {
       // Server-side counts shrink under a page that is already open (rule 8:
       // the count comes from the server, the client never recounts).

package/src/components/unified-table/__tests__/integration/pagination-range.test.tsx

@@ -0,0 +1,183 @@
+/**
+ * "Showing X-Y of N" must describe the rows that are actually on screen
+ * (bd startsim-b9v6p).
+ *
+ * MEASURED LIVE on the marketing-agents tenant: every content view said
+ * "Showing 1-20 of N" no matter how many rows the body held — 50 for a
+ * server-paged view, 68 for one that renders its whole corpus. The end of the
+ * range was arithmetic over the paginator's OWN page size, a number the table
+ * body never consults, because `UnifiedTable` renders exactly the rows its
+ * caller hands it and never slices them.
+ *
+ * These tests drive the REAL `usePagination` through a real `<UnifiedTable>`,
+ * which is the only way to prove the wiring: `TablePagination`'s own suite
+ * mocks `getDisplayRange`, so it asserts the label renders whatever the mock
+ * said and can never see the range being wrong.
+ *
+ * THEY ASSERT AN INVARIANT, NOT A ROW COUNT. Every expectation below is
+ * "the label counts the rows that are on screen", read from the DOM both
+ * times. That is deliberate: whether `UnifiedTable` should also SLICE its data
+ * is a live question elsewhere, and pinning "50 rows render" here would turn
+ * this suite into an obstacle to that decision while proving nothing extra —
+ * the invariant is already red against the old arithmetic, which computed the
+ * end of the range from a page size the body never consulted.
+ */
+import { render } from '@testing-library/react'
+import { UnifiedTable } from '../../index'
+import { ColumnConfig } from '../../types'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const columns: ColumnConfig<Row>[] = [{ id: 'name', header: 'Name', accessorKey: 'name' }]
+
+/** `count` rows whose ids start at `startAt`, as a server page would arrive. */
+function rows(count: number, startAt = 1): Row[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: String(startAt + i),
+    name: `Row ${startAt + i}`,
+  }))
+}
+
+/** The "Showing …" line, read out of the DOM the way a user reads it. */
+function rangeLabel(container: HTMLElement): string {
+  const matches = Array.from(container.querySelectorAll('div')).filter((d) =>
+    /^Showing \d+-\d+ of \d+$/.test((d.textContent ?? '').trim()),
+  )
+  if (matches.length === 0) throw new Error('no "Showing X-Y of N" label rendered')
+  // Deepest match: an ancestor carrying only this text is the same label.
+  return (matches[matches.length - 1].textContent ?? '').trim()
+}
+
+/** How many body rows the table actually put on screen. */
+function renderedRowCount(container: HTMLElement): number {
+  return container.querySelectorAll('tbody tr').length
+}
+
+/**
+ * Asserts the one thing the label owes the user: its span is the rows in the
+ * body. Both numbers are read out of the same DOM, so the assertion holds
+ * whatever the table decides to render.
+ */
+function expectRangeToCountTheBody(container: HTMLElement, opts: { from: number; of: number }) {
+  const rows = renderedRowCount(container)
+  expect(rows).toBeGreaterThan(0)
+  expect(rangeLabel(container)).toBe(
+    `Showing ${opts.from}-${opts.from + rows - 1} of ${opts.of}`,
+  )
+}
+
+describe('pagination range vs the rows on screen', () => {
+  it('counts a server page of 50 as 50, not as the declared page size', () => {
+    // news_item on the marketing-agents tenant: 5485 rows, 50 fetched per page,
+    // a paginationConfig that declares 20. The body holds 50.
+    const { container } = render(
+      <UnifiedTable<Row>
+        data={rows(50)}
+        columns={columns}
+        tableId="server-paged"
+        getRowId={(r) => r.id}
+        pagination={{
+          enabled: true,
+          pageSize: 20,
+          totalCount: 5485,
+          currentPage: 1,
+          serverSide: true,
+          onPageChange: jest.fn(),
+        }}
+      />,
+    )
+
+    // Pre-fix this read "Showing 1-20 of 5485" over a body of 50 rows.
+    expectRangeToCountTheBody(container, { from: 1, of: 5485 })
+  })
+
+  it('counts a fully client-rendered table as all of it', () => {
+    // topic: the page asks for every row, so all 68 render at once and the
+    // range is the whole corpus.
+    const { container } = render(
+      <UnifiedTable<Row>
+        data={rows(68)}
+        columns={columns}
+        tableId="client-rendered"
+        getRowId={(r) => r.id}
+        pagination={{
+          enabled: true,
+          pageSize: 20,
+          totalCount: 68,
+          currentPage: 1,
+          serverSide: false,
+        }}
+      />,
+    )
+
+    // Pre-fix this read "Showing 1-20 of 68" over a body of 68 rows.
+    expectRangeToCountTheBody(container, { from: 1, of: 68 })
+  })
+
+  it('leaves a table whose page size matches its fetch exactly as it was', () => {
+    // The overwhelming majority of the fleet: 25 declared, 25 rendered, page 3.
+    const { container } = render(
+      <UnifiedTable<Row>
+        data={rows(25, 51)}
+        columns={columns}
+        tableId="well-behaved"
+        getRowId={(r) => r.id}
+        pagination={{
+          enabled: true,
+          pageSize: 25,
+          totalCount: 100,
+          currentPage: 3,
+          serverSide: true,
+          onPageChange: jest.fn(),
+        }}
+      />,
+    )
+
+    expectRangeToCountTheBody(container, { from: 51, of: 100 })
+  })
+
+  it('stops a short last page at the last row', () => {
+    const { container } = render(
+      <UnifiedTable<Row>
+        data={rows(15, 76)}
+        columns={columns}
+        tableId="short-last-page"
+        getRowId={(r) => r.id}
+        pagination={{
+          enabled: true,
+          pageSize: 25,
+          totalCount: 90,
+          currentPage: 4,
+          serverSide: true,
+          onPageChange: jest.fn(),
+        }}
+      />,
+    )
+
+    expectRangeToCountTheBody(container, { from: 76, of: 90 })
+  })
+
+  it('says "No items" rather than a range when the body is empty', () => {
+    const { container } = render(
+      <UnifiedTable<Row>
+        data={[]}
+        columns={columns}
+        tableId="empty"
+        getRowId={(r) => r.id}
+        pagination={{
+          enabled: true,
+          pageSize: 20,
+          totalCount: 0,
+          currentPage: 1,
+          serverSide: true,
+        }}
+      />,
+    )
+
+    expect(() => rangeLabel(container)).toThrow()
+    expect(container.textContent).toContain('No items')
+  })
+})

package/src/components/unified-table/hooks/usePagination.ts

@@ -8,6 +8,15 @@ interface UsePaginationProps {
   initialPage?: number
   serverSide?: boolean
   onPageChange?: (page: number) => void
+  /**
+   * How many rows the table actually put on screen for this page.
+   *
+   * Optional because the hook is public API and a caller may drive it without a
+   * table attached; when it is absent the page size is the only number
+   * available. When it is present it WINS for the width of the display range,
+   * because the body is the thing the label is describing.
+   */
+  renderedCount?: number
 }
 
 export function usePagination({
@@ -16,6 +25,7 @@ export function usePagination({
   initialPage = 1,
   serverSide = false,
   onPageChange,
+  renderedCount,
 }: UsePaginationProps): UsePaginationReturn {
   const [currentPage, setCurrentPage] = useState(initialPage)
   const [pageSize, setPageSize] = useState(initialPageSize)
@@ -102,18 +112,40 @@ export function usePagination({
    * no span to describe. `totalCount` is whatever the server reported, so it can
    * legitimately be 0, or drop below the page the user already has open — both
    * cases used to produce a backwards range like `1-0`.
+   *
+   * The WIDTH of the span comes from `renderedCount` — the rows the table
+   * actually drew — and not from `pageSize`. `UnifiedTable` renders exactly the
+   * rows it is handed and never slices them, so a view that fetches 50 per page,
+   * or fetches its whole corpus at once, holds a different number of rows than
+   * the page size its caller declared. Deriving the end from `pageSize` made the
+   * label read "Showing 1-20" over a body of 50 or 68 rows on every table in the
+   * fleet (bd startsim-b9v6p).
+   *
+   * The OFFSET still comes from `currentPage * pageSize`: how many rows precede
+   * this page is a fact only the caller's page size can supply, and no count of
+   * what is on screen can recover it. A caller that declares one page size and
+   * fetches another therefore still gets a wrong `start` past page 1 — but its
+   * pager is already wrong in exactly the same way, and the fix for that is for
+   * the caller to declare the size it uses.
    */
   const getDisplayRange = useCallback(() => {
     if (totalCount <= 0) return { start: 0, end: 0 }
 
+    // An empty body is left to the page-size arithmetic rather than reported as
+    // an empty range: a refetch that clears `data` between pages would otherwise
+    // flash "No items" over a table that has thousands.
+    const rowsOnScreen = renderedCount != null && renderedCount > 0 ? renderedCount : pageSize
+
     const start = (currentPage - 1) * pageSize + 1
-    const end = Math.min(currentPage * pageSize, totalCount)
+    // Clamped to `totalCount`: a caller reporting a total BELOW what it rendered
+    // is a different defect, and "1-68 of 50" would only make it unreadable.
+    const end = Math.min(start + rowsOnScreen - 1, totalCount)
 
     // The page begins past the last row: nothing is shown here.
     if (start > end) return { start: 0, end: 0 }
 
     return { start, end }
-  }, [currentPage, pageSize, totalCount])
+  }, [currentPage, pageSize, totalCount, renderedCount])
 
   return {
     currentPage,

package/src/lib/scroll-affordance.ts

@@ -21,6 +21,48 @@ 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'
 
+/**
+ * The edge hint SHADES its surface; it must never try to MATCH it.
+ *
+ * It shipped as a fade to `hsl(var(--background))` and that is structurally
+ * unable to work: the hint is absolutely positioned over table rows whose
+ * `background-color` is `rgba(0,0,0,0)` for every level from the cell up to the
+ * shell, so it cannot know what is behind it. On the marketing-agents tenant
+ * what is behind it is the dashboard's `bg-gray-50` = rgb(249,250,251), while
+ * the token resolves to rgb(250,250,250) — MEASURED 2026-09-09 by sampling the
+ * live page: delta (1,0,1), a contrast ratio of 1.00:1. The hint rendered at
+ * the right size, in the right place, and mounted only while a side hid
+ * content — and was invisible (bd startsim-xe1uo). Its only visible effect was
+ * erasing whatever glyphs sat under it, so the affordance appeared or not
+ * depending on whether that row had text at the right, and never on the header
+ * band, a blank cell, or the gap between rows.
+ *
+ * That matters more than it sounds, because the hint is the ONLY affordance a
+ * reader at the header row can see: the scrollbar is at the bottom of a
+ * scroller as tall as the whole table, measured 2,741-5,994px below the
+ * truncation on the live tenant.
+ *
+ * `--foreground` at a low alpha inverts with the theme, so one rule shades
+ * both. Measured with the pixel diff in
+ * examples/workflow-studio/scripts/measure-scrollers.mjs, which scores only the
+ * pixels that were bare surface before the hint was drawn:
+ *
+ *   hsl(var(--background))         on bg-gray-50   ->  delta   3   (the old rule)
+ *   hsl(var(--foreground) / 0.14)  on bg-gray-50   ->  delta  35
+ *   hsl(var(--foreground) / 0.14)  on a dark page  ->  delta  33
+ *
+ * Confirmed against the deployed tenant rather than assumed from the harness:
+ * its `--foreground` resolves to rgba(2,8,23,0.14) at this alpha, which over
+ * the surface sampled there (rgb(249,250,251)) composites to rgb(214,216,219)
+ * — per-channel 35/34/32.
+ *
+ * If this needs re-tuning, move the alpha — do NOT reintroduce a token that
+ * names a background, or the hint silently disappears again wherever a page
+ * paints itself a shade the token does not know about.
+ */
+const EDGE_SHADE = 'hsl(var(--foreground) / 0.14)'
+const EDGE_SHADE_NONE = 'hsl(var(--foreground) / 0)'
+
 /**
  * Content scrolls, but on macOS nothing says so (startsim-5pq7h, 5pq7h.1).
  *
@@ -51,7 +93,11 @@ export const TABLE_EDGE_RIGHT_CLASS = 'ss-table-edge-right'
  *    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.
+ *    hint below instead — a claim that was FALSE as originally shipped, because
+ *    the hint faded to the background token and was invisible (startsim-xe1uo,
+ *    measured delta 3). It holds because {@link EDGE_SHADE} shades instead. If
+ *    that ever goes back to matching a background, this paragraph goes with it
+ *    and Firefox is left with nothing at all.
  *
  * 2. `width` IS LOAD-BEARING even though the defect that started this is
  *    horizontal. Declaring any `::-webkit-scrollbar` rule opts the element out
@@ -75,8 +121,14 @@ export const TABLE_EDGE_RIGHT_CLASS = 'ss-table-edge-right'
  *    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.
+ * not reserve a second gutter, so no platform guard is needed. That was the one
+ * unmeasured line in this file until startsim-xe1uo; MEASURED 2026-09-09 in
+ * headful Linux Chromium (classic scrollbars, negative control 15px with this
+ * sheet disabled) on the live tenant, it holds — no double gutter — at the cost
+ * of a bar 5px thinner and, at `currentColor` 22%, fainter than the platform's
+ * own. Weigh that if this ever gets tuned; it is not what sent the bead back.
+ * Nothing here animates or transitions, so `prefers-reduced-motion` has nothing
+ * to honour.
  *
  * ONE stylesheet, ONE id, ONE string: `ensureInjectedStyle` rewrites the sheet
  * when an existing id carries different text, so two call sites shipping
@@ -114,11 +166,11 @@ export const SCROLL_AFFORDANCE_CSS = `
 }
 .${TABLE_EDGE_RIGHT_CLASS} {
   right: 0;
-  background-image: linear-gradient(to left, hsl(var(--background)), hsl(var(--background) / 0));
+  background-image: linear-gradient(to left, ${EDGE_SHADE}, ${EDGE_SHADE_NONE});
 }
 .${TABLE_EDGE_LEFT_CLASS} {
   left: 0;
-  background-image: linear-gradient(to right, hsl(var(--background)), hsl(var(--background) / 0));
+  background-image: linear-gradient(to right, ${EDGE_SHADE}, ${EDGE_SHADE_NONE});
 }
 `.trim()