@guildofgleks/ui 21.12.0 → 21.13.0

package/CHANGELOG.md

@@ -4,6 +4,618 @@ All notable changes to `@guildofgleks/ui` are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project has not yet
 reached 1.0, so breaking changes may land in minor versions.
 
+## [21.13.0] - 13.09.2026
+
+### Added
+
+- **`gog-table` windows its rows — `virtualize`, off by default, and it needed a second
+  primitive.** The dropdowns' `GogVirtualWindow` takes one row height, and a table cannot supply
+  one: **a table row's height cannot be pinned**, because `height` on a `<tr>` _and_ on a `<td>` is
+  a **minimum** in table layout. One cell taken from 40 to 600 characters measured 39px → 173.75px
+  under `table-layout: fixed`, with the column width unchanged, and neither `height` on the row nor
+  on its cells moved it.
+
+  So `GogVariableWindow` (internal, `lib/shared`): a height per row — measured where a row has
+  rendered, estimated everywhere else — with a prefix sum, so the range is a binary search rather
+  than a division. The three dropdowns keep the fixed-pitch one, which is exact where this is only
+  ever as right as the rows it has seen.
+
+  **It requires `maxHeight` and `fullWidth`, does nothing without either, and says which is missing
+  in a dev-mode warning.** Both are measured constraints rather than preferences: without
+  `maxHeight` the table never scrolls vertically on its own, so there is no viewport to window
+  against; and `fullWidth="false"` means `table-layout: auto`, where the browser sizes columns from
+  the rows that are _rendered_ — measured, rendering 2 of 24 rows moved columns by up to 7.8px, so
+  a windowed table would shift its own columns as you scroll.
+
+  The `<tbody>` spacers are `<tr>`s, since a table body takes rows and nothing else; a row honours
+  an explicit height exactly, including at 400 000px. **The ceiling is Chrome's, not the
+  library's:** an element clamps at 33 554 426px, about 745 000 rows at 45px — and a dev-mode
+  warning says so once when a table passes it, because past that the rows stay correct while the
+  scrollbar stops reaching the end of the data, which is not a symptom anyone traces back to a row
+  count.
+
+  **Three indices would have changed meaning silently, and all three are public promises**:
+  `gogRowClick`'s `index` (documented as the index within the page), the `showRowNumbers` column,
+  and `GogColumnBodyContext.index` in every consumer's cell template. Under a window `$index` is
+  the position in the rendered slice, so each keeps its name, its type and its documentation while
+  meaning something else. Specs fail without the fix with `expected +0 to be 196` and
+  `expected '1' to be '197'`. Checked rather than assumed on the other side: `toggleAllOnPage` and
+  the header checkbox still read the page, not the window — select-all would otherwise have
+  selected the twenty rows on screen while claiming a thousand.
+
+  **Two of the three things the plan called hard were not.** The sticky header lives in `<thead>`,
+  which a window over `<tbody>` never touches — pinned exactly at the viewport top across 200 000px
+  of scroll past a 400 000px spacer. The selection column is an ordinary `<td>` per row. That is
+  the third release running where the predicted hard part cost nothing.
+
+  **And one bug came out of the live pass that no spec would have suggested.** The effect that
+  clears cached heights on a new page or sort calls `reset()`, and `reset()` _reads_ the
+  measurement signal to decide whether it has anything to clear — so, called bare inside an effect,
+  that read became one of the effect's dependencies. Measuring wrote the signal, the effect re-ran,
+  and it cleared the measurements that had just been taken. **Nothing looked wrong**: the right
+  rows rendered at the right heights, and only the scroll height was quietly the estimate times the
+  row count, for ever. `untracked` is the fix and a regression spec now asserts it — it fails
+  without it on a spacer that is exactly `982 × 30`, a whole number of estimates.
+
+  The estimate is seeded from the **median** of the first rendered batch rather than its first row.
+  Taking row 0 was the first version, and the showcase's own demo is why it is wrong: it makes
+  every seventh row wrap, row 0 among them, so the estimate came out 65% high and all 10 000 rows
+  were sized from the one row that least resembles them.
+
+- **`gog-select` windows its option list — `virtualize`, off by default.** Measured in Chrome on
+  one page holding two selects over the same 10 000 options: the eager panel takes **512ms** to
+  appear and builds **10 000 rows to show six**; the windowed one takes **21ms** and holds **10**.
+  Both scroll through an identical 450 008px of content, because spacers stand in for the rows
+  that are not there. A per-field input, with `GOG_CONFIG.dropdown.virtualize` as the app-wide
+  default.
+
+  **Never automatic above some row count**, which is the same call `GOG_CONFIG.ripple.enabled`
+  makes: a windowed list differs from a plain one under `Ctrl+F`, under a screen reader's "list
+  all items", and under consumer CSS targeting `:last-child`, so flipping it when enough rows
+  happen to arrive is behaviour that depends on how much data turned up — it works in development
+  and surprises in production.
+
+  Under it, `GogVirtualWindow` in `lib/shared` (added below, internal): the arithmetic and nothing
+  that touches the page, so the component keeps its own scroller. The four things
+  `docs/virtualization.md` said were easy to get wrong all needed work, and three of them landed
+  differently from the plan:
+
+  - **The count stays honest.** `aria-setsize` and `aria-posinset` carry the real list and the
+    real index, so a listbox holding twenty rows is announced as ten thousand items. Set only
+    while windowing — an unwindowed list has every row present and the browser's own count is
+    both right and free.
+  - **The keyboard moves an index, not an element.** ArrowUp from the trigger means option 10 000,
+    which is not in the DOM to be focused: the index moves first, the scroll follows, and the row
+    is focused after the render that stamps it. `nextRovingFocusIndex` already existed as the
+    index half of the roving-focus helper, so the navigation rules — wrapping, skipping disabled,
+    Home/End meaning first/last _reachable_ — did not have to be written twice.
+  - **The panel's height is read from the scroller, not from a token.** The plan asked for a
+    `ResizeObserver`; `gog-scroll` already runs one and already coalesces scroll and resize into
+    one rAF-batched emission carrying both `scrollTop` and `clientHeight`, so `(gogScroll)` is the
+    whole answer and a second observer would have measured the same element a frame later. A
+    reported height of **zero** is ignored rather than believed: the scroller's first emission can
+    land before the panel has a height, and taking it literally renders the whole list for a frame
+    — the one thing the seed exists to prevent.
+  - **Filtering resets the window and the scroller together** — and this one is narrower than the
+    plan claimed. `GogVirtualWindow` already clamps a scroll position past the end of its own
+    list, so filtering 10 000 options down to three cannot render rows 400–420 of a three-row
+    list; the plan's own example is handled for free. The real case is a filtered list still long
+    enough to scroll, where the old position clamps to a **valid** position in the new list and
+    the search shows the end of its results. The first spec written for this passed with the reset
+    removed, which is how that was found.
+
+  One thing the plan did not have at all. **A row scrolled out of the window is unmounted, and an
+  unmounted element holding focus drops it on `<body>`** — where an open panel has no keyboard:
+  Escape does not close it and the arrows scroll the page. So a mouse scroll that would take the
+  focused row away hands focus back to the trigger first, which Escape and ArrowDown both work
+  from. It is checked before the re-render rather than after, because once the row is gone there
+  is nothing left to ask whether it was the focused one. This is a cost a plain list does not pay
+  and part of why windowing is opt-in.
+
+  `gog-multiselect`, `gog-autocomplete` and `gog-table` do not window yet.
+
+- **`npm run check:layering` — the library's own layering, as a build failure.** Two rules:
+  nothing in `lib/shared/` may import a component or a service, and no two units may import each
+  other. It exists because both were being broken and neither hurt anything: **a cycle is
+  invisible until something tries to cut along it.**
+
+  `shared/config.ts` imported `ToastPosition` from `services/toast-service`, which imports
+  `shared/config`. `shared/tooltip-overlay.ts` imported a component out of `components/tooltip/`,
+  which imports `shared/`. In one flat bundle, harmless. To a secondary entry point, fatal —
+  ng-packagr refuses a cycle between entry points outright — which is what makes this the
+  prerequisite for that work rather than tidying.
+
+  Both are fixed: `ToastPosition` moved to `shared/types.ts`, where
+  `gleks-ui-library.instructions.md` already said public types live, and is re-exported from the
+  service so the package's surface is unchanged; `tooltip-overlay.ts` moved into
+  `components/tooltip/`, which is its only consumer and the component it stamps. 36 units, no
+  cycles.
+
+- **`npm run check:glyph-box` — the first check in this repo that measures a rendering.** Every
+  other one reads source; this rule cannot be read honestly from source, because a glyph is
+  `--gog-icon-size` (1.2em) of its element's resolved font-size and **an `em` attaches to the
+  element carrying the property, not the one the value was written for**. Guessing that produced a
+  "fix" 25% worse at `slg` in this very release. So it serves the prerendered `ui-showcase`, walks
+  all 46 routes in Playwright against the installed Chrome, and compares every `<gog-icon>`'s
+  `<svg>` to the element holding it. 580 icons.
+
+  The rule has **no exemption list**, which no other check here can say: a box roomier than its
+  mark is fine, smaller never is.
+
+  **Two things went wrong in the check before it was right, and both are the lesson.** It first
+  walked every route on one page, so findings depended on visit order — the showcase persists
+  theme and density, and a route measured after the themes page inherited whatever it had left
+  set. And it compared against the _content_ box, which reported `gog-checkbox`: a 12px tick
+  spanning its own 2px outline, which is what a checkbox is. **The border box is the box.**
+
+- **`npm run check:tokens` rule K — a token `theme.css` declares that nothing reads.** The mirror
+  of rule F, which has always caught the opposite direction: a `var()` read with no declaration.
+  Nothing caught a declaration with no reader, so a component could ship a documented knob wired to
+  nothing and every gate this project has would pass. `--gog-menu-panel-gap` was exactly that for
+  the whole life of `gog-menu` (fixed below).
+
+  Reads are collected from component stylesheets, the global ones, `theme.css` itself **and
+  TypeScript**, because a token read only from script is still read. That last half took two
+  passes: TypeScript spells a token two ways — a bare name handed to `resolveLengthToken`, and a
+  whole declaration built as a string (`'var(--gog-control-checkbox-box-size-lg, 32px)'`, which a
+  host binding writes) — and the first version matched only the first shape, reporting **eight
+  live tokens as dead**. A check that cannot read half its inputs is worse than no check, because
+  its findings are what you act on.
+
+  Five exemptions, all steps of a complete public scale (`--gog-elevation-0`, two spacing aliases,
+  two type steps): a scale is offered whole or it is not a scale, and the consumer is the reader.
+  **Nothing belonging to a component may be exempted** — that is the defect the rule exists for.
+
+  It cannot see a dead _chain_: if A is read only by B's declaration and nothing reads B, both look
+  live. The leaf case is the one that has ever happened here.
+
+- **`gog-multiselect` and `gog-autocomplete` window too — the same `virtualize`, same default.**
+  Verified live in Chrome on 10 000 options each. Multiselect: 8 rows in the DOM, a 490 004px
+  scroll height matching the unwindowed list to the pixel, and row 2 036 sitting at 99 768px,
+  which is `2036 × 49 + 4` exactly. Autocomplete: 12 rows, `End` reaching option 10 000 with
+  `aria-activedescendant` on it and the panel scrolled to match.
+
+  Two things were specific to these two rather than shared, and both were real:
+
+  - **A spacer in a list that declares a row `gap` takes that gap on both sides of itself**, while
+    the window's padding already stands in for every gap between the rows it replaces. So the
+    spacer's height is the padding less one gap. `gog-multiselect` is the only one of the three
+    lists with a row gap, and uncorrected the panel was two gaps too tall and every row sat one
+    gap below where its index said. **A constant error, not an accumulating one**, which is why it
+    would have survived a reading: at the shipped 4px nothing looks wrong, it is just 4px wrong
+    everywhere.
+  - **A combobox names a row by id, and the id has to be the index in the whole list.** Focus
+    never leaves `gog-autocomplete`'s input, so the highlight travels by `aria-activedescendant`.
+    With the id keyed to the rendered slice it restarts at zero on every scroll, so the input
+    points at option 0 while the highlight paints a row in the middle — the two agreeing only
+    while the window happens to be at the top. Its spec fails that way without the fix
+    (`expected 'gog-autocomplete-35-option-10' to contain '-option-999'`).
+
+  `gog-autocomplete`'s keyboard needed nothing else: its active row was already an index into the
+  full list rather than an element, because the combobox pattern had put it there years before
+  windowing existed. Only `scrollIntoView` had to go — it needs an element, and the window's whole
+  point is that most of them are not rendered; the arithmetic knows where the row would be.
+
+  **`virtualize` and `gogLoadMore` are different halves and compose.** One keeps the records the
+  server sends small, the other keeps the rows the browser builds small; a `gogLoadMore` list that
+  has loaded 10 000 records still stamps 10 000 rows without this. The spacers are also what keep
+  `gogReachEnd` meaning the end of the data rather than the end of the window.
+
+  `gog-table` still does not window.
+
+- **`gog-alert` — a persistent, in-flow message**, and the thing `gog-toast` cannot be. No timer,
+  no queue, no overlay, no service: it renders where you write it and stays until your app removes
+  it. `severity` (the shared `GogSeverity`, defaulting to `'accent'`), an optional `heading`, a
+  projected body, `dismissible` with a `dismissed` output, `iconName` with a `gogAlertIcon` slot,
+  and `GOG_CONFIG.labels.closeAlert`.
+
+  **`dismissed` means pressed, not removed.** The alert stays in the DOM and the app decides. A
+  component that deleted itself would take the focused element with it and drop a keyboard reader
+  onto `<body>`.
+
+  **It announces through `live`** — `'assertive' | 'polite' | 'off'`, defaulting from the severity,
+  with `GogAlertLive` exported. The announcement is a copy of the message in a **separate
+  visually-hidden region**, empty until one render after the alert mounts, because a live region
+  filled in the same pass as its own creation announces nothing — the trap
+  `gog-toast-container`'s permanently-mounted regions exist to avoid.
+
+  **Whether the component could pick `live` itself was measured, and it cannot.** The question was
+  whether it can detect having been created during the application's first render, which is the
+  one case the severity-derived default gets wrong. `@angular/core` exposes no stability member on
+  `ApplicationRef` a component can read synchronously at construction, and `afterNextRender`
+  reports its _own_ first render — which every alert has, whenever it mounts. So `live` is the
+  consumer's call with a loud note: **set `'off'` for a message that is on the page when it
+  loads.**
+
+  One thing the plan called for and the code refused: **there is no `variant` input.** It was to be
+  `GogSurfaceVariant` defaulting to `'filled'`, but `filled` in this library means _a tint_ and
+  there is no per-status tint to draw it with — `--gog-accent-pale` exists, `--gog-success-pale`
+  does not. Inventing that family here would make the alert the twelfth place a theme restates its
+  red, so the severity is a leading edge and the icon over the ordinary surface, which is the shape
+  `gog-toast` already reached for the same reason.
+
+- **`--gog-button-focus-ring-color`**, and it is a fix as much as an addition. `gog-button` had a
+  focus-ring width and a focus-ring offset but no colour, so `button.css` reached for
+  `--gog-button-variant-hover-bg` — the _hover_ fill doing focus duty, which is the same defect
+  eight other indicators had corrected in 21.12.0. It passed on `primary` and `secondary`, whose
+  hover fill is a saturated accent, and failed wherever that fill is a wash: **`ghost` at
+  1.07–1.16:1** and the **severity `outline`** combinations at **1.79–2.65:1**, eleven failures
+  across `light`, `material`, `primeng` and `terminal`.
+
+  It defaults to `--gog-accent-color` — one colour, not one per variant. A focus ring's job is to
+  be visible against the page the button sits on, which does not change with the button's fill,
+  and this ring already sits a pixel further out than the foundation's so it reads as separate
+  even on a filled accent button. That is the answer the library's other fourteen rings give.
+
+### Changed
+
+- **The package has a second entry point, `@guildofgleks/ui/shared`, and it is internal.** Shared
+  types, configuration and helpers moved out of the root bundle into their own, which the root now
+  imports by package path. Nothing an app imports changes: every symbol the root exported, it still
+  exports, now named one by one instead of re-exported wholesale.
+
+  This is phase 1 of `docs/entry-points.md` in the repository, and the reason for it is a
+  measurement: **the package tree-shakes but does not code-split.** On the real CLI a button costs
+  about 10 kB gzip over an empty app, but a lazy route holding `gog-table`, `gog-datepicker`,
+  `gog-calendar` and `gog-dialog` produced a 442-byte chunk and left all four in the initial bundle
+  — 40 kB heavier than it needs to be. Splitting the heavy components out needs `GOG_CONFIG` to live
+  in exactly one bundle, which is what this entry point is; the split itself comes in the next
+  minors.
+
+  `@guildofgleks/ui/shared` resolves, but it is plumbing the package's own entry points share.
+  Import from `@guildofgleks/ui`.
+
+- **`public-api.ts` names what it exports instead of re-exporting two modules wholesale.** The
+  defect was never which symbols are public — it was that **adding one published it silently**. A
+  helper written into `date-utils.ts` or `option-accessor.ts` became part of the package's `.d.ts`
+  the moment it was saved, with nobody deciding that and no diff showing it.
+
+  **Nothing is dropped from `date-utils`.** All twenty of its helpers and `GogDateRange` are
+  listed by name, because `AGENTS.md` already advertises `formatDate`, `parseDate` "and a family
+  of date-math helpers" — the set is supported on purpose. The list changes nothing a consumer can
+  import; it changes who decides the next one, which is the whole point.
+
+  `option-accessor` is the module where the accident had consequences, and its three functions are
+  deprecated above.
+
+- **A warning toast and an info toast were both the accent, and an info toast was pixel-identical
+  to a plain one.** `--gog-toast-warning-color` read `--gog-accent-bright` and
+  `--gog-toast-info-color` read `--gog-accent-color` — which is also what a _typeless_ toast
+  paints. That token is the whole signal: it draws the leading stripe, the icon and the countdown
+  bar. Three of the five toast states were the accent, in every theme, since the component
+  shipped. Both now read their own role.
+
+  **Surveyed rather than assumed, after the palette fix below raised the question.** All 45
+  severity-named colour tokens across every component were resolved against their own role in all
+  eleven themes; `gog-toast` is the only one that was wrong, and it was wrong twice. `gog-alert`,
+  `gog-button`, `gogBadge`, `gog-tag` and `gog-progressbar` all derive correctly — which is what
+  made this invisible, since nothing compared a token's _name_ against the root it reads.
+
+- **`check:tokens` rule J — a token named for a severity resolves to that severity.** A text rule
+  rather than a sweep: the declaration either names its own role or it does not, and that needs no
+  colour maths. Scoped to the four suffixes whose job is to _be_ the role's colour (`-color`,
+  `-bg`, `-fill`, `-border`); `--gog-badge-warning-color` is the _label_ on the warning fill and is
+  in the exception list with that reason, beside `-wash`, `-ink` and `-buffer-bg`, which are
+  percentages of a role rather than the role. Verified by putting the old value back and watching
+  it fail.
+
+- **`README.md` and `AGENTS.md` say where `gog-table` stops.** No column resizing or reordering by
+  the reader, no frozen columns, no expandable rows, no grouping — stated where someone evaluating
+  the table will read it rather than discovered halfway into a project. Documentation only;
+  nothing about the component changes.
+
+  **This list said "no virtualization" when it was written, and this release removed that line by
+  building the thing.** Both entries are in this changelog, days apart, and for a while the release
+  both added `virtualize` and advertised its absence. A limitations list is a claim with a shelf
+  life, and the shelf can be one release.
+
+  Each claim was verified against the code first, and one in `docs/backlog.md`'s filing was wrong:
+  it said "no sticky columns" while the table has shipped `stickyHeader` since 21.6.0. Those are
+  different axes — the header pins while rows scroll under it; the absent one is freezing a column
+  against _horizontal_ scroll — and both documents now draw that line, because a limitations list
+  that looks wrong on its first line teaches a reader to distrust the rest.
+
+- **`check:oklch`'s R3 compares five severities, not four — and three themes were painting two of
+  them as one colour.** `GogSeverity` is `'accent' | 'success' | 'danger' | 'warning' | 'info'`
+  and the library paints all five as a set (`gog-button`'s `severity`, `gog-progressbar`'s
+  `variant`, `gogBadge`, and now `gog-alert`, whose entire signal is the colour of one edge). R3
+  was written against "the four status colours" and left the accent out, so four of the ten pairs
+  went unmeasured.
+
+  Two of the three findings are not close calls: the **dark** theme declared
+  `--gog-warning-color: #fbbf24`, the same hex as its accent, and **terminal** declared
+  `--gog-success-color: #3ddc5c`, the same hex as its. Nobody writes one value twice for two roles
+  on purpose — it is what a palette typed role-by-role produces when nothing compares them.
+  **parchment**'s danger sat 6.9° of hue and 0.052 of lightness from its oxblood accent, which is
+  not a distance a reader can use.
+
+  All three moved the **status**, never the accent: the accent is the theme's identity and the
+  status is the role that has to be read. `dark`'s warning is ember orange `#ffac4e` — moved by
+  hue rather than lightness, because darkening a status on a dark ground trades one defect for
+  another. `terminal`'s success is `#00b330`, moved along its own hue because that theme's other
+  three statuses already occupy yellow, red and cyan and the room left is in lightness.
+  `parchment`'s danger is `#a24439`. `check:contrast` stays green on all eleven themes.
+
+- **A disabled control is exempt from `check:contrast`, consistently and on purpose.** WCAG carves
+  out "an inactive user interface component" in both SC 1.4.3 and 1.4.11 — a disabled control is
+  meant to look unavailable, and holding it to 4.5:1 makes "unavailable" impossible to draw. The
+  script had simply never had `:disabled` in one of its state regexes, with nothing saying why, so
+  the omission read as an oversight.
+
+  It also was not the exemption it looked like: **eight pairs reached the sweeps through compound
+  selectors** — `.gog-accordion__item--disabled .gog-accordion__header:hover` enters on its
+  `:hover` — and were gated. One predicate governs all three sweeps now, and such pairs are
+  printed rather than dropped. Nothing in the library changes; all eight already passed.
+
+- **`npm run check:oklch` gates that a raised surface has an edge (R4).** `*-shadow` colours were
+  the last thing the palette gate did not read. `check:elevation` requires a theme to declare all
+  ten elevation knobs, but a theme may declare all ten at zero and pass it — rendering a dialog
+  with no boundary against the page behind it, with every check green.
+
+  The rule is a disjunction, because four different things can mark that edge and the eleven
+  shipped themes split on which: **six are carried by their shadow and five by their hairline
+  ring**, so gating any single carrier would have failed half the catalogue for a choice it made
+  deliberately. Whichever is strongest must clear ΔL ≥ 0.03 — the same threshold R1 already uses,
+  because it is the same question. Observed 0.0852 (`light`) to 0.3465 (`material`): the weakest
+  shipped theme clears it by 2.8x, and both figures are now printed per theme.
+
+  Nothing in the library changes. This one is a gate against a theme a consumer writes, which is
+  where the failure is silent.
+
+- **`npm run check:contrast` resolves a boundary through the variant layer, and `.gog-btn` is
+  gated by it.** The button was the one control deliberately outside the boundary sweep, because
+  what identifies a button depends on its variant and the sweep resolved each painting rule once —
+  on `.gog-btn` that meant reading `--gog-button-primary-border`, `transparent` in the base theme.
+  It now resolves every boundary under each variant chain, the same machinery the variant sweep
+  already used for fills and labels, so `outline`'s border is measured as `outline`'s and
+  `ghost`'s transparent one is skipped. That is what found the focus-ring failures above.
+
+  Two smaller corrections came out of building it. **`boundaryBlock` matched the first gated
+  prefix rather than the longest**, and `.gog-ms` is a prefix of `.gog-ms__filter-input`: the
+  multiselect's filter input was being measured against the _page_ rather than the panel it sits
+  in, so the pair it reported was one nobody sees. And **the sweep now asserts that every block it
+  gates actually matched a declaration** — the same discipline as the pattern self-test added in
+  21.12.0, and it is what surfaced the prefix bug. A gated list whose entries match nothing looks
+  exactly like a library with no defects.
+
+### Deprecated
+
+- **`gog-table`, `gog-datepicker`/`gog-calendar` and `gog-dialog` move to their own entry points —
+  import them from `@guildofgleks/ui/table`, `/datepicker` and `/dialog`.** The root keeps
+  exporting all 25 symbols until **21.14.0** and stops then, when the code moves. The split is the
+  point: a lazy route using these components currently ships them in the initial bundle anyway,
+  and only an entry point the root does not re-export can change that — measured in
+  `docs/entry-points.md` in the repository.
+
+  - `@guildofgleks/ui/table` — `TableComponent`, `GogColumn`, `GogColumnBodyDirective`,
+    `GogColumnHeaderDirective`, `defaultCompare`, and the types `GogColumnBodyContext`,
+    `GogColumnHeaderContext`, `GogTableRowClickEvent`, `GogTableSelectionMode`,
+    `GogTableSortEvent`, `SortDirection`.
+  - `@guildofgleks/ui/datepicker` — `DatepickerComponent`, `CalendarComponent`, and the types
+    `GogCalendarDay`, `GogDatepickerValue`. The date helpers and `GogDateRange` stay in the root.
+  - `@guildofgleks/ui/dialog` — `DialogService`, `DialogComponent`,
+    `ConfirmationDialogComponent`, `DIALOG_DATA`, `DIALOG_REF`, and the types `DialogRef`,
+    `DialogConfig`, `DialogHandle`, `OpenDialog`, `ConfirmDialogData`.
+
+  **Your editor will not strike the old imports through**, and that is measured rather than
+  overlooked: ng-packagr bundles the root's types into a single export statement and drops the
+  deprecation tag on every re-export. A tag on the class itself would survive — and would strike
+  through the new subpath too, since it is the same class. This entry, `AGENTS.md` and
+  `GOG_DEPRECATIONS` are the notice.
+
+  Switching an import today changes nothing at runtime; both paths reach the same class.
+
+- **`getByPath`, `readOption` and `isSameOptionValue` are deprecated, removed in 21.14.0.** They
+  are this library's own plumbing for reading a field off a consumer's object, and they became
+  public API because `public-api.ts` re-exported their module wholesale. Nothing in `README.md` or
+  `AGENTS.md` has ever mentioned them. `GogOptionAccessor` — the type every collection control's
+  `optionLabel` / `optionValue` / `optionDisabled` input is declared with — stays, and is the
+  reason the module was exported at all.
+
+- **`--gog-slider-thumb-shadow` becomes `--gog-slider-thumb-glow-color`, removed in 21.14.0.**
+  The thumb composes it as `box-shadow: 0 0 var(--gog-slider-thumb-glow-size) <this>`, so the
+  token holds a **colour** and always has. Of the 31 `*-shadow` tokens the elevation audit
+  classified for 21.12.0, it was the only one whose name was simply wrong — and the wrongness is
+  not decorative: a consumer overriding it with a colour got what they expected, and one
+  overriding it with a shadow got a declaration the browser silently dropped.
+
+  `check-elevation.mjs` has carried it in `NOT_ELEVATION` with that reason since it was found;
+  that entry now explains why it is still listed (the sweep keys on the `-shadow`/`-glow`
+  families, not on what a token holds) rather than promising a rename.
+
+- **`--gog-select-panel-offset` and `--gog-multiselect-panel-offset` become `*-panel-gap`,
+  removed in 21.14.0.** Five components place a panel with `calc(100% + <token>)` and split three
+  ways on what to call the value: `gog-autocomplete` and `gog-datepicker` said `-panel-gap`,
+  `gog-select` and `gog-multiselect` said `-panel-offset`, and `gog-menu` said `-offset`. A
+  consumer who learned one spelling guessed wrong on the next component.
+
+  `-gap` wins because it is the true one: an offset is a displacement from where a thing would
+  otherwise be, and this is the space between two things. `gog-menu`'s is renamed outright in the
+  same release with no window, because that one was never read (see Fixed) — a deprecation cycle
+  protects working consumer code, and there was none.
+
+  **Both old names keep resolving until 21.14.0.** `theme.css` declares each new token as
+  `var(<old name>, <value>)`, which is the mechanism the 21.7.0 prefix removals used: an override
+  on the old name still wins, one on the new name wins over it, and everyone else gets the value.
+  One minor rather than two, per `api-design.instructions.md` — the migration is a find-and-replace
+  in a theme.
+
+  **The ratchet had to grow a second half to hold this.** `DEPRECATED_NAMESPACES` can express
+  `--gog-btn-*` becoming `--gog-button-*`, because the prefix moves and the suffix is carried
+  through — it cannot express a rename, where the suffix itself moves and the replacement has to be
+  named. `DEPRECATED_TOKENS` is that map, `check:deprecations` fails on an overdue entry the same
+  way, and `GOG_DEPRECATIONS` now ships two entries where it shipped none. Verified by dating both
+  to the current version and watching the check fail.
+
+### Fixed
+
+- **Six tokens were declared and read by nothing — one wired up, five removed.** Everything rule K
+  found on its first run, each given a verdict rather than a blanket fix:
+
+  **`gog-inputfield`'s clear mark was the wrong size**, and this is the one a consumer can see.
+  Six controls offer a clear button and all six declare `--gog-<block>-clear-icon-ratio` at `0.7`;
+  five read it and `gog-inputfield` did not, so its `×` rendered at the field's full type size —
+  about **43% larger** than the identical mark on a select, multiselect, autocomplete, datepicker
+  or textarea standing next to it. It now reads its own token, like its five siblings.
+
+  **Five leftovers removed**, none of which any stylesheet could reach:
+  `--gog-accordion-hover-ring` (the header's hover paints a colour and a background, never a ring),
+  `--gog-multiselect-checkbox-bg` and `--gog-multiselect-checkbox-checked-color` (the option's mark
+  is a glyph, so a background and a label colour have nothing to paint — the two tokens the mark
+  _does_ read are untouched), `--gog-panel-elevated-shadow` (21.12.0 deliberately pointed the
+  elevated variant at the foundation's own `--gog-panel-shadow`, which left this behind), and
+  `--gog-toast-gap` (the stack uses `--gog-toast-stack-expanded-gap` and the row
+  `--gog-toast-content-gap`).
+
+  **No deprecation cycle for any of the five**, on the same reasoning as the menu's rename: a
+  deprecation window protects working consumer code, and a token nothing reads has none to protect.
+  Overriding any of them has always done exactly nothing, and still does.
+
+- **Two more marks were bigger than the boxes holding them**, found by the check above rather than
+  by eye — the same defect as the chip's remove mark, the select's chevron and the multiselect's
+  arrow earlier in this release, in two places that audit did not reach.
+
+  **`gog-table`'s sort icon was 9% wider than its slot**, and it is the _fourth_ time this library
+  has paid for "a relative unit resolves against the element carrying the property".
+  `--gog-table-sort-icon-width: 1.1em` reads as "a little wider than the mark" and is not: the
+  `em` resolves against the element's own font-size, which the line below it had already reduced
+  to `0.9em`, so the slot came out `0.99em` of the header while the mark is `1.2 × 0.9 = 1.08em`
+  of it. The slot now takes a floor of `--gog-icon-size`, which states the invariant in the CSS
+  rather than leaving it to a number someone has to get right. A consumer setting the token wider
+  still wins.
+
+  **`gog-textarea`'s clear mark was 20% wider than its button**, and this one is the largest of
+  the four because its ratio is deliberately `1` — `theme.css` says why, and it is right: 0.7
+  suits a dropdown's dense single-line trigger and reads as a speck on a multi-line box. So the
+  **box grew and the mark did not move**, which is the same resolution the chip's got. The clear
+  button's hit area is about 20% larger.
+
+- **An `interactiveRows` table row answered a click and not a press.** It had a cursor, a hover
+  tint and a focus ring, and nothing at all under the finger — 21.9.0 gave nine other pressable
+  surfaces a `:active` colour and this one was not among them. `--gog-table-row-press-bg` now
+  fills that, guarded on `--interactive` because a plain row is not a control, and a selected row
+  keeps its own tint under the finger for the reason it already keeps it on hover.
+
+  **A colour rather than a ripple, and that is the verdict on `docs/ripple.md`'s deferred table
+  rows.** That plan left them out on two arguments and gated the revisit on the weaker one —
+  "no virtualization in this library yet" — which `virtualize` has now removed. The other never
+  depended on it: a wave whose radius is an 800–1200px row reads as a flash across the table
+  rather than as feedback where the finger landed. A colour also survives
+  `prefers-reduced-motion`, which was 21.9.0's other half.
+
+- **`gog-menu`'s gap between trigger and panel was a token nothing read.** `--gog-menu-offset` was
+  declared in `theme.css`, listed in `TOKENS.md`, and documented on the site as "gap between the
+  trigger and the panel" — and the panel is placed in script, by a function that was called
+  without its `gap` argument and fell back to its own hard-coded `4`. Setting the token did
+  nothing, in every theme, since the component shipped.
+
+  What it cost beyond the dead knob: the four other components that place a panel this way take
+  their gap from CSS and follow `--gog-density`, so **a theme changing density moved four of the
+  five and left the menu's gap at 4px.** The component resolves the token now, through
+  `resolveLengthToken` — `parseFloat` would return `NaN` on the `calc(4px * var(--gog-density))`
+  the density scale produces, which is the trap that file exists for.
+
+  **Renamed to `--gog-menu-panel-gap` in the same change, with no deprecation cycle, on purpose.**
+  A deprecation window protects working consumer code and there is none to protect: nothing a
+  consumer wrote against the old name ever had an effect. Keeping an alias alive for two releases
+  would be complexity spent guarding a promise that was never kept. The new name is also the one
+  the other four already use — `--gog-<block>-panel-gap` — which is what the
+  `-gap`/`-offset` split in `docs/backlog.md` is about.
+
+  Found by sweeping `theme.css` for tokens nothing reads, after `--gog-menu-offset` turned up while
+  auditing that naming split. **The sweep found twelve candidates out of 1482**, and no check
+  covers the category: `check:tokens` rule F is the opposite direction — a `var()` read with no
+  declaration — so a declaration with no reader passes every gate the project has.
+
+- **A dropdown could open downward into a panel that does not fit.** The three controls on
+  `GogDropdownBase` — `gog-select`, `gog-multiselect` and `gog-autocomplete` — size their panel
+  from `--gog-*-option-height` and choose up or down from the result. That token calls itself an estimate; measured against a rendered row it is wrong in
+  **all eleven shipped themes** — low in ten of them, by up to 8.38px a row — so the estimate
+  systematically under-reported and a short list could be judged to fit below when it needed more
+  room than there was.
+
+  It only ever misfired on lists short enough to sit under the panel's max-height cap (roughly
+  five rows), which is why it went unseen: above the cap the cap dominates and the error is
+  masked. **No static token can fix it** — the same `parchment` row is 48.38px at
+  `--gog-density: 1` and 42.38px at 0.85 — so the component now measures one real row a frame
+  after the panel renders and re-places if the token disagreed, caching it so every later open is
+  right from its first frame. The token remains as the seed for that first frame and its
+  documentation is corrected in all three.
+
+  Found by `docs/virtualization.md`'s iteration 0, which existed to check exactly this before
+  anything new depended on it.
+
+- **Two of the three dropdowns sized their panel from a gap that is not between the rows.** The
+  height estimate that decides whether a panel opens up or down sums the rows _and the gap
+  between them_, and it took that gap from `--gog-<block>-option-gap` — which on `gog-select` and
+  `gog-autocomplete` is the gap **inside** a row, between the mark or icon and the label. Neither
+  options container declares a gap between rows at all, so every row added 12px of panel that is
+  not on the page: 48px on a five-row list, which is the length at which this decision is made at
+  all.
+
+  It is the same defect as the row-height one above and the opposite sign, which is why they were
+  invisible together — one estimate ran low per row and the other ran high per gap. Fixing the
+  first is what exposed the second, and that is the argument for measuring rather than deriving:
+  **a sum of two wrong terms can place a panel correctly and does not stay lucky.**
+
+  The gap is now measured from the rendered options container, in the same frame and from the same
+  element as the row — the row's own `parentElement`, so no subclass has to declare a second
+  selector. `gog-multiselect` is unaffected: its list is the one that really does declare a row
+  gap, and it is the only one that still seeds from a token.
+
+  **The token names are unchanged and so is what they paint.** `--gog-select-option-gap` still
+  sets the space between the check mark and the label, which is what it has always done; only
+  what read it for a different purpose has changed. All three now say in `theme.css` which gap
+  they are.
+
+- **`gog-progressbar`'s buffer had no edge, and its edge is the whole of what it says.** The
+  buffer tier marks how much is loaded; where it _ends_ was under 3:1 against the track in **55 of
+  55** shipped theme/variant combinations, worst **1.06:1**. That is a stronger result than the 51
+  of 55 that justified marking the fill's edge in 21.10.0, and it has the same cause: the two
+  tiers are the same hue by design — "the buffer tier is the same hue at low opacity, so it reads
+  as _ahead of the fill_ rather than as a second, competing colour" — which is the right choice
+  and exactly why a colour difference cannot carry the boundary.
+
+  The buffer now draws the same two hairlines the fill has drawn since 21.10.0. **No new token and
+  no palette change:** measured at the buffer's own edge across the same 55, the existing marker
+  clears 3:1 everywhere, worst 3.25:1, carried by the ink line against the bare track — the pair
+  `check:contrast` already gates. Visible wherever `mode="buffer"` is used.
+
+- **Three icon buttons were smaller than the icon inside them** — `gog-chip`'s remove mark by 9%,
+  `gog-select`'s chevron and `gog-multiselect`'s arrow by 5%, at every size and in every theme.
+  Each set its box from one basis and let `<gog-icon>` draw the mark from another: the icon
+  renders its `<svg>` at `--gog-icon-size` (1.2em) of its own font-size, and none of the three
+  boxes was derived from that.
+
+  **Nothing painted the overflow, so nothing showed it** — the boxes carry no background at rest
+  or on hover. What it cost was the focus indicator. `:focus-visible` draws its outline on the
+  box, so on the chip the ring was drawn _inside_ the mark it indicates and cleared it only
+  because `--gog-chip-focus-ring-offset` happens to be 2px; measured at an offset of `0` — a
+  value any theme may choose, and one the theme generator offers as a slider — the ring landed
+  0.79px inside the glyph at `md`.
+
+  All three now state the mark's font-size and its box on the same element, with the box reading
+  the same `--gog-icon-size` the icon reads. The two cannot drift again for any ratio, or for any
+  icon size a consumer sets.
+
+- **`--gog-chip-remove-scale` now means what its name says, and its default is `1`.** It was
+  `1.1`, and it multiplied the button's _font-size_ rather than the mark — so it produced a box
+  9% narrower than its own contents, and any value under `1.2` did nothing visible at all. It is
+  the ring around the mark now: `1` is the box the glyph occupies, and anything above it is
+  padding. **A theme that overrides this token gets a larger box than before at the same
+  number**, by a factor of 1.2.
+
+  `--gog-select-chevron-icon-ratio` and `--gog-multiselect-arrow-icon-ratio` were wrong in the
+  same way and are unchanged in value: both read `0.875`, which a reader takes to mean the
+  chevron is seven eighths of the field's type. It was 1.05 of it, because `--gog-icon-size`
+  multiplied on top. The mark does not move; the box around it grows 5% to contain it.
+
+  One visible consequence: **a removable chip with no avatar is ~9% of its remove box taller** —
+  1.2px at `xsm` to 2.0px at `slg`, measured at `--gog-density: 1`. The mark itself does not
+  change size at any of the five. A chip with an avatar does not move at all, because the avatar
+  is the taller element. On `gog-select` and `gog-multiselect` nothing moves: the chevron's box
+  is not what sets a field's height.
+
 ## [21.12.0] - 10.09.2026
 
 ### Added