@lotics/ui 46.14.1 → 47.1.0

package/AGENTS.md

@@ -61,6 +61,26 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   Worked in `examples/tpl_record.tsx` § Progress.
   → [catalog.md §"Tasks, to-dos, phased work"](./docs/catalog.md),
   [catalog.md §"Tasks & checklists"](./docs/catalog.md).
+- **A calendar is for WHEN; a Gantt is for WHO/WHAT.** Days on the axis → `CalendarView`
+  (compound: `CalendarToolbar` + `CalendarMonth`/`CalendarWeek`/`CalendarDay`/`CalendarAgenda`,
+  controlled via `date`/`view`). Resources on the axis — a channel, an owner, a vehicle →
+  `GanttView`, which draws lanes (`group`), milestones and progress. And
+  a grid is unreadable in TWO directions: too narrow OR too short, month/week fall back to the
+  agenda on their own, so never wrap one in a horizontal scroller to force it.
+  → [catalog.md §"Scheduling & time"](./docs/catalog.md).
+- **A repeating event is ONE row with a `repeat`, and there is no `timeZone` prop.** The
+  calendar expands a repeat to the view's own range, so a timetable is one event rather than a
+  year of them; an occurrence's id resolves back to the source row. And a stored Lotics
+  datetime is a naive WALL CLOCK — "14:30" means 14:30 to the business — so there is nothing to
+  convert and a calendar that re-projected it would move every event. Only *what day it is*
+  depends on the reader's location: that is the `now` prop.
+  → [catalog.md §"Scheduling & time"](./docs/catalog.md).
+- **A wash gives a surface its body; a border — or an accent stripe down one side — is that
+  same edge asserted twice.** Light ground + dark ink of one family (`Badge`'s tonal pairing),
+  never the solid shade under white text; `solid()` is for a DOT, where a few pixels carry
+  identity. And a radius is a PROPORTION of the box (`proportionalRadius`), because a component
+  sized by data renders as a pill at one height and barely a corner at another.
+  → [composition.md §"A body, not an edge"](./docs/composition.md).
 - **`Badge` = STATUS only; supporting detail is the muted second line.** A type / category /
   attribute / count is not a status — it belongs under its identity as `size="xs" color="muted"`,
   never a second chip. →

package/MIGRATION.md

@@ -4,6 +4,64 @@ 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.
 
+## 47.0.0
+
+**`@lotics/ui/calendar` is a compound, and `CalendarEvent.color` is a token.**
+
+`CalendarView` still exists and `<CalendarView events={…} />` still renders a working calendar,
+so the drop-in call site is unchanged. Four things did change:
+
+- **`MonthView` / `TimeGridView` are gone.** The parts are `CalendarMonth`, `CalendarWeek`,
+  `CalendarDay`, `CalendarAgenda`, `CalendarToolbar` and `CalendarBody`, and they read their
+  state from the root rather than taking `date`/`events` props. Mount them as children of
+  `CalendarView` to compose your own chrome.
+- **`color` is a `ColorName`, not a string.** `color: solid("blue")` becomes `color: "blue"`.
+  The views derive a fill, a tint and a border from the token; the old code appended `"1f"` to
+  the string for the tint, which produced garbage for anything that was not a 6-digit hex.
+- **`CalendarLabels` is `CalendarViewLabels`, and it is provider-wired.** Strings now resolve
+  prop → `LoticsLocale.calendarView` → English, so a localized app can delete its hand-passed
+  set. `DEFAULT_CALENDAR_LABELS` is `DEFAULT_CALENDAR_VIEW_LABELS`. (`CalendarLabels` still
+  exists and still belongs to `@lotics/ui/date_calendar`, the date PICKER's month grid — the
+  two had the same name.) Two labels are new: `agenda`, `noEvents`, `addAt`.
+- **`onEventDrop` is gone.** Dragging an event to another day wrote through no seam an app
+  could gate. Press-to-open is the gesture: `onEventPress`, plus `onSlotPress(start, end)` on
+  an empty day cell or hour slot.
+
+**Two behaviours changed without an API change, and both are worth looking at.** A week or day
+grid now opens on the earliest event IN VIEW rather than an hour before the wall clock (a week
+of 09:00 meetings viewed at 13:00 used to open on empty grid). And month/week fall back to the
+agenda when the surface is too narrow OR too short for a grid to name a single event — if you
+wrapped a calendar in a horizontal `ScrollView` with a `minWidth` to work around the old
+behaviour, delete that: it now fights the fallback.
+
+**Additive in the same release:** `CalendarEvent.repeat` expands a series to the view's own
+range (a timetable is one row, not a year of them) and `CalendarView`'s `now` supplies the
+reference instant for the today badge, the now line and the opening scroll — which also
+makes "today" pinnable in a test. There is deliberately **no `timeZone` prop**: Lotics
+stores a datetime as a naive wall clock, so a calendar that re-projected it would move
+every event.
+
+### `GanttView`, in the same major
+
+It keeps the promise its type was already making, and `color` becomes a token.
+
+- **`group` now renders.** It was declared on `GanttTask`, documented as a lane label, passed by
+  callers — and read by nothing; every task rendered in one flat list. Tasks sharing a `group`
+  now sit under one heading, in first-seen order, with ungrouped tasks leading. If you were
+  passing `group` and relying on the flat rendering, drop the field.
+- **`color` is a `ColorName`, not a string** — `solid("blue")` becomes `"blue"`, matching
+  `CalendarEvent`.
+- **`onTaskResize` is gone.** Dragging a bar's edge wrote through no seam an app could gate,
+  the same reason the calendar's drag went in 47.0.0. Press is the gesture.
+- **Labels are provider-wired** — prop → `LoticsLocale.gantt` → English, so a localized app can
+  delete its hand-passed set. One label is new: `empty`.
+
+New, additive: `milestone` draws a diamond, `progress` fills part of a bar. `buildRows` is
+exported for anything that needs the same lane geometry.
+
+There are deliberately **no dependency connectors**. Lane order and bar position already carry
+the sequence, and elbow arrows over an already-ruled grid restate it as line noise.
+
 ## 46.3.0
 
 **A `Text` with `numberOfLines` now declares `flexShrink: 1` + `minWidth: 0` for you.**

package/docs/catalog.md

@@ -86,6 +86,13 @@ inline: a picker option, an assignee, a `select_member` value. Pure: resolve the
 your directory and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`MemberSelect`
 renders these per option.)
 
