@wildmason/aegis 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -18,6 +18,328 @@ that 404s.
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-10-07
+
+Patch: one fix and one theme colour. Nothing is added, renamed or removed.
+
+### Fixed
+
+- `WmSlider`: the thumb sits on the value after the value and the range change
+  in one render. The native input bound its `value` before its `min`, `max`
+  and `step`, and the browser sanitizes a written value against the bounds the
+  input holds at that moment. A value that rose with `max` was clamped to the
+  old `max`, and the binding was not written again because the value did not
+  change. The thumb and the input's own value, which a screen reader reads as
+  the current value, sat a stop short, while the fill, the readout and
+  `aria-valuetext` named the new value. Scaffold hit it when an effort scale
+  gained a stop: the readout said "ultra" and the thumb sat on "max". The
+  bounds and the step are now bound first.
+
+### Changed
+
+- `wildmason` theme: `--wm-text-muted` is `#949d94`, down from `#c0cac0`. The
+  old value was within 2/255 of `--wm-text-secondary` (`#c2ccc2`), so muted text
+  such as a timestamp read as body text. Every muted label on this theme dims.
+
+## [2.2.0] - 2026-10-02
+
+Minor: new components, variants and inputs, and accessibility fixes. Nothing is
+renamed or removed, so a consumer on `^2.0.0` picks this up on its next install
+and nothing it already names moves. Two fixes change the ARIA that renders, so
+a consumer test that reads it can see a difference: the `<wm-popover>` host no
+longer carries the panel's role, and a `dialog` or `alertdialog` panel now has
+`aria-modal="true"`.
+
+### Added
+
+- `WmTabs` accepts `activeValue` `null` for "no tab selected". Use it when the
+  stage shows something that is not any tab's panel, such as a document opened
+  from a second tablist in the same row. Every tab reports
+  `aria-selected="false"` and none paints as active, and the tablist keeps one
+  tab stop (see Fixed). The input type widens from `string` to
+  `string | null`, so every existing template binding still compiles.
+- `WmTabs` `ariaLabel` and `ariaLabelledby` inputs name the inner
+  `role="tablist"`; `ariaLabelledby` wins when both are set. The tablist had no
+  way to take a name, so two tablists in one row sounded identical to a screen
+  reader. An `aria-label` attribute on the `<wm-tabs>` element still names
+  nothing, because that element has no role.
+- `WmButtonDirective` (`button[wmButton]`, `a[wmButton]`) puts the Aegis
+  button classes on a native element the consumer writes, from the same
+  `variant`, `size` and `iconOnly` inputs as `<wm-button>`. `<wm-button>`
+  renders its own `<button>` inside a host that has no role and cannot take
+  focus, and passes it only `disabled`, `type`, `ariaLabel` and `btnTitle`.
+  So `aria-pressed`, `aria-expanded`, `aria-controls`, `cdkFocusInitial`, an
+  `id`, a popover `trigger`, `[wmTooltip]`, `data-tooltip` and layout classes
+  all stayed on the wrapper. On the directive's element they reach the button
+  with no forwarding list. Both forms compute their classes in one function,
+  so they cannot drift apart. A `<button>` with no `type` gets
+  `type="button"`, the `<wm-button>` default, so moving from the component to
+  the directive does not create a submit button; a written or bound `type`
+  wins. The consumer's own classes, static or bound, are kept. `WmButton` is
+  unchanged.
+- `.wm-btn--dashed`, and `variant="dashed"` on `<wm-button>` and
+  `[wmButton]`: the empty slot, for the place a new item goes at the end of
+  the list it adds to. It is transparent, with a 1px dashed edge and a
+  `--wm-text-secondary` label. On hover it fills with `--wm-bg-sunken`, the
+  edge turns solid and the label moves to `--wm-text-primary`. Focus uses the
+  pulse, as `ghost` does. `ButtonVariant` gains `'dashed'`. Helm hand-rolled
+  this twice (`workflow-chain-add`, `lfs-add-pattern`), and the two copies
+  disagreed on edge token, opacity and padding. At full strength, neither
+  copy's edge token reached 3:1 on every theme and surface: `--wm-border` is
+  1.04:1 on warm-light, and `--wm-border-subtle` is 1.00:1 on arctic-night.
+  Their 80% and 78% mixes toward transparent fall below 3:1 on all 48 theme
+  and surface pairs. The shipped edge mixes `--wm-border-input` 70/30 toward
+  `--wm-text-primary`, which clears 3:1 everywhere (worst 3.34:1, wildmason
+  on `--wm-bg-float`).
+- `scripts/check-dashed-contrast.mjs` (`npm run check:dashed-contrast`, part
+  of `build`) reads the variant's rules out of inputs.css and holds them on
+  every theme and on `--wm-bg-base`, `-raised`, `-float` and `-sunken`: a
+  4.5:1 label at rest and on hover, APCA Lc 60 on hover, and a 3:1 edge at
+  rest and on hover, against the fill as well as the surface.
+- `scripts/check-focus-pulse.mjs` (`npm run check:focus-pulse`, part of
+  `build`) fails when a selector animates `wm-focus-pulse` and has no
+  reduced-motion rule in the same file that stops the animation and sets a
+  static `box-shadow` ring.
+- `WmToggleGroup` and `WmToggleGroupItem` (`<wm-toggle-group>`,
+  `<wm-toggle-group-item>`): a single choice among a few visible options,
+  drawn as joined `segmented` items in one sunken track or as separate
+  `chip`s that wrap, in `size` `sm` (24px) or `md` (28px). Aegis had no
+  single-select control of this kind, so each consumer hand-rolled one: Helm
+  has six, each a `role="group"` row of `aria-pressed` buttons in which every
+  button is its own Tab stop, the arrow keys do nothing, and nothing tells a
+  screen reader that the options exclude each other. The component is the
+  WAI-ARIA radio group: the group element is `role="radiogroup"`, each item
+  element is `role="radio"` with `aria-checked`, the group keeps one Tab stop
+  (the focused item while focus is inside, otherwise the checked item,
+  otherwise the first item that is not disabled), and the arrow keys move
+  focus and check, wrapping and stepping over disabled items, with Left and
+  Right mirrored in a right-to-left layout. `Home` and `End` go to the ends,
+  `Space` checks, and `Enter` does not. `(valueChange)` fires once per user
+  choice and never with `null`, so `[(value)]` type-checks against a signal
+  that cannot hold `null`. Values compare by `Object.is` and keep their type.
+  It is a ControlValueAccessor and marks the control touched when focus
+  leaves the group. The items are the radios, so `aria-label` on an
+  icon-only item, `data-testid` and `[wmTooltip]` land on the control. New
+  exported types: `WmToggleGroupAppearance`, `WmToggleGroupSize`.
+- `scripts/check-toggle-group-contrast.mjs` (`npm run
+  check:toggle-group-contrast`, part of `build`) reads the toggle group's
+  rules out of its stylesheet and holds both appearances on every theme and
+  on `--wm-bg-base`, `-raised`, `-float` and `-sunken`: 4.5:1 labels
+  unchecked, hovered and checked, APCA Lc 60 on hover, and a 3:1 checked edge
+  and focus ring. It measured out the first choices: a bare
+  `--wm-color-accent` fill is 2.91:1 against `--wm-bg-float` on
+  posh-sandalwood, so the checked item carries a
+  `--wm-color-accent-readable` edge, and primary text on `--wm-bg-hover` is
+  4.41:1 on vampires-kiss, so segmented hover fills with `--wm-bg-float`.
+
+- `.wm-hatch` and `.wm-hatch--warning` in inputs.css: the stand-in texture,
+  for an elided node that stands for items the view does not draw and for a
+  value that nobody has filled in. The class paints 135deg bands, 4px of tone
+  then 4px clear, as `background-image` over the element's own fill. The
+  neutral tone is `--wm-text-primary` at 10% and the warning tone is
+  `--wm-color-warning` at 14%, both mixed toward `transparent`;
+  `--wm-hatch-tone` replaces the band colour. Aegis had no texture, so two
+  consumers hand-rolled the same geometry: Helm's Stacks overflow node
+  (`+N`) and Mortar's unset path variable. Helm's copy built its band from
+  `--wm-bg-hover` mixed into `--wm-bg-raised`, which measures 1.08:1 on
+  thistle-mocha, close to invisible, and 2.24:1 on vampires-kiss. Each
+  shipped share is the smallest that shows on every theme and surface,
+  because every point above it costs the text on top contrast.
+- `scripts/check-hatch-contrast.mjs` (`npm run check:hatch-contrast`, part of
+  `build`) reads the hatch rules out of inputs.css and holds both tones on
+  every theme and on `--wm-bg-base`, `-raised`, `-float` and `-sunken`: a band
+  of at least 1.15:1 against the surface, `--wm-text-primary` on the band at
+  4.5:1 and APCA Lc 60, every token the tone reads defined by the theme, the
+  135deg 4px/8px geometry, and a translucent tone. One pair has no APCA bar:
+  on solarized-precision's `--wm-bg-float` the bare text is Lc 65.4, and no
+  share of either tone gives a visible band with Lc 60 text (the neutral band
+  leaves Lc 57.5 and 5.87:1). The guard proves that on every run and fails if
+  a theme change makes the pair reachable.
+
+### Fixed
+
+- `.wm-btn--flat` and the `.wm-checkbox` class kept the animated focus pulse
+  under `prefers-reduced-motion: reduce`. The reduced-motion rule in
+  inputs.css lists each pulsing selector by hand, and these two were missing,
+  although the Accessibility page said every pulse becomes a static ring. Both
+  now get the static 3px ring. `check:focus-pulse` found them.
+
+- `WmTabs` no longer drops out of the page's Tab order when no tab is
+  selected. It gave the tab stop to the selected tab only, so an `activeValue`
+  that matched no tab left every tab at `tabindex="-1"`, and a consumer could
+  not repair it because the binding re-applied `-1` on each change detection.
+  The stop is now the focused tab while focus is inside, otherwise the
+  selected tab, otherwise the first tab that is not `unavailable` (the first
+  tab when all are). Helm's Navigator hid the selected pill in CSS to avoid
+  this, which left `aria-selected="true"` on a tool that did not look
+  selected.
+- `WmTabs` tracks the focused tab by value instead of by index. A tab added or
+  removed before the focused one shifted the index, so the stop moved to a
+  different tab or past the end of the list, where no tab had
+  `tabindex="0"`.
+- `WmTabs` returns its tab stop to the selected tab when focus moves to a
+  second `<wm-tabs>`. Its blur check asked whether focus was inside any
+  `.wm-tabs` element, so focus in the other tablist counted as inside this
+  one and left the stop on the tab last focused.
+
+- `WmPopover` sets `aria-modal="true"` on a `role="dialog"` or
+  `role="alertdialog"` panel. The panel always opens over a click-catching
+  backdrop and traps focus, so it is modal, and without the attribute a screen
+  reader kept reading the page behind it. Other roles get no `aria-modal`,
+  since the attribute is defined for those two only. A panel with
+  `[trapFocusAutoCapture]="false"` gets none either: focus stays on the trigger
+  outside the panel, and `aria-modal` would hide that focused trigger. Mortar's
+  combobox is that case (default `dialog` role, auto-capture off), and keeps
+  its current semantics. A modal panel whose content has nothing tabbable
+  (text only, or a lone disabled button) takes focus itself, through
+  `tabindex="-1"`, and Tab and Shift+Tab keep focus on it. The focus trap
+  finds nothing to focus there, so focus used to stay on the trigger, which
+  `aria-modal` hides, and a second Tab walked out to the page behind the
+  backdrop. A non-modal panel gets no `tabindex`, so a click on it cannot pull
+  focus off a typeahead input.
+- The `<wm-popover>` host no longer carries the panel's role. A consumer
+  writes `role="dialog"` as a plain attribute, and Angular copies a static
+  attribute onto the host as well as into the input, so each popover written
+  that way wrapped its trigger in a second, unnamed `dialog` — or in a `menu`
+  that owned no `menuitem`. The role now lives on the panel alone.
+- `WmModal` lays out its own backdrop. It used Tailwind utilities for this
+  (`fixed inset-0 flex items-center justify-center z-50`, and `items-start
+  pt-20` for `align="top"`), which Aegis does not ship. A consumer's Tailwind
+  build emits only the classes its own sources name, so the backdrop was fixed
+  and centred only where a consumer happened to use the same utilities; in an
+  app without Tailwind, the docs app included, it rendered in the page flow.
+  Helm's sources name every centred-layout utility but not `pt-20`, so
+  `align="top"` never got its offset there; Helm does not use `align="top"`.
+  The rendered values are unchanged: fixed, full viewport, z-index 50, and
+  `5rem` from the top for `align="top"`. The inline
+  `background: var(--wm-modal-backdrop)` stays, because consumers detect an
+  open modal by `[style*="--wm-modal-backdrop"]`.
+
+### Documentation
+
+- The `popover` guide page, which the MCP serves, documented the docs app's
+  private copy of the popover rather than the shipped `WmPopover`: a required
+  `data-popover-trigger`, two-way `[(isOpen)]`, `align="center"` and CSS-string
+  widths, none of which the shipped component has. The page now runs its demos
+  on `WmPopover`, documents `(closed)` and `trapFocusAutoCapture`, and adds an
+  Accessibility section. The private copy is deleted.
+- The `popover` page, DESIGN_LANGUAGE.md §7.13 and `WmPopover`'s doc comment
+  now say what a consumer following the old page got wrong. The `trigger`
+  attribute is the only thing the component reads; `data-popover-trigger` is
+  not. The component writes `aria-haspopup`, `aria-expanded` and
+  `aria-controls` to the trigger on every change to `isOpen` or `hasPopup`, so
+  the template does not bind them, and a static `aria-haspopup` is replaced by
+  `hasPopup`. A `<wm-button>` cannot be the trigger: the attribute stays on
+  its host, which then wraps a second button role around the real `<button>`,
+  so use a native `<button trigger>` with the `wm-btn` classes. The
+  Accessibility page's trigger row now lists `aria-controls` too. Helm carries
+  nine dead `data-popover-trigger` attributes, eight hand-written
+  `aria-expanded` bindings and two `<wm-button trigger>` sites from the old
+  page; Mortar carries five dead attributes and one `<mortar-button trigger>`.
+- The `modal` guide page (the Dialog topic) never mentioned
+  `--wm-dialog-width`, so it read as though `size="lg"` (640px) were the widest
+  `wm-dialog` can go. The property overrides every preset, and Helm sets it on
+  ten dialogs, up to 960px. The page now documents it, with a demo, and ran its
+  demos on a private copy of the dialog that ignored it; the page now runs on
+  the shipped `WmDialog` and `WmButton`, and the dialog copy is deleted. The
+  page also documents `wm-modal` for the first time: when to choose it over
+  `wm-dialog`, its inputs, what it supplies (backdrop, dismissal, focus trap)
+  and what the consumer supplies (`role`, `aria-modal`, the accessible name, a
+  close control), with a working demo. `WmDialog`'s own doc comment wrongly
+  credited the browser with returning focus on close; `cdkTrapFocusAutoCapture`
+  does it.
+- DESIGN_LANGUAGE.md lists `<wm-modal>` among the shipped components (§20 says
+  anything unlisted is not shipped), §8.6 names both components and
+  `--wm-dialog-width`, and §15.2 says the shipped overlays trap focus
+  themselves instead of telling consumers to implement a trap.
+- The `tabs` guide page, which the MCP serves, ran its demos on a private
+  copy of the tabs in the docs app; it now runs on the shipped `WmTabs`, and
+  the copy is deleted. The page adds a "No Tab Selected" section with a
+  working demo of two named tablists that hand the stage to each other, names
+  every demo tablist, and documents `ariaLabel`, `ariaLabelledby`, the tab
+  stop rule, the `wm-tab-{value}`/`wm-panel-{value}` ids and `WmTab`'s
+  `unavailable`, `unavailableReason` and `separatorBefore` inputs, which its
+  API table left out. Its request and response demos both used the values
+  `body` and `headers`, so the page rendered `wm-tab-body` and
+  `wm-tab-headers` twice; the response demo now uses its own values.
+- DESIGN_LANGUAGE.md §10 documents `<wm-tabs>` for the first time (§10.0).
+  The section taught only hand-rolled switchers, with no tablist semantics.
+- The Quick Reference component table listed an `[options]` input on
+  `<wm-tabs>`, which does not exist, and gave `<wm-popover>` the export name
+  `Popover` and a two-way `[(isOpen)]`. The rows now name `WmTabs`'s real
+  inputs, and `WmPopover` with `[isOpen]` and `(closed)`.
+- The `button` guide page, which the MCP serves, said `<wm-button>` and the
+  `.wm-btn` classes "are interchangeable" and "produce identical output".
+  They are not: attributes written on `<wm-button>` stay on its host. Helm
+  met this twice on 2026-08-09 (an `aria-pressed` that could not reach the
+  button, and a `cdkFocusInitial` that CDK reported as "not focusable") and
+  fell back to writing the classes by hand. The page now opens with a
+  "Component, Directive or Class"
+  section: use `<wm-button>` by default, `[wmButton]` whenever something has
+  to land on the focusable element, and the bare classes only outside
+  Angular, with a table of what does not reach the inner button and a working
+  `aria-pressed` toggle. `data-tooltip` is in that table: it opens on
+  `:focus-visible`, which the wrapper never matches, so an icon-only
+  `<wm-button>` never showed its tooltip to a keyboard user. DESIGN_LANGUAGE.md
+  gains the same rule as §6.5, and `WmButton` gains a doc comment that says
+  what it forwards.
+- The `button` page ran on a private copy of `WmButton` in the docs app that
+  had drifted from the library (no `xs`, `iconOnly`, `ariaLabel` or
+  `btnTitle`). The page and the Composition, Form Patterns and Toast pages now
+  use the library component, and the copy is deleted. The page documents the
+  `xs` size, `iconOnly`, `ariaLabel` and `btnTitle`, which its API table left
+  out. Its own stylesheet set `.btn-icon-only` to 36 × 36px, so every
+  icon-only demo rendered at the default size whatever its size class, against
+  the 28px and 40px its own table promised; that rule is removed.
+- DESIGN_LANGUAGE.md §8.4 (toolbar button) and §12.3 (notification dot) wrote
+  `class="btn btn-sm btn-ghost"`, which Aegis does not ship; the docs check
+  cannot see it because the names have no `wm-` prefix. Both now use
+  `[wmButton]`, and §8.4 tells a toolbar toggle to expose its state with
+  `aria-pressed` or `aria-expanded` rather than colour alone. §20 said
+  anything it did not list is not shipped, and it did not list `<wm-button>`,
+  `<wm-checkbox>`, `<wm-toggle>`, `<wm-ghost-field>` or `<wm-rich-tooltip>`;
+  it lists them now, with `[wmButton]`.
+- The `popover` page, DESIGN_LANGUAGE.md §7.13 and `WmPopover`'s doc comment
+  now point an Aegis-styled trigger at `<button wmButton trigger>`, and the
+  page's demo triggers use it. The Quick Reference and Accessibility pages
+  list `[wmButton]` beside `<wm-button>`.
+- The `button` page gains an Empty Slot section: when to use `dashed`, a demo
+  of both Helm shapes (a full-width slot and one at its own width), what each
+  state paints, and why the edge is mixed. It says that width is the
+  consumer's layout, so a full-width slot is `[wmButton]` plus a width class.
+  The Variants demo, table and both API tables list `dashed`. The Quick
+  Reference page lists `.wm-btn--flat`, `.wm-btn--dashed` and `.wm-btn--xs`;
+  it listed none of the three before. The Accessibility page's pulse card
+  lists every control that pulses. DESIGN_LANGUAGE.md §6.3 and §15.1 and the
+  inputs.css button header are updated.
+- A `toggle-group` guide page (served by the MCP) documents
+  `<wm-toggle-group>` with working demos of both appearances, `size="sm"`,
+  icon-only items, a reactive form with numeric values, disabled items and
+  groups, the keyboard and ARIA contract, and how to replace a hand-rolled
+  `aria-pressed` row. DESIGN_LANGUAGE.md gains §10.4. §10's opening splits
+  tabs from toggle groups by what the control does (choose a panel, or set a
+  value), and §7.5, §10.2, §10.3 and §12.5 point at the component. §15.1
+  adds the outline focus treatment its items use, and §20 lists it.
+- The Checkbox, Combobox, Select and Toggle pages sent exclusive choices to
+  "radio buttons", which Aegis does not ship, and the Slider page and
+  `WmSlider`'s doc comment sent them to "a pill tab group", which is for
+  switching panels. All now name `<wm-toggle-group>`. The Tabs page adds a
+  Don't: pill tabs do not set a value. The Quick Reference and Accessibility
+  pages list the component, its keys, its roles and its reduced-motion rule.
+- DESIGN_LANGUAGE.md gains §2.8, the hatch: what it marks and what it must
+  not, the geometry, why the fill must be `background-color` (the
+  `background` shorthand resets `background-image`, and a component
+  stylesheet outranks `.wm-hatch`), and the rules. Text on a hatch is
+  `--wm-text-primary`: under the neutral band `--wm-text-secondary` falls to
+  3.70:1 on vampires-kiss. The hatch never carries the meaning alone, because
+  forced-colors mode computes a gradient `background-image` and `box-shadow`
+  to `none`; a border survives. §6.3 and §18.3 point at it. The `color` guide
+  page gains a Hatch section with demos on all four surfaces, and Quick
+  Reference gains rows for both classes.
+- DESIGN_LANGUAGE.md §2.7 said Aegis ships 10 themes and left `sage-linen`
+  and `wildmason` out of its table; it ships 12. §20 now lists the
+  `.wm-shadow` utilities, which it left out, and the hatch classes.
+
 ## [2.1.0] - 2026-09-20
 
 Minor: one new component and its inputs. Nothing existing changes, so a consumer
@@ -461,7 +783,9 @@ a `^1.x` range does not pick this release up by accident.
 Releases before 1.8.0 are in `git log`. See also `wiki/products/Aegis - Health.md`
 for the decisions behind these changes, including the ones decided against.
 
-[Unreleased]: https://github.com/wildmason/aegis/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/wildmason/aegis/compare/v2.2.1...HEAD
+[2.2.1]: https://github.com/wildmason/aegis/releases/tag/v2.2.1
+[2.2.0]: https://github.com/wildmason/aegis/releases/tag/v2.2.0
 [2.1.0]: https://github.com/wildmason/aegis/releases/tag/v2.1.0
 [2.0.0]: https://github.com/wildmason/aegis/releases/tag/v2.0.0
 [1.18.0]: https://github.com/wildmason/aegis/releases/tag/v1.18.0