@guildofgleks/ui 21.4.3 → 21.5.0

package/CHANGELOG.md

@@ -6,12 +6,258 @@ reached 1.0, so breaking changes may land in minor versions.
 
 ## [21.5.0] - planned
 
-Nothing yet. What this release already owes is in the source: every
-`@deprecated … Removed in 21.5.0` tag — the six legacy icon inputs on `gog-inputfield`, the
-`checkIconTemplate` / `clearIconTemplate` / `iconTemplate` / `chevronTemplate` inputs, the
-`<column>` element with its `Column` const and type, the string-keyed `[template]` column slot,
-and the `GogSelectOption` / `GogMultiselectOption` aliases (those two overran their announced
-21.4.0 removal). Each names its replacement in the tag itself.
+**The breaking release** — the one version consumers have to read before upgrading into. It
+carries the removals below and the token-prefix rename (`--gog-btn-*`, `--gog-ms-*` and
+`--gog-confirm-*` spelled out; the old spellings keep working until 21.7.0). Everything
+non-breaking that was ready earlier shipped in 21.4.4 instead, so a reader upgrading to 21.4.4 has
+nothing to migrate and a reader upgrading to 21.5.0 has one list to work through rather than one
+buried among fixes.
+
+### Removed
+
+Everything deprecated for this version is gone. **All of it was announced with a replacement in
+21.3.0 or earlier**, and every replacement has shipped since then, so each item below is a
+mechanical edit at the call site rather than a redesign. If you are on 21.4.x, your editor has
+been striking these through already.
+
+**Per-slot `TemplateRef` inputs → projected slot directives.** Declare the template where it is
+used; it no longer has to be wired through an input, and it carries a typed context.
+
+| Removed input                                        | Replacement                             |
+| ---------------------------------------------------- | --------------------------------------- |
+| `gog-checkbox` `[checkIconTemplate]`                 | `<ng-template gogCheckboxIcon>`         |
+| `gog-tag` `[iconTemplate]`                           | `<ng-template gogTagIcon>`              |
+| `gog-multiselect` `[clearIconTemplate]`              | `<ng-template gogMultiselectClearIcon>` |
+| `gog-select` / `gog-multiselect` `[chevronTemplate]` | `<ng-template gogDropdownChevron>`      |
+
+```html
+<!-- before -->
+<gog-tag [iconTemplate]="star">Featured</gog-tag>
+<ng-template #star><gog-icon name="check" /></ng-template>
+
+<!-- after -->
+<gog-tag>
+  <ng-template gogTagIcon><gog-icon name="check" /></ng-template>
+  Featured
+</gog-tag>
+```
+
+**`gog-inputfield`'s six legacy icon inputs** — `iconStartTemplate`, `iconEndTemplate`,
+`iconStartFn`, `iconEndFn`, `iconStartLabel`, `iconEndLabel` — replaced by projecting a real
+element into the field's leading or trailing slot. A projected `<button gogInputAddonEnd>` carries
+its own click handler, its own `aria-label` and its own disabled state, which is why six inputs
+collapse into none:
+
+```html
+<!-- before -->
+<gog-inputfield label="Search" iconEnd="check" [iconEndFn]="run" iconEndLabel="Search" />
+
+<!-- after -->
+<gog-inputfield label="Search">
+  <button gogInputAddonEnd type="button" aria-label="Search" (click)="run()">
+    <gog-icon name="check" />
+  </button>
+</gog-inputfield>
+```
+
+`iconStart` / `iconEnd` stay, and are now unambiguously **decorative**: they render an
+`aria-hidden` span, never a button. The only action button `gog-inputfield` still renders for
+itself is the password reveal toggle, whose labels remain `showPasswordLabel` /
+`hidePasswordLabel`.
+
+**`gog-table`'s string-keyed template slot.** `<ng-template template="field" type="body">` matched
+a column by a string the compiler could not check — a typo silently rendered the default cell.
+Declare the template inside the column it belongs to instead:
+
+```html
+<!-- before -->
+<gog-column field="status" />
+<ng-template template="status" type="body" let-row>…</ng-template>
+
+<!-- after -->
+<gog-column field="status">
+  <ng-template gogColumnBody let-row let-value="value">…</ng-template>
+</gog-column>
+```
+
+The `TemplateDirective` export goes with it, along with the `GogTableBodyContext` /
+`GogTableHeaderContext` types it carried — `GogColumnBodyContext` / `GogColumnHeaderContext` are
+the typed replacements, and they are what the column-scoped templates have always used.
+
+**The unprefixed table column names.** The `<column>` element selector and the `Column` const and
+type are gone; use `<gog-column>` and `GogColumn`.
+
+**The `GogSelectOption` and `GogMultiselectOption` type aliases.** Use `GogDropdownOption` — the
+same type; both were aliases of it since 21.2.2. These two were announced for removal in **21.4.0**
+and overran it by a minor: 21.4.0 through 21.4.4 all shipped with them still exported. Recorded
+here rather than quietly re-dated, and `npm run check:deprecations` now fails the build on any
+`@deprecated … Removed in <version>` tag whose version has already been reached, so no deprecation
+can overrun its date again.
+
+**The `@guildofgleks/ui/src/styles/…` asset path.** Stylesheets moved to `@guildofgleks/ui/styles/…`
+in 21.3.2, with the old path documented as working until 21.5.0. The package no longer ships the
+duplicate copy, and the `./src/styles/*` export is gone — if your `angular.json` still names the
+long path, drop the `src/` segment.
+
+### Fixed
+
+- **`gogCollapsibleTrigger` is reachable by keyboard on any element.** Its own documentation
+  invites a non-focusable host ("works on any clickable element"), and on one it used to apply
+  `aria-expanded`/`aria-controls` and nothing else: a control that announces itself to a screen
+  reader, with no tab stop and no response to Enter or Space — the one combination that strands
+  the person relying on that announcement.
+
+  On a host that is not natively operable the directive now also supplies `role="button"`,
+  `tabindex="0"` (`-1` while disabled) and Enter/Space. A `<button>` or `<a href>` is untouched,
+  since a second key handler would toggle twice in one press, and a `role`/`tabindex` you set
+  yourself is respected rather than overwritten.
+
+### Added
+
+- **`GOG_DEPRECATIONS` — the deprecation manifest**, generated from the library's own source and
+  shipped in the public API:
+
+  ```ts
+  import { GOG_DEPRECATIONS } from '@guildofgleks/ui';
+
+  // → { kind: 'token', name: '--gog-btn-radius', replacement: '--gog-button-radius',
+  //     since: '21.5.0', sinceDate: '2026-08-19', removedIn: '21.7.0' }
+  ```
+
+  It answers "is this still supported, and until when?" for tooling that has to mark an API row —
+  a docs site, an editor plugin, a codemod — without anyone maintaining a second list. Symbols
+  come from their `@deprecated` tags and tokens from the stylesheets that still resolve them, so
+  it cannot drift from the code.
+
+  In this release it holds **154 tokens and no symbols**: 21.5.0 removed every deprecated symbol
+  the library had, and its deprecations are the three abbreviated token prefixes above. An empty
+  symbol half is the healthy state, not a broken generator.
+
+- **`gog-menu` — a command menu**, with `[gogMenuTrigger]` on your own button and `gogMenuItem` on
+  your own items:
+
+  ```html
+  <button gogButton variant="ghost" [gogMenuTrigger]="rowMenu" aria-label="Row actions">
+    <gog-icon name="more-vertical" />
+  </button>
+
+  <gog-menu #rowMenu>
+    <button gogMenuItem (click)="edit(row)">Edit</button>
+    <button gogMenuItem disabled>Transfer ownership</button>
+  </gog-menu>
+  ```
+
+  The library created this gap itself: 21.4.0 added `more-horizontal`/`more-vertical` icons and a
+  table built for row actions, with nothing to open with them. Everything else a consumer can
+  assemble from what already ships; an accessible menu cannot be — it needs focus management,
+  roving focus and overlay placement at once.
+
+  Keyboard follows the WAI-ARIA menu button pattern: Enter/Space/ArrowDown open with the first
+  item focused, ArrowUp with the last, arrows and Home/End move and skip disabled items, Escape
+  closes and restores focus to the trigger, Tab closes and moves on.
+
+  Disable an item with the native `disabled` attribute on your own button — the arrow keys step
+  over it. The panel always renders into `<body>`, placed from the trigger's measured rect, so a
+  menu inside `gog-scroll`, `gog-table` or any clipping ancestor needs no configuration; it takes
+  the `--gog-dropdown-z` its trigger inherits, so a menu inside a dialog stacks above it. Past
+  `--gog-menu-max-height` the panel scrolls with `gog-scroll`. Themed by `--gog-menu-*`.
+
+- **Right-to-left support.** `dir="rtl"` on `<html>` — or on any subtree — now mirrors every
+  component, with nothing to set per component. What changed under it: physical `left`/`right`
+  declarations became logical properties across 16 stylesheets; the select/multiselect panel and
+  the tooltip bubble copy a _scoped_ `dir` onto their portaled host, so an RTL region inside an
+  LTR page renders correctly; a tooltip's `position="auto"` prefers the mirrored horizontal side;
+  the calendar's month/year arrows turn around; and the slider fill, toast progress bar and
+  indeterminate progressbar run from the inline start.
+
+  Physical by design, because they are physical words in the API: a tooltip's explicit
+  `position="left"`/`"right"`, and a toast's `top-left`/`top-right`/`bottom-left`/`bottom-right`.
+
+  Three CSS custom properties are declared for the handful of properties with no logical form
+  (`transform-origin`, `translate`): `--gog-inline-start-side`, `--gog-inline-end-side` (the
+  `left`/`right` keywords) and `--gog-direction-sign` (`1`/`-1`). They flip on `[dir='rtl']` and
+  are available to your own styles.
+
+### Changed
+
+- **Component token prefixes are spelled out.** Three families were abbreviations of a
+  component's name — the one thing a consumer cannot guess — and now read as the component does:
+
+  | Was               | Is                                                           |
+  | ----------------- | ------------------------------------------------------------ |
+  | `--gog-btn-*`     | `--gog-button-*`                                             |
+  | `--gog-confirm-*` | `--gog-confirmation-dialog-*`                                |
+  | `--gog-ms-*`      | `--gog-multiselect-*` (since 21.3.0; the removal moved here) |
+
+  **Nothing breaks now.** Every old spelling still feeds the component: each replacement declares
+  it in its own fallback (`--gog-button-md-padding: var(--gog-btn-md-padding, 0.75rem 1.25rem)`),
+  and the per-instance names (`--gog-btn-bg`, `--gog-btn-padding`, …) are still read by the
+  button's own fallback chain. Override either spelling, at any scope, and it applies —
+  verified in a browser rather than reasoned about, for a theme block, a nested `[data-theme]`
+  subtree and an inline instance override.
+
+  **They are removed in 21.7.0** — two minors rather than one, because a CSS custom property that
+  nothing reads fails silently: no error, no warning, just a value that stops applying. Migration
+  is a find-and-replace on those three prefixes. `TOKENS.md` lists only the current names.
+
+  One prefix that looks abbreviated and is staying: **`--gog-input-*`**. It names the text-field
+  block that `gog-inputfield` and `gog-textarea` both render, not the `gog-inputfield` component —
+  the two restyle together from one token set on purpose, so there is no `--gog-inputfield-*`.
+
+- **`peerDependencies` now accept Angular 22** (`^21.2.0 || ^22.0.0` for `@angular/common`,
+  `@angular/core`, `@angular/forms`, `@angular/platform-browser`) instead of `^21.2.0` alone.
+  The library ships partial-compiled (Ivy partial mode), which is forward-compatible with the
+  next major without a rebuild — the strict `^21.2.0` peer range was blocking installation into
+  an Angular 22 app that otherwise built and ran fine, forcing every such consumer to reach for
+  `overrides`/`resolutions` as a workaround.
+
+## [21.4.4] - 17.08.2026
+
+Everything that is ready. Two defects and one addition, none of which changes an existing
+signature, so upgrading from 21.4.3 needs no migration — see the `gog-collapsible` entry only if
+you were relying on a panel being capped at 480px.
+
+### Added
+
+- **`ng add @guildofgleks/ui` now works.** It installs the latest version and adds
+  `node_modules/@guildofgleks/ui/styles/index.css` to your project's `angular.json` styles —
+  the one setup step that's pure mechanical JSON editing. Importing components and placing
+  `<gog-dialog />` / `<gog-toast-container />` are still manual; see the README.
+
+  In a patch rather than a minor because it is purely additive — it adds a way to install the
+  package and touches no existing API — the same reasoning that put "`CHANGELOG.md` now ships
+  inside the package" in 21.4.2.
+
+### Fixed
+
+- **An open `gog-collapsible` no longer clips content taller than 480px.**
+  `--gog-collapsible-max-height` defaulted to `480px` and the panel is `overflow: hidden`, so any
+  panel taller than that lost the rest of its content — with no scrollbar, no ellipsis and nothing
+  else to indicate it. The cap existed only to give the CSS transition an animatable target, which
+  meant every consumer had to discover the limit by having content disappear, then override the
+  token per instance. The default is now `max-content`, and `interpolate-size: allow-keywords` on
+  the panel keeps the open/close transition animating to it. `gog-accordion` never had this
+  problem — it animates `grid-template-rows` instead — so the two components now behave the same
+  way.
+
+  No token was added or removed, and nothing about the closed state changed. **Setting
+  `--gog-collapsible-max-height` to a length still caps the panel and still clips**, which is now
+  a deliberate opt-in rather than the default; per-instance overrides that only existed to work
+  around the old cap can be deleted.
+
+- **`gog-button`'s loading spinner was painted with the page's text colour.**
+  `--gog-btn-primary-spinner-color` and `--gog-btn-secondary-spinner-color` resolved to
+  `--gog-text-color` — the colour of text on the page background — while the label beside the
+  spinner used `--gog-accent-text-color`, the colour meant to sit on the button's fill. On the two
+  filled variants those are opposite ends of the palette, so the spinner came out washed out: on
+  the dark theme, `#f3ebd8` parchment on a `#fbbf24` amber button, next to a near-black label.
+  Both now resolve to the variant's own label colour, so a spinner reads exactly as strongly as
+  the text it replaced and follows any re-theming of the button's foreground. `outline` and
+  `ghost` were already correct and are untouched.
+
+  Only the two tokens' values changed; no token was added or removed. A theme that sets either
+  one explicitly is unaffected. Note the button as a whole still dims to
+  `--gog-btn-loading-opacity` (0.7) while loading — that is deliberate and separate from this.
 
 ## [21.4.3] - 16.08.2026
 