+**`showAvatar={false}` where the member is ONE FIELD AMONG COLUMNS** — an owner, an assignee,
+a last-edited-by. Keep the face where the member IS the subject (a roster, a picker option, a
+profile). In a supporting column it fails twice: it competes with the mark the row already
+carries for its own subject, and on a real book a few people own hundreds of rows, so the
+column draws one repeated disc — which `composition.md` §Identity marks calls a mark that
+"carries nothing and is the largest, brightest thing there".
+
 **To answer "who IS this?" — `MemberPeek`**, the same chip made a door onto a
 `MemberProfileCard`: a 72px avatar, what they sign in as, their role, their teams and when they
 joined. The trigger takes `Peek`'s `variant="control"` there, so the chip seats in the 40px
@@ -130,7 +137,11 @@ that a whole office shares.
 `ThumbnailStack` is `AvatarGroup`'s sibling over a different subject: a capped, overlapping set
 of PICTURES answering "an order of what?", "which parts?", "what arrived?" in one register cell.
 Pass `{ id, label, image }` per thing; `max` (default 3) caps it and the rest become the `+N`
-mark at the end of the stack. Both components read their separating edge from `mark_stack.ts`,
+mark at the end of the stack. Each mark ANNOUNCES its label by default — a standalone stack is
+unreadable otherwise — so pass **`decorative`** where the row already names the thing in text, or
+the pictures read it a second time on every row. (The default is the opposite of
+`Avatar.announce`, and for the same reason: an avatar almost always sits beside its name, a stack
+often does not. The default follows where the component actually sits.) Both components read their separating edge from `mark_stack.ts`,
 so a row carrying people in one column and goods in the next reads as one device used twice
 rather than two — but they **tuck by different fractions, and that is deliberate**: a face is
 edge-anchored and survives being covered two thirds of the way, while a product shot centres its
@@ -279,7 +290,12 @@ by size.)
   search, you don't group. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx).
   Never an HTML `<table>` or a `.map` of rows. The register adapts to its container on its
   own — hides columns by `priority`, stacks rows below the two-column floor (see the `table`
-  inventory entry) — so a narrow screen or panel needs NO branching; compose a hand-designed
+  inventory entry) — so a narrow screen or panel needs NO branching. **A flexible column that
+  carries fixed chrome inside its cell declares it as `lead`** (a leading mark plus its gap): the
+  fit guarantees a READ floor for the text, and without `lead` the mark eats part of that floor,
+  so a register reports "fitted" while its subject clips. `composition.md` requires a leading mark
+  on every register row and `tpl_item_list` puts it inside the subject cell, so this is the
+  ordinary case, not an exotic one; compose a hand-designed
   card pile (`PressableRow` + your own hierarchy) over `useScreenSize` only when a screen
   deserves a better mobile shape than the automatic stack.
 - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view)
