@startsimpli/ui 0.4.116 → 0.4.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.116",
+  "version": "0.4.118",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -48,8 +48,8 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "@startsimpli/api": "^0.5.58",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/auth": "^0.4.35"
+    "@startsimpli/auth": "^0.4.35",
+    "@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/collection/DraftReviewWorkspace.tsx

@@ -27,6 +27,7 @@ import {
   isChosen,
   gradeWords,
   wordTargets,
+  draftWordCount,
   sourceOverlapCheck,
   pickChanges,
   isRejectedTopicGroup,
@@ -332,8 +333,7 @@ function CandidateCard({
   const chosen = isChosen(record);
   const status = field(record, 'status');
   const preview = field(record, 'blog').slice(0, 150);
-  const checks = obj(readData(record.data, 'auto_checks'));
-  const blogWords = Number(get(checks, 'blogWords', 'blog_words')) || 0;
+  const blogWords = draftWordCount(record, 'blog');
   const target = wordTargets(contentType).blog;
   return (
     <div className={`flex flex-col rounded-md border p-3 ${chosen ? 'border-emerald-400 bg-emerald-50/40' : 'border-border bg-white'}`}>
@@ -407,8 +407,8 @@ function ContentReview({
   })();
 
   const targets = wordTargets(contentType);
-  const blogWords = Number(get(checks, 'blogWords', 'blog_words')) || 0;
-  const liWords = Number(get(checks, 'linkedinWords', 'linkedin_words')) || 0;
+  const blogWords = draftWordCount(record, 'blog');
+  const liWords = draftWordCount(record, 'linkedin');
   const hype = get(checks, 'hypeFlags', 'hype_flags');
   const approvedSources = get(checks, 'approvedSources', 'approved_sources');
 

package/src/components/collection/__tests__/drafts.test.ts

@@ -1,4 +1,5 @@
-import { parseSources, normUrl, groupKeyOf, groupDrafts, candidateTitle, gradeWords, wordTargets, sourceOverlapCheck, pickChanges, isRejectedTopicGroup } from '../drafts';
+import { parseSources, normUrl, groupKeyOf, groupDrafts, candidateTitle, gradeWords, wordTargets, sourceOverlapCheck, pickChanges, isRejectedTopicGroup, draftWordCount } from '../drafts';
+import { wordCount } from '../../validation';
 import type { EntityRecord } from '../types';
 
 function rec(id: string, name: string, data: Record<string, unknown>): EntityRecord {
@@ -151,3 +152,100 @@ describe('isRejectedTopicGroup (startsim-ay9l — collapse drafts of rejected to
     expect(isRejectedTopicGroup(g, new Set(['']))).toBe(false);
   });
 });
+
+/**
+ * A draft with no stored auto-checks still has a LENGTH (bd startsim-8hgmq.15).
+ *
+ * OBSERVED on the live tenant, 2026-09-07, at /drafts: a Chinese candidate card
+ * read "blog 0w … unjudged". The draft was 1027 characters, 855 of them CJK.
+ * The workspace was reading the count out of the stored `auto_checks` blob with
+ * `Number(get(checks, 'blogWords', 'blog_words')) || 0`, and the blob is null on
+ * every translated draft — `auto_checks` is written by the generator, while a
+ * translation is made by the tenant's own translate-draft, which deliberately
+ * does not inherit checks that measured text the checker never saw. So
+ * `Number(undefined) || 0` announced every translation as empty.
+ *
+ * The three live rows, all `auto_checks: null` and `judge_verdict: null`:
+ *   f6a2d629 zh  1027 chars (855 CJK)
+ *   147d0eb8 zh  1109 chars (972 CJK)
+ *   d0ca457a ar  2998 chars
+ *
+ * "unjudged" was honest — no judge ran. "0w" was not: nothing measured this
+ * draft, and an absent check must never render as a zero measurement.
+ */
+describe('draftWordCount (startsim-8hgmq.15 — a missing check is not a zero)', () => {
+  // The opening of the live zh draft f6a2d629, not invented text — the same
+  // fixture the counter's own tests use (validation/__tests__/word-count-scripts).
+  const ZH_BLOG =
+    '来自《Arabian Business》的报道显示，海湾—亚洲技术走廊正进入新阶段，' +
+    '中国企业正从单纯投资转向在GCC范围内更深度嵌入的运营模式。';
+  const EN_BLOG =
+    'The Gulf-Asia technology corridor is entering a new phase, with Chinese firms ' +
+    'moving from investment into deeper operational embedding across the GCC.';
+
+  it('counts the draft itself when the translation carries no auto_checks', () => {
+    // The reported card. Whitespace counting scores this text 2 and the old
+    // stored-only read scored it 0; either way the reviewer was told the draft
+    // was empty.
+    const zh = rec('f6a2d629', '中国—海湾科技扩张引发入局者对执行的疑问', {
+      candidate_index: 1,
+      lang: 'zh',
+      blog: ZH_BLOG,
+      auto_checks: null,
+      judge_verdict: null,
+    });
+    expect(draftWordCount(zh, 'blog')).toBeGreaterThan(20);
+  });
+
+  it('falls back for linkedin the same way', () => {
+    const zh = rec('f6a2d629', 'zh', { lang: 'zh', linkedin: ZH_BLOG, auto_checks: null });
+    expect(draftWordCount(zh, 'linkedin')).toBeGreaterThan(20);
+    expect(draftWordCount(zh, 'blog')).toBe(0); // no blog field at all IS zero
+  });
+
+  it('is a FALLBACK, not a replacement — a stored count wins', () => {
+    // Without this, "always recompute" passes the test above while quietly
+    // dropping the pipeline's own measurement, which is the number the judge and
+    // the writer agreed on.
+    const en = rec('d1', 'EN', { blog: EN_BLOG, auto_checks: { blog_words: 431, linkedin_words: 118 } });
+    expect(draftWordCount(en, 'blog')).toBe(431);
+    expect(draftWordCount(en, 'linkedin')).toBe(118);
+  });
+
+  it('reads the camelCased blob the API client returns', () => {
+    // The tenant client camelCases response keys, data blob included, so the
+    // same record arrives as autoChecks.blogWords over the wire.
+    const en = rec('d1', 'EN', { blog: EN_BLOG, autoChecks: { blogWords: 431 } });
+    expect(draftWordCount(en, 'blog')).toBe(431);
+  });
+
+  it('keeps a stored zero, which is a measurement rather than an absence', () => {
+    const empty = rec('d2', 'EN', { blog: '', auto_checks: { blog_words: 0 } });
+    expect(draftWordCount(empty, 'blog')).toBe(0);
+  });
+
+  it('recomputes when the blob exists but lacks this field', () => {
+    // A checker that ran on the blog only must not make the LinkedIn post read 0.
+    const partial = rec('d3', 'EN', { blog: EN_BLOG, linkedin: EN_BLOG, auto_checks: { blog_words: 431 } });
+    expect(draftWordCount(partial, 'blog')).toBe(431);
+    expect(draftWordCount(partial, 'linkedin')).toBe(23);
+  });
+
+  it('recomputes rather than trusting an unparseable stored value', () => {
+    const junk = rec('d4', 'EN', { blog: EN_BLOG, auto_checks: { blog_words: 'n/a' } });
+    expect(draftWordCount(junk, 'blog')).toBe(23);
+  });
+
+  it('agrees with the shared counter, so the chip and the rail cannot contradict', () => {
+    // startsim-wn2p.28: the count was wrong in four places because it was
+    // written in four places, and the screen ended up saying "524 words" and
+    // "16w" about one draft. This must stay a call to that one function.
+    const en = rec('d5', 'EN', { blog: EN_BLOG, auto_checks: null });
+    expect(draftWordCount(en, 'blog')).toBe(wordCount(EN_BLOG));
+  });
+
+  it('is 0 for a draft that really is empty', () => {
+    expect(draftWordCount(rec('d6', 'EN', { blog: '', auto_checks: null }), 'blog')).toBe(0);
+    expect(draftWordCount(rec('d7', 'EN', {}), 'blog')).toBe(0);
+  });
+});

package/src/components/collection/__tests__/translated-draft-word-chip.test.tsx

@@ -0,0 +1,129 @@
+/**
+ * The compare workspace must not tell a reviewer that a full draft is empty
+ * (bd startsim-8hgmq.15).
+ *
+ * OBSERVED on the live tenant, 2026-09-07, at /drafts. A Chinese candidate card
+ * in the "How Chinese Firms Are Anchoring Into the Gulf Tech Corridor" set read
+ *
+ *   blog 0w   unjudged
+ *
+ * and the draft behind it was 1027 characters, 855 of them CJK. Half of that
+ * card was honest: no judge ran on a translation, so "unjudged" is true. The
+ * other half was a MISSING measurement rendered as a real zero — the card read
+ * the count out of the stored `auto_checks` blob, which a translation never
+ * gets, and `Number(undefined) || 0` is 0.
+ *
+ * `drafts.test.ts` pins the counting rule. This pins the SCREEN, at the level
+ * the defect was reported at: mount the workspace over a stubbed tenant client
+ * holding the three real drafts and read the chips.
+ */
+import * as React from 'react';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+// react-markdown is ESM and this suite is not; the workspace pulls it in only
+// to render an OPEN draft's body, which no assertion here reads.
+jest.mock('../../blog/MarkdownRenderer', () => ({
+  MarkdownRenderer: ({ content }: { content: string }) => <div>{content}</div>,
+}));
+
+import { DraftReviewWorkspace } from '../DraftReviewWorkspace';
+import type { CollectionClient, EntityRecord, EntityTypeDef, Paginated } from '../types';
+
+const DRAFT_TYPE: EntityTypeDef = { id: 1, key: 'draft', label: 'Draft', attributes: [] };
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function draft(id: number, name: string, data: Record<string, unknown>): EntityRecord {
+  return {
+    id,
+    entityType: 'draft',
+    externalId: null,
+    name,
+    data: { content_type: 'weekly_brief', topic_ref: 'topic-1', topic_title: 'Gulf tech corridor', ...data },
+    createdAt: '2026-09-01T00:00:00Z',
+  };
+}
+
+// The opening of the live zh draft f6a2d629 — real text, not a repeat()ed glyph.
+const ZH_BLOG =
+  '来自《Arabian Business》的报道显示，海湾—亚洲技术走廊正进入新阶段，' +
+  '中国企业正从单纯投资转向在GCC范围内更深度嵌入的运营模式。';
+const EN_BLOG =
+  'The Gulf-Asia technology corridor is entering a new phase, with Chinese firms ' +
+  'moving from investment into deeper operational embedding across the GCC.';
+
+/** The English original, which the writer checked, and its zh translation, which nothing checked. */
+const DRAFTS: EntityRecord[] = [
+  draft(1, 'Candidate 1 — Gulf tech corridor', {
+    candidate_index: 1,
+    story_title: 'China-Gulf Tech Expansion Raises Execution Questions for Entrants',
+    lang: 'en',
+    blog: EN_BLOG,
+    auto_checks: { blog_words: 431, linkedin_words: 180 },
+    judge_verdict: { verdict: 'accept' },
+  }),
+  draft(2, 'Candidate 2 — Gulf tech corridor', {
+    candidate_index: 2,
+    story_title: '中国—海湾科技扩张引发入局者对执行的疑问',
+    lang: 'zh',
+    blog: ZH_BLOG,
+    // Exactly how the live translations are stored: the generator's checks and
+    // verdict are NOT inherited, because they measured text neither one saw.
+    auto_checks: null,
+    judge_verdict: null,
+  }),
+];
+
+function stubClient(): CollectionClient {
+  return {
+    listTypes: jest.fn(async () => page([DRAFT_TYPE])),
+    listAllEntities: jest.fn(async (type: string) => (type === 'draft' ? DRAFTS : [])),
+    updateEntity: jest.fn(async () => DRAFTS[0]),
+  };
+}
+
+function renderWorkspace() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <DraftReviewWorkspace client={stubClient()} />
+    </QueryClientProvider>,
+  );
+}
+
+/** The card for one candidate, found by the title the reviewer reads. */
+async function card(title: string): Promise<HTMLElement> {
+  const heading = await screen.findByText(title);
+  const el = heading.closest('div.flex.flex-col');
+  if (!el) throw new Error(`no candidate card around "${title}"`);
+  return el as HTMLElement;
+}
+
+describe('a translated candidate card (startsim-8hgmq.15)', () => {
+  it('shows the draft’s real length instead of “blog 0w”', async () => {
+    renderWorkspace();
+    const zh = await card('中国—海湾科技扩张引发入局者对执行的疑问');
+
+    expect(within(zh).queryByText(/^blog 0w/)).toBeNull();
+    const chip = within(zh).getByText(/^blog \d+w/);
+    const words = Number(chip.textContent!.match(/blog (\d+)w/)![1]);
+    expect(words).toBeGreaterThan(20);
+  });
+
+  it('still says “unjudged”, which was the honest half of that card', async () => {
+    // No judge ran on the translation. The fix is to stop faking the count, not
+    // to fake a verdict alongside it.
+    renderWorkspace();
+    const zh = await card('中国—海湾科技扩张引发入局者对执行的疑问');
+    expect(within(zh).getByText('unjudged')).toBeTruthy();
+  });
+
+  it('leaves a checked candidate showing the count the pipeline stored', async () => {
+    renderWorkspace();
+    const en = await card('China-Gulf Tech Expansion Raises Execution Questions for Entrants');
+    await waitFor(() => expect(within(en).getByText(/^blog 431w/)).toBeTruthy());
+  });
+});

