@lotics/ui 46.14.0 → 47.0.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

@@ -482,7 +482,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
 
@@ -2048,14 +2049,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
@@ -1827,6 +1854,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

@@ -397,7 +397,7 @@ A destination named for two things is two destinations, and the second strip is
 gets taken apart again. The same grep over the source (`<Tabs` per file) finds it without a
 running app: more than one file rendering `Tabs` in one app is the same defect at rest.
 
-→ [composition.md](./composition.md) §"Choice, filter & navigation controls" (one strip per surface).
+→ [composition.md](./composition.md) §"One view-control vocabulary" (one strip per surface).
 
 ### 8b. Does each tab earn its slot — count its rows AS A SCOPED READER
 
@@ -417,7 +417,7 @@ permission check; the screen moves to the app its owner already opens.
 **Source-side signature:** a screen whose list query filters by the viewer's membership, over a
 table the domain describes as organisation-wide.
 
-→ [composition.md](./composition.md) §"Choice, filter & navigation controls".
+→ [composition.md](./composition.md) §"One view-control vocabulary".
 
 ### 8c. First paint — count the controls the task actually needs
 - **On any screen whose job is ENTRY, count `input`/`select`/`textarea` on first paint.** Zero is
@@ -450,7 +450,7 @@ filter in its dependency array. Typecheck, lint and a screenshot all passed it.)
 **The cheap source-side signature:** a `SummaryLine` item carrying `tone` in a file whose filter
 band has only a `SearchInput`.
 
-→ [composition.md](./composition.md) §"Choice, filter & navigation controls"; the rule itself is in
+→ [composition.md](./composition.md) §"One view-control vocabulary"; the rule itself is in
 `src/summary_line.tsx`'s contract.
 
 ### 8e. Derivable columns — every column another cell already answers
@@ -503,8 +503,9 @@ the aggregates no control states: the money, the extreme, the ratio.
 hook's array) where the register renders a filtered derivative of it — and the two sitting far
 apart in the file, which is what lets them drift.
 
-→ [composition.md](./composition.md) §"Register / list" — the rule this measures is already
-written there; this probe exists because reading it is not the same as obeying it.
+→ [composition.md](./composition.md) §"Summaries — two altitudes, never mixed" — the rule this
+measures is already written there; this probe exists because reading it is not the same as obeying
+it.
 
 ### 8g. Truncation — every string the layout cut, at the width a phone actually is
 
@@ -739,17 +740,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.14.0",
+  "version": "47.0.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

package/src/board.tsx

@@ -10,7 +10,7 @@ import {
 } from "react";
 import { Platform, ScrollView, StyleSheet, View } from "react-native";
 import { colors, tint } from "./colors";
-import { CONTROL_RADIUS, MIN_CONTROL_WIDTH } from "./control_surface";
+import { CONTROL_RADIUS, MIN_CONTROL_WIDTH, CARD_RADIUS } from "./control_surface";
 import { EmptyState } from "./empty_state";
 import { Icon } from "./icon";
 import { IconButton } from "./icon_button";
@@ -40,7 +40,6 @@ import { usePointerDrag } from "./use_pointer_drag";
 /** A card is a container, so it sits on the container rung of the radius ladder
  *  — the same 16 a `Card` takes. Kept here rather than imported so the two
  *  cannot drift apart silently; if the ladder moves, both move. */
