@pythia-software/query-table-react 0.4.2 → 0.6.0

package/README.md

@@ -25,6 +25,11 @@ the complete selection, including IDs outside the displayed page.
 `table.selection.retain(ids)` atomically intersects the current selection with
 an iterable. Both operations reset the Shift-click range anchor.
 
+Without `transport.fetchDistinctValues`, `table.filterValues(field, search)`
+uses `clientRows` for autocomplete. For `textarray` fields it suggests individual
+array elements, deduplicated and matched case-insensitively by substring. Local
+suggestions are capped at 50 values, with `hasMore` indicating additional matches.
+
 ## Privacy defaults
 
 URL synchronization and durable browser storage are disabled by default. Set
@@ -39,7 +44,7 @@ for transport and schema examples.
 
 ## Shared computed column definitions
 
-Pass a stable `computedColumnStore` (for example, `httpComputedColumnStore("/api/computed-columns")` from core) to `useQueryTable`. `api.computed` exposes the catalogue, compile/preview, save with revision checking, and reload operations. Queries store only `@computed/<id>` SELECT references; formula evaluation stays in browser workers. Without a store, definitions are in memory for the mounted hook. See the repository’s `docs/computed-columns.md` for the complete integration contract and PostgreSQL adapter.
+Pass a stable `computedColumnStore` (for example, `httpComputedColumnStore("/api/computed-columns")` from core) to `useQueryTable`. `api.computed` exposes the catalogue, compile/preview, save with revision checking, and reload operations. Queries store only `@computed/<id>` SELECT references. Local evaluation uses browser workers. With `fetchRowsV2` and an authoritative `computedExecution` envelope, computed SELECT and global sorting run on the server and values attach through validated stable-row-ID sidecars. Without a store, definitions are in memory for the mounted hook. See the repository’s `docs/computed-columns.md` for the complete integration contract and PostgreSQL adapter.
 
 ### Canonical keys and unavailable filters
 
