@guildofgleks/ui 21.6.0 → 21.7.0

package/AGENTS.md

@@ -5,12 +5,13 @@ 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.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.
+Everything below reflects the library's actual source as of **`21.7.0`**. 21.7.0 removed the three
+abbreviated token prefixes and 21.5.0 removed a batch of deprecated API — see **Removed in 21.7.0**
+and **Removed in 21.5.0** near the end of this file, which exist so code written against an older
+version 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.
 
 > **Maintainers:** this file ships inside the npm package and is the API reference an agent reads
 > while writing code against it, so a stale table here becomes wrong code in someone else's app —
@@ -166,30 +167,66 @@ exist.
 
 ## Theming
 
-Full model is in `README.md`'s Theming section and `theming.md`; short version:
+Full model is in `README.md`'s Theming section; 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-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).
+- **Foundation includes a small character layer** (since 21.7.0, `docs/themes.md` iteration 1):
+  `--gog-radius` (corner rounding), `--gog-control-border-*`/`--gog-panel-border-*`/`--gog-border-*`
+  (border weight — form fields, raised surfaces, everything smaller and inline, respectively),
+  `--gog-text-transform`/`--gog-letter-spacing` (emphasis casing/tracking). Component tokens in
+  the categories these cover derive from them by default; setting one in a `[data-theme]` block
+  restyles every component that reads it, with nothing to re-list per component.
+- **`--gog-density` is the character layer for spacing** (since 21.7.0, `docs/themes.md`
+  iteration 6). It multiplies the fourteen-step scale `--gog-space-2` … `--gog-space-48`, named
+  for their pixel value at density 1, and every padding and gap in the library derives from a
+  step. `--gog-density: 0.9` in a `[data-theme]` block makes the whole library tighter; nothing
+  else needs to be named. `--gog-space-xs|sm|md|lg|2xl` are aliases for steps 4/8/16/24/48 and
+  still work. Icon offsets follow density; the glyph box, focus-ring offset and float-label
+  reserve deliberately do not — they are legibility, not spacing.
 - **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.
+  were removed in 21.7.0 — if you're reading a codebase or an example that still uses one, rename
+  it; it no longer resolves. 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.
 - **The package does not need the app's `box-sizing` reset** (since 21.6.0): `utilities.css`
   sets `border-box` on every element carrying a `gog-*` class, including the ones the library
   puts on a consumer's own element. Do not add a reset "so the components line up" — they
   already do, and a `* { box-sizing: content-box }` in an app is the only thing that undoes it.
 - 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`).
+  Ships `light` and `dark`, plus nine importable presets at
+  `@guildofgleks/ui/styles/presets/<name>.css`. **All nine set palette and character** (since
+  21.7.0 — before it, three were palette-only, which made them recoloured defaults):
+
+  | Preset                 | Radius | Density | Identity                                         |
+  | ---------------------- | ------ | ------- | ------------------------------------------------ |
+  | `slate`                | 12px   | 1.05    | soft modern — hairline borders, roomy            |
+  | `one-dark`/`one-light` | 4px    | 0.9     | editor chrome; identical character, two tones    |
+  | `material`             | 4px    | 1.1     | Material Design 3, pill buttons                  |
+  | `primeng`              | 6px    | 0.95    | PrimeNG Aura                                     |
+  | `ledger`               | 0      | 0.9     | administrative — hard offset shadow, no motion   |
+  | `terminal`             | 0      | 0.85    | green phosphor, monospaced throughout, no motion |
+  | `bevel`                | 0      | 0.9     | early-web desktop — `outset`/`inset` borders     |
+  | `parchment`            | 0      | 1.1     | ink on paper — old-style serif, oxblood          |
+
+  `material`, `primeng` and `bevel` also set a few genuinely per-component things the character
+  layer has no vocabulary for (a pill button, a table's header font, a button bevel that has to
+  disagree with a field's); see their own file headers.
+
+- **A preset never makes a network request.** Each sets a font _stack_ resolving to a real system
+  face. Where a webfont is worth offering, it is a separate opt-in file — `terminal.fonts.css`
+  (IBM Plex Mono), `parchment.fonts.css` (EB Garamond) — imported **after** the preset, since it
+  re-points the same tokens and later wins. Do not add an `@import url(…)` to a preset itself; put
+  it in a companion file, or the import becomes a download nobody asked for.
 - 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.
+- Build a custom theme by declaring a palette **and a character** against a new `data-theme`
+  value (see `README.md`'s Theming section for the full worked example) — component tokens
+  re-derive automatically, you don't restate them.
 
 ## Right-to-left
 
@@ -235,6 +272,7 @@ parent's config**, one level deep per key — it does not replace it.
 | `tooltip`      | `position`, `showDelay`, `hideDelay`                                    | the `gogTooltip` directive.                                                                                                                                                                                                                                                                                                                                                                                  |
 | `scroll`       | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`      | `gog-scroll` (and every component that uses one internally).                                                                                                                                                                                                                                                                                                                                                 |
 | `button`       | `debounce`                                                              | `gog-button`.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `ripple`       | `enabled`                                                               | the press ripple on `gog-button`, `[gogButton]`, `gog-button-toggle-group`, `gog-chip`, `gog-tabs`, `gog-accordion`, `gogCollapsibleTrigger`, `gogMenuItem` and the `gog-select`/`gog-multiselect`/`gog-autocomplete` options. **Off by default.** Each of those takes a `ripple` input that wins over it. Not the `gogRipple` directive — writing that attribute is already the per-element decision.       |
 | `inputfield`   | `showSpinButtons`                                                       | `gog-inputfield`.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `textarea`     | `resize`                                                                | `gog-textarea`.                                                                                                                                                                                                                                                                                                                                                                                              |
 | `paginator`    | `showPageSizeSelect`, `pageSizeOptions`                                 | `gog-paginator`, and through it `gog-table`'s built-in pagination.                                                                                                                                                                                                                                                                                                                                           |