@@ -482,7 +498,8 @@ patterns doc indexed in [AGENTS.md](../AGENTS.md)).
 `ScanField` (scan/verify), `Stepper` (a guided run / progress sequence — done, current,
 upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocation),
 `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
-`Calendar` (the `calendar` module's views), `Gantt`, `comments_thread`.
+`CalendarView` (the `calendar` module — days are the axis), `GanttView` (RESOURCES are the
+axis: a channel, an owner, a vehicle), `comments_thread`.
 
 ### AI surfaces
 
@@ -1350,7 +1367,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed
   total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column;
   non-interactive, NOT a disabled input; `muted`/`tabular`/`align="right"` for a number
-  column, `weight="medium"` to emphasise a total among plain rows, `multiline` to WRAP rather
+  column, `weight="medium"` to emphasise a total among plain rows, **`actions` for a verb about
+  the value** (look this id up, copy it, request the gated change) — a static value is still a
+  field, and its verb belongs on the field's surface, never on the row's ground where an
+  `InlineButton` has nothing under it; `multiline` to WRAP rather
   than truncate (single-line is the default, because a field column reads as a column only if
   its rows are one height — pass it where the counterpart editor is itself `multiline`, or a
   truncated value beside a wrapping input reintroduces the misalignment on the other axis).
@@ -1375,7 +1395,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`inline_button`** — `InlineButton`: a verb that sits INSIDE an inline field's surface
   (the `Open` on a reference, a `Copy` on a value worth copying) rather than in the row's
   trailing column — put it inside when the act is ABOUT THE VALUE, so it travels with what it
-  acts on and the trailing column stays free for row-level verbs. FILLED (`Button secondary`'s own
+  acts on and the trailing column stays free for row-level verbs.
+
+  **NEVER use it outside an inline field.** Not in a section header, not in a toolbar, not as a
+  row action, not as a card's own verb — it is an *inner* control of a field, and the whole of its
+  design says so: it is FILLED against the field's white ground (a relationship to a surface it no
+  longer has when you move it), it is 28px against a 40px band, it carries no border because the
+  field already draws one, and **it stops propagation** because the field beneath it is pressable.
+  Outside a field every one of those becomes wrong: it reads as a heavier `Button secondary` that
+  is mysteriously too small, it sits on a ground it was not contrasted against, and its swallowed
+  press is now swallowing nothing. If the verb is about the ROW use the row's trailing action; if
+  it is about the SECTION use its heading row; if it is about the SCREEN it is a `Button`. The
+  test is one question — **is there a field surface under it?** If not, it is the wrong control. FILLED (`Button secondary`'s own
   zinc-100) on the field's white surface — the contrast is a RELATIONSHIP, not a colour: invert it
   if the resting field surface ever changes, or the verb dissolves into the value. 28px, radius 8,
   no border (the field already has one) and no shadow (depth belongs to the primary action alone). **It stops propagation** — that is the contract: the
@@ -2048,14 +2079,42 @@ component rather than showing it at zero.
 
 ### Scheduling & time
 
-- **`calendar`** — the calendar views: `CalendarView` (the composed month/week surface),
-  `TimeGridView`, `MonthView`, plus the layout/date helpers (`layoutDayColumns`,
-  `packEventLanes`, `addDays`, `startOfWeek`, …) and `CalendarEvent`/`CalendarLabels` types.
-  **Limitation:** labels are not provider-wired — pass `labels`
-  (`DEFAULT_CALENDAR_LABELS` is English).
-- **`gantt`** — `GanttView` + scale helpers (`barGeometry`, `axisRange`, `buildTicks`,
-  `pxPerDay`) + `GanttTask`/`GanttLabels` types. **Limitation:** labels are not
-  provider-wired — pass `labels` (`DEFAULT_GANTT_LABELS` is English).
+- **`calendar`** — a COMPOUND calendar of events. `CalendarView` is the root and holds the
+  state; `CalendarToolbar`, `CalendarMonth`, `CalendarWeek`, `CalendarDay`, `CalendarAgenda`
+  and `CalendarBody` are the parts. Mount it bare (`<CalendarView events={…} />`) for the
+  toolbar plus the current view, or pass children to compose your own chrome — an app screen
+  already has a header band, and a calendar that welds one on stacks two. `date` / `view` with
+  their `on*Change` make it controlled, so a filter chip or a route can drive it. It NEVER
+  writes: `onEventPress` and `onSlotPress` hand you the event or an empty range and your own
+  form does the rest. `renderEvent` replaces a chip's contents while the calendar keeps the
+  press target and the geometry. Also `EventChip`, `useCalendar`, and the pure helpers
+  (`layoutDayColumns`, `packEventLanes`, `compareEvents`, `fitLanes`, `initialScrollMinutes`,
+  `gridWindow`, `weekRowsInMonth`, `addDays`, `startOfWeek`, …).
+  **A repeating event costs one row, not a year of them:** put a `repeat` on the event
+  (`{ every: "day" | "week" | "month", interval?, on?, until?, count? }`) and the calendar
+  expands it to the occurrences in the view's own range. Deliberately NOT RFC 5545 — a
+  timetable, a standup, a monthly close; see `expandRepeats` for why the long tail is a
+  platform field type rather than a wider rule. An occurrence's id encodes its source, so
+  `onEventPress` still hands you the row the series came from (`sourceEventId`).
+  **There is no `timeZone` prop, on purpose:** Lotics stores a datetime as a naive WALL CLOCK,
+  so "14:30" means 14:30 to the business and there is nothing to convert — re-projecting it
+  would move every event. What does depend on where the reader sits is *what day it is*, so
+  that alone is the `now` prop (which also pins "today" in a test).
+  Three things it decides for you: **which shape** — below `compactBelow` (720px) or too short
+  for a month to name one event per row, month/week become the agenda, because seven columns on
+  a phone can only say WHICH days have something; **how many lanes** — measured against the row,
+  not a constant; and **the hour window** — `dayStartHour`/`dayEndHour` are a VIEWPORT, so a
+  06:00 delivery widens the grid instead of disappearing from it. `color` is a `ColorName`, not
+  a hex. Labels resolve prop → `LoticsLocale.calendarView` → English.
+- **`gantt`** — `GanttView`: a frozen label column beside a zoomable, horizontally
+  scrollable axis. Reach for it over a calendar when the **rows** are the subject (a phase, an
+  owner, a vehicle, a channel) and dates are the horizontal axis. **Lanes** come from `group`,
+  **milestones** render as diamonds, and `progress` fills part of a bar. No dependency
+  connectors: lane order and bar position already carry the sequence, and elbow arrows over an
+  already-ruled grid restate it as line noise. The bar carries no label, because the frozen
+  column beside it already names the task. Helpers: `buildRows`, `barGeometry`, `axisRange`,
+  `buildTicks`, `pxPerDay`; types `GanttTask`/`GanttRow`/`GanttLabels`. `color` is a
+  `ColorName`; labels resolve prop → `LoticsLocale.gantt` → English.
 - **`timeline`** — `Timeline`: a heterogeneous event LOG — per-row icon + expandable
   details; models the past, NOT progress. Three things it decides for you, because a row
   cannot be trusted to a caller's data: the **label clamps to two lines WHILE COLLAPSED**

package/docs/composition.md

@@ -360,6 +360,33 @@ 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.
 
+## 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
+this happen* and the answer is read off a POSITION — which day, how long, what else is running
+at the same time. When the question is *which of these needs me*, the answer is a register with
+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.
+
+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
+a real title; below that every event reads "Cont…" and the grid can only say WHICH days have
+something. Height fails the same way — a month too short to give each week row one event plus
+its overflow chip renders nothing but "+3 more" on all thirty-one days. Both are the same
+finding, and the answer to both is a different SHAPE: `CalendarView` falls back to the agenda on
+its own. Never wrap a month grid in a horizontal scroller to force it — that trades a readable
+list for a wide thing the reader has to drag.
+
+**A time window is a viewport, never a filter.** Declaring the working day as 08:00–18:00 sets
+where the grid OPENS. An event outside it widens the grid; a calendar that silently refuses to
+draw a 06:00 delivery is a calendar that lies, and nothing on screen says so.
+
+**Rows of days, or rows of resources — pick by what the reader is comparing.** Comparing days
+is a calendar. Comparing a channel against a channel, an owner against an owner, a vehicle
+against a vehicle — with days as the horizontal axis — is `GanttView`. A campaign plan is
+usually the second one, however much it is called a calendar.
+
 ## Keyboard & focus
 
 - **Use `tabIndex`, never `focusable`.** React Native Web's `Pressable` silently ignores
@@ -529,9 +556,25 @@ have decided the thing itself (which one they want).
 The toggle earns its place when the two states differ in more than a number — different rows,
 different units, a different shape of answer. Swapping `1.700.000` for `2.000.000` is not that.
 
+**A container's own gap must exceed the largest gap INSIDE its children — not just the gap to its
+siblings.** The comparison authors are told to make is within-group against between-group, which
+reads as "compare the two numbers *you* wrote". The failure that actually ships compares a number
+you wrote against one the KIT wrote inside a component you dropped in: a section body at 12 or 14
+around a field table that spaces its own rows at 16. Both are conventional, neither looks wrong
+alone, and the boundary BETWEEN two objects ends up tighter than the boundary inside one. Measured
+form: per container, collect its own `row-gap` and the **max `row-gap` of its visible children**;
+`own <= child-max` is the finding.
+
 ## Numbers, money, dates
 
 - Free-standing numerals: `<Text tabular>` — always.
+- **A kit component that RENDERS a number takes the app's formatter — it must never `String()` a
+  decimal.** In a locale that writes `28,9`, the one figure the kit prints for itself becomes the
+  one figure on the screen that is wrong, sitting beside numbers the app formatted correctly — and
+  in a locale where `.` is the *thousands* separator that is not a cosmetic difference, it is a
+  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.
 - **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
@@ -1638,6 +1681,19 @@ information.
   identity a reader actually scans for — a deal takes its account's mark, since "whose deal is
   this" is the question being asked of the list. Only rows with genuinely no identity are exempt:
   a list of amounts, a log of events.
+- **A member as one FIELD among columns is TEXT, not a face** (`MemberChip showAvatar={false}`).
+  Keep the face where the member IS the subject — a roster, a picker option, a profile. In an
+  owner / assignee / last-edited-by column it fails twice over: it competes with the mark the row
+  already carries for its own subject, and on a real book a handful of people own hundreds of rows,
+  so the column draws the same disc over and over. Shipped example: an owner column rendering four
+  identical discs for two people, both initial "T", both hashed to a purple.
+- **A mark derived from POSITION is not identity — the list already draws position.** An ordinal
+  disc, a rank badge, an index chip *does* vary per row, so it passes "the mark must not look the
+  same on every row" and every probe built on that test. It fails for a different reason: it
+  restates what top-to-bottom order says, and it spends the one slot that could have carried the
+  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`).
 - **A column of faces must not draw an UNBOUNDED audience as faces.** Where a cell answers "who
