npm - @guildofgleks/ui - Versions diffs - 21.4.4 → 21.5.1 - Mend

@guildofgleks/ui 21.4.4 → 21.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/AGENTS.md +135 -21
package/CHANGELOG.md +251 -17
package/README.md +73 -26
package/TOKENS.md +44 -44
package/fesm2022/guildofgleks-ui.mjs +2068 -376
package/fesm2022/guildofgleks-ui.mjs.map +1 -1
package/package.json +9 -10
package/styles/button.css +112 -79
package/styles/index.css +2 -0
package/styles/menu.css +104 -0
package/styles/theme.css +301 -235
package/styles/utilities.css +27 -0
package/types/guildofgleks-ui.d.ts +285 -138
package/src/styles/button.css +0 -193
package/src/styles/fonts.css +0 -16
package/src/styles/index.css +0 -19
package/src/styles/presets/one-dark.css +0 -48
package/src/styles/presets/one-light.css +0 -47
package/src/styles/presets/slate.css +0 -55
package/src/styles/theme.css +0 -1702
package/src/styles/typography.css +0 -15
package/src/styles/utilities.css +0 -185

package/AGENTS.md CHANGED Viewed

@@ -5,7 +5,9 @@ an app that **consumes** the published `@guildofgleks/ui` npm package. It is not
 authoring the library — if you are working inside the `gleks_web_ui` monorepo itself, read
 `.github/instructions/*.md` instead.
-Everything below reflects the library's actual source as of **`21.4.4`**. `README.md` covers the
+Everything below reflects the library's actual source as of **`21.5.1`**. 21.5.0 removed a batch
+of deprecated API — see **Removed in 21.5.0** near the end of this file, which exists so code
+written against 21.4.x can be migrated — and `CHANGELOG.md` has the rest. `README.md` covers the
 same ground at a higher level — install, setup, theming, global configuration — and is accurate;
 this file goes further, into per-component input tables, and is the one to trust for exact names,
 types and defaults.
@@ -168,17 +170,33 @@ Full model is in `README.md`'s Theming section and `theming.md`; short version:
 - Every visual value (color, spacing, radius, shadow, duration) is a `--gog-*` CSS custom
   property, layered **foundation** (`--gog-accent-color`, `--gog-space-md`, …, restyles
-  everything) → **component** (`--gog-btn-primary-bg`, …, one block per component) →
-  **instance** (`--gog-btn-bg`, …, deliberately undeclared escape hatch for one element).
+  everything) → **component** (`--gog-button-primary-bg`, …, one block per component, named after
+  the component's own element) → **instance** (`--gog-button-bg`, …, deliberately undeclared
+  escape hatch for one element).
+- **Component prefixes are spelled out** since 21.5.0: `--gog-button-*`, `--gog-multiselect-*`,
+  `--gog-confirmation-dialog-*`. The abbreviated `--gog-btn-*`, `--gog-ms-*` and `--gog-confirm-*`
+  still resolve and are removed in 21.7.0 — don't write new code with them. The exception is
+  `--gog-input-*`, which is not an abbreviation: it is the shared text-field block that
+  `gog-inputfield` and `gog-textarea` both render, and it keeps that name.
 - Theme switch is a `data-theme` attribute, usually on `<html>`, toggled through the
   `ThemeService` (`inject(ThemeService).setTheme('dark')` / `.toggleTheme()` / `.theme` signal).
   Ships `light` and `dark`. Three more importable presets: `slate`, `one-dark`, `one-light`
   (`@guildofgleks/ui/styles/presets/<name>.css`).
-- Restyle one instance without touching a theme: `<gog-button style="--gog-btn-bg: #ff4edb">`.
+- Restyle one instance without touching a theme: `<gog-button style="--gog-button-bg: #ff4edb">`.
 - Build a custom theme by declaring a palette against a new `data-theme` value (see
   `theming.md` for the full worked example) — component tokens re-derive automatically, you
   don't restate them.
