@evotecit/canopyx 0.1.2 → 0.2.0

package/JavaScript/editing.d.ts

@@ -0,0 +1,257 @@
+// Editing of flat grids (docs/editing.md): typed editors, validation, the change set, row and batch commit, undo and redo.
+import type { CellValue, Cell, TimeZone } from "./protocol.js";
+import type { GridRow, GridQuery, AcceptedGridQuery } from "./grid.js";
+
+/** A built-in editor type, or the name of an editor a plugin or the host registers. */
+export type GridEditorType = "text" | "number" | "date" | "datetime" | "time" | "select" | "toggle" | "lookup" | (string & {});
+
+/** A select choice or a fixed lookup suggestion: a raw value, or a value with the label readers see. */
+export type GridEditorOption = string | number | boolean | { value: string | number | boolean; label?: string };
+
+/** The editor of an editable column; a name alone is shorthand for { type }. */
+export type GridEditorDefinition = GridEditorType | {
+  type: GridEditorType;
+  /** Number editors: the smallest value, also the start of step. */
+  min?: number;
+  /** Number editors: the largest value. */
+  max?: number;
+  /** Number editors: Up and Down move by it; values keep its multiple. */
+  step?: number;
+  placeholder?: string;
+  /** Select choices, or a lookup's fixed suggestions (at most 1000). */
+  options?: readonly GridEditorOption[];
+  /** Lookups: the column whose values it suggests through the data source (default the edited column), how many (1..50, default 20) and after how many characters (0..16, default 1). */
+  lookup?: { column?: string; limit?: number; minLength?: number };
+};
+
+/** Checks an edited value must pass before its row commits; the messages are the gridEdit… labels unless message replaces them. */
+export interface GridValidation {
+  required?: boolean;
+  /** A number, or an ISO 8601 moment with its time zone for date-and-time columns. */
+  min?: number | string;
+  max?: number | string;
+  minLength?: number;
+  maxLength?: number;
+  /** A regular expression the whole text must match. */
+  pattern?: string;
+  message?: string;
+}
+
+/** The view document's editing settings; the editing option overrides them. */
+export interface GridEditingSettings {
+  /** The whole grid is read-only until setReadOnly(false). */
+  readOnly?: boolean;
+  /** One cell at a time (default), or every editable cell of a row. */
+  mode?: "cell" | "row";
+  /** When the record drawer becomes an edit form (default "phone"). */
+  drawer?: "phone" | "always" | "never";
+  /** The toolbar shows unsaved changes with Undo, Redo, Discard and Save (default true). */
+  editBar?: boolean;
+}
+
+/** What an editor's create function receives. Frozen. */
+export interface CanopyEditorContext {
+  /** A unique id prefix for elements the editor creates. */
+  readonly id: string;
+  /** The cell's raw value when editing starts. */
+  readonly value: CellValue;
+  /** The cell's display text. */
+  readonly text: string;
+  /** A frozen copy of the record. */
+  readonly row: Readonly<GridRow>;
+  readonly column: Readonly<{ id: string; title: string; kind: "text" | "number" | "datetime" }>;
+  /** The column's editor definition, with its type. */
+  readonly editor: Readonly<Exclude<GridEditorDefinition, string>>;
+  readonly options: readonly Readonly<{ value: string | number | boolean; label: string }>[] | null;
+  readonly rules: Readonly<GridValidation & { step?: number }>;
+  readonly labels: Readonly<Record<string, string>>;
+  /** The page language, for parsing and formatting. */
+  readonly locale: string | undefined;
+  /** The grid's time zone: dates are shown and entered in it. */
+  readonly timeZone: TimeZone;
+  /** Where the editor is: a cell, a row in full-row mode, or the drawer's edit form. */
+  readonly mode: "cell" | "row" | "form";
+  /** The character the reader typed to start editing ("" for Backspace or Delete), when there is one. */
+  readonly initial: string | undefined;
+  /** Aborts when the editor closes. */
+  readonly signal: AbortSignal;
+  readonly lookupMinLength: number;
+  /** Applies the editor's value and closes it. */
+  commit(): void;
+  /** Closes the editor without applying. */
+  cancel(): void;
+  /** Searches the column's suggestions as a lookup does. */
+  lookup(search: string, signal: AbortSignal): Promise<readonly { value: string | number | boolean; label: string }[]>;
+  /** Remembers a chosen suggestion, so the cell shows its label. */
+  remember(option: { value: string | number | boolean; label: string }): void;
+}
+
+/** An editor instance. getValue returns the raw cell value; error returns a message while the input is not a value yet. */
+export interface CanopyEditorInstance {
+  /** What goes into the cell (or the form field). */
+  readonly element: HTMLElement;
+  /** The focusable control, when it is not element itself; it gets the accessible name and the invalid state. */
+  readonly control?: HTMLElement;
+  getValue(): CellValue;
+  focus?(): void;
+  error?(): string | null;
+  destroy?(): void;
+}
+
+/** A typed cell editor a plugin (editors) or the host (editing.editors) registers under a name. */
+export interface CanopyCellEditor {
+  create(context: CanopyEditorContext): CanopyEditorInstance;
+}
+
+/** A row's change: the new values and the values the row started from; a new row (op "insert") has no original. */
+export type GridChange = GridUpdateChange | GridInsertChange;
+/** A change of a stored row. */
+export interface GridUpdateChange extends GridChangeState {
+  readonly op?: "update";
+  readonly original: Readonly<Record<string, CellValue>>;
+}
+/** A new row from insertRow: every value, no original. */
+export interface GridInsertChange extends GridChangeState {
+  readonly op: "insert";
+}
+/** What every change carries. */
+export interface GridChangeState {
+  readonly id: string;
+  readonly values: Readonly<Record<string, CellValue>>;
+  /** Messages by column of the failed checks. */
+  readonly errors?: Readonly<Record<string, string>>;
+  /** The row's own message: a row check or a failed save. */
+  readonly error?: string;
+  readonly status?: "saving" | "error" | "conflict";
+}
+
+/** What a writer answers for one row of a gridCommit. */
+export interface GridCommitRowResult {
+  status: "saved" | "error" | "conflict";
+  /** Saved rows: canonical cells that replace the shown ones. */
+  cells?: Record<string, Cell>;
+  /** A saved insert: the identity the writer stored the new row under (the client id new-<n> is replaced). */
+  newId?: string;
+  error?: string;
+  errors?: Record<string, string>;
+}
+
+/** Changed rows a grid asks its writer to save (docs/data-protocol.md#editing-and-commit). */
+export interface GridCommit {
+  readonly protocol: "canopyx/2";
+  readonly type: "gridCommit";
+  readonly view: string;
+  /** The dataset revision the grid read, or null. */
+  readonly revision: string | null;
+  /** Updates carry the original values; inserts (op "insert", a client id new-<n> or the host's) carry every value and no original. */
+  readonly rows: readonly ({ readonly op?: "update"; readonly id: string; readonly values: Readonly<Record<string, CellValue>>; readonly original: Readonly<Record<string, CellValue>> }
+    | { readonly op: "insert"; readonly id: string; readonly values: Readonly<Record<string, CellValue>> })[];
+}
+
+/** A writer's answer to gridCommit. A row it leaves out was not saved; revision is the dataset revision after the commit. */
+export interface GridCommitResult {
+  protocol: "canopyx/2";
+  type: "gridCommitResult";
+  view: string;
+  revision?: string;
+  rows: (GridCommitRowResult & { id: string })[];
+}
+
+/** The result of one row of a commit. */
+export interface GridRowCommitOutcome {
+  readonly id: string;
+  readonly ok: boolean;
+  readonly status: "saved" | "pending" | "unchanged" | "invalid" | "cancelled" | "error" | "conflict" | "superseded";
+  readonly error?: string | null;
+  readonly errors?: Readonly<Record<string, string>>;
+}
+
+/** What commitChanges resolves with. */
+export interface GridCommitOutcome {
+  readonly ok: boolean;
+  readonly saved: number;
+  readonly failed: number;
+  readonly rows: readonly GridRowCommitOutcome[];
+  /** The revision the writer answered with; the grid keeps reading pages at the one it accepted until it reloads. */
+  readonly revision?: string;
+}
+
+/** cellValueChanging (cancelable) and cellValueChanged. */
+export interface GridCellValueChange {
+  readonly id: string;
+  readonly column: string;
+  readonly value: CellValue;
+  readonly previous: CellValue;
+  readonly row: Readonly<GridRow>;
+  /** paste and fill come from the cell range part (docs/cell-ranges.md): pasted cells and the fill handle go through editing. */
+  readonly source: "edit" | "form" | "api" | "undo" | "redo" | "revert" | "paste" | "fill" | "calendar" | "accept";
+}
+
+/** canopyx:rowCommit and onRowCommit: a row whose edits are complete and valid (a new row: op "insert" and no original). */
+export interface GridRowCommit {
+  readonly id: string;
+  readonly op?: "update" | "insert";
+  readonly values: Readonly<Record<string, CellValue>>;
+  readonly original?: Readonly<Record<string, CellValue>>;
+  readonly row: Readonly<GridRow>;
+  readonly revision: string | null;
+  /** Answers for the row from an event listener: a result, true for saved, or a promise of one. */
+  respondWith(result: GridCommitRowResult | true | PromiseLike<GridCommitRowResult | true>): void;
+}
+
+/** A lookup search the host answers itself. */
+export interface GridLookupRequest {
+  readonly column: string;
+  readonly search: string;
+  readonly limit: number;
+  readonly row: Readonly<GridRow>;
+  readonly signal: AbortSignal;
+}
+
+/** The host's editing option. */
+export interface GridEditingOptions<Q extends AcceptedGridQuery = GridQuery> extends GridEditingSettings {
+  /** Per-row read-only rule; runs synchronously for every cell it is asked about. */
+  isEditable?(row: Readonly<GridRow>, column: string): boolean;
+  /** Per-column checks: a message, null, or a promise of one. */
+  validators?: Readonly<Record<string, (value: CellValue, row: Readonly<GridRow>) => string | null | undefined | PromiseLike<string | null | undefined>>>;
+  /** A row check before it commits: a row message, messages by column, null, or a promise of them. */
+  validateRow?(row: Readonly<GridRow>, change: GridChange): string | Record<string, string> | null | undefined | PromiseLike<string | Record<string, string> | null | undefined>;
+  /** Lookup suggestions by column, in place of the editor's options and the data source. */
+  lookups?: Readonly<Record<string, (request: GridLookupRequest) => readonly GridEditorOption[] | PromiseLike<readonly GridEditorOption[]>>>;
+  /** The text edited cells of a column show, by column: the same formatter the host's source text comes from, so every cell of the column reads alike. Without one, edited cells use the column's default formatting (or a choice's label). */
+  formatters?: Readonly<Record<string, (value: Exclude<CellValue, null>, row: Readonly<GridRow>) => string>>;
+  /** Editors for this grid, beside the built-in ones and the plugins'. */
+  editors?: Readonly<Record<string, CanopyCellEditor>>;
+  /** The batch writer; wins over the source's commit. */
+  commit?(batch: GridCommit, options: { signal: AbortSignal }): GridCommitResult | PromiseLike<GridCommitResult>;
+  /** Undo steps kept (0..10000, default 100). */
+  undoLimit?: number;
+}
+
+/** The editing members of a flat grid's API. */
+export interface GridEditingApi {
+  /** Opens the editor of a loaded record's cell (the first editable visible cell without column); false when it cannot. */
+  beginEdit(id: string, column?: string, options?: { initial?: string }): Promise<boolean>;
+  /** Applies the open editors; false while a value fails a check. */
+  endEdit(): Promise<boolean>;
+  cancelEdit(): void;
+  isEditing(): boolean;
+  /** A host's change with the same events, history and checks as an edit; read-only rules do not apply. */
+  setCellValue(id: string, column: string, value: CellValue): Promise<{ applied: boolean; valid: boolean; error?: string }>;
+  /** Adds a new record (id: new-<n>, or the host's, which starts with new- too) as an insert in the change set: validated, undoable, committed as op "insert". */
+  insertRow(input: { id?: string; cells: Readonly<Record<string, Cell>> }): Promise<{ id: string; applied: boolean; valid: boolean; errors?: Record<string, string> }>;
+  getChanges(): GridChange[];
+  hasChanges(): boolean;
+  /** Puts rows (all by default) back to their starting values, as one undoable step. */
+  revertChanges(ids?: readonly string[]): void;
+  validate(ids?: readonly string[]): Promise<{ valid: boolean; rows: { id: string; valid: boolean; errors: Record<string, string>; error?: string | null }[] }>;
+  /** Checks a row and raises rowCommit; resolves with what the handler answered. */
+  commitRow(id: string): Promise<GridRowCommitOutcome>;
+  /** Sends every valid changed row (or the ids) to the writer in one gridCommit. */
+  commitChanges(options?: { ids?: readonly string[]; signal?: AbortSignal }): Promise<GridCommitOutcome>;
+  undo(): boolean;
+  redo(): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  setReadOnly(readOnly: boolean): void;
+}

