@lotics/ui 44.3.0 → 44.5.0

package/MIGRATION.md

@@ -4,6 +4,52 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 44.5.0 — `Pagination` drops the page index
+
+The pager rendered a range AND a page index — `16–30 of 45` beside `Page 2 of 3`. Both answer
+"where am I", and the second enables no decision the first does not: how much is left is in the
+total, and whether this is the end is in the disabled arrow. The index is gone; the range is the
+whole label.
+
+**`PaginationLabels.pageWithTotal` and `.page` are removed.** Delete them from any `labels` object
+— every other field is unchanged, so that is the whole edit.
+
+```tsx
+// before
+labels={{ rangeWithTotal: (s, e, t) => `${s}–${e} trên ${t}`,
+          pageWithTotal: (p, n) => `Trang ${p} / ${n}`, page: (p) => `Trang ${p}`,
+          previous: "Trước", next: "Sau" }}
+// after
+labels={{ rangeWithTotal: (s, e, t) => `${s}–${e} trên ${t}`, previous: "Trước", next: "Sau" }}
+```
+
+Not breaking, but do it in the same pass: the range is now the register's only statement of the
+total, so a `Table` paired with the pager takes **`counted`** instead of `count`. Left as `count`,
+the matched total prints twice a few rows apart.
+
+## 44.4.0 — `MemberChip`'s `marker` is gone
+
+A minor that broke a type, recorded here under its exact version rather than held
+for a major: `marker` existed for one release, had a single consumer inside the
+kit, and underlined the chip's name to say "this opens something".
+
+Delete the prop. A chip that opens something is a `MemberPeek`, which now carries
+its own affordance through the trigger's control-band surface — the underline was
+decorating the text to describe the container.
+
+```tsx
+// before
+<MemberChip name={m.name} marker />
+
+// after
+<MemberPeek name={m.name} identity={m.email} groups={m.groups} />
+```
+
+A chip carrying `secondary` also takes a larger mark now (`lg` rather than the
+requested `md`), because two lines of text stand taller than a 28px avatar. Single
+-line chips are unchanged. Nothing to do — but a layout that hard-coded 28px
+beside a two-line chip will need the number.
+
 ## 44.0.0 — `Finding` is horizontal, and `FindingComparison` is gone
 
 `Finding` stacked six blocks — badge, title, detail, a labelled row per side, a hairline, the

package/docs/catalog.md

@@ -1295,9 +1295,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   reference is a FIELD, not a section — one pointer to one other row never earns a heading
   and a rail entry. Worked example: [`tpl_record`](../examples/tpl_record.tsx) § General
   (customer) and its Transport parties.
-- **`peek`** — `Peek`: drill-down for inline references — press a name/id where it appears
-  and get its details in an anchored popover, without leaving the screen; keep the content a
-  summary with ONE action to the full record.
+- **`peek`** — `Peek`: drill-down for a reference — press a name/id where it appears and get its
+  details in an anchored popover, without leaving the screen; keep the content a summary with ONE
+  action to the full record. **`variant` picks the register the TRIGGER sits in, and getting it
+  wrong is visible:** `text` (default) boxes the child at the 32px chip scale and bleeds the extra
+  height back out, so a reference inside a line of reading never grows that line; `control` takes
+  the full `CONTROL_HEIGHT` band and the control radius, for a token that is a control-band citizen
+  — anything built on `MemberChip`, whose `md` avatar is sized to `CONTROL_CONTENT_HEIGHT` for
+  exactly that. On the wrong one a chip under-fills the band and stands a different height from the
+  same chip un-peeked beside it. The horizontal bleed is common to both, so a peekable token keeps
+  the surface's left edge.
 
 ### Lists, tables & registers
 