@@ -252,39 +290,39 @@ in English sets these once rather than on every control:
 ```ts
 provideGogConfig({
   labels: {
-    clear: 'Очистить', // inputfield / textarea clear button
-    clearSelection: 'Очистить выбор', // select / multiselect / autocomplete
-    clearDate: 'Очистить дату', // datepicker
-    selectAll: 'Выбрать все', // multiselect panel
-    clearAll: 'Очистить', // multiselect panel
-    increment: 'Увеличить', // number spin buttons
-    decrement: 'Уменьшить',
-    showPassword: 'Показать пароль',
-    hidePassword: 'Скрыть пароль',
-    closeDialog: 'Закрыть',
-    closeToast: 'Закрыть',
-    pagination: 'Навигация по страницам',
-    previousPage: 'Предыдущая страница',
-    nextPage: 'Следующая страница',
-    openCalendar: 'Открыть календарь',
-    rowsPerPage: 'Строк на странице', // gog-paginator's size select
-    total: 'Всего', // gog-table's row-count label
-    tablePagination: 'Навигация по таблице',
-    selectRow: 'Выбрать строку',
-    selectAllRows: 'Выбрать все строки на странице',
-    today: 'Сегодня',
-    thisMonth: 'Текущий месяц',
-    previousMonth: 'Предыдущий месяц',
-    nextMonth: 'Следующий месяц',
-    previousYear: 'Предыдущий год',
-    nextYear: 'Следующий год',
-    hours: 'Часы',
-    minutes: 'Минуты',
-    seconds: 'Секунды',
+    clear: 'Löschen', // inputfield / textarea clear button
+    clearSelection: 'Auswahl löschen', // select / multiselect / autocomplete
+    clearDate: 'Datum löschen', // datepicker
+    selectAll: 'Alle auswählen', // multiselect panel
+    clearAll: 'Alle löschen', // multiselect panel
+    increment: 'Erhöhen', // number spin buttons
+    decrement: 'Verringern',
+    showPassword: 'Passwort anzeigen',
+    hidePassword: 'Passwort verbergen',
+    closeDialog: 'Schließen',
+    closeToast: 'Schließen',
+    pagination: 'Seitennavigation',
+    previousPage: 'Vorherige Seite',
+    nextPage: 'Nächste Seite',
+    openCalendar: 'Kalender öffnen',
+    togglePanel: 'Bereich umschalten', // gog-panel's toggle, only when it has no heading
+    rowsPerPage: 'Zeilen pro Seite', // gog-paginator's size select
+    total: 'Gesamt', // gog-table's row-count label
+    tablePagination: 'Tabellennavigation',
+    selectRow: 'Zeile auswählen',
+    selectAllRows: 'Alle Zeilen auswählen',
+    today: 'Heute',
+    thisMonth: 'Aktueller Monat',
+    previousMonth: 'Vorheriger Monat',
+    nextMonth: 'Nächster Monat',
+    previousYear: 'Vorheriges Jahr',
+    nextYear: 'Nächstes Jahr',
+    hours: 'Stunden',
+    minutes: 'Minuten',
+    seconds: 'Sekunden',
     // The one non-string field: it interpolates the page number, and word order and
     // agreement around a number vary by language, so it takes a formatter.
-    page: (page, isCurrent) =>
-      isCurrent ? `Страница ${page}, текущая` : `Перейти на страницу ${page}`,
+    page: (page, isCurrent) => (isCurrent ? `Seite ${page}, aktuell` : `Zu Seite ${page} wechseln`),
   },
 });
 ```