package/JavaScript/enhance.d.ts

@@ -0,0 +1,202 @@
+// Progressive enhancement of an existing table and simple init from data or a URL (docs/enhance.md).
+import type { CanopyLabels } from "./protocol.js";
+import type { DataGrid, GridColumn, GridHostOptions, GridPageLengthChoice, GridPaging, GridQuery, GridState, GridView } from "./grid.js";
+
+/** What a column render is called for: the text shown, the sort value, the search value, and the value whose type sets the column kind. */
+export type GridRenderPurpose = "display" | "sort" | "filter" | "type";
+
+/** Where a render call happens: the record's position in the data, the column's position, and the column id. */
+export interface GridRenderMeta {
+  readonly row: number;
+  readonly column: number;
+  readonly id: string;
+}
+
+/** A column render: receives the column's field value, the purpose, the whole record and the position. */
+export type GridRenderFunction<R = any> = (data: any, purpose: GridRenderPurpose, record: R, meta: GridRenderMeta) => unknown;
+
+/** A render function, or per purpose a function or a field path of the record; "_" is the fallback for purposes not named. */
+export type GridRender<R = any> = GridRenderFunction<R> | {
+  readonly display?: GridRenderFunction<R> | string;
+  readonly sort?: GridRenderFunction<R> | string;
+  readonly filter?: GridRenderFunction<R> | string;
+  readonly type?: GridRenderFunction<R> | string;
+  readonly _?: GridRenderFunction<R> | string;
+};
+
+/**
+ * A column of CanopyX.enhance or CanopyX.grid: the grid column fields, plus where its values come from and how they read.
+ * For a table, the options at a header cell's index merge over that cell's data-* attributes.
+ */
+export interface GridColumnOptions<R = any> extends Partial<Omit<GridColumn, "id" | "title" | "kind" | "hidden">> {
+  /** The column id; defaults to the field name, or c0, c1, ... for positions. */
+  id?: string;
+  /** The header text; defaults to the table header or the field name. */
+  title?: string;
+  /** A field name, a dotted path ("owner.name") or an array position; defaults to the column's position. */
+  data?: string | number;
+  /** The value kind; auto (the default) reads it from the values: numbers, ISO dates, else text. date is datetime. */
+  type?: "text" | "number" | "datetime" | "date" | "auto";
+  /** The same as type, in the grid column's own name. */
+  kind?: "text" | "number" | "datetime";
+  /** Display, sort, search and type values computed from the record. */
+  render?: GridRender<R>;
+  /** False leaves the column out of the search box. Default true. */
+  searchable?: boolean;
+  /** False hides the column at first; readers can show it from the Columns menu. Default true. */
+  visible?: boolean;
+  hidden?: boolean;
+  /** Text an empty cell shows instead of the dash. */
+  defaultContent?: string;
+}
+
+/** A URL source: read once for client-side processing, or asked for every query with serverSide. */
+export interface GridUrlSource {
+  url: string;
+  /** Defaults to GET when there is no body, else POST. A server source posts the grid query as JSON. */
+  method?: string;
+  headers?: Readonly<Record<string, string>>;
+  /** Extra request data: query parameters for GET, JSON fields otherwise; a function receives the grid query in server mode. */
+  data?: Readonly<Record<string, unknown>> | ((query?: GridQuery) => Readonly<Record<string, unknown>> | undefined);
+  /** Where the records are in the answer: a property path ("" for the answer itself) or a function. Default: the answer, its data or its items. */
+  dataSrc?: string | ((answer: any) => any);
+  credentials?: RequestCredentials;
+  /** A function with the fetch signature, for authenticated clients or tests. */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>;
+  /** Ask the server for every query (sort, search, filters, page) with the canopyx/2 grid query; it answers a grid page or { total, matched, items }. */
+  serverSide?: boolean;
+  /** A server source's value-list endpoint (canopyx/2 grid facet queries), used by the reporting runtime's value lists. */
+  facetUrl?: string;
+}
+
+/** What stateSave stores: the grid's state, its named views and when it was saved. */
+export interface GridStoredState {
+  time: number;
+  current: GridState;
+  views: { name: string; state: GridState }[];
+}
+
+/** State saving between visits. */
+export interface GridStateSaveOptions {
+  /** Default session. */
+  storage?: "session" | "local";
+  /** Seconds a stored state stays valid; 0 keeps it without a limit. Default 7200. */
+  duration?: number;
+  /** The storage key prefix; defaults to the page path. The grid id is added. */
+  key?: string;
+  /** Also keep the shareable part (sort, search, filters, page, page length) in the address. */
+  url?: false | "query" | "hash";
+  /** The address parameter; defaults to the grid id. */
+  parameter?: string;
+  /** Reads the state from the host's own store instead of browser storage. */
+  load?(event: { key: string; view: string }): GridStoredState | null | PromiseLike<GridStoredState | null>;
+  /** Writes the state to the host's own store instead of browser storage. */
+  save?(event: { key: string; view: string; state: GridStoredState }): void | PromiseLike<void>;
+}
+
+/** Short names for the texts people change most; every other text is a CanopyX label (labels). Unknown names are ignored. */
+export interface GridTexts {
+  search?: string; info?: string; infoFiltered?: string; lengthMenu?: string; first?: string; previous?: string; next?: string; last?: string;
+  page?: string; all?: string; empty?: string; emptyReason?: string; noMatches?: string; loading?: string; loadFailed?: string; retry?: string;
+}
+
+/** The detail of draw, order, search, page and length: the accepted query and the paging it produced. */
+export interface GridDrawEvent {
+  readonly query: GridQuery;
+  readonly paging: GridPaging;
+}
+
+/** The options of CanopyX.grid and CanopyX.enhance. Host options of createDataGrid (renderers, actions, plugins, toolbar, onQuery, ...) pass through. */
+export interface GridInitOptions<R = any> extends Omit<GridHostOptions, "source" | "viewStore" | "labels"> {
+  /** The grid id; defaults to the element id. */
+  id?: string;
+  /** The accessible name; defaults to aria-label, the table caption or the title attribute. */
+  label?: string;
+  noun?: string;
+  /** Columns; for a table, options by header position. Without columns, the first record's fields (or positions) become columns. */
+  columns?: readonly (GridColumnOptions<R> | null | undefined)[];
+  /** Records as arrays or objects. */
+  data?: readonly R[];
+  /** A URL source; without declared column types it is read before the grid appears. */
+  url?: string | GridUrlSource;
+  /** Ask the URL for every query. The same as url.serverSide. */
+  serverSide?: boolean;
+  /** The record field (or a function) that gives each row its stable id; missing ids are generated from positions. */
+  rowId?: string | ((record: R, index: number) => string | number);
+  /** False scrolls all rows instead of paging. Default true. */
+  paging?: boolean;
+  /** Rows per page. Default 25. */
+  pageLength?: number;
+  /** Page-size choices. Default 10, 25, 50, 100 and All. */
+  pageLengths?: readonly GridPageLengthChoice[];
+  /** False hides the rows-per-page menu. */
+  lengthMenu?: boolean;
+  /** "sentence" (default), "range" (compact), or false for no result text. */
+  info?: boolean | "range" | "sentence";
+  /** Numbered page buttons: true for seven (default), a count from 5 to 15, or false. */
+  pageNumbers?: boolean | number;
+  /** The page number field; shown by default only without numbered pages. */
+  pageInput?: boolean;
+  /** False hides the first-page and last-page buttons. */
+  firstLast?: boolean;
+  /** False removes the search box. Default true. */
+  search?: boolean;
+  /** The initial search. */
+  searchText?: string;
+  searchMode?: "substring" | "words";
+  /** The initial sort: [[column position or id, "asc" | "desc"], ...] or [{ column, direction }, ...]. */
+  order?: readonly (readonly [number | string, ("asc" | "desc")?] | { column: number | string; direction?: "asc" | "desc" })[];
+  /** False makes every column unsortable unless a column says otherwise. Default true. */
+  sortable?: boolean;
+  selection?: "none" | "single" | "multiple";
+  stateSave?: boolean | GridStateSaveOptions;
+  texts?: GridTexts;
+  labels?: Partial<CanopyLabels>;
+  /** Keep the markup of table cells (links, badges) in the grid's cells. Default true. */
+  markup?: boolean;
+  /** False drops the table footer strip. Default: the table footer shows below the rows. */
+  footer?: boolean;
+  /** The grid's CSS height; paged grids default to the height of a page of rows. */
+  height?: string;
+  theme?: "light" | "dark" | "auto";
+  density?: "compact" | "default" | "comfortable";
+  zebra?: boolean;
+  /** Further grid definition fields (rowHeight, statusBar, toolbar, reporting, timeZone, ...), merged last. */
+  view?: Partial<GridView>;
+  /** Handlers by event name, attached before the grid starts. */
+  on?: Readonly<Record<string, (detail: any, grid: EnhancedGrid<R>, event?: CustomEvent) => void>>;
+}
+
+/** A header row above the bottom one: groups with their titles and the ids of the columns they span. */
+export interface GridHeaderGroup {
+  readonly title: string;
+  readonly columns: readonly string[];
+}
+
+/**
+ * The controller CanopyX.enhance and CanopyX.grid resolve with: the grid's API plus events by name, records and the restored
+ * table. Its addRows and removeRows take records as the controller was given them; the grid's other live methods stay.
+ */
+export interface EnhancedGrid<R = any> extends Omit<DataGrid, "addRows" | "removeRows"> {
+  /** The original table, put back by destroy(); null for a grid built in another element. */
+  readonly table: HTMLTableElement | null;
+  /** Header rows above the bottom one, as levels of groups. */
+  readonly headerGroups: readonly (readonly GridHeaderGroup[])[];
+  on(name: "init", handler: (detail: { query: GridQuery }, grid: EnhancedGrid<R>) => void): this;
+  on(name: "draw" | "order" | "search" | "page" | "length", handler: (detail: GridDrawEvent, grid: EnhancedGrid<R>, event?: CustomEvent) => void): this;
+  /** Any canopyx:<name> event of the grid: select, query, state, error, rowActivate, link, columnResize, columnPin, ... */
+  on(name: string, handler: (detail: any, grid: EnhancedGrid<R>, event?: CustomEvent) => void): this;
+  off(name: string, handler: (...args: any[]) => void): this;
+  /** Records as given (a table row's cell texts): all in data order, filtered in the accepted order, or the visible page. A server source returns its last loaded rows. */
+  getRows(scope?: "all" | "filtered" | "page"): R[];
+  getRow(id: string): R | undefined;
+  /** Replaces the records; the sort, search, filters and page stay. Inline data only. */
+  setData(data: readonly R[]): Promise<GridQuery>;
+  addRows(data: readonly R[]): Promise<GridQuery>;
+  removeRows(ids: readonly string[]): Promise<GridQuery>;
+}
+
+/** Turns an existing table into a grid, keeping the table as the script-free fallback; destroy() puts it back. */
+export function enhance(table: HTMLTableElement | string, options?: GridInitOptions<string[]>): Promise<EnhancedGrid<string[]>>;
+/** Builds a grid in an element from records or a URL source; given a table, it enhances it. */
+export function grid<R = any>(element: HTMLElement | string, options: GridInitOptions<R>): Promise<EnhancedGrid<R>>;

