@getaster/elements 0.3.5 → 0.4.5

package/dist/grid/features.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How a permitted capability behaves. A descriptor says how, never whether:
+ * switching a capability off is [[object:GridPolicy]]'s job, and whether it
+ * is shown is chrome's. Plain data, so a composition catalog can carry it.
+ */
+export type GridFeature = {
+    readonly kind: "sort";
+    readonly multi?: boolean;
+} | {
+    readonly kind: "edit";
+    readonly mode?: "row" | "cell";
+} | {
+    readonly kind: "select";
+    readonly appearance?: "row" | "cell";
+    readonly column?: boolean;
+} | {
+    readonly kind: "page";
+};
+/** One descriptor of `kind`, if the page gave one. */
+export declare function feature<K extends GridFeature["kind"]>(features: readonly GridFeature[] | undefined, kind: K): Extract<GridFeature, {
+    kind: K;
+}> | undefined;
+/** The features with `next` replacing the first descriptor of its kind, or appended. */
+export declare function withFeature(features: readonly GridFeature[] | undefined, next: GridFeature): GridFeature[];
+/** The features without the descriptor of `kind`. */
+export declare function withoutFeature(features: readonly GridFeature[] | undefined, kind: GridFeature["kind"]): GridFeature[];
+/** Whether the grid loads a page at a time instead of scrolling through the whole set. */
+export declare function paged(features: readonly GridFeature[] | undefined): boolean;
+/** The sort descriptor's multi-key setting, on by default. */
+export declare function multiSort(features: readonly GridFeature[] | undefined): boolean;
+/** The edit descriptor's mode, row editing by default. */
+export declare function editMode(features: readonly GridFeature[] | undefined): "row" | "cell";
+/** How selected records are highlighted, the whole row by default. */
+export declare function selectionAppearance(features: readonly GridFeature[] | undefined): "row" | "cell";
+/** Whether selection gets a checkbox column of its own, off by default. */
+export declare function selectionColumn(features: readonly GridFeature[] | undefined): boolean;
+/** Checks a features value: known kinds, plain fields and valid unions. */
+export declare function validateFeatures(value: unknown): asserts value is readonly GridFeature[];

package/dist/grid/features.js

@@ -0,0 +1,78 @@
+/** One descriptor of `kind`, if the page gave one. */
+export function feature(features, kind) {
+    return features?.find((entry) => entry.kind === kind);
+}
+/** The features with `next` replacing the first descriptor of its kind, or appended. */
+export function withFeature(features, next) {
+    const list = [...(features ?? [])];
+    const at = list.findIndex((entry) => entry.kind === next.kind);
+    if (at < 0)
+        list.push(next);
+    else
+        list[at] = next;
+    return list;
+}
+/** The features without the descriptor of `kind`. */
+export function withoutFeature(features, kind) {
+    return (features ?? []).filter((entry) => entry.kind !== kind);
+}
+/** Whether the grid loads a page at a time instead of scrolling through the whole set. */
+export function paged(features) {
+    return feature(features, "page") !== undefined;
+}
+/** The sort descriptor's multi-key setting, on by default. */
+export function multiSort(features) {
+    return feature(features, "sort")?.multi ?? true;
+}
+/** The edit descriptor's mode, row editing by default. */
+export function editMode(features) {
+    return feature(features, "edit")?.mode ?? "row";
+}
+/** How selected records are highlighted, the whole row by default. */
+export function selectionAppearance(features) {
+    return feature(features, "select")?.appearance ?? "row";
+}
+/** Whether selection gets a checkbox column of its own, off by default. */
+export function selectionColumn(features) {
+    return feature(features, "select")?.column ?? false;
+}
+/** Checks a features value: known kinds, plain fields and valid unions. */
+export function validateFeatures(value) {
+    if (!Array.isArray(value))
+        throw new TypeError("features must be an array");
+    const seen = new Set();
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new TypeError("each feature must be a plain object");
+        const kind = entry.kind;
+        if (kind !== "sort" && kind !== "edit" && kind !== "select" && kind !== "page")
+            throw new TypeError(`unknown feature kind: ${String(kind)}`);
+        if (seen.has(kind))
+            throw new TypeError(`feature "${kind}" appears more than once`);
+        seen.add(kind);
+        switch (kind) {
+            case "sort": {
+                const multi = entry.multi;
+                if (multi !== undefined && typeof multi !== "boolean")
+                    throw new TypeError("sort.multi must be a boolean");
+                break;
+            }
+            case "edit": {
+                const mode = entry.mode;
+                if (mode !== undefined && mode !== "row" && mode !== "cell")
+                    throw new TypeError('edit.mode must be "row" or "cell"');
+                break;
+            }
+            case "select": {
+                const { appearance, column } = entry;
+                if (appearance !== undefined && appearance !== "row" && appearance !== "cell")
+                    throw new TypeError('select.appearance must be "row" or "cell"');
+                if (column !== undefined && typeof column !== "boolean")
+                    throw new TypeError("select.column must be a boolean");
+                break;
+            }
+            case "page":
+                break;
+        }
+    }
+}

