fold-ng 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -8,6 +8,347 @@ All notable changes to **fold-ng** are documented here. The format follows
 
 _Nothing yet._
 
+## [0.8.1] - 2026-08-02
+
+### Changed
+
+- **The visual-snapshot tier is no longer a release gate.** Pixel screenshots
+  against a live dev server drift for reasons that are not a regression — a
+  scrollbar toggling or a font hint moves the frame ~20px — and the baselines
+  are per-platform, so gating on them turned the release red on Linux CI _and_
+  intermittently on the Mac it was cut from. The shots are now tagged `@visual`
+  and run only via `pnpm test:e2e:visual` (a local eyeball aid); the gate
+  (`test:e2e`, used by CI and `pnpm release`) excludes them. The geometry that
+  matters stays gated, and stably, by measurement in `calendar.spec.ts`. `0.8.0`
+  was tagged but never published because of this — `0.8.1` is the first published
+  cut of the 0.8 line, and carries the whole calendar family.
+
+## [0.8.0] - 2026-08-02
+
+### Added
+
+- **A calendar family, starting with `fold-calendar-month` and the plain-date
+  model it stands on.** The grid is a date axis: seven columns of whole days,
+  and over them a layer of **bands**, each stretching from the column its event
+  starts on to the column it ends on. A span crossing a week is drawn once per
+  week with an open edge on the side that continues, so a three-week holiday
+  reads as one thing rather than twenty-one chips. Bands pack into lanes
+  (earliest start, then longest) under a `maxLanes` budget, and whatever will
+  not fit becomes an overflow chip **in the column of each day that lost
+  something** — a hidden span counts against every day it would have covered,
+  so the chip says _which_ day to open rather than only that the week is
+  crowded, and `overflowClick` emits that day. Events sharing a `groupId`
+  collapse into one chip spanning the union of their ranges and carrying the
+  count; a half-day edge is kept only on the segment holding the event's real
+  edge. Inputs cover `weekStartsOn` (any anchor, not just Monday), `fixedWeeks`,
+  `locale` and `labels`; `month` is a two-way `model`, so keyboard paging writes
+  back. Project an `<ng-template foldCalendarEvent>` to replace the built-in
+  chip. Generic over `T`, so an event's `data` survives the round trip to
+  `eventClick` without a cast.
+- **`fold-calendar-agenda` — a rail of what is still ahead, grouped by day.**
+  The counterpart to the grids: they answer "what does this month look like",
+  it answers "what do I do next". Its `todo` slice keeps only the events asking
+  for attention — the `warning` and `alert` tones, the **same scale the chips
+  paint with**, so the rail needs no second notion of urgency — and carries the
+  count as a badge. An event already running is filed under the boundary rather
+  than its real start, so a three-week absence that began last week sits at the
+  top of what's next instead of in a past day the rail never shows. Days inside
+  the next week are named relatively ("Today", "Tomorrow", then the weekday),
+  which reads faster than a date at that distance. `mode` and `collapsed` are
+  two-way `model`s — persist the collapse if you want it to stick; the package
+  stores nothing. Pure `foldBuildAgenda` / `foldCountActionable` behind it.
+- **`fold-calendar-source-filter` — chips that switch each feed of a merged
+  calendar on and off.** A calendar usually merges several feeds (a programme,
+  staff leave, contracts); an event names its own with `sourceKey`, a
+  `FoldCalendarSource` declares the label and dot, and the chips count what each
+  contributes. They own the **selection only** — the caller runs the pure
+  `foldFilterBySource()` over its own events, so the chips never learn how
+  anything is fetched. An event with no `sourceKey` belongs to no feed and no
+  chip can hide it. Each chip is a real toggle (`aria-pressed` in both states)
+  whose accessible name says which feed and whether it is showing, because the
+  tick and the dot are colour and colour cannot be the only carrier.
+- **`fold-calendar-toolbar` — the chrome that makes the views one calendar.**
+  Jump to today, page back and forward, the period's name, and the view switch.
+  It owns no data: both pieces of state are two-way `model`s, so a page binds
+  the same `date` and `view` it hands the view on screen and paging works with
+  no output handler. The step matches the reading — a month under the month
+  view, a week under the week view, a day under the day view. The title carries
+  `aria-live="polite"`, so paging announces where a keyboard user landed instead
+  of changing silently. Backed by pure `foldShiftDate`, `foldRangeForView` (the
+  window a caller fetches — the whole painted grid for a month, not just its
+  days) and `foldViewTitle`.
+- **The three column views that complete the drill-down: `fold-calendar-week`,
+  `fold-calendar-day` and `fold-calendar-list`.** Where the month grid packs
+  spans into lanes, these simply list what covers each day — so nothing is
+  clipped and no lane budget can hide anything. `week` is seven day columns;
+  `day` is one day in full, with a tag-qualified `button[empty]` slot for a "new request" action
+  when nothing sits on it; `list` is the flat chronological reading, each row
+  led by its span (formatted with `Intl`'s own range formatter, which collapses
+  a single day to one date and factors out a shared month). All three take the
+  same `foldCalendarEvent` template, labels and `locale` as the month view.
+  Their a11y is **simpler than the month's on purpose**: because a chip nests
+  inside the day it belongs to rather than spanning columns, every control is a
+  real child in the natural tab order — no roving tabindex, no `aria-hidden`,
+  every event reachable by keyboard. New pure builders `foldBuildWeek` and
+  `foldBuildDay` back them.
+- **`FoldCalendarDate` — the package's date primitive is a plain
+  `YYYY-MM-DD` string, not a `Date`.** A calendar of all-day spans deals in
+  dates, not instants: `new Date("2026-05-18")` is UTC midnight, i.e. the 17th
+  anywhere west of Greenwich, and that off-by-one is the most common calendar
+  bug there is. Strings remove the class by construction, compare
+  lexicographically (`a <= b` _is_ "on or before"), are `===`-equal when they
+  mean the same day, and are already the wire format. Arithmetic runs through
+  `Date.UTC`, so no DST boundary can repeat or skip a day. Ships with
+  `foldToday`, `foldAddDays`, `foldAddMonths`, `foldStartOfWeek`,
+  `foldStartOfMonth`, `foldEndOfMonth`, `foldDaysBetween`, `foldWeekdayIndex`,
+  `foldWeekdayOf`, `foldIsWeekend`, `foldIsCalendarDate`, `foldToNativeDate` and
+  `foldFromNativeDate` (the inbound bridge — the conversion every consumer would
+  otherwise write as `toISOString().slice(0, 10)`, which is the very timezone bug
+  this design exists to remove), plus the layout entry points
+  `foldBuildMonthGrid`, `foldBuildWeek`, `foldBuildDay`, `foldEventsOnDay`,
+  `foldEventsInRange` and `foldFilterBySource`. Supported range is
+  `0001-01-01`–`9999-12-31`: the four-digit year is what makes the lexicographic
+  guarantee hold, so it is enforced rather than assumed.
+  `fold-timeline` keeps a native `Date` on purpose — it plots dated _instants_,
+  which is the other domain.
+- **Month and weekday names come from `Intl`, not from a label token.** The
+  `locale` input drives `Intl.DateTimeFormat`, so every locale works without
+  hand-translating twelve month names; `FoldCalendarLabels` (with
+  `provideFoldCalendarLabels`) covers only what `Intl` cannot supply — the today
+  marker, the overflow chip and the event count.
+
+- **Everything the calendar draws _around_ an event is a projectable template.**
+  The chip was replaceable from day one; the containers were not, which had it
+  backwards — an app could restyle the smallest unit and not the cell behind it.
+  Four more `<ng-template>` seams, each with a typed context and an
+  `ngTemplateContextGuard` (so `let-` variables are real types under
+  `strictTemplates`, not `any`): **`foldCalendarDay`** replaces the inside of a
+  month cell — the hook for a public holiday, a closure, "3/8 staffed";
+  **`foldCalendarHeading`** replaces the agenda's day heading;
+  **`foldCalendarTitle`** replaces the toolbar's `<h2>`, which also lets a page
+  give the title the heading level its outline needs; **`foldCalendarOverflow`**
+  replaces the `+N` chip. Alongside them, `dayModifiers: (day) => string[]`
+  emits an app's own names as one `data-fold-day-modifiers` attribute, matchable
+  with `[data-fold-day-modifiers~="holiday"]` — so nobody has to write CSS
+  against an internal class name. `foldCalendarEvent` is now generic too, so
+  `event.data` comes back as the app's own record.
+- **`fold-calendar-timegrid` — the reading the other four cannot give: when
+  _inside_ a day.** Hour columns for a week or a single day (`dayCount`), with
+  the all-day strip on top. A meeting is a block whose height is its duration
+  and whose width is shared with whatever it collides with; an absence is a band
+  across the strip, spanning days through **the same packer the month grid
+  uses** — extracted rather than copied, so a three-day leave request reads
+  identically in both.
+
+  Time is modelled as wall-clock `HH:mm` (`FoldCalendarTime`), **not an
+  instant** — the same decision as the date, for the same reason: 09:00 is the
+  hour on the wall, and an instant re-derives that from a zone every render,
+  which is one wrong default away from drawing the wrong hour. The app converts
+  once at its own boundary.
+
+  Two details that are the difference between a real time grid and a demo: the
+  overlap test is **exclusive** at the boundary, so back-to-back meetings keep
+  the full width instead of each taking half; and events are grouped into
+  **clusters**, so one triple-booked morning does not narrow an unrelated
+  afternoon. A span crossing midnight becomes one block per day, each with the
+  right open edge, rather than one impossible block running off the bottom.
+
+  `now` is an input, never a clock the package reads — `today` already works
+  that way, and a server render that invented one would hydrate to a different
+  position. Positions are **fractions of the visible window**, so `dayStart` /
+  `dayEnd` and the CSS height stay independent. Backed by pure
+  `foldBuildTimeGrid` and `foldLayOutOverlaps`.
+
+- **`foldFromTemporal` — the family is Temporal-native without depending on
+  it.** `Temporal.PlainDate.toString()` **is** `YYYY-MM-DD`: the primitive
+  chosen for correctness turns out to be exactly Temporal-shaped, which no
+  `Date`-based calendar can say. The bridge accepts a `PlainDate`,
+  `PlainDateTime` or `ZonedDateTime` — typed structurally, so it compiles and
+  runs on an engine that has none of them — and drops the time, which is what a
+  whole-day calendar wants **and** keeps the day the value itself means rather
+  than the one UTC would have picked. The other direction needs no helper:
+  `Temporal.PlainDate.from(foldDate)` already accepts one of ours.
+- **The week now comes from the locale, not from a guess.** `Intl.Locale`
+  knows which day a locale's week opens on and which days it rests — most
+  calendars stop at the month names and hard-code Monday, which is right in
+  Paris and wrong in Chicago, Cairo and Malé. `weekStartsOn` and `weekendDays`
+  default to `foldLocaleWeekInfo(locale)` and stay overridable, so the common
+  case needs no input at all. Both `getWeekInfo()` and the older `weekInfo`
+  getter are probed, and a runtime with neither falls back to Monday + Sat/Sun.
+- **ISO week numbers, as an optional leading column.** `showWeekNumbers` on
+  `fold-calendar-month`, backed by `foldIsoWeek` / `foldIsoWeekYear`. ISO weeks
+  start on Monday and belong to the year holding their **Thursday**, so they are
+  deliberately _not_ derived from the calendar's own anchor — 1 January is
+  sometimes week 53 of the year before, which is the whole point of the rule and
+  the reason European B2B reporting asks for it. The column is a real grid
+  track, so every placed element — cells, bands, overflow chips — shifts with it.
+- **A `formats` input beside `labels`.** Labels let a locale translate; this
+  lets it **reformat**. Every `Intl` option bag the family uses lives in one
+  table (`FOLD_CALENDAR_FORMATS`, now exported); `formats` merges over it per
+  instance — a narrow weekday header, a numeric month, a four-digit year.
+- **A print stylesheet for the month.** Browsers drop backgrounds but keep text
+  colour, so a dark theme printed as-is is light-on-white — unreadable. The
+  print block re-expresses everything in system colours (`Canvas`/`CanvasText`/
+  `GrayText`), which are neither theme tokens nor hard-coded values, and asks
+  for ink on exactly one thing: the tone bar, the last cue telling two bands
+  apart on paper.
+- **The month layout is ~5× faster, and the benchmark ships with it.** The cost
+  was never the algorithm — it was the representation: every comparison in the
+  candidate sort called `foldDaysBetween`, which re-parsed two strings and built
+  two `Date`s, and the whole feed was re-filtered once per week row. Spans now
+  carry epoch-day bounds computed once, rows are bucketed in a single pass
+  (`O(rows × N)` → `O(N)`), and clipping is integer arithmetic. The public model
+  is unchanged — this is internal only. Measured on a month layout, mean of 20:
+  1 000 events 4.8 ms → **0.99 ms**, 5 000 28.9 → **5.0**, 20 000 124 → **22**.
+  `pnpm bench:calendar` re-runs it against a committed budget and exits non-zero
+  when a size blows it.
+- **`foldCalendarNextFocus` is public — the geometry tier is now complete.**
+  The pure builders (`foldBuildMonthGrid`, `foldBuildWeek`, `foldBuildDay`,
+  `foldBuildAgenda`) and the period functions (`foldShiftDate`,
+  `foldRangeForView`, `foldViewTitle`) let an app lay a calendar out and draw it
+  its own way; the arrow-key map was the one piece missing, and a hand-rolled
+  date grid owes its users the same keyboard as the built-in one. Documented as
+  a **tier** in the README rather than left as an accident of what happened to
+  be exported. `foldFocusDayCell` deliberately stays internal: it reads a
+  `data-fold-day` attribute this package writes, and exporting it would freeze
+  that attribute into the public contract.
+- **The view switch is open.** `FoldCalendarView` keeps the four built-ins as
+  autocompleting literals but accepts any string, and `views` takes
+  `{ value, label }` — so an app's own reading (a resource grid, a timeline) can
+  sit in the same toolbar without the library knowing about it. Paging and
+  titling an unrecognised view fall back to month semantics, which always lands
+  on a real date.
+- **A `FoldCalendarDay` now carries its own `eventCount` and `hiddenCount`.**
+  Both were previously recomputed per cell per change-detection cycle (an O(N)
+  filter, with an allocation, 35 times a tick) or exposed as a positional
+  `hiddenByDay` array only readable when crossed with the row's dates. Counting
+  once while the grid is built is both cheaper and self-describing, and it is
+  what lets a day cell announce "5 events, 2 not shown".
+
+### Changed
+
+- **A standalone `fold-view-nav` now separates itself from the content it heads
+  by the same gap a `fold-nav-layout` applies.** A horizontal bar used on its own
+  (outside a layout) gained a `margin-block-end` equal to `--fold-nav-layout-gap`
+  (default `--fold-space-lg`, 16px) — the value is now shared through a
+  `nav-content-gap` mixin (`layout/_nav-gap.scss`) that both the layout and the
+  bar `@use`, so the two can't drift and consumers stop hand-rolling a margin.
+  Applied only to a **standalone horizontal** bar: inside a `fold-nav-layout` the
+  layout still owns the gap (no double space), and a vertical bar is a side rail,
+  not a header. `fold-tabs` is unaffected (an in-place widget, not a bar that
+  introduces following content). Purely additive spacing — the layout's own
+  rendering is unchanged.
+
+- **The weekend is its own input, because it is its own fact.**
+  `foldIsWeekEnd(date, weekStartsOn)` defined the weekend as "the last two
+  columns", which shades **Friday and Saturday** on a Sunday-first calendar and
+  calls Sunday a working day. Replaced by `foldIsWeekend(date, weekendDays)`
+  with a `weekendDays` input (default `['sat', 'sun']`) on the month and week
+  views — the anchor moves the columns, it does not move the days people rest
+  on, and a Saturday-first calendar resting Fri+Sat is now expressible.
+- **`foldRangeForView('list')` returns the month, not the painted grid.** It
+  shared the month branch, so a May list showed late-April events: a month view
+  paints padding days and needs their events, a list has none.
+- **A projected template replaces a list row's whole inside**, as it already did
+  in the other four views. The bar and the date used to render outside the
+  branch, so the same template rendered differently depending on which view
+  hosted it, and a one-element template landed in a four-column grid.
+- **The month day cell is a `gridcell`, not a `<button>` wearing the role.**
+  `role="gridcell"` on a button replaces its native role, so activation is now
+  wired explicitly (`Enter`/`Space`) and the cell is the focusable widget the
+  ARIA grid pattern asks for. `role="grid"` and its accessible name moved onto
+  the host, which also removes the second root the keyboard helper had to find.
+- **`fold-calendar-week`'s `date` is a plain input.** It was a
+  `model.required` that the component never wrote to — a two-way binding
+  promising something it does not do. Pair it with the toolbar, which does own
+  the paging.
+- **The five views share one host directive for their chrome.** Labels, locale
+  and the projected chip template were eight identical lines copied five times,
+  and the `Intl.DateTimeFormat` option bags were duplicated with small
+  divergences — which is how the day view came to ask for
+  `{ weekday: 'long', month: 'long' }` and print "Saturday May", a phrase in no
+  locale. There is now one table of formats (`FOLD_CALENDAR_FORMATS`) and one
+  cache keyed by locale.
+- **Tones are written once.** The four roles were reimplemented in three places
+  (the month's bands, the shared chip, the list's rows, which had drifted into
+  its own copy); they are now one mixin parameterised by selector.
+- **RTL decorations follow the reading direction.** Continuation edges, the
+  chevrons, the cell separators and the chip padding were physical properties,
+  so a right-to-left calendar squared off the wrong side. All logical now.
+- **The label token drops `dateRange`** (declared, translated by consumers,
+  used nowhere — `Intl.formatRange` already orders a span per locale) and gains
+  `hiddenCount`, `agendaModes` and `agendaMore`.
+
+### Fixed
+
+- **Two events sharing an `id` no longer merge into one.** The layout keyed its
+  identity map on the id alone, so a duplicate was indistinguishable from an
+  explicit `groupId`: the second event was **never rendered**, both bands showed
+  the first one's label, a bogus group counter appeared, and the four column
+  views threw `NG0955` on their `track event.id`. Duplicates now stay separate,
+  with a dev-mode warning naming the id.
+- **`maxLanes` is clamped in one place, and coerced from an attribute.** The
+  invariant lived in two and only one enforced it: `maxLanes="2"` as a string
+  built an overflow row of `"22"`, a negative value made `repeat(-5, …)` and the
+  CSS parser dropped the whole `grid-template-rows` rule, and `NaN` **disabled
+  the lane budget entirely** (`lane >= NaN` is never true) so nothing was ever
+  counted as hidden.
+- **A reversed range (`end < start`) is put back in order.** Left alone it
+  rendered _twice, wrongly_: `grid-column: 5 / 2`, which CSS Grid silently
+  swaps, so a band covered four days that every other view — asking
+  `start <= day && end >= day` — reported as empty. Same input, two
+  contradictory renders, no error.
+- **A month that is not a date yields no grid, and says so.** `foldIsCalendarDate`
+  existed, was tested, and was called by nothing: `month="not-a-date"` produced
+  a `role="grid"` with headers and zero rows, and `month="2026-13-45"` produced
+  a December calendar displayed with total confidence.
+- **A collapsed group shows its most severe member.** It kept the first event in
+  document order and merged only the dates, so a cancelled first member greyed
+  out a whole group containing an alert, and an open-ended member inside a
+  closed group had its open edge dropped — a contract with no end drawn as
+  finished. Open edges are now the OR of the members, and the representative is
+  the most severe by tone (ties to document order), so tone, icon, label and
+  source all come from one event that really exists.
+- **The agenda's `limit` can no longer empty the rail.** `limit: 0` printed
+  "Nothing to handle — all up to date." directly under a badge saying otherwise,
+  and `NaN` did the same (`slice(0, NaN)` returns nothing). It now clamps to at
+  least one day and reports what it cut off, so "there is more" stops rendering
+  as "there is nothing".
+- **Paging with the keyboard twice in a row keeps the focus.** The deferred
+  focus target was a signal that was never reset, so repeating the _same_
+  transition wrote the same value, the effect did not re-run, and focus fell
+  onto `<body>`. The request is now consumed, and applied in an
+  `afterNextRender` rather than an `effect` — the ordering of an effect against
+  the DOM it wants to touch is not contracted, and has already changed between
+  Angular versions.
+- **The day view's `[empty]` slot no longer swallows a child.** `empty` is also
+  an input on `fold-data-table` and `fold-field`; an unqualified selector
+  captured either of them, and with no default slot the child simply vanished
+  (rule 4.8). Tag-qualified, with a default slot behind it and a projection test.
+- **Years below 100 no longer jump 1900 years.** `Date.UTC(99, …)` means 1999,
+  so `foldAddDays("0099-12-31", 1)` returned `"2000-01-01"`. Years are also
+  zero-padded to four digits, without which they sort before every other date.
+- **`foldFilterBySource` accepts `null`** — the initial value of the very model
+  it exists to consume. Every caller was writing the same ternary; the gallery
+  did too.
+- **The band icon takes the tone's colour**, and the collapsed agenda spine
+  names the slice it will open into rather than always saying "To handle". The
+  agenda's slice switch has its own accessible name instead of repeating the
+  rail's, and its badge honours a caller's `isActionable`, so it can no longer
+  disagree with the list under it.
+- **The calendar is now honestly Gregorian in every locale.** Names were
+  formatted in the locale's _own_ calendar system, so `locale="ar-SA"` printed
+  Hijri month names over the Gregorian day numbers the grid counts, on rows that
+  break on Gregorian months — a calendar contradicting itself. The `Intl`
+  formatters are pinned to `calendar: 'gregory'`, so a locale now localises the
+  _language_ of the names, not the calendar behind them. A true non-Gregorian
+  layout is a separate widget this family does not pretend to be.
+- **`foldIsCalendarTime` rejects an impossible minute field.** `"10:75"` and
+  `"23:60"` are `HH:mm`-shaped and under 1440 minutes, so a range check on the
+  total waved them through; the hour and minute fields are now validated
+  separately (`00:00`–`23:59`, plus `24:00`), the same rigour the date guard
+  applies to `2026-02-30`.
+
 ## [0.7.0] - 2026-07-29
 
 ### Added