package/JavaScript/facets.d.ts

@@ -0,0 +1,58 @@
+// The facet panel of flat grids (docs/facets.md): value lists with counts and ranges with histograms that filter each other.
+import type { GridRow, GridColumnId } from "./grid.js";
+
+/** One facet: a column id, or a column with its settings. */
+export type GridFacet<Row extends GridRow = GridRow> = GridColumnId<Row> | {
+  column: GridColumnId<Row>;
+  /** "list" (text columns by default) or "range" with a histogram (number and date columns by default). */
+  kind?: "list" | "range";
+  /** The facet's heading; the column's title by default. */
+  label?: string;
+  /** Values a list shows before "Show N more", 1..200 (default 8). */
+  limit?: number;
+  /** Bars in a range's histogram, 2..60 (default 16). */
+  bins?: number;
+  /** "count" (most frequent first) or "value"; omitted uses declared column order, otherwise count. */
+  sort?: "count" | "value";
+  /** Starts collapsed to its heading. */
+  collapsed?: boolean;
+};
+
+/** The facet panel a grid definition carries (the C# CanopyFacetPanel writes it). */
+export interface GridFacetPanelDefinition<Row extends GridRow = GridRow> {
+  /** 1 to 24 distinct columns; a hosted grid's must be reporting facet columns. */
+  columns: readonly GridFacet<Row>[];
+  /** Beside the grid (default) or above it. */
+  position?: "side" | "top";
+  /** Starts open (default true); the grid state keeps the reader's choice. */
+  open?: boolean;
+  /** The reader can collapse the panel (default true). */
+  collapsible?: boolean;
+  /** A side panel's width, 180..480 pixels (default 260). */
+  width?: number;
+  /** The panel's heading; "Filter by" by default. */
+  label?: string;
+}
+
+/** The host's facet options: the definition's fields, and an element the panel renders into. */
+export interface GridFacetPanelOptions<Row extends GridRow = GridRow> extends Partial<GridFacetPanelDefinition<Row>> {
+  /** An element the panel renders into, for a host that lays out the page itself; the grid element stays where it is. */
+  target?: HTMLElement;
+}
+
+/** The facet panel's state, from getFacetPanel(). */
+export interface GridFacetPanelState {
+  /** Whether the panel is open; null before the facets part has started. */
+  readonly open: boolean | null;
+  /** The facet columns, in order; empty before the facets part has started. */
+  readonly columns: readonly string[];
+  /** Facets with a choice. */
+  readonly active?: number;
+}
+
+/** Facet panel methods of a flat grid. */
+export interface GridFacetPanelApi {
+  getFacetPanel(): GridFacetPanelState;
+  /** Opens or collapses the panel; loads the facets part on first use. */
+  setFacetPanelOpen(open: boolean): Promise<GridFacetPanelState>;
+}