+## Right-to-left
+Supported since 21.5.0. `dir="rtl"` on `<html>` or on any wrapper mirrors every component —
+you write nothing per component. Portaled overlays (select/multiselect panels, tooltip bubbles)
+copy a _scoped_ `dir` onto themselves, so an RTL region inside an LTR page works too.
+Physical by design, in both directions: `gogTooltip [position]="'left' | 'right'"` and
+`ToastConfig.position` (`'top-right'`, …). Use the tooltip's `'auto'` for direction-aware
+placement; a toast corner is a deliberate choice, so it is not mirrored.
 ## Global configuration — `GOG_CONFIG` / `provideGogConfig(...)`
 For the handful of inputs an app typically wants to set once (a size for every form control, a
@@ -604,7 +622,7 @@ not from `value`, since `value` clears the moment the text stops matching the se
 | `indeterminate`, `disabled`, `fullWidth` | `boolean`              | `false` |
 Model: `checked: boolean`. CVA: yes. Slot: `<ng-template gogCheckboxIcon>` for a custom tick
-icon (replaces the deprecated `checkIconTemplate` input).
+icon.
 ```html
 <gog-checkbox label="I agree to the terms" formControlName="agree" />
@@ -907,7 +925,7 @@ Outputs: `gogClick: MouseEvent | KeyboardEvent`, `gogRemove: void`.
 | `iconName`  | `GogIconName \| null` | `null`      |
 | `fullWidth` | `boolean`             | `false`     |
-Slot: `<ng-template gogTagIcon>` for custom icon markup (replaces the deprecated `iconTemplate`).
+Slot: `<ng-template gogTagIcon>` for custom icon markup.
 ```html
 <gog-tag variant="success">Active</gog-tag>
@@ -1042,6 +1060,12 @@ Model: `open: boolean`.
 </gog-collapsible>
 ```
+**The trigger can be any element.** On a `<button>` or `<a href>` the directive adds only the
+ARIA wiring, because the browser already handles focus and keys. On anything else — a `<div>`, a
+`<span>` — it also supplies `role="button"`, `tabindex="0"` and Enter/Space, so the control it
+announces is one a keyboard can actually reach. If you set `role` or `tabindex` yourself, the
+directive leaves both alone: you have said what the element is.
 An open panel is as tall as its content — `--gog-collapsible-max-height` defaults to
 `max-content`. Set it to a length on an instance to cap one deliberately; the panel is
 `overflow: hidden`, so a cap **clips** rather than scrolls. (Before 21.4.4 that default was
@@ -1298,6 +1322,75 @@ Methods (via template ref): `scrollTo(options)`, `scrollToTop()`, `scrollToBotto
 ### Overlays
+**Overlays and the viewport — the caveat that bites once per project.** `gog-dialog`'s backdrop,
+`gog-toast-container` and `gog-spinner [overlay]` are `position: fixed`, which covers the viewport
+only while no ancestor establishes a containing block. `contain`, `transform`, `filter`,
+`backdrop-filter` or `will-change` anywhere above retargets them to that element's box — and
+**`gog-scroll` sets `contain: layout style`**, so a dialog opened inside a scroller dims the
+scroller rather than the page. Place the dialog and toast outlets in the root component. The
+dropdown panels and `gog-menu` sidestep it by rendering into `<body>`.
+#### `gog-menu` + `gogMenuTrigger` / `gogMenuItem`
+A command menu. The trigger is a directive on **your own button** — usually the icon button you
+already styled — and the items are your own buttons too, so an item can hold an icon, a label and
+a shortcut hint without an input per piece:
+```html
+<button gogButton variant="ghost" [gogMenuTrigger]="rowMenu" aria-label="Row actions">
+  <gog-icon name="more-vertical" />
+</button>
+<gog-menu #rowMenu ariaLabel="Row actions">
+  <button gogMenuItem (click)="edit(row)"><gog-icon name="check" /> Edit</button>
+  <button gogMenuItem disabled>Transfer ownership</button>
+  <button gogMenuItem (click)="remove(row)"><gog-icon name="close" /> Remove</button>
+</gog-menu>
+```
+| Input       | Type                       | Default  | Notes                                                                        |
+| ----------- | -------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `direction` | `'auto' \| 'up' \| 'down'` | `'auto'` | `'auto'` drops down whenever the panel fits and flips up only when it cannot |
+| `ariaLabel` | `string`                   | `''`     | Names the panel itself                                                       |
+**There is no `appendToBody`.** The panel always renders into `<body>` and is placed from the
+trigger's measured rect, so a menu inside `gog-scroll`, `gog-table` or any `overflow: hidden`
+ancestor is not clipped and needs no configuration. It also takes the `--gog-dropdown-z` its
+trigger inherits, so a menu opened inside a `gog-dialog` stacks above the dialog.
+Output: `gogClosed` — fires after every close, whatever caused it.
+Public methods, for driving it yourself: `open(trigger, 'first' | 'last')`, `close(restoreFocus?)`,
+`toggle(trigger)`, and the `isOpen` signal.
+**Keyboard**, the WAI-ARIA menu button pattern: Enter/Space/ArrowDown open with the first item
+focused, ArrowUp opens with the last, arrows and Home/End move between items and step over
+disabled ones, Escape closes and returns focus to the trigger, Tab closes and lets focus move on.
+A press outside closes without pulling focus back.
+**Disabling an item** is the native `disabled` attribute on your own button — static or bound,
+there is no input for it:
+```html
+<button gogMenuItem disabled>Transfer ownership</button>
+<button gogMenuItem [disabled]="isLocked()" (click)="edit()">Edit</button>
+```
+A disabled item stays in the list rather than disappearing (removing it would shift the others
+under the pointer), the arrow keys step over it, and clicking it does nothing.
+**A long menu scrolls itself**, using `gog-scroll` — the same thin, auto-hiding scroller as
+everywhere else in the package, with `overscrollBehavior="contain"` so a wheel at the end of the
+list does not scroll the page behind it. Arrowing past the last visible item scrolls it into view.
+The panel's height is the smallest of three: its own content, `--gog-menu-max-height` (320px by
+default), and the room between the trigger and the viewport edge. Lower the token to make a menu
+scroll sooner. **In 21.5.0 the token did nothing** — the measured room was written onto the panel
+as an inline `max-height`, which beat it; fixed in 21.5.1.
+A closed menu renders nothing at all, so its commands are not in the accessibility tree until it
+opens.
 #### `gog-dialog`
 A **single** `<gog-dialog />` renders **every** dialog `DialogService.open(...)` creates —
