@pythia-software/query-table-react 0.9.9 → 1.0.0

package/README.md

@@ -53,8 +53,9 @@ 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
+With a transport, `table.filterValues(field, search, signal?)` sends a v3
+`distinct` request (core's `fetchDistinctValuesV3`) for server-filterable fields;
+aborting the signal cancels it. Without one it 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.
 
@@ -108,11 +109,11 @@ api.setDefinition(previous => ({ query: { ...previous.query, offset: 0 }, hostSt
 `hostState` is `{ version, params: Record<string, string[]> }`. It rides in
 `QueryState.hostState`, so history, saves, `encodeQuery` links and durable
 `@…` snapshots carry it with the query, within the existing size budgets.
-Every request the table sends carries the `hostState` it runs with
-(`ServerQuery`, `ServerQueryV2`, `QueryRequestV3`, `MetricQuery`,
-`AggregationRequest` and distinct-value requests), so the host's transport
-never sees one definition's table query with another's host state; the Go
-request types accept and expose it without interpreting it.
+Every `QueryRequestV3` the table sends carries the `hostState` it runs with,
+including filter suggestions, row lookups and field statistics (opt-in with
+`remoteFieldStats: true`, since each reduces the whole dataset), so the host's
+transport never sees one definition's table query with another's host state;
+the Go request types accept and expose it without interpreting it.
 
 - One `setDefinition` is one history entry and one execution. Edits through
   `setQuery` keep the current host state unless they set one.
@@ -160,7 +161,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. 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.
+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 an authoritative `computedExecution` envelope, computed SELECT and global sorting run on the v3 server and values arrive inline in the rows, validated against the requested revisions. 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
 
@@ -183,7 +184,7 @@ 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.
+`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. With a transport, every metric batch is one v3 request (`rows: false`); a clause using a population control the server's `queryCapabilities` does not advertise fails on its own. All-matching scope requires the complete client dataset or a transport. Without a transport, shown-row metrics use the committed page and report missing dependencies.
 
 See [the metrics integration guide](../../docs/metrics.md) for scopes, cancellation, worker-isolated regex, capability negotiation, computed revisions, and snapshot requirements.
 
@@ -194,14 +195,11 @@ while `clientRows` continues through local filtering, sorting, and paging.
 selection. Computed grouping choices in `api.computed.catalogue` use the metric
 transport and handshake, including definition revisions; row selection,
 filtering, sorting, and value access keep their row capabilities.
-Use `metricRowsReady(query)` to confirm that the external row window
-matches the current query and origin before local shown-row evaluation or
-previews. Remote `allMatching` metrics run while that gate is false.
-
-A V2 transport must explicitly advertise `metricCapabilities.shownRows: true`
-to execute supported shown-row clauses remotely. False or omitted uses the
-committed page, provided its inputs are loaded. See the
-[migration example](../../docs/metrics.md#independent-remote-metrics).
+A metric transport executes every clause, shown-row ones included, on the
+server. Use `metricRowsReady(query)` to confirm that a local row window matches
+the current query and origin before local shown-row evaluation or previews
+(tables without a metric transport). See the
+[example](../../docs/metrics.md#independent-remote-metrics).
 
 Standalone `useAggregations` calls with a complete client dataset derive the
 shown page when readiness options are omitted. An explicit `rowsReady: false`

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FieldSchema, WhereClause, QueryState, GroupedRow, GroupingModel, GroupingView, GroupKey, SummaryOp, RepresentativeRow, SummaryColumn, SelectColumn, PropertyViewState, SavedPropertyView, PropertyViewStorage, QueryLink, QuerySnapshot, ScopedJsonInspectionState, AttentionRegistry, ItemPropertyMode, ItemPageOptions, ItemDetailMode, ItemDetailsState, RelationshipAdapter, RowId, FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, HostQueryState, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedExecution, ComputedColumnStore, QueryLinkOptions, ObjectReference, ResolvedObjectReference } from '@pythia-software/query-table-core';
+import { FieldSchema, WhereClause, QueryState, GroupedRow, GroupingModel, GroupingView, GroupKey, SummaryOp, RepresentativeRow, SummaryColumn, SelectColumn, PropertyViewState, SavedPropertyView, PropertyViewStorage, QueryLink, QuerySnapshot, ScopedJsonInspectionState, AttentionRegistry, ItemPropertyMode, ItemPageOptions, ItemDetailMode, ItemDetailsState, RelationshipAdapter, RowId, FormulaNode, FormulaValue, FormulaResult, ComputedColumn, FieldDef, ComputedColumnDraft, FormulaPlan, ColumnPreview, SavedQuery, StorageAdapter, AggOp, AggregationClause, AggregationResult, QueryError, HostQueryState, DistinctValuesResult, FieldStats, OrderByClause, Transport, ComputedExecution, ComputedColumnStore, QueryLinkOptions, ObjectReference, ResolvedObjectReference } from '@pythia-software/query-table-core';
 
 /** Filter controls for either the result query or grouping's source query. */
 type QueryFilterApi<Row> = Pick<QueryTableApi<Row>, "query" | "setQuery" | "loading" | "addFilter" | "updateFilter" | "removeFilter" | "clearFilters" | "updatePredicate" | "removePredicate" | "negatePredicate" | "reorderFilters" | "mergeFilters" | "filterValues" | "fieldStats">;
@@ -114,7 +114,7 @@ interface ItemDetailsOptions<Row> {
     storage?: PropertyViewStorage;
     objectType?: string;
     relationships?: RelationshipAdapter;
-    /** Defaults to complete clientRows or Transport.fetchRow, then the current projected row. */
+    /** Defaults to complete clientRows or a v3 identity lookup, then the current projected row. */
     loadRow?: (id: RowId, signal: AbortSignal) => Promise<ItemDetailRecord<Row> | null>;
 }
 interface ItemDetailsApi<Row> {
@@ -216,7 +216,7 @@ interface SelectApi<Row> {
     hide: (field: string) => void;
     /** Reorder via drag-drop: move `field` to `toIndex` in the visible order. */
     move: (field: string, toIndex: number) => void;
-    /** Set a column's pixel width. */
+    /** Set a column's pixel width. Other columns keep any live `fit`. */
     setWidth: (field: string, width: number) => void;
     /** Reset to the schema's default columns (clears query.select). */
     reset: () => void;
@@ -327,6 +327,11 @@ interface UseQueryTableOptions<Row> {
     links?: QueryLinkOptions;
     /** Enable schema-driven click popovers, item modals and row expansion. */
     itemDetails?: boolean | ItemDetailsOptions<Row>;
+    /** Ask the transport for field statistics (distinct count, min, max) when
+     * the column picker or a metric filter editor opens. Each request reduces
+     * the whole dataset, so it is off by default; complete clientRows always
+     * provide them. */
+    remoteFieldStats?: boolean;
     /** Debounce (ms) between a query change and the fetch it triggers. Default 200. */
     debounceMs?: number;
     /** Injected clock for deterministic saved-query timestamps. Default Date.now. */
@@ -368,7 +373,8 @@ interface AggregationsApi {
     /** Server (or client-mirror) results, one entry per clause; null when none. */
     results: AggregationResult | null;
     loading: boolean;
-    error: Error | null;
+    /** A QueryError (with a code from docs/errors.md) for server and client refusals. */
+    error: QueryError | Error | null;
     /** Append a metric. Defaults to "count all rows"; pass a partial to override.
      *  Returns the generated id. */
     add: (partial?: Partial<Omit<AggregationClause, "id">>) => string;
@@ -424,14 +430,15 @@ interface QueryExecutionReceipt {
     /** "none" when the query has no metrics. A metric error fails the receipt. */
     metrics: "none" | "running" | "succeeded" | "failed";
     /** The row or metric error behind a failure. */
-    error: Error | null;
+    /** A QueryError (with a code from docs/errors.md) for server and client refusals. */
+    error: QueryError | Error | null;
 }
 interface QueryTableApi<Row> {
     /** Dependent source fetches can use ready without parsing display errors. */
     restoration: {
         status: "resolving" | "ready" | "error";
         ready: boolean;
-        error: Error | null;
+        error: QueryError | Error | null;
     };
     /** Execution of the current query, separate from restoration. Null while
      * restoring, after a restoration error and while the table is inactive, so
@@ -472,11 +479,13 @@ interface QueryTableApi<Row> {
     rows: Row[];
     total: number | null;
     loading: boolean;
-    error: Error | null;
+    /** A QueryError (with a code from docs/errors.md) for server and client refusals. */
+    error: QueryError | 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. */
+    /** Refresh one row in place through a v3 identity lookup. A grouped page or
+     * one with computed columns or sorts refreshes as a whole instead, so computed
+     * values and page membership remain coherent; track that through loading/error. */
     refreshRow: (id: RowId) => Promise<void>;
     aggregations: AggregationsApi;
     /** Append a predicate as its own AND term. */
@@ -502,8 +511,9 @@ interface QueryTableApi<Row> {
     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>;
+    /** Keystroke-driven filter-value autocomplete (a v3 `distinct` request, or
+     * the complete clientRows). Aborting the signal cancels the request. */
+    filterValues: (field: string, search: string, signal?: AbortSignal) => 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;
@@ -524,6 +534,7 @@ interface QueryTableApi<Row> {
 declare function useQueryTable<Row>(opts: UseQueryTableOptions<Row>): QueryTableApi<Row>;
 
 interface MetricExecutionContext<Row> {
+    /** Remote execution; defaults to executeV3Metrics over `transport`. */
     executeV3?: (query: QueryState, signal?: AbortSignal) => Promise<AggregationResult>;
     queryContextKey?: string;
     schema: FieldSchema<Row>;
@@ -546,7 +557,7 @@ interface MetricExecutionContext<Row> {
 interface AggregationsApiState {
     results: AggregationResult | null;
     loading: boolean;
-    error: Error | null;
+    error: QueryError | Error | null;
     preview: (clauses: AggregationClause[], signal?: AbortSignal) => Promise<AggregationResult>;
 }
 /** Fetch state is keyed by computation and scope, never card presentation. */