@guildofgleks/ui 21.7.2 → 21.9.0

package/AGENTS.md

@@ -5,7 +5,8 @@ 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.7.0`**. 21.7.0 removed the three
+Everything below reflects the library's actual source as of **`21.9.0`** (in progress — the
+released version is 21.8.0; see `CHANGELOG.md` for what 21.9.0 adds). 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
@@ -180,13 +181,30 @@ Full model is in `README.md`'s Theming section; short version:
   `--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.
+- **The type scale is `--gog-text-xs | sm | md | lg | slg | xl | 2xl | 3xl`.** `slg` (1.25rem)
+  fills the gap between `lg` and `xl` and is named for the control size that needed it. Every
+  component font size that is one of these reads the token, so retuning the scale retunes the
+  library; the handful that do not are off-scale on purpose (an 11px chip, the accordion
+  chevron's px ramp, the toggle's own micro-ramp).
+
+- **Weight is `--gog-font-weight-medium | semibold | bold | heavy`** (500/600/700/900). Every
+  component weight reads one of them, so a lighter or heavier house style is four declarations.
+
+- **`--gog-z-base` moves the whole stacking order.** Badge `+1`, toast `+100`, dropdowns, dialogs
+  and menus `+300`, tooltip `+400`, the blocking spinner overlay `+8000`. Set the base to lift
+  the library above your own chrome without disturbing its internal order.
+
 - **`--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.
+  still work. Icon offsets, dropdown panel gaps, error-line offsets and the badge's overhang
+  follow density; the glyph box, the focus-ring offset, the float-label reserve and the
+  scrollbar/toggle thumb insets deliberately do not — those are legibility or geometry fitted to
+  a fixed-width track, not spacing. Since 21.9.0 the split is enforced rather than trusted:
+  `check-tokens` rule H fails the build on a length token that restates a scale step's value as
+  a bare literal, with the three exceptions named in the script.
 - **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-*`
   were removed in 21.7.0 — if you're reading a codebase or an example that still uses one, rename
@@ -264,13 +282,14 @@ parent's config**, one level deep per key — it does not replace it.
 
 | Key            | Fields                                                                  | Applies to                                                                                                                                                                                                                                                                                                                                                                                                   |
 | -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `control`      | `size`, `errorDisplay`, `clearable`                                     | `size`: button, inputfield, textarea, select, multiselect, checkbox, radio-group, button-toggle-group, datepicker. `errorDisplay`: inputfield, textarea, select, multiselect, autocomplete, radio-group, slider, datepicker. `clearable`: inputfield, textarea, select, multiselect, autocomplete, datepicker. Not table/accordion/paginator (density, not form size), not spinner/skeleton/tag/chip/toggle. |