@@ -1665,12 +1721,19 @@ Every rule above removes a defect. None of them ADDS anything, so a screen can p
 and still be reported as plain, boring, or unfinished — which is a different complaint with a
 different fix.
 
-- **What is inherently visual in THIS data?** Work software has no photography, so the data itself
-  is the imagery: identity marks (above), status colour, file-type badges, sparklines, proportion
-  bars, tabular figures aligning down a column. Every one of these is information first and
-  decoration never — which is why they are the only kind of visual interest that survives contact
-  with a real dataset. Reaching instead for a gradient, an illustration or a hero band adds weight
-  without adding a single fact.
+- **What is inherently visual in THIS data?** Mostly the data itself: identity marks (above),
+  status colour, file-type badges, sparklines, proportion bars, tabular figures aligning down a
+  column. Every one of these is information first and decoration never — which is why they are the
+  only kind of visual interest that survives contact with a real dataset. Reaching instead for a
+  gradient, an illustration or a hero band adds weight without adding a single fact.
+- **But some entities DO have a likeness, and then it is the strongest mark available.** A product,
+  a property, a vehicle, a dish, a person — a reader recognises the thing itself faster than any
+  derived initial, and the picture is doing the identifying rather than decorating. Where the entity
+  has one, an empty image field is a **DATA gap, not a design constraint**: the fix is to put the
+  image on the record, not to restyle the row around its absence. A catalogue of sixty rows opening
+  with text reads as a fixture no treatment pass will rescue. The test is unchanged — it must make
+  the screen clearer AND better-looking — which is exactly what a thumbnail that is also the
+  identifier does, and exactly what a stock photo bolted onto a task list does not.
 - **What does the screen DECIDE?** A register listing every row at equal weight has no point of
   view: it hands the reader the same undifferentiated wall the query returned. A screen with a
   point of view puts what needs attention first (`TableGroup`), spends its one accent on where the
