@pythia-software/query-table-react 0.2.0 → 0.4.0

package/README.md

@@ -20,6 +20,11 @@ function Orders({ schema, rows }) {
 }
 ```
 
+`table.selection.replace(ids)` atomically makes any iterable of stable row IDs
+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.
+
 ## Privacy defaults
 
 URL synchronization and durable browser storage are disabled by default. Set
@@ -31,3 +36,21 @@ is appropriate; sensitive applications should use an access-controlled server
 
 See the [repository README](https://github.com/Pythia-Software/query-table#readme)
 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.
+
+### Canonical keys and unavailable filters
+
+`useQueryTable` accepts two optional pure callbacks:
+
+- `canonicalizeQuery(query)` returns a query with external aliases resolved. It must
+  not throw. The returned query drives evaluation, sharing, and saved state.
+- `validateQuery(query)` may throw an actionable error before row or metric execution.
+  Both local and server transports honor it, including restored queries. Rejection
+  clears results/totals while retaining the query so the user can repair its filters.
+
+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.

package/dist/index.d.ts

@@ -1,4 +1,21 @@
-import { RowId, SelectColumn, FieldDef, QueryState, FieldSchema, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, WhereClause, DistinctValuesResult, OrderByClause, Transport } 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 } from '@pythia-software/query-table-core';
+
+type FormulaWorkerFactory = () => Worker;
+/** Host applications with a restrictive CSP can supply their own worker factory. */
+declare const createFormulaWorker: FormulaWorkerFactory;
+declare function evaluateFormulaRows(ast: FormulaNode, inputs: Record<string, FormulaValue>[], signal?: AbortSignal, factory?: FormulaWorkerFactory): Promise<FormulaResult[]>;
+
+interface ComputedColumnsApi<Row> {
+    definitions: ComputedColumn[];
+    catalogue: FieldDef<Row>[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+    save: (column: ComputedColumnDraft, expectedRevision: string | null) => Promise<ComputedColumn>;
+    compile: (source: string, editingId?: string) => FormulaPlan;
+    /** Sample the first N matching rows in current sort order, independent of table paging. */
+    preview: (source: string, count: number, signal?: AbortSignal, editingId?: string, includeInputs?: boolean) => Promise<ColumnPreview>;
+}
 
 interface SelectionApi {
     selected: Set<RowId>;
@@ -9,6 +26,10 @@ interface SelectionApi {
     toggle: (id: RowId, shiftKey?: boolean) => void;
     /** Select / clear every row currently on the page. */
     setPage: (ids: RowId[], selected: boolean) => void;
+    /** Atomically replace the complete selection with arbitrary stable row ids. */
+    replace: (ids: Iterable<RowId>) => void;
+    /** Atomically retain only selected ids that are also present in `ids`. */
+    retain: (ids: Iterable<RowId>) => void;
     /** Header checkbox tri-state for the current page. */
     pageState: (pageIds: RowId[]) => "none" | "some" | "all";
     clear: () => void;
@@ -76,6 +97,10 @@ declare function useSavedQueries(key: string, currentQuery: QueryState, applyQue
 now: () => number): SavedQueriesApi;
 
 interface UseQueryTableOptions<Row> {
+    /** Normalize external aliases without storing presentation in query state. Must be pure and not throw. */
+    canonicalizeQuery?: (query: QueryState) => QueryState;
+    /** Reject an entire query before rows or metrics execute. Errors retain editable query state. */
+    validateQuery?: (query: QueryState) => void;
     schema: FieldSchema<Row>;
     /** Data access. Omit for a purely client-side table driven by `clientRows`. */
     transport?: Transport<Row>;
@@ -85,6 +110,10 @@ interface UseQueryTableOptions<Row> {
      * Pass localStorageAdapter() explicitly only when filter values are safe to
      * retain as cleartext JSON on the device. */
     storage?: StorageAdapter;
+    /** Shared reusable definitions, independent of saved-query storage. */
+    computedColumnStore?: ComputedColumnStore;
+    /** Override the worker factory when CSP disallows blob workers. */
+    formulaWorkerFactory?: FormulaWorkerFactory;
     /** Seed query, normalized and resource-bounded before use. When omitted the
      * hook resolves: opted-in URL → storage.loadLast → schema defaults. */
     initialQuery?: QueryState;
@@ -168,17 +197,36 @@ interface QueryTableApi<Row> {
     autoRefresh: AutoRefreshApi;
     refreshRow: (id: RowId) => Promise<void>;
     aggregations: AggregationsApi;
+    /** Append a predicate as its own AND term. */
     addFilter: (clause: WhereClause) => void;
+    /** Replace the whole term at `index` with a single predicate. */
     updateFilter: (index: number, clause: WhereClause) => void;
+    /** Remove the whole term at `index`. */
     removeFilter: (index: number) => void;
     clearFilters: () => void;
+    /** Replace one predicate inside a term (predIndex 0 for a literal term). */
+    updatePredicate: (termIndex: number, predIndex: number, clause: WhereClause) => void;
+    /** Remove one predicate; a group of one flattens to a literal, an emptied term drops. */
+    removePredicate: (termIndex: number, predIndex: number) => void;
+    /** Logically invert one predicate (flips the op, else toggles its NOT flag). */
+    negatePredicate: (termIndex: number, predIndex: number) => void;
+    /** Move the term at `fromIndex` to `toIndex` (an index in the list with the
+     *  dragged term removed, so a drag preview's slot maps straight to the result). */
+    reorderFilters: (fromIndex: number, toIndex: number) => void;
+    /** OR-merge the term at `sourceIndex` into the term at `targetIndex`: the
+     *  target becomes (or stays) an OR group holding both terms' predicates, and
+     *  the source term is removed. This is the drag-onto-another-filter gesture. */
+    mergeFilters: (sourceIndex: number, targetIndex: number) => void;
     /** Reset the complete query state back to schema defaults. */
     resetAll: () => void;
     /** Keystroke-driven filter-value autocomplete (Transport.fetchDistinctValues). */
     filterValues: (field: string, search: string) => Promise<DistinctValuesResult>;
+    /** Dataset-wide field statistics for catalogue and picker affordances. */
+    fieldStats: (fields: string[], signal?: AbortSignal) => Promise<Record<string, FieldStats>>;
     toggleSort: (field: string, additive?: boolean) => void;
     setSort: (orderBy: OrderByClause[]) => void;
     select: SelectApi<Row>;
+    computed: ComputedColumnsApi<Row>;
     setLimit: (limit: number) => void;
     setOffset: (offset: number) => void;
     nextPage: () => void;
@@ -197,6 +245,6 @@ interface AggregationsApiState {
     loading: boolean;
     error: Error | null;
 }
-declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number): AggregationsApiState;
+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;
 
-export { type AggregationPatch, type AggregationsApi, type AggregationsApiState, type AutoRefreshApi, type AutoRefreshConfig, type AutoRefreshStatus, type ColumnDragApi, type QueryTableApi, type SavedQueriesApi, type SelectApi, type SelectionApi, type UseQueryTableOptions, 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 SavedQueriesApi, type SelectApi, type SelectionApi, type UseQueryTableOptions, createFormulaWorker, evaluateFormulaRows, useAggregations, useColumnDrag, useQueryTable, useSavedQueries, useSelect, useSelection };