@ex-grid/core 0.2.0-beta.3 → 0.2.0-rc.1

package/dist/index.d.ts

@@ -787,6 +787,8 @@ export declare class FetchingGridSource<Row> implements GridSource<Row> {
     #private;
     /** A Find step through the Consumer's server (ADR-0055); absent when it was given no `find`. */
     readonly find?: (request: GridFindRequest, signal: AbortSignal) => Promise<GridFindResult>;
+    /** A page of a Find All through the Consumer's server (ADR-0470); absent when it was given no `findAll`. */
+    readonly findAll?: (request: GridFindAllRequest, signal: AbortSignal) => Promise<GridFindAllPage>;
     /** A Selection Summary through the Consumer's server (ADR-0130); absent when it was given no
      * `summarize`. */
     readonly summarize?: (request: GridSummaryRequest, signal: AbortSignal) => Promise<GridSummaryResult>;
@@ -958,6 +960,9 @@ export declare interface FetchingSourceOptions<Row> {
     /** A Find step (ADR-0055), answered under the Sort and the Filter in force; `findStep` is the reference
      * for what a match is. Without it the source does not find. */
     readonly find?: (request: GridFindRequest, query: QueryInForce, signal: AbortSignal) => Promise<GridFindResult>;
+    /** A page of a Find All (ADR-0470), answered under the Sort and the Filter in force with the exact count; `findAll`
+     * is the reference for the list and its order. Offered only beside `find`: without both the source lists nothing. */
+    readonly findAll?: (request: GridFindAllRequest, query: QueryInForce, signal: AbortSignal) => Promise<GridFindAllPage>;
     /** A Selection Summary (ADR-0130), answered under the Sort and the Filter in force as `summaryOf` would
      * over that result, or declined. Without it the source does not summarise. */
     readonly summarize?: (request: GridSummaryRequest, query: QueryInForce, signal: AbortSignal) => Promise<GridSummaryResult>;
@@ -1158,6 +1163,38 @@ export declare interface FilterSpec {
  * form where the source answers TooMany; or both, which the built-in panel shows as the value list. */
 export declare type FilterUi = 'condition' | 'valueList' | 'both';
 
+/**
+ * One page of the reference Find All over `rows` (ADR-0470 §2), read under `rowSequenceVersion`: the whole list walked
+ * and the range asked read from it. A source that answers many pages of one list keeps a {@link FindAllMatches}
+ * instead, as `GridSource.from` does.
+ */
+export declare function findAll<Row>(rows: readonly Row[], rowSequenceVersion: number, request: GridFindAllRequest, textOf: (column: string) => ((row: Row) => string) | undefined): GridFindAllPage;
+
+/**
+ * Every match of a Find All over one set of rows, found once and read a page at a time: the reference source keeps
+ * one while the rows, the pattern, the scope and the columns stand, so a list scrolled through is walked once. Each
+ * match is held as its cell's ordinal in row-major order, a number for millions of matches rather than an object.
+ */
+export declare class FindAllMatches<Row> {
+    #private;
+    private constructor();
+    /**
+     * Walks `rows` once (ADR-0470 §2), by rows and across a row in the request's column order. `textOf` answers a
+     * column's displayed text by name, or `undefined` for a column with no text to search or one not known, which is
+     * skipped, as a step skips it. An empty pattern matches nothing. `rowLabel`, where given, names each match's row in
+     * the Consumer's words.
+     */
+    static of<Row>(rows: readonly Row[], request: Omit<GridFindAllRequest, 'start' | 'count' | 'rowSequenceVersion'>, textOf: (column: string) => ((row: Row) => string) | undefined, rowLabel?: (row: Row) => string): FindAllMatches<Row>;
+    /** How many cells match. */
+    get total(): number;
+    /** The entries from `start`, `count` of them or every one left, under `rowSequenceVersion`. A range past the end
+     * holds none; a range outside the list's positions is refused. */
+    page(start: number, count: number, rowSequenceVersion: number): GridFindAllPage;
+}
+
+/** A page of a Find All's list, frozen and checked: `matches` at most as many as the range asked. */
+export declare function findAllPage(total: number, matches: readonly GridFindAllMatch[], rowSequenceVersion: number): GridFindAllPage;
+
 /**
  * The reference rule for one cell (ADR-0055, ADR-0332 §4): whether `displayedText`, the column's format
  * applied, matches `pattern`. The step finds by it, and the grid marks the painted matches by it. An empty
@@ -1249,6 +1286,22 @@ export declare const findPanelLabelIds: Readonly<{
     readonly replaceRefusedMore: 'find-replace-refused-more';
     /** Why a match in a column that is not Editable cannot be written. */
     readonly notEditable: 'find-not-editable';
+    /** The Find All button (ADR-0470 §1). */
+    readonly findAll: 'find-all';
+    /** The list of a Find All's matches: its accessible name. */
+    readonly findAllList: 'find-all-list';
+    /** What a Find All that matched several cells says, their count at `{count}`. */
+    readonly findAllFound: 'find-all-found';
+    /** What a Find All that matched one cell says. */
+    readonly findAllFoundOne: 'find-all-found-one';
+    /** What a Find All that matched nothing says. */
+    readonly findAllNone: 'find-all-none';
+    /** Where a match in a row is, its row's number from 1 at `{row}` and its column's header at `{column}`. */
+    readonly findAllInRow: 'find-all-in-row';
+    /** Where a match in a row is, by the Consumer's label for the row at `{row}` and its column's header at `{column}`. */
+    readonly findAllInLabelledRow: 'find-all-in-labelled-row';
+    /** Where a match in a header is, the header's text at `{column}`. */
+    readonly findAllInHeader: 'find-all-in-header';
 }>;
 
 /** One cell a Replace could not write, as the panel names it: its row's number from 1, its column's header,
@@ -1281,6 +1334,10 @@ export declare interface FindPanelView {
     /** What the last step or Replace came to, in the grid's words, for a live region; empty when it says nothing
      * (ADR-0033). */
     readonly outcome: string;
+    /** Whether the panel offers Find All (ADR-0470 §1): the source lists every match. While it does, the contents draw
+     * a Find All button that calls {@link GridFindPanelSlotContext.findAll}; the list and its count are the core's, drawn
+     * under the contents (ADR-0470 §3). */
+    readonly findAllShown: boolean;
 }
 
 /**
@@ -2095,6 +2152,78 @@ export declare interface GridFilterPanelSlotContext {
     }) => void;
 }
 
+/** One line of a Find All's list: where the match is, and the text it displays. */
+export declare interface GridFindAllLine {
+    /** Where the match is, in the grid's words: "Row 12, Trader", "Header Trader", "Sheet2!B12". */
+    readonly where: string;
+    /** The matched cell's displayed text. */
+    readonly text: string;
+}
+
+/**
+ * A Find All list a find panel slot's contents hold themselves (ADR-0470 §7), handed to the core to draw as it draws
+ * its own: ExSheet's over every Sheet of its Workbook. The contents answer how many lines it holds, each line, and
+ * what choosing one does; the core draws the count and the lines, takes the list's keys and clicks in their place in
+ * the Input Order, and takes the list away when the text or an option changes or the panel closes.
+ */
+export declare interface GridFindAllList {
+    /** How many lines the list holds: every match, never capped. */
+    readonly count: number;
+    /** Line `index`, from 0 to `count` − 1. */
+    readonly line: (index: number) => GridFindAllLine;
+    /** The user chose line `index`, in its turn: the contents move to it, as a step that found it would, and answer
+     * whether they did; a choice they refuse (ExSheet's, while a cell is edited) leaves the list's current line as it
+     * was. */
+    readonly choose: (index: number) => boolean;
+}
+
+/** One cell of a Find All's list: where it is, and the text it displays, which is what matched. */
+export declare interface GridFindAllMatch {
+    /** The row's position in the order the request was read in. */
+    readonly row: number;
+    /** The column's name, one of the request's `columns`. */
+    readonly column: string;
+    /** The cell's displayed text, as the user reads it. */
+    readonly text: string;
+    /** What the list calls the row, in the Consumer's words (a trade's id, say), in place of its position; absent,
+     * the list names it by its position in the order shown (ADR-0470 §3). */
+    readonly rowLabel?: string | undefined;
+}
+
+/**
+ * The Consumer's answer to a Find All (ADR-0470 §2): the entries of the range asked and the exact count of the whole
+ * list, which is never an estimate and never capped, read under one Row Sequence Version.
+ */
+export declare interface GridFindAllPage {
+    /** How many cells match, exactly, over every row in the scope. */
+    readonly total: number;
+    /** The entries from the request's `start`, in walk order: `count` of them, or every one left past `start`. */
+    readonly matches: readonly GridFindAllMatch[];
+    /** The order the rows were read in. Under another than the request's, the grid drops the list as the order
+     * having moved. */
+    readonly rowSequenceVersion: number;
+}
+
+/**
+ * A Find All (ADR-0470 §2): what a Find step would look for, over every row, and the range of the list the grid wants
+ * now. The grid asks for the range it shows, a page at a time, under the Row Sequence Version it read the positions
+ * in; the Consumer answers that range and the exact count of the whole list.
+ */
+export declare interface GridFindAllRequest extends GridFindPattern {
+    /** The selected ranges, when more than one cell is selected, as a Find step's. Absent: every row. */
+    readonly scope?: readonly SelectionRange[] | undefined;
+    /** The visible columns' names in the grid's current order: position `i` here is column `i` of every position in
+     * this request and its answer. */
+    readonly columns: readonly string[];
+    /** The order the positions above were read in (ADR-0011). An answer under another version is discarded, and the
+     * list with it. */
+    readonly rowSequenceVersion: number;
+    /** The first entry of the list wanted, counted from 0 in walk order. */
+    readonly start: number;
+    /** How many entries are wanted from `start`: the answer holds this many, or every one left past `start`. */
+    readonly count: number;
+}
+
 /**
  * What the find panel's contents are handed (ADR-0055, ADR-0332): what the panel shows and the changes and steps the
  * user makes in it. The core owns the search, the request, the answer and the Focus it moves; the contents draw a
@@ -2130,6 +2259,16 @@ export declare interface GridFindPanelSlotContext {
     readonly replace: () => void;
     /** Replace All, asked of the Consumer. Nothing while Replace is not shown or a Replace All is out. */
     readonly replaceAll: () => void;
+    /** Find All, its list asked of the Consumer and drawn by the core under the contents (ADR-0470). Nothing while Find
+     * All is not offered. */
+    readonly findAll: () => void;
+    /** Find All, its list the contents' own (ADR-0470 §7), as ExSheet's over its Workbook: `list` is asked in the
+     * call's turn among the inputs, and the core draws what it answers under the contents as it draws its own list.
+     * Nothing while the find field is empty. */
+    readonly listFindAll: (list: () => GridFindAllList) => void;
+    /** An option of the contents' own changed what a search means (ADR-0470 §5), as ExSheet's Within does: the list
+     * standing goes, as it goes when the text or one of the core's options changes. */
+    readonly dropFindAll: () => void;
     /** Closes the panel as a Cancel, for a dismissal of the contents' own; the keyboard returns to the grid. */
     readonly close: () => void;
     /** The count of the core's requests for the find field to take the keyboard: the opening, Ctrl+F or Ctrl+H again,
@@ -2539,6 +2678,12 @@ export declare class GridMetrics {
     get nameBoxWidthPx(): number;
     /** The fill handle's side (ADR-0050, item 5): a little under a third of a row, and at least 5px. */
     get fillHandleSizePx(): number;
+    /** The side of a Reference Outline's corner square (ADR-0480): 5px, as Excel draws it, in the Reference's colour
+     * with a 1px margin of the ground, centred on the outline's corner. */
+    get referenceHandleSizePx(): number;
+    /** How wide the strip along a Reference Outline's line is that a press grabs it by (ADR-0480): 5px, centred on
+     * the line, wider than the line so that it can be pressed. */
+    get referenceGripPx(): number;
     /** A cell's horizontal padding on one side; a cell pays it twice. */
     get cellPaddingXPx(): number;
     /** The width of one digit: the unit `####` is counted in (ADR-0016). */
@@ -2696,6 +2841,11 @@ export declare interface GridOptions<Row> extends CellPaintOptions<Row>, Formula
     /** A band across the Focus's row, beneath the Selection's tints (ADR-0008), filled with
      * `--ex-focus-row-fill`. Off unless given. */
     readonly highlightFocusRow?: boolean;
+    /** A band down the Focus's column, beneath the Selection's tints (ADR-0008, 2026-11-03), filled with
+     * `--ex-focus-column-fill`, which is `--ex-focus-row-fill` unless set. It covers the column's cells and not its
+     * header, and with `highlightFocusRow` as well the two cross as Excel's Focus Cell does, the Focus's cell tinted
+     * once. Off unless given. */
+    readonly highlightFocusColumn?: boolean;
     /** A band across the row under the pointer, what every design system's table calls Hover (ADR-0029),
      * filled with `--ex-row-hover-background`. It is the overlay's, so no row learns anything and none is
      * painted again; it goes when the pointer leaves the grid or the rows move under it. Off unless given,
@@ -3018,6 +3168,16 @@ export declare interface GridOptions<Row> extends CellPaintOptions<Row>, Formula
      * earlier. None, and nothing is outlined.
      */
     readonly outlinedColumns?: readonly GridOutlinedColumn[];
+    /**
+     * The text a Reference is rewritten to when its Reference Outline is dragged (ADR-0480): `reference` as it stands
+     * in the editor's text, and the cells it is to name, answered as the Reference naming them written as `reference`
+     * was (`$A$1` moved two columns is `$C$1`). Declared beside `referencesIn`, every outline over this grid's cells
+     * carries grips while an edit is open: its edges, which move the Reference keeping its size, and a square at each
+     * corner, which resizes it from the opposite corner. The text is rewritten each time the range reached changes;
+     * the caret stays where it was, and Escape mid-drag puts the Reference back. A non-string or empty answer is
+     * refused by name. None, and no outline carries a grip.
+     */
+    readonly moveReference?: (reference: string, range: SelectionRange) => string;
     /**
      * Whether, in this text with the caret here, a Reference can go at the caret (ADR-0051): after `=`, an operator,
      * `(` or `,` in a Formula. Asked synchronously on the editor's text and caret as each key or press finds them,
@@ -3712,6 +3872,9 @@ export declare interface GridSource<Row> {
      * this member, and otherwise refuses Find as unavailable. `findStep` is the reference for what a match
      * is. */
     find?(request: GridFindRequest, signal: AbortSignal): Promise<GridFindResult>;
+    /** Answers a page of a Find All (ADR-0470), where this source lists every match: the grid offers Find All only
+     * for a source that has this member beside `find`. `findAll` is the reference for the list and its order. */
+    findAll?(request: GridFindAllRequest, signal: AbortSignal): Promise<GridFindAllPage>;
     /** Answers a Selection Summary (ADR-0130), where this source summarises: the grid asks only a source
      * that has this member, and otherwise shows no figure. `summaryOf` is the reference for what each
      * figure is. */
@@ -4155,6 +4318,13 @@ export declare class InMemoryGridSource<Row> implements GridSource<Row> {
      * discards it by the version, which is the one place that knows.
      */
     find(request: GridFindRequest, signal: AbortSignal): Promise<GridFindResult>;
+    /**
+     * The reference Find All (ADR-0470): `findAll` over the current result, matching each column's displayed text as
+     * `find` does. The matches are found once for a question and read a page at a time while the result stands. A
+     * request read under another version is answered anyway, under this source's: the grid discards it by the
+     * version.
+     */
+    findAll(request: GridFindAllRequest, signal: AbortSignal): Promise<GridFindAllPage>;
     /**
      * The reference Selection Summary (ADR-0130): `summaryOf` over the current result, reading each column's
      * value. A column this source was not told about, or one with no value of its own, is blank. It never
@@ -4222,6 +4392,8 @@ export declare interface InMemorySourceOptions<Row> {
     readonly rowKey?: RowKeyOf<Row>;
     /** The clock live changes are gathered by; the browser's unless given. Read only under a Row Key. */
     readonly clock?: GridClock;
+    /** What a Find All's list calls a row, in place of its position (ADR-0470 §3): a trade's id, say. */
+    readonly findAllRowLabel?: (row: Row) => string;
 }
 
 /** A clock's ticks at an offset of `offsetMinutes` from UTC as the Temporal `Instant` they name, read through its