ngwr 11.1.0 → 12.0.0

package/types/ngwr-dialog.d.ts

@@ -4,6 +4,7 @@ import { OverlayRef } from '@angular/cdk/overlay';
 import * as i0 from '@angular/core';
 import { ComponentRef, InjectionToken, ElementRef } from '@angular/core';
 import { ReplaySubject } from 'rxjs';
+import * as i1 from '@angular/cdk/scrolling';
 
 /**
  * @license
@@ -87,6 +88,15 @@ interface WrDialogOptions<D = unknown> {
     readonly closeOnBackdropClick?: boolean;
     /** When `true`, the Escape key closes the dialog. @default true */
     readonly closeOnEscape?: boolean;
+    /**
+     * When `true`, the dialog closes as soon as the URL changes — the Back button
+     * and any `router.navigate()` alike. Nothing else ties a dialog to the route
+     * it was opened on, so turning this off leaves the pane, its backdrop and its
+     * focus trap over whatever page the app navigates to. Turn it off only for a
+     * dialog that OWNS the navigation (a wizard that keeps its step in the URL).
+     * @default true
+     */
+    readonly closeOnNavigation?: boolean;
     /**
      * Render a dismiss (×) button in the panel's top-right corner. Set `false`
      * when the content supplies its own close affordance, or when the dialog must
@@ -139,7 +149,24 @@ declare class WrDialog {
     private readonly isBrowser;
     private readonly responsiveConfig;
     private readonly i18n;
+    private readonly location;
     open<C, R = unknown, D = unknown>(component: ComponentType<C>, options?: WrDialogOptions<D>): WrDialogRef<C, R>;
+    /**
+     * Tie the dialog's lifetime to the URL it was opened on.
+     *
+     * Nothing else does. The overlay belongs to a root service and is dismissed
+     * only by the backdrop, Escape or an explicit `close()`, so pressing Back
+     * swapped the routed view underneath and left the modal pane, its backdrop and
+     * its focus trap sitting over a page the user never opened them on.
+     *
+     * `onUrlChange`, not `Location.subscribe()` — which is what CDK's own
+     * `disposeOnNavigation` uses: `subscribe` fires on popstate alone, so an
+     * in-app `router.navigate()` left the dialog standing. And `dialogRef.close()`
+     * rather than disposing the overlay behind the ref's back, which would never
+     * emit `closed`, never destroy the focus trap, and leave `awaitClose()`
+     * pending forever.
+     */
+    private watchNavigation;
     /**
      * The dismiss button's accessible name.
      *
@@ -242,6 +269,16 @@ declare class WrDialogTitle {
 /**
  * Styles the scrollable body section of a dialog.
  *
+ * `CdkScrollable` is a host directive because this element is a real scroll
+ * container (`overflow: auto`) and an anchored overlay opened from inside it has
+ * to follow its trigger. CDK's `reposition()` strategy listens to
+ * `ScrollDispatcher`, which is fed by registered scrollables plus ONE
+ * non-capturing `document` listener — and element `scroll` does not bubble, so
+ * without the registration a `<wr-select>` halfway down a long dialog form kept
+ * its panel pinned to the viewport while the trigger scrolled away. Angular
+ * Material carries the same host directive on `MatDialogContent` for the same
+ * reason.
+ *
  * @example
  * ```html
  * <div wrDialogContent>…body…</div>
@@ -249,7 +286,7 @@ declare class WrDialogTitle {
  */
 declare class WrDialogContent {
     static ɵfac: i0.ɵɵFactoryDeclaration<WrDialogContent, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<WrDialogContent, "[wrDialogContent]", never, {}, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<WrDialogContent, "[wrDialogContent]", never, {}, {}, never, never, true, [{ directive: typeof i1.CdkScrollable; inputs: {}; outputs: {}; }]>;
 }
 
 /**

package/types/ngwr-divider.d.ts

@@ -65,6 +65,31 @@ declare class WrDivider {
      */
     readonly align: _angular_core.InputSignal<WrDividerAlign>;
     protected readonly classes: _angular_core.Signal<string>;
