ngwr 10.2.1 → 11.1.0

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

@@ -0,0 +1,423 @@
+import { BaseHarnessFilters, ContentContainerComponentHarness, HarnessPredicate, ComponentHarness } 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-table>` a harness query matches. */
+interface WrTableHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match a table that renders a column with this header title — the readable way
+     * to tell two tables on one page apart. A string is an exact match, a RegExp is
+     * tested.
+     */
+    readonly columnTitle?: string | RegExp;
+    /** Match only hierarchies (`true` — a `treegrid`) or only flat tables (`false`). */
+    readonly tree?: boolean;
+}
+/** Narrows which body row a harness query matches. */
+interface WrTableRowHarnessFilters extends BaseHarnessFilters {
+    /** Match a row where ANY data cell's text matches. A string is exact, a RegExp is tested. */
+    readonly cellText?: string | RegExp;
+    /** Match only selected (`true`) or only unselected (`false`) rows. */
+    readonly selected?: boolean;
+    /** Match only open (`true`) or only closed (`false`) rows — a detail row or a tree branch. */
+    readonly expanded?: boolean;
+    /**
+     * Match the row's 1-based `aria-level`, i.e. its depth in a tree. Rows of a flat
+     * table announce no level and never match.
+     */
+    readonly level?: number;
+}
+/** Narrows which data cell a harness query matches. */
+interface WrTableCellHarnessFilters extends BaseHarnessFilters {
+    /** Match the cell's text — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match the title of the column the cell sits in. */
+    readonly columnTitle?: string | RegExp;
+}
+/** Narrows which column header a harness query matches. */
+interface WrTableHeaderCellHarnessFilters extends BaseHarnessFilters {
+    /** Match the column title — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match only sortable (`true`) or only plain (`false`) columns. */
+    readonly sortable?: boolean;
+}
+
+/**
+ * @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 one data cell of a `<wr-table>` row.
+ *
+ * A CONTENT CONTAINER, because a cell is where a consumer's own components end
+ * up: a `[wrTableCell]` template can render a `<wr-tag>`, a button, an input, and
+ * `cell.getHarness(WrButtonHarness…)` resolves those INSIDE this cell — so the
+ * "Delete" button of row 3 cannot be mistaken for the one in row 1.
+ *
+ * @example
+ * ```ts
+ * const [row] = await table.getRows({ cellText: 'Ada' });
+ * const [status] = await row.getCells({ columnTitle: 'Status' });
+ *
+ * expect(await status.getText()).toBe('active');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTableCellHarness extends ContentContainerComponentHarness {
+    /**
+     * Data cells only. The lead selection and expand cells carry the same
+     * `.wr-table__td` class — they hold the row's controls, not its data — so a cell
+     * list that swept them in would no longer line up with the header list.
+     */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrTableCellHarnessFilters): HarnessPredicate<WrTableCellHarness>;
+    /** The cell's text, with the template's indentation collapsed to single spaces. */
+    getText(): Promise<string>;
+    /**
+     * The title of the column this cell belongs to.
+     *
+     * Read from `data-label` — the attribute responsive card mode prints in front of
+     * each value — because it is the only place a cell says which column it is in.
+     * The column KEY is never in the DOM at all.
+     */
+    getColumnTitle(): Promise<string | null>;
+    /** Which edge the cell's column is frozen against, or `null` when it scrolls. */
+    getPin(): Promise<'left' | 'right' | null>;
+}
+
+/**
+ * @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 one column header of a `<wr-table>`.
+ *
+ * The selector deliberately skips the two LEAD headers — selection and expand —
+ * which carry the same `.wr-table__th` class but hold a checkbox or nothing at
+ * all. What is left lines up index-for-index with the data columns, so a header's
+ * position is its column's position.
+ *
+ * Columns are addressed by their TITLE here and everywhere else in this harness
+ * family, never by their `columns` key: the key never reaches the DOM. Only the
+ * title does — in this header and in every cell's `data-label` — so it is the one
+ * handle a spec and the rendered table share.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTableHeaderCellHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrTableHeaderCellHarnessFilters): HarnessPredicate<WrTableHeaderCellHarness>;
+    /** The column title, trimmed. The sort and filter controls are not part of it. */
+    getText(): Promise<string>;
+    /**
+     * The direction this column announces, exactly as `aria-sort` puts it — or
+     * `null` when the column does not sort.
+     *
+     * `null` is not "unsorted": a sortable column with no direction announces
+     * `'none'`, and only a plain column omits the attribute entirely. Claiming
+     * sortability a column does not have is the bug that distinction prevents.
+     */
+    getSortDirection(): Promise<'ascending' | 'descending' | 'none' | null>;
+    /** Whether the column offers sorting at all. */
+    isSortable(): Promise<boolean>;
+    /**
+     * Advance the sort one step — none → ascending → descending → none, the cycle a
+     * click on the indicator drives.
+     *
+     * Throws on a column with no sort control rather than doing nothing: the quiet
+     * version of this leaves a spec asserting an unchanged direction and passing.
+     */
+    sort(): Promise<void>;
+    /** Whether the column offers a filter dropdown (its definition carries a NON-EMPTY `filterItems`). */
+    isFilterable(): Promise<boolean>;
+    /** Which edge the column is frozen against, or `null` when it scrolls with the rest. */
+    getPin(): Promise<'left' | 'right' | null>;
+}
+
+/**
+ * @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 one body row of a `<wr-table>` — flat, grouped or tree.
+ *
+ * Also a CONTENT CONTAINER, so `row.getHarness(WrButtonHarness…)` reaches the
+ * consumer's own components anywhere in the row without leaving this row.
+ *
+ * @example
+ * ```ts
+ * const [ada] = await table.getRows({ cellText: 'Ada' });
+ *
+ * await ada.select();
+ * await (await ada.getHarness(WrButtonHarness.with({ text: 'Edit' }))).click();
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTableRowHarness extends ContentContainerComponentHarness {
+    /**
+     * `.wr-table__tr` is the DATA row and nothing else.
+     *
+     * Everything else a `<tbody>` can hold is a `<tr>` too: the group band
+     * (`.wr-table__group-row`), its subtotal row, the detail row a `[wrTableExpand]`
+     * template renders, the two virtual spacers, and the "no data" row. Querying
+     * `tbody tr` would hand every one of those back as a row with no cells.
+     */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrTableRowHarnessFilters): HarnessPredicate<WrTableRowHarness>;
+    private readonly selectBox;
+    /**
+     * The row's disclosure control, whichever of the two the table gave it: the lead
+     * button of a `[wrTableExpand]` table, or the tree toggle inside the tree column.
+     * The two never coexist — a tree row owns its own disclosure, so the component
+     * refuses the pair.
+     *
+     * `button` in the tree selector is load-bearing. A leaf renders a `<span>` with
+     * the same `.wr-table__tree-toggle` class purely to hold the indent, and taking
+     * that for a control would report every leaf as expandable.
+     */
+    private readonly disclosure;
+    /** The row's data cells, in DOM order. The lead control cells are not cells. */
+    getCells(filters?: WrTableCellHarnessFilters): Promise<WrTableCellHarness[]>;
+    /** The text of every data cell, in DOM order. */
+    getCellTexts(): Promise<string[]>;
+    /**
+     * Whether the row is selected.
+     *
+     * Read from the `--selected` modifier, which is what the row looks like and what
+     * a consumer styles against. It also means a row is not "selected" while
+     * `rowSelection` is off, however many keys the `selection` model holds — nothing
+     * on screen says otherwise.
+     */
+    isSelected(): Promise<boolean>;
+    /** Whether the row offers a selection checkbox at all. */
+    isSelectable(): Promise<boolean>;
+    /** Flip the row's checkbox. Throws when the table has no selection column. */
+    toggleSelection(): Promise<void>;
+    /** Select the row if it is not already selected. */
+    select(): Promise<void>;
+    /** Deselect the row if it is selected. */
+    deselect(): Promise<void>;
+    /**
+     * Whether the row has something to open — a detail template's disclosure, or
+     * children in a tree. A tree leaf answers `false`.
+     */
+    isExpandable(): Promise<boolean>;
+    /** Whether the row is open, from the disclosure's `aria-expanded`. */
+    isExpanded(): Promise<boolean>;
+    /** Open or close the row. Throws when it has nothing to open. */
+    toggleExpand(): Promise<void>;
+    /**
+     * The row's depth as the table announces it — 1-based `aria-level`, `null` in a
+     * flat table, where depth is not a thing that exists.
+     */
+    getLevel(): Promise<number | null>;
+    /** The row's 1-based position among its siblings (`aria-posinset`), or `null` when flat. */
+    getPosInSet(): Promise<number | null>;
+    /** How many rows are in the row's sibling set, itself included (`aria-setsize`); `null` when flat. */
+    getSetSize(): Promise<number | null>;
+    /**
+     * The row's 1-based index in the FULL dataset (`aria-rowindex`, header included),
+     * or `null` when the table is not virtualized.
+     *
+     * Only a windowed table publishes it, and that is precisely when it matters: the
+     * rows in the DOM are a slice, so their DOM order says nothing about where they
+     * sit in the data.
+     */
+    getRowIndex(): Promise<number | null>;
+    private numericAttribute;
+}
+
+/**
+ * @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-table>` — the root of a small family, since a table is a
+ * tree and not one control: {@link WrTableHeaderCellHarness} for a column header,
+ * {@link WrTableRowHarness} for a body row, and `WrTableCellHarness` for a cell.
+ *
+ * Columns are addressed by their header TITLE, never by their `columns` key: the
+ * key never reaches the DOM.
+ *
+ * What this harness deliberately does NOT do:
+ * - open a column's filter dropdown. The panel is a `wr-dropdown` in the overlay
+ *   container, and driving it belongs to a dropdown harness rather than this one;
+ *   {@link WrTableHeaderCellHarness.isFilterable} reports that a column offers one.
+ * - scroll a virtualized body. See {@link getRows}.
+ *
+ * @example
+ * ```ts
+ * const table = await loader.getHarness(WrTableHarness);
+ *
+ * expect(await table.getHeaderTexts()).toEqual(['Name', 'Role']);
+ * await table.sortByColumn('Name');
+ * expect(await table.getSortDirection('Name')).toBe('ascending');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTableHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrTableHarnessFilters): HarnessPredicate<WrTableHarness>;
+    private readonly tableEl;
+    private readonly selectAllBox;
+    /**
+     * The role the table announces.
+     *
+     * A flat table sets no `role` at all, so it announces the native `table` role —
+     * NOT `grid`, which would promise cell-by-cell keyboard navigation it does not
+     * implement. `childrenKey` turns it into a `treegrid`, and that role is the only
+     * place the hierarchy exists for a screen-reader user: the indent is decoration.
+     */
+    getRole(): Promise<'treegrid' | 'table'>;
+    /** Whether the rows are a hierarchy rather than a flat list. */
+    isTree(): Promise<boolean>;
+    /**
+     * Whether the body is WINDOWED right now.
+     *
+     * Read from the host modifier rather than from the input, and that is the point:
+     * `virtualScroll` is a request, not a promise. The table falls back to rendering
+     * every row whenever the layout stops being uniform — grouping, a detail
+     * template, responsive card mode, a visible pager, a tree — so this answers what
+     * actually happened.
+     */
+    isVirtual(): Promise<boolean>;
+    /** Whether the loading spinner is covering the table. */
+    isLoading(): Promise<boolean>;
+    /** The column headers, in render order — which `columnOrder` and a drag can change. */
+    getHeaderCells(filters?: WrTableHeaderCellHarnessFilters): Promise<WrTableHeaderCellHarness[]>;
+    /**
+     * The column titles, in render order.
+     *
+     * The selection and expand headers are not columns and are not here, so this
+     * list stays as wide as every row from {@link getCellTexts}.
+     */
+    getHeaderTexts(): Promise<string[]>;
+    /** The direction a column announces via `aria-sort`, or `null` when it does not sort. */
+    getSortDirection(columnTitle: string): Promise<'ascending' | 'descending' | 'none' | null>;
+    /**
+     * Advance a column's sort one step — none → ascending → descending → none.
+     *
+     * Sorting is the host's job: `<wr-table>` publishes the intent through its `sort`
+     * model and never reorders `items` itself, so a spec that expects the rows to
+     * move has to sort the data the way the app does.
+     */
+    sortByColumn(columnTitle: string): Promise<void>;
+    /**
+     * The body rows currently rendered, in DOM order.
+     *
+     * "Currently rendered" is the whole caveat of a virtualized table: while
+     * {@link isVirtual} is true the `<tbody>` holds only the window around the scroll
+     * offset, padded by a spacer row at each end that still has rows to stand in for
+     * (one of them, at the top or the bottom of the list), so this returns the
+     * WINDOW — not the dataset.
+     * {@link getAriaRowCount} is the total the table announces and
+     * {@link WrTableRowHarness.getRowIndex} says where a row sits in it. Nothing here
+     * scrolls that window on purpose: the viewport has no layout in a unit test, so a
+     * `scrollTo` would silently do nothing. Reach for `WrTable.scrollToRow()` in a
+     * real browser, or narrow the data instead.
+     *
+     * Group bands, per-group subtotals, detail rows and the "no data" row are not
+     * rows and never appear here.
+     */
+    getRows(filters?: WrTableRowHarnessFilters): Promise<WrTableRowHarness[]>;
+    /** The whole body as a matrix of cell text — one array per row, one entry per column. */
+    getCellTexts(): Promise<string[][]>;
+    /**
+     * The `<tfoot>` summary cells, one per column and `''` for a column with no
+     * `summary`. Empty when no column defines one.
+     *
+     * The lead cells are dropped so this lines up with {@link getHeaderTexts}. A
+     * per-group subtotal row is NOT here — it lives in the body, under its band.
+     */
+    getFooterTexts(): Promise<string[]>;
+    /** The "no data" message, or `null` while the table has rows to show. */
+    getEmptyText(): Promise<string | null>;
+    /**
+     * The row count the table announces (`aria-rowcount` — header and summary row
+     * included), or `null` when it is not virtualized and every row is in the DOM.
+     */
+    getAriaRowCount(): Promise<number | null>;
+    /** Whether the header offers a select-all box — only `rowSelection="multiple"` does. */
+    hasSelectAll(): Promise<boolean>;
+    /** Whether every row in the select-all scope is selected — see {@link toggleSelectAll}. */
+    isAllSelected(): Promise<boolean>;
+    /**
+     * Whether some rows are selected and others are not — the box's third state.
+     *
+     * `indeterminate` is a DOM PROPERTY, not an attribute: reading the attribute
+     * reports `null` for a box that is visibly dashed.
+     */
+    isPartiallySelected(): Promise<boolean>;
+    /**
+     * Click the select-all box, once.
+     *
+     * Its scope is the rows the table RENDERS — the current page, and a collapsed
+     * group's rows are out because collapsing drops them from that list. A
+     * virtualized table's off-window rows are IN, though: the window is a slice
+     * taken after the list is built, so one click selects the whole dataset and not
+     * just what is in the DOM. And the third state is worth knowing about before
+     * asserting: while the selection is partial the box reads unchecked, so one
+     * click selects everything rather than clearing it.
+     */
+    toggleSelectAll(): Promise<void>;
+    /**
+     * The text of each open detail row, in row order.
+     *
+     * A detail row is a full-width `<tr>` NEXT TO the row it belongs to, not inside
+     * it — which is why it is neither one of {@link getRows} nor one of a row's
+     * cells.
+     */
+    getDetailTexts(): Promise<string[]>;
+    /**
+     * The group band labels, in order.
+     *
+     * Empty when `groupBy` is off — and also when a `[wrTableGroupHeader]` template
+     * replaced the built-in band, since the label is then the consumer's own markup.
+     * Reach for that through {@link getRows}' siblings or your own component's
+     * harness.
+     */
+    getGroupLabels(): Promise<string[]>;
+    /** Whether the band with this label is collapsed. */
+    isGroupCollapsed(label: string): Promise<boolean>;
+    /** Collapse or expand the band with this label. */
+    toggleGroup(label: string): Promise<void>;
+    /** The header for a column title, or a failure that says which titles do exist. */
+    private headerCellFor;
+    /**
+     * The collapse toggle of one band.
+     *
+     * Paired by index rather than by containment: both lists are emitted once per
+     * band by the same loop, in the same order, and a `TestElement` cannot be
+     * queried into.
+     */
+    private groupToggleFor;
+    /** The select-all input, or a failure naming both reasons it is missing. */
+    private selectAllHost;
+}
+
+export { WrTableCellHarness, WrTableHarness, WrTableHeaderCellHarness, WrTableRowHarness };
+export type { WrTableCellHarnessFilters, WrTableHarnessFilters, WrTableHeaderCellHarnessFilters, WrTableRowHarnessFilters };

