@startsimpli/ui 0.4.117 → 0.4.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.117",
+  "version": "0.4.118",
   "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/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,