+    private readonly host;
+    /**
+     * The consumer's own `aria-label`, resolved on the first sync — `undefined`
+     * until then, which is how "not looked at yet" stays distinct from "they wrote
+     * none".
+     */
+    private authored;
+    constructor();
+    /**
+     * Name the separator with the label it projects.
+     *
+     * `role="separator"` makes the host's children presentational and a separator
+     * takes its accessible name from the author alone — so `<wr-divider>OR</wr-divider>`
+     * reaches assistive tech as an unnamed rule while everyone else reads "OR".
+     * Copying the label into `aria-label` is the only way to expose it without giving
+     * up the role, and the two can never disagree because one is the source of the
+     * other.
+     *
+     * Written straight to the DOM rather than through a host binding, for two
+     * reasons a binding cannot cover: the label is projected content, so an
+     * interpolation or an `@if` can change it while the divider stays put; and a
+     * binding resolving to `null` would strip an `aria-label` the consumer wrote
+     * themselves — theirs is the author name already and is never touched.
+     */
+    private syncLabel;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrDivider, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrDivider, "wr-divider", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }

package/types/ngwr-donut-chart-testing.d.ts

@@ -0,0 +1,83 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-donut-chart>` a harness query matches. */
+interface WrDonutChartHarnessFilters extends BaseHarnessFilters {
+    /** Match the chart's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a chart whose legend holds this label. */
+    readonly sliceLabel?: string | RegExp;
+}
+/** One legend row — the only place a slice's label and value are readable. */
+interface WrDonutChartLegendEntry {
+    readonly label: string;
+    readonly value: string;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-donut-chart>`.
+ *
+ * **The ring itself is unreadable, and that is by design.** The slices are SVG
+ * paths inside a `role="img"` drawing: a screen reader is given that drawing's
+ * `aria-label` and nothing else, and a spec cannot get a label or a value off a
+ * path's `d`. {@link getLegend} is where the numbers are — which is also the
+ * argument for keeping `showLegend` on, since with it off the only other text is
+ * whatever {@link getCenterValue} and {@link getCenterLabel} were given.
+ *
+ * The name is read off the `<svg>` rather than off the surface that wraps it, and
+ * the two are not interchangeable: `img` makes its whole subtree presentational, so
+ * a name on the wrapper would take the centre text down with it.
+ *
+ * {@link getSliceCount} is therefore the one thing the ring answers: how many
+ * wedges were drawn. Compare it with the legend's length to catch a slice that was
+ * filtered out of one and not the other.
+ *
+ * @example
+ * ```ts
+ * const chart = await loader.getHarness(WrDonutChartHarness);
+ *
+ * expect(await chart.getSliceCount()).toBe(3);
+ * expect(await chart.getLegend()).toEqual([
+ *   { label: 'Direct', value: '48' },
+ *   { label: 'Search', value: '32' },
+ *   { label: 'Social', value: '20' },
+ * ]);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDonutChartHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrDonutChartHarnessFilters): HarnessPredicate<WrDonutChartHarness>;
+    /** The name the ring announces — the whole chart's, since the slices announce nothing. */
+    getAccessibleName(): Promise<string | null>;
+    /** How many wedges were drawn. */
+    getSliceCount(): Promise<number>;
+    /** Whether the legend is rendered (`showLegend`, and at least one slice). */
+    hasLegend(): Promise<boolean>;
+    /** The legend rows in order — the only textual form the data has. */
+    getLegend(): Promise<WrDonutChartLegendEntry[]>;
+    /** The big number in the middle, or `null` when the chart has none. */
+    getCenterValue(): Promise<string | null>;
+    /** The caption under the centre value, or `null`. */
+    getCenterLabel(): Promise<string | null>;
+    /** The ring's diameter in pixels, as the component writes it inline. */
+    getSize(): Promise<number>;
+}
+
+export { WrDonutChartHarness };
+export type { WrDonutChartHarnessFilters, WrDonutChartLegendEntry };

package/types/ngwr-donut-chart.d.ts

@@ -23,9 +23,9 @@ interface WrDonutSegment {
 declare class WrDonutChart {
     readonly segments: _angular_core.InputSignal<readonly WrDonutSegment[]>;
     /**
-     * Accessible name of the chart. The ring is `aria-hidden` and the legend is optional,
-     * so with `showLegend: false` this is the only thing a screen reader gets. Falls back
-     * to `donutChart.label`.
+     * Accessible name of the drawing. The arcs carry no text and the legend is optional, so
+     * with `showLegend: false` this and the centre text are the whole of what a screen reader
+     * gets. Falls back to `donutChart.label`.
      */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedAriaLabel: _angular_core.Signal<string>;

package/types/ngwr-drag-drop.d.ts

@@ -21,8 +21,21 @@ interface WrSortableReorderEvent<T> {
  * emitted via 2-way `[(items)]`.
  *
  * Drop a single template — it's rendered per item with `let-item