package/src/components/collection/drafts.ts

@@ -9,7 +9,7 @@
  */
 import type { EntityRecord } from './types';
 import { readData } from './data';
-import { runContentChecks, type ContentCheck } from '../validation';
+import { runContentChecks, wordCount, type ContentCheck } from '../validation';
 
 export interface DraftSource {
   url: string;
@@ -160,6 +160,49 @@ export function wordTargets(contentType: string): { blog: [number, number]; link
   }
 }
 
+/**
+ * The word count to SHOW for one field of one draft (bd startsim-8hgmq.15).
+ *
+ * WHY THIS EXISTS. The workspace used to read the count straight out of the
+ * stored blob — `Number(get(checks, 'blogWords', 'blog_words')) || 0` — and on
+ * 2026-09-07 a live Chinese candidate at /drafts advertised itself as
+ * "blog 0w … unjudged". The draft was 1027 characters, 855 of them CJK.
+ *
+ * `auto_checks` is written by the pipeline that GENERATES a candidate. A
+ * TRANSLATION is created by the tenant's own translate-draft, which copies the
+ * prose and deliberately does not inherit the generator's checks or verdict —
+ * they measured text neither one ever saw. So `auto_checks` is null on every
+ * translation, `Number(undefined) || 0` is 0, and every translated draft in the
+ * compare workspace announced itself as empty. Structural, not a bad row: the
+ * three live translations (zh, zh, ar) all read 0w, and so would every future
+ * one. "unjudged" beside it was honest — no judge ran — but an ABSENT check must
+ * never render as a zero MEASUREMENT.
+ *
+ * ABSENCE FALLS BACK, FALSINESS DOES NOT. A stored `0` is a measurement the
+ * pipeline actually took and it survives; only a missing or unparseable value is
+ * recomputed. That is the whole bug: the old code tested truthiness where it
+ * meant presence.
+ *
+ * IT RECOUNTS RATHER THAN BLANKING because the reviewer's job here is comparing
+ * candidates, and "—" tells them nothing about whether this one runs long.
+ *
+ * IT CALLS THE SHARED `wordCount` WITH NO LOCALE, exactly as `runContentChecks`
+ * does, so the chip and the validation rail on the same screen cannot disagree
+ * about one draft. This is a FALLBACK TO that function, never a second
+ * implementation of it — bd startsim-wn2p.28 was one line of arithmetic that
+ * took four PRs because the count had been written in four places, and the
+ * half-fixed screen read "524 words" in the rail and "16w" on the tab above it.
+ */
+export function draftWordCount(r: EntityRecord, field: 'blog' | 'linkedin'): number {
+  const checks = readData(r.data, 'auto_checks');
+  const bag = checks && typeof checks === 'object' && !Array.isArray(checks) ? (checks as Record<string, unknown>) : null;
+  // Both spellings, because the tenant API client camelCases the data blob.
+  const stored = bag ? bag[`${field}Words`] ?? bag[`${field}_words`] : undefined;
+  const n = Number(stored);
+  if (stored != null && stored !== '' && Number.isFinite(n)) return n;
+  return wordCount(str(readData(r.data, field)));
+}
+
 export type CheckStatus = 'ok' | 'low' | 'high' | 'none';
 
 /** Grade a word count against a [lo, hi] target. hi===0 means "no target". */

package/src/components/collection/index.ts

@@ -61,6 +61,7 @@ export {
   groupDrafts,
   wordTargets,
   gradeWords,
+  draftWordCount,
   type DraftSource,
   type DraftGroup,
   type CheckStatus,

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,