@wildmason/aegis 2.1.0 → 2.2.0

package/dist/types/wildmason-aegis.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { ElementRef, AfterViewInit, TemplateRef, OnDestroy } from '@angular/core';
+import { ElementRef, AfterViewInit, TemplateRef, Signal, OnDestroy } from '@angular/core';
 import { ScrollStrategy, OverlayRef, ConnectedPosition } from '@angular/cdk/overlay';
 import { ControlValueAccessor } from '@angular/forms';
 import * as rxjs from 'rxjs';
@@ -9,7 +9,16 @@ import * as rxjs from 'rxjs';
  *
  * Owns the fixed backdrop, centering, keyboard/pointer dismissal AND the focus trap,
  * so individual modal components don't need to repeat this logic or add their own
- * HostListeners.
+ * HostListeners. The consumer supplies the whole panel: its surface, size, header
+ * and close control.
+ *
+ * ## wm-modal or wm-dialog
+ *
+ * Reach for `wm-dialog` first. It is a complete dialog — header, title wired to
+ * `aria-labelledby`, close button, padded scrolling body — and it is not limited to
+ * its `size` presets: `--wm-dialog-width` sets any width (Helm uses up to 960px).
+ * Use `wm-modal` when that chrome is wrong for the surface: a two-pane browser, a
+ * command palette, a panel with its own toolbar or its own scroll regions.
  *
  * ## Focus is trapped here, and it has to be
  *
@@ -28,8 +37,9 @@ import * as rxjs from 'rxjs';
  *
  * Usage:
  *   <wm-modal [visible]="visible()" (dismiss)="close()">
- *     <div class="p-6 wm-r-md w-80" style="background: var(--wm-bg-raised)">
- *       <!-- modal panel content -->
+ *     <div class="panel" role="dialog" aria-modal="true" aria-labelledby="panel-title">
+ *       <h2 id="panel-title">Browse snapshot</h2>
+ *       <!-- modal panel content, including a visible close control -->
  *     </div>
  *   </wm-modal>
  *
@@ -38,6 +48,11 @@ import * as rxjs from 'rxjs';
  *
  * The projected content is wrapped in a stop-propagation container so clicks inside
  * the panel do not bubble up to the backdrop and trigger a dismiss.
