ngwr 11.0.0 → 11.2.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;
@@ -420,8 +431,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,16 +453,22 @@ 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 };

package/window/styles/_index.scss

@@ -197,8 +197,9 @@
 
   // OS preset: Linux (GNOME-style) — chrome-action retains the windows
   //                   look but the chrome bar is slightly taller and the
-  //                   title stays left-aligned (close-only is enforced by
-  //                   the template).
+  //                   title stays left-aligned. Close-only is the template's
+  //                   DEFAULT here, not a rule: `[showMinimize]="true"` puts
+  //                   the button back.
   &--os-linux {
     .wr-window__chrome {
       height: 2.5rem;
@@ -384,30 +385,45 @@
     pointer-events: auto;
   }
 
+  // The pill, which is now a container rather than the button itself — the
+  // close beside it has to be a sibling, not a control nested in a control.
+  // The class stays: consumers style against it, and it still names the pill.
   &__tab {
-    appearance: none;
-    background: transparent;
-    border: 0;
     display: inline-flex;
     align-items: center;
-    gap: 0.375rem;
-    padding-block: 0.25rem;
-    // Roomy where the title starts, tight against the trailing close button.
-    padding-inline: 0.75rem 0.5rem;
+    gap: 0.125rem;
+    // Roomy where the title starts, tight against the trailing close button,
+    // which now carries its own padding to reach a 24px target.
+    padding-inline: 0.75rem 0.125rem;
     border-radius: var(--wr-border-radius-sm);
     color: var(--wr-color-on-surface);
-    font-family: inherit;
     font-size: var(--wr-text-sm);
     line-height: 1.25rem;
-    cursor: pointer;
     max-width: 12rem;
-    transition:
-      background var(--wr-transition-base),
-      color var(--wr-transition-base);
+    transition: background var(--wr-transition-base);
 
     &:hover {
       background: rgba(var(--wr-color-outline-rgb), 0.6);
     }
+  }
+
+  &__tab-restore {
+    appearance: none;
+    background: transparent;
+    border: 0;
+    padding-block: 0.25rem;
+    padding-inline: 0;
+    flex: 1 1 auto;
+    min-width: 0;
+    display: inline-flex;
+    align-items: center;
+    border-radius: var(--wr-border-radius-sm);
+    color: inherit;
+    font-family: inherit;
+    font-size: inherit;
+    line-height: inherit;
+    cursor: pointer;
+    text-align: start;
 
     &:focus-visible {
       @include theme.focus-ring;
@@ -424,9 +440,16 @@
   }
 
   &__tab-close {
+    appearance: none;
+    border: 0;
+    background: transparent;
     flex: 0 0 auto;
-    width: 1rem;
-    height: 1rem;
+    // 24px, which is what WCAG 2.5.8 asks of a pointer target. The glyph is
+    // still 9px and the pill is 28px tall, so the box grows into padding that
+    // was already there rather than changing the taskbar's height.
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -438,6 +461,11 @@
       color: var(--wr-color-surface);
       background: var(--wr-color-danger);
     }
+
+    &:focus-visible {
+      @include theme.focus-ring;
+      outline-offset: -2px;
+    }
   }
 }