optikos 0.3.0 → 0.4.0

package/dist/testing.js

@@ -0,0 +1,2 @@
+import{b as c}from"./chunk-V5G5JECN.js";import"./chunk-4C666HHU.js";var a=(t=0)=>new Promise(o=>setTimeout(o,t));function l(t,o){let e=t instanceof HTMLElement?t:t.el.querySelector("input,textarea");if(!e)return void t.setValue(o);e.value=o,e.dispatchEvent(new Event("input",{bubbles:!0}))}function u(t,o){let e={},r=(n,i="")=>{for(let s in n){let p=i+s;n[s]&&typeof n[s]=="object"&&!Array.isArray(n[s])&&!t.getField(p)?r(n[s],`${p}.`):e[p]=n[s]}};r(o);for(let n in e){let i=t.getField(n);if(!i)throw new Error(`Optikos testing: the form has no field "${n}"`);typeof e[n]=="string"&&i.el.querySelector("input[type=text],input:not([type]),textarea")&&!i.el.querySelector("[role=combobox]")?l(i,e[n]):i.setValue(e[n])}return t}async function f(t,o){o&&u(t,o);let e=null,r=t.on("submit",n=>e=n);return t.submit(),await a(),r(),e}function y(t){let o={};for(let e of t.getFields())e.name&&e.getError()&&c(o,e.name,e.getError());return o}function g(t,o){let e=t.getStore(),r=typeof o=="number"?e.getAt(o):e.getRange().find(o);if(!r)throw new Error("Optikos testing: no such row in the grid");return t.select(r),t.emit("row-click",r),r}async function m(t){return t.loading&&await new Promise(o=>t.once("load",o)),await a(),t}async function w(t,o=0){t.openDialog(),await a();let e=t.win,r=e?.query(n=>n.constructor.type==="searchgrid")[0];if(!r)throw new Error("Optikos testing: the lookup window did not open");return await m(r.store),r.grid.select(o),[...e.el.querySelectorAll(".op-panel__footer button")].pop().click(),await a(),t.getValue()}var k=t=>((t instanceof HTMLElement?t:t.el).textContent??"").replace(/\s+/g," ").trim();export{g as clickRow,y as errors,u as fill,a as flush,m as loaded,w as pickLookup,f as submit,k as text,l as type};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/testing/index.ts"],
+  "sourcesContent": ["// Helpers for testing an app built with Optikos (Vitest + happy-dom, or any DOM): fill a form, pick a row, wait for a store.\n// They go through the public API and real DOM events, so a test reads like what the user does.\nimport type { Form } from '../components/form/form/form';\nimport type { Grid } from '../components/data/grid/grid';\nimport type { Field } from '../core/field';\nimport type { Component } from '../core/component';\nimport type { Store } from '../data/store';\nimport type { Model } from '../data/model';\nimport type { LookupField } from '../components/fields/lookupfield/lookupfield';\nimport { setPath } from '../core/path';\n\n/** Lets pending promises, microtasks and 0 ms timers run (after `fill`, `store.load()`, a debounce of `ms`...). */\nexport const flush = (ms = 0): Promise<void> => new Promise((done) => setTimeout(done, ms));\n\n/** Types into a field the way a user does: sets the input and fires `input`, so parsing, masks and validation run. Falls back to `setValue`. */\nexport function type(field: Field<any> | HTMLInputElement, text: string): void {\n  const input = field instanceof HTMLElement ? field : (field.el.querySelector('input,textarea') as HTMLInputElement | null);\n  if (!input) return void (field as Field<any>).setValue(text);\n  input.value = text;\n  input.dispatchEvent(new Event('input', { bubbles: true }));\n}\n\n/** Fills a form from an object (`{ 'address.city': 'Rio', name: 'Ada' }` or nested). Text fields are typed into; the rest get `setValue`. */\nexport function fill(form: Form, values: Record<string, any>): Form {\n  const flat: Record<string, any> = {};\n  const walk = (o: Record<string, any>, prefix = '') => {\n    for (const k in o) {\n      const path = prefix + k;\n      if (o[k] && typeof o[k] === 'object' && !Array.isArray(o[k]) && !form.getField(path)) walk(o[k], `${path}.`);\n      else flat[path] = o[k];\n    }\n  };\n  walk(values);\n  for (const name in flat) {\n    const f = form.getField(name);\n    if (!f) throw new Error(`Optikos testing: the form has no field \"${name}\"`);\n    if (typeof flat[name] === 'string' && f.el.querySelector('input[type=text],input:not([type]),textarea') && !f.el.querySelector('[role=combobox]')) type(f, flat[name]);\n    else f.setValue(flat[name]);\n  }\n  return form;\n}\n\n/** Fills and submits. Resolves with the values when the form was valid and submitted, or `null`. */\nexport async function submit(form: Form, values?: Record<string, any>): Promise<Record<string, any> | null> {\n  if (values) fill(form, values);\n  let sent: Record<string, any> | null = null;\n  const off = form.on('submit', (v: Record<string, any>) => (sent = v));\n  form.submit();\n  await flush();\n  off();\n  return sent;\n}\n\n/** What the form shows as errors: `{ fieldName: message }`. */\nexport function errors(form: Form): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const f of form.getFields()) if (f.name && f.getError()) setPath(out, f.name, f.getError());\n  return out;\n}\n\n/** Selects a grid row by index, or by the first record the predicate accepts; returns its record. */\nexport function clickRow<T extends Record<string, any>>(grid: Grid<T>, which: number | ((rec: Model<T>) => boolean)): Model<T> {\n  const store = grid.getStore();\n  const rec = typeof which === 'number' ? store.getAt(which) : store.getRange().find(which);\n  if (!rec) throw new Error('Optikos testing: no such row in the grid');\n  grid.select(rec);\n  grid.emit('row-click', rec);\n  return rec;\n}\n\n/** Waits until the store is not loading (and, if it has not started yet, until its first `load`). */\nexport async function loaded<T extends Record<string, any>>(store: Store<T>): Promise<Store<T>> {\n  if (store.loading) await new Promise((done) => store.once('load', done));\n  await flush();\n  return store;\n}\n\n/** Opens a lookup's search window, selects the record at `row` and confirms. Resolves with what the field then holds. */\nexport async function pickLookup(field: LookupField<any>, row = 0): Promise<unknown> {\n  field.openDialog();\n  await flush();\n  const win = (field as unknown as { win?: Component & { query(f: (c: Component) => boolean): Component[] } }).win;\n  const sg = win?.query((c) => (c.constructor as { type?: string }).type === 'searchgrid')[0] as unknown as { store: Store<any>; grid: Grid } | undefined;\n  if (!sg) throw new Error('Optikos testing: the lookup window did not open');\n  await loaded(sg.store);\n  sg.grid.select(row);\n  [...win!.el.querySelectorAll<HTMLButtonElement>('.op-panel__footer button')].pop()!.click();\n  await flush();\n  return field.getValue();\n}\n\n/** The text a component shows, collapsed to single spaces. */\nexport const text = (c: Component | HTMLElement): string => ((c instanceof HTMLElement ? c : c.el).textContent ?? '').replace(/\\s+/g, ' ').trim();\n"],
+  "mappings": "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",
+  "names": ["flush", "ms", "done", "type", "field", "text", "input", "fill", "form", "values", "flat", "walk", "o", "prefix", "k", "path", "name", "f", "submit", "sent", "off", "v", "errors", "out", "setPath", "clickRow", "grid", "which", "store", "rec", "loaded", "pickLookup", "row", "win", "sg", "c"]
+}