+| `control`      | `size`, `errorDisplay`, `clearable`                                     | `size`: button, `[gogButton]`, button-toggle-group, checkbox, toggle, radio-group, inputfield, textarea, select, multiselect, autocomplete, datepicker. `errorDisplay`: inputfield, textarea, select, multiselect, autocomplete, datepicker, radio-group, slider. `clearable`: inputfield, textarea, select, multiselect, autocomplete, datepicker. Not table/accordion/paginator (density, not form size), not spinner/skeleton/tag/chip.                                                          |
 | `dropdown`     | `appendToBody`, `direction`, `filter`, `filterPosition`                 | `gog-select`, `gog-multiselect`. `gog-datepicker`/`gog-autocomplete` honour `appendToBody`/`direction` too (autocomplete has no `filter` box — it filters via the trigger's own text).                                                                                                                                                                                                                       |
 | `floatLabel`   | `variant`, `showPlaceholder`                                            | inputfield, textarea, select, multiselect, autocomplete, datepicker.                                                                                                                                                                                                                                                                                                                                         |
 | `datepicker`   | `locale`, `firstDayOfWeek`, `format`                                    | `gog-datepicker`, `gog-calendar`.                                                                                                                                                                                                                                                                                                                                                                            |
 | `autocomplete` | `searchDebounce`, `minLength`, `openOnFocus`                            | `gog-autocomplete`.                                                                                                                                                                                                                                                                                                                                                                                          |
 | `tooltip`      | `position`, `showDelay`, `hideDelay`                                    | the `gogTooltip` directive.                                                                                                                                                                                                                                                                                                                                                                                  |
-| `scroll`       | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`      | `gog-scroll` (and every component that uses one internally).                                                                                                                                                                                                                                                                                                                                                 |
+| `spinner`      | `component`, `variant`                                                  | every spinner the library draws — `gog-spinner`, `gog-spinner-overlay`, and the ones inside `gog-button` and `gog-autocomplete`, which have no input of their own. `component` takes **your** component and renders it in place of the built-in look. |
+| `scroll`       | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`, `horizontalWheel` | `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`.                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -467,6 +486,7 @@ Every component below is exported from `@guildofgleks/ui`'s root — `import { X
 | Input       | Type                              | Default     | Notes                                                 |
 | ----------- | --------------------------------- | ----------- | ----------------------------------------------------- |
 | `variant`   | `GogVariant`                      | `'primary'` |                                                       |
+| `severity`  | `GogSeverity`                     | `'accent'`  | what the action means; orthogonal to `variant` — see below |
 | `size`      | `GogSize \| undefined`            | `'md'`      | via `GOG_CONFIG.control.size`                         |
 | `disabled`  | `boolean`                         | `false`     |                                                       |
 | `fullWidth` | `boolean`                         | `false`     |                                                       |
@@ -474,10 +494,80 @@ 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**        |
+| `ariaPressed` | `boolean \| 'mixed' \| null`    | `null`      | toggle button; `false` renders `aria-pressed="false"` |
+| `ariaExpanded` | `boolean \| null`              | `null`      | disclosure / popup trigger                            |
+| `ariaControls` | `string \| null`               | `null`      | id of the controlled element; pairs with `ariaExpanded` |
+| `ariaHasPopup` | `GogAriaHasPopup \| null`      | `null`      | `boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'` |
 | `ripple`    | `boolean \| undefined`            | `false`     | press ripple; via `GOG_CONFIG.ripple.enabled`         |
 
 Outputs: `gogClick: MouseEvent`.
 
+**`severity` says what the action means; `variant` says how loudly it is drawn** (21.9.0). The
+two are orthogonal, so this is not a fifth variant — it re-points the colours all four are built
+from, and every combination is real: `variant="ghost" severity="danger"` is a quiet delete,
+`variant="primary" severity="danger"` a loud one. `'accent'` is the default and the absence of a
+claim, so nothing has to opt out of a severity it does not have. `GogSeverity` is shared with
+`gog-progressbar`, whose `GogProgressbarVariant` is now an alias of it.
+
+```html
+<gog-button severity="danger" (gogClick)="deleteAccount()">Delete account</gog-button>
+<gog-button variant="outline" severity="warning">Discard draft</gog-button>
+<a gogButton severity="success" routerLink="/done">Finish</a>
+```
+
+Two colour rules are worth knowing before you override anything. A **filled** severity button's
+label is `--gog-<status>-text-color`, which each theme states for its own hue — `material` and
+`primeng` put near-black on their bright ones, the rest white — and hover and press deepen the
+fill *away* from that label (`--gog-<status>-shade`), so a state always makes the label easier to
+read rather than harder. A **transparent** one's label is `--gog-button-<status>-ink`: the status
+hue mixed halfway toward the page's ink, because the raw hue is legible body text in only five of
+the eleven shipped themes. Override `--gog-button-<status>-ink` if your own theme wants more
+colour there, and check it: all four severities across all four variants and all their states are
+gated by `npm run check:contrast`.
+
+**Every ARIA attribute this button needs has an input, and a raw attribute is not a
+substitute.** `<gog-button [attr.aria-pressed]="on()">` compiles, throws nothing, and does
+nothing: the attribute lands on the `<gog-button>` custom element, which has no role, while the
+real `<button>` inside stays unmarked. The failure is invisible — the control looks right and is
+simply not a toggle to a screen reader. Use `[ariaPressed]`, `[ariaExpanded]`, `[ariaControls]`,
+`[ariaHasPopup]` and `ariaLabel`.
+
+`false` is not the same as unset. `null` omits the attribute; `false` renders
+`aria-pressed="false"` / `aria-expanded="false"`, which is what an off toggle or a closed
+disclosure has to say — a button with no `aria-pressed` at all is not a toggle button.
+
+**A toggle button now looks toggled** (21.9.0). `aria-pressed="true"` (or `"mixed"`) draws an
+inset ring — `--gog-button-<variant>-toggled-shadow`, overridable per instance with
+`--gog-button-toggled-shadow`. A ring rather than a fill because hover and press already own the
+background: the state has to survive both, and until 21.9.0 it did not exist at all, so a button
+could announce itself as on to a screen reader and look identical to an off one. `[gogButton]`
+gets the same look from the attribute you write on your own element.
+
+**`[gogButton]` needs none of these inputs.** It styles an element you own, so write the ARIA
+attributes on your own `<button>`/`<a>` directly. Same for `[gogMenuTrigger]`, which sets
+`aria-haspopup`/`aria-expanded`/`aria-controls` on its host — put it on your own `<button
+gogButton>`, as its own example shows, not on a `<gog-button>`.
+
+```html
+<gog-button [ariaPressed]="mirrored()" (gogClick)="toggleMirror()">Mirror</gog-button>
+
+<gog-button [ariaExpanded]="open()" ariaControls="filters" ariaHasPopup="dialog"
+            (gogClick)="open.set(!open())">Filters</gog-button>
+```
+
+**The press is a colour, not only a movement.** `:active` deepens the button's background (and
+the label where the fill demands it) as well as scaling it by `--gog-button-active-scale`. Under
+`prefers-reduced-motion: reduce` the scale is dropped and the colour stays, so the press is still
+visible to a reader who has switched animations off — before 21.9.0 that reader got no feedback at
+all, since the ripple is off by default and is itself suppressed under reduced motion. Override
+per instance with `--gog-button-press-bg` / `--gog-button-press-color`, or per theme with
+`--gog-button-<variant>-active-bg`.
+
+Every other pressable surface in the library does the same thing since 21.9.0 — menu items,
+chips, tab and accordion headers, button-toggle options and the three dropdowns' option rows —
+each through its own `--gog-<block>-press-bg`. `gogCollapsibleTrigger` is the exception: the
+library paints nothing on that element in any state, because it is yours.
+
 **`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.
 
@@ -707,12 +797,12 @@ icon.
 An on/off switch (`role="switch"`) — semantically different from a checkbox ("is this setting
 on", not "is this one of the things you selected").
 
-| Input                   | Type                   | Default |
-| ----------------------- | ---------------------- | ------- |
-| `label`, `ariaLabel`    | `string`               | `''`    |
-| `size`                  | `GogSize \| undefined` | `'md'`  |
-| `disabled`, `fullWidth` | `boolean`              | `false` |
-| `labelPosition`         | `'start' \| 'end'`     | `'end'` |
+| Input                   | Type                   | Default | Notes                                 |
+| ----------------------- | ---------------------- | ------- | ------------------------------------- |
+| `label`, `ariaLabel`    | `string`               | `''`    |                                       |
+| `size`                  | `GogSize \| undefined` | `'md'`  | via `GOG_CONFIG.control.size`         |
+| `disabled`, `fullWidth` | `boolean`              | `false` |                                       |
+| `labelPosition`         | `'start' \| 'end'`     | `'end'` |                                       |
 | `onLabel`, `offLabel`   | `string`               | `''`    | text rendered inside the track itself |
 
 Model: `checked: boolean`. CVA: yes.
@@ -928,6 +1018,7 @@ the element stays yours and the directive only gives it the look.
 | Input       | Type                     | Default                                  |
 | ----------- | ------------------------ | ---------------------------------------- |
 | `variant`   | `GogVariant`             | `'primary'`                              |
+| `severity`  | `GogSeverity`            | `'accent'`; same as `gog-button`         |
 | `size`      | `GogSize \| undefined`   | `'md'`; via `GOG_CONFIG.control.size`    |
 | `fullWidth` | `boolean` (bare attr ok) | `false`                                  |
 | `ripple`    | `boolean \| undefined`   | `false`; via `GOG_CONFIG.ripple.enabled` |
@@ -976,6 +1067,7 @@ are impossible by design.
 | `size`                         | `GogSize`                           | `'md'`                                   |
 | `shape`                        | `GogTagShape` (`'rounded'\|'pill'`) | `'rounded'`                              |
 | `disabled`, `clickable`        | `boolean`                           | `false`, `true`                          |
+| `selected`                     | `boolean \| null` (two-way)         | `null` — see below                       |
 | `removable`                    | `boolean`                           | `false`                                  |
 | `fullWidth`                    | `boolean`                           | `false`                                  |
 | `ariaLabel`, `removeAriaLabel` | `string`                            | `''`, `'Remove chip'`                    |
@@ -991,6 +1083,29 @@ Outputs: `gogClick: MouseEvent | KeyboardEvent`, `gogRemove: void`.
 >
 ```
 