@@ -1359,7 +1366,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`data_grid`** — `DataGrid` + `gridRowStyle`: the inline-managed grouped table (see
   [Tabular data](#tabular-data--pick-by-scale--intent)); `labels` localizes the sort-header
   a11y via `SortHeaderLabels`.
-- **`pagination`** — `Pagination` (+ `PaginationLabels`): the register's pager.
+- **`pagination`** — `Pagination` (+ `PaginationLabels`): the register's pager — a range and two
+  arrows, no page index. ONE per register, ABOVE the rows on the `SummaryLine` row; its range is
+  the register's count (pair with `Table` `counted`), and `onPageChange` owes a scroll reset the
+  control cannot do itself — see [composition.md](./composition.md) §register.
 - **`column_filter`** — `ColumnFilter` + `columnFilterToConditions` +
   `isColumnFilterActive` + `columnFilterSummary`: the typed per-column filter pill; for a
   register filtering on several columns.

package/docs/composition.md

@@ -587,8 +587,41 @@ hook (`@lotics/ui/use_selection`: `selected` / `has` / `count` / `toggle` / `set
 `allSelected` / `indeterminate` / `clear`) — gating which rows CAN be ticked stays with you: pass
 only the selectable ids to `setAll`/`allSelected`/`indeterminate` (a non-selectable row gets a
 disabled checkbox, keeping the gutter aligned). Selection persists across pages, so `count` is the
-running total. `tpl_item_list` is the reference. Paginate OUTSIDE (slice + `Pagination` in the
-`CardFooter`).
+running total. `tpl_item_list` is the reference. Paginate OUTSIDE (slice + `Pagination`).
+
+**A paginated register owes the reader a scroll reset, and it is not the pager's to give.** Putting
+the pager under the rows is inherited from full page loads, where the browser reset the scroll for
+free; an SPA swaps the rows under a viewport that does not move, so paging from the bottom lands on
+the LAST rows of the next page with its first ones already scrolled past. Every control that changes
+WHICH rows are on screen owes the same reset — page, tab, search, sort, each filter — so route them
+all through ONE function that moves the window and scrolls (`goToPage` / `resetPaging` in
+`tpl_item_list`), never a `setPage(0)` at each call site that also has to remember to scroll.
+
+**ONE pager, ABOVE the rows.** Once the reset returns the viewport to the top on every press, the
+top is where the reader's cursor already is. A second copy under the rows is the same state said
+twice, and two identical clusters of arrows read as two controls.
+
+**Put it on the `SummaryLine` row, not a row of its own** — summary at `flex: 1`, pager sized to its
+content, the row aligned `flex-start` so the arrows stay on the summary's FIRST line when it wraps.
+Both describe the window the toolbar just set (what matched, and which slice is on screen), so they
+are one line. A pager given its own row is a small cluster against a mostly empty band — measure it
+before believing the row is needed; a four-item summary and a full pager leave a quarter of a
+1000px band spare.
+
+Never hand `Pagination` the full width with an empty left slot. It gives its range `flex: 1` so a
+band whose left slot HOLDS something pushes the arrows to the far edge; with nothing there, that
+same rule strands the range hundreds of pixels from the arrows it belongs to — two halves of one
+control reading as two unrelated things on a line.
+
+**The pager's range IS the register's count** (`16–30 of 45`), so pair it with `Table` `counted`,
+never `count` — the latter prints the matched total again a few rows below, and one number in two
+places is two numbers that can disagree. Row totals beside the pager go the same way when a
+`SummaryLine` above already states them.
+
+There is deliberately no page index. `Page 2 of 3` beside `16–30 of 45` answers the same question a
+second way and enables no decision the range does not — how much is left is in the total, whether
+this is the end is in the disabled arrow. A control that is reached for rarely (a register built
+around search and filters is meant to be NARROWED, not paged) earns one label, not two.
 
 Right-hand columns align only if every trailing element is FIXED-width — give each trailing action
 a fixed `width`, so amount/status columns don't jitter.

package/docs/reviewing.md

@@ -419,6 +419,20 @@ is the usual cause.
 Note the RN-Web trap: once a `Text` contains a nested pressable, `numberOfLines` degrades to bare
 `overflow: hidden` and loses the ellipsis.
 
+### Measure INK, not the box — a stretched label hides the gap it sits in
+
+```js
+// getBoundingClientRect on an RN-Web Text returns the DIV, which stretches to
+// its flex slot. Range over the contents to get where the glyphs actually end.
+(sel) => { const rg = document.createRange(); rg.selectNodeContents(document.querySelector(sel)); return rg.getBoundingClientRect(); }
+```
+
+A label inside a `flex: 1` slot measures as wide as the slot, so a box-to-box gap between it and
+its neighbour reads as the container's `gap` — 12px — while the reader sees hundreds of pixels of
+void between the last glyph and the next element. Any gap RATIO taken across a stretching text is
+wrong in the reassuring direction. Use this whenever one side of a measured gap is text that could
+be filling a flex slot rather than sizing to its content.
+
 ### Grouping — is one `gap` flattening the hierarchy?
 
 ```js

package/examples/tpl_item_list.tsx

@@ -159,6 +159,34 @@ const HO_SO: HoSo[] = [
   { ma: "RC-2026-0061", binhLuan: 1, khach: "Harbor Industries", dienThoai: "(555) 047-5829", trangThai: "dangxuly", phi: 6_800_000, daThu: true, ngayThu: "11/06", ngayNhan: "10/06", phuTrach: "Maria Lopez" },
   { ma: "RC-2026-0062", binhLuan: 0, khach: "Grace Holloway", dienThoai: "(555) 826-3050", trangThai: "hoantat", phi: 3_100_000, daThu: true, ngayThu: "05/06", ngayNhan: "31/05", phuTrach: "David Park" },
   { ma: "RC-2026-0063", binhLuan: 3, khach: "Olivia Manning", dienThoai: "(555) 631-2904", trangThai: "dangxuly", phi: 1_200_000, daThu: false, ngayNhan: "11/06", phuTrach: "Sarah Chen" },
+  // The book runs past one SCREEN on purpose, not just past one page. A register
+  // whose page fits the viewport cannot exhibit the defect the paging controls
+  // below are shaped around — the reader never has to scroll, so it never
+  // matters where the viewport is left when the rows change. This example ran on
+  // 23 records at 8 a page for exactly that reason, and the reset was missing
+  // from the reference the whole time.
+  { ma: "RC-2026-0064", binhLuan: 0, khach: "Marcus Webb", dienThoai: "(555) 318-7742", trangThai: "hoantat", phi: 2_500_000, daThu: true, ngayThu: "07/06", ngayNhan: "01/06", phuTrach: "David Park" },
+  { ma: "RC-2026-0065", binhLuan: 2, khach: "Ironwood Textiles", dienThoai: "(555) 924-6018", trangThai: "dangxuly", phi: 5_600_000, daThu: false, ngayNhan: "12/06", phuTrach: "Maria Lopez" },
+  { ma: "RC-2026-0066", binhLuan: 0, khach: "Helen Vargas", dienThoai: "(555) 673-2295", trangThai: "chobosung", phi: 1_800_000, daThu: true, ngayThu: "11/06", ngayNhan: "10/06", phuTrach: "Sarah Chen" },
+  { ma: "RC-2026-0067", binhLuan: 4, khach: "Peter Nakamura", dienThoai: "(555) 405-8830", trangThai: "dangxuly", phi: 3_100_000, daThu: true, ngayThu: "12/06", ngayNhan: "11/06", phuTrach: "James Walker" },
+  { ma: "RC-2026-0068", binhLuan: 0, khach: "Redstone Millwork", dienThoai: "(555) 217-5546", trangThai: "hoantat", phi: 6_800_000, daThu: true, ngayThu: "04/06", ngayNhan: "30/05", phuTrach: "David Park" },
+  { ma: "RC-2026-0069", binhLuan: 1, khach: "Sandra Piper", dienThoai: "(555) 860-3971", trangThai: "dangxuly", phi: 1_200_000, daThu: false, ngayNhan: "12/06", phuTrach: "Maria Lopez" },
+  { ma: "RC-2026-0070", binhLuan: 0, khach: "Owen Fitzgerald", dienThoai: "(555) 592-1487", trangThai: "chobosung", phi: 2_500_000, daThu: false, ngayNhan: "13/06", phuTrach: "Sarah Chen" },
+  { ma: "RC-2026-0071", binhLuan: 3, khach: "Lakeshore Dairy", dienThoai: "(555) 736-9204", trangThai: "hoantat", phi: 4_200_000, daThu: true, ngayThu: "02/06", ngayNhan: "27/05", phuTrach: "James Walker" },
+  { ma: "RC-2026-0072", binhLuan: 0, khach: "Deborah Quinn", dienThoai: "(555) 148-6673", trangThai: "dangxuly", phi: 1_800_000, daThu: true, ngayThu: "13/06", ngayNhan: "12/06", phuTrach: "David Park" },
+  { ma: "RC-2026-0073", binhLuan: 2, khach: "Vincent Osei", dienThoai: "(555) 389-2015", trangThai: "chobosung", phi: 3_100_000, daThu: false, ngayNhan: "13/06", phuTrach: "Maria Lopez" },
+  { ma: "RC-2026-0074", binhLuan: 0, khach: "Pinehill Ceramics", dienThoai: "(555) 651-4738", trangThai: "hoantat", phi: 5_600_000, daThu: true, ngayThu: "06/06", ngayNhan: "31/05", phuTrach: "Sarah Chen" },
+  { ma: "RC-2026-0075", binhLuan: 1, khach: "Alan Whitcombe", dienThoai: "(555) 902-8564", trangThai: "dangxuly", phi: 2_500_000, daThu: false, ngayNhan: "14/06", phuTrach: "James Walker" },
+  { ma: "RC-2026-0076", binhLuan: 0, khach: "Priya Raghavan", dienThoai: "(555) 473-1290", trangThai: "dangxuly", phi: 6_800_000, daThu: true, ngayThu: "14/06", ngayNhan: "13/06", phuTrach: "David Park" },
+  { ma: "RC-2026-0077", binhLuan: 5, khach: "Fairview Optics", dienThoai: "(555) 260-7451", trangThai: "chobosung", phi: 1_200_000, daThu: false, ngayNhan: "14/06", phuTrach: "Maria Lopez" },
+  { ma: "RC-2026-0078", binhLuan: 0, khach: "Gregory Salazar", dienThoai: "(555) 815-3607", trangThai: "hoantat", phi: 3_100_000, daThu: true, ngayThu: "03/06", ngayNhan: "29/05", phuTrach: "Sarah Chen" },
+  { ma: "RC-2026-0079", binhLuan: 2, khach: "Tessa Lindqvist", dienThoai: "(555) 547-9382", trangThai: "dangxuly", phi: 4_200_000, daThu: true, ngayThu: "15/06", ngayNhan: "14/06", phuTrach: "James Walker" },
+  { ma: "RC-2026-0080", binhLuan: 0, khach: "Copperfield Tools", dienThoai: "(555) 031-6825", trangThai: "chobosung", phi: 1_800_000, daThu: false, ngayNhan: "15/06", phuTrach: "David Park" },
+  { ma: "RC-2026-0081", binhLuan: 1, khach: "Naomi Ferrell", dienThoai: "(555) 794-2158", trangThai: "hoantat", phi: 2_500_000, daThu: true, ngayThu: "05/06", ngayNhan: "01/06", phuTrach: "Maria Lopez" },
+  { ma: "RC-2026-0082", binhLuan: 0, khach: "Bridgeport Marine", dienThoai: "(555) 368-5093", trangThai: "dangxuly", phi: 5_600_000, daThu: false, ngayNhan: "16/06", phuTrach: "Sarah Chen" },
+  { ma: "RC-2026-0083", binhLuan: 3, khach: "Ethan Castellanos", dienThoai: "(555) 620-4716", trangThai: "dangxuly", phi: 1_200_000, daThu: true, ngayThu: "16/06", ngayNhan: "15/06", phuTrach: "James Walker" },
+  { ma: "RC-2026-0084", binhLuan: 0, khach: "Willow Creek Farms", dienThoai: "(555) 187-9340", trangThai: "chobosung", phi: 3_100_000, daThu: false, ngayNhan: "16/06", phuTrach: "David Park" },
+  { ma: "RC-2026-0085", binhLuan: 2, khach: "Simone Beaufort", dienThoai: "(555) 452-8671", trangThai: "hoantat", phi: 6_800_000, daThu: true, ngayThu: "07/06", ngayNhan: "02/06", phuTrach: "Maria Lopez" },
 ];
 
 const TABS: { value: Tab; label: string }[] = [
@@ -168,7 +196,9 @@ const TABS: { value: Tab; label: string }[] = [
   { value: "hoantat", label: "Complete" },
 ];
 
-const PAGE_SIZE = 8;
+// Fifteen rows at the register's rhythm is taller than the viewport, which is
+// the point: paging only has ergonomics once a page is something you SCROLL.
+const PAGE_SIZE = 15;
 
 // Distinct case handlers — the secondary filter dimension (a multi-select FilterChip).
 const ASSIGNEES = [...new Set(HO_SO.map((r) => r.phuTrach))].map((n) => ({ label: n, value: n }));
@@ -1041,7 +1071,34 @@ export function TplItemList() {
   // The register rows are state: the create dialog PREPENDS a real row and
   // opens its drawer — create-then-refine.
   const [rows, setRows] = useState<HoSo[]>(HO_SO);
-  const nextMa = useRef(64);
+  // Past the LAST seeded code, not past the old one — a created row that reuses
+  // an existing `ma` collides on the register's key and on every lookup by code.
+  const nextMa = useRef(86);
+
+  /** The page's scroll container, so a control that changes the rows can put the
+   *  reader back at the first of them. */
+  const scrollRef = useRef<ScrollView>(null);
+
+  /**
+   * Move the window, and return the viewport to the top of it.
+   *
+   * The scroll is HALF the act, not a courtesy on top of it. Bottom pagination
+   * is inherited from full page loads, where the browser reset the scroll for
+   * free; an SPA swaps the rows under a viewport that does not move, so paging
+   * from the bottom lands the reader on the LAST rows of the next page with its
+   * first ones already behind them.
+   *
+   * EVERY control that changes which rows are on screen goes through here —
+   * paging, tabs, search, sort, each filter — rather than each one calling
+   * `setPage(0)` and remembering the scroll. That list is the reason this is one
+   * function: nine call sites each responsible for two things is nine chances to
+   * do one of them, and the one that gets forgotten fails silently.
+   */
+  const goToPage = (p: number) => {
+    setPage(p);
+    scrollRef.current?.scrollTo({ y: 0, animated: false });
+  };
+  const resetPaging = () => goToPage(0);
   const addRow = (khach: string, dienThoai: string, phi: number): string => {
     const now = new Date();
     const ma = `RC-2026-${String(nextMa.current++).padStart(4, "0")}`;
@@ -1067,7 +1124,7 @@ export function TplItemList() {
     setAssignee([]);
     setFeeStatus(null);
     setSort(null);
-    setPage(0);
+    resetPaging();
   };
   const createRecord = (khach: string, dienThoai: string, phi: number) => {
     const ma = addRow(khach, dienThoai, phi);
@@ -1101,16 +1158,16 @@ export function TplItemList() {
   // meaningless under the new one.
   const chonTab = (t: Tab) => {
     setTab(t);
-    setPage(0);
+    resetPaging();
   };
   const doiTimKiem = (s: string) => {
     setSearch(s);
-    setPage(0);
+    resetPaging();
   };
   // One sort at a time; the third toggle on a column clears it.
   const onSort = (key: string) => {
     setSort(cycleSort(sort, key));
-    setPage(0);
+    resetPaging();
   };
 
   // Search + status tab filter FIRST, then paging over the filtered ordering.
@@ -1140,7 +1197,6 @@ export function TplItemList() {
     : key === "ngayNhan" ? r.ngayNhan.split("/").reverse().join("")
     : r.ma,
   );
-  const tongPhi = filtered.reduce((s, r) => s + r.phi, 0);
   const pageRows = sorted.slice(page * PAGE_SIZE, (page + 1) * PAGE_SIZE);
   const hasMore = (page + 1) * PAGE_SIZE < sorted.length;
 
@@ -1171,7 +1227,7 @@ export function TplItemList() {
         on top); the accent ring frames the page on drag. A real app opts in
         per-app — this page is the reference shape. */}
     <FileDropTarget onFiles={openIntakeSeeded} paste style={{ flex: 1 }}>
-    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView ref={scrollRef} style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 1040, alignSelf: "center", gap: 16 }}>
         {/* The page band — the screen's TYPE ANCHOR before it is a label. Without
             it this page's largest text is 16px against a 12px floor, and a 1.33x
@@ -1208,7 +1264,7 @@ export function TplItemList() {
             <FilterChip
               label="Assignee"
               summary={assigneeSummary}
-              onClear={() => { setAssignee([]); setPage(0); }}
+              onClear={() => { setAssignee([]); resetPaging(); }}
               clearLabel="Clear assignee filter"
             >
               <OptionList
@@ -1216,7 +1272,7 @@ export function TplItemList() {
                 multi
                 options={ASSIGNEES}
                 value={assignee}
-                onValueChange={(v) => { setAssignee(v); setPage(0); }}
+                onValueChange={(v) => { setAssignee(v); resetPaging(); }}
               />
             </FilterChip>
             {/* Single-select sibling — the render-prop `close` shuts the popover on
@@ -1224,7 +1280,7 @@ export function TplItemList() {
             <FilterChip
               label="Payment"
               summary={feeStatus === "paid" ? "Paid" : feeStatus === "unpaid" ? "Unpaid" : undefined}
-              onClear={() => { setFeeStatus(null); setPage(0); }}
+              onClear={() => { setFeeStatus(null); resetPaging(); }}
               clearLabel="Clear payment filter"
             >
               {({ close }) => (
@@ -1232,7 +1288,7 @@ export function TplItemList() {
                   search={{ mode: "none" }}
                   options={[{ value: "paid", label: "Paid" }, { value: "unpaid", label: "Unpaid" }]}
                   value={feeStatus}
-                  onValueChange={(v) => { setFeeStatus(v); setPage(0); }}
+                  onValueChange={(v) => { setFeeStatus(v); resetPaging(); }}
                   onRequestClose={close}
                 />
               )}
@@ -1243,7 +1299,7 @@ export function TplItemList() {
             <ColumnFilter
               column={{ key: "phi", label: "Fee", type: "number" }}
               value={feeAmount}
-              onChange={(v) => { setFeeAmount(v); setPage(0); }}
+              onChange={(v) => { setFeeAmount(v); resetPaging(); }}
             />
           </View>
           {/* the intake TRIGGER — the register's whole-surface drop/paste opens
@@ -1262,25 +1318,66 @@ export function TplItemList() {
             It is not a page-band subtitle for the same reason. A subtitle
             describes the screen; these describe the QUERY, and the query is what
             the toolbar above just wrote. */}
-        <SummaryLine
-          items={[
-            { label: "processing", value: dem("dangxuly") },
-            { label: "awaiting docs", value: dem("chobosung"), tone: "warning", info: "Records waiting on customer paperwork — they aren't complete, so they can't be ticked for export until the docs arrive." },
-            { label: "complete", value: dem("hoantat") },
-            { label: "fees collected", value: phiDaThu, format: "currency", compact: true },
-          ]}
-        />
-
-        {/* the register — eyebrow band (Table header) → list rows → totals + paging */}
+        {/* THE SUMMARY ROW IS THE PAGING ROW. Both describe the window the
+            toolbar above just set — what matched, and which slice of it is on
+            screen — so they are one line, not two.
+
+            PAGING SITS ABOVE THE ROWS, and there is only one of it. Under them is
+            where it has always gone, and that is inherited from full page loads:
+            the browser reset the scroll, so a reader who pressed Next at the
+            bottom arrived at the top of the next page for free. An SPA swaps the
+            rows under a viewport that does not move, so the same press now lands
+            on that page's LAST rows with its first ones already scrolled past.
+            `goToPage` restores the reset — and once the viewport returns here on
+            every press, here is where the control should be: under the reader's
+            cursor, not a page-height below it. A second copy at the bottom would
+            be the same state said twice.
+
+            It carries the RANGE and nothing else. The totals that used to ride
+            the old footer (`45 records, ₫X in fees`) said what this summary
+            already says, and `Table`'s own `count` prints the matched total in
+            the eyebrow below.
+
+            The pager sizes to its CONTENT and the summary takes `flex: 1`.
+            Reversed — the pager handed the full width — its own `flex: 1` range
+            stretches and strands the range hundreds of pixels from the arrows it
+            belongs to, two halves of one control reading as two things. Given a
+            row of its own it read worse still: 236px of control against 778px of
+            nothing. `flex-start` keeps the arrows on the summary's FIRST line
+            when the summary wraps at a narrow width. */}
+        <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 24 }}>
+          <View style={{ flex: 1, minWidth: 0 }}>
+            <SummaryLine
+              items={[
+                { label: "processing", value: dem("dangxuly") },
+                { label: "awaiting docs", value: dem("chobosung"), tone: "warning", info: "Records waiting on customer paperwork — they aren't complete, so they can't be ticked for export until the docs arrive." },
+                { label: "complete", value: dem("hoantat") },
+                { label: "fees collected", value: phiDaThu, format: "currency", compact: true },
+              ]}
+            />
+          </View>
+          <Pagination
+            page={page}
+            pageSize={PAGE_SIZE}
+            rowCount={pageRows.length}
+            hasMore={hasMore}
+            total={filtered.length}
+            onPageChange={goToPage}
+          />
+        </View>
+
+        {/* the register — eyebrow band (Table header) → list rows */}
         <View>
-          {/* THE COUNTED REGISTER. `count` is what MATCHED, not what this page
-              shows — the reader's "how many" survives paging — and each row's
-              `ordinal` continues across pages rather than restarting at 1, so the
-              last row of page 2 reads 100 under a header that says 100. */}
+          {/* THE COUNTED REGISTER — `counted`, not `count`, because the PAGER
+              states the total now (`16–30 of 45`) and a number printed twice a
+              few rows apart is two numbers that can disagree. `counted` keeps the
+              ordinal gutter reserved and leaves the figure to the row that owns
+              it. Each row's `ordinal` still continues across pages rather than
+              restarting at 1, so the last row of page 2 reads 30, not 15. */}
           <Table
             columns={COLUMNS}
             leading={24}
-            count={filtered.length}
+            counted
             trailing={132}
             sort={sort}
             onSort={onSort}
@@ -1304,25 +1401,6 @@ export function TplItemList() {
               <EmptyState message="No matching records" hint="Try another keyword or switch status" />
             </>
           ) : null}
-          {/* NOT `CardFooter` — that is a Card PART, and its 20px is the card's
-              interior gutter. There is no card here, so it put the totals 20px
-              right of the register's own rows and of the toolbar above them.
-              A bare table's footer is a divider and a row; borrowing furniture
-              from a container that is not there is what put it out of true. */}
-          <Divider />
-          <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 12 }}>
-            <Text size="sm" color="muted" tabular style={{ flex: 1 }}>
-              {`${filtered.length} records, ${formatMoney(tongPhi)} in fees`}
-            </Text>
-            <Pagination
-              page={page}
-              pageSize={PAGE_SIZE}
-              rowCount={pageRows.length}
-              hasMore={hasMore}
-              total={filtered.length}
-              onPageChange={setPage}
-            />
-          </View>
         </View>
       </View>
     </ScrollView>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.3.0",