-const CARD_RADIUS = 16;
 
 /** Half the difference between an `sm` IconButton's box (24) and its glyph (14).
  *  It exists so a control cluster can be pulled out by exactly the amount that

package/src/calendar/agenda_view.tsx

@@ -0,0 +1,136 @@
+import { useMemo } from "react";
+import { ScrollView, View, StyleSheet } from "react-native";
+import { Text } from "../text";
+import { colors, solid } from "../colors";
+import { CARD_RADIUS } from "../control_surface";
+import { ListItem } from "../list_item";
+import { useCalendar } from "./context";
+import { compareEvents, isBanner } from "./layout";
+import { dayDiff, dayHeading, daysInView, formatTime, isToday, startOfDay } from "./dates";
+import type { CalendarEvent } from "./types";
+
+/**
+ * The agenda: days as headings, their events as rows.
+ *
+ * **This is the narrow-screen answer, and it is a different SHAPE rather than a
+ * smaller month grid.** Seven equal columns on a 375px screen leave 53px per
+ * day for titles that need 160 — every event reads "Cont…" and the calendar can
+ * only tell you WHICH days have something, never what. Below `compactBelow` the
+ * root mounts this instead, and the one app that hit this had already reached
+ * the same conclusion by hand, wrapping the grid in a horizontal scroller with
+ * a 760px floor.
+ *
+ * Empty days are omitted. A month is mostly empty days, and printing thirty
+ * "nothing scheduled" rows to find four with content is not a list, it is a
+ * haystack.
+ */
+export function CalendarAgenda() {
+  const { events, date, weekStartsOn, locale, labels, now, onEventPress } = useCalendar();
+  const days = useMemo(() => daysInView("agenda", date, weekStartsOn), [date, weekStartsOn]);
+
+  const grouped = useMemo(() => {
+    const first = days[0];
+    const byDay = days.map((day) => ({
+      day,
+      items: events
+        .filter((e) => {
+          const from = dayDiff(startOfDay(e.start), day);
+          const to = dayDiff(day, startOfDay(e.end ?? e.start));
+          if (from < 0 || to < 0) return false;
+          // A multi-day banner is listed ONCE, on the day it starts — or on the
+          // first day of the range when it started before it, so something
+          // already running is still visible. Repeating it per day put a
+          // 28-day campaign on twenty-eight rows and buried everything that
+          // only happens once.
+          if (!isBanner(e)) return true;
+          const startsHere = startOfDay(e.start).getTime() === day.getTime();
+          const ongoingAtOpen =
+            day.getTime() === first.getTime() && startOfDay(e.start).getTime() < first.getTime();
+          return startsHere || ongoingAtOpen;
+        })
+        .sort(compareEvents),
+    }));
+    return byDay.filter((g) => g.items.length > 0);
+  }, [events, days]);
+
+
+  if (grouped.length === 0) {
+    return (
+      <View style={styles.empty}>
+        <Text size="sm" color="muted">{labels.noEvents}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <ScrollView style={styles.root} contentContainerStyle={styles.content}>
+      {grouped.map(({ day, items }) => {
+        const today = isToday(day, now);
+        return (
+          <View key={day.toISOString()} style={styles.group}>
+            <View style={styles.heading}>
+              <Text size="sm" weight={today ? "semibold" : "medium"} style={today ? styles.todayInk : undefined}>
+                {dayHeading(day, locale)}
+              </Text>
+              {today ? <View style={styles.todayDot} /> : null}
+            </View>
+            <View style={styles.card}>
+            {items.map((e) => (
+              <ListItem
+                key={e.id}
+                left={<View style={[styles.dot, { backgroundColor: solid(e.color ?? "teal") }]} />}
+                title={e.title}
+                description={describe(e, labels.allDay, locale)}
+                onPress={onEventPress ? () => onEventPress(e.id) : undefined}
+              />
+            ))}
+            </View>
+          </View>
+        );
+      })}
+    </ScrollView>
+  );
+}
+
+/** The row's second line: when it is, then whatever the event carries. Never
+ *  the title again — the row above it already said that. */
+function describe(event: CalendarEvent<unknown>, allDayLabel: string, locale?: string): string {
+  const when = isBanner(event)
+    ? bannerSpan(event, allDayLabel, locale)
+    : event.end
+      ? `${formatTime(event.start, locale)} – ${formatTime(event.end, locale)}`
+      : formatTime(event.start, locale);
+  return event.meta ? `${when} · ${event.meta}` : when;
+}
+
+/** A banner listed once has to say how far it runs, or the row claims the whole
+ *  thing happens on the day it is filed under. */
+function bannerSpan(event: CalendarEvent<unknown>, allDayLabel: string, locale?: string): string {
+  const end = event.end ? startOfDay(event.end) : null;
+  if (!end || dayDiff(event.start, end) <= 0) return allDayLabel;
+  const md = (d: Date) => new Intl.DateTimeFormat(locale, { day: "numeric", month: "short" }).format(d);
+  return `${md(event.start)} – ${md(end)}`;
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.white },
+  content: { paddingBottom: 16 },
+  group: { paddingTop: 0, paddingHorizontal: 8 },
+  card: { borderRadius: CARD_RADIUS, overflow: "hidden", backgroundColor: colors.zinc[50] },
+  // A day heading is separated by SPACE and weight, not a rule — the rule was
+  // a second statement of a boundary the gap already makes.
+  heading: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingHorizontal: 14,
+    paddingTop: 16,
+    paddingBottom: 6,
+  },
+  todayInk: { color: colors.teal[700] },
+  todayDot: { width: 6, height: 6, borderRadius: 3, backgroundColor: colors.teal[600] },
+  // A dot, not a bar down the row's left edge: an edge is a border, and the
+  // row's own wash already states where it begins.
+  dot: { width: 8, height: 8, borderRadius: 4 },
+  empty: { flex: 1, alignItems: "center", justifyContent: "center", padding: 24, backgroundColor: colors.white },
+});