@@ -715,7 +1056,9 @@ design-token stylesheet.
   `currentColor`; `prefers-reduced-motion` + `forced-colors` are respected;
   strings localise via inputs / providers (`provideFoldPanelLabels`).
 
-[unreleased]: https://github.com/hugoheynard/fold-ng/compare/v0.7.0...HEAD
+[unreleased]: https://github.com/hugoheynard/fold-ng/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.8.1
+[0.8.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.8.0
 [0.7.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.7.0
 [0.6.1]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.6.1
 [0.6.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.6.0

package/README.md

@@ -341,6 +341,56 @@ the package root.
 | `FoldPopoverComponent`                                   | `fold-popover`                         | Anchored floating layer — projected content in the native top layer (escapes `overflow`/`z-index`), positioned by a dependency-free **flip → size → shift** engine (`computePlacement`): a tall panel gets a `max-height` and scrolls inside the viewport. `[(open)]`; `autoUpdate` (ResizeObserver); optional `arrow`; native CSS enter/exit (`@starting-style` + `allow-discrete`); outside-click + `Escape` dismissal, focus-return, auto-wired `aria-haspopup`/`expanded`/`controls`.                                                                                                                                                                                                                                                                   |
 | `FoldDropdownComponent`                                  | `fold-dropdown`                        | Actions menu on `fold-popover` — `role="menu"` with `<fold-dropdown-item>`s, ↑/↓ roving, `Home`/`End`, type-ahead; opens onto the first enabled item, closes returning focus to the trigger. Give the trigger `foldPopoverTrigger="menu"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
+| `FoldCalendarMonthComponent` | `fold-calendar-month` | Month grid where events **span** the days they cover: a date-axis `role="grid"` with one roving tab stop, and over it a lane-packed layer of bands (one per week crossed, with open edges). `+N` chips sit on the crowded day, not at the end of the row. |
+| `FoldCalendarWeekComponent` | `fold-calendar-week` | Seven day columns of stacked chips — nothing spans, so nothing is clipped and every chip is a real button in the tab order. Container-queried: labels and icons drop out before they truncate. |
+| `FoldCalendarDayComponent` | `fold-calendar-day` | One day in full, with room for the subline — where a `dayClick` drill-down lands. Empty state takes a projected action (`button[empty]`). |
+| `FoldCalendarListComponent` | `fold-calendar-list` | The flat reading of the same feed, in date order, each row leading with the span `Intl` formats. Nothing is ever hidden behind a lane budget. |
+| `FoldCalendarTimegridComponent` | `fold-calendar-timegrid` | Hour columns for a week or a day, with the all-day strip on top. Timed events are placed on the clock and share their width only with what they actually collide with (exclusive boundaries, per-cluster widening); a span crossing midnight becomes one block per day. Times are wall-clock `HH:mm`, never instants; `now` is an input, not a clock. |
+| `FoldCalendarAgendaComponent` | `fold-calendar-agenda` | "What's next" rail grouped by day, with a **to-handle** slice (the `warning`/`alert` tones — the same scale the chips paint with) and a live badge. Collapses to a spine; `mode`/`collapsed` are models, so the app owns persistence. |
+| `FoldCalendarToolbarComponent` | `fold-calendar-toolbar` | Today / prev / next / period title / view switch. Owns no data — `date` and `view` are two-way, and the step matches the reading. `views` takes `{ value, label }` for an app's own view. |
+| `FoldCalendarSourceFilterComponent` | `fold-calendar-source-filter` | Chips switching each feed of a merged calendar on and off. Owns the **selection** only; the caller runs the pure `foldFilterBySource()`. |
+
+**Two tiers, on purpose.** The components are the first; under them, the same
+geometry is exported as pure functions — `foldBuildMonthGrid` (week rows with
+their events already packed into lanes), `foldBuildWeek` / `foldBuildDay`,
+`foldBuildAgenda`, plus `foldShiftDate` / `foldRangeForView` / `foldViewTitle`
+for paging and naming a period, and `foldCalendarNextFocus` for the arrow keys.
+Lay a calendar out without rendering it with these components, and the hard part
+— packing spans into lanes, clipping them at week boundaries, keeping an open
+edge on the side that continues — is already solved and already tested. The
+filters (`foldEventsOnDay`, `foldEventsInRange`, `foldFilterBySource`) are the
+tier every page uses whichever rendering it picks.
+
+**Measured, and kept measured.** Laying out a month (mean of 20 runs,
+`pnpm bench:calendar`, committed with a budget so it cannot regress quietly):
+
+| events in the window | 50   | 200  | 1 000 | 5 000 | 20 000 |
+| -------------------- | ---- | ---- | ----- | ----- | ------ |
+| ms per layout        | 0.14 | 0.41 | 0.99  | 5.0   | 22     |
+
+Calendar dates are plain `YYYY-MM-DD` **strings**, never `Date`. That is also
+exactly what `Temporal.PlainDate.toString()` returns, so the family is
+**Temporal-native without depending on it**: `foldFromTemporal()` accepts a
+`PlainDate`, `PlainDateTime` or `ZonedDateTime` (structurally typed, so it
+compiles on a runtime that has none of them), and going the other way needs no
+helper — `Temporal.PlainDate.from(foldDate)` already takes one of ours. See
+`foldToday` / `foldFromNativeDate` / `foldAddDays` and the reasoning in
+[`/calendar-dates`](https://hugoheynard.github.io/fold-ng/calendar-dates). The
+family plots on the **Gregorian** calendar and has no resource (staff × day)
+view. Whole-day spans are the month, week, day, list and agenda views; the
+**time grid** adds the hours, with time as wall-clock `HH:mm` rather than an
+instant — the app converts at its own boundary, and no zone can move a meeting
+after that.
+
+It is a **pure display**, by decision and not by omission: it knows nothing
+about what an event means or which layer produced it, so it never originates
+one — no drag-to-create, no range-select. Tone is the caller's to compute,
+which is what lets the same component paint a leave request and an account
+sitting open between registration and activation, its band crossing into
+`warning` then `alert` on a threshold the app owns. Everything drawn around an event is a projectable template:
+`foldCalendarEvent`, `foldCalendarDay`, `foldCalendarHeading`,
+`foldCalendarTitle`, `foldCalendarOverflow`.
+
 Directives worth knowing: **`foldSurface`** (`page`·`chrome` — the seam a mixed
 theme re-colours across), **`foldElevated`** (raise any bg-owning element into
 an inset, rounded, shadowed card — the per-surface "floating" mechanism, driven