package/dist/themes/dark.css

@@ -26,6 +26,13 @@
     --op-color-warning-soft: #36270c;
     --op-color-info: #6ea8ec;
     --op-color-info-soft: #172a45;
+    --op-chart-2: #f0a35e;
+    --op-chart-3: #5cc493;
+    --op-chart-4: #c79bea;
+    --op-chart-5: #5fc4d6;
+    --op-chart-6: #f28b82;
+    --op-chart-7: #e0c45c;
+    --op-chart-8: #9ba7b8;
     --op-color-focus: #6ea8ec;
     --op-color-disabled-fg: #647186;
     --op-color-disabled-bg: #1a222e;

package/dist/types/bind/index.d.ts

@@ -20,4 +20,4 @@ export declare function fromStore<S extends {
  * is two-way: the field's `change` event writes back.
  */
 export declare function bind(cmp: Component<any>, map: Record<string, () => unknown>): void;
-export {};
+export { viewModel, bindVM, bindForm, type ViewModel, type ViewModelConfig } from './viewmodel.js';

package/dist/types/bind/viewmodel.d.ts

@@ -0,0 +1,33 @@
+import type { Component } from '../core/component.js';
+import type { Field } from '../core/field.js';
+import type { Model } from '../data/model.js';
+export interface ViewModelConfig {
+    /** The starting data, nested as you like (`{ qty: 2, record: { name: 'Ada' } }`). */
+    data?: Record<string, any>;
+    /** Values computed from the data and each other: `{ total: (get) => get('qty') * get('price') }`. They are read like data (`get('total')`) and rerun when what they read changes. */
+    formulas?: Record<string, (get: <T = any>(path: string) => T) => unknown>;
+}
+export interface ViewModel {
+    /** Reads a dotted path. Inside an `effect`, `computed` or `bind` it makes the reader rerun when that path changes. */
+    get<T = any>(path: string): T;
+    /** Writes a dotted path and notifies whoever read it, or something under it, or above it. A formula cannot be written. */
+    set(path: string, value: unknown): void;
+    /** Makes `name` stand for a record (a Model, or a plain object): `link('record', grid.getSelection()[0])`. A write to `record.x` goes through `model.set`, so the record is marked modified. `null` clears it. */
+    link(name: string, record: Model | Record<string, any> | null): void;
+    /** Counts the `link` calls for `name` (reactive): a form uses it to know it was given a new record. */
+    linked(name: string): number;
+}
+/** Shared state for a screen: the Ext `ViewModel` subset that matters (data, formulas, a linked record) without the rest. */
+export declare function viewModel(config?: ViewModelConfig): ViewModel;
+/**
+ * Ext's `bind: { text: '{record.name}', disabled: '{!canSave}' }` for any component: each key calls its setter whenever
+ * what the string reads changes. A field's `value: '{record.name}'` is two ways: the field's `change` writes back.
+ */
+export declare function bindVM(cmp: Component<any>, vm: ViewModel, map: Record<string, string>): void;
+/**
+ * Binds every named field of a form to `record.<name>` of the view model, both ways. When the record is replaced (`link`)
+ * the form is loaded from it and becomes clean; a change in the form writes through to the record (a Model is marked modified).
+ */
+export declare function bindForm(form: Component<any> & {
+    getFields(): Array<Field<any>>;
+}, vm: ViewModel, name?: string): void;

package/dist/types/components/avatar.d.ts

@@ -0,0 +1 @@
+export * from '../components/base/avatar/avatar.js';

package/dist/types/components/base/avatar/avatar.d.ts

@@ -0,0 +1,22 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface AvatarConfig extends ComponentConfig {
+    /** A person's or team's name: the initials when there is no picture, and the accessible name. */
+    name?: string;
+    /** Picture URL. If it fails to load the initials show. */
+    src?: string;
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    shape?: 'circle' | 'square';
+    status?: 'online' | 'away' | 'busy' | 'offline';
+}
+/** A picture or the initials of a name, on a color picked from the name (so the same person always looks the same). */
+export declare class Avatar extends Component<AvatarConfig> {
+    protected baseCls: string;
+    private img?;
+    private text;
+    private dot;
+    protected build(): HTMLSpanElement;
+    protected onRender(): void;
+    setName(name: string): void;
+    setSrc(src: string | undefined): void;
+    setStatus(status: AvatarConfig['status']): void;
+}

package/dist/types/components/base/image/image.d.ts

@@ -0,0 +1,25 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface ImageConfig extends ComponentConfig {
+    src?: string;
+    /** What the picture shows, for screen readers. Empty (the default) marks it decorative. */
+    alt?: string;
+    /** Aspect ratio as CSS: `'16/9'`, `'1'`. The box keeps it while the picture loads, so the page does not jump. */
+    ratio?: string;
+    fit?: 'cover' | 'contain';
+    /** Shown while the picture is missing or fails: an icon name, or a second URL if it contains a `/` or a `.`. Default `image`. */
+    fallback?: string;
+    /** `lazy` (default) waits until the picture is near the screen. */
+    eager?: boolean;
+    rounded?: boolean;
+}
+/** A picture in a box that keeps its aspect ratio and shows a fallback when the file is missing. */
+export declare class Image extends Component<ImageConfig> {
+    protected baseCls: string;
+    private img?;
+    private ph;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    setSrc(src: string | undefined, fallback?: boolean): void;
+    setAlt(alt: string): void;
+    setRatio(ratio: string): void;
+}

package/dist/types/components/base/imagecanvas/imagecanvas.d.ts

@@ -0,0 +1,39 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface ImageCanvasConfig extends ComponentConfig {
+    src?: string;
+    alt?: string;
+    /** How the image fills the box at zoom 1. Default `contain`. */
+    fit?: 'contain' | 'cover';
+    /** Default `true`. */
+    zoomable?: boolean;
+    /** Default 8. */
+    maxZoom?: number;
+    /** The zoom buttons. Default `true`. */
+    showTools?: boolean;
+    /** CSS `aspect-ratio` of the box (e.g. `'16 / 9'`). */
+    ratio?: string;
+}
+/** An image that fills its box, with zoom and pan. A plain `<img>` moved by a CSS transform. */
+export declare class ImageCanvas extends Component<ImageCanvasConfig> {
+    protected baseCls: string;
+    private stage;
+    private img;
+    private status;
+    private zoom;
+    private x;
+    private y;
+    private pointers;
+    protected onRender(): void;
+    private bindZoom;
+    private pan;
+    /** Keeps the image covering the box, then moves it. */
+    private paint;
+    /** Zooms to `level` (1 to `maxZoom`), keeping the point under the pointer (client coordinates) still; the centre by default. */
+    zoomTo(level: number, clientX?: number, clientY?: number): void;
+    zoomBy(factor: number, clientX?: number, clientY?: number): void;
+    reset(): void;
+    getZoom(): number;
+    setSrc(src: string): void;
+    setAlt(alt: string): void;
+    setFit(fit: 'contain' | 'cover'): void;
+}

package/dist/types/components/carousel.d.ts

@@ -0,0 +1 @@
+export * from '../components/layout/carousel/carousel.js';

package/dist/types/components/chart.d.ts

@@ -0,0 +1 @@
+export * from '../components/charts/chart/chart.js';

package/dist/types/components/charts/chart/chart.d.ts

@@ -0,0 +1,64 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+import { type Formatter } from '../../../data/format.js';
+import type { Store } from '../../../data/store.js';
+export interface ChartSeries {
+    /** Record field with the value. */
+    field: string;
+    /** Name in the legend and tooltip. Default: the field. */
+    label?: string;
+    /** Any CSS color. Default: the theme's `--op-chart-N` in order. */
+    color?: string;
+}
+export interface ChartConfig extends ComponentConfig {
+    kind?: 'bar' | 'line' | 'area' | 'pie' | 'donut' | 'sparkline';
+    /** Records. Give `data` or a `store` (any change of the store repaints the chart). */
+    data?: Array<Record<string, any>>;
+    store?: Store<any>;
+    /** Field with the category: the x axis, or the name of each slice. */
+    x: string;
+    /** Series to draw (a field name, or an object). A pie and a donut draw the first one. */
+    series: Array<string | ChartSeries>;
+    /** `bar` and `area` pile the series up instead of putting them side by side. */
+    stacked?: boolean;
+    /** Default: shown when there is more than one series, or for a pie. */
+    legend?: boolean;
+    /** Name of a registered format (`money`, `number`, `percent`...) or a function, for the axis and the tooltip. Default `number`. */
+    format?: string | Formatter;
+    /** Accessible name; also the caption of the data table read by screen readers. */
+    title?: string;
+    /** Height in px. Default 240 (sparkline 36). */
+    height?: number;
+}
+/** Bar, line, area, pie, donut and sparkline charts in SVG. Colors come from the theme (`--op-chart-1`...), so dark mode and white-label just work. */
+export declare class Chart extends Component<ChartConfig> {
+    protected baseCls: string;
+    private svg;
+    private plot;
+    private tip;
+    private legendEl;
+    private sr;
+    private hidden;
+    private rows;
+    private active;
+    private geom;
+    private queued;
+    private offStore?;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    private bindStore;
+    setStore(store: Store<any>): void;
+    setData(data: Array<Record<string, any>>): void;
+    setKind(kind: NonNullable<ChartConfig['kind']>): void;
+    setSeries(series: ChartConfig['series']): void;
+    private series;
+    private fmt;
+    private isPie;
+    private slices;
+    private paint;
+    private paintXY;
+    private paintPie;
+    private paintLegend;
+    private paintTable;
+    private activate;
+    private onKey;
+}

package/dist/types/components/charts/stat/stat.d.ts

@@ -0,0 +1,34 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+import { type Formatter } from '../../../data/format.js';
+export interface StatConfig extends ComponentConfig {
+    label: string;
+    value?: number | string | null;
+    /** Name of a registered format (`money`, `percent`...) or a function, for a numeric `value`. */
+    format?: string | Formatter;
+    /** The change since the last period, as a fraction (`0.125` shows `+12.5%`). */
+    delta?: number;
+    /** Which way is good news. `down` for costs, errors or waiting times. Default `up`. */
+    good?: 'up' | 'down';
+    /** Small text under the value ("vs last week"). */
+    caption?: string;
+    icon?: string;
+    /** Numbers for a sparkline beside the value. */
+    trend?: number[];
+}
+/** A KPI tile: a label, a big value, the change since last time and an optional sparkline. */
+export declare class Stat extends Component<StatConfig> {
+    protected baseCls: string;
+    private labelEl;
+    private valueEl;
+    private deltaEl;
+    private captionEl;
+    private chart?;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    setLabel(label: string): void;
+    setValue(value: number | string | null): void;
+    setDelta(delta: number | undefined): void;
+    setCaption(caption: string): void;
+    setTrend(trend: number[] | undefined): void;
+    protected onDestroy(): void;
+}

package/dist/types/components/data/cellediting/cellediting.d.ts

@@ -1,8 +1,11 @@
+import type { Column } from '../../../data/column.js';
 import type { GridPlugin } from '../grid/grid.js';
 export interface CellEditingOptions {
     /** What starts editing with the pointer: a double click (default) or a single click. F2 and Enter always do. */
     trigger?: 'dblclick' | 'click';
 }
+/** The field config for a column's editor: from `editor`, else from the type of the current value. */
+export declare function editorConfig(col: Column, value: unknown): Record<string, any>;
 /**
  * Inline editing plugin. Events on the grid: `before-edit(record, field)` (cancelable), `edit(record, field, value, old)`
  * after a valid value was written to the record (`record.set`, so it is marked modified), `edit-cancel(record, field)`.

package/dist/types/components/data/grid/grid.d.ts

@@ -41,6 +41,21 @@ export interface GridPlugin<T extends Record<string, any> = any> {
     init(grid: Grid<T>): void | (() => void);
     destroy?(): void;
 }
+/**
+ * One displayed row. Without a row layout every store record is a row; a plugin (grouping, tree) replaces the list with
+ * its own, mixing records with rows that are not records (a group header, a total).
+ */
+export interface RowEntry<T extends Record<string, any> = any> {
+    /** The record this row shows; absent on a header or total row (which cannot be selected). */
+    rec?: Model<T>;
+    /** `aria-level` and, with `expanded`, `aria-expanded`: for rows that open and close (a group, a tree node). */
+    level?: number;
+    expanded?: boolean;
+    /** Extra classes on the row (`op-grid__row--group`...). */
+    cls?: string;
+    /** Fills the row's cells after the grid did (or, on a row without a record, instead of it). */
+    paint?(cells: HTMLElement[], row: HTMLElement): void;
+}
 /** What `cellAt` finds under a DOM node: the row index, its record, the column and the cell element. */
 export interface GridCell<T extends Record<string, any> = any> {
     index: number;
@@ -52,12 +67,16 @@ export interface GridAction<T extends Record<string, any> = any> {
     text: string;
     icon?: string;
     variant?: 'default' | 'danger';
+    /** Left out (or disabled) while `setPermissionResolver` denies it. */
+    permission?: string;
     handler: (records: Model<T>[], grid: Grid<T>) => void;
 }
 export interface GridRowAction<T extends Record<string, any> = any> {
     text: string;
     icon?: string;
     variant?: 'default' | 'danger';
+    /** Left out (or disabled) while `setPermissionResolver` denies it. */
+    permission?: string;
     /** Disabled for the records where this returns true. */
     disabled?: (record: Model<T>) => boolean;
     handler: (record: Model<T>, grid: Grid<T>) => void;
@@ -66,6 +85,7 @@ export interface ColumnState {
     field: string;
     hidden: boolean;
     width?: number;
+    locked?: 'start' | 'end';
 }
 /** Data grid with a virtualized body: only the visible rows (plus a small overscan) exist in the DOM. */
 /** `T` is the record shape; `new Grid({ store })` infers it from a typed `Store<T>`. */
@@ -81,6 +101,8 @@ export declare class Grid<T extends Record<string, any> = any> extends Component
     private table;
     private pager?;
     private v;
+    private entries?;
+    private lockEdge;
     private selected;
     private active;
     private anchor;
@@ -99,6 +121,7 @@ export declare class Grid<T extends Record<string, any> = any> extends Component
     private colChips?;
     private colGroup;
     private cols;
+    /** Visible columns; the locked ones are kept together at their edge, whatever the order they were given or dragged to. */
     private userCols;
     private visibleActions;
     private mode;
@@ -113,6 +136,8 @@ export declare class Grid<T extends Record<string, any> = any> extends Component
     /** The active row index (keyboard cursor), or -1. */
     getActive(): number;
     notifyMount(): void;
+    /** The header follows the body sideways; its locked cells hold still, and the edges say when there is more to scroll. */
+    private onScrollX;
     /** Re-measures row height and scrollbar (needed after the grid becomes visible or resizes). */
     private layout;
     private bindStore;
@@ -120,8 +145,18 @@ export declare class Grid<T extends Record<string, any> = any> extends Component
     private sync;
     setStore(store: Store<T>): void;
     getStore(): Store<T>;
+    private count;
+    private recAt;
+    /** For plugins: replaces the displayed rows (`undefined` goes back to one row per store record) and repaints. */
+    setRowLayout(rows: RowEntry<T>[] | undefined): void;
+    /** The displayed row `i`: its record, or the header/total a plugin put there. */
+    getRowEntry(i: number): RowEntry<T> | undefined;
+    /** How many rows are displayed (records plus whatever a plugin added). */
+    getRowCount(): number;
     /** Column widths → the CSS grid template shared by the header and every row. */
     private layoutColumns;
+    /** Classes and offset of a locked cell (header or body); `n` is the column's place. */
+    private lock;
     private buildHeader;
     /** Labels over runs of neighbouring columns that share a group (a dragged column can split a group: it shows twice). */
     private groupBand;
@@ -129,6 +164,8 @@ export declare class Grid<T extends Record<string, any> = any> extends Component
     getColumnGroups(): string[];
     /** Shows or hides every column of a group at once (at least one column always stays visible). */
     setColumnGroupVisible(group: string, visible: boolean): void;
+    /** Pins a column to the start or the end while the body scrolls sideways (`null` releases it). A locked column needs a `width` (default 140). */
+    setColumnLocked(field: string, locked: 'start' | 'end' | null): void;
     setColumns(columns: Column[]): void;
     /** Order, visibility and width of every column; save it and give it back to `setColumnState`. */
     getColumnState(): ColumnState[];

package/dist/types/components/data/gridexport/gridexport.d.ts

@@ -0,0 +1,29 @@
+import type { Grid } from '../grid/grid.js';
+export interface ExportOptions {
+    format?: 'csv' | 'xlsx';
+    /** File name without extension. Default `export`. */
+    filename?: string;
+    /** `all` (default): every record that matches the sort and filters, across pages (a remote store is read through its proxy). `page`: what the grid shows now. */
+    scope?: 'all' | 'page';
+    /** Page size for reading a remote store. Default 500. */
+    pageSize?: number;
+    /** `false` only builds the file and returns it. Default true: the browser downloads it. */
+    download?: boolean;
+}
+/**
+ * Exports a grid: the visible columns in their current order, values as shown (money, dates...), the current sort and filters.
+ * Resolves with the file; downloads it unless `download: false`.
+ */
+export declare function exportGrid(grid: Grid, o?: ExportOptions): Promise<Blob>;
+export interface PrintOptions {
+    /** A heading above the table. */
+    title?: string;
+    /** `all` (default) prints every record that matches the filters, which the virtual list on screen does not render. */
+    scope?: 'all' | 'page';
+    pageSize?: number;
+}
+/**
+ * Prints a grid as a plain table: every row, the visible columns, the header repeated on each page, and none of the
+ * application around it. Resolves after the print dialog closed.
+ */
+export declare function printGrid(grid: Grid, o?: PrintOptions): Promise<void>;

package/dist/types/components/data/gridstate/gridstate.d.ts

@@ -0,0 +1,23 @@
+import type { GridPlugin, ColumnState } from '../grid/grid.js';
+import type { FilterNode, Sorter } from '../../../data/proxy.js';
+export interface GridState {
+    columns?: ColumnState[];
+    sorters?: Sorter[];
+    filters?: FilterNode[];
+    page?: number;
+    pageSize?: number;
+}
+export interface PersistOptions {
+    /** What to keep. All on by default. */
+    columns?: boolean;
+    sort?: boolean;
+    filters?: boolean;
+    page?: boolean;
+    /** ms to wait after a change before saving. Default 300. */
+    delay?: number;
+}
+/**
+ * Keeps widths, order and visibility of the columns, the sort, the filters, the page size and the page under `key`
+ * (`setStateStorage` decides where: the browser by default) and puts them back when the grid is created.
+ */
+export declare function persistState(key: string, o?: PersistOptions): GridPlugin;

package/dist/types/components/data/grouping/grouping.d.ts

@@ -0,0 +1,31 @@
+import type { Model } from '../../../data/model.js';
+import type { Column } from '../../../data/column.js';
+import type { GridPlugin } from '../grid/grid.js';
+export interface GroupingOptions {
+    /** Record field to group by. */
+    field?: string;
+    /** Or any function of the record (a year, a range): its result is the group. */
+    by?: (rec: Model) => unknown;
+    /** Text of a group header (before the count). Default: the key. */
+    label?: (key: unknown, recs: Model[]) => string;
+    /** Total rows of the columns that have a `summary`: `group` (under each group), `grand` (at the end) or `both`. Default `group`. */
+    summary?: 'group' | 'grand' | 'both';
+    /** Start with every group closed. */
+    collapsed?: boolean;
+}
+export interface Grouping extends GridPlugin {
+    expandAll(): void;
+    collapseAll(): void;
+    /** Changes what to group by; `null` shows the plain list. */
+    setGroupBy(by: string | ((rec: Model) => unknown) | null): void;
+    /** Opens or closes one group by its key. */
+    toggle(key: unknown, open?: boolean): void;
+}
+/** The value of a column's `summary` over some records. */
+export declare function summarize(col: Column, recs: Model[]): unknown;
+/**
+ * Groups the rows of the current page (a remote store groups what it loaded, not the whole set) under a header with
+ * its count; the header toggles by click, Enter/Space, → and ←. Sorting works inside each group. Group headers and total
+ * rows are virtual rows like any other. Fires `group-toggle(key, open)` on the grid.
+ */
+export declare function grouping(options?: GroupingOptions): Grouping;

package/dist/types/components/data/rowediting/rowediting.d.ts

@@ -0,0 +1,13 @@
+import type { GridPlugin } from '../grid/grid.js';
+export interface RowEditingOptions {
+    /** What starts editing with the pointer: a double click (default) or a single click. F2 and Enter always do. */
+    trigger?: 'dblclick' | 'click';
+}
+/**
+ * Edits every `editor` column of a row at once, under a bar with Save and Cancel. Enter saves, Esc cancels, Tab walks the
+ * editors and the buttons and wraps; Save validates every field and keeps the row open while one is invalid.
+ * Events on the grid: `before-edit(record)` (cancelable), `edit(record, values, old)` after the new values were written
+ * (`record.set`, so it is marked modified; a remote store's app saves from here), `cancel-edit(record)`.
+ * Use it instead of `cellEditing()`, not beside it.
+ */
+export declare function rowEditing(options?: RowEditingOptions): GridPlugin;

package/dist/types/components/data/searchgrid/searchgrid.d.ts

@@ -5,11 +5,18 @@ import type { Model } from '../../../data/model.js';
 import type { Column } from '../../../data/column.js';
 import type { FilterOp, FilterSpec } from '../../../data/proxy.js';
 import { Grid } from '../grid/grid.js';
-/** A filter field of a lookup: any field config, plus how its value is matched. */
-export type LookupFilter = AnyConfig & {
+/** A filter field of a lookup: a field config or a field instance (`ui.text(...)`); `op` and `field` say how its value is matched. */
+export type LookupFilter = (AnyConfig & {
     name: string;
     op?: FilterOp;
     field?: string;
+}) | Component;
+/** `name`, `op`, `field` and `type` of a filter, whether it was given as a config or an instance. */
+export declare const filterInfo: (f: LookupFilter) => {
+    name: string;
+    op?: FilterOp;
+    field?: string;
+    type?: string;
 };
 /** Everything that describes "search for a record": shared by SearchGrid and LookupField. */
 export interface LookupDef {

package/dist/types/components/data/timeline/timeline.d.ts

@@ -0,0 +1,60 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+import type { Store } from '../../../data/store.js';
+export interface TimelineItem {
+    id?: string | number;
+    title: string;
+    text?: string;
+    icon?: string;
+    tone?: 'default' | 'success' | 'warning' | 'danger' | 'info';
+    /** `list`: when it happened (an ISO date or time, or any text). */
+    time?: string;
+    /** `range`: ISO dates or date-times. */
+    start?: string;
+    end?: string;
+    /** `range`: the row (a person, a room, a phase). */
+    lane?: string;
+}
+export interface TimelineConfig extends ComponentConfig {
+    /** `list`: events one under the other, with a marker (default). `range`: a schedule: bars over a time axis, one row per `lane`. */
+    mode?: 'list' | 'range';
+    items?: TimelineItem[];
+    /** Items from a Store (its records are `TimelineItem`s). */
+    store?: Store<any>;
+    /** `range`: the order of the rows. Default: order of appearance. */
+    lanes?: string[];
+    /** `range`: the window shown. Default: from the first start to the last end. */
+    from?: string;
+    to?: string;
+    /** `range`: a marker at the current time. Default true. */
+    now?: boolean;
+    /** Optional features (`timeEntry()`...). See `TimelinePlugin`. */
+    plugins?: TimelinePlugin[];
+}
+/** Extends a Timeline without growing its base: `init` runs once it is rendered and may return a cleanup. The timeline fires `paint` after every repaint. */
+export interface TimelinePlugin {
+    init(timeline: Timeline): void | (() => void);
+}
+/** The time axis of a `range` timeline: its ends in ms, and how to read and write the item dates (`clock`: `'HH:mm'` of one day, else ISO). */
+export interface TimelineScale {
+    lo: number;
+    hi: number;
+    clock: boolean;
+    parse(v: string): number;
+    format(ms: number): string;
+}
+/** Events as a vertical list, or a schedule (phases, staff shifts) as bars on a time axis. Click or Enter on an item fires `select`. */
+export declare class Timeline extends Component<TimelineConfig> {
+    protected baseCls: string;
+    private items;
+    private scale?;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    private pick;
+    getItems(): TimelineItem[];
+    /** The time axis of a `range` timeline (set by the last paint), for plugins. */
+    getScale(): TimelineScale | undefined;
+    setItems(items: TimelineItem[]): void;
+    private paint;
+    private list;
+    private range;
+}

package/dist/types/components/data/treegrid/treegrid.d.ts

@@ -0,0 +1,32 @@
+import type { Model } from '../../../data/model.js';
+import type { GridPlugin } from '../grid/grid.js';
+export interface TreeGridOptions {
+    /** Column that shows the indentation and the expander. Default: the first one. */
+    treeColumn?: string;
+    /** Field that holds the parent's id (`null` or missing: a root). Default `parentId`. */
+    parentField?: string;
+    /** Loads the children of a node the first time it opens: resolves with their rows (the plugin sets `parentField` and adds them to the store). Without it every node is already in the store. */
+    load?: (node: Model) => Promise<Array<Record<string, any>>> | Array<Record<string, any>>;
+    /** With `load`: the field that says a node has no children (default `leaf`), so it gets no expander. */
+    leafField?: string;
+    /** Start with every node open. */
+    expanded?: boolean;
+}
+export interface TreeGrid extends GridPlugin {
+    expand(id: string | number): void;
+    collapse(id: string | number): void;
+    expandAll(): void;
+    collapseAll(): void;
+}
+/** Nested data (`{ id, name, children: [...] }`) → the flat rows the plugin wants, each with its `parentId`. */
+export declare function flattenTree<T extends Record<string, any>>(nodes: T[], o?: {
+    children?: string;
+    parentField?: string;
+}, parent?: unknown): Array<Record<string, any>>;
+/**
+ * Indents each record under its parent with an expander; ←/→ close/open and walk to the parent/first child (ARIA treegrid),
+ * click on the chevron toggles. The rest of the columns are ordinary: format, renderer, sort (siblings), resize, lock.
+ * A record whose parent is filtered out (or not on the page) shows as a root. Events on the grid: `expand-node(record)`,
+ * `collapse-node(record)`, `load-error(record, error)`.
+ */
+export declare function treeGrid(options?: TreeGridOptions): TreeGrid;

package/dist/types/components/datetimefield.d.ts

@@ -0,0 +1 @@
+export * from '../components/fields/datetimefield/datetimefield.js';