package/types/ngwr-table.d.ts

@@ -438,6 +438,17 @@ declare class WrTable {
     protected readonly cellMap: _angular_core.Signal<Map<string, TemplateRef<WrTableCellContext>>>;
     private readonly platformId;
     private readonly headerCells;
+    /**
+     * Ambient reading direction, for the two header gestures that travel the
+     * inline axis: the resize drag and the CDK's drop-slot index.
+     *
+     * Optional so a bare `TestBed` — or a consumer who never set a direction —
+     * needs no provider; `Directionality` is root-provided anyway, and a missing
+     * one reads as `ltr`. Read per gesture rather than cached, so a runtime `dir`
+     * flip needs no subscription to `change`.
+     */
+    private readonly dir;
+    private isRtl;
     /**
      * Columns in render order — declaration order, overridden by `columnOrder`
      * once reordered; new keys append, removed keys drop out. Pin and resize
@@ -477,6 +488,16 @@ declare class WrTable {
     /** Freeze every column at its current rendered header width (skips frozen keys). */
     private freezeColumnWidths;
     protected onResizeStart(event: PointerEvent, key: string, th: HTMLElement): void;
+    /**
+     * Pointer travel along the INLINE axis since the drag started, in px.
+     *
+     * The grip sits on each column's inline-END edge, so a column grows as the
+     * pointer moves away from that column's start: rightward in LTR, leftward in
+     * RTL. Signed here once rather than sprinkled through the width maths — and
+     * this sign is the pair of `inset-inline-end` on `.wr-table__resize-handle`,
+     * so the two must move together.
+     */
+    private resizeDelta;
     protected onResizeMove(event: PointerEvent): void;
     protected onResizeEnd(event: PointerEvent): void;
     /** md-density fallback row height (px), used before measuring / on the server. */
@@ -519,6 +540,17 @@ declare class WrTable {
     /**
      * Keep pinned columns anchored — a drop can't land on a pinned column's slot,
      * so a scrollable column can't be dragged into the frozen region at either edge.
+     *
+     * The index the CDK hands over is a slot in the pointer sweep it does along
+     * the header, and that sweep is always left-to-right (`SingleAxisSortStrategy`
+     * caches item rects sorted by `clientRect.left`). `displayColumns()` is DOM
+     * order, which under `dir="rtl"` runs the other way — so without the mirror
+     * the guard is asked about the column at the opposite end of the header, and
+     * a drop lands on the pinned one it was meant to protect.
+     *
+     * The drop event itself needs no such mapping: `previousIndex` /
+     * `currentIndex` come from `getItemIndex`, which the CDK already un-mirrors
+     * back to DOM order.
      */
     protected readonly sortPredicate: (index: number) => boolean;
     private rowKeyOf;
@@ -760,6 +792,16 @@ declare class WrTableFilter {
     protected readonly query: _angular_core.WritableSignal<string>;
     /** Filtered + selection-tracked view of items. */
     protected readonly visible: _angular_core.Signal<WrTableFilterItem<unknown>[]>;
+    /**
+     * Bumped on every selection change.
+     *
+     * `items` belongs to the CONSUMER — the column definition hands the same array
+     * back on every render — and this component flips `selected` on those objects in
+     * place. No signal sees a property mutation, so `selectedCount` memoised its
+     * first answer: the count badge never appeared and the `--active` class never
+     * arrived, however many boxes were ticked.
+     */
+    private readonly selectionVersion;
     protected readonly selectedCount: _angular_core.Signal<number>;
     protected readonly classes: _angular_core.Signal<string>;
     protected onSearchInput(event: Event): void;