@@ -32,6 +278,7 @@ first entry if you were relying on a calendar filling its container.
 
   This sizes `inline` mode too — `[inline]="true"` renders `gog-calendar` with a border and
   nothing else. **Set `--gog-calendar-max-width: 100%` to keep the old full-width behaviour.**
+
 - **`--gog-datepicker-panel-width`** (default `max-content`) exposes the dropdown panel's width,
   which was hardcoded. Same value as before; nothing changes unless you set it.
 
@@ -80,7 +327,7 @@ entries above are that kind of gap, which is why a documentation-only patch was
 - **Overlays ignored custom properties set on `:root`.** A select panel, tooltip or any other
   overlay rendered into `<body>` copied the `data-theme` of its trigger's nearest themed
   ancestor. When that ancestor is `<html>` — the usual case — the copy made the overlay match
-  `theme.css`'s derived layer (`:root, [data-theme]`) *locally*, re-declaring every component
+  `theme.css`'s derived layer (`:root, [data-theme]`) _locally_, re-declaring every component
   token against the plain preset palette and discarding anything set on the root that the preset
   does not itself declare.
 
@@ -88,7 +335,7 @@ entries above are that kind of gap, which is why a documentation-only patch was
   `document.documentElement` — a live theme editor, or any runtime accent switch — saw the
   document follow while every overlay kept rendering the un-edited theme.
 