@@ -1827,6 +1890,31 @@ the ring. Collapsing them into one "active" style makes the selected item pixel-
 hovered one, so "which did I pick" is answerable only by moving the mouse away. The tell in code
 is a single boolean OR-ing selection together with hover, press and focus.
 
+## A body, not an edge — and a corner proportionate to the box
+
+Two rules that decide how any small coloured surface is drawn: an event chip, a board card, a
+timeline bar, a status pill.
+
+**A wash gives it a body; a border on top is the same edge asserted twice.** A transparent
+rectangle on a white canvas *is* its border — so the fill is what makes it an object, and once
+it has one, the outline says nothing new. This matters most where the surface already sits on a
+ruled ground (a calendar grid, a timeline, a table): every extra hairline competes with the
+rules that carry the structure. The same goes for an accent stripe down one side — it is a
+border wearing a colour, and the wash it sits on has already stated where the thing begins.
+
+**The wash is the family's light ground with its dark ink, never the solid shade with white on
+it.** A saturated fill per item turns a dense surface into a paint chart, and a screen with a
+dozen categories on it stops being something anyone can look at. The pairing is the one `Badge`
+uses for `tonal`. The solid shade keeps exactly one job: a DOT — a few pixels carrying identity
+rather than area, where the contrast is the point.
+
+**A radius is a proportion of the box, not a constant.** A component whose height is data —
+a chip sized to its duration, a bar sized to its span — cannot take one number: at 22px the
+control rung renders a pill, and the same value on a tall block is barely a corner, so two
+boxes of one family read as two vocabularies. Scale by height and cap at the container rung
+(`proportionalRadius`). Keep the ratio under a third, or the corner eats the side and the shape
+stops being a rounded rectangle.
+
 ## `Badge` is for STATUS only — everything else is text
 
 A `Badge` means STATE that must read at a GLANCE — a lifecycle status, a risk level, a quality

