@wildmason/aegis 1.13.0 → 1.14.1

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

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { ElementRef, AfterViewInit, TemplateRef, OnDestroy } from '@angular/core';
-import { ConnectedPosition } from '@angular/cdk/overlay';
+import { ScrollStrategy, OverlayRef, ConnectedPosition } from '@angular/cdk/overlay';
 import { ControlValueAccessor } from '@angular/forms';
 import * as rxjs from 'rxjs';
 
@@ -110,6 +110,26 @@ interface SelectOption {
     disabled?: boolean;
 }
 
+/**
+ * A scroll strategy that keeps a connected overlay anchored to its trigger,
+ * including when the thing that scrolled was an ordinary `overflow: auto`
+ * element rather than the document.
+ *
+ * CDK's own reposition strategy does the right thing and is simply never told:
+ * it listens through `ScrollDispatcher`, which cannot hear a scroll from a
+ * container that is not marked `cdkScrollable`. See `onViewportChange` for the
+ * full account. This strategy listens in the capture phase instead, so the
+ * consumer annotates nothing.
+ */
+declare class WmAnchoredScrollStrategy implements ScrollStrategy {
+    private overlayRef;
+    private release;
+    attach(overlayRef: OverlayRef): void;
+    enable(): void;
+    disable(): void;
+    detach(): void;
+}
+
 /**
  * WmSelect — Accessible dropdown select built on Angular CDK Overlay.
  *
@@ -143,6 +163,16 @@ interface SelectOption {
  *  - Always pair with a visible label via <wm-label> or aria-label on the host
  */
 declare class WmSelect {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Array of options to display. */
     options: _angular_core.InputSignal<SelectOption[]>;
     /** The currently selected value. Two-way bindable. */
@@ -202,6 +232,16 @@ declare class WmSelect {
  *    Import WmAutoFocus from @wildmason/aegis/components and add it to your component's imports.
  */
 declare class WmPopover {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Whether the panel is currently open. */
     readonly isOpen: _angular_core.InputSignal<boolean>;
     /** Panel width in pixels, or 'auto' to match content. */
@@ -306,7 +346,7 @@ declare class WmButton {
     readonly variant: _angular_core.InputSignal<ButtonVariant>;
     readonly size: _angular_core.InputSignal<ButtonSize>;
     readonly disabled: _angular_core.InputSignal<boolean>;
-    readonly type: _angular_core.InputSignal<"button" | "submit" | "reset">;
+    readonly type: _angular_core.InputSignal<"reset" | "submit" | "button">;
     /** Makes the button square (equal width/height). Use for icon-only buttons. */
     readonly iconOnly: _angular_core.InputSignal<boolean>;
     /** Accessible label forwarded to the inner <button>. Required for icon-only buttons. */
@@ -595,6 +635,16 @@ declare class ComboboxPanel {
  *   <wm-combobox formControlName="tag" [options]="tags" />
  */
 declare class WmCombobox implements ControlValueAccessor, OnDestroy {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Full option list (before filtering). */
     readonly options: _angular_core.InputSignal<ComboboxOption[]>;
     /** Selected value (single-select). Two-way bindable. */
@@ -774,6 +824,164 @@ declare class WmToastContainer implements OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmToastContainer, "wm-toast-container", never, {}, {}, never, never, true, never>;
 }
 
+/** Where the panel sits relative to its host, before any viewport fallback. */
+type WmTooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * How the panel is related to the host for assistive technology.
+ *
+ * `description` points the host at the panel with `aria-describedby`. Use it
+ * when the host already has a name and the tooltip adds detail — an icon with
+ * an `aria-label`, a truncated cell, a status mark.
+ *
+ * `label` uses `aria-labelledby` instead, for an icon-only control whose only
+ * name is the tooltip. Do not use it alongside an `aria-label` on the same
+ * host: `aria-labelledby` wins, and the two texts then disagree about what the
+ * control is called depending on whether the tooltip happens to be open.
+ */
+type WmTooltipRelation = 'description' | 'label';
+/**
+ * WmTooltip — accessible floating explanation for any element.
+ *
+ * ```html
+ * <button class="wm-btn btn-icon-only" aria-label="Undo" [wmTooltip]="'Undo the last commit'">…</button>
+ * ```
+ *
+ * Why this exists next to the CSS `[data-tooltip]` chip: that chip is a
+ * pseudo-element on the host, so it cannot escape an ancestor's
+ * `overflow: hidden`, cannot wrap, and is invisible to assistive technology —
+ * it is a visual hint that must be paired with an `aria-label` saying the same
+ * thing twice. Reach for the chip for a one-to-five word label on a toolbar
+ * button. Reach for this directive when the text explains something, when the
+ * host sits inside a scrolling container, or when the explanation must be part
+ * of the accessible description rather than a duplicate of it.
+ *
+ * Accessibility:
+ *  - The panel carries `role="tooltip"` and a generated id.
+ *  - While open, the host points at that id with `aria-describedby` (default)
+ *    or `aria-labelledby`. The id is appended to whatever the host already
+ *    referenced and removed again on hide, so an application's own description
+ *    survives untouched.
+ *  - Opens on hover and on `:focus-visible`, so a mouse click that moves focus
+ *    to a button does not leave a tooltip hanging behind the pointer.
+ *  - WCAG 1.4.13 (Content on Hover or Focus): Escape dismisses without moving
+ *    focus; the pointer can travel into the panel and read it without it
+ *    closing; nothing auto-dismisses on a timer.
+ *
+ * Keyboard reachability is the caller's responsibility. A tooltip on an element
+ * that cannot take focus is unreachable by keyboard, so set
+ * `wmTooltipFocusable` to make the host a tab stop — but NOT inside a
+ * roving-tabindex container (tree, listbox, grid, tablist). There the container
+ * is a single tab stop by design, and adding one stop per row is worse for
+ * keyboard users than the gap it closes. Put the tooltip on the row itself, or
+ * expose it from a control the roving focus already reaches.
+ */
+declare class WmTooltip {
+    /** Tooltip body. Blank or absent means the tooltip never opens. */
+    readonly wmTooltip: _angular_core.InputSignal<string>;
+    /** Preferred side. Flips automatically when the viewport has no room. */
+    readonly wmTooltipPosition: _angular_core.InputSignal<WmTooltipPosition>;
+    /** Milliseconds a pointer must rest on the host before the panel opens. */
+    readonly wmTooltipDelay: _angular_core.InputSignal<number>;
+    /** Suppress the tooltip without unbinding it — for a control whose explanation only applies in some states. */
+    readonly wmTooltipDisabled: _angular_core.InputSignal<boolean>;
+    /** Whether the panel describes the host or names it. See WmTooltipRelation. */
+    readonly wmTooltipRelation: _angular_core.InputSignal<WmTooltipRelation>;
+    /**
+     * Make a non-focusable host a tab stop so a keyboard user can reach the
+     * tooltip. Only applied when the host is not already focusable, and never
+     * safe inside a roving-tabindex container — see the class comment.
+     */
+    readonly wmTooltipFocusable: _angular_core.InputSignal<boolean>;
+    private readonly host;
+    private readonly injector;
+    private readonly renderer;
+    private readonly panelId;
+    private overlayRef;
+    private panelRef;
+    private portal;
+    private showTimer;
+    private hideTimer;
+    private raiseFrame;
+    private pointerOnHost;
+    private pointerOnPanel;
+    private hostFocused;
+    private detachDocumentListeners;
+    /**
+     * Elements between the host and the document that can clip it, resolved
+     * once per open. They cannot change while the panel is up, and walking the
+     * ancestor chain on every scroll event would be work done per frame.
+     */
+    private clippingAncestors;
+    constructor();
+    /** Open the tooltip immediately, bypassing the hover delay. */
+    show(): void;
+    /** Close the tooltip immediately, without the pointer grace period. */
+    hideNow(): void;
+    /** True while the panel is attached. Exposed for tests and for callers driving it manually. */
+    get isOpen(): boolean;
+    protected onPointerEnterHost(): void;
+    protected onPointerLeaveHost(): void;
+    protected onFocusHost(): void;
+    protected onBlurHost(): void;
+    private text;
+    private scheduleShow;
+    private scheduleHide;
+    private clearTimer;
+    private ensureOverlay;
+    private positions;
+    private readonly onPointerEnterPanel;
+    private readonly onPointerLeavePanel;
+    private attachDocumentListeners;
+    private releaseDocumentListeners;
+    /**
+     * Follow the host, or give up on it.
+     *
+     * Repositioning alone is not enough. Once the host has scrolled out of its
+     * container the panel would be pushed against the container edge and left
+     * explaining a row the reader can no longer see - worse than not being there,
+     * because it now appears to describe whatever it happens to cover.
+     */
+    private reanchor;
+    /** Every ancestor that can clip the host, nearest first. */
+    private resolveClippingAncestors;
+    /** True once no part of the host is inside every container that clips it. */
+    private isHostClipped;
+    private relationAttribute;
+    private linkHostToPanel;
+    private unlinkHostFromPanel;
+    private isNativelyFocusable;
+    private matchesFocusVisible;
+    private teardown;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmTooltip, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WmTooltip, "[wmTooltip]", ["wmTooltip"], { "wmTooltip": { "alias": "wmTooltip"; "required": false; "isSignal": true; }; "wmTooltipPosition": { "alias": "wmTooltipPosition"; "required": false; "isSignal": true; }; "wmTooltipDelay": { "alias": "wmTooltipDelay"; "required": false; "isSignal": true; }; "wmTooltipDisabled": { "alias": "wmTooltipDisabled"; "required": false; "isSignal": true; }; "wmTooltipRelation": { "alias": "wmTooltipRelation"; "required": false; "isSignal": true; }; "wmTooltipFocusable": { "alias": "wmTooltipFocusable"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Notify a handler whenever anything that can move an anchored overlay moves.
+ *
+ * This exists because of one property of the DOM that CDK's `ScrollDispatcher`
+ * does not account for: **`scroll` does not bubble.**
+ *
+ * `ScrollDispatcher` has exactly two sources. It listens for `scroll` on the
+ * document in the *bubbling* phase, which therefore only ever hears the
+ * document itself scrolling; and it hears containers that registered
+ * themselves through a `cdkScrollable` directive. In an application shell that
+ * is a fixed-height frame with an inner scrolling element — which is every
+ * Wildmason product — the document never scrolls and nothing is registered, so
+ * both sources are empty and any scroll strategy built on the dispatcher is a
+ * silent no-op. The overlay keeps the coordinates it was born with while its
+ * trigger scrolls out from under it.
+ *
+ * A **capture-phase** listener on the document sees the event from any
+ * descendant, so nothing has to be annotated. Requiring every consumer to mark
+ * their scroll containers — and failing invisibly when they forget — is not a
+ * contract a design system should hand out.
+ *
+ * @param handler called on any scroll or resize while the subscription is live
+ * @returns a function that removes exactly what was added
+ */
+declare function onViewportChange(handler: () => void): () => void;
+
 interface LicenseStatus {
     valid: boolean;
     org: string | null;
@@ -843,5 +1051,5 @@ declare class WmLicenseDialog {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmLicenseDialog, "wm-license-dialog", never, { "visible": { "alias": "visible"; "required": true; "isSignal": true; }; }, { "dismiss": "dismiss"; }, never, never, true, never>;
 }
 
-export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService };
-export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, LicenseStatus, SelectOption, Toast, ToastType, WmDeclaredUseType };
+export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService, WmTooltip, onViewportChange };
+export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, LicenseStatus, SelectOption, Toast, ToastType, WmDeclaredUseType, WmTooltipPosition, WmTooltipRelation };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@wildmason/aegis",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "description": "Aegis design system \u00e2\u20ac\u201d CSS tokens and Angular component library",
   "scripts": {
     "check:offline-fonts": "node scripts/check-offline-fonts.mjs",
-    "build": "npm run check:offline-fonts && npm run check:destructive-contrast && npm run check:semantic-contrast && ng-packagr -p ng-package.json",
+    "build": "npm run check:offline-fonts && npm run check:destructive-contrast && npm run check:semantic-contrast && npm run check:tooltip-contrast && ng-packagr -p ng-package.json",
     "prepublishOnly": "npm run build",
     "check:destructive-contrast": "node scripts/check-destructive-contrast.mjs",
-    "check:semantic-contrast": "node scripts/check-semantic-contrast.mjs"
+    "check:semantic-contrast": "node scripts/check-semantic-contrast.mjs",
+    "check:tooltip-contrast": "node scripts/check-tooltip-contrast.mjs"
   },
   "files": [
     "dist",

package/themes.css

@@ -269,7 +269,22 @@
    * those wearing the tone's own 8% tint — the tint is the binding case,
    * because it moves the background toward the text.
    *
-   * Themes whose tone is already readable inherit it unchanged.
+   * EVERY THEME MUST STATE ALL FOUR `-readable` TOKENS. A theme that is happy
+   * with its own tone writes `var(--wm-color-<tone>)` and says so; it does not
+   * leave the declaration out. These aliases below are a floor for a theme
+   * being written, never a fallback a shipped theme may rely on, and
+   * `scripts/check-semantic-contrast.mjs` fails the build on an omission.
+   *
+   * The reason is a trap in this file's own shape. The warm-light block below
+   * is selected as `:root, [data-theme='warm-light']`, so it is BOTH the
+   * default theme AND a later bare-`:root` declaration. Anything it sets wins
+   * over these aliases for every theme that stays silent — which means a
+   * silent dark theme receives warm-light's dark-on-light values. That is
+   * exactly what shipped in 1.12.0 and 1.13.0: five (theme, tone) pairs
+   * inherited `#553f00` / `#3c4801` and rendered at 1.08:1 to 1.38:1 — Matt
+   * found the wildmason one by eye, as an unreadable glyph in Helm's branch
+   * picker. Every other token in this file escaped only because every theme
+   * happens to declare it.
    */
   --wm-color-danger-readable: var(--wm-color-danger);
   --wm-color-warning-readable: var(--wm-color-warning);
@@ -572,6 +587,11 @@
   --wm-color-danger: #ff5555;
   --wm-color-danger-solid: #cf4545;
   --wm-color-danger-readable: #febdb7;
+  /* Stated rather than inherited, and that is the whole rule for these four —
+     see the note over the generic aliases in :root. Both of these tones already
+     read: 6.66:1 / Lc 82.4 and 5.65:1 / Lc 69.7 at their worst ground. */
+  --wm-color-warning-readable: var(--wm-color-warning);
+  --wm-color-success-readable: var(--wm-color-success);
 
   /* Item type colors */
   --wm-color-task: #8be9fd;
@@ -648,6 +668,10 @@
   --wm-color-danger-solid: #b65b5b;
   --wm-color-danger-readable: #fea7a4;
   --wm-color-success-readable: #6dcfb0;
+  /* #f0b464 reads on the bare surfaces but lands under Lc 61 on its own 8%
+     tint over --wm-bg-float. Hue held, chroma at 95%, lightness moved only:
+     6.43:1 / Lc 61.1 at the worst ground. */
+  --wm-color-warning-readable: #eeb56a;
 
   /* Item type colors */
   --wm-color-task: #70a8f0;
@@ -873,6 +897,8 @@
   --wm-color-danger-solid: #e02267;
   --wm-color-danger-readable: #ffb1bf;
   --wm-color-warning-readable: #feb878;
+  /* Already reads at 5.96:1 / Lc 65.8; stated so it cannot inherit. */
+  --wm-color-success-readable: var(--wm-color-success);
 
   /* Item type colors */
   --wm-color-task: #66d9ef;
@@ -1105,6 +1131,11 @@
   --wm-color-danger-solid: #b45b64;
   --wm-color-danger-readable: #febec1;
   --wm-color-success-readable: #b2d8b2;
+  /* The token Matt caught: this theme inherited warm-light's #553f00 and drew
+     the branch picker's stash glyph at 1.11:1 — a dark brown on a dark grey.
+     #ebcb8b itself lands just under Lc 61 on its own tint over --wm-bg-float,
+     so hue held, chroma at 90%: 4.91:1 / Lc 61.1 at the worst ground. */
+  --wm-color-warning-readable: #e8cc93;
 
   /* Item type colors — Wildmason selection */
   --wm-color-task: #82a682;