-  The attribute is now copied only for a genuinely *scoped* theme, where the overlay would
+  The attribute is now copied only for a genuinely _scoped_ theme, where the overlay would
   otherwise pick up the document's; when the theme sits on the document element, inheritance
   already does the work. Several themes rendered side by side in scoped subtrees keep working
   exactly as before.
@@ -108,6 +355,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   `gogPageChange` deliberately stays quiet in two cases: the initial render, and the reset to
   page 1 that a new sort causes — that reset is part of the sort, and a consumer refetching from
   both events would issue two requests for one user action.
+
 - **`gog-table`: `lazy` — server-driven sorting and paging.** With `[lazy]="true"` the table
   stops sorting and slicing `value` and renders it exactly as handed over, treating it as the
   current page; `totalRecords` tells the paginator how many pages exist, and the two outputs are
@@ -124,6 +372,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   **The select-all covers the current page, not the whole data set** — in `lazy` mode the table
   has never seen the other pages, and a control that meant different things in the two modes
   would be worse than either behaviour on its own.
+
 - **`gog-table`: `dataKey`.** The field (or dot-path) identifying a row. Selection matches on it
   instead of object identity — without it a refetch producing new objects silently drops the
   selection — and it becomes the `@for` track key, so the rendered DOM survives a refetch of the