+**`selected` makes it a filter chip** (21.9.0) — a chip you toggle on and off rather than press.
+It is tri-state, and `null` is the default so nothing about an existing chip changes: no
+`aria-pressed`, no selected look, activation only emits `gogClick`. Set it to `false` and the chip
+is a toggle that is off (`aria-pressed="false"` — a chip with no `aria-pressed` at all is not a
+toggle to a screen reader, so "off" has to be stated); `true` and it is on, which draws an inset
+ring from `--gog-chip-selected-shadow`. A ring rather than a fill because `:hover` and `:active`
+already own the chip's background and the selection has to survive both.
+
+It is a two-way `model`, so the chip flips it on click, Enter and Space — a row of filters needs
+no click handler:
+
+```html
+@for (f of filters; track f.label) {
+<gog-chip [(selected)]="f.on">{{ f.label }}</gog-chip>
+}
+```
+
+`gogClick` still fires, **after** the flip, so a handler reading `selected()` sees the new value.
+Drive the state from that handler instead and you want a one-way `[selected]`, or the two writes
+cancel out. A `disabled` chip keeps the ring but drops `aria-pressed`, which needs the
+`role="button"` a disabled chip does not carry — "selected, and currently unavailable" is a real
+state and hiding it would leave it announced and invisible.
+
 #### `gog-tag`
 
 | Input       | Type                  | Default     |