package/docs/reviewing.md

@@ -543,15 +543,23 @@ this converges on *distinctive*.
   largest, brightest thing there.
 - **What does the screen DECIDE?** A register listing every row at equal weight has no point of
   view. Usually the real answer when treatment fixes keep not landing.
-- **What is inherently visual in THIS data?** Where there is no photography — most work software —
-  the data is the imagery: identity marks, status colour, file-type badges, sparklines, proportion
-  bars, tabular figures.
+- **What is inherently visual in THIS data?** Usually the data itself: identity marks, status
+  colour, file-type badges, sparklines, proportion bars, tabular figures. **But check whether the
+  entity has a LIKENESS** — a product, a property, a vehicle, a person. If it does and the rows
+  open without one, query the image field's fill rate before writing a treatment finding: an empty
+  field makes this a DATA defect, and no amount of restyling fixes it.
 - **What makes this belong to THIS product?** Default typeface, default greys, default accent,
   default control shapes is a well-built generic screen, and no polish changes that. The fix is a
   theme, not another treatment pass.
 
 → [composition.md](./composition.md) §"Identity marks", §"Character comes from the DATA", §"Where the accent goes".
 
+**A driver's `.focus()` does not set `:focus-visible`** — so a focus-ring check driven
+programmatically reports *no ring* on a control whose ring is fine, and the audit spends its time
+on a defect that does not exist. Walk the surface with real `Tab` presses and read the computed
+`box-shadow` at each stop; `.focus()` is only good for asking what CAN take focus, never for how it
+looks when it does.
+
 ### 10. Microcopy
 - **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
   refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be
@@ -637,6 +645,32 @@ variant that walks ELEMENTS rather than text nodes. Those tags hold text nodes t
 sees, and counting them produces confident nonsense — a page "with eight nodes in Times New Roman"
 that has none, or a clean tally on a screen with an untracked component still on it.
 
+### Identity marks — N identical is a finding, and only a per-COLUMN count sees it
+Probe 9 says "count them. Zero is the finding, and so is N identical" — and every other snippet
+here reads type, rules, gaps, states or reachability, so nothing fired on a column of identical
+discs. Group by the x band (i.e. by column), because that is what separates the row's own subject
+mark from a supporting column that borrowed identity weight.
+
+```js
+// → [{ x, count, distinct, sample }] — flag any band with count > 1 && distinct === 1
+Object.values(
+  [...document.querySelectorAll('[data-avatar], [class*="avatar"], img')]
+    .filter((n) => n.getBoundingClientRect().width > 0)
+    .reduce((acc, n) => {
+      const band = Math.round(n.getBoundingClientRect().x / 24) * 24;   // column, not pixel
+      const cs = getComputedStyle(n);
+      const key = [cs.backgroundColor, n.textContent?.trim(), n.getAttribute("src") ?? ""].join("|");
+      acc[band] ??= { x: band, keys: new Set(), count: 0 };
+      acc[band].keys.add(key);
+      acc[band].count++;
+      return acc;
+    }, {}),
+).map((b) => ({ x: b.x, count: b.count, distinct: b.keys.size, sample: [...b.keys][0] }));
+```
+
+A band with `count > 1 && distinct === 1` is the reported defect. A band whose `distinct` is well
+under `count` is the softer version — a palette collapsing on real names — and worth reading by eye.
+
 ### Separator beats — is the biggest boundary the widest?
 
 **A rule is a painted LINE, and it is drawn two ways.** Selecting "thin and wide" alone gets both
@@ -740,17 +774,34 @@ Snapshot the SAME selector four times — at rest, hovered, focused, and while e
   const r = e.getBoundingClientRect(), cs = getComputedStyle(e);
   const inner = e.querySelector('input, textarea, [contenteditable]') || e;
   const ir = inner.getBoundingClientRect();
