ngwr 11.1.0 → 12.0.0

package/types/ngwr-window-testing.d.ts

@@ -0,0 +1,263 @@
+import { BaseHarnessFilters, ContentContainerComponentHarness, HarnessPredicate, ComponentHarness } from '@angular/cdk/testing';
+import { WrWindowState } from 'ngwr/window';
+
+/**
+ * @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-window>` a harness query matches. */
+interface WrWindowHarnessFilters extends BaseHarnessFilters {
+    /** Match the title-bar text — a string is an exact match, a RegExp is tested. */
+    readonly title?: string | RegExp;
+    /** Match windows in one visual state. */
+    readonly state?: WrWindowState;
+}
+/** Narrows which `<wr-window-taskbar>` a harness query matches. */
+interface WrWindowTaskbarHarnessFilters extends BaseHarnessFilters {
+    /** Match the edge the taskbar is pinned to. */
+    readonly position?: 'top' | 'bottom';
+}
+/**
+ * Where a window is and how big, in CSS pixels — the numbers the component writes
+ * inline, not a measured box.
+ */
+interface WrWindowBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * @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 a window opened through `WrWindowManager.open()`.
+ *
+ * `WrWindow` is deliberately not exported — a window is always a service call — so
+ * there is nothing in your fixture to load: each window is a portal in its own
+ * overlay pane, and this comes from
+ * `TestbedHarnessEnvironment.documentRootLoader()`.
+ *
+ * It is a CONTENT CONTAINER, like `WrDialogHarness`: the component you opened is
+ * projected into the window's body, so `window.getHarness(WrButtonHarness…)` reads
+ * ITS buttons and cannot reach another window's. That matters more here than
+ * anywhere else, because windows are explicitly non-modal and several are normally
+ * open at once.
+ *
+ * **Geometry is read from the inline styles the component writes**, never measured:
+ * a window is positioned with `left` / `top` / `width` / `height` in pixels, and a
+ * unit test has no layout to measure. That also makes {@link getBox} the way to
+ * assert a move or a resize — including the ones a drag would produce, which no
+ * synthetic pointer event can, since the drag divides by a rect that is 0×0 here.
+ *
+ * @example
+ * ```ts
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * windows.open(EditorComponent, { title: 'Untitled.md' });
+ * await fixture.whenStable();
+ *
+ * const win = await rootLoader.getHarness(WrWindowHarness.with({ title: 'Untitled.md' }));
+ * await win.maximize();
+ * expect(await win.getState()).toBe('maximized');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrWindowHarness extends ContentContainerComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — windows come in stacks. */
+    static with(options?: WrWindowHarnessFilters): HarnessPredicate<WrWindowHarness>;
+    private readonly titleEl;
+    /**
+     * Whether this window is still on the page.
+     *
+     * For a harness you are already HOLDING: closing disposes the overlay, so this
+     * flips to `false` where a fresh `getHarnessOrNull()` comes back `null`. A
+     * MINIMIZED window is still open — it is a state, not a dismissal — and this
+     * stays `true` for one.
+     */
+    isOpen(): Promise<boolean>;
+    /** The title-bar text. */
+    getTitle(): Promise<string>;
+    /** The projected `[wrWindowTitleExtra]` content, trimmed — empty when there is none. */
+    getTitleExtraText(): Promise<string>;
+    /** The window's visual state, from the host modifier. */
+    getState(): Promise<WrWindowState>;
+    /**
+     * The OS the chrome is dressed as — `macos`, `windows` or `linux`.
+     *
+     * Worth asserting because it is not cosmetic: on macOS the buttons are a
+     * traffic-light cluster in close → minimize → maximize order, and the Linux
+     * chrome renders neither minimize nor maximize UNLESS `showMinimize` /
+     * `showMaximize` asks for them. "No minimize on Linux" is a default, not an
+     * invariant — see {@link hasMinimizeButton}.
+     */
+    getOs(): Promise<string>;
+    /** The title-bar density — `normal` or `compact`. */
+    getChromeSize(): Promise<string>;
+    /**
+     * Where the window is and how big, in CSS pixels.
+     *
+     * From the inline styles the component writes, which is the only readable answer
+     * without layout — and the same numbers a drag or a snap would change.
+     */
+    getBox(): Promise<WrWindowBox>;
+    /**
+     * The window's stacking order.
+     *
+     * The manager hands out a z-index per focus, so this is how a spec asserts that
+     * clicking a window brought it to the front — the one thing a window manager
+     * exists to do, and the reason these panes are deliberately kept OUT of the
+     * browser's top layer, which orders strictly by entry.
+     */
+    getZIndex(): Promise<number>;
+    /** Whether the resize handles are rendered — `resizable`, and only in the normal state. */
+    isResizable(): Promise<boolean>;
+    /** The resize handles currently rendered, by their edge / corner suffix. */
+    getResizeHandles(): Promise<string[]>;
+    /** The body text of the window — the component you opened, as rendered. */
+    getBodyText(): Promise<string>;
+    /** The projected `[wrWindowStatusBar]` content, trimmed. */
+    getStatusBarText(): Promise<string>;
+    /** Whether the chrome offers a close button (`showClose`). */
+    hasCloseButton(): Promise<boolean>;
+    /**
+     * Whether the chrome offers a minimize button.
+     *
+     * `false` on Linux BY DEFAULT — that chrome is close-only by convention, which
+     * is a real behavioural difference and not a style. `showMinimize: true`
+     * overrides it, and a spec that asserts "no minimize on Linux" without saying
+     * which of the two it means will pass for the wrong reason.
+     */
+    hasMinimizeButton(): Promise<boolean>;
+    /** Whether the chrome offers a maximize button. Also `false` on Linux by default. */
+    hasMaximizeButton(): Promise<boolean>;
+    /** The close button's accessible name — the buttons are icon-only, so it is their only name. */
+    getCloseLabel(): Promise<string | null>;
+    /**
+     * The minimize button's accessible name, which flips to the restore wording while
+     * the window is minimized — the same button does both.
+     */
+    getMinimizeLabel(): Promise<string | null>;
+    /** The maximize button's accessible name, which flips while the window is maximized. */
+    getMaximizeLabel(): Promise<string | null>;
+    /** Click the close button. Throws on a window opened `showClose: false`. */
+    close(): Promise<void>;
+    /**
+     * Click the minimize button — which RESTORES a minimized window, since it is the
+     * same control.
+     */
+    minimize(): Promise<void>;
+    /** Click the maximize button — which restores a maximized window down. */
+    maximize(): Promise<void>;
+    /**
+     * Double-click the title bar, the other way to maximize.
+     *
+     * A separate gesture worth its own assertion, and it does NOT follow the
+     * button: only an explicit `showMaximize: false` turns it off. The Linux
+     * chrome hides the button by convention and keeps the gesture — which is also
+     * the only way out of a window that reached `maximized` without one.
+     */
+    doubleClickChrome(): Promise<void>;
+    /** Click the window body — which pulls it to the front of the stack. */
+    focusWindow(): Promise<void>;
+    /** Press Escape. A window opened `closeOnEscape: false` ignores it — assert, do not assume. */
+    sendEscape(): Promise<void>;
+    /** The role the window announces — `dialog`, on a non-modal window. */
+    getRole(): Promise<string | null>;
+    /**
+     * Whether the window takes its accessible name from its own title element.
+     *
+     * Resolved rather than trusted: `aria-labelledby` naming an element that is not
+     * this window's title is not a name, and with several windows open the ids are
+     * the only thing keeping them apart.
+     */
+    isLabelledByTitle(): Promise<boolean>;
+    /** Whether the window is hidden from assistive tech (`aria-hidden`, set while closed). */
+    isHiddenFromAssistiveTech(): Promise<boolean>;
+    private chromeAction;
+    private requireAction;
+}
+
+/**
+ * @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-window-taskbar>` — the rail of minimized windows.
+ *
+ * The taskbar IS an element in your template, so it comes from the normal fixture
+ * loader, unlike the windows it lists. It renders nothing but its own host until a
+ * window is minimized; {@link isEmpty} is the question, and {@link getTabTitles}
+ * answers `[]` rather than throwing, because "no minimized windows" is the ordinary
+ * state rather than a mistake.
+ *
+ * @example
+ * ```ts
+ * const taskbar = await loader.getHarness(WrWindowTaskbarHarness);
+ *
+ * await (await rootLoader.getHarness(WrWindowHarness)).minimize();
+ * expect(await taskbar.getTabTitles()).toEqual(['Untitled.md']);
+ * await taskbar.restore('Untitled.md');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrWindowTaskbarHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrWindowTaskbarHarnessFilters): HarnessPredicate<WrWindowTaskbarHarness>;
+    /** The edge the rail is pinned to. */
+    getPosition(): Promise<'top' | 'bottom'>;
+    /**
+     * The rail's accessible name — it is a `role="toolbar"`, and an unnamed one is
+     * announced as nothing.
+     */
+    getRailLabel(): Promise<string | null>;
+    /** Whether nothing is minimized — the rail draws no markup at all then. */
+    isEmpty(): Promise<boolean>;
+    /**
+     * The titles in the rail, in order.
+     *
+     * A window opened without a title still gets a tab, named by the catalog's
+     * fallback rather than left blank — a nameless tab is unreachable by voice and
+     * indistinguishable from its neighbours.
+     */
+    getTabTitles(): Promise<string[]>;
+    /** A tab's accessible name — the restore wording with the window's title in it. */
+    getRestoreLabel(title: string): Promise<string | null>;
+    /** Click a tab — restoring that window and focusing it. */
+    restore(title: string): Promise<void>;
+    /**
+     * Click a tab's ✕ — closing the window WITHOUT restoring it.
+     *
+     * Still worth asserting separately now that the two are siblings rather than
+     * nested: they sit inside one pill and look like one control, so a close that
+     * also restored would flash a closing window's content and look plausible.
+     */
+    closeTab(title: string): Promise<void>;
+    /**
+     * The tab's BUTTON, not the pill around it.
+     *
+     * `.wr-window-taskbar__tab` is a plain container — it carries the pill's look
+     * and nothing else, because the close beside it cannot be a control nested in
+     * a control. The name and the click both belong to `__tab-restore`.
+     */
+    private requireTab;
+    /** Which tab carries this title — one lookup for both the tab and its close button. */
+    private indexOf;
+}
+
+export { WrWindowHarness, WrWindowTaskbarHarness };
+export type { WrWindowBox, WrWindowHarnessFilters, WrWindowTaskbarHarnessFilters };

package/types/ngwr-window.d.ts

@@ -1,8 +1,9 @@
-import * as i0 from '@angular/core';
+import * as _angular_core from '@angular/core';
 import { ComponentRef, WritableSignal, Signal, InjectionToken } from '@angular/core';
 import { OverlayRef } from '@angular/cdk/overlay';
 import { ReplaySubject, Subject } from 'rxjs';
 import { ComponentType } from '@angular/cdk/portal';
+import * as ngwr_i18n from 'ngwr/i18n';
 
 /**
  * @license
@@ -35,8 +36,10 @@ type WrWindowChromeSize = 'compact' | 'normal';
  * - `macos` — traffic-light dots on the LEFT (red close, yellow minimize,
  *   green maximize). Glyphs (×, −, +) appear when the cluster is hovered.
  * - `windows` — monochrome glyph buttons on the RIGHT.
- * - `linux` — close-only on the right; minimize / maximize hidden unless
- *   explicitly requested.
+ * - `linux` — close-only on the right, the GNOME convention. That is a DEFAULT
+ *   and not a rule: `showMinimize` / `showMaximize` set to `true` put the
+ *   buttons back, which is what a Linux user needs before a window can be
+ *   minimized into `<wr-window-taskbar>`.
  */
 type WrWindowOs = 'auto' | 'macos' | 'windows' | 'linux';
 
@@ -129,8 +132,16 @@ interface WrWindowConfig<D = unknown> {
     readonly closeOnEscape?: boolean;
     /** Snap-on-drag mode. @default 'none' */
     readonly snap?: WrWindowSnap;
+    /**
+     * Show the minimize control. Omit to follow the chrome — every OS but Linux
+     * shows it, and the Linux preset is close-only by convention. Pass `true` to
+     * override that, which is what a Linux user needs before a window can reach
+     * `<wr-window-taskbar>`.
+     */
     readonly showMinimize?: boolean;
+    /** Show the maximize control. Omit to follow the chrome, as with {@link showMinimize}. */
     readonly showMaximize?: boolean;
+    /** Show the close control. Every chrome closes, so this is not per-OS. */
     readonly showClose?: boolean;
     /** Show in `<wr-window-taskbar>` when minimized. @default true */
     readonly taskbar?: boolean;
@@ -155,6 +166,31 @@ interface WrWindowConfig<D = unknown> {
  */
 type WrWindowState = 'normal' | 'minimized' | 'maximized';
 
+/**
+ * @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
+ */
+
+/**
+ * One window as `WrWindowManager.saveLayout()` recorded it — the geometry the
+ * window really had, not the geometry it happens to be showing while maximized
+ * or minimized.
+ *
+ * Public because `readLayout()` returns an array of these; a consumer that
+ * stores or forwards that result has to be able to name the element type.
+ */
+interface WrWindowLayoutSnapshot {
+    readonly id: string;
+    readonly state: WrWindowState;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly title: string;
+}
+
 /** Hook signature for `WrWindowRef.beforeClose()`. Return falsy to veto. */
 type WrWindowBeforeCloseHook<R> = (result: R | undefined) => boolean | Promise<boolean>;
 
@@ -261,6 +297,7 @@ declare class WrWindowRef<C, R = unknown> {
     constructor(id: string, _overlayRef: OverlayRef);
     /** Resolved instance of the projected component. */
     get componentInstance(): C;
+    private isClosed;
     /**
      * Close the window, optionally returning a result. If a `beforeClose`
      * hook is registered it is consulted first — a falsy resolution
@@ -304,15 +341,6 @@ declare const WR_WINDOW_REF: InjectionToken<WrWindowRef<unknown, unknown>>;
 /** Resolves to the `data` passed in `WrWindowConfig.data`. */
 declare const WR_WINDOW_DATA: InjectionToken<unknown>;
 
-interface RestoreSnapshot {
-    readonly id: string;
-    readonly state: WrWindowState;
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-    readonly title: string;
-}
 /**
  * Owns the open `<wr-window>` stack, hands out z-indexes, cascades the
  * default spawn position, and opens programmatic windows that wrap a
@@ -377,6 +405,17 @@ declare class WrWindowManager {
      * "Settings" menu item that should always re-focus the same window).
      */
     open<C, R = unknown, D = unknown>(component: ComponentType<C>, config?: WrWindowConfig<D>): WrWindowRef<C, R>;
+    /**
+     * Whether a keyboard event routed to `ref`'s overlay is actually meant for it.
+     *
+     * The window holding real DOM focus owns the key. When focus is outside every
+     * window — the common case, since a window is not modal and traps nothing —
+     * the FRONT-most one does, by the manager's own z stack rather than by attach
+     * order. A tie (nothing has ever been focused, so no z has been handed out
+     * yet) leaves every window willing, and the dispatcher's newest-first walk
+     * settles it as before.
+     */
+    private ownsKeyboard;
     /** Close every programmatically-opened window. */
     closeAll(): void;
     /** Look up an open window by its `config.id`. Returns `null` when no match. */
@@ -395,7 +434,7 @@ declare class WrWindowManager {
      */
     saveLayout(name: string): void;
     /** Read a saved workspace. Returns `null` when no snapshot is found. */
-    readLayout(name: string): readonly RestoreSnapshot[] | null;
+    readLayout(name: string): readonly WrWindowLayoutSnapshot[] | null;
     /**
      * Apply a saved workspace.
      *
@@ -420,8 +459,8 @@ declare class WrWindowManager {
     private applyRestore;
     /** Drop a saved workspace. */
     clearLayout(name: string): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<WrWindowManager, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<WrWindowManager>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrWindowManager, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<WrWindowManager>;
 }
 
 /**
@@ -442,17 +481,23 @@ declare class WrWindowManager {
  * @see https://ngwr.dev/reference/components/window
  */
 declare class WrWindowTaskbar {
+    /** @internal */ protected readonly railLabel: _angular_core.Signal<string>;
+    /** @internal */ protected readonly closeLabel: _angular_core.Signal<string>;
+    /** @internal */ protected readonly untitled: _angular_core.Signal<string>;
+    /** @internal */ protected readonly restoreLabel: (params?: ngwr_i18n.WrI18nParams) => string;
     /** Edge the taskbar pins itself to. @default 'bottom' */
-    readonly position: i0.InputSignal<"top" | "bottom">;
+    readonly position: _angular_core.InputSignal<"top" | "bottom">;
     private readonly manager;
     /** @internal — minimized windows that haven't opted out via `taskbar: false`. */
-    protected readonly items: i0.Signal<WrWindowRef<unknown, unknown>[]>;
-    protected readonly classes: i0.Signal<string>;
+    protected readonly items: _angular_core.Signal<WrWindowRef<unknown, unknown>[]>;
+    protected readonly classes: _angular_core.Signal<string>;
+    /** A window with no title still needs a name in the rail. */
+    protected tabTitle(ref: WrWindowRef<unknown, unknown>): string;
     protected restore(ref: WrWindowRef<unknown, unknown>): void;
     protected close(ref: WrWindowRef<unknown, unknown>, event: Event): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<WrWindowTaskbar, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<WrWindowTaskbar, "wr-window-taskbar", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrWindowTaskbar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrWindowTaskbar, "wr-window-taskbar", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WR_WINDOW_DATA, WR_WINDOW_REF, WrWindowManager, WrWindowRef, WrWindowTaskbar };
-export type { WrWindowBeforeCloseHook, WrWindowChromeSize, WrWindowConfig, WrWindowOs, WrWindowPersistMode, WrWindowSize, WrWindowSnap, WrWindowState, WrWindowStorageConfig };
+export type { WrWindowBeforeCloseHook, WrWindowChromeSize, WrWindowConfig, WrWindowLayoutSnapshot, WrWindowOs, WrWindowPersistMode, WrWindowSize, WrWindowSnap, WrWindowState, WrWindowStorageConfig };

package/typography/styles/_index.scss

@@ -86,7 +86,7 @@
 
   &--code {
     padding: 0.0625rem 0.375rem;
-    background: rgba(var(--wr-color-outline-rgb), 0.6);
+    background: var(--wr-color-fill-strong);
     border-radius: var(--wr-border-radius-sm);
     font-size: 0.875em;
   }