@@ -1020,6 +1135,19 @@ Slot: `<ng-template gogTagIcon>` for custom icon markup.
 `variant="custom"` renders your own projected markup, still inheriting the size wrapper and
 `--gog-spinner-color` theming.
 
+**To replace the spinner everywhere at once, pass a component to `GOG_CONFIG`** — including the
+two places you cannot reach with an input, `gog-button`'s and `gog-autocomplete`'s loading
+states:
+
+```ts
+provideGogConfig({ spinner: { component: HouseLoaderComponent } });
+```
+
+It renders inside the same size wrapper as the built-ins, so it keeps the sizing, the overlay
+behaviour, `role="status"` and the accessible name — only the visual is yours. An instance's own
+`variant` still wins over it, so `<gog-spinner variant="ring">` is a ring in an app that has set
+a component: a default does not overrule something asked for explicitly.
+
 ```html
 <gog-spinner-overlay [loading]="isLoading()">
   <app-content-that-loads />
@@ -1560,6 +1688,21 @@ region — the library's official recommendation over a raw `overflow-x`/`overfl
 | `ariaLabel`          | `string`                                                                 | `''`                                                                                    |
 | `overscrollBehavior` | `GogScrollOverscrollBehavior \| undefined` (`'auto'\|'contain'\|'none'`) | `'auto'`; via `GOG_CONFIG.scroll.overscrollBehavior`                                    |
 | `showTrack`          | `boolean \| undefined`                                                   | `true`; via `GOG_CONFIG.scroll.showTrack`                                               |
+| `horizontalWheel`    | `boolean \| undefined`                                                   | `false`; via `GOG_CONFIG.scroll.horizontalWheel`                                        |
+
+**`horizontalWheel` turns a vertical wheel into horizontal scrolling** (21.9.0), for the case a
+consumer hits first: hover a horizontal-only row, turn the wheel, and the *page* moves. That is
+the browser's own behaviour and the component deliberately did nothing about it until now.
+
+It is off by default because it changes what an existing instance does with a gesture it
+currently passes on; `provideGogConfig({ scroll: { horizontalWheel: true } })` turns it on
+app-wide. It only acts when the viewport cannot scroll vertically (checked against live
+geometry, so `axis="both"` scrolls down while there is down to go), the event carries no
+horizontal delta of its own (a trackpad swipe and `Shift`+wheel already work), `ctrlKey` is
+clear (pinch-zoom), and there is room left in the direction of the turn. **That last condition is
+the point:** at the content's end the event is left alone and the page picks it up, so the wheel
+never goes dead over a scrolled-to-the-end region. `overscrollBehavior: 'contain'` still
+contains — that boundary is the browser's and this never reaches past it.
 
 Outputs: `gogScroll: GogScrollMetrics`, `gogReachStart`/`gogReachEnd: 'vertical'|'horizontal'`.
 Methods (via template ref): `scrollTo(options)`, `scrollToTop()`, `scrollToBottom()`,
@@ -1752,6 +1895,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`                                                 |
+| `GogAriaHasPopup`             | `boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'` — `gog-button`'s `ariaHasPopup`                    |
 | `GogTagVariant`               | `'success' \| 'danger' \| 'warning' \| 'info'`                                                                      |
 | `GogOrientation`              | `'horizontal' \| 'vertical'`                                                                                        |
 | `GogTagShape`                 | `'rounded' \| 'pill'`                                                                                               |