@wildmason/aegis 1.13.0 → 1.14.0

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/fonts/CascadiaCode-OFL.txt

@@ -1,94 +1,94 @@
-Copyright (c) 2019 - Present, Microsoft Corporation,
-with Reserved Font Name Cascadia Code.
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+Copyright (c) 2019 - Present, Microsoft Corporation,
+with Reserved Font Name Cascadia Code.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@wildmason/aegis",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "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",