@@ -54,3 +59,14 @@ Pass a stable `computedColumnStore` (for example, `httpComputedColumnStore("/api
 Memoize these callbacks and change their identity when external validation metadata
 changes. Return immutable query values from the canonicalizer. No callback is required
 for ordinary tables; the existing execution behavior remains the default.
+
+For native set editors, use core's `mapSetFilterValues(query.where, (field, key) =>
+canonicalKey)` inside `canonicalizeQuery` to update aliases in both the existing
+predicates and their editor identity. Leave unrecognized/deleted keys unchanged
+and reject them through `validateQuery` so users can repair the selected tags.
+
+## Metric execution and drafts
+
+`api.aggregations.preview(clauses, signal)` evaluates a draft without modifying the query. `replace(clauses, expected?)` commits the entire dashboard as one undoable change and can reject a stale editor baseline. Presentation-only changes reuse computation. Advanced remote execution uses `fetchMetrics` plus explicit v2 `metricCapabilities`; v1 transports continue to support representable simple metrics. All-matching scope requires the complete client dataset or a server metric service. Shown-row fallback uses committed inputs and reports missing dependencies.
+
+See [the metrics integration guide](../../docs/metrics.md) for scopes, cancellation, worker-isolated regex, capability negotiation, computed revisions, and snapshot requirements.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, RowId, SelectColumn, QueryState, FieldSchema, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, WhereClause, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedColumnStore } from '@pythia-software/query-table-core';
+import { FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, RowId, SelectColumn, QueryState, FieldSchema, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, WhereClause, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedColumnStore, ComputedExecution } from '@pythia-software/query-table-core';
 
 type FormulaWorkerFactory = () => Worker;
 /** Host applications with a restrictive CSP can supply their own worker factory. */
@@ -17,6 +17,20 @@ interface ComputedColumnsApi<Row> {
     preview: (source: string, count: number, signal?: AbortSignal, editingId?: string, includeInputs?: boolean) => Promise<ColumnPreview>;
 }
 
+interface RequestActivityEntry {
+    id: number;
+    kind: string;
+    startedAt: number;
+    status: "pending" | "success" | "error" | "aborted";
+    durationMs?: number;
+    error?: string;
+}
+interface RequestActivityApi {
+    /** Newest first; bounded to the latest 100 calls. Query values and results are never retained. */
+    entries: readonly RequestActivityEntry[];
+    clear: () => void;
+}
+
 interface SelectionApi {
     selected: Set<RowId>;
     isSelected: (id: RowId) => boolean;
@@ -65,12 +79,14 @@ interface ColumnDragApi {
     overIndex: number | null;
     /** True while a column drag is in progress. */
     active: boolean;
-    /** Begin dragging `field`, initially previewed at `index` (its own slot). */
-    start: (field: string, index: number) => void;
-    /** Update the previewed insertion index (no-op if unchanged). */
-    over: (index: number) => void;
+    /** Changes only for confirmed drops, so surfaces can persist auxiliary positions. */
+    dropRevision?: number;
+    /** Begin dragging `field` at `index`. Supply the surface order for cross-surface mapping. */
+    start: (field: string, index: number, order?: string[]) => void;
+    /** Update the insertion slot and optional surface order (no-op if unchanged). */
+    over: (index: number, order?: string[]) => void;
     /** End the drag (on drop or cancel). */
-    end: () => void;
+    end: (committed?: boolean) => void;
     /** The live order to render while dragging: `source` moved to `overIndex`.
      *  Returns `order` unchanged when idle, or when `source` isn't in `order`. */
     preview: (order: string[]) => string[];
@@ -112,6 +128,8 @@ interface UseQueryTableOptions<Row> {
     storage?: StorageAdapter;
     /** Shared reusable definitions, independent of saved-query storage. */
     computedColumnStore?: ComputedColumnStore;
+    /** Authoritative host handshake for versioned server SELECT, sorts, and metrics. */
+    computedExecution?: ComputedExecution;
     /** Override the worker factory when CSP disallows blob workers. */
     formulaWorkerFactory?: FormulaWorkerFactory;
     /** Seed query, normalized and resource-bounded before use. When omitted the
@@ -150,12 +168,12 @@ interface AutoRefreshApi {
 /** A patch for one metric. `field`/`label` accept an explicit `undefined` to
  *  CLEAR them (e.g. switching to an op whose measure no longer applies); an
  *  absent key leaves the existing value untouched. */
-interface AggregationPatch {
+type AggregationPatch = {
     op?: AggOp;
-    field?: string | undefined;
     groupBy?: string[];
-    label?: string | undefined;
-}
+} & {
+    [K in keyof Omit<AggregationClause, "id" | "op" | "groupBy">]?: AggregationClause[K] | undefined;
+};
 interface AggregationsApi {
     /** The metric specs currently in the query. */
     clauses: AggregationClause[];
@@ -175,6 +193,14 @@ interface AggregationsApi {
     remove: (id: string) => void;
     /** Remove all metrics. */
     clear: () => void;
+    /** Evaluate a draft without modifying the query. */
+    preview?: (clauses: AggregationClause[], signal?: AbortSignal) => Promise<AggregationResult>;
+    /** Commit the complete draft as one undoable change. */
+    replace?: (clauses: AggregationClause[], expected?: AggregationClause[]) => void;
+    /** Validate a clause, including reusable computed dependencies. */
+    compile?: (clause: AggregationClause) => unknown;
+    /** Invalidation token for page, refresh, schema, and definition changes. */
+    contextKey?: string;
 }
 interface QueryTableApi<Row> {
     query: QueryState;
@@ -189,12 +215,15 @@ interface QueryTableApi<Row> {
     undo: () => void;
     /** Move forward through local, unsaved query history. */
     redo: () => void;
+    requestActivity: RequestActivityApi;
     rows: Row[];
     total: number | null;
     loading: boolean;
     error: Error | null;
     refresh: () => void;
     autoRefresh: AutoRefreshApi;
+    /** Refresh one legacy row, or schedule a full V2 page refresh so computed
+     * values and page membership remain coherent. Track V2 completion via loading/error. */
     refreshRow: (id: RowId) => Promise<void>;
     aggregations: AggregationsApi;
     /** Append a predicate as its own AND term. */
@@ -240,11 +269,27 @@ interface QueryTableApi<Row> {
 }
 declare function useQueryTable<Row>(opts: UseQueryTableOptions<Row>): QueryTableApi<Row>;
 
+interface MetricExecutionContext<Row> {
+    schema: FieldSchema<Row>;
+    transport?: Transport<Row> | undefined;
+    clientRows?: Row[] | undefined;
+    shownRows?: Row[] | undefined;
+    rowsReady?: boolean | undefined;
+    rowsError?: Error | null | undefined;
+    shownFields?: readonly string[] | undefined;
+    resolveComputed?: ((name: string) => FormulaPlan | undefined) | undefined;
+    workerFactory?: FormulaWorkerFactory | undefined;
+    revisions?: Record<string, string> | undefined;
+    execution?: ComputedExecution;
+}
+
 interface AggregationsApiState {
     results: AggregationResult | null;
     loading: boolean;
     error: Error | null;
+    preview: (clauses: AggregationClause[], signal?: AbortSignal) => Promise<AggregationResult>;
 }
-declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number, validateQuery?: (query: QueryState) => void): AggregationsApiState;
+/** Fetch state is keyed by computation and scope, never card presentation. */
+declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number, validateQuery?: (q: QueryState) => void, options?: Omit<MetricExecutionContext<Row>, "schema" | "transport" | "clientRows">): AggregationsApiState;
 
-export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type ComputedColumnsApi, type FormulaWorkerFactory, type QueryTableApi, type SavedQueriesApi, type SelectApi, type SelectionApi, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, useQueryTable, useSavedQueries, useSelect, useSelection };
+export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type ComputedColumnsApi, type FormulaWorkerFactory, type QueryTableApi, type RequestActivityApi, type RequestActivityEntry, type SavedQueriesApi, type SelectApi, type SelectionApi, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, useQueryTable, useSavedQueries, useSelect, useSelection };