@pythia-software/query-table-react 0.1.0 → 0.3.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,7 @@ 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.

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, 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;
@@ -85,6 +106,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,10 +193,26 @@ 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). */
@@ -179,6 +220,7 @@ interface QueryTableApi<Row> {
     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;
@@ -199,4 +241,4 @@ interface AggregationsApiState {
 }
 declare function useAggregations<Row>(query: QueryState, schema: FieldSchema<Row>, transport: Transport<Row> | undefined, clientRows: Row[] | undefined, debounceMs: number, nonce: number): 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 };