@lotics/ui 47.13.1 → 47.15.0

package/docs/composition.md

@@ -398,6 +398,38 @@ badge. Every period-dependent number MUST follow the selection. Pass `includeTim
 time-of-day matters: the trigger previews the chosen time (locale-aware) and the `labels` prop
 translates the presets, footer buttons, placeholder, and the time-segment editors.
 
+**One field, every grain — a `SegmentedControl` of grains beside it re-adds the mode the field
+removed.** The presets already run day → week → month → quarter → year, and the trigger folds a
+whole period back to its own name ("Tháng 9 năm 2026", "Quý 3 năm 2026", "2026"), so the grain is
+something the reader SETS and READS in one control. Putting *Tháng | Quý | Năm* next to it splits
+one fact across two controls that can disagree — pick "Quý" beside a range of eleven days and the
+screen states a grain nothing on it is computed at.
+
+**A report's comparator is DERIVED from the selected range, never chosen.** "So với kỳ trước" is
+`previousPeriod(value)` from `@lotics/ui/date_filter_presets` — a whole month steps back a whole
+month, a quarter a quarter, a year a year, and anything else steps back by its own length. Feed
+that range to the same query the selection feeds and put the result ON the figure: a
+`KPIStripItem`'s `trend` / `caption`, `Metric`'s `previousValue`, a second `LineChart` series
+(`series` is what makes two periods one chart on one scale), `TrendFooter` under a chart card. A
+second date field, a "compare to" picker or a comparison toggle beside the filter is the same
+mistake in three shapes — it lets a reader select a comparator that is not the period they are
+looking at, and every figure on the screen then answers a question nobody asked. `null` back means
+the range is open-ended: show the figure with no delta rather than inventing one.
+
+**A period still RUNNING is compared TO DATE — `periodToDate(value, now)`.** Six days of this
+month set beside a whole previous month reads as a collapse that never happened, and it lands on
+the first figure anyone looks at, so both sides are cut to the days that have elapsed: it hands
+back the selection ending today, the comparator cut to the same count from its own first day
+(clamped to that period's end, so 30 days of March meet all 28 of February), and
+`running` / `elapsedDays` / `totalDays` for the caption that says how far in the reader is. A
+closed period keeps both sides whole.
+
+**A surface keyed by a whole month takes a `MonthStepper`, not a range field.** A monthly plan, a
+roster, a month's attendance cannot take "the 3rd to the 19th", so a range control offers moves
+that do not exist. The stepper's bound is its contract: pass `max` as this month on any surface
+about what has happened, or the reader walks into a month nobody has planned and reads it as a
+plan. Two hand-rolled steppers in one app disagreed on exactly this.
+
 ## A calendar answers WHEN — and only when the position on a timeline is the question
 
 A calendar is not a prettier register. Reach for one when the reader's question is *when does
@@ -406,6 +438,19 @@ at the same time. When the question is *which of these needs me*, the answer is
 a date column, and a calendar buries it: thirty rows of a table are scannable, thirty rows
 scattered across a month grid are a search.
 
+**A weekly PATTERN with no dates is a `Timetable`, not a calendar.** Which days a departure
+runs, which hours a lane is open: nothing has a date to be placed on, so a week view pages
+between identical weeks and draws the same four facts seven times. Rows are the slots, the
+fixed positions are columns named once in the header, today is a tinted column, and a mark is
+its own editor.
+
+**A subject-by-date sheet of STATES is a `StateMatrix`.** Who was in on which day, which vehicle
+ran on the 14th: the reader compares a subject against a date and reads a category, not a
+number. Rows are the subjects with a pinned name and figure, the dates are columns named once,
+a glyph per cell says the state, and the legend is derived from the same list the cells draw
+from. A calendar would scatter thirty subjects across a month grid; a `Matrix` would put a
+number where a blank means "nothing was due".
+
 Three rules follow from that, and each of them is about legibility rather than taste.
 
 **A grid is unreadable in two directions.** Seven equal columns need roughly 110px each to hold
@@ -647,6 +692,11 @@ form: per container, collect its own `row-gap` and the **max `row-gap` of its vi
   different quantity. `ChargeLines` takes `formatMoney` and `formatQuantity` for this reason, both
   at the BAND so two lines cannot disagree, and threads them to the locked value and the inline
   editor alike. Any new component that displays a caller's number owes the same hook.
+- **An axis over whole things has no half.** A count of vehicles, contracts or trips cannot be
+  0,5, so gridlines at `0 · 0,5 · 1 · 1,5 · 2` state something false about the SUBJECT rather than
+  about the layout, and they appear exactly where the numbers are smallest — a five-tick target
+  starts reaching below the unit at a maximum of two. The kit's charts derive this from the values
+  themselves; anywhere you draw a scale by hand, the step comes from what the data is made of.
 - **A column states its unit ONCE — which is only possible if it holds ONE unit.** State it in the
   header band and leave the cells bare. The corollary is the one that bites: a label/value list
   whose rows are a date range, a sum of money and a COUNT has no single unit to state, so each
@@ -667,7 +717,8 @@ form: per container, collect its own `row-gap` and the **max `row-gap` of its vi
 | `medium` | `22 thg 5, 2026` |
 | `long` | `22 tháng 5, 2026` |
 | `dayMonth` | `22 thg 5` |
-| `monthYear` | `Tháng 5 2026` |
+| `monthYear` | `Tháng 5 năm 2026` |
+| `quarterYear` | `Quý 2 năm 2026` (`Q2 2026` outside Vietnamese) |
 
   **`time: true` is orthogonal** — it prepends the 24h time to ANY style (`14:30 22/05/2026`,
   `14:30 22 tháng 5, 2026`); `compact` drops the year on the `date` style; `emptyLabel` renders
@@ -1123,6 +1174,15 @@ When a region genuinely must sit beside the list (a source/remainder summary, a
 make it a TOP summary header or move it into a `Popover`/sheet at the decision point — not a
 standing column.
 
+**A screen is cut by the JOB, never by the subject.** Two jobs done at different hours — watching
+exceptions all day, signing a count once at its end — are two surfaces even when both are about
+the same day; a screen that stacks them puts the act done once under the list read least, and the
+one fact they share travels as a single line. The work screen opens on what the person DOES, then
+what they look up; an end-of-period act sits with the book it lands in — the register of periods
+above, the picked period's form below. A working screen summarises with `SummaryLine`; `KPIStrip`
+is a dashboard band. And a screen keyed by a period is named for the period it shows ("Trong
+ngày"), never for the default its filter happens to hold ("Hôm nay").
+
 ## One control radius
 
 Every interactive control (`Button`, the inputs/selects/pickers, `SearchInput`, `MenuButton`,
@@ -1594,6 +1654,19 @@ next step. When the state is already derivable from a neighbour, the badge is a
 fact, free to disagree with the first, and it costs a column on every screen to say what the
 reader already read.
 
+**A state the system DERIVES from an absence is pending until a person confirms it.** No chuyến
+past the slot, no reply past the deadline, no scan past the cut-off: the system can say the thing
+did not happen, never WHY, and the why is the only fact anyone acts on. Label such a row as the
+question ("Chưa xác nhận"), tone it as attention rather than failure, and put the confirming act
+on the row; the verdict word ("Nghỉ") appears only once the reason is on record. Painting the
+derived absence with the verdict spends the register's one alarm colour on the commonest row of
+the morning and accuses a row nobody has looked at yet.
+
+**A strip whose every option shows the same register with fewer rows is a FILTER**, so it is
+`ChipGroup` with counts and `overflow="scroll"`, opening on the partition that owes the act.
+`Tabs` is for sections whose content differs; `PipelineTabs` for stages that change what the
+register under them IS.
+
 The clean discriminator is what the badge would say that the row does not:
 
 - A gate register whose status reads *"paperwork not closed"* keeps its column. No other cell
@@ -1867,7 +1940,7 @@ information.
   first word.** `avatarInitials` takes a name's first (and last) letters, which is right for a
   person and wrong for an ORGANIZATION: an organization's name opens with its legal form, so a
   register of companies marks the same letter on every row — and it is the same failure the derived
-  hue was written to fix, arriving through the glyph instead of the ground. Strip the form from
+  hue was written to fix, arriving through the glyph instead of the ground. Strip the form (`stripLegalForm`, `@lotics/ui/organization_name`) from
   both ends before the name reaches the mark, and use the stripped name for the row's TITLE too:
   whatever eats the first letters of a mark is also eating the first 60px of the column beside it,
   where the words that tell two customers apart fall off the end. The legal name belongs on the
@@ -1904,8 +1977,14 @@ information.
   subject. Keep the ordinal where order is the thing being EDITED, and then as text in the
   supporting line — never as the mark. A surface that needs to state position has its own readout
   (a drawer's `3/8`, a stepper's rail).
-- **The rung follows what the row is ABOUT**: `lg` where the entity is the row's subject, `md`
-  where it is one field among columns (see `avatar_size`).
+- **The rung follows what the reader AIMS AT**: `lg` where the mark is the thing the eye lands on
+  — the row's subject, or an ORGANIZATION in its own column, whose logo is what a reader scans a
+  book of movements by. `md` only where the mark is incidental to a value the reader came for (see
+  `avatar_size`). Read as "subject ⇒ `lg`, field column ⇒ `md`" this drew a 28px disc in a carrier
+  column and the register was reported as flat — the same complaint the leading-mark rule above
+  names, arriving through the rung instead of the absence. The budget is the real constraint: `lg`
+  is 12px wider and takes them from the flexible column the name is in, so a column too tight to
+  seat one takes `md` and says so.
 - **A column of faces must not draw an UNBOUNDED audience as faces.** Where a cell answers "who
   can reach this", the commonest state is often *everyone* — and three sampled avatars assert
   something false about it. Draw the

package/docs/data_entry.md

@@ -335,6 +335,15 @@ in a `DataGrid`), where a cell varying with its data breaks the row rhythm the g
 on a record surface; reserve in a table. Worked both ways in `dev/pages/inline_edit.tsx`
 § Multiline — the same value in a reserved field and a grown one, side by side.
 
+**In a table the WIDTH is reserved too, and by the CELL — the editor never states its own.** An
+inline editor is sized by what it holds: at rest a chip around the formatted value, focused a real
+input at its natural width. Put one in a `TableCell` with nothing bounding it and the two states
+are different boxes — the focused one grows sideways out of its column, over the neighbour, and
+takes the row's height with it, on the one row somebody is working in. So wrap it in a `View` with
+a fixed `width`, one number for the column, and both states land on the same rectangle.
+(`NumberInput` already refuses to state a width for exactly this reason — see its `width: "100%"`
+comment — but "fills its container" only bounds anything once a container has a size.)
+
 ### The row stack — `DetailTable` + `DetailRow`
 
 A STACK of rows lives in a `DetailTable` (label, value laid out like a TABLE: `labelWidth` /
@@ -765,12 +774,10 @@ chronological order; each phase owns ITS OWN fee rows + phase total (the invoice
 level up — money never reads as one pot); each closes with a SEQUENTIAL confirm gate that names
 its blockers ("Confirm check-in first."). The header status chip carries the phase.
 
-A LONG record surface pairs with a LEFT OUTLINE RAIL — `MenuButton` items + `useSectionNav`
-(scroll-spy: jump to a section, the highlight follows the scroll); the active item is
-`current={activeKey === key}`, the NAVIGATION state, never `selected`, which is listbox
-selection. On narrow containers the rail
-becomes a PINNED bar naming the current section that opens a full-page section-picker `Modal`. A
-per-phase dot on a rail item carries its confirmed state. A direction that is a TYPE (one record
+A LONG record surface pairs with a LEFT OUTLINE RAIL — `SectionNav` for the chrome,
+`useSectionNav` for the scroll-spy that feeds it `activeKey` and `jumpTo`. On narrow containers
+the same list collapses to a pinned bar naming the current section, which opens it as a picker
+anchored to that bar. A per-phase `issue` dot on an item carries its confirmed state. A direction that is a TYPE (one record
 per event) is instead a discriminator chosen ONCE at creation — a `SegmentedControl` in the
 create step, never a toggle on the record.
 

package/docs/reviewing.md

@@ -333,6 +333,13 @@ defect, so finding it on one panel is a reason to sweep the siblings.
   that drifts across the track means each one was offset by a guess at its own width.
 - **A row beat belongs to the PAGE** — collect every row primitive's height on one screen before
   calling any of them right.
+- **A bar's TRACK, not its card.** A chart whose label column and value column are FIXED spends
+  those pixels first, so a narrow pane leaves the plot itself with almost nothing — and a bar has
+  a minimum width, so every row draws the same short stub and the picture states that all the
+  entities are equal. It measures perfectly: the card is there, the rows are there, the figures
+  are right. Collect the track's width and each bar's, per row: a set of identical bar widths
+  under differing values is the finding, and so is any track under about a third of the card.
+  Same collection catches the axis underneath it, whose labels stack rather than crowd.
 - **Cards laid side by side: collect their BOTTOM edges, not their tops.** Tops align for free —
   the row sets them — so every horizontal check passes while the row ends on a staircase. One
   `getBoundingClientRect().bottom` per card in a row: more than one value is the finding, and the
@@ -342,6 +349,15 @@ defect, so finding it on one panel is a reason to sweep the siblings.
   neighbour, give the short card the fact it is missing, or re-pair the row. Screenshots are how
   this is noticed and the rects are how it is aimed: a staircase is obvious on sight and invisible
   to every probe above this one.
+- **A scroller's CONTENT against the scroller — measure both, never just the frame.** A horizontal
+  scroll region lays its child out in a ROW, so a grid, a strip or a rail narrower than its frame
+  keeps its own content width and leaves the rest of the box empty; a `min-width: 100%` on the
+  content container does not carry to the child, which is what makes this look already fixed in
+  the source. It never appears as the blank space it is — the child sits at its floor, so what
+  shows is its CELLS wrapping their values onto two lines while a third of the card beside them is
+  drawn on by nothing. Walk up from one cell to the ancestor whose parent has `overflow-x: auto`,
+  comparing widths at each step; a child narrower than that frame is the finding, and the fix is
+  to let the child grow, never to widen the cells by hand.
 
 → [composition.md](./composition.md) §"Canvas & content column", §"Cards — banded and composable", §"No dead rows", §"The register's own craft".
 
@@ -583,6 +599,20 @@ explicit one, so a set where "the important ones are annotated" sheds the unanno
 first — annotating some columns and not others is the failure, not the fix. If the register has
 more than one column, either all of them carry a rank or none do.
 
+**Then ask what the FIRST survivor is, because position outranks every rank.** Column 0 is the
+row's identity and never drops, whatever number it carries — so if the survivor list opens on
+something that does not identify the row (a time, a date, a sequence number), the finding is the
+column ORDER and no amount of re-ranking touches it. It hides behind the reading convention:
+anything read as a schedule is ordered time-first, which quietly makes the clock the one column a
+phone cannot lose. Chasing it through the ranks finds nothing, because the rank was never what
+kept it.
+
+**And count each survivor as a FACT, not a column.** Two columns holding one fact-pair — declared
+against counted, quoted against invoiced, planned against actual — mean nothing apart, so the fit
+drops whichever it reaches first and the survivor states a number with nothing to compare it to.
+That is worse than dropping both. Put the pair in ONE cell (`38 → 41`) and it survives or sheds
+whole, which also halves what the width has to carry.
+
 ### 8h-bis. A cell that grows a second line lifts its first
 **Collect** one column's first-line `y` MINUS its row's top, for every row; report the SET.
 
@@ -639,6 +669,47 @@ reports two cells. And a `Text` wrapping another `Text` keeps its own words in a
 so a walk over leaf ELEMENTS measures only the nested span and reports the cell starting a
 hundred pixels in; measure text nodes with a `Range`.
 
+### 8k. Opinions the reader cannot operate — authored bands, and pills beside a search
+
+Two defects of one kind: the screen holds a view the reader can neither inspect nor put down. Both
+render perfectly, and neither shows up in any measurement of treatment.
+
+**Measure, bands.** Count the group bands a register renders, then look in the filter band for a
+control that produced them. Bands with no `group by` control are AUTHORED — the screen decided the
+cut. Then ask the harder half: is the value those bands group on also a COLUMN? A register that
+bands by something it never shows as a column leaves that fact unsortable and unfilterable, and it
+disappears the moment the reader wants a different cut.
+
+```js
+// bands rendered vs. a control that could have produced them
+const bands = document.querySelectorAll('[data-table-group], [role="rowgroup"] > [role="presentation"]').length
+const controls = [...document.querySelectorAll('button, select')].map(e => e.textContent.trim())
+```
+
+**Measure, pills.** In one filter band, count `SearchInput`s and count pill rows (`ChipGroup`). Both
+above zero is the finding: a row of pills next to a search box is two controls competing to be read
+first, and the pills win on ink while the search wins on habit.
+
+```js
+const band = document.querySelector('[data-filter-band]')
+band && { search: band.querySelectorAll('input[type="search"], input[type="text"]').length,
+          pills: band.querySelectorAll('[role="radiogroup"], [data-chip-group]').length }
+```
+
+**The source-side signature is cheaper than either.** A file rendering band headings whose label
+comes from the row's own data, with no state driving it — a `groupBy`/`lens` param absent from the
+url or component state. And an import of both `search_input` and `chip_group` in one screen.
+
+**What the fix is not.** Deleting the bands is not the fix, and neither is keeping them and adding a
+chip. Ship the value as a column first, then offer grouping as a control defaulting to none, and
+drop that column while its own grouping is on — the band states it once, the column would repeat it
+on every row beneath it.
+
+→ [composition.md](./composition.md) §"A register that TRIAGES — `TableGroup`" (flat is the
+default) and §"One view-control vocabulary" (a `ChipGroup` lens only where the band has no search).
+Both rules predate this probe; it exists because reading them is not the same as noticing you broke
+them.
+
 ### 9. The absence pass — what catches "bland"
 Every probe above reads an element that EXISTS. None fires on a screen where nothing is wrong and
 nothing is right, which is the screen reported as bland. Defect-removal converges on *inoffensive*;

package/docs/templates.md

@@ -805,7 +805,7 @@ quick-capture templates. Top → bottom:
   so a walk-back is one handoff at a time.
 - **Danger zone** — with the full section anatomy (heading + description) like every other
   section; the fenced red `DangerZone` card is the section's BODY.
-- A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) — **the rail is the page's COMPLETE
+- A LEFT OUTLINE RAIL (`SectionNav` + `useSectionNav`) — **the rail is the page's COMPLETE
   map** (every section including Danger zone; subsections never join it) — headed by the
   bare circular `BackButton`; it scroll-spies the active section (`current={activeKey === key}`
   on each item — navigation, not selection), and on narrow containers becomes the pinned

package/examples/tpl_attendance.tsx

@@ -2,7 +2,6 @@ import { useState } from "react";
 import { ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { colors, solid } from "@lotics/ui/colors";
-import { Accordion, AccordionContent, AccordionHeader } from "@lotics/ui/accordion";
 import { ActionMenu } from "@lotics/ui/action_menu";
 import { Avatar } from "@lotics/ui/avatar";
 import { Badge } from "@lotics/ui/badge";
@@ -14,6 +13,7 @@ import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { Picker } from "@lotics/ui/picker";
+import { StateMatrix, type StateMatrixState } from "@lotics/ui/state_matrix";
 import { Tabs } from "@lotics/ui/tabs";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -24,8 +24,9 @@ import { Tabs } from "@lotics/ui/tabs";
 // Grammar: zinc-50 canvas, header + month Picker, KPIStrip (four counts),
 // Tabs Today / This week. "Today" = one banded roster Card — each row
 // press-opens the employee workspace Drawer (◀ ▶ sequencing) and carries a
-// ⋯ ActionMenu with the day's quick fixes. "This week" = per-person Accordion
-// rows: five day markers, expanding to the day-by-day detail in place.
+// ⋯ ActionMenu with the day's quick fixes. "This week" = one StateMatrix —
+// a person per row, the weekdays named once across the top, a glyph per day;
+// a cell opens the same workspace Drawer.
 // ─────────────────────────────────────────────────────────────────────────────
 
 type TrangThai = "co_mat" | "di_muon" | "vang" | "nghi_phep";
@@ -66,12 +67,13 @@ const TRANG_THAI: Record<TrangThai, { label: string; color: "emerald" | "amber"
   nghi_phep: { label: "On leave", color: "blue" },
 };
 
-const NGAY_CONG: Record<NgayCong, { bg: string; border: string; label: string }> = {
-  du: { bg: solid("emerald"), border: solid("emerald"), label: "Full day" },
-  muon: { bg: solid("amber"), border: solid("amber"), label: "Late" },
-  vang: { bg: colors.white, border: solid("red"), label: "Absent" },
-  phep: { bg: solid("blue"), border: solid("blue"), label: "On leave" },
-};
+const NGAY_CONG: (StateMatrixState & { key: NgayCong })[] = [
+  { key: "du", label: "Full day", color: "emerald" },
+  { key: "muon", label: "Late", color: "amber" },
+  { key: "vang", label: "Absent", color: "red", shape: "hollow" },
+  { key: "phep", label: "On leave", color: "blue", shape: "dot" },
+];
+const ngayCong = (k: NgayCong) => NGAY_CONG.find((n) => n.key === k) ?? NGAY_CONG[0];
 
 const THANG = [
   { label: "April 2026", value: "2026-04" },
@@ -85,12 +87,9 @@ const TAB = [
 ];
 
 const NGAY_TUAN = ["T2", "T3", "T4", "T5", "T6"];
+const NGAY_TUAN_DAY = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"];
 
-const rowPad = { paddingHorizontal: 20, flexDirection: "row" as const, alignItems: "center" as const, gap: 12 };
 
-// Week-view widths (the Accordion grid: day cells + week total + disclosure).
-// The Today roster uses COLUMNS below, rendered by Table.
-const W = { tong: 72, cell: 22, chevron: 28 };
 
 const COLUMNS: TableColumn[] = [
   { key: "ten", label: "Employee", flex: 1, sortable: true },
@@ -104,12 +103,23 @@ function badgeLabel(nv: NhanVien): string {
   return nv.trangThai === "di_muon" && nv.muonPhut !== undefined ? `${tt.label} ${nv.muonPhut}ph` : tt.label;
 }
 
-/** One weekday marker — filled means worked, hollow red ring means absent. */
+/** One weekday marker in the drawer's day list — the same glyph the week grid draws. */
 function DayCell({ ngay }: { ngay: NgayCong }) {
-  const s = NGAY_CONG[ngay];
+  const s = ngayCong(ngay);
+  const hollow = s.shape === "hollow";
+  const dot = s.shape === "dot";
   return (
-    <View style={{ width: W.cell, alignItems: "center" }}>
-      <View style={{ width: 13, height: 13, borderRadius: 4, backgroundColor: s.bg, borderWidth: 1, borderColor: s.border }} />
+    <View style={{ width: 22, alignItems: "center" }}>
+      <View
+        style={{
+          width: dot ? 6 : 12,
+          height: dot ? 6 : 12,
+          borderRadius: dot ? 999 : 3,
+          backgroundColor: hollow ? colors.white : solid(s.color),
+          borderWidth: hollow ? 1.5 : 0,
+          borderColor: solid(s.color),
+        }}
+      />
     </View>
   );
 }
@@ -160,38 +170,6 @@ function HomNayRow({ nv, selected, onPress }: { nv: NhanVien; selected: boolean;
   );
 }
 
-/** Week row — read-only drill-down: expands in place to the day-by-day detail. */
-function TuanRow({ nv }: { nv: NhanVien }) {
-  return (
-    <Accordion>
-      <AccordionHeader accessibilityLabel={`Week detail for ${nv.ten}`}>
-        <View style={{ flex: 1, gap: 2 }}>
-          <Text size="sm" weight="medium" leading="tight" numberOfLines={1}>{nv.ten}</Text>
-          {/* Body size: `medium` above already separates the pair, so the rung
-              down would be a second demotion on the line that says WHICH
-              person this is. */}
-          <Text size="sm" color="muted" leading="tight" numberOfLines={1}>{nv.chucVu}</Text>
-        </View>
-        <View style={{ flexDirection: "row", gap: 10 }}>
-          {nv.tuan.map((ngay, i) => <DayCell key={NGAY_TUAN[i]} ngay={ngay} />)}
-        </View>
-        <View style={{ width: W.tong, alignItems: "flex-end" }}>
-          <Text size="sm" weight="medium" tabular>{nv.tongTuan}</Text>
-        </View>
-      </AccordionHeader>
-      <AccordionContent>
-        {nv.tuan.map((ngay, i) => (
-          <View key={NGAY_TUAN[i]} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 32 }}>
-            <Text size="xs" color="muted" tabular style={{ width: 24 }}>{NGAY_TUAN[i]}</Text>
-            <DayCell ngay={ngay} />
-            <Text size="sm">{NGAY_CONG[ngay].label}</Text>
-          </View>
-        ))}
-      </AccordionContent>
-    </Accordion>
-  );
-}
-
 function KVRow({ label, value }: { label: string; value: string }) {
   return (
     <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 24 }}>
@@ -234,7 +212,7 @@ function NhanVienWorkspace({ nv }: { nv: NhanVien }) {
                 <View key={NGAY_TUAN[i]} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 24 }}>
                   <Text size="xs" color="muted" tabular style={{ width: 24 }}>{NGAY_TUAN[i]}</Text>
                   <DayCell ngay={ngay} />
-                  <Text size="sm">{NGAY_CONG[ngay].label}</Text>
+                  <Text size="sm">{ngayCong(ngay).label}</Text>
                 </View>
               ))}
             </View>
@@ -258,7 +236,6 @@ export function TplAttendance() {
   const onSort = (key: string) => setSort(cycleSort(sort, key));
 
   const dem = (tt: TrangThai) => NHAN_VIEN.filter((nv) => nv.trangThai === tt).length;
-  const eyebrow = (label: string) => <Text size="xs" color="muted" weight="medium">{label}</Text>;
 
   // The Today roster, ordered by the active sort (Hours sorts numerically).
   const sorted = sortBy(NHAN_VIEN, sort, (nv, key) =>
@@ -310,35 +287,29 @@ export function TplAttendance() {
             </Table>
           </Card>
         ) : (
-          <Card style={{ padding: 0 }}>
-            <View style={[rowPad, { paddingVertical: 10 }]}>
-              <View style={{ flex: 1 }}>{eyebrow("Employee")}</View>
-              <View style={{ flexDirection: "row", gap: 10 }}>
-                {NGAY_TUAN.map((d) => (
-                  <View key={d} style={{ width: W.cell, alignItems: "center" }}>{eyebrow(d)}</View>
-                ))}
-              </View>
-              <View style={{ width: W.tong, alignItems: "flex-end" }}>{eyebrow("Week total")}</View>
-              <View style={{ width: W.chevron - 12 }} />
-            </View>
-            <View style={{ paddingHorizontal: 20 }}>
-              {NHAN_VIEN.map((nv) => (
-                <View key={nv.id}>
-                  <Divider />
-                  <TuanRow nv={nv} />
-                </View>
-              ))}
-            </View>
-            <Divider />
-            {/* legend band — what each marker means */}
-            <View style={[rowPad, { paddingVertical: 12, gap: 18 }]}>
-              {(Object.keys(NGAY_CONG) as NgayCong[]).map((k) => (
-                <View key={k} style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-                  <DayCell ngay={k} />
-                  <Text size="xs" color="muted">{NGAY_CONG[k].label}</Text>
-                </View>
-              ))}
-            </View>
+          <Card>
+            {/* The grid owns its axis, its legend and its scroll; a cell is a door to the
+                same workspace the roster opens. Absent is HOLLOW and leave is a DOT so the
+                two kinds of "not here" read apart before the legend is consulted. */}
+            <StateMatrix
+              columns={NGAY_TUAN.map((d, i) => ({ key: d, label: d, current: i === 2 }))}
+              states={NGAY_CONG}
+              rows={NHAN_VIEN.map((nv) => ({
+                key: nv.id,
+                leading: <Avatar name={nv.ten} size="sm" />,
+                label: nv.ten,
+                total: nv.tongTuan,
+                cells: nv.tuan.map((ngay, i) => ({
+                  state: ngay,
+                  pressable: true,
+                  name: `${nv.ten}, ${NGAY_TUAN_DAY[i]}: ${ngayCong(ngay).label}`,
+                })),
+              }))}
+              onPressCell={(rowKey) => setOpenId(rowKey)}
+              rowLabelWidth={220}
+              cellWidth={36}
+              labels={{ total: "Week total" }}
+            />
           </Card>
         )}
       </View>

package/examples/tpl_pivot.tsx

@@ -2,6 +2,7 @@ import { useMemo, useState } from "react";
 import { Pressable, ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
+import { Avatar } from "@lotics/ui/avatar";
 import { Badge } from "@lotics/ui/badge";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
@@ -149,7 +150,15 @@ export function TplPivot() {
           </CardHeader>
           <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
             <Matrix
-              rows={WAREHOUSES.map((w) => ({ key: w.key, label: w.label }))}
+              // A row is a SUBJECT, so it carries the same identity mark a
+              // warehouse wears anywhere else in the app — square, because a
+              // facility is an organization and not a person. The mark is drawn
+              // inside `rowLabelWidth`, so nothing else in the grid moves.
+              rows={WAREHOUSES.map((w) => ({
+                key: w.key,
+                label: w.label,
+                leading: <Avatar shape="square" size="sm" name={w.label} />,
+              }))}
               cols={CATEGORIES.map((c) => ({ key: c.key, label: c.label }))}
               value={value}
               selected={cell}