@@ -132,7 +381,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   Enter and Space activating the focused row. `gogRowClick` fires on a click either way; this is
   what stops a whole-row target from being mouse-only.
 - **`[gogButton]` — a link that looks like a button.** `gog-button` renders its own `<button>`,
-  so it could never *be* a link, and a large share of buttons on a real site are navigation. The
+  so it could never _be_ a link, and a large share of buttons on a real site are navigation. The
   directive inverts the relationship: the element stays the consumer's, and only the look is
   applied.
 
@@ -153,6 +402,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   on an `<a>`) and no `loading` (the spinner is a projected child a directive cannot add). The
   selector is `a[gogButton], button[gogButton]`, not a bare attribute, so it cannot be put on a
   `<div>` and produce something that looks clickable and is invisible to the keyboard.
+
 - **`gog-paginator`: a rows-per-page select.** `showPageSizeSelect` turns it on (**off by
   default** — a paginator that silently grew a control would change every existing layout) and
   `pageSizeOptions` sets the choices, defaulting to `[10, 20, 30, 40, 50]`. Both are also
@@ -160,7 +410,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   while the rest of the app uses the house default.
 - **`gog-paginator`: `pageSize` (a `model`) and `totalRecords`.** Given `totalRecords`, the
   paginator derives the page count from `pageSize` itself — which removes the