@@ -1335,24 +1428,45 @@ screen readers, and a second region would announce everything twice. Don't add e
 ---
-## Deprecated patterns — do not use in new code
+## Reading the deprecations at runtime — `GOG_DEPRECATIONS`
-These still work (nothing breaks if you use them), but are marked `@deprecated` and **will be
-removed** on the stated schedule. Don't generate new code using any of them — use the listed
-replacement instead.
+Everything the package currently deprecates, as data:
-| Deprecated                                                                                                       | Removed in | Replacement                                                                                                     |
-| ---------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
-| `GogSelectOption`, `GogMultiselectOption` type aliases                                                           | `21.4.0`   | `GogDropdownOption`                                                                                             |
-| `gog-select`/`gog-multiselect` `chevronTemplate` input                                                           | `21.5.0`   | `<ng-template gogDropdownChevron>`                                                                              |
-| `gog-checkbox` `checkIconTemplate` input                                                                         | `21.5.0`   | `<ng-template gogCheckboxIcon>`                                                                                 |
-| `gog-tag` `iconTemplate` input                                                                                   | `21.5.0`   | `<ng-template gogTagIcon>`                                                                                      |
-| `gog-multiselect` `clearIconTemplate` input                                                                      | `21.5.0`   | `<ng-template gogMultiselectClearIcon>`                                                                         |
-| `gog-inputfield` `iconStartTemplate`/`iconEndTemplate`/`iconStartFn`/`iconEndFn`/`iconStartLabel`/`iconEndLabel` | `21.5.0`   | `<span gogInputAddonStart>`/`<span gogInputAddonEnd>` (or a `<button>` with its own handler)                    |
-| `gog-table`'s `[template]` attribute (`<ng-template template="field" type="body">`)                              | `21.5.0`   | `<ng-template gogColumnBody>` / `<ng-template gogColumnHeader>` declared **inside** the matching `<gog-column>` |
-| `<column>` selector / `Column` export                                                                            | `21.5.0`   | `<gog-column>` / `GogColumn`                                                                                    |
+```ts
+import { GOG_DEPRECATIONS, type GogDeprecation } from '@guildofgleks/ui';
+GOG_DEPRECATIONS.filter((entry) => entry.removedIn === '21.7.0');
+// { kind: 'token', name: '--gog-btn-bg', replacement: '--gog-button-bg',
+//   since: '21.5.0', sinceDate: '2026-08-19', removedIn: '21.7.0' }
+```
-The general rule they all follow: a `TemplateRef` **input** or a string-keyed lookup is the old
+`kind` is `'symbol'` for an export or input and `'token'` for a `--gog-*` custom property. The
+list is generated from the library's source — tags for symbols, stylesheets for tokens — so it
+matches what actually still resolves in the version you installed.
+**In 21.5.0 it holds 154 tokens and no symbols.** Nothing in the TypeScript API is deprecated
+right now; the three abbreviated token prefixes are, until 21.7.0.
+## Removed in 21.5.0
+**Nothing in this table exists any more.** It is here so that code written against 21.4.x — or
+generated from a stale copy of this file — can be migrated: each row names what a call site must
+become. If you are writing new code, ignore this section entirely and use the right-hand column,
+which is documented in full above.
+| Removed                                                                                                          | Replacement                                                                                                     |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `gog-select`/`gog-multiselect` `chevronTemplate` input                                                           | `<ng-template gogDropdownChevron>`                                                                              |
+| `gog-checkbox` `checkIconTemplate` input                                                                         | `<ng-template gogCheckboxIcon>`                                                                                 |
+| `gog-tag` `iconTemplate` input                                                                                   | `<ng-template gogTagIcon>`                                                                                      |
+| `gog-multiselect` `clearIconTemplate` input                                                                      | `<ng-template gogMultiselectClearIcon>`                                                                         |
+| `gog-inputfield` `iconStartTemplate`/`iconEndTemplate`/`iconStartFn`/`iconEndFn`/`iconStartLabel`/`iconEndLabel` | `<span gogInputAddonStart>`/`<span gogInputAddonEnd>` (or a `<button>` with its own handler)                    |
+| `gog-table`'s `[template]` attribute (`<ng-template template="field" type="body">`)                              | `<ng-template gogColumnBody>` / `<ng-template gogColumnHeader>` declared **inside** the matching `<gog-column>` |
+| `<column>` selector / `Column` export                                                                            | `<gog-column>` / `GogColumn`                                                                                    |
+| `GogSelectOption` / `GogMultiselectOption` types                                                                 | `GogDropdownOption` (the same type — they were aliases of it)                                                   |
+| `@guildofgleks/ui/src/styles/…` asset path                                                                       | `@guildofgleks/ui/styles/…`                                                                                     |
+The general rule they all followed: a `TemplateRef` **input** or a string-keyed lookup was the old
 shape; a **projected content directive with a typed context**, declared where it's used, is the
 current one. If you're about to write `fooTemplate` next to an existing `foo` input, or key
 something off a string that has to match another string elsewhere, that's this exact