@@ -320,7 +358,7 @@ provideGogConfig({
     followSystem: true, // open in the OS prefers-color-scheme, and keep following it
     // until the app calls setTheme/toggleTheme
     lightTheme: 'light', // the two names followSystem maps to and toggleTheme alternates
-    darkTheme: 'cyberpunk', // between
+    darkTheme: 'one-dark', // between
     defaultTheme: 'light', // used when nothing else decides
   },
 });
@@ -368,10 +406,31 @@ async confirmDelete(): Promise<void> {
 }
 ```
 
-`DialogConfig`: `{ title?, component, data?, modal? (default true), closable?, draggable?, closeIconName?, closeIconTemplate?, width?, maxWidth?, role? ('dialog' default | 'alertdialog'), zIndex? }`.
-`open()` returns `{ close(result?), afterClosed: Promise<TResult | undefined> }`. Also:
+`DialogConfig<TData>`: `{ title?, component, data?: TData, modal? (default true), closable?, draggable?, closeIconName?, closeIconTemplate?, width?, maxWidth?, role? ('dialog' default | 'alertdialog'), zIndex? }`.
+`open<TResult, TData>()` returns `{ close(result?), afterClosed: Promise<TResult | undefined> }`. Also:
 `closeAll(result?)`, `updatePosition(id, offsetX, offsetY)` (for `draggable` dialogs).
 
+**`open<TResult, TData>()` type-checks `data` against `TData` when you supply both type
+arguments** — supplying only `TResult` (the common case above) leaves `TData` as `unknown`,
+exactly as before:
+
+```ts
+interface EditUserData {
+  userId: string;
+}
+
+const handle = this.dialogService.open<{ saved: boolean }, EditUserData>({
+  component: EditDialogComponent,
+  data: { userId: user.id }, // checked against EditUserData here
+});
+```
+
+This checks only the call site. `EditDialogComponent` still reads its data via `inject(DIALOG_DATA)`
+— an `InjectionToken<unknown>` shared by every dialog, so it still needs its own cast
+(`inject<EditUserData>(DIALOG_DATA)`, shown below). Angular's DI has no way to carry a
+per-call-site type through one shared token, so the receiving half of the round trip is still on
+trust — this closes only the half that can be closed.
+
 The library ships a ready-made `ConfirmationDialogComponent` for yes/no prompts — pass it as
 `component` with `data: { title, description, confirmText, cancelText }`; it resolves the
 dialog's result to `true`/`false`.
@@ -415,12 +474,20 @@ Every component below is exported from `@guildofgleks/ui`'s root — `import { X
 | `loading`   | `boolean`                         | `false`     | shows an inline `gog-spinner`, blocks clicks          |
 | `debounce`  | `number \| undefined`             | `300`       | ms; via `GOG_CONFIG.button.debounce` — see note below |
 | `ariaLabel` | `string \| null`                  | `null`      | **use this, not a raw `aria-label` attribute**        |
+| `ripple`    | `boolean \| undefined`            | `false`     | press ripple; via `GOG_CONFIG.ripple.enabled`         |
 
 Outputs: `gogClick: MouseEvent`.
 
 **`debounce` is a spam guard, not a delay before the first click.** The first click in a window
 fires immediately (leading edge); further clicks within `debounce` ms are silently dropped.
 
+**Use `(gogClick)`, never `(click)`, on `gog-button`.** The click handler that drives `debounce`
+and emits `gogClick` is bound on the `<button>` inside the component's own template, not on the
+host — a native click still bubbles up through `<gog-button>`, so a `(click)` listener written
+there fires on every press, silently bypassing the debounce entirely. This is specific to the
+component: `[gogButton]` on your own `<a>`/`<button>` has no debounce to bypass, so `(click)` on
+it works exactly as written.
+
 ```html
 <gog-button variant="primary" [loading]="saving()" (gogClick)="save()">Save</gog-button>
 <gog-button variant="ghost" ariaLabel="Close" (gogClick)="close()"
@@ -432,18 +499,19 @@ fires immediately (leading edge); further clicks within `debounce` ms are silent
 
 A row of buttons, single- or multi-select, built from your own option objects.
 
-| Input                                | Type                                       | Default                | Notes                                 |
-| ------------------------------------ | ------------------------------------------ | ---------------------- | ------------------------------------- |
-| `options`                            | `TOption[]`                                | `[]`                   |                                       |
-| `optionLabel`                        | accessor                                   | `'name'`               |                                       |
-| `optionValue`                        | accessor \| `null`                         | `'id'`                 | `null` emits the option object        |
-| `optionDisabled`                     | accessor                                   | `'disabled'`           |                                       |
-| `optionIcon`                         | accessor → `GogIconName \| null` \| `null` | `null`                 | optional leading icon per option      |
-| `multiple`                           | `boolean`                                  | `false`                | changes ARIA role entirely — see note |
-| `appearance`                         | `'joined' \| 'separated'`                  | `'joined'`             |                                       |
-| `orientation`                        | `GogOrientation`                           | `'horizontal'`         |                                       |
-| `size`                               | `GogSize \| undefined`                     | `'md'`                 | via `GOG_CONFIG.control.size`         |
-| `disabled`, `fullWidth`, `ariaLabel` |                                            | `false`, `false`, `''` |                                       |
+| Input                                | Type                                       | Default                | Notes                                         |
+| ------------------------------------ | ------------------------------------------ | ---------------------- | --------------------------------------------- |
+| `options`                            | `TOption[]`                                | `[]`                   |                                               |
+| `optionLabel`                        | accessor                                   | `'name'`               |                                               |
+| `optionValue`                        | accessor \| `null`                         | `'id'`                 | `null` emits the option object                |
+| `optionDisabled`                     | accessor                                   | `'disabled'`           |                                               |
+| `optionIcon`                         | accessor → `GogIconName \| null` \| `null` | `null`                 | optional leading icon per option              |
+| `multiple`                           | `boolean`                                  | `false`                | changes ARIA role entirely — see note         |
+| `appearance`                         | `'joined' \| 'separated'`                  | `'joined'`             |                                               |
+| `orientation`                        | `GogOrientation`                           | `'horizontal'`         |                                               |
+| `size`                               | `GogSize \| undefined`                     | `'md'`                 | via `GOG_CONFIG.control.size`                 |
+| `disabled`, `fullWidth`, `ariaLabel` |                                            | `false`, `false`, `''` |                                               |
+| `ripple`                             | `boolean \| undefined`                     | `false`                | press ripple; via `GOG_CONFIG.ripple.enabled` |
 
 Model: `value: TValue | TValue[] | null` (single value, or array in `multiple` mode). CVA: yes.
 Slot: `<ng-template gogButtonToggleOption let-opt let-selected="selected">` for custom button
@@ -552,6 +620,7 @@ and multiselect unless noted otherwise):
 | `disabled`, `fullWidth`                                |                                         | `false`, `true`                                              |                                                                                     |
 | `floatLabel`, `floatLabelShowPlaceholder`              |                                         | `'none'`, `false`                                            |                                                                                     |
 | `inputId` (select/autocomplete only)                   | `string`                                | `''`                                                         |                                                                                     |
+| `ripple`                                               | `boolean \| undefined`                  | `false`                                                      | press ripple; via `GOG_CONFIG.ripple.enabled`                                       |
 
 `gog-select`-specific: `value: model<TValue>(null)`.
 `gog-multiselect`-specific additions: `value: model<TValue[]>([])`, `showControls: boolean` (default `false`, a select-all/clear row), `controlsPosition: 'top'|'bottom'` (default `'top'`), and `selectAllLabel`/`clearAllLabel` for that row's two buttons (`'Select all'`/`'Clear'`, also via `GOG_CONFIG.labels`).
@@ -595,6 +664,7 @@ panel-filter box; it filters/searches off what's typed in the field itself.
 | `loading`                                                                                              | `boolean`              | `false`        | shows a spinner in the trailing slot                                                                                                     |
 | `emptyMessage`                                                                                         | `string`               | `'No matches'` |                                                                                                                                          |
 | `forceSelection`                                                                                       | `boolean`              | `true`         | see note below                                                                                                                           |
+| `ripple`                                                                                               | `boolean \| undefined` | `false`        | press ripple; via `GOG_CONFIG.ripple.enabled`                                                                                            |
 
 Outputs: `gogSearch: string` (debounced query — wire your server lookup here),
 `gogLoadMore: void` (panel scrolled to the end — fetch the next page).
@@ -855,11 +925,12 @@ the element stays yours and the directive only gives it the look.
 <a gogButton fullWidth routerLink="/checkout">Checkout</a>
 ```
 
-| Input       | Type                     | Default                               |
-| ----------- | ------------------------ | ------------------------------------- |
-| `variant`   | `GogVariant`             | `'primary'`                           |
-| `size`      | `GogSize \| undefined`   | `'md'`; via `GOG_CONFIG.control.size` |
-| `fullWidth` | `boolean` (bare attr ok) | `false`                               |
+| Input       | Type                     | Default                                  |
+| ----------- | ------------------------ | ---------------------------------------- |
+| `variant`   | `GogVariant`             | `'primary'`                              |
+| `size`      | `GogSize \| undefined`   | `'md'`; via `GOG_CONFIG.control.size`    |
+| `fullWidth` | `boolean` (bare attr ok) | `false`                                  |
+| `ripple`    | `boolean \| undefined`   | `false`; via `GOG_CONFIG.ripple.enabled` |
 
 Selector is `a[gogButton], button[gogButton]` — deliberately not a bare `[gogButton]`, because on
 a `<div>` the result looks like a button and is invisible to the keyboard and to assistive tech.
@@ -900,16 +971,17 @@ are impossible by design.
 
 #### `gog-chip`
 
-| Input                          | Type                                | Default               |
-| ------------------------------ | ----------------------------------- | --------------------- |
-| `size`                         | `GogSize`                           | `'md'`                |
-| `shape`                        | `GogTagShape` (`'rounded'\|'pill'`) | `'rounded'`           |
-| `disabled`, `clickable`        | `boolean`                           | `false`, `true`       |
-| `removable`                    | `boolean`                           | `false`               |
-| `fullWidth`                    | `boolean`                           | `false`               |
-| `ariaLabel`, `removeAriaLabel` | `string`                            | `''`, `'Remove chip'` |
-| `avatarUrl`, `avatarAlt`       | `string \| null` / `string`         | `null`, `''`          |
-| `iconName`                     | `GogIconName \| null`               | `null`                |
+| Input                          | Type                                | Default                                  |
+| ------------------------------ | ----------------------------------- | ---------------------------------------- |
+| `size`                         | `GogSize`                           | `'md'`                                   |
+| `shape`                        | `GogTagShape` (`'rounded'\|'pill'`) | `'rounded'`                              |
+| `disabled`, `clickable`        | `boolean`                           | `false`, `true`                          |
+| `removable`                    | `boolean`                           | `false`                                  |
+| `fullWidth`                    | `boolean`                           | `false`                                  |
+| `ariaLabel`, `removeAriaLabel` | `string`                            | `''`, `'Remove chip'`                    |
+| `avatarUrl`, `avatarAlt`       | `string \| null` / `string`         | `null`, `''`                             |
+| `iconName`                     | `GogIconName \| null`               | `null`                                   |
+| `ripple`                       | `boolean \| undefined`              | `false`; via `GOG_CONFIG.ripple.enabled` |
 
 Outputs: `gogClick: MouseEvent | KeyboardEvent`, `gogRemove: void`.
 
@@ -1000,6 +1072,63 @@ Label is projected content, not an input — put an icon or a `gog-tag` inside i
 <gog-divider>OR</gog-divider>
 ```
 
+#### `gogRipple` — directive, not a component
+
+A pointer-position wash that grows from where you pressed and fades when you let go. Drop it on
+any element you already have — it adds no wrapper and changes no layout.
+
+| Input            | Type      | Default                                                     |
+| ---------------- | --------- | ----------------------------------------------------------- |
+| `rippleDisabled` | `boolean` | `false`                                                     |
+| `rippleCentred`  | `boolean` | `false` — start from the middle instead of from the pointer |
+
+```html
+<button gogRipple>Press me</button>
+<div gogRipple rippleCentred class="tile">A tile</div>
+```
+
+Four things suppress it, none of which you have to wire up: `rippleDisabled`, a host carrying
+`disabled`, a host carrying `aria-disabled="true"`, and `prefers-reduced-motion: reduce` — the
+last one **suppressed outright, not shortened**. Keyboard activation (`Enter`/`Space`) is always
+centred, because a key press carries no coordinates.
+
+**Put it on the element that paints the surface.** The wash lives in its own layer that clips
+itself — the host is never given `overflow: hidden`, so a `gogBadge` on the same element is not
+clipped — and that layer takes its corner radius from its host with `border-radius: inherit`. On a
+wrapper whose _child_ paints the rounded background, the layer inherits the wrapper's radius (very
+often `0`) and the wash squares off at the corners.
+
+Tokens: `--gog-ripple-color` (`currentColor`, so the wash reads as the surface's own foreground on
+a filled surface and a ghost one alike), `--gog-ripple-opacity`, `--gog-ripple-enter-duration`,
+`--gog-ripple-exit-duration`, `--gog-ripple-easing`. All five are ordinary inherited custom
+properties, so setting one anywhere above the host is the per-instance override.
+
+#### Turning the ripple on for the library's own components
+
+You do **not** add `gogRipple` to a `gog-*` component: each one already owns the element that
+paints its surface, so it wires its own. What you do is switch it on, once:
+
+```ts
+provideGogConfig({ ripple: { enabled: true } });
+```
+
+That covers `gog-button`, `[gogButton]`, `gog-button-toggle-group`, `gog-chip`, `gog-tabs`
+headers, `gog-accordion` headers, `gogCollapsibleTrigger`, `gogMenuItem`, and the options inside
+`gog-select` / `gog-multiselect` / `gog-autocomplete`. `gog-paginator` follows because its page
+buttons are `gog-button`s.
+
+**Off by default**, so adding the ripple to the library changed the look of nothing. Every one of
+those takes a `ripple` input that beats the config in both directions: `[ripple]="false"` opts one
+control out of an app-wide on, `[ripple]="true"` opts one in without switching the app over.
+
+Not covered, and deliberately: `gog-table` rows and `gogCardLink`. A row and a card are hundreds
+of pixels wide, so the wave has to travel the whole surface and reads as a flash rather than as
+feedback at the point you pressed — and a table renders one directive per row, with no
+virtualization in this library yet. Put `gogRipple` on them yourself if you disagree.
+
+A chip that is not `clickable`, or is `disabled`, never ripples whatever the config says: a label
+answering a press is a promise it cannot keep.
+
 #### `gogTooltip` — directive, not a component
 
 Drop on any element — a `gog-*` component's host tag or a plain native one.
@@ -1029,6 +1158,7 @@ Drop on any element — a `gog-*` component's host tag or a plain native one.
 | `skeletonCount`                   | `number`                                                                  | `3` — rows shown while `loading` and `items` is still empty |
 | `showChevron`                     | `boolean`                                                                 | `true`                                                      |
 | `headingLevel`                    | `2\|3\|4\|5\|6 \| undefined`                                              | `undefined` — wraps headers in `role="heading"` when set    |
+| `ripple`                          | `boolean \| undefined`                                                    | `false`; via `GOG_CONFIG.ripple.enabled`                    |
 
 Model: `openIds: ReadonlySet<string | number>`. Output: `gogToggle: { item, open }`.
 
@@ -1070,6 +1200,10 @@ ARIA wiring, because the browser already handles focus and keys. On anything els
 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.
 
+`gogCollapsibleTrigger` takes a **`ripple`** input of its own (`boolean | undefined`, `false`, via
+`GOG_CONFIG.ripple.enabled`) — the trigger is your element, but the directive owns the ripple so
+you do not have to add `gogRipple` beside it.
+
 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
@@ -1085,6 +1219,7 @@ An open panel is as tall as its content — `--gog-collapsible-max-height` defau
 | `fullWidth`, `ariaLabel` |                                                        | `false`, `''`                                        |
 | `scrollActiveIntoView`   | `boolean`                                              | `true`                                               |
 | `showScrollTrack`        | `boolean \| undefined`                                 | follows `scrollActiveIntoView` (hidden when it's on) |
+| `ripple`                 | `boolean \| undefined`                                 | `false`; via `GOG_CONFIG.ripple.enabled`             |
 
 Model: `activeIndex: number`. Output: `gogTabChange: number`.
 
@@ -1108,6 +1243,94 @@ hidden via `[hidden]` while inactive — preserves scroll/input state).
 </gog-tabs>
 ```
 
+#### `gog-card` + `gogCardHeader` / `gogCardMedia` / `gogCardFooter` / `gogCardLink`
+
+A surface for one self-contained thing — a product tile, a summary, a search result.
+
+| Input           | Type                                                     | Default                                 |
+| --------------- | -------------------------------------------------------- | --------------------------------------- |
+| `variant`       | `GogSurfaceVariant` (`'outlined'\|'elevated'\|'filled'`) | `'outlined'`                            |
+| `size`          | `GogSize`                                                | `'md'` — drives padding and the row gap |
+| `disabled`      | `boolean` (bare attribute works)                         | `false`                                 |
+| `loading`       | `boolean` (bare attribute works)                         | `false`                                 |
+| `skeletonLines` | `number`                                                 | `2` — body lines shown while `loading`  |
+
+No outputs. Slots, all **attribute** directives on your own elements (not `ng-template`):
+`gogCardHeader`, `gogCardMedia`, `gogCardFooter`, `gogCardLink`. Layout order is fixed by the
+component — media, heading, body (the default slot), footer — not by the order you write them.
+
+```html
+<gog-card>
+  <img gogCardMedia [src]="person.photo" alt="" />
+  <h3 gogCardHeader><a gogCardLink [routerLink]="['/people', person.id]">{{ person.name }}</a></h3>
+  <p>{{ person.role }}</p>
+  <div gogCardFooter>
+    <gog-button size="xsm" (gogClick)="shortlist(person)">Shortlist</gog-button>
+  </div>
+</gog-card>
+```
+
+- **`gogCardHeader` names the card.** The card reads that element's `id` (minting one if it has
+  none) and points its own `aria-labelledby` at it, with `role="group"`. A card with no header
+  gets neither — an unnamed group is noise, not structure. The heading level is yours; the visual
+  size comes from `--gog-card-heading-font-size` regardless of it.
+- **There is no `interactive` input, and no `gogClick` output.** A card becomes interactive by
+  _containing_ a `gogCardLink`, which stretches that link's hit area over the whole surface. The
+  link stays yours: `routerLink`, `href`, `target`, middle-click, "open in new tab" and Enter all
+  behave normally, and the focus ring is drawn around the card. `gogCardLink` only applies to
+  `<a>` and `<button>` — on a `<div>` it does nothing, deliberately.
+- **Other controls inside an interactive card still get their own clicks.** A footer button, a
+  checkbox, a second link: each sits above the stretched hit area automatically.
+- Two costs of the pattern, inherent to it: text in the card cannot be selected by dragging, and
+  a second link is reachable by keyboard but not by clicking the surface around it.
+- **`loading`** replaces the content with a title bar plus `skeletonLines` text lines and sets
+  `aria-busy`; **`disabled`** dims the card, sets `aria-disabled`, and takes the card link out of
+  the tab order. Both make the link non-clickable. For a _refresh_ of a card that already has
+  content, project a `gog-spinner-overlay` instead — `loading` is the first-paint treatment.
+- `gogCardMedia` runs full-bleed to the card's edges, and rounds into its top corners when it is
+  the first element in the card.
+
+#### `gog-panel` + `gogPanelHeader` / `gogPanelFooter`
+
+A titled region of a page — a settings section, a dashboard area, a form group.
+
+| Input           | Type                             | Default      |
+| --------------- | -------------------------------- | ------------ |
+| `variant`       | `GogSurfaceVariant`              | `'elevated'` |
+| `size`          | `GogSize`                        | `'lg'`       |
+| `collapsible`   | `boolean` (bare attribute works) | `false`      |
+| `disabled`      | `boolean` (bare attribute works) | `false`      |
+| `loading`       | `boolean` (bare attribute works) | `false`      |
+| `skeletonLines` | `number`                         | `3`          |
+
+Model: `open: boolean` (default `true`, ignored while `collapsible` is off). No outputs beyond
+`openChange`. Slots: `gogPanelHeader`, `gogPanelFooter` — attribute directives on your elements.
+
+```html
+<gog-panel [collapsible]="true" [(open)]="notificationsOpen">
+  <h2 gogPanelHeader>Notifications</h2>
+  <gog-checkbox label="Email digest" [(checked)]="emailDigest" />
+  <div gogPanelFooter><gog-button size="xsm">Save</gog-button></div>
+</gog-panel>
+```
+
+- **It is a landmark.** With a `gogPanelHeader` it renders `role="region"` named by that heading —
+  which is why the panel gets one and `gog-card` gets `role="group"`: a handful of named regions
+  is how a page is navigated, a landmark per card would bury that list.
+- **Collapsing composes `gog-collapsible`**, so the state, the id wiring and the animation are the
+  library's existing ones. The heading stays a heading: the toggle is a separate `<button>` named
+  by it through `aria-labelledby`, with its hit area stretched across the header row so clicking
+  the title works for the pointer. Without a header the toggle falls back to
+  `GOG_CONFIG.labels.togglePanel` (default `'Toggle section'`).
+- **A non-collapsible panel does not clip.** It undoes the collapse geometry it inherits,
+  `overflow` included, so a dropdown or menu opened inside it escapes the panel's box. A
+  _collapsible_ one does clip while animating, exactly like `gog-collapsible` — prefer
+  `[appendToBody]` for an overlay inside one.
+- **`loading` keeps the heading and the footer** and replaces only the body: a page section is
+  titled before its content arrives, and blanking the title would move the layout twice.
+- **The surface is never itself a link** — there is no `gogPanelLink`. Controls live inside a
+  panel, and a region that is a link cannot hold them. Use `gog-card` for that.
+
 #### `gog-paginator`
 
 | Input                           | Type                                             | Default                                            |