-  `computed(() => Math.ceil(total / size))` a consumer would otherwise have to write *and* keep
+  `computed(() => Math.ceil(total / size))` a consumer would otherwise have to write _and_ keep
   in sync with the select. `totalPages` still works and is right when a server hands you a page
   count directly; `totalRecords` wins if both are set. Changing the size returns to page 1:
   "page 5" of 10-row pages is not "page 5" of 50-row ones, so clamping alone would leave the user
@@ -174,7 +424,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
 - **`provideGogIcons(...)` — register your own icons by name.** `gog-icon` shipped a closed set
   of 20 glyphs, and the only way to render anything else was a `TemplateRef` per instance,
   which costs an `<ng-template>` at every use site and does not work at all for the components
-  that take an icon *name* (`gog-tag`, `gog-chip`, `gog-tabs`, `gog-button-toggle-group`,
+  that take an icon _name_ (`gog-tag`, `gog-chip`, `gog-tabs`, `gog-button-toggle-group`,
   `ToastService`, `DialogService`). In practice that meant installing a second icon library —
   precisely the dependency the "no CDK, no Material" footprint exists to avoid.
 
@@ -184,8 +434,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   ```
 
   ```html
-  <gog-icon name="cart" />
-  <gog-tag iconName="cart">In basket</gog-tag>
+  <gog-icon name="cart" /> <gog-tag iconName="cart">In basket</gog-tag>
   ```
 
   - A registered name **overrides a built-in of the same name**, so an app can replace the
@@ -193,6 +442,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
   - Providing it again lower in the injector tree **layers onto** the parent set rather than
     replacing it, matching `provideGogConfig`.
   - The registry is also exposed as the `GOG_ICONS` injection token.
+
 - **`GogBuiltinIconName`** — the closed union of the shipped glyphs, for code that wants
   exhaustiveness (an icon gallery, a `Record` keyed by icon).
 - **21 more built-in icons, taking the set from 20 to 41.** The old set covered what the
@@ -213,6 +463,7 @@ A minor rather than a patch: this adds public API. Iterations 5 and 6 of the con
 
   Cost: `ICON_DEFS` is one object, so every consumer pays for all of it — it grew from 8.0 KB to
   16.5 KB raw, **1.6 KB to 2.7 KB gzipped**.
+
 - **Attribution for the icons.** The glyphs were always Lucide but the package said so nowhere;
   Lucide's ISC licence asks for the notice to travel with them. It is now at the top of
   `icons.ts` and summarised in the README's licence section.
@@ -400,7 +651,7 @@ made unreachable.
   overriding it, and ignored outside `range` mode (nothing to disable "one side" of there). A
   one-sided disable only dims and disables that one thumb (its native input's own `disabled`
   attribute takes it out of the tab order); the whole-control `.gog-slider--disabled` styling
-  (dimming + `pointer-events: none` over the whole track) only kicks in once *both* sides are
+  (dimming + `pointer-events: none` over the whole track) only kicks in once _both_ sides are
   disabled, since applying it for just one would also block pointer input to the other,
   still-enabled thumb. Reactive forms are unaffected by this addition: a `[formControl]`'s own
   `.disable()`/`.enable()` still speaks for both thumbs at once, same as before — one

package/README.md

@@ -31,6 +31,20 @@ npm install @guildofgleks/ui
 
 ## Setup
 
+Install it with whichever package manager you use — or with `ng add`, which installs it and does
+step 1 for you:
+
+```bash
+npm install @guildofgleks/ui
+# or
+yarn add @guildofgleks/ui
+# or — also does step 1 below
+ng add @guildofgleks/ui
+```
+
+Steps 2 and 3 are yours either way: a schematic can't know where in your app you want components
+or dialog and toast hosts.
+
 **1. Add the stylesheet.** It carries the baseline theme and the utility classes the components
 use — without it they render unstyled.
 
@@ -42,9 +56,6 @@ use — without it they render unstyled.
 ]
 ```
 
-> Up to 21.3.1 these files shipped under `@guildofgleks/ui/src/styles/…`. That path keeps working
-> until 21.5.0; new setups should use the shorter one.
-
 **2. Import components where you use them** — each is standalone:
 
 ```ts
@@ -82,6 +93,18 @@ export class App {}
 One `<gog-dialog />` hosts every dialog (they stack); one `<gog-toast-container />` hosts all
 four toast corners.
 
+## Right-to-left
+
+**RTL is supported.** Set `dir="rtl"` on `<html>` (or on any subtree) and every component
+mirrors: stylesheets use logical properties, portaled panels and tooltip bubbles copy a scoped
+`dir` onto themselves, a tooltip's `position="auto"` prefers the mirrored horizontal side, and
+the calendar's month arrows turn around.
+
+Two things stay physical on purpose, because they are physical words in the API: a tooltip's
+explicit `position="left"`/`"right"`, and a toast's `top-left`/`top-right`/`bottom-left`/
+`bottom-right` corner. `"auto"` is the direction-aware tooltip placement; pick the corner you
+want for a toast.
+
 ## Theming
 
 Every value the components paint with lives in `styles/theme.css`, in three layers:
@@ -89,13 +112,13 @@ Every value the components paint with lives in `styles/theme.css`, in three laye
 **Foundation** — palette, type scale, spacing, motion. Override these to restyle everything at
 once; component tokens derive from them, so a palette swap carries through on its own.
 
-**Component** — `--gog-<block>-*`, one block per component, to restyle a single component
-app-wide:
+**Component** — `--gog-<component>-*`, one block per component, named after the component you
+write in markup (`gog-button` → `--gog-button-*`), to restyle a single component app-wide:
 
 ```css
 :root[data-theme='mine'] {
-  --gog-btn-font-family: var(--gog-font-body);
-  --gog-btn-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
+  --gog-button-font-family: var(--gog-font-body);
+  --gog-button-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
   --gog-table-hover-bg: var(--gog-hover-color);
 }
 ```
@@ -105,10 +128,21 @@ variant and size classes:
 
 ```css
 .my-form gog-button {
-  --gog-btn-bg: rebeccapurple; /* wins over .gog-btn--primary */
+  --gog-button-bg: rebeccapurple; /* wins over .gog-btn--primary */
 }
 ```
 
+> **Renamed in 21.5.0.** Three prefixes were abbreviated and are now spelled out:
+> `--gog-btn-*` → `--gog-button-*`, `--gog-confirm-*` → `--gog-confirmation-dialog-*`, and
+> `--gog-ms-*` → `--gog-multiselect-*` (that one since 21.3.0). **The old spellings still work**
+> — every new name derives from its old twin — and are **removed in 21.7.0**. A CSS override that
+> stops being read fails silently, which is why the window is two minors rather than one.
+>
+> One prefix that looks abbreviated and is not: **`--gog-input-*`**. It names the shared
+> text-field block that both `gog-inputfield` and `gog-textarea` render (`.gog-input__field`), not
+> the `gog-inputfield` component — the two are meant to restyle together from one token set, so
+> there is no `--gog-inputfield-*` and there will not be one.
+
 Every group and token name is in **[`TOKENS.md`](./TOKENS.md)**, generated from `theme.css` so it
 cannot drift, and available at runtime as `GOG_TOKEN_GROUPS`.
 
@@ -174,15 +208,15 @@ provideGogIcons({ cart: '<svg viewBox="0 0 24 24">…</svg>' });
 
 ## Components
 
-| Group | Components |
-| --- | --- |
-| Form controls | `gog-inputfield`, `gog-textarea`, `gog-select`, `gog-multiselect`, `gog-autocomplete`, `gog-checkbox`, `gog-radio-group`, `gog-toggle`, `gog-slider`, `gog-datepicker`, `gog-calendar`, `gog-button-toggle-group` |
-| Actions | `gog-button`, `gog-chip` |
-| Data | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag` |
-| Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll` |
-| Overlays | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`) |
-| Feedback | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton` |
-| Content | `gog-icon` |
+| Group               | Components                                                                                                                                                                                                        |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Form controls       | `gog-inputfield`, `gog-textarea`, `gog-select`, `gog-multiselect`, `gog-autocomplete`, `gog-checkbox`, `gog-radio-group`, `gog-toggle`, `gog-slider`, `gog-datepicker`, `gog-calendar`, `gog-button-toggle-group` |
+| Actions             | `gog-button`, `gog-chip`                                                                                                                                                                                          |
+| Data                | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag`                                                                                                                                                          |
+| Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll`                                                                                                                         |
+| Overlays            | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`), `gog-menu` (+ `gogMenuTrigger` / `gogMenuItem`)                                                                                   |
+| Feedback            | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton`                                                                                                                                           |
+| Content             | `gog-icon`                                                                                                                                                                                                        |
 
 **Directives:** `gogButton` (a link that looks like a button), `gogTooltip`, `gogBadge`,
 `gogCollapsibleTrigger`, `gogCollapsibleContent`.
@@ -209,11 +243,11 @@ A few things worth knowing before you reach for a workaround:
 
 ## Documentation
 
-| | |
-| --- | --- |
-| **[`AGENTS.md`](./AGENTS.md)** | the full API reference — every input, output, slot, type and default, per component. Ships in this package. |
-| **[`TOKENS.md`](./TOKENS.md)** | every `--gog-*` token, generated from `theme.css` |
-| [CHANGELOG](https://github.com/GuildOfGleks/gleks_web_ui/blob/master/projects/gleks/ui/CHANGELOG.md) | release history |
+|                                                                                                      |                                                                                                             |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **[`AGENTS.md`](./AGENTS.md)**                                                                       | the full API reference — every input, output, slot, type and default, per component. Ships in this package. |
+| **[`TOKENS.md`](./TOKENS.md)**                                                                       | every `--gog-*` token, generated from `theme.css`                                                           |
+| [CHANGELOG](https://github.com/GuildOfGleks/gleks_web_ui/blob/master/projects/gleks/ui/CHANGELOG.md) | release history                                                                                             |
 
 `AGENTS.md` is written for an AI coding assistant working in your project, but it is the most
 complete API reference either way — point your assistant at it and it will stop guessing.