+ *
+ * The backdrop's layout lives in this component's stylesheet, so it needs no utility
+ * framework in the consumer. Its colour stays an inline
+ * `background: var(--wm-modal-backdrop)`, because consumers detect an open modal
+ * with `[style*="--wm-modal-backdrop"]`.
  */
 declare class WmModal {
     /** Whether the modal is currently open. */
@@ -46,8 +61,8 @@ declare class WmModal {
     dismiss: _angular_core.OutputEmitterRef<void>;
     /**
      * Vertical alignment of the panel within the backdrop.
-     * - 'center' (default): panel is vertically centered (items-center)
-     * - 'top': panel appears near the top (items-start pt-20), for search/command overlays
+     * - 'center' (default): panel is centered on both axes
+     * - 'top': panel sits 5rem below the top edge, for search/command overlays
      */
     align: _angular_core.InputSignal<"center" | "top">;
     onEscape(): void;
@@ -74,21 +89,36 @@ type DialogSize = 'sm' | 'md' | 'lg';
  *     </div>
  *   </wm-dialog>
  *
+ * Width:
+ *  `size` picks a preset (sm 360px, md 480px, lg 640px). For any other width, set the
+ *  `--wm-dialog-width` custom property on the host; it overrides every preset:
+ *    <wm-dialog [(isOpen)]="open" title="Line history" style="--wm-dialog-width: 800px">
+ *  Fluid values work too, e.g. `min(90vw, 48rem)`. Whatever the width, the panel is
+ *  capped at `calc(100vw - 2rem)` wide and `calc(100dvh - 4rem)` tall.
+ *
+ *  When the dialog chrome itself is wrong for the surface (a two-pane browser, a
+ *  command palette, a panel with its own toolbar), use `wm-modal` with your own panel.
+ *
  * Accessibility:
  *  - role="dialog" + aria-modal="true" on the panel
  *  - aria-labelledby wired to the title element (when title is set)
- *  - Focus is trapped inside the panel when open (cdkTrapFocus)
+ *  - Focus is trapped inside the panel when open (cdkTrapFocus). Do not add a
+ *    cdkTrapFocus of your own inside the body; it would nest a second trap.
  *  - Escape key closes the dialog
  *  - Clicking the backdrop closes the dialog
- *  - On close, focus returns to the element that opened the dialog
- *    (browser default when focus trap is released)
+ *  - On close, focus returns to the element that had it when the dialog opened
+ *    (cdkTrapFocusAutoCapture records that element and refocuses it when the
+ *    trap is destroyed)
  */
 declare class WmDialog {
     /** Two-way binding for open/closed state. */
     isOpen: _angular_core.ModelSignal<boolean>;
     /** Dialog heading text. When set, aria-labelledby is applied automatically. */
     title: _angular_core.InputSignal<string>;
-    /** Panel width preset. sm = 360px, md = 480px (default), lg = 640px. */
+    /**
+     * Panel width preset. sm = 360px, md = 480px (default), lg = 640px.
+     * `--wm-dialog-width` on the host overrides every preset.
+     */
     size: _angular_core.InputSignal<DialogSize>;
     close(): void;
     onEscape(): void;
@@ -200,8 +230,14 @@ declare class WmSelect {
  * backdrop, focus-trapping, and ARIA attribute management.
  *
  * Slots:
- *  - [trigger]  — the anchor element (button, icon, etc.)
- *  - [content]  — the panel body (menu items, form, etc.)
+ *  - [trigger]  — the anchor element. Put the attribute on the focusable
+ *                 element itself, never on a wrapper or on a component host
+ *                 such as <wm-button>: the ARIA below goes to the element
+ *                 that carries it. For an Aegis-styled trigger, use
+ *                 `<button wmButton trigger>`. Nothing reads
+ *                 `data-popover-trigger`
+ *  - [content]  — the panel body (menu items, form, etc.). The panel carries
+ *                 the role, so the body takes no role of its own
  *
  * Usage:
  * ```html
@@ -214,16 +250,26 @@ declare class WmSelect {
  *   align="end"
  * >
  *   <button trigger (click)="open.set(!open())">Options</button>
- *   <div content role="menu">
+ *   <div content>
  *     <button role="menuitem" (click)="doThing()">Do thing</button>
  *   </div>
  * </wm-popover>
  * ```
  *
  * Accessibility:
- *  - Trigger element automatically receives aria-haspopup, aria-expanded, aria-controls
- *  - Panel receives the configured role and optional accessible name
+ *  - Trigger element automatically receives aria-haspopup (from `hasPopup`),
+ *    aria-expanded and aria-controls, plus role="button" when it has no role.
+ *    They are rewritten on every change to `isOpen` or `hasPopup`, so the
+ *    consumer does not bind them
+ *  - Panel receives the configured role and optional accessible name. The
+ *    role goes on the panel only: the host element, which wraps the trigger,
+ *    never carries it, even when a consumer writes `role` as a static attribute
+ *  - A `dialog` or `alertdialog` panel receives aria-modal="true" while it
+ *    captures focus (see `trapFocusAutoCapture`)
  *  - Focus is trapped inside the open panel (cdkTrapFocus)
+ *  - A modal panel whose content has nothing tabbable (text only, or a lone
+ *    disabled button) takes focus itself (tabindex="-1") and keeps it on Tab,
+ *    so focus is never left on the trigger that aria-modal makes inert
  *  - Escape key closes the panel
  *  - Backdrop click closes the panel
  *
@@ -276,6 +322,26 @@ declare class WmPopover {
      * auto-restore.
      */
     readonly trapFocusAutoCapture: _angular_core.InputSignal<boolean>;
+    /**
+     * `"true"` for a `dialog` or `alertdialog` panel that captures focus, else
+     * no attribute.
+     *
+     * The panel opens over a click-catching backdrop, and a modal panel keeps
+     * focus inside itself (see `onAttach` and `onPanelKeydown`), so nothing
+     * outside it can be reached until it closes. A dialog that is modal must say
+     * so, or a screen reader keeps reading the page behind it. `aria-modal` is
+     * defined for those two roles only, so a menu or listbox panel gets no
+     * attribute. With `trapFocusAutoCapture` off, focus is meant to stay on the
+     * trigger outside the panel, and `aria-modal` would hide that focused
+     * trigger from a screen reader, so the panel is not declared modal.
+     */
+    protected readonly ariaModal: _angular_core.Signal<string>;
+    /**
+     * `-1` on a modal panel, so the panel itself can take focus when its content
+     * has nothing tabbable. A non-modal panel stays unfocusable: a click on it
+     * must not pull focus off a typeahead trigger input.
+     */
+    protected readonly panelTabIndex: _angular_core.Signal<number>;
     /** Emitted when the panel should close (backdrop click, Escape key, CDK detach). */
     readonly closed: _angular_core.OutputEmitterRef<void>;
     private readonly renderer;
@@ -283,9 +349,26 @@ declare class WmPopover {
     private readonly cdr;
     protected readonly panelId: string;
     protected readonly panel: _angular_core.Signal<ElementRef<HTMLElement>>;
+    private readonly trap;
     constructor();
     protected get positions(): ConnectedPosition[];
+    /**
+     * Runs after the focus trap's own capture, which CDK defers to the next
+     * render. A `[wmAutoFocus]` element takes focus first. Otherwise a modal
+     * panel that the trap left without focus takes focus itself. The trap finds
+     * nothing to focus when the content has no tabbable element (text only, or a
+     * lone disabled button), and it then leaves focus on the trigger, which
+     * `aria-modal` has just made inert to a screen reader.
+     */
     protected onAttach(): void;
+    /**
+     * Tab and Shift+Tab while focus is on a modal panel itself, not on a control
+     * inside it. Focus moves to the first or the last tabbable control. With none,
+     * focus stays on the panel. The trap's own boundary anchors cannot do this:
+     * with nothing tabbable inside, the anchor keeps focus, and the next Tab
+     * leaves the overlay for the page behind the backdrop.
+     */
+    protected onPanelKeydown(event: KeyboardEvent): void;
     protected onClose(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmPopover, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmPopover, "wm-popover", never, { "isOpen": { "alias": "isOpen"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "hasPopup": { "alias": "hasPopup"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "trapFocusAutoCapture": { "alias": "trapFocusAutoCapture"; "required": false; "isSignal": true; }; }, { "closed": "closed"; }, never, ["[trigger]", "[content]"], true, never>;
@@ -327,21 +410,93 @@ declare class WmTab {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmTab, "wm-tab", never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "unavailable": { "alias": "unavailable"; "required": false; "isSignal": true; }; "unavailableReason": { "alias": "unavailableReason"; "required": false; "isSignal": true; }; "separatorBefore": { "alias": "separatorBefore"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
+/**
+ * WmTabs — an ARIA tablist of `<wm-tab>` children with a roving tab stop.
+ *
+ * Usage:
+ *   <wm-tabs [activeValue]="tool()" ariaLabel="Navigator tools" (select)="tool.set($event)">
+ *     <wm-tab value="graph">Graph</wm-tab>
+ *     <wm-tab value="search">Search</wm-tab>
+ *   </wm-tabs>
+ *
+ * Selection:
+ *  - `activeValue` names the selected tab. `null`, or a value no tab carries,
+ *    selects nothing: every tab reports aria-selected="false" and none paints
+ *    as active. 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.
+ *  - The tablist always keeps exactly one tab stop: the focused tab while
+ *    focus is inside, otherwise the selected tab, otherwise the first tab that
+ *    is not unavailable (the first tab when every tab is unavailable).
+ *  - Arrow keys, Home and End move focus only. A tab is selected on click,
+ *    Enter or Space, which emit `(select)`; the consumer sets `activeValue`.
+ *
+ * Accessibility:
+ *  - `ariaLabel` or `ariaLabelledby` names the inner role="tablist". Name
+ *    every tablist that shares a surface with another one, or assistive
+ *    technology cannot tell them apart. `ariaLabelledby` wins when both are
+ *    set. An `aria-label` attribute on the `<wm-tabs>` host names nothing: the
+ *    host has no role, so the attribute never reaches the tablist.
+ *  - Each tab is `id="wm-tab-{value}"` with `aria-controls="wm-panel-{value}"`.
+ *    Give the panel that id and role="tabpanel". The ids are built from the
+ *    value alone, so values must be unique across every tablist on the page.
+ */
 declare class WmTabs {
-    activeValue: _angular_core.InputSignal<string>;
-    variant: _angular_core.InputSignal<"line" | "pill">;
+    /**
+     * Value of the selected tab. `null`, or a value that matches no tab, selects
+     * nothing; the tablist still keeps one tab stop (see the class comment).
+     */
+    readonly activeValue: _angular_core.InputSignal<string>;
+    readonly variant: _angular_core.InputSignal<"line" | "pill">;
+    /** Accessible name for the tablist. Ignored while `ariaLabelledby` is set. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /**
+     * Id of a visible element that names the tablist. Prefer it over
+     * `ariaLabel` when a visible caption exists, so the accessible name matches
+     * the visible text (WCAG 2.5.3, Label in Name).
+     */
+    readonly ariaLabelledby: _angular_core.InputSignal<string>;
     readonly select: _angular_core.OutputEmitterRef<string>;
     protected readonly tabs: _angular_core.Signal<readonly WmTab[]>;
-    protected focusedIndex: _angular_core.WritableSignal<number>;
-    protected selectTab(tab: WmTab, index: number): void;
+    /**
+     * Value of the tab that holds focus, or null while focus is outside the
+     * tablist. Keyed by value, not index, so a tab added or removed before it
+     * cannot move the stop onto a different tab or off the end of the list.
+     */
+    protected readonly focusedValue: _angular_core.WritableSignal<string>;
+    /** Index of the one tab that is in the page's Tab order. */
+    protected readonly tabStop: _angular_core.Signal<number>;
+    private readonly host;
+    protected selectTab(tab: WmTab): void;
     protected onBlur(): void;
     protected onKeyDown(event: KeyboardEvent, container: HTMLElement): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmTabs, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmTabs, "wm-tabs", never, { "activeValue": { "alias": "activeValue"; "required": true; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; }, { "select": "select"; }, ["tabs"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmTabs, "wm-tabs", never, { "activeValue": { "alias": "activeValue"; "required": true; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; }, { "select": "select"; }, ["tabs"], never, true, never>;
 }
 
-type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive' | 'flat';
+/**
+ * `dashed` is the empty slot: the place a new item goes, at the end of the
+ * list it adds to. It sets colour and the dash only; a full-width slot is a
+ * `[wmButton]` with the consumer's own width class. For any other quiet
+ * action, use `ghost`.
+ */
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive' | 'flat' | 'dashed';
 type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+/**
+ * WmButton — an Aegis button as an element: `<wm-button variant="ghost">`.
+ *
+ * The host wraps a real `<button>` and passes it four inputs: `disabled`,
+ * `type`, `ariaLabel` (as `aria-label`) and `btnTitle` (as `title`). Nothing
+ * else crosses. An attribute, class or directive written on `<wm-button>` stays on
+ * the host, which has no role and cannot take focus. When something must reach
+ * the element a screen reader and the keyboard use (ARIA state such as
+ * `aria-pressed` or `aria-expanded`, `cdkFocusInitial`, an `id` another element
+ * points at, a popover `trigger`, `[wmTooltip]`, a class that changes the
+ * button's own box), write a native element with `[wmButton]` instead:
+ *
+ * ```html
+ * <button wmButton variant="ghost" [attr.aria-pressed]="wrap()">Wrap</button>
+ * ```
+ */
 declare class WmButton {
     readonly variant: _angular_core.InputSignal<ButtonVariant>;
     readonly size: _angular_core.InputSignal<ButtonSize>;
@@ -358,6 +513,44 @@ declare class WmButton {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmButton, "wm-button", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "iconOnly": { "alias": "iconOnly"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "btnTitle": { "alias": "btnTitle"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
+/**
+ * WmButtonDirective — the Aegis button classes on a native `<button>` or `<a>`.
+ *
+ * It renders exactly the class set `<wm-button>` puts on its inner button, but
+ * on the element the consumer writes. That element is the focusable one, so
+ * every attribute and directive on it reaches the right place with no
+ * forwarding list: ARIA state, `cdkFocusInitial`, `id`, `form`, a popover
+ * `trigger`, `[wmTooltip]`, test ids and consumer classes.
+ *
+ * Use `<wm-button>` by default. Use this when one of those has to land on the
+ * button itself (see `WmButton` for what the component forwards).
+ *
+ * - `variant`, `size` and `iconOnly` mean what they mean on `<wm-button>`.
+ * - Classes the consumer writes, static or bound, are kept.
+ * - A `<button>` with no `type` gets `type="button"`, the `<wm-button>`
+ *   default, so it does not submit a surrounding form. A written or bound
+ *   `type` wins. An `<a>` is left alone.
+ * - Everything else is native: write `disabled`, `aria-label` and `title`
+ *   directly. An `<a>` cannot be disabled.
+ *
+ * @example
+ * <button wmButton variant="ghost" size="sm" [attr.aria-pressed]="wrap()" (click)="toggleWrap()">
+ *   Wrap lines
+ * </button>
+ * <button wmButton variant="secondary" cdkFocusInitial (click)="cancel()">Keep editing</button>
+ * <a wmButton variant="ghost" href="/back">Back</a>
+ */
+declare class WmButtonDirective {
+    readonly variant: _angular_core.InputSignal<ButtonVariant>;
+    readonly size: _angular_core.InputSignal<ButtonSize>;
+    /** Makes the button square. An icon-only button still needs an `aria-label`. */
+    readonly iconOnly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    protected readonly hostClass: _angular_core.Signal<string>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmButtonDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WmButtonDirective, "button[wmButton], a[wmButton]", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "iconOnly": { "alias": "iconOnly"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
  * WmCheckbox — Boolean selection control with optional indeterminate state.
  *
@@ -541,7 +734,7 @@ interface Segment {
  *
  * When NOT to use:
  *  - An exact number the user knows before they start typing it → <wm-number-input>
- *  - Fewer than about five discrete choices → <wm-select> or a pill tab group
+ *  - Fewer than about five discrete choices → <wm-toggle-group> or <wm-select>
  *  - An unbounded value — a slider has to have a min and a max
  *
  * Value pipeline: every value, whether it arrives from a two-way binding, a
@@ -654,6 +847,160 @@ declare class WmSlider implements ControlValueAccessor {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmSlider, "wm-slider", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "showValue": { "alias": "showValue"; "required": false; "isSignal": true; }; "formatValue": { "alias": "formatValue"; "required": false; "isSignal": true; }; "track": { "alias": "track"; "required": false; "isSignal": true; }; "ticks": { "alias": "ticks"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
 }
 
+/** How the group is drawn. See `WmToggleGroup.appearance`. */
+type WmToggleGroupAppearance = 'segmented' | 'chip';
+/** Control height: `sm` is 24px, `md` is 28px. */
+type WmToggleGroupSize = 'sm' | 'md';
+/**
+ * WmToggleGroupItem — one choice in a `<wm-toggle-group>`.
+ *
+ * The element itself is the `role="radio"`, so anything written on it lands
+ * on the control a screen reader and the keyboard use: `aria-label` for an
+ * icon-only item, `[wmTooltip]`, `data-testid`, a consumer class.
+ */
+declare class WmToggleGroupItem {
+    /**
+     * The value the group takes, and emits, when this item is checked. Give
+     * every item one.
+     *
+     * Not `input.required`: the group reads every item's value to place the tab
+     * stop, and an item rendered by `@for` has its host bindings run before the
+     * next item's inputs are set. A required input throws NG0950 on that read;
+     * this one reads `undefined`, the group places the stop without it, and the
+     * binding settles when the next item's value arrives in the same pass.
+     */
+    readonly value: _angular_core.InputSignal<unknown>;
+    /** Takes this item out of the focus order and out of selection. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    protected readonly group: WmToggleGroup<any>;
+    /** @internal The item's own element, which carries role="radio". */
+    readonly element: HTMLElement;
+    protected readonly checked: Signal<boolean>;
+    /** @internal Disabled by its own input or by the group. */
+    readonly isDisabled: Signal<boolean>;
+    /**
+     * 0 for the one tab stop, -1 for the rest. A disabled item gets no tabindex
+     * at all: -1 would still let a pointer press focus it.
+     */
+    protected readonly tabIndex: Signal<0 | -1 | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmToggleGroupItem, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmToggleGroupItem, "wm-toggle-group-item", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+/**
+ * WmToggleGroup — a single-select choice among a few options, drawn as joined
+ * segments or as separate chips.
+ *
+ * Usage:
+ *   <wm-toggle-group [(value)]="strategy" ariaLabel="Pull strategy">
+ *     <wm-toggle-group-item value="merge">Merge</wm-toggle-group-item>
+ *     <wm-toggle-group-item value="rebase">Rebase</wm-toggle-group-item>
+ *   </wm-toggle-group>
+ *
+ * When to use:
+ *  - Two to about five mutually exclusive options that should all stay visible:
+ *    a setting (pull strategy, tab size, config scope), a view mode, a verdict
+ *  - A single-select filter row → `appearance="chip"`
+ *
+ * When NOT to use:
+ *  - Choosing which panel shows → `<wm-tabs>`. A tab controls a panel; a toggle
+ *    group sets a value
+ *  - An on/off setting → `<wm-toggle>` or a checkbox
+ *  - Several options that can be on together → checkboxes
+ *  - More options than fit on one line → `<wm-select>`
+ *
+ * Selection:
+ *  - `value` names the checked item. `null`, or a value no item carries,
+ *    checks nothing; the group still keeps one tab stop.
+ *  - `(valueChange)` fires once per user choice and only then: never for a
+ *    value written from outside, never for the item that is already checked,
+ *    and never with null. A two-way binding to a signal that cannot hold null
+ *    therefore type-checks.
+ *  - Items compare by `Object.is`, so a value keeps its type: `[value]="4"` on
+ *    an item emits the number 4, not the string "4".
+ *
+ * Keyboard (the WAI-ARIA APG radio group):
+ *  - Tab enters the group on one stop: the focused item while focus is inside,
+ *    otherwise the checked item, otherwise the first item that is not disabled.
+ *  - Arrow keys move focus AND check, wrapping at both ends and stepping over
+ *    disabled items. Left and Right swap in a right-to-left layout; Up and Down
+ *    follow document order. `Home` and `End` go to the first and last items.
+ *  - `Space` checks the focused item. `Enter` does not, as on a native radio.
+ *
+ * Accessibility:
+ *  - The `<wm-toggle-group>` element is the `role="radiogroup"` and each item
+ *    is a `role="radio"` with `aria-checked`. Name the group with `ariaLabel`,
+ *    or `ariaLabelledby` when a visible caption exists; `ariaLabelledby` wins.
+ *    An `aria-label` written straight on the element also works, because the
+ *    element carries the role.
+ *  - An icon-only item needs its own `aria-label`, written on the item.
+ *  - A disabled item keeps `aria-disabled="true"` and leaves the focus order.
+ *    A disabled group does the same for every item.
+ *
+ * Form integration: a ControlValueAccessor, so `formControlName`,
+ * `[formControl]` and `[(ngModel)]` all work. The control is marked touched
+ * when focus leaves the group.
+ */
+declare class WmToggleGroup<T = unknown> implements ControlValueAccessor {
+    /** Value of the checked item. `null`, or a value no item carries, checks nothing. */
+    readonly value: _angular_core.InputSignal<T>;
+    /** The value of the item the user checked. Never null; see the class comment. */
+    readonly valueChange: _angular_core.OutputEmitterRef<T>;
+    /** Accessible name for the radiogroup. Ignored while `ariaLabelledby` is set. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /**
+     * Id of a visible element that names the group. Prefer it over `ariaLabel`
+     * when a visible caption exists, so the accessible name matches the visible
+     * text (WCAG 2.5.3, Label in Name).
+     */
+    readonly ariaLabelledby: _angular_core.InputSignal<string>;
+    /**
+     * `segmented` joins the items in one sunken track, for a setting or a view
+     * mode. `chip` spaces them as separate rounded chips that wrap, for a filter
+     * row or a verdict.
+     */
+    readonly appearance: _angular_core.InputSignal<WmToggleGroupAppearance>;
+    readonly size: _angular_core.InputSignal<WmToggleGroupSize>;
+    /** Disables every item. Reactive forms set this independently. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    private readonly items;
+    private readonly host;
+    private readonly staticLabel;
+    private readonly staticLabelledby;
+    protected readonly accessibleLabelledby: Signal<string>;
+    protected readonly accessibleLabel: Signal<string>;
+    /** The checked value. Follows `value`, and moves at once on a user choice or a form write. */
+    private readonly checkedValue;
+    /** Set by reactive forms through setDisabledState, independent of the input. */
+    private readonly formDisabled;
+    /** @internal */
+    readonly isDisabled: Signal<boolean>;
+    /**
+     * The item that holds focus, or null while focus is outside the group. Kept
+     * as the item itself rather than an index, so an item added or removed
+     * before it cannot move the stop onto another item.
+     */
+    private readonly focusedItem;
+    /** @internal The one item in the page's Tab order, or null when none can take focus. */
+    readonly tabStop: Signal<WmToggleGroupItem | null>;
+    private onChange;
+    private onTouched;
+    /** @internal */
+    isChecked(item: WmToggleGroupItem): boolean;
+    /** @internal Checks `item` on a user action. */
+    select(item: WmToggleGroupItem): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onFocusIn(event: FocusEvent): void;
+    protected onFocusOut(event: FocusEvent): void;
+    /** The next item in `direction` that is not disabled, wrapping at both ends. */
+    private step;
+    writeValue(value: T | null): void;
+    registerOnChange(fn: (value: T) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmToggleGroup<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmToggleGroup<any>, "wm-toggle-group", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, ["items"], ["*"], true, never>;
+}
+
 /**
  * GhostField — transparent-until-hover wrapper for inline-editable fields.
  *
@@ -1262,5 +1609,5 @@ declare class WmRichTooltip {
  */
 declare function onViewportChange(handler: () => void): () => void;
 
-export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmModal, WmPopover, WmRichTooltip, WmRichTooltipContent, WmRichTooltipTrigger, WmSelect, WmSlider, WmTab, WmTabs, WmToastContainer, WmToastService, WmTooltip, onViewportChange };
-export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, SelectOption, Toast, ToastType, WmSliderTick, WmSliderTickFn, WmSliderTrack, WmTooltipPosition, WmTooltipRelation };
+export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmButtonDirective, WmCombobox, WmDialog, WmModal, WmPopover, WmRichTooltip, WmRichTooltipContent, WmRichTooltipTrigger, WmSelect, WmSlider, WmTab, WmTabs, WmToastContainer, WmToastService, WmToggleGroup, WmToggleGroupItem, WmTooltip, onViewportChange };
+export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, SelectOption, Toast, ToastType, WmSliderTick, WmSliderTickFn, WmSliderTrack, WmToggleGroupAppearance, WmToggleGroupSize, WmTooltipPosition, WmTooltipRelation };