fold-ng 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -8,6 +8,554 @@ All notable changes to **fold-ng** are documented here. The format follows
 
 _Nothing yet._
 
+## [0.9.0] - 2026-08-04
+
+### Changed
+
+- **BREAKING — the shell owns the content scroll by default; pages flow.** The
+  all-in-one scroll model (`docs/scroll.md`), slice A. `fold-app-shell`'s
+  `contentScroll="clip" | "auto"` input is **renamed and reshaped** to
+  `scroll="scroll" | "stage"`, and the **default flips**: the shell's content
+  region now owns the scroll (`scroll`, was `clip`/page-owns), so a
+  `fold-page-layout` inside it no longer double-scrolls. `fold-page-layout` gains
+  `scroll="flow" | "own"` and **defaults to `flow`** — it owns no scroll box and
+  flows inside the shell. Net effect for a normal page: identical, minus the P0
+  bug where a `footerBehavior="scroll"` footer sat below an unreachable
+  `overscroll-behavior: contain` boundary (this **deletes the LaFolieDouce B2B
+  `!important` workaround**). The scroll lives on an **inner** box, never the
+  content region itself, so a docked panel anchored to the region stays fixed
+  over the frame. Migration: a page that must scroll as a self-contained unit
+  (a split view whose shell must not move) sets `fold-app-shell scroll="stage"`
+  and/or `fold-page-layout scroll="own"`. A short page still pins a trailing
+  `scroll` footer to the bottom (the content grows to fill), replacing the old
+  `margin-top: auto` glue.
+
+- **`@angular/router` is now a declared (optional) peer dependency.** `fold-view-nav`
+  imports `RouterLink`/`RouterLinkActive`, but the package only listed router as a
+  devDependency — an undeclared peer that happened to resolve because every Angular
+  app ships Router. It's now in `peerDependencies` with `peerDependenciesMeta:
+{ "@angular/router": { optional: true } }`, so apps that use the router-coupled
+  nav components (view-nav, and the new breadcrumb / back-link) get a correct
+  install signal, while apps that don't aren't forced to add it (those components
+  tree-shake out). No API change.
+
+- **`FoldPanelHostService.open()` accepts an optional-data panel without a manual
+  type widen.** A panel whose `data` input is optional (`data = input<T>()` →
+  `InputSignal<T | undefined>`) used to force `open<T | undefined, R>()` to dodge
+  a `TS2345` (hit by the LaFolieDouce B2B PickupPanel). `FoldPanelContent<T>.data`
+  is now typed as the covariant **read** side (`Signal<T | undefined>`) instead of
+  the invariant `InputSignal<T>`, so both a required (`input.required<T>()`) and an
+  optional data input satisfy the contract — `open(Cmp, { data })` infers `T` from
+  the value with no widen, and the data value stays type-checked. Non-breaking for
+  existing panels (an `InputSignal<T>` still assigns to the contract).
+
+### Added
+
+- **House scrollbar tokens + `overflow-anchor` — scroll-system Slice C.** The
+  shell content scroll box and every `[foldScrollRegion]` now paint one tokenised
+  scrollbar: `--fold-scrollbar-size` / `-radius` / `-thumb` / `-track`, with the
+  thumb derived from the surface's own text so it adapts per theme **and** per
+  surface (a chrome rail vs the page). Standard `scrollbar-width`/`scrollbar-color`
+  everywhere, plus a `@supports selector(::-webkit-scrollbar)` layer (shipped in
+  `tokens.css`) for the thumb radius on Blink/WebKit. Both regions also set
+  `overflow-anchor: auto` so the reading position survives content reflowing above
+  them. (The `--fold-scrollbar-*` knobs are component vars, out of the colour
+  catalogue — retune them on any ancestor. The viewport-**resize** anchoring
+  correction, which native `overflow-anchor` doesn't cover, is a deferred
+  follow-up — see `docs/scroll.md`.)
+
+- **`[foldScrollRegion]` + the shell scroll registry — scroll-system Slice B.**
+  The one opt-in of the scroll model (`docs/scroll.md`): with `fold-app-shell`
+  owning the page scroll, a layout that needs an independently-scrolling area (a
+  split list/detail, a data-table body, a sticky sidebar, a panel body) marks it
+  with `[foldScrollRegion]` instead of hand-rolling `overflow`. The directive sets
+  the three foot-guns (`overflow`, `min-*: 0`, `overscroll-behavior: contain`) and
+  the thin house scrollbar, and takes an axis (`block` default · `inline` · `both`).
+  It **registers with the new `ScrollRegionRegistry`**, which the shell also feeds
+  with its own content scroll box; the panel host freezes the registry when a
+  modal opens, so the page stops scrolling behind the overlay even though the
+  scroll owner is an inner box, not `document.body`. Freezing toggles a
+  `.fold-scroll-frozen` class (`overflow: hidden !important`, shipped in
+  `tokens.css`), never an inline write, so a region's own overflow is never
+  clobbered. Registry injection is optional, so the directive is a useful bounded
+  scroll box even without a shell. Gallery `/scroll-region`; 19 specs. (Migrating
+  the data-table / panel bodies onto it is deferred — they already scroll
+  correctly; the win there is registry coordination, not the overflow.)
+
+- **`fold-back-link` — the “← Back” affordance for a detail page.** Three modes,
+  picked by which input is set: an in-app `routerLink`, a plain `href`, or — with
+  neither — a `<button>` that goes **back in history** (`Location.back()`).
+  Router-coupled but degradable (the history mode needs no router; `RouterLink`
+  only instantiates on a `routerLink`). Gallery `/back-link`; 4 specs.
+
+- **`fold-breadcrumb` — a hierarchical link trail.** Data-driven: pass `[items]`
+  where each crumb links by an Angular `routerLink` **or** a plain `href`, so it
+  works in a router app and degrades to anchors without one (importing it never
+  forces `@angular/router` — `RouterLink` only instantiates on a crumb that sets
+  `routerLink`). The last item renders as the current page (`aria-current="page"`),
+  never a link; it's a `navigation` landmark with decorative chevron separators.
+  Gallery `/breadcrumb`; 5 specs.
+
+- **Panel bottom sheet (`side: 'bottom'`) + responsive `side: 'auto'`.** The panel
+  host gained two docking edges beyond `left`/`right`: `bottom` is a full-width
+  sheet whose height is content-driven up to a max (`85dvh`) with the body
+  scrolling, slides up, rounded top, and a top **grabber** that taps to dismiss
+  (honours `disableClose`). `auto` docks **right on a wide host, bottom on a
+  narrow one** — the switch is container-driven via `@container` on the panel
+  host's own inline-size (fold's "responsive on its own width", not the viewport),
+  so it reacts to the content region, not the screen. All the modal machinery
+  (focus-trap, `inert` barrier, scroll-lock, `disableClose`) is edge-agnostic and
+  reused as-is. Motivated by the LaFolieDouce storefront cart on mobile. Gallery
+  `/panel` gained “Bottom sheet” + “Auto (by width)” triggers; +6 host specs.
+  (Pointer-drag-to-dismiss on the grabber is a deferred nice-to-have.)
+
+- **`fold-panel-footer` — the action bar for panels/dialogs.** Pairs with
+  `fold-panel-header`: the tokenised bar at a panel's bottom edge (glass top
+  border + padding + button alignment), so a panel no longer hand-rolls a
+  `<footer class="foot">`. `align="end"` (default — the Annuler/Confirmer pair)
+  · `between` (a leading total + trailing actions) · `start`. Sits with
+  `flex: none`, so it stays pinned while the body scrolls — no `position: sticky`.
+  Probed against the 2nd consumer (LaFolieDouce): **17** hand-rolled panel footers
+  across its 3 apps, so it earns a primitive. Gallery `/panel` “Panel footer”; 3 specs.
+
+- **`fold-danger-zone` — the destructive-action block.** A framed region for
+  “delete X” settings: a title, a projected explanation, and a guarded action.
+  **Two appearances** — `filled` (alert-tinted block) and `section`, a danger
+  _section_ with a **normal-background body** so it can host ordinary content, only
+  the frame + heading signalling danger (the GitHub “Danger Zone” look). The
+  destructive control's confirm **reveals on click**: an `actionLabel` button
+  opens an in-place `fold-inline-confirm` — a plain “are you sure?”, or a
+  type-to-confirm field when `confirmPhrase` is set (the input is never shown until
+  the button is clicked). `(confirmed)` emits the typed text (or `""`); omit
+  `actionLabel` for a framed section with no action. `role="group"` +
+  `aria-labelledby`. Gallery `/danger-zone`; 5 specs.
+
+- **`fold-multiselect` bulk actions — `allowSelectAll` / `allowClear`.** A sticky
+  bar at the top of the panel offers **Select all** (adds every enabled option,
+  skipping disabled rows and preserving an already-picked disabled one) and
+  **Clear** (empties the set). Each button is gated — select-all disables once
+  everything enabled is picked, clear disables while empty. Labels are overridable
+  (`selectAllLabel` / `clearLabel`). The panel is now a wrapper around the
+  `role="listbox"` (the bar sits outside it, so it stays valid ARIA). Gallery
+  `/listbox` multiselect tab enables both; 5 specs.
+
+- **`fold-optgroup` — labelled option groups for the styleable selects.** The
+  counterpart to the native `<optgroup>`: wrap `<fold-option>`s in
+  `<fold-optgroup label="…">` to sort a long list into sections. Purely
+  presentational — the owning `fold-listbox` / `fold-multiselect` now discovers
+  options with a `descendants: true` query, so grouped options join the same
+  flat, document-ordered list the roving keyboard core walks; the header carries
+  `role="group"` + `aria-labelledby` (no `role="option"`), so nav skips straight
+  over it. Also supported in the data-driven **`[options]` array API**: an entry
+  is a `FoldSelectOption<T>` or a labelled `FoldSelectOptionGroup<T>` (mix both),
+  narrowed by the exported `isFoldSelectOptionGroup` guard. Gallery `/listbox`
+  “grouped” tab shows both forms; specs cover projected + array discovery,
+  cross-group roving and selection.
+
+- **The icon devtool browses by category.** `FoldIconDevtoolComponent` now
+  groups the live registry into **collapsible sections** — UI · Navigation ·
+  Commerce · Music · Status · People · Brands (+ a **Custom** bucket for
+  host-registered icons) — each with its icon count; a search only surfaces the
+  categories it hits. New public `FOLD_BUILTIN_ICON_CATEGORIES` (+ `FoldIconCategoryId`)
+  is the single source of truth for the grouping (each icon file owns its slice).
+
+- **`fold-ng/devtools` now builds as a real ng-packagr secondary entry**, so
+  `import("fold-ng/devtools")` resolves for **published (npm) consumers**, not
+  only source-consumed ones. It compiles to its own FESM + `d.ts` and imports the
+  primary `fold-ng` by name; `finalize-dist` normalises ng-packagr's flattened
+  `./src/devtools` export to the public `./devtools` subpath (+ a node10 directory
+  manifest). `attw` all-🟢, `publint` clean. The api-surface guard was generalised
+  to snapshot every published entry point (`.` + `./devtools`).
+
+- **`fold-ng/devtools` — an opt-in dev-tools entry, starting with
+  `FoldIconDevtoolComponent`.** A **dev-only** floating panel that browses the live
+  `FoldIconRegistry` (built-ins + whatever the host app registered), with a search,
+  a preview grid, and a mini playground that builds a `<fold-icon>` snippet and
+  copies it. The panel is **draggable** (grab the header) and **minimisable**
+  (collapses to a pill). Published from a **separate entry** so it never lands in a
+  bundle that doesn't ask for it — import it behind a dev guard
+  (`if (isDevMode())` + a dynamic `import("fold-ng/devtools")`) so production
+  tree-shakes it away. Dogfooded in the gallery (primary-rail "Dev tools" + the
+  `/icons` hero CTA).
+- **`FoldIconRegistry.names()`** — the sorted list of every registered icon name
+  (built-ins + runtime additions), reactive. Powers catalogue tooling (the icon
+  devtool).
+
+- **A `commerce` icon category — 21 e-commerce glyphs.** The built-in set had no
+  cart, catalogue, payment or fulfilment icons, so a consumer reused `package` as a
+  placeholder for both a cart and a delivery tab (`docs/consumer-friction.md` Round
+  4 #3). New `COMMERCE_ICONS` (the 7th category, wired into `FOLD_BUILTIN_ICONS` and
+  the `/icons` gallery): `shopping-cart` · `shopping-bag` · `basket` · `package` ·
+  `package-check` · `tag` · `tags` · `barcode` · `qr-code` · `gift` · `credit-card`
+  · `wallet` · `receipt` · `coins` · `banknote` · `percent` · `truck` · `store` ·
+  `warehouse` · `map-pin` · `package-return`. Same self-contained inlined-SVG /
+  `currentColor` contract; names autocomplete on `FoldIconName`.
+
+- **`fold-textarea` — the multiline sibling of `fold-input`.** Same box chrome
+  (tokens, sizes, `panel` variant, focus/disabled) via `input-shell.scss` and the
+  same label / required / hint / error chrome via `fold-input-base` — so a note
+  field is no longer a hand-rolled native `<textarea>` + copied box CSS. **No
+  resize handle by design**: the box keeps its `rows` height and **wraps +
+  scrolls** overflow (`resize: none; overflow-y: auto`), so a user-dragged corner
+  can't break a panel layout. `FormValueControl<string>` (`[formField]` or
+  `[(value)]`).
+- **`fold-date` + `fold-time` — the temporal-field wrappers.** Two sibling
+  controls (distinct selectors for call-site clarity, the same "one control, one
+  job" split as `fold-input` vs `fold-number-input`): `fold-date` wraps the native
+  `<input type="date">` family (`type`: `date` · `datetime-local` · `month` ·
+  `week`), `fold-time` wraps `<input type="time">`. Both wrap the native control
+  the way `fold-select` wraps `<select>` — keeping the OS calendar/clock + mobile
+  keyboard — and hand back a **typed `[(value)]`** (the native string, `YYYY-MM-DD`
+  / `HH:mm`), so consumers stop hand-writing an `inputValue($event)` reader.
+  `min` / `max` / `step` pass through; both share the `fold-input` box + field
+  chrome. **Not** a calendar popover (that's the `fold-calendar` family) — the plain
+  fields. `FormValueControl<string>`.
+- Surfaced by the 2nd consumer (LaFolieDouce B2B); see `docs/consumer-friction.md`
+  Round 4 #2. The shared `_field-box.scss` `size()` mixin gained a `$height: false`
+  opt-out (a `<textarea>`'s height is content-driven), and `readInputValue` now
+  reads `<textarea>` targets.
+
+## [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 +1263,10 @@ 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.9.0...HEAD
+[0.9.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.9.0
+[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