@@ -1198,7 +1421,7 @@ rather than a hard split, so those can usually go.
 
 **`stickyHeader` needs `maxHeight`** (both since 21.6.0 for the pairing). A sticky element
 resolves against its nearest scroll container, and the table wraps itself in a `gog-scroll`;
-once that scroller moves on either axis it is a scroll container on *both*, because CSS coerces
+once that scroller moves on either axis it is a scroll container on _both_, because CSS coerces
 `overflow-y: visible` to `auto` beside a scrolling `overflow-x` (and `clip` to `hidden`). So the
 header can only ever stick to something inside the table — and without `maxHeight` that viewport
 is exactly as tall as its content and never scrolls, so there is nothing to stick to.
@@ -1386,6 +1609,10 @@ trigger's measured rect, so a menu inside `gog-scroll`, `gog-table` or any `over
 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.
 
+`gogMenuItem` takes a **`ripple`** input (`boolean | undefined`, `false`, via
+`GOG_CONFIG.ripple.enabled`). The item is your own `<button>`, but the directive owns the ripple,
+so there is no `gogRipple` to add.
+
 Output: `gogClosed` — fires after every close, whatever caused it.
 
 Public methods, for driving it yourself: `open(trigger, 'first' | 'last')`, `close(restoreFocus?)`,