+  "version": "44.5.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/locale.tsx

@@ -265,8 +265,6 @@ export const en: LoticsLocale = {
   pagination: {
     rangeWithTotal: (start, end, total) => `${start}–${end} of ${total.toLocaleString()}`,
     range: (start, end) => `${start}–${end}`,
-    pageWithTotal: (page, pageCount) => `Page ${page} of ${pageCount}`,
-    page: (page) => `Page ${page}`,
     previous: "Previous",
     next: "Next",
   },
@@ -445,8 +443,6 @@ export const vi: LoticsLocale = {
   pagination: {
     rangeWithTotal: (start, end, total) => `${start}–${end} trên ${total.toLocaleString("vi-VN")}`,
     range: (start, end) => `${start}–${end}`,
-    pageWithTotal: (page, pageCount) => `Trang ${page} / ${pageCount}`,
-    page: (page) => `Trang ${page}`,
     previous: "Trang trước",
     next: "Trang sau",
   },

package/src/member_chip.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import { View, StyleSheet, StyleProp, ViewStyle } from "react-native";
 import { Avatar } from "./avatar";
 import { Text } from "./text";
-import type { AvatarSize } from "./avatar_size";
+import { AVATAR_PX, type AvatarSize } from "./avatar_size";
 import { useLoticsLocale } from "./locale";
 
 /**
@@ -34,22 +34,6 @@ interface MemberChipProps {
    *  than as a current assignment. The chip keeps its height, because its usual
    *  home is a fixed row: this is a colour change, never an extra line. */
   inactive?: boolean;
-  /**
-   * This chip is a DOOR — something opens when it is pressed. Underlines the
-   * name in neutral ink, the kit's marker for "leads somewhere, and not away"
-   * (see `TextLink` with no `href`).
-   *
-   * It exists because a pressable that paints nothing at rest is text: with no
-   * ground, no border and no underline, its only affordance is a hover wash,
-   * which does not exist on touch and has not happened yet for anyone who has
-   * not already pointed at it. The chip then measures perfectly, carries a real
-   * focus ring, and is never pressed.
-   *
-   * Set it ONLY when the chip itself opens something. A chip inside a row that
-   * navigates must not wear it — the row is the door, and marking the chip
-   * promises a second destination that is not there.
-   */
-  marker?: boolean;
   style?: StyleProp<ViewStyle>;
 }
 
@@ -75,7 +59,6 @@ export function MemberChip({
   secondary,
   size = "md",
   inactive,
-  marker,
   style,
 }: MemberChipProps) {
   // `Avatar` has always taken this word from the pack; the NAME beside it was a
@@ -105,9 +88,20 @@ export function MemberChip({
   // name is not a pair, and leaving it on prose leading keeps every single-line
   // chip — every picker option, every cell — pixel-identical to before.
   const pairLeading = secondary ? ("tight" as const) : undefined;
+  // THE MARK IS NEVER SHORTER THAN WHAT IT MARKS. Two tight lines measure ~38
+  // at this rung, so beside a 28px avatar the text overflowed the mark by ten
+  // pixels and the person's face read as a decoration hung off their name.
+  // Tight leading is already the floor — 38 is as short as the pair gets — so
+  // the fix is the MARK, not the type: a chip carrying a supporting line is a
+  // taller object, and it takes the rung that covers the stack. That rung is
+  // `lg` = `CONTROL_HEIGHT`, which is the band a two-line chip belongs in
+  // anyway. A caller already above it (`xl`, a profile header) keeps what it
+  // asked for.
+  const markSize: AvatarSize =
+    secondary && AVATAR_PX[size] < AVATAR_PX.lg ? "lg" : size;
   return (
     <View style={[styles.row, style]}>
-      <Avatar size={size} name={displayName} source={image ? { uri: image } : undefined} />
+      <Avatar size={markSize} name={displayName} source={image ? { uri: image } : undefined} />
       <View style={styles.text}>
         <Text
           userSelect="none"
@@ -118,10 +112,6 @@ export function MemberChip({
           // supporting line except by colour.
           weight="medium"
           leading={pairLeading}
-          // NEUTRAL underline, never the navigation blue: pressing this opens
-          // the person in place rather than travelling to them, and blue
-          // underlined text promises a destination.
-          decoration={marker ? "underline" : undefined}
           color={inactive ? "zinc-500" : undefined}
           numberOfLines={1}
         >

package/src/member_peek.tsx

@@ -72,6 +72,12 @@ export function MemberPeek(props: MemberPeekProps) {
     <Peek
       accessibilityLabel={accessibilityLabel ?? words.profile(displayName)}
       content={<MemberProfileCard {...card} />}
+      // A chip is a CONTROL-BAND citizen — `md` is `CONTROL_CONTENT_HEIGHT`
+      // precisely so it seats in one. On the default `text` register the
+      // trigger boxed it at 32 and bled 4 off each side, so a peeking chip
+      // under-filled the band and stood shorter than the same chip un-peeked
+      // beside it.
+      variant="control"
       side={side}
       align={align}
     >
@@ -81,9 +87,6 @@ export function MemberPeek(props: MemberPeekProps) {
         secondary={secondary}
         size={size}
         inactive={card.inactive}
-        // This chip IS the door — without the marker it paints nothing at rest
-        // and only a pointer already on it would ever learn that.
-        marker
         style={style}
       />
     </Peek>

package/src/pagination.tsx

@@ -16,10 +16,6 @@ export interface PaginationLabels {
   rangeWithTotal?: (start: number, end: number, total: number) => string;
   /** Range summary without a total. Default `${start}–${end}`. */
   range?: (start: number, end: number) => string;
-  /** Page indicator with a known total. Default `Page ${page} of ${pageCount}`. */
-  pageWithTotal?: (page: number, pageCount: number) => string;
-  /** Page indicator without a total. Default `Page ${page}`. */
-  page?: (page: number) => string;
   /** Previous-page button tooltip. Default "Previous". */
   previous?: string;
   /** Next-page button tooltip. Default "Next". */
@@ -46,11 +42,34 @@ export interface PaginationProps {
 }
 
 /**
- * Pagination control: range summary on the left, page indicator + arrows on the
- * right. A pure control — it owns no border, background, or padding. The
- * container that frames it (a `CardFooter`, a grid footer, a bordered band)
- * supplies the divider and insets, so the same control composes anywhere without
- * doubling up a border.
+ * Pagination control: which rows are on screen, and arrows to change them. A
+ * pure control — it owns no border, background, or padding. The container that
+ * frames it (a summary row, a grid footer, a bordered band) supplies the divider
+ * and insets, so the same control composes anywhere without doubling up a border.
+ *
+ * The range is the WHOLE label. A page index beside it ("Page 2 of 3") answers
+ * the same question a second way and enables no decision the range does not —
+ * how much is left is in the total, and whether this is the end is in the
+ * disabled arrow. It was rendered here once and cut.
+ *
+ * The range is also the register's COUNT. Pass `counted` rather than `count` to
+ * a `Table` paired with this, or the matched total is printed twice a few rows
+ * apart.
+ *
+ * **`onPageChange` must also return the viewport to the first row.** This
+ * control cannot do it: the scroll container belongs to the page, not to the
+ * kit. Bottom pagination is a browser-reload-era convention — a full page load
+ * reset the scroll, and that reset is what made it work. An SPA changes the rows
+ * underneath a viewport that does not move, so a reader who pages from the
+ * bottom lands on the LAST rows of the next page and never sees its first ones.
+ * The same is true of every other control that changes which rows are on screen
+ * — a filter, a sort, a search — so the reset belongs to "the window changed",
+ * not to this component's arrows. `tpl_item_list` is the reference.
+ *
+ * ONE per register, ABOVE the rows. Once the reset returns the viewport here on
+ * every press, this is where the reader's cursor already is; a second copy under
+ * the rows is the same state said twice, and two identical clusters of arrows
+ * read as two controls rather than one.
  */
 export function Pagination(props: PaginationProps): React.ReactNode {
   const { page, pageSize, rowCount, hasMore, total, loading, onPageChange, labels } = props;
@@ -65,11 +84,6 @@ export function Pagination(props: PaginationProps): React.ReactNode {
       : (labels?.range ?? loc.range)(start, end)
     : "";
 
-  const pageLabel =
-    total !== undefined
-      ? (labels?.pageWithTotal ?? loc.pageWithTotal)(page + 1, Math.max(1, Math.ceil(total / pageSize)))
-      : (labels?.page ?? loc.page)(page + 1);
-
   return (
     <View style={styles.container}>
       <View style={styles.summary}>
@@ -78,9 +92,6 @@ export function Pagination(props: PaginationProps): React.ReactNode {
         </Text>
       </View>
       <View style={styles.controls}>
-        <Text size="sm" color="zinc-500">
-          {pageLabel}
-        </Text>
         <IconButton
           icon="chevron-left"
           color="secondary"

package/src/peek.tsx

@@ -3,6 +3,7 @@ import { StyleSheet } from "react-native";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { PressableHighlight } from "./pressable_highlight";
+import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 
 export interface PeekProps {
   /** The inline reference that becomes the trigger — a customer name, a
@@ -15,6 +16,27 @@ export interface PeekProps {
   content: ReactNode;
   /** Announced name for the trigger ("Hồ sơ KOMASPEC VIỆT NAM"). */
   accessibilityLabel: string;
+  /**
+   * WHICH REGISTER the trigger sits in — the two surfaces a peek lives on need
+   * different boxes, and picking by taste puts the wrong one on both.
+   *
+   * `text` (default) is a reference INSIDE a line of reading — a customer name
+   * in a sentence, an id in a table cell. It takes the 32px chip register and
+   * bleeds the extra height back out with negative margins, so wrapping a
+   * `Text` never grows the line it sits in.
+   *
+   * `control` is a reference that IS a control-band citizen — anything built on
+   * `MemberChip`, whose `md` avatar is sized to `CONTROL_CONTENT_HEIGHT` for
+   * exactly this. It takes the full `CONTROL_HEIGHT` band and no vertical
+   * bleed, so the token seats where every other control on the surface does
+   * instead of under-filling the band and standing a different height from the
+   * same chip un-peeked beside it.
+   *
+   * The HORIZONTAL bleed is common to both: the trigger's padding must not
+   * shift its content off the surface's left edge, or a peekable token sits 8px
+   * right of the plain one above it.
+   */
+  variant?: "text" | "control";
   side?: PopoverSide;
   align?: PopoverAlign;
 }
@@ -28,7 +50,7 @@ export interface PeekProps {
  * customer names, order ids, member names, linked records.
  */
 export function Peek(props: PeekProps) {
-  const { children, content, accessibilityLabel, side = "bottom", align = "start" } = props;
+  const { children, content, accessibilityLabel, variant = "text", side = "bottom", align = "start" } = props;
   return (
     <Popover side={side} align={align}>
       <PopoverTrigger>
@@ -36,7 +58,7 @@ export function Peek(props: PeekProps) {
           focusRing
           accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
-          style={styles.trigger}
+          style={[styles.trigger, variant === "control" ? styles.triggerControl : null]}
           // 32px visual, 40px touch target (32 + 2×4) — same as IconButton.
           hitSlop={4}
         >
@@ -51,9 +73,9 @@ export function Peek(props: PeekProps) {
 }
 
 const styles = StyleSheet.create({
-  // Inline bleed at the 32px chip register (matches Badge scale, fits inside
-  // text rows without inflating them); negative margins absorb the extra
-  // height so the line's layout never shifts. hitSlop keeps the 40px target.
+  // The `text` register: a 32px chip box (Badge scale) whose extra height is
+  // bled back out with negative margins, so a reference inside a line of
+  // reading never grows that line. hitSlop keeps the 40px touch target.
   trigger: {
     flexDirection: "row",
     alignItems: "center",
@@ -63,6 +85,16 @@ const styles = StyleSheet.create({
     marginHorizontal: -8,
     marginVertical: -4,
   },
+  // The `control` register: the surface's own band. The vertical bleed goes —
+  // a control-band token is SUPPOSED to occupy the band — and the radius joins
+  // every other control's, so a peekable chip corners like the inputs it sits
+  // among rather than like a badge. The horizontal bleed stays, so the token
+  // keeps the left edge (see `variant`).
+  triggerControl: {
+    minHeight: CONTROL_HEIGHT,
+    borderRadius: CONTROL_RADIUS,
+    marginVertical: 0,
+  },
   content: {
     width: 320,
   },