package/JavaScript/formatting.d.ts

@@ -0,0 +1,88 @@
+// Conditional formatting of flat grids (docs/conditional-formatting.md). The same schema as the .NET CanopyFormatRule
+// family writes; the browser's rule editor reads and writes it too.
+
+/** Every flat-grid filter operator, plus negations, suffixes, patterns, ranges and relative dates in days. */
+export type GridFormatOperator = "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "contains" | "notContains" | "startsWith" | "endsWith" | "like" | "notLike"
+  | "matches" | "notMatches" | "in" | "notIn" | "between" | "betweenExclusive" | "isNull" | "isNotNull" | "olderThan" | "withinLast";
+/** A raw operand: text, a finite number or a boolean. Dates are ISO 8601 strings with a time zone. */
+export type GridFormatValue = string | number | boolean;
+/** One test: a column, an operator and operands, or another column to compare with. */
+export interface GridFormatPredicate {
+  readonly column: string;
+  readonly operator: GridFormatOperator;
+  /** None for the null tests, two for ranges, 1..1000 for in/notIn, days for relative dates, one otherwise. */
+  readonly values?: readonly GridFormatValue[];
+  /** Compare with this column's value instead of values (one-operand comparisons). */
+  readonly valueColumn?: string;
+  /** How values are read; the column's kind by default. */
+  readonly type?: "text" | "number" | "boolean" | "date";
+  /** Text compares case-insensitively unless true. */
+  readonly caseSensitive?: boolean;
+  /** A BCP 47 culture for parsing numbers in text and comparing text. */
+  readonly culture?: string;
+}
+/** A condition group: a filter group with a third junction, none. Eight levels, 64 groups and 64 predicates at most. */
+export interface GridFormatCondition {
+  readonly operator: "and" | "or" | "none";
+  readonly filters?: readonly GridFormatPredicate[];
+  readonly groups?: readonly GridFormatCondition[];
+}
+/** An icon name, "auto" (the tone's shape) or "none", or up to four characters of the host's own. */
+export type GridFormatIcon = "auto" | "none" | "up" | "down" | "check" | "cross" | "warning" | "info" | "dot" | "circle" | "triangle" | "square" | "diamond"
+  | "flag" | "star" | "minus" | "plus" | "clock" | (string & {});
+/** A data bar: absent bounds run from zero (or the lowest value) to the highest value of the rows in hand. */
+export interface GridFormatDataBar { readonly minimum?: number; readonly maximum?: number; readonly tone?: string; readonly showValue?: boolean; }
+/** A colour scale stop at the lowest or highest value, at a number, or at a percentage of the range. */
+export interface GridFormatScaleStop { readonly type: "min" | "max" | "number" | "percent"; readonly value?: number; readonly tone: string; }
+export interface GridFormatColorScale {
+  readonly stops: readonly [GridFormatScaleStop, GridFormatScaleStop] | readonly [GridFormatScaleStop, GridFormatScaleStop, GridFormatScaleStop];
+}
+/** A threshold band: values up to its inclusive upper bound take its tone; the last band may leave its bound open. */
+export interface GridFormatBand { readonly upperBound?: number; readonly tone: string; readonly label?: string; readonly icon?: GridFormatIcon; }
+/** Theme tones with an emphasis, an icon, a badge and a cue, or one of a bar, a scale and bands; className and css are the escape hatch. */
+export interface GridFormatStyle {
+  readonly tone?: string;
+  readonly emphasis?: "fill" | "text" | "strong";
+  readonly icon?: GridFormatIcon;
+  readonly badge?: string;
+  readonly cue?: string;
+  readonly bar?: GridFormatDataBar;
+  readonly scale?: GridFormatColorScale;
+  readonly bands?: readonly GridFormatBand[];
+  readonly className?: string;
+  readonly css?: Readonly<Record<string, string>>;
+}
+/** A rule: identity, condition (absent matches every row), target and style. Rules apply in order; the first rule that sets an aspect of a target wins it. */
+export interface GridFormatRule {
+  readonly id: string;
+  /** The legend entry and default screen reader description. */
+  readonly label?: string;
+  /** What screen readers hear on a formatted cell. */
+  readonly description?: string;
+  readonly enabled?: boolean;
+  readonly when?: GridFormatCondition;
+  /** The cell a cell rule paints and the value bars, scales and bands read. */
+  readonly column?: string;
+  readonly target?: "cell" | "row" | "columns";
+  readonly columns?: readonly string[];
+  /** Follow the column into the record drawer and the phone's hidden fields (default true). */
+  readonly details?: boolean;
+  readonly style: GridFormatStyle;
+  readonly stopIfTrue?: boolean;
+}
+/** A legend of the labelled rules, and the rule editor in the more menu. */
+export interface GridFormatOptions { readonly legend?: boolean; readonly editor?: boolean; }
+/** A cell's or record's resolved format in export records, for writers that paint (a styled spreadsheet, a print snapshot). */
+export interface GridExportFormat {
+  readonly rules: readonly string[];
+  readonly tone?: string;
+  readonly icon?: string;
+  readonly badge?: string;
+  readonly cue?: string;
+  readonly band?: string;
+  /** Where the value lies between the bar's bounds, 0..1, and the bar's tone. */
+  readonly bar?: { readonly fraction: number; readonly tone: string };
+  /** A colour scale's CSS colour, mixed from theme tone variables. */
+  readonly color?: string;
+  readonly description?: string;
+}