package/CHANGELOG.md CHANGED Viewed

@@ -4,32 +4,266 @@ 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.5.1] - planned
+Two defects 21.5.0 shipped, both of the same shape: correct-looking CSS whose effect was cancelled
+by something else in the box model, and neither visible to a test suite that runs without a style
+engine. Both were found by opening the components in a browser while writing the documentation
+site's pages for them. No input, output, type or public token changed, so upgrading from 21.5.0 is
+a version bump with nothing to migrate.
+### Fixed
+- **`--gog-menu-max-height` now caps the panel.** It never did: `gog-menu` measured the room
+  between its trigger and the viewport edge and wrote that onto the panel as an inline
+  `max-height`, which beats the stylesheet rule the token feeds. Setting
+  `--gog-menu-max-height: 150px` on a page with 500px of room changed nothing, and a menu of any
+  length simply grew until it ran out of screen.
+  The measured room is now handed to CSS as `--gog-menu-available-height` and `menu.css` takes the
+  smaller of the two, so a panel's height is the least of its content, the token, and the room
+  available. Lower the token to make a menu start scrolling sooner.
+  A menu that flips **up** is now anchored by its `bottom` rather than by a `top` computed from
+  its expected height. That is what makes the cap safe: with the old arithmetic, a panel the token
+  cut short would have floated away from its trigger by exactly the height it did not take.
+- **Text no longer runs underneath a field's own icon in RTL.** `gog-inputfield`, `gog-select`,
+  `gog-autocomplete` and `gog-datepicker` each reserve a gutter for their leading or trailing
+  chrome. The chrome is placed with `inset-inline-start` / `inset-inline-end` — logical — but the
+  gutter was a physical `padding-left`/`padding-right`, so under `dir="rtl"` the two ended up on
+  opposite sides: the icon at one edge, the space kept for it stranded at the other, and the value
+  or placeholder rendering under the icon. A floating label offset itself by the wrong gutter for
+  the same reason, and a clearable `gog-select` was padded on both sides at once.
+  All four now use `padding-block` + `padding-inline`. `gog-inputfield`'s two internal properties
+  are renamed to match what they now mean — `--gog-input-pl`/`-pr` became `--gog-input-ps`/`-pe`
+  (inline **start** / **end**). Neither was ever public: they are not in `GogTokenName`, not in
+  `TOKENS.md` and not declared in `theme.css`, so nothing a consumer can have written changes.
+  Left-to-right rendering is byte-for-byte what it was.
+  **`npm run check:logical-properties` now fails the build** on a `padding`, `margin`,
+  `border-width` or `border-radius` shorthand that sets the two horizontal sides differently.
+  21.5.0 converted 16 stylesheets to logical properties and still missed these four, because the
+  sidedness lives in a value's *position inside a shorthand* rather than in a `left`/`right`
+  keyword — invisible to a grep, and invisible to a unit test with no style engine.
+- **Documented the `position: fixed` containing-block caveat**, in one place plus a line on each
+  overlay it affects. `gog-dialog`'s backdrop, `gog-toast-container` and
+  `gog-spinner [overlay]` cover the viewport only while no ancestor establishes a containing
+  block — `contain`, `transform`, `filter`, `backdrop-filter` or `will-change` above them
+  retargets the overlay to that element's box, with no error and no warning. `gog-scroll` sets
+  `contain: layout style`, so this library can trigger it on its own: a dialog opened inside a
+  scroller dims the scroller. Nothing changed in behaviour; what changed is that the behaviour is
+  now written down where you meet it — README's "Overlays and the viewport", `AGENTS.md`, and the
+  TSDoc of each overlay.
 ## [21.5.0] - planned
 **The breaking release** — the one version consumers have to read before upgrading into. It
-carries the removals below and, per `docs/hardening-21.5.0.md`, the token-prefix rename
-(`--gog-ms-*`, `--gog-btn-*`, `--gog-input-*` spelled out in full). Everything non-breaking that
-is ready today ships 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.
+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
-Not done yet — this section records what the version owes. Fourteen public symbols carry an
-`@deprecated … Removed in 21.5.0` tag naming its own replacement:
+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.
-- 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;
-- the `GogSelectOption` / `GogMultiselectOption` aliases — **these two overran their announced
-  21.4.0 removal**, which is the reason the date on this list is not moved again.
+  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.
-One more is promised in prose rather than by a tag, so it has no `@deprecated` to grep for and is
-the one most likely to be missed:
+- **`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
-- the **`./src/styles/*` export** in `package.json`. Stylesheets moved to `./styles/*` in 21.3.2
-  and the README says the old path "keeps working until 21.5.0". Removing it breaks anyone still
-  importing `@guildofgleks/ui/src/styles/…`, and the README paragraph promising it goes too.
+- **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