package/dist/grid/grid.d.ts

@@ -8,10 +8,16 @@ import "../select/choice-element.ts";
 import "../filter/filter-builder.ts";
 import "../dialog/dialog.ts";
 import { type GridView } from "./view.ts";
+import { type Capability, type CapabilityValue, type GridPolicy } from "./policy.ts";
+import { type GridLabels, type GridPresentation } from "./appearance.ts";
+import { type GridFeature } from "./features.ts";
+export type { GridFeature } from "./features.ts";
 /** Renders a cell's content; `entity` is the row's record. */
 export type CellRenderer = (entity: Entity, key: KeyText) => View;
 /** Text presentation of a typed value. Queries and exports retain the underlying value. */
 export type CellFormatter = (value: Value | undefined, entity: Entity, field: Field | undefined) => string;
+/** Where a non-focus scroll puts the requested row or cell. */
+export type GridScrollAlign = "start" | "center" | "end" | "nearest";
 /** How a column shows a foreign key: the related set and the field to show. */
 export interface Lookup {
     readonly set: string;
@@ -31,6 +37,38 @@ export interface GridCsvOptions extends Omit<CsvOptions, "keys"> {
     /** All filtered results by default, or shared selection in pick order. */
     readonly scope?: "query" | "selection";
 }
+/** Which grid chrome is shown. Every option preserves today's full grid by default. */
+export interface GridChrome {
+    /** The toolbar above the table. Default `true`; hide it with `showToolbar`. */
+    readonly toolbar?: boolean;
+    /** The column header row. Default `true`. When hidden it stays in the accessibility tree. */
+    readonly header?: boolean;
+    /** The filter row: `"auto"` (default) follows the view and the Filters button; `true` forces it open; `false` removes it. */
+    readonly filterRow?: "auto" | boolean;
+    /** The per-header menu button. Default `true`; `false` removes it and the header's keyboard menu. */
+    readonly headerMenu?: boolean;
+    /** The paging bar. Default `true`; shown only when a `page` feature is configured. */
+    readonly pagingBar?: boolean;
+}
+/** Which controls the toolbar shows. Every option defaults to `true`. */
+export interface GridToolbar {
+    /** The row count. Default `true`. */
+    readonly count?: boolean;
+    /** The Sort panel button. Default `true`. */
+    readonly sort?: boolean;
+    /** The filter-row toggle. Default `true`; hidden when `chrome.filterRow` is false. */
+    readonly filters?: boolean;
+    /** The advanced filter button. Default `true`. */
+    readonly advanced?: boolean;
+    /** The Columns panel button. Default `true`. */
+    readonly columns?: boolean;
+    /** The Views panel button, when `persist` is set. Default `true`. */
+    readonly views?: boolean;
+    /** Expand all / Collapse all in a tree grid. Default `true`. */
+    readonly expandAll?: boolean;
+    /** A host view placed at the end of the toolbar, after the built-in controls. */
+    readonly extra?: View;
+}
 /** A row as row controls and expansion content see it; read inside a render, it updates them. */
 export interface RowState {
     readonly key: KeyText;
@@ -77,6 +115,26 @@ export interface GridTree {
     readonly filterMode?: FilterMode;
     /** Rows can be dragged onto another row to move under it, or onto the header to the top level; a touch or pen holds a row still to lift it. */
     readonly draggable?: boolean;
+    /** Whether a drop may change a row's parent. Default `true`; `false` leaves only a no-op drop. */
+    readonly reparent?: boolean;
+    /** Whether a row may be dropped on a leaf. Default `true`; `false` accepts folders and the top level. */
+    readonly dropOnLeaves?: boolean;
+    /** Levels opened when the tree first loads, below the top level. Default `0`; bounded by `openLimit`. */
+    readonly autoOpen?: number;
+    /** Openers in the first column. Default `true`. */
+    readonly showOpener?: boolean;
+    /** A template before a folder's title, when it has children. */
+    readonly folderIcon?: View;
+    /** A template before a leaf's title. */
+    readonly nodeIcon?: View;
+    /** Selecting a row applies to its loaded descendants too. Needs a multiple shared Selection. Default `false`. */
+    readonly cascadeSelection?: boolean;
+    /** Rows per level load. Default the data core's 100. */
+    readonly pageSize?: number;
+    /** Matches beyond this make keep-ancestors give up. Default the data core's 8000. */
+    readonly matchLimit?: number;
+    /** Folders opened at most to show where matches are; also bounds Expand all. Default 200. */
+    readonly openLimit?: number;
 }
 /**
  * A virtualized grid over an entity set, shaped by a view the person can
@@ -120,6 +178,21 @@ export declare class Grid extends AsterElement {
     /** Text-only display formatting by field; never changes server sorting or filtering. */
     get formatters(): Readonly<Record<string, CellFormatter>>;
     set formatters(value: Readonly<Record<string, CellFormatter>>);
+    /**
+     * Declarative presentation: per-column titles, alignment, value maps and
+     * formats, row and cell classes, and hilites. Default `{}`, which keeps
+     * today's rendering. Renderers and formatters (JavaScript) outrank these
+     * plain-data display overrides for cell content.
+     */
+    get presentation(): GridPresentation;
+    set presentation(value: GridPresentation);
+    /**
+     * The grid's overridable strings. Every entry is optional; a missing entry
+     * keeps today's text, and `{name}` placeholders are filled by the grid.
+     * A stopgap before full i18n, not an i18n engine.
+     */
+    get labels(): GridLabels;
+    set labels(value: GridLabels);
     /** Exact overall totals and, when grouped, totals on each group header. */
     get summaries(): readonly GridSummary[];
     set summaries(value: readonly GridSummary[]);
@@ -131,6 +204,19 @@ export declare class Grid extends AsterElement {
     /** The page's actions for a row, shown first in its menu (right-click, Shift+F10, the Menu key). */
     get rowMenu(): (entity: Entity, key: KeyText) => readonly MenuItem[];
     set rowMenu(v: (entity: Entity, key: KeyText) => readonly MenuItem[]);
+    /**
+     * The page's actions for a column, shown first in its menu. Read each time
+     * a menu opens. Default: no items.
+     */
+    get columnMenu(): (field: string) => readonly MenuItem[];
+    set columnMenu(v: (field: string) => readonly MenuItem[]);
+    /**
+     * Per-field operator allowlists for filtering, by column field. Each entry
+     * narrows the operators the metadata offers; it can never add one. Default
+     * `{}`: the metadata's operators.
+     */
+    get filterOperators(): Readonly<Record<string, readonly string[]>>;
+    set filterOperators(v: Readonly<Record<string, readonly string[]>>);
     /**
      * A tree grid: the first column shows each record's level with an opener;
      * levels load as they open; a filter keeps the path to each match. Set it
@@ -170,9 +256,60 @@ export declare class Grid extends AsterElement {
      * scrolls it to the top. Resolves to whether the record is in the tree.
      */
     reveal(key: KeyText): Promise<boolean>;
-    /** Rows can be edited in place: Enter, F2 or a double-click start, Enter saves, Escape cancels. */
-    get editable(): boolean;
-    set editable(v: boolean);
+    /**
+     * What the page allows, by capability and field. Policy can only restrict:
+     * schema and structure refuse first, and a page rule's read-only reason
+     * outranks a policy reason. It is host configuration, never part of the
+     * saved [[object:GridView]].
+     */
+    get policy(): GridPolicy;
+    set policy(value: GridPolicy);
+    /** Sugar for `policy.sortable`: no sorting, an allowlist, or a predicate. */
+    get sortable(): CapabilityValue | undefined;
+    set sortable(value: Capability | undefined);
+    /** Sugar for `policy.filterable`: no filtering, an allowlist, or a predicate. */
+    get filterable(): CapabilityValue | undefined;
+    set filterable(value: Capability | undefined);
+    /** Sugar for `policy.groupable`: no grouping, an allowlist, or a predicate. */
+    get groupable(): CapabilityValue | undefined;
+    set groupable(value: Capability | undefined);
+    /** Sugar for `policy.resizable`: no column resizing, an allowlist, or a predicate. */
+    get resizable(): CapabilityValue | undefined;
+    set resizable(value: Capability | undefined);
+    /** Sugar for `policy.movable`: no column moving, an allowlist, or a predicate. */
+    get movable(): CapabilityValue | undefined;
+    set movable(value: Capability | undefined);
+    /** Sugar for `policy.hideable`: no column hiding, an allowlist, or a predicate. */
+    get hideable(): CapabilityValue | undefined;
+    set hideable(value: Capability | undefined);
+    /** Sugar for `policy.freezable`: no column freezing, an allowlist, or a predicate. */
+    get freezable(): CapabilityValue | undefined;
+    set freezable(value: Capability | undefined);
+    /** Sugar for `policy.editable`: no editing, an allowlist, or a predicate. */
+    get editable(): CapabilityValue;
+    set editable(value: Capability);
+    /**
+     * How permitted capabilities behave, as [[type:GridFeature]] descriptors.
+     * The structured form is the contract; the matching properties are sugar.
+     * Default `[]`, which keeps today's grid.
+     */
+    get features(): readonly GridFeature[];
+    set features(value: readonly GridFeature[]);
+    /**
+     * Sugar for a `sort` feature's `multi`: whether Shift adds another sort key.
+     * `false` makes every sort action replace the sort. Default `true`.
+     */
+    get multiSort(): boolean;
+    set multiSort(value: boolean);
+    /** Sugar for an `edit` feature's `mode`: a whole row (`"row"`, the default) or one cell (`"cell"`). */
+    get editMode(): "row" | "cell";
+    set editMode(value: "row" | "cell");
+    /** Sugar for a `select` feature's `appearance`: how a selected record is highlighted. */
+    get selectionAppearance(): "row" | "cell";
+    set selectionAppearance(value: "row" | "cell");
+    /** Sugar for a `select` feature's `column`: whether selection gets a checkbox column. */
+    get selectionColumn(): boolean;
+    set selectionColumn(value: boolean);
     /**
      * Page rules for the cells of a row being edited. Each row has a child
      * scope where it's published as `row`, so a rule reads its own record.
@@ -184,11 +321,75 @@ export declare class Grid extends AsterElement {
     /** Shown when the query matches nothing. */
     get empty(): View;
     set empty(v: View);
+    /**
+     * Shown in the content area while the first page loads. Default: the
+     * built-in presentation with [[attr:Grid.loadingMessage]].
+     */
+    get loading(): View;
+    set loading(v: View);
+    /** The built-in loading presentation's text. Default `"Loading…"`. */
+    get loadingMessage(): string;
+    set loadingMessage(v: string);
+    /**
+     * The root collection failure, as a template: the page says what happened
+     * and offers `retry`, which calls [[method:Grid.refresh]]. Default: a
+     * "Couldn’t load rows." message with a Retry button.
+     */
+    get error(): ((error: unknown, retry: () => void) => View) | undefined;
+    set error(v: ((error: unknown, retry: () => void) => View) | undefined);
+    /**
+     * Load on connect (the default) or wait for [[method:Grid.refresh]] or the
+     * first interaction with the grid. Default `true`.
+     */
+    get autoFetch(): boolean;
+    set autoFetch(v: boolean);
+    /**
+     * Rows per load, in either loading mode. Default `100`. In paged mode it is
+     * also the number of rows shown at once.
+     */
+    get pageSize(): number;
+    set pageSize(v: number);
+    /** Loaded pages kept while scrolling; the data core's default (20) when unset. */
+    get keepPages(): number | undefined;
+    set keepPages(v: number | undefined);
+    /** Ask the server for an exact total where it would estimate or omit one. Default `false`. */
+    get exactCount(): boolean;
+    set exactCount(v: boolean);
+    /**
+     * Reloads the rows the grid shows, keeping them visible until the answer
+     * arrives. Rejects when the load fails; the error view or `collection.error`
+     * reports it. With `autoFetch` false it also starts the first load.
+     */
+    refresh(): Promise<void>;
+    /** Which chrome the grid shows. Default `{}`: the full toolbar, header, automatic filter row and paging bar. */
+    get chrome(): GridChrome;
+    set chrome(v: GridChrome);
+    /** The toolbar's controls. Default `{}`: every control shown. Object-only; use `showToolbar` to hide the toolbar. */
+    get toolbar(): GridToolbar;
+    set toolbar(v: GridToolbar);
+    /** Sugar for `chrome.header`. Default `true`; false hides the header visually but keeps it for assistive technology. */
+    get showHeader(): boolean;
+    set showHeader(v: boolean);
+    /** Sugar for `chrome.toolbar`. Default `true`. */
+    get showToolbar(): boolean;
+    set showToolbar(v: boolean);
+    /** Sugar for `chrome.filterRow`: false removes the row, true forces it open, "auto" (the default) follows the view. */
+    get showFilterRow(): boolean;
+    set showFilterRow(v: boolean);
+    /** Sugar for `chrome.headerMenu`. Default `true`. */
+    get showHeaderMenu(): boolean;
+    set showHeaderMenu(v: boolean);
+    /** Sugar for `chrome.pagingBar`. Default `true`. */
+    get showPagingBar(): boolean;
+    set showPagingBar(v: boolean);
     get collection(): Collection | undefined;
     set collection(v: Collection | undefined);
     /** Shared selection; without collection, its collection supplies the binding. */
     get selection(): Selection | undefined;
-    /** Allows this view to change selection; borrowed selection state remains visible. */
+    /**
+     * Allows this view to change selection; borrowed selection state remains
+     * visible. Sugar for `policy.selectable`, default on.
+     */
     get selectable(): boolean;
     set selectable(value: boolean);
     set selection(v: Selection | undefined);
@@ -202,6 +403,17 @@ export declare class Grid extends AsterElement {
     focusIndex(index: number, column?: number): Promise<boolean>;
     /** Reveals a key currently loaded in the flat collection. */
     focusKey(key: KeyText, column?: number): Promise<boolean>;
+    /**
+     * Scrolls a flat row into view without moving focus or the active cell.
+     * Loads its page if needed. False for grouped/tree grids or a bad position.
+     */
+    scrollToRow(index: number, align?: GridScrollAlign): Promise<boolean>;
+    /**
+     * Scrolls a flat row and visible column into view without moving focus or
+     * the active cell. A frozen column needs no sideways scroll. False like
+     * [[method:Grid.scrollToRow]].
+     */
+    scrollToCell(index: number, column: number, align?: GridScrollAlign): Promise<boolean>;
     connectedCallback(): void;
     focus(options?: FocusOptions): void;
     protected render(): View;