+  // The PAINTED node, which is often not the one you selected: a press target
+  // is frequently transparent with its ground on a child (a chip's body, a
+  // bar's fill). Reading the target's own `backgroundColor` returns
+  // `rgba(0,0,0,0)` at rest AND hovered, so a component with a perfectly good
+  // hover reports as having none — a probe that fails silently in the
+  // reassuring direction.
+  const opaque = (x) => { const b = getComputedStyle(x).backgroundColor; return b && b !== 'rgba(0, 0, 0, 0)' ? b : null; };
+  const painted = opaque(e) || [...e.querySelectorAll('*')].map(opaque).find(Boolean) || 'none';
   return {
     box: [Math.round(r.x), Math.round(r.y), Math.round(r.width), Math.round(r.height)],
     text: [Math.round(ir.x), Math.round(ir.y)],
     border: `${cs.borderTopWidth} ${cs.borderTopColor}`,
-    bg: cs.backgroundColor,
+    bg: painted,
     shadow: cs.boxShadow,
   };
 })
 ```
 
-`border`/`bg`/`shadow` differing is the design; `box`/`text` differing is the defect. The usual
+`border`/`bg`/`shadow` differing is the design; `box`/`text` differing is the defect.
+
+**A control that differs in NOTHING is the finding this catches most often**, and it does not
+look like a bug in a screenshot — the thing renders correctly, presses correctly, announces
+correctly, and simply never says it can be pressed. Run it against anything the eye reads as a
+card, chip or bar: identical rest and hover means the affordance was never built. What should
+change is the surface's OWN signature (a chip's fill, a row's wash, a field's border) one rung
+deeper, never a different colour and never the cursor — see composition.md §"The pointer
+cursor". And a surface with no press handler must NOT light up: an affordance on something
+inert advertises an action that does not exist. The usual
 cause is two components spending the same inset or the same padding — a wrapper AND the input both
 paying `CONTROL_TEXT_INSET`, a focus ring owned by both a shell and a nested pressable.
 

package/docs/templates.md

@@ -1015,8 +1015,14 @@ when you want them in the context of a whole record surface, and here when money
 One real `CalendarView` week grid over the current week's events, then a "Today" agenda card
 of pressable rows. Every slot is a door: pressing a grid event or an agenda row opens the
 sequenced workspace `Drawer`; agenda rows also carry the `⋯` quick-actions menu. Event colors
-carry meaning (one `ColorName` per event kind). The mock data anchors to the real current
-week so the copied screen is evergreen.
+carry meaning (one `ColorName` per event kind, stated ONCE — the chip's colour and the agenda
+row's swatch read the same field). The mock data anchors to the real current week so the copied
+screen is evergreen.
+
+**Read the header band for the controlled pattern.** The screen owns `date`, so its own "Today"
+button sets it — the calendar has no second toolbar of its own to fight, and nothing is
+remounted to force a jump. That is the shape to copy whenever a calendar sits under a header
+band you already have.
 
 ### `tpl_attendance` — the attendance desk
 

package/examples/tpl_calendar.tsx

@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
-import { colors, solid, type ColorName } from "@lotics/ui/colors";
+import { colors, type ColorName } from "@lotics/ui/colors";
 import { ActionMenu } from "@lotics/ui/action_menu";
 import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
@@ -52,47 +52,48 @@ function evt(
   m: number,
   durMin: number,
   title: string,
-  color: string,
   data: AgendaMeta,
 ): CalendarEvent<AgendaMeta> {
   const start = new Date(day.getFullYear(), day.getMonth(), day.getDate(), h, m);
-  return { id, title, start, end: new Date(start.getTime() + durMin * 60_000), color, data };
+  // The chip's colour IS the row's colour — `data.mau` is the one statement of
+  // it, so the two surfaces cannot drift apart.
+  return { id, title, start, end: new Date(start.getTime() + durMin * 60_000), color: data.mau, data };
 }
 
 const EVENTS: CalendarEvent<AgendaMeta>[] = [
   // Today — the dispatch desk's three slots.
-  evt("hn-1", TODAY, 8, 0, 90, "Deliver APEX PLASTICS — VTD063518", solid("blue"), {
+  evt("hn-1", TODAY, 8, 0, 90, "Deliver APEX PLASTICS — VTD063518", {
     diaDiem: "Eastport industrial zone",
     trangThai: "Truck loaded",
     mau: "blue",
   }),
-  evt("hn-2", TODAY, 10, 30, 60, "Reconcile delivery notes — HANDAN", solid("emerald"), {
+  evt("hn-2", TODAY, 10, 30, 60, "Reconcile delivery notes — HANDAN", {
     diaDiem: "Head office",
     trangThai: "Prepared",
     mau: "emerald",
   }),
-  evt("hn-3", TODAY, 15, 0, 60, "Customer sample review — VITTORIA", solid("amber"), {
+  evt("hn-3", TODAY, 15, 0, 60, "Customer sample review — VITTORIA", {
     diaDiem: "Factory sample room",
     trangThai: "Awaiting confirmation",
     mau: "amber",
   }),
   // The rest of the week.
-  evt("t-1", addDays(WEEK_START, SLOTS[0]), 8, 0, 90, "Deliver KOMASPEC — blanks 675×325", solid("blue"), {
+  evt("t-1", addDays(WEEK_START, SLOTS[0]), 8, 0, 90, "Deliver KOMASPEC — blanks 675×325", {
     diaDiem: "Northgate industrial park",
     trangThai: "Truck loaded",
     mau: "blue",
   }),
-  evt("t-2", addDays(WEEK_START, SLOTS[1]), 14, 0, 60, "Reconcile delivery notes — NEWTECONS", solid("emerald"), {
+  evt("t-2", addDays(WEEK_START, SLOTS[1]), 14, 0, 60, "Reconcile delivery notes — NEWTECONS", {
     diaDiem: "Head office",
     trangThai: "Prepared",
     mau: "emerald",
   }),
-  evt("t-3", addDays(WEEK_START, SLOTS[2]), 10, 0, 60, "Kick off the VITTORIA order", solid("amber"), {
+  evt("t-3", addDays(WEEK_START, SLOTS[2]), 10, 0, 60, "Kick off the VITTORIA order", {
     diaDiem: "Online meeting",
     trangThai: "Awaiting confirmation",
     mau: "amber",
   }),
-  evt("t-4", addDays(WEEK_START, SLOTS[3]), 8, 30, 90, "Deliver BRIGHTCELL BATTERIES — TS1250", solid("blue"), {
+  evt("t-4", addDays(WEEK_START, SLOTS[3]), 8, 30, 90, "Deliver BRIGHTCELL BATTERIES — TS1250", {
     diaDiem: "Brightcell plant, Eastport",
     trangThai: "Truck loaded",
     mau: "blue",
@@ -104,20 +105,10 @@ const EVENTS: CalendarEvent<AgendaMeta>[] = [
     start: addDays(WEEK_START, 2),
     end: addDays(WEEK_START, 4),
     allDay: true,
-    color: colors.zinc[500],
+    color: "zinc",
   },
 ];
 
-const CAL_LABELS = {
-  today: "Today",
-  month: "Month",
-  week: "Week",
-  day: "Day",
-  previous: "Previous",
-  next: "Next",
-  allDay: "all day",
-  more: (n: number) => `+${n} more`,
-};
 
 const p2 = (n: number) => String(n).padStart(2, "0");
 const fmtTime = (d: Date) => `${p2(d.getHours())}:${p2(d.getMinutes())}`;
@@ -187,9 +178,10 @@ function SlotWorkspace({ e }: { e: CalendarEvent<AgendaMeta> }) {
 }
 
 export function TplCalendar() {
-  // "Today" remounts the calendar — CalendarView owns date+view internally,
-  // so a fresh mount is the supported way to jump back to the current week.
-  const [calKey, setCalKey] = useState(0);
+  // The screen owns the date, so its own header band can drive the calendar —
+  // no remount, no second toolbar. This used to be `key={calKey}`, forcing a
+  // fresh mount because the calendar's date was private to it.
+  const [date, setDate] = useState(TODAY);
   const [openId, setOpenId] = useState<string | null>(null);
 
   const openEvent = EVENTS.find((e) => e.id === openId) ?? null;
@@ -215,21 +207,22 @@ export function TplCalendar() {
             <Text size="sm" color="muted">This week — deliveries, reconciliations and customer visits</Text>
           </View>
           <Text size="sm" color="muted" tabular>
-            {viewTitle("week", TODAY, 1, "vi")}
+            {viewTitle("week", date, 1, "vi")}
           </Text>
-          <Button title="Today" color="secondary" onPress={() => setCalKey((k) => k + 1)} />
+          <Button title="Today" color="secondary" onPress={() => setDate(TODAY)} />
         </View>
 
         {/* the calendar — real week grid, internal toolbar + scroll */}
         <Card style={{ padding: 0, height: 520, overflow: "hidden" }}>
           <CalendarView<AgendaMeta>
-            key={calKey}
             events={EVENTS}
             defaultView="week"
-            defaultDate={TODAY}
+            date={date}
+            onDateChange={setDate}
             weekStartsOn={1}
             locale="vi"
-            labels={CAL_LABELS}
+            dayStartHour={7}
+            dayEndHour={19}
             onEventPress={(e) => setOpenId(e.id)}
           />
         </Card>

package/examples/tpl_item_list.tsx

@@ -1244,8 +1244,13 @@ export function TplItemList() {
         <Text size="xxl" weight="semibold">Records</Text>
 
         {/* toolbar — search + consolidated filters LEFT, New case RIGHT, one row.
-            A search is present, so status is a dropdown (Select), not pills. */}
-        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+            A search is present, so status is a dropdown (Select), not pills.
+
+            `flex-start`, not `center`: the filter block wraps to two or three
+            lines on a phone, and centring floats the CTA against the whole
+            wrapped block — measured landing level with the SECOND row of chips,
+            anchored to nothing. The band's top edge is what it belongs to. */}
+        <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 8 }}>
           <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8, alignItems: "center", flex: 1 }}>
             <View style={{ flexGrow: 1, flexBasis: 220, minWidth: 200, maxWidth: 340 }}>
               <SearchInput