@@ -1463,17 +1690,33 @@ Everything the package currently deprecates, as data:
 ```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' }
+GOG_DEPRECATIONS; // []
 ```
 
 `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.
+**As of 21.7.0 the list is empty on both halves.** Nothing in the TypeScript API is deprecated, and
+the three abbreviated token prefixes that used to fill the token half are gone rather than
+deprecated — see the removal table below. An empty list here means exactly that: nothing to
+migrate away from right now.
+
+## Removed in 21.7.0
+
+**Nothing in this table exists any more.** Three CSS custom-property prefixes, abbreviations of a
+component's own name, are gone — each was honoured only as a fallback the spelled-out token wrapped
+(`--gog-button-x: var(--gog-btn-x, value)`), never declared on its own.
+
+| Removed           | Replacement                   |
+| ----------------- | ----------------------------- |
+| `--gog-btn-*`     | `--gog-button-*`              |
+| `--gog-ms-*`      | `--gog-multiselect-*`         |
+| `--gog-confirm-*` | `--gog-confirmation-dialog-*` |
+
+A consumer's CSS that still sets one of the left-hand names doesn't fail their build — an
+unresolved `var()` just stops matching anything, silently. If a themed surface stopped picking up
+an override after upgrading to 21.7.0, this table is the first thing to check.
 
 ## Removed in 21.5.0
 
@@ -1508,6 +1751,7 @@ Shared enum-like types (`import type { ... } from '@guildofgleks/ui'`):
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `GogSize`                     | `'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'`                                                                            |
 | `GogVariant`                  | `'primary' \| 'secondary' \| 'outline' \| 'ghost'`                                                                  |
+| `GogSurfaceVariant`           | `'outlined' \| 'elevated' \| 'filled'` — `gog-card` and `gog-panel`                                                 |
 | `GogTagVariant`               | `'success' \| 'danger' \| 'warning' \| 'info'`                                                                      |
 | `GogOrientation`              | `'horizontal' \| 'vertical'`                                                                                        |
 | `GogTagShape`                 | `'rounded' \| 'pill'`                                                                                               |