- * let-index="index"`. Add `[handle]="true"` (or `[wrDragHandle]` inside
- * your template) to restrict drag start to a handle element.
+ * let-index="index"`. Put `wrDragHandle` on an element inside that
+ * template to restrict drag start to a handle; there is no input for
+ * it, the directive's presence is the switch.
+ *
+ * Every row is a tab stop: Space or Enter picks it up, the arrow keys move it,
+ * Space or Enter drops it and Escape puts it back. CDK's `cdkDrag` ships no key
+ * handling of its own, so without this the component's only function was
+ * unreachable from a keyboard.
+ *
+ * What that does NOT answer is WCAG 2.5.7, which asks for a POINTER alternative
+ * to the drag. Click-to-pick-up is the obvious candidate and is not safe here:
+ * the CDK's drag-drop bundle installs no click suppressor of any kind, so the
+ * mouseup ending a drag still produces a click, and a row that grabbed itself on
+ * click would be picking itself straight back up. A visible move-up /
+ * move-down affordance is the remaining answer, and that is a design change.
  *
  * @example
  * ```html
@@ -64,7 +77,48 @@ declare class WrSortableList<T = unknown> {
     /** Fired after a successful reorder with the new array + indices. */
     readonly reorder: _angular_core.OutputEmitterRef<WrSortableReorderEvent<T>>;
     protected readonly rowTemplate: _angular_core.Signal<TemplateRef<any>>;
+    private readonly injector;
+    private readonly rowEls;
+    /** Index of the row the keyboard is holding, or `null` when nothing is held. */
+    protected readonly grabbedIndex: _angular_core.WritableSignal<number | null>;
+    /** Live-region text. Written by the keyboard path only. */
+    protected readonly announcement: _angular_core.WritableSignal<string>;
+    /** Links every row to the key model via `aria-describedby`. */
+    protected readonly keyHelpId: string;
+    protected readonly resolvedKeyHelp: _angular_core.Signal<string>;
+    private readonly grabbedText;
+    private readonly movedText;
+    private readonly droppedText;
+    private readonly cancelledText;
+    /** Where the held row started. Escape puts it back there. */
+    private grabOrigin;
+    /** True while a keyboard move is handing focus back — see `onRowFocusout`. */
+    private restoringFocus;
     protected onDrop(event: CdkDragDrop<T[]>): void;
+    /**
+     * The keyboard reorder path: pick up, move, drop — deliberately a two-step
+     * grab rather than "an arrow moves the focused row", so that arrowing through
+     * a list a user is only reading can never rearrange it.
+     *
+     * Keys are handled only when the ROW itself is the event target; a button or
+     * an input projected into the row template keeps every key it would normally
+     * get.
+     */
+    protected onRowKeydown(event: KeyboardEvent, index: number): void;
+    /**
+     * Focus leaving a held row ends the gesture as a drop rather than dropping the
+     * change on the floor — `[(items)]` has already been written by then, so a
+     * silent release would leave `reorder` never reporting a move that happened.
+     * The guard is what makes it safe: moving a focused node in the DOM blurs it,
+     * so every keyboard move fires this too.
+     */
+    protected onRowFocusout(): void;
+    private grab;
+    private moveGrabbed;
+    private drop;
+    private cancelGrab;
+    private relocate;
+    private position;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrSortableList<any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSortableList<any>, "wr-sortable-list", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "lockAxis": { "alias": "lockAxis"; "required": false; "isSignal": true; }; "dragStartDelay": { "alias": "dragStartDelay"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; }, { "items": "itemsChange"; "reorder": "reorder"; }, ["rowTemplate"], never, true, never>;
 }

package/types/ngwr-drawer.d.ts

@@ -48,6 +48,16 @@ interface WrDrawerOptions<D = unknown> {
     readonly closeOnBackdropClick?: boolean;
     /** When `true`, the Escape key closes the drawer. @default true */
     readonly closeOnEscape?: boolean;
+    /**
+     * When `true`, the drawer closes as soon as the URL changes — the Back button
+     * and any `router.navigate()` alike. Nothing else ties a drawer to the route
+     * it was opened on, so turning this off leaves the panel, its backdrop, its
+     * focus trap and the page-wide scroll block over whatever page the app
+     * navigates to. Turn it off only for a drawer that OWNS the navigation (a
+     * filter panel that keeps its state in the query string).
+     * @default true
+     */
+    readonly closeOnNavigation?: boolean;
     /**
      * Render a dismiss (×) button in the panel's top-right corner. Set `false`
      * when the content supplies its own close affordance. @default true
@@ -125,12 +135,33 @@ declare class WrDrawer {
     readonly closeLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedCloseLabel: _angular_core.Signal<string>;
     protected readonly panelTpl: _angular_core.Signal<TemplateRef<any>>;
+    /**
+     * A projected `[wrDrawerTitle]`, if the consumer gave one.
+     *
+     * The dismiss button is corner chrome positioned at a fixed
+     * `inset-block-start` chosen to centre it on the TITLE's first line. With no
+     * title the content starts at the top of the panel and runs underneath it: on
+     * a bare `<wr-drawer><nav /></wr-drawer>` the button covered the first menu
+     * row by 24×16 px, and `elementFromPoint` at the button's centre returned the
+     * button, so that corner of the first item was unclickable. The panel has to
+     * know, because only the panel can reserve the space.
+     */
+    private readonly projectedTitle;
     protected panelClass(): string;
     private swipeStartX;
     private swipeStartY;
     private swiping;
     protected onSwipeStart(event: PointerEvent): void;
     protected onSwipeMove(event: PointerEvent, panel: HTMLElement): void;
+    /**
+     * A cancelled pointer is an ABANDONED swipe, not a completed one — the system
+     * took the gesture away (a call, a system gesture, an orientation change) and
+     * no `pointerup` ever arrives. Routing it through `onSwipeEnd` dismissed the
+     * drawer on an interruption the user did not ask for and, because the overlay
+     * is disposed with the dragged offset applied, could not take back. Same rule
+     * `wr-pull-to-refresh` states for `touchcancel`.
+     */
+    protected onSwipeCancel(panel: HTMLElement): void;
     protected onSwipeEnd(event: PointerEvent, panel: HTMLElement): void;
     /** Axis + sign of the closing direction for the current position. */
     private closeAxis;
@@ -143,10 +174,22 @@ declare class WrDrawer {
     private focusTrap;
     private previouslyFocused;
     constructor();
+    /**
+     * Point the panel's `aria-labelledby` at the CURRENT `[wrDrawerTitle]`.
+     *
+     * Re-resolved after every render rather than once when the drawer opens,
+     * because the title element is projected content and can come and go while
+     * the drawer stays open — an `@if` around it, or a heading that only exists
+     * once the data arrives. A one-shot lookup leaves the attribute naming an
+     * element that has been removed or replaced, and a dangling reference is not
+     * a name: the dialog is announced as unnamed, with nothing on screen to say
+     * so. A missing title clears the attribute for the same reason.
+     */
+    private syncLabel;
     private openOverlay;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrDrawer, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrDrawer, "wr-drawer", never, { "open": { "alias": "open"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "showHandle": { "alias": "showHandle"; "required": false; "isSignal": true; }; "safeArea": { "alias": "safeArea"; "required": false; "isSignal": true; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; "isSignal": true; }; "closeOnBackdropClick": { "alias": "closeOnBackdropClick"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "closeLabel": { "alias": "closeLabel"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrDrawer, "wr-drawer", never, { "open": { "alias": "open"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "showHandle": { "alias": "showHandle"; "required": false; "isSignal": true; }; "safeArea": { "alias": "safeArea"; "required": false; "isSignal": true; }; "hasBackdrop": { "alias": "hasBackdrop"; "required": false; "isSignal": true; }; "closeOnBackdropClick": { "alias": "closeOnBackdropClick"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "closeLabel": { "alias": "closeLabel"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, ["projectedTitle"], ["*"], true, never>;
 }
 
 /**
@@ -253,14 +296,34 @@ declare class WrDrawerManager {
     private readonly focusTrapFactory;
     private readonly isBrowser;
     private readonly i18n;
+    private readonly location;
     open<C, R = unknown, D = unknown>(component: ComponentType<C>, options?: WrDrawerOptions<D>): WrDrawerRef<C, R>;
+    /**
+     * Tie the drawer's lifetime to the URL it was opened on — the same treatment
+     * `WrDialog` gets, and for the same reason.
+     *
+     * Nothing else does. The overlay belongs to a root service and is dismissed
+     * only by the backdrop, Escape, the appended × or an explicit `close()`, so
+     * navigating away left the panel, its backdrop, its focus trap and the
+     * page-wide scroll block sitting over a page the user never opened them on.
+     *
+     * `onUrlChange`, not `Location.subscribe()` — which is what CDK's own
+     * `disposeOnNavigation` uses: `subscribe` fires on popstate alone, so an in-app
+     * `router.navigate()` left the drawer standing. And `drawerRef.close()` rather
+     * than disposing the overlay behind the ref's back, which would never emit
+     * `closed`, never destroy the focus trap, and leave `awaitClose()` pending.
+     */
+    private watchNavigation;
     /**
      * The dismiss button's accessible name.
      *
-     * Resolved per open, not once at injection: this is a root service, so a
-     * `readI18nText` field — which is what `WrDialog` uses — would be evaluated
-     * before an async catalog had loaded and then freeze that answer for the life
-     * of the app.
+     * Resolved per open, not stored as a plain string at injection: this is a root
+     * service, so a one-shot read — which is what `WrDialog` used to have, and moved
+     * off for this reason — would run before an async catalog had loaded and then
+     * freeze that answer for the life of the app. (`readI18nText` hands back a signal
+     * now, so it would no longer freeze; the name still has to be pushed onto the
+     * button per open either way.) `WrDialog.closeLabel()` is the matching precedent,
+     * not the counter-example.
      *
      * The miss check is the point. `t()` hands back the KEY when the catalog has
      * no entry, and `WrI18n` is root-provided with an empty catalog by default —

package/types/ngwr-dropdown.d.ts

@@ -97,6 +97,15 @@ declare class WrDropdown {
     /** Toggle the menu. */
     toggle(): void;
     /** @internal */
+    /**
+     * Whether the pointer, rather than the keyboard, opened the current menu.
+     *
+     * A hover-opened menu must not take focus — the APG shows a menu on hover and
+     * leaves the caret where it was — while a keyboard-opened one must. The
+     * trigger MODE cannot answer that on its own: a `trigger="hover"` menu is
+     * still openable with Enter, and that open should focus the first item.
+     */
+    private openedByPointer;
     protected onClick(event: MouseEvent): void;
     /** @internal */
     protected onMouseEnter(): void;