@pythia-software/query-table-react 0.9.6 → 0.9.8

package/dist/index.js

@@ -1,11 +1,28 @@
 // src/useQueryFilters.ts
 import { useCallback, useMemo } from "react";
 import {
+  branchesOf,
   isOrGroup,
-  predicatesOf,
+  isWhereConjunction,
   negateClause,
   opsForField
 } from "@pythia-software/query-table-core";
+function editBranchPredicate(term, predIndex, edit) {
+  let k = 0;
+  const any = [];
+  for (const member of term.any) {
+    const kept = [];
+    for (const clause of isWhereConjunction(member) ? member.all : [member]) {
+      const next = k++ === predIndex ? edit(clause) : clause;
+      if (next) kept.push(next);
+    }
+    if (kept.length === 1) any.push(kept[0]);
+    else if (kept.length > 1) any.push({ all: kept });
+  }
+  if (any.length > 1) return [{ any }];
+  const only = any[0];
+  return !only ? [] : isWhereConjunction(only) ? only.all : [only];
+}
 function useQueryFilters(schema, setQuery) {
   const byName = useMemo(
     () => new Map(schema.fields.map((field) => [field.name, field])),
@@ -45,8 +62,9 @@ function useQueryFilters(schema, setQuery) {
           return {
             any: term.any.map((c, j) => j === predIndex ? clause : c)
           };
+        if ("any" in term) return editBranchPredicate(term, predIndex, () => clause);
         return clause;
-      })
+      }).flat()
     })),
     [setQuery]
   );
@@ -64,6 +82,10 @@ function useQueryFilters(schema, setQuery) {
           else if (members.length > 1) where.push({ any: members });
           return;
         }
+        if ("any" in term) {
+          where.push(...editBranchPredicate(term, predIndex, () => null));
+          return;
+        }
       });
       return { ...q, offset: 0, where };
     }),
@@ -86,8 +108,9 @@ function useQueryFilters(schema, setQuery) {
           return {
             any: term.any.map((c, j) => j === predIndex ? negateOne(c) : c)
           };
+        if ("any" in term) return editBranchPredicate(term, predIndex, negateOne);
         return negateOne(term);
-      })
+      }).flat()
     })),
     [setQuery, negateOne]
   );
@@ -108,7 +131,9 @@ function useQueryFilters(schema, setQuery) {
       const target = q.where[targetIndex];
       if (!source || !target) return q;
       const merged = {
-        any: [...predicatesOf(target), ...predicatesOf(source)]
+        any: [...branchesOf(target), ...branchesOf(source)].map(
+          (branch) => branch.length === 1 ? branch[0] : { all: branch }
+        )
       };
       const where = [];
       q.where.forEach((term, i) => {
@@ -135,9 +160,10 @@ function useQueryFilters(schema, setQuery) {
 // src/useGrouping.ts
 import { useEffect, useRef, useState } from "react";
 import {
+  groupKeyFields,
   MAX_SUMMARY_COLUMNS,
   normalizeQueryState,
-  predicatesOf as predicatesOf2,
+  predicatesOf,
   withGroupingKeys,
   withoutGrouping,
   queriesEqual
@@ -150,7 +176,8 @@ function useGroupingController(api, source, model, inputs, supported, viewRevisi
   const view = {
     version: 2,
     mode: stage ? "groups" : "rows",
-    keys: stage?.keys ?? [],
+    keys: groupKeyFields(stage?.keys ?? []),
+    groupKeys: stage?.keys ?? [],
     summaries: stage?.summaries ?? [],
     representative: stage?.representative ?? null,
     input: source.query,
@@ -205,7 +232,7 @@ function useGroupingController(api, source, model, inputs, supported, viewRevisi
           offset: 0,
           aggregations: [],
           where: q.where.filter(
-            (term) => !predicatesOf2(term).some((p) => changed.has(p.field))
+            (term) => !predicatesOf(term).some((p) => changed.has(p.field))
           ),
           orderBy: q.orderBy.filter((term) => !changed.has(term.field))
         } : {}
@@ -213,7 +240,7 @@ function useGroupingController(api, source, model, inputs, supported, viewRevisi
     );
     setNotice(
       changed.size && (api.query.where.some(
-        (term) => predicatesOf2(term).some((p) => changed.has(p.field))
+        (term) => predicatesOf(term).some((p) => changed.has(p.field))
       ) || api.query.orderBy.some((term) => changed.has(term.field)) || api.query.aggregations?.length) ? "Columns updated. Affected filters, sorts, and metrics cleared; Undo restores them." : ""
     );
   }
@@ -321,6 +348,7 @@ import { ITEM_DETAILS_COLUMN, itemPageFields } from "@pythia-software/query-tabl
 
 // src/useItemDetails.ts
 import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
+import { isPropertyFieldLoaded, jsonInspectionScopeKey, MAX_JSON_INSPECTIONS } from "@pythia-software/query-table-core";
 
 // src/usePropertyView.ts
 import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
@@ -509,7 +537,7 @@ function initialDetailModes(config) {
   const available = ALL_MODES.filter((mode) => !config?.modes || config.modes.includes(mode));
   return config?.defaultModes ? available.filter((mode) => config.defaultModes.includes(mode)) : available.includes("modal") ? ["modal"] : available.slice(0, 1);
 }
-function useDetailProperties(mode, schema, config, query, setQuery, enabled) {
+function useDetailProperties(mode, schema, config, query, setQuery, enabled, readOnly = false) {
   const snapshot = query.itemDetails?.views?.[mode] ?? query.itemDetails?.view;
   const seed = useRef3(snapshot);
   const properties = usePropertyView({
@@ -539,7 +567,7 @@ function useDetailProperties(mode, schema, config, query, setQuery, enabled) {
       if (target !== localViewKey) properties.setView(next);
     } else if (pendingView.current && pendingView.current.query === queryViewKey) {
       if (pendingView.current.local === localViewKey) pendingView.current = null;
-    } else if (!properties.loading && localViewKey !== queryViewKey && (queryViewKey !== void 0 || localViewKey !== previous.local)) {
+    } else if (!readOnly && !properties.loading && localViewKey !== queryViewKey && (queryViewKey !== void 0 || localViewKey !== previous.local)) {
       setQuery((current) => ({ ...current, itemDetails: {
         modes: current.itemDetails?.modes ?? initialDetailModes(config),
         ...current.itemDetails,
@@ -561,7 +589,9 @@ function useItemDetails({
   refreshKey,
   links,
   queryReady = true,
-  queryParameter: queryParameter2
+  queryParameter: queryParameter2,
+  lookupRow,
+  subject
 }) {
   const enabled = Boolean(options);
   const config = typeof options === "object" ? options : void 0;
@@ -573,9 +603,10 @@ function useItemDetails({
   const sharedModal = requested?.mode === "modal" && query.itemDetails?.modes.includes("modal") && (availableModes.includes("hover") || availableModes.includes("page") && !page.urlTemplate.trim());
   const active = requested && (modes.includes(requested.mode) || sharedModal) ? requested : null;
   const syncProperties = enabled && queryReady;
-  const modalProperties = useDetailProperties("modal", detailSchema, config, query, setQuery, syncProperties);
-  const hoverProperties = useDetailProperties("hover", detailSchema, config, query, setQuery, syncProperties);
-  const expandProperties = useDetailProperties("expand", detailSchema, config, query, setQuery, syncProperties);
+  const readOnly = subject === "group";
+  const modalProperties = useDetailProperties("modal", detailSchema, config, query, setQuery, syncProperties, readOnly);
+  const hoverProperties = useDetailProperties("hover", detailSchema, config, query, setQuery, syncProperties, readOnly);
+  const expandProperties = useDetailProperties("expand", detailSchema, config, query, setQuery, syncProperties, readOnly);
   const propertiesByMode = { modal: modalProperties, hover: hoverProperties, expand: expandProperties };
   const views = {
     modal: modalProperties.view,
@@ -585,10 +616,14 @@ function useItemDetails({
   const customLoad = config?.loadRow;
   const customLoadRef = useRef3(customLoad);
   customLoadRef.current = customLoad;
+  const lookupRef = useRef3(lookupRow);
+  lookupRef.current = lookupRow;
+  const hasLookup = Boolean(lookupRow);
   const hasCustomLoad = Boolean(customLoad);
   const sourceType = config?.objectType ?? detailSchema.name;
   const fallbackRows = !customLoad && !clientRows && !transport?.fetchRow ? rows : void 0;
   const loadRow = useCallback3(async (id, signal) => {
+    if (lookupRef.current) return lookupRef.current(id) ?? null;
     if (customLoadRef.current) return customLoadRef.current(id, signal);
     if (clientRows) {
       const row2 = clientRows.find((row3) => rowId(row3) === id);
@@ -600,10 +635,10 @@ function useItemDetails({
     }
     const row = rows.find((row2) => rowId(row2) === id);
     return row ? { row, loadedFields: Object.keys(row) } : null;
-  }, [hasCustomLoad, sourceType, clientRows, transport?.fetchRow, fallbackRows, rowId]);
+  }, [hasLookup, hasCustomLoad, sourceType, clientRows, transport?.fetchRow, fallbackRows, rowId]);
   const [retryKey, setRetryKey] = useState3(0);
   const [result, setResult] = useState3({ source: void 0, epoch: "", id: void 0, record: null, loading: false, error: null });
-  const activeId = enabled ? active?.id : void 0;
+  const activeId = enabled && !lookupRow ? active?.id : void 0;
   const epoch = `${refreshKey}:${retryKey}`;
   const currentResult = result.id === activeId && result.source === loadRow && result.epoch === epoch;
   useEffect3(() => {
@@ -612,7 +647,7 @@ function useItemDetails({
       setResult((previous) => previous.id === void 0 && !previous.loading && !previous.error && !previous.record ? previous : { source: void 0, epoch: "", id: void 0, record: null, loading: false, error: null });
       return;
     }
-    setResult({ source: loadRow, epoch, id: activeId, record: null, loading: true, error: null });
+    setResult((previous) => ({ source: loadRow, epoch, id: activeId, record: previous.id === activeId && previous.source === loadRow ? previous.record : null, loading: true, error: null }));
     void Promise.resolve().then(() => loadRow(activeId, controller.signal)).then((record) => {
       if (!controller.signal.aborted) setResult({ source: loadRow, epoch, id: activeId, record, loading: false, error: null });
     }).catch((error) => {
@@ -627,9 +662,66 @@ function useItemDetails({
     });
     return () => controller.abort();
   }, [activeId, loadRow, refreshKey, retryKey]);
+  const preserveFocus = useRef3(false);
+  const attentionSequence = useRef3(0);
+  const [attentionRequest, setAttentionRequest] = useState3({ revision: 0, pending: false });
+  const attentionLatest = useRef3({ loadRow, setQuery, modes, views, active, query });
+  attentionLatest.current = { loadRow, setQuery, modes, views, active, query };
+  useEffect3(() => {
+    const registry = config?.attention;
+    if (!enabled || !registry) return;
+    const provider = { reveal: async (target, signal) => {
+      if (target.rowId === void 0 || signal.aborted) return false;
+      const current = attentionLatest.current;
+      const record = await current.loadRow(target.rowId, signal);
+      if (!record || signal.aborted) return false;
+      if (target.field !== void 0 && !detailSchema.fields.some((field) => field.name === target.field && field.property?.enabled !== false && isPropertyFieldLoaded(field, record.loadedFields))) return false;
+      const mode = current.active?.id === target.rowId ? current.active.mode : current.modes.includes("expand") ? "expand" : current.modes.includes("modal") ? "modal" : null;
+      if (!mode || target.field !== void 0 && !current.views[mode].properties.some((property) => property.field === target.field)) return false;
+      preserveFocus.current = true;
+      const revision = ++attentionSequence.current;
+      setAttentionRequest({ revision, pending: true });
+      try {
+        current.setQuery((previous) => ({ ...previous, itemDetails: {
+          ...previous.itemDetails,
+          modes: previous.itemDetails?.modes ?? current.modes,
+          views: current.views,
+          active: { id: target.rowId, mode }
+        } }));
+        const mounted = await registry.whenRegistered({ dataset: detailSchema.name, rowId: target.rowId }, signal);
+        if (mounted.ready) await mounted.ready(signal);
+        return signal.aborted ? false : await mounted.reveal(target, signal);
+      } finally {
+        setAttentionRequest((previous) => previous.revision === revision ? { revision, pending: false } : previous);
+      }
+    } };
+    return registry.register({ dataset: detailSchema.name }, provider);
+  }, [enabled, config?.attention, detailSchema]);
   if (!enabled) return;
+  const looked = lookupRow && active ? lookupRow(active.id) : null;
   return {
+    ...subject ? { subject } : {},
     ...links ? { links } : {},
+    ...config?.attention ? { attention: config.attention } : {},
+    preserveFocus: preserveFocus.current,
+    attentionRevision: attentionRequest.revision,
+    attentionPending: attentionRequest.pending,
+    jsonInspections: query.itemDetails?.jsonInspections ?? [],
+    setJsonInspection(entry) {
+      if (entry.dataset !== detailSchema.name) return;
+      setQuery((current) => {
+        const inspections = (current.itemDetails?.jsonInspections ?? []).filter((previous) => jsonInspectionScopeKey(previous) !== jsonInspectionScopeKey(entry));
+        while (inspections.length >= MAX_JSON_INSPECTIONS) {
+          const closed = inspections.findIndex((previous) => !previous.state.open);
+          inspections.splice(closed < 0 ? 0 : closed, 1);
+        }
+        return { ...current, itemDetails: {
+          ...current.itemDetails,
+          modes: current.itemDetails?.modes ?? modes,
+          jsonInspections: [...inspections, entry]
+        } };
+      });
+    },
     schema: detailSchema,
     queryParameter: queryParameter2 ?? config?.queryParameter ?? "q",
     properties: modalProperties,
@@ -639,9 +731,9 @@ function useItemDetails({
     active,
     page,
     pageSchema: schema,
-    record: currentResult ? result.record : null,
-    loading: activeId !== void 0 && (!currentResult || result.loading),
-    error: currentResult ? result.error : null,
+    record: lookupRow ? looked ?? null : result.id === activeId && result.source === loadRow ? result.record : null,
+    loading: lookupRow ? looked === void 0 : activeId !== void 0 && (!currentResult || result.loading),
+    error: lookupRow ? null : currentResult ? result.error : null,
     ...config?.relationships ? { relationships: config.relationships } : {},
     loadRow,
     retry: () => setRetryKey((value) => value + 1),
@@ -654,6 +746,8 @@ function useItemDetails({
       });
     },
     open(id, mode) {
+      config?.attention?.cancel();
+      preserveFocus.current = false;
       if (!modes.includes(mode)) return;
       setQuery((current) => ({ ...current, itemDetails: {
         ...current.itemDetails,
@@ -663,6 +757,7 @@ function useItemDetails({
       } }));
     },
     close() {
+      config?.attention?.cancel();
       setQuery((current) => {
         if (!current.itemDetails?.active) return current;
         const { active: _active, ...state } = current.itemDetails;
@@ -674,6 +769,7 @@ function useItemDetails({
 
 // src/computedExecution.ts
 import {
+  predicatesOf as predicatesOf2,
   isComputedField,
   readFieldValue
 } from "@pythia-software/query-table-core";
@@ -689,7 +785,7 @@ function validateComputedResponse(request, result, schema) {
   const executed = /* @__PURE__ */ new Set([
     ...request.select.filter(isComputedField),
     ...request.orderBy.map((term) => term.field).filter(isComputedField),
-    ...request.where.flatMap((term) => ("any" in term ? term.any : [term]).map((predicate) => predicate.field)).filter(isComputedField)
+    ...request.where.flatMap((term) => predicatesOf2(term).map((predicate) => predicate.field)).filter(isComputedField)
   ]);
   for (const [name, revision] of Object.entries(request.expectedRevisions)) {
     const id = name.replace(/^@computed\//, "");
@@ -724,6 +820,7 @@ function validateComputedResponse(request, result, schema) {
 
 // src/previewRows.ts
 import {
+  predicatesOf as predicatesOf3,
   sourceExecutionSchema,
   toQueryRequestV3,
   toServerQuery,
@@ -734,13 +831,13 @@ async function fetchPreviewRows(transport, query, schema, execution, definitions
   if (signal.aborted) throw new DOMException("Aborted", "AbortError");
   const sourceSchema = sourceExecutionSchema(baseSchema, execution, definitions);
   let result;
-  const computedFilter = query.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => predicate.field.startsWith("@computed/")));
+  const computedFilter = query.where.some((term) => predicatesOf3(term).some((predicate) => predicate.field.startsWith("@computed/")));
   if (transport.fetchRowsV2 && execution && !query.grouping && !computedFilter) {
     const request = toServerQueryV2(query, sourceSchema, execution);
     if (request.diagnostics.length)
       throw Error(request.diagnostics.map((issue) => issue.message).join(" "));
     for (const definition of definitions) {
-      if (executionRevision(execution, definition.id) !== definition.revision && (request.select.includes(`@computed/${definition.id}`) || request.orderBy.some((term) => term.field === `@computed/${definition.id}`) || request.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => predicate.field === `@computed/${definition.id}`))))
+      if (executionRevision(execution, definition.id) !== definition.revision && (request.select.includes(`@computed/${definition.id}`) || request.orderBy.some((term) => term.field === `@computed/${definition.id}`) || request.where.some((term) => predicatesOf3(term).some((predicate) => predicate.field === `@computed/${definition.id}`))))
         throw Error("Computed definitions changed. Refresh the server execution handshake.");
     }
     const response = await transport.fetchRowsV2(request, signal);
@@ -772,6 +869,7 @@ async function fetchPreviewRows(transport, query, schema, execution, definitions
 // src/useComputedColumns.ts
 import { useCallback as useCallback4, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef4, useState as useState4 } from "react";
 import {
+  predicatesOf as predicatesOf4,
   isGroupLinkField,
   applyQuery,
   compileFormula,
@@ -1173,7 +1271,7 @@ function useComputedColumns(options) {
             offset: 0
           };
           const now = options.now ?? Date.now();
-          const computedFilter = request.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => isComputedField2(predicate.field)));
+          const computedFilter = request.where.some((term) => predicatesOf4(term).some((predicate) => isComputedField2(predicate.field)));
           const v3 = !(transport.fetchRowsV2 && options.execution && !request.grouping && !computedFilter) && transport.fetchQueryV3 && transport.queryCapabilities?.version === 3;
           const pageSize = Math.min(500, v3 ? transport.queryCapabilities.maxRows : 500);
           if (!Number.isInteger(pageSize) || pageSize < 1) throw Error("Invalid negotiated preview row limit.");
@@ -1262,17 +1360,22 @@ import {
   applyQuery as applyQuery2,
   memoryStorageAdapter,
   normalizeQueryState as normalizeQueryState3,
+  parseHostQueryState,
   readFieldValue as readFieldValue4,
   selectedFields as selectedFields2,
   toServerQuery as toServerQuery2,
   queriesEqual as queriesEqual2,
-  isOrGroup as isOrGroup2,
+  isWhereConjunction as isWhereConjunction2,
+  isWhereGroup,
+  predicatesOf as predicatesOf6,
   metricPlans as metricPlans2,
   validateMetric as validateMetric2,
-  metricDependencies,
+  metricDependencies as metricDependencies2,
   isComputedField as isComputedField4,
   computedFieldName as computedFieldName2,
-  toServerQueryV2 as toServerQueryV22
+  toServerQueryV2 as toServerQueryV22,
+  groupKeyField,
+  groupKeyFields as groupKeyFields2
 } from "@pythia-software/query-table-core";
 
 // src/useRequestActivity.ts
@@ -1385,11 +1488,12 @@ import {
   normalizeQueryState as normalizeQueryState2,
   evaluateMetrics,
   metricPlans,
+  metricDependencies,
   hasRegex as hasRegex2,
   metricPopulationError,
   hasMetricSeries,
   planMetricSeries,
-  predicatesOf as predicatesOf3,
+  predicatesOf as predicatesOf5,
   toAggregationQuery,
   toMetricQuery,
   validateMetric,
@@ -1545,11 +1649,10 @@ async function executeMetrics(query, context, signal) {
       shown.flatMap((clause) => [
         ...clause.groupBy,
         ...(clause.where ?? []).flatMap(
-          (term) => predicatesOf3(term).map((predicate) => predicate.field)
+          (term) => predicatesOf5(term).map((predicate) => predicate.field)
         ),
-        ...metricPlans(clause, context.schema, context.resolveComputed).flatMap(
-          (p) => p.dependencies
-        )
+        // Includes a measured minimum's field, which the page must also hold.
+        ...metricDependencies(clause, context.schema, context.resolveComputed)
       ])
     );
     for (const name of names) {
@@ -2134,7 +2237,7 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now, snaps
 // src/useQueryLinks.ts
 import { useCallback as useCallback11, useEffect as useEffect9, useRef as useRef8, useState as useState10 } from "react";
 import { encodeQuery } from "@pythia-software/query-table-core";
-function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, onUrlChange) {
+function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, onUrlChange, decorate = (url) => url) {
   const latest = useRef8(query);
   latest.current = query;
   const [kind, setKind] = useState10(null);
@@ -2153,14 +2256,15 @@ function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, o
     if (!syncUrl || !ready || typeof window === "undefined") return;
     try {
       const result = service.local(query, window.location.href, parameter);
-      window.history.replaceState(window.history.state, "", result.url);
-      onUrlChange(result.url);
+      const url = decorate(result.url, query);
+      window.history.replaceState(window.history.state, "", url);
+      onUrlChange(url);
       setKind(result.kind);
       setError(null);
     } catch (e) {
       setError(e instanceof Error ? e : Error(String(e)));
     }
-  }, [queryKey, syncUrl, ready, service, parameter, onUrlChange]);
+  }, [queryKey, syncUrl, ready, service, parameter, onUrlChange, decorate]);
   const snapshot = useCallback11(async (q) => {
     const captured = encodeQuery(q);
     const base = typeof window !== "undefined" ? window.location.href : void 0;
@@ -2174,8 +2278,9 @@ function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, o
         const url = new URL(base);
         url.searchParams.set(parameter, "@" + saved.code);
         const result = service.local(q, url.toString(), parameter);
-        window.history.replaceState(window.history.state, "", result.url);
-        onUrlChange(result.url);
+        const next = decorate(result.url, q);
+        window.history.replaceState(window.history.state, "", next);
+        onUrlChange(next);
         setKind("durable");
       }
       return saved;
@@ -2186,7 +2291,7 @@ function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, o
       operations.current--;
       if (mounted.current) setBusy(operations.current > 0);
     }
-  }, [service, syncUrl, ready, parameter, onUrlChange]);
+  }, [service, syncUrl, ready, parameter, onUrlChange, decorate]);
   const create = useCallback11(async (q = latest.current, options = {}) => {
     const baseUrl = options.baseUrl ?? window.location.href;
     const param = options.parameter ?? parameter;
@@ -2196,7 +2301,8 @@ function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, o
     setError(null);
     try {
       if (!ready) throw Error("Resolve or reset the query link before sharing it.");
-      const result = await service.durable(q, baseUrl, param);
+      const durable = await service.durable(q, baseUrl, param);
+      const result = param === parameter ? { ...durable, url: decorate(durable.url, q) } : durable;
       if (mounted.current && syncUrl && ready && param === parameter && window.location.href === baseUrl && encodeQuery(latest.current) === captured) {
         window.history.replaceState(window.history.state, "", result.url);
         onUrlChange(result.url);
@@ -2210,8 +2316,11 @@ function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, o
       operations.current--;
       if (mounted.current) setBusy(operations.current > 0);
     }
-  }, [service, syncUrl, ready, parameter, onUrlChange]);
-  const local = useCallback11((q, base = window.location.href, param = parameter) => service.local(q, base, param), [service, parameter]);
+  }, [service, syncUrl, ready, parameter, onUrlChange, decorate]);
+  const local = useCallback11((q, base = window.location.href, param = parameter) => {
+    const result = service.local(q, base, param);
+    return param === parameter ? { ...result, url: decorate(result.url, q) } : result;
+  }, [service, parameter, decorate]);
   return { maxUrlBytes, kind, busy, error, create, local, snapshot };
 }
 
@@ -2248,7 +2357,7 @@ function defaultsFor(schema, details = false) {
   });
 }
 function cloneWhereTerm(term) {
-  const copy = isOrGroup2(term) ? { ...term, any: term.any.map((c) => ({ ...c })) } : { ...term };
+  const copy = isWhereGroup(term) ? { ...term, any: term.any.map((c) => isWhereConjunction2(c) ? { all: c.all.map((m) => ({ ...m })) } : { ...c }) } : { ...term };
   if (term.setFilter)
     copy.setFilter = { ...term.setFilter, values: [...term.setFilter.values] };
   return copy;
@@ -2264,6 +2373,7 @@ function cloneQueryState(q) {
     offset: q.offset
   };
   if (q.fitToScreen) clone.fitToScreen = true;
+  if (q.hostState) clone.hostState = { version: q.hostState.version, params: Object.fromEntries(Object.entries(q.hostState.params).map(([name, values]) => [name, [...values]])) };
   if (q.aggregations)
     clone.aggregations = JSON.parse(
       JSON.stringify(q.aggregations)
@@ -2325,16 +2435,61 @@ function hasQueryLink(url, parameter) {
 function queryParameter(opts) {
   return opts.queryParameter ?? (typeof opts.itemDetails === "object" ? opts.itemDetails.queryParameter : void 0) ?? "q";
 }
+function withHostState(query, host) {
+  if (!host) {
+    if (query.hostState) throw Error("This query includes host state that this table does not support.");
+    return query;
+  }
+  const raw = query.hostState ?? host.defaults;
+  if (raw.version === 0) throw Error("This query's host state could not be read.");
+  const state = parseHostQueryState(host.normalize ? host.normalize(parseHostQueryState(raw)) : raw);
+  return { ...query, hostState: state };
+}
+function withoutHostState(query) {
+  const { hostState: _hostState, ...rest } = query;
+  return rest;
+}
+function hostStateFromUrl(location, host) {
+  const url = new URL(location);
+  const params = {};
+  for (const name of host.ownedParameters) {
+    const values = url.searchParams.getAll(name);
+    if (values.length) params[name] = values;
+  }
+  return Object.keys(params).length ? { version: host.defaults.version, params } : void 0;
+}
+function writeHostParameters(url, host, state) {
+  const next = new URL(url);
+  for (const name of host.ownedParameters) next.searchParams.delete(name);
+  for (const name of host.ownedParameters)
+    for (const value of state?.params[name] ?? []) next.searchParams.append(name, value);
+  return next.toString();
+}
+var HOST_REQUEST_METHODS = /* @__PURE__ */ new Set(["fetchRows", "fetchRowsV2", "fetchQueryV3", "fetchMetrics", "fetchAggregations", "fetchDistinctValues"]);
+function withHostTransport(transport, hostStateKey) {
+  if (!transport || !hostStateKey) return transport;
+  const hostState = JSON.parse(hostStateKey);
+  const wrappers = /* @__PURE__ */ new Map();
+  return new Proxy(Object.create(transport), {
+    get(_target, key) {
+      const method = Reflect.get(transport, key, transport);
+      if (!HOST_REQUEST_METHODS.has(String(key)) || typeof method !== "function") return method;
+      if (!wrappers.has(key))
+        wrappers.set(key, (request, signal) => method.call(transport, { ...request, hostState }, signal));
+      return wrappers.get(key);
+    }
+  });
+}
 function resolveInitial(opts) {
-  const defaults = defaultsFor(opts.schema, Boolean(opts.itemDetails));
+  const defaults = withHostState(defaultsFor(opts.schema, Boolean(opts.itemDetails)), opts.hostQuery);
   if (opts.initialQuery)
     return {
-      q: normalizeQueryState3(opts.initialQuery, defaults),
+      q: withHostState(normalizeQueryState3(opts.initialQuery, defaults), opts.hostQuery),
       fromUrl: false
     };
   if (opts.syncUrl === true && opts.active !== false && typeof window !== "undefined") {
     const parameter = queryParameter(opts);
-    if (hasQueryLink(window.location.href, parameter))
+    if (hasQueryLink(window.location.href, parameter) || opts.hostQuery && hostStateFromUrl(window.location.href, opts.hostQuery))
       return {
         q: defaults,
         fromUrl: true
@@ -2353,8 +2508,13 @@ function useQueryTable(opts) {
   const active = opts.active !== false;
   const urlSyncEnabled = opts.syncUrl === true;
   const syncUrl = urlSyncEnabled && active;
-  const { transport: metadataTransport, metricTransport, activity: requestActivity } = useRequestActivity(sourceTransport, opts.metricTransport);
-  const transport = metadataTransport;
+  const { transport: activityTransport, metricTransport: activityMetricTransport, activity: requestActivity } = useRequestActivity(sourceTransport, opts.metricTransport);
+  const host = opts.hostQuery;
+  const hostRef = useRef9(host);
+  hostRef.current = host;
+  const hostDefaultsKey = host ? JSON.stringify(host.defaults) : "";
+  if (host?.ownedParameters.includes(queryParameter(opts)))
+    throw Error(`hostQuery.ownedParameters cannot include the table's own "${queryParameter(opts)}" parameter.`);
   const storage = useMemo9(
     () => opts.storage ?? memoryStorageAdapter(),
     [opts.storage]
@@ -2367,7 +2527,10 @@ function useQueryTable(opts) {
   const now = opts.now ?? Date.now;
   const nowRef = useRef9(now);
   const onRefreshRef = useRef9(opts.onRefresh);
-  const defaults = useMemo9(() => defaultsFor(sourceSchema, Boolean(opts.itemDetails)), [sourceSchema, Boolean(opts.itemDetails)]);
+  const defaults = useMemo9(
+    () => withHostState(defaultsFor(sourceSchema, Boolean(opts.itemDetails)), hostRef.current),
+    [sourceSchema, Boolean(opts.itemDetails), hostDefaultsKey]
+  );
   const initRef = useRef9(resolveInitial(opts));
   const [restoration, setRestoration] = useState11({ loading: initRef.current.fromUrl, error: null });
   const [storageReady, setStorageReady] = useState11(Boolean(initialQuery));
@@ -2404,6 +2567,10 @@ function useQueryTable(opts) {
     () => opts.canonicalizeQuery?.(storedQuery) ?? storedQuery,
     [storedQuery, opts.canonicalizeQuery]
   );
+  const hostStateKey = host && query.hostState ? JSON.stringify(query.hostState) : "";
+  const metadataTransport = useMemo9(() => withHostTransport(activityTransport, hostStateKey), [activityTransport, hostStateKey]);
+  const metricTransport = useMemo9(() => withHostTransport(activityMetricTransport, hostStateKey), [activityMetricTransport, hostStateKey]);
+  const transport = metadataTransport;
   const sourceCatalogue = useMemo9(() => sourceExecutionSchema2(sourceSchema, opts.computedExecution), [sourceSchema, opts.computedExecution]);
   const sourceRows = providedRows;
   const groupingModel = useMemo9(() => createGroupingModel(sourceCatalogue), [sourceCatalogue]);
@@ -2433,6 +2600,7 @@ function useQueryTable(opts) {
   const executionQuery = useMemo9(() => withoutGrouping2(query), [query]);
   const byName = useMemo9(() => new Map(schema.fields.map((field) => [field.name, field])), [schema]);
   const detailsEnabled = Boolean(opts.itemDetails) && !query.grouping;
+  const groupDetailsEnabled = Boolean(opts.itemDetails) && Boolean(query.grouping);
   const validateExecution = useCallback12((q) => {
     if (prepared?.error) throw prepared.error;
     opts.validateQuery?.(query.grouping ? { ...q, grouping: query.grouping } : q);
@@ -2445,6 +2613,7 @@ function useQueryTable(opts) {
   const [loading, setLoading] = useState11(false);
   const [error, setError] = useState11(null);
   const [committedPage, setCommittedPage] = useState11(null);
+  const [failedPage, setFailedPage] = useState11(null);
   const [committedSource, setCommittedSource] = useState11(null);
   const rows = useMemo9(() => committedSource?.schema === schema ? committedRows : [], [committedSource?.schema, schema, committedRows]);
   const [autoRefreshStatus, setAutoRefreshStatus] = useState11(null);
@@ -2464,7 +2633,8 @@ function useQueryTable(opts) {
       updateQueryHistory((history) => {
         const prev = history.query;
         const candidate = typeof next === "function" ? next(prev) : next;
-        const nextQuery = normalizeQueryState3(candidate, defaults);
+        const normalized = normalizeQueryState3(candidate, defaults);
+        const nextQuery = withHostState(normalized.hostState || !prev.hostState ? normalized : { ...normalized, hostState: prev.hostState }, hostRef.current);
         if (queriesEqual2(prev, nextQuery)) return history;
         return { query: cloneQueryState(nextQuery), past: [...history.past, cloneQueryState(prev)], future: [] };
       });
@@ -2481,9 +2651,15 @@ function useQueryTable(opts) {
   }, [setQuery]);
   const sourceFilters = useQueryFilters(sourceCatalogue, setSourceQuery);
   const observedQueryUrl = useRef9(null);
+  const tableUrlKey = (url) => {
+    const params = new URL(url).searchParams;
+    return JSON.stringify([params.getAll(parameter), ...(hostRef.current?.ownedParameters ?? []).map((name) => params.getAll(name))]);
+  };
   const recordQueryUrl = useCallback12((url) => {
-    observedQueryUrl.current = JSON.stringify(new URL(url).searchParams.getAll(parameter));
+    observedQueryUrl.current = tableUrlKey(url);
   }, [parameter]);
+  const ownedParametersKey = JSON.stringify(host?.ownedParameters ?? null);
+  const decorateLink = useCallback12((url, q) => hostRef.current ? writeHostParameters(url, hostRef.current, q.hostState) : url, [ownedParametersKey]);
   const links = useQueryLinks(
     query,
     linkService,
@@ -2491,7 +2667,8 @@ function useQueryTable(opts) {
     storageReady && !restoration.loading && !restoration.error,
     parameter,
     opts.links?.maxUrlBytes ?? 2e3,
-    recordQueryUrl
+    recordQueryUrl,
+    decorateLink
   );
   const restoreSources = useRef9({ storage, linkService, defaults, initialQuery });
   restoreSources.current = { storage, linkService, defaults, initialQuery };
@@ -2513,17 +2690,21 @@ function useQueryTable(opts) {
       signal?.addEventListener("abort", abort2, { once: true });
       if (signal?.aborted) currentController.abort();
       setStorageReady(false);
-      const explicitLink = !!location && (navigation || urlSyncEnabled) && hasQueryLink(location, parameter);
+      const host2 = hostRef.current;
+      const hostFromUrl = host2 && location && (navigation || urlSyncEnabled) ? hostStateFromUrl(location, host2) : void 0;
+      const explicitLink = !!location && (navigation || urlSyncEnabled) && (hasQueryLink(location, parameter) || !!hostFromUrl);
       setRestoration({ loading: true, error: null });
       try {
         if (currentController.signal.aborted) throw new DOMException("Query restoration cancelled.", "AbortError");
         const fromUrl = location && (navigation || urlSyncEnabled) ? await linkService2.resolve(location, parameter, currentController.signal) : null;
-        const defaultSaved = fromUrl ? null : await storage2.loadDefaultSaved?.(sourceSchema.name);
-        const restored = fromUrl ?? defaultSaved?.query ?? (navigation ? defaults2 : await storage2.loadLast(sourceSchema.name));
+        const linked = fromUrl ?? (hostFromUrl ? defaults2 : null);
+        const defaultSaved = linked ? null : await storage2.loadDefaultSaved?.(sourceSchema.name);
+        let restored = linked ?? defaultSaved?.query ?? (navigation ? defaults2 : await storage2.loadLast(sourceSchema.name));
         if (currentController.signal.aborted) throw new DOMException("Query restoration cancelled.", "AbortError");
+        if (linked && !fromUrl?.hostState && hostFromUrl) restored = { ...linked, hostState: hostFromUrl };
         if (!cancelled && run === generation && epoch === manualQueryEpoch.current) {
           if (restored) {
-            const normalized = normalizeQueryState3(restored, defaults2);
+            const normalized = withHostState(normalizeQueryState3(restored, defaults2), host2);
             savedBaseline.current = defaultSaved || fromUrl?.grouping ? { source: sourceSchema.name, query: cloneQueryState(normalized) } : null;
             viewRevision.current++;
             updateQueryHistory(() => ({ query: normalized, past: [], future: [] }));
@@ -2548,7 +2729,7 @@ function useQueryTable(opts) {
     }
     restoreHandler.current = async (location, signal) => {
       location = new URL(location, typeof window !== "undefined" ? window.location.href : void 0).href;
-      const key = JSON.stringify(new URL(location).searchParams.getAll(parameter));
+      const key = tableUrlKey(location);
       const current = restorationCurrent.current;
       if (key === observedQueryUrl.current && current.storageReady && !current.restoration.loading && !current.restoration.error) return;
       recordQueryUrl(location);
@@ -2558,7 +2739,7 @@ function useQueryTable(opts) {
     if (typeof window !== "undefined") recordQueryUrl(window.location.href);
     const navigate = () => {
       if (!restorationCurrent.current.active) return;
-      const key = JSON.stringify(new URL(window.location.href).searchParams.getAll(parameter));
+      const key = tableUrlKey(window.location.href);
       if (key === observedQueryUrl.current) return;
       observedQueryUrl.current = key;
       void restore(true).catch(() => {
@@ -2618,7 +2799,7 @@ function useQueryTable(opts) {
   const definitionKey = JSON.stringify(computedRevisions);
   const queryKey = useMemo9(() => JSON.stringify(query), [query]);
   const serverRowQuery = useMemo9(() => {
-    const execution = opts.computedExecution;
+    const execution2 = opts.computedExecution;
     const detailConfig = typeof opts.itemDetails === "object" ? opts.itemDetails : void 0;
     const page = query.itemDetails?.page ?? detailConfig?.page;
     const pageEnabled = Boolean(opts.itemDetails) && (query.itemDetails?.modes ?? initialDetailModes(detailConfig)).includes("page") && (!detailConfig?.modes || detailConfig.modes.includes("page"));
@@ -2627,13 +2808,13 @@ function useQueryTable(opts) {
       ...query.select.length ? query.select : defaults.select,
       ...pageFields.filter((name) => displaySchema.fields.some((field) => field.name === name)).map((field) => ({ field }))
     ] } : executionQuery;
-    const v2Request = execution && transport?.fetchRowsV2 ? toServerQueryV22(requestQuery, displaySchema, execution) : void 0;
+    const v2Request = execution2 && transport?.fetchRowsV2 ? toServerQueryV22(requestQuery, displaySchema, execution2) : void 0;
     const request = v2Request ?? toServerQuery2(requestQuery, displaySchema);
     if (v2Request)
       for (const definition of computed.definitions) {
-        if ((execution?.fields[computedFieldName2(definition.id)]?.select || v2Request.orderBy.some(
+        if ((execution2?.fields[computedFieldName2(definition.id)]?.select || v2Request.orderBy.some(
           (term) => term.field === computedFieldName2(definition.id)
-        )) && executionRevision(execution, definition.id) !== void 0 && executionRevision(execution, definition.id) !== definition.revision)
+        )) && executionRevision(execution2, definition.id) !== void 0 && executionRevision(execution2, definition.id) !== definition.revision)
           v2Request.diagnostics.push({
             from: 0,
             to: 1,
@@ -2644,7 +2825,7 @@ function useQueryTable(opts) {
     for (const clause of query.aggregations ?? [])
       if (clause.scope === "shownRows") {
         try {
-          for (const name of metricDependencies(
+          for (const name of metricDependencies2(
             clause,
             schema,
             resolveComputed
@@ -2694,7 +2875,7 @@ function useQueryTable(opts) {
     ]
   );
   const executionKey = JSON.stringify(opts.computedExecution ?? null);
-  const pageContext = `${schema.name}:${rowQueryKey}:${nonce}:${executionKey}`;
+  const pageContext = `${schema.name}:${rowQueryKey}:${nonce}:${executionKey}:${hostStateKey}`;
   useEffect10(() => {
     if (!active || !storageReady || restoration.loading || restoration.error) {
       setRows((previous) => previous.length ? [] : previous);
@@ -2708,10 +2889,11 @@ function useQueryTable(opts) {
     const run = async () => {
       setLoading(true);
       setError(null);
+      setFailedPage(null);
       try {
         validateExecution(query);
         if (transport) {
-          if (transport.fetchQueryV3 && transport.queryCapabilities?.version === 3 && (query.grouping || query.select.some((column) => isComputedField4(column.field)) || query.orderBy.some((term) => isComputedField4(term.field)) || query.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => isComputedField4(predicate.field))) || !transport.fetchRows && !(transport.fetchRowsV2 && opts.computedExecution))) {
+          if (transport.fetchQueryV3 && transport.queryCapabilities?.version === 3 && (query.grouping || query.select.some((column) => isComputedField4(column.field)) || query.orderBy.some((term) => isComputedField4(term.field)) || query.where.some((term) => predicatesOf6(term).some((predicate) => isComputedField4(predicate.field))) || !transport.fetchRows && !(transport.fetchRowsV2 && opts.computedExecution))) {
             const request = toQueryRequestV32(
               { ...query, aggregations: [], select: [
                 ...query.select.filter((column) => isComputedField4(column.field)),
@@ -2792,6 +2974,7 @@ function useQueryTable(opts) {
       } catch (e) {
         if (!cancelled && !ac.signal.aborted) {
           setError(e);
+          setFailedPage(pageContext);
           setRows([]);
           setTotal(null);
           setCommittedPage(null);
@@ -2820,11 +3003,13 @@ function useQueryTable(opts) {
     active,
     storageReady
   ]);
+  const persistLast = opts.persistLast ?? "always";
+  const hostStorageUnsupported = Boolean(host) && !storage.storesHostState;
   useEffect10(() => {
-    if (!storageReady || restoration.loading || restoration.error) return;
+    if (persistLast !== "always" || !storageReady || restoration.loading || restoration.error || hostStorageUnsupported) return;
     const t = setTimeout(() => void storage.saveLast(sourceSchema.name, query), 400);
     return () => clearTimeout(t);
-  }, [queryKey, storage, sourceSchema.name, query, restoration, storageReady]);
+  }, [persistLast, queryKey, storage, sourceSchema.name, query, restoration, storageReady, hostStorageUnsupported]);
   const idField = useMemo9(
     () => schema.fields.find((f) => f.name === schema.idField),
     [schema]
@@ -2845,7 +3030,7 @@ function useQueryTable(opts) {
   useEffect10(() => {
     selection.clear();
   }, [identityScope, selection.clear]);
-  const columnSchema = useMemo9(() => detailColumnSchema(displaySchema, detailsEnabled), [displaySchema, detailsEnabled]);
+  const columnSchema = useMemo9(() => detailColumnSchema(displaySchema, detailsEnabled || groupDetailsEnabled), [displaySchema, detailsEnabled, groupDetailsEnabled]);
   const resultDefaults = useMemo9(() => query.grouping ? defaultsFor(schema) : defaults, [Boolean(query.grouping), schema, defaults]);
   const select = useSelect(query, setQuery, columnSchema);
   const columnDrag = useColumnDrag();
@@ -2853,7 +3038,7 @@ function useQueryTable(opts) {
     sourceSchema.name,
     query,
     (q) => {
-      const normalized = normalizeQueryState3(q, defaults);
+      const normalized = withHostState(normalizeQueryState3(q, defaults), hostRef.current);
       savedBaseline.current = { source: sourceSchema.name, query: cloneQueryState(normalized) };
       viewRevision.current++;
       setQuery(normalized);
@@ -2862,11 +3047,23 @@ function useQueryTable(opts) {
     now,
     links.snapshot
   );
-  const saved = { ...savedQueries, save: async (name) => {
+  const hostStorageError = host && !storage.storesHostState ? "This storage adapter cannot save host query state (set StorageAdapter.storesHostState once it keeps QueryState.hostState)." : null;
+  const savedItems = useMemo9(() => !host ? savedQueries.items : savedQueries.items.map((item) => {
+    try {
+      return { ...item, query: withHostState(normalizeQueryState3(item.query, defaults), hostRef.current) };
+    } catch {
+      return item;
+    }
+  }), [savedQueries.items, Boolean(host), defaults]);
+  const saved = { ...savedQueries, items: savedItems, save: async (name) => {
+    if (hostStorageError) throw Error(hostStorageError);
     const item = await savedQueries.save(name);
-    savedBaseline.current = { source: sourceSchema.name, query: cloneQueryState(normalizeQueryState3(item.query, defaults)) };
+    savedBaseline.current = { source: sourceSchema.name, query: cloneQueryState(withHostState(normalizeQueryState3(item.query, defaults), hostRef.current)) };
     viewRevision.current++;
     return item;
+  }, update: async (id) => {
+    if (hostStorageError) throw Error(hostStorageError);
+    return savedQueries.update(id);
   } };
   const pageReady = committedPage === pageContext && committedSource?.schema === schema && committedSource?.transport === transport && committedSource?.clientRows === clientRows && !error;
   const dataToken = useRef9(0);
@@ -2886,7 +3083,7 @@ function useQueryTable(opts) {
     const capabilities = metricTransport.queryCapabilities;
     const refused = /* @__PURE__ */ new Map();
     for (const clause of metricQuery.aggregations ?? []) {
-      const issue = metricPopulationError2(clause, { filters: capabilities.metricFilters, minCount: capabilities.metricMinCount });
+      const issue = metricPopulationError2(clause, { filters: capabilities.metricFilters, minCount: capabilities.metricMinCount, minCountMeasures: capabilities.metricMinCountMeasures });
       if (issue) refused.set(clause.id, issue);
     }
     const runnable = (metricQuery.aggregations ?? []).filter((clause) => !refused.has(clause.id));
@@ -2938,7 +3135,7 @@ function useQueryTable(opts) {
     nonce,
     validateExecution,
     {
-      ...metricTransport?.fetchQueryV3 && metricTransport.queryCapabilities?.version === 3 && (query.grouping || query.aggregations?.some((metric) => metric.dateGrouping) || query.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => isComputedField4(predicate.field)))) ? { executeV3: executeV3Metrics, queryContextKey: groupKey } : {},
+      ...metricTransport?.fetchQueryV3 && metricTransport.queryCapabilities?.version === 3 && (query.grouping || query.aggregations?.some((metric) => metric.dateGrouping) || query.where.some((term) => predicatesOf6(term).some((predicate) => isComputedField4(predicate.field)))) ? { executeV3: executeV3Metrics, queryContextKey: groupKey } : {},
       ...groupingNow !== void 0 ? { now: groupingNow, strictLocalMetrics: true } : {},
       shownRows: rows,
       rowsReady: metricRowsReady,
@@ -3239,6 +3436,62 @@ function useQueryTable(opts) {
       query.where
     ]
   );
+  const executionIdentity = JSON.stringify([pageContext, query.aggregations ?? [], query.where, groupKey, nonce]);
+  const executionGeneration = useRef9({ key: "", generation: 0 });
+  if (executionGeneration.current.key !== executionIdentity)
+    executionGeneration.current = { key: executionIdentity, generation: executionGeneration.current.generation + 1 };
+  const execution = useMemo9(() => {
+    if (!active || !storageReady || restoration.loading || restoration.error) return null;
+    const rowsStatus = pageReady ? "succeeded" : error && failedPage === pageContext ? "failed" : "running";
+    const metricError = aggState.error ?? aggState.results?.metrics.find((entry) => entry.error)?.error;
+    const metricsStatus = !query.aggregations?.length ? "none" : aggState.loading || !aggState.results && !aggState.error ? "running" : metricError ? "failed" : "succeeded";
+    const status = rowsStatus === "failed" || metricsStatus === "failed" ? "failed" : rowsStatus === "succeeded" && metricsStatus !== "running" ? "succeeded" : "running";
+    return {
+      query,
+      key: executionIdentity,
+      generation: executionGeneration.current.generation,
+      status,
+      rows: rowsStatus,
+      metrics: metricsStatus,
+      error: rowsStatus === "failed" ? error : metricError ? metricError instanceof Error ? metricError : Error(String(metricError)) : null
+    };
+  }, [
+    active,
+    storageReady,
+    restoration.loading,
+    restoration.error,
+    pageReady,
+    error,
+    failedPage,
+    pageContext,
+    aggState.error,
+    aggState.results,
+    aggState.loading,
+    query,
+    executionIdentity
+  ]);
+  const succeededQuery = execution?.status === "succeeded" ? execution.query : null;
+  const pendingLast = useRef9(null);
+  const savedLast = useRef9(null);
+  useEffect10(() => {
+    if (persistLast !== "succeeded" || !succeededQuery || hostStorageUnsupported) return;
+    const key = JSON.stringify([sourceSchema.name, succeededQuery]);
+    if (pendingLast.current?.key === key || !pendingLast.current && savedLast.current === key) return;
+    if (pendingLast.current) clearTimeout(pendingLast.current.timer);
+    const save = () => {
+      pendingLast.current = null;
+      savedLast.current = key;
+      void storage.saveLast(sourceSchema.name, succeededQuery);
+    };
+    pendingLast.current = { key, save, timer: setTimeout(save, 400) };
+  }, [persistLast, succeededQuery, storage, sourceSchema.name, hostStorageUnsupported]);
+  useEffect10(() => () => {
+    const pending = pendingLast.current;
+    if (pending) {
+      clearTimeout(pending.timer);
+      pending.save();
+    }
+  }, []);
   const sourceRowId = useCallback12((row) => {
     const field = sourceSchema.fields.find((f) => f.name === sourceSchema.idField);
     const value = field ? readFieldValue4(field, row) : row[sourceSchema.idField];
@@ -3258,16 +3511,71 @@ function useQueryTable(opts) {
     queryParameter: parameter,
     queryReady: storageReady && !restoration.loading && !restoration.error
   });
+  const groupPopulation = query.grouping ? JSON.stringify([query.grouping, query.where, nonce, hostStateKey]) : "";
+  const groupRecords = useRef9({ population: "", source: [], rows: /* @__PURE__ */ new Map() });
+  const groupSource = [clientRows, transport, schema];
+  if (groupRecords.current.population !== groupPopulation || groupSource.some((part, i) => part !== groupRecords.current.source[i]))
+    groupRecords.current = { population: groupPopulation, source: groupSource, rows: /* @__PURE__ */ new Map() };
+  const groupsSettled = groupDetailsEnabled && pageReady && !restoration.loading;
+  if (groupsSettled) for (const row of rows) {
+    const id = rowId(row);
+    if (id != null) groupRecords.current.rows.set(id, row);
+  }
+  const groupDetailOptions = useMemo9(() => {
+    if (!groupDetailsEnabled) return void 0;
+    const config = typeof opts.itemDetails === "object" ? opts.itemDetails : void 0;
+    const modes = (config?.modes ?? ["hover", "modal", "expand"]).filter((mode) => mode !== "page");
+    return {
+      modes,
+      defaultModes: initialDetailModes(config).filter((mode) => modes.includes(mode)),
+      objectType: `${config?.objectType ?? sourceSchema.name}:groups`,
+      ...config?.storage ? { storage: config.storage } : {}
+    };
+  }, [groupDetailsEnabled, opts.itemDetails, sourceSchema.name]);
+  const groupDetailSchema = useMemo9(() => ({
+    ...displaySchema,
+    defaultSelect: displaySchema.fields.filter((field) => field.name !== displaySchema.idField).map((field) => ({ field: field.name })),
+    fields: displaySchema.fields.map((field) => field.name === displaySchema.idField ? { ...field, property: { enabled: false } } : field)
+  }), [displaySchema]);
+  const setGroupQuery = useCallback12((next) => setQuery((current) => current.grouping ? typeof next === "function" ? next(current) : next : current), [setQuery]);
+  const groupDetails = useItemDetails({
+    schema: groupDetailSchema,
+    query,
+    setQuery: setGroupQuery,
+    options: groupDetailOptions,
+    rows,
+    clientRows: void 0,
+    rowId,
+    transport: void 0,
+    refreshKey: nonce,
+    links,
+    queryParameter: parameter,
+    queryReady: storageReady && !restoration.loading && !restoration.error,
+    lookupRow: (id) => {
+      const row = groupRecords.current.rows.get(id);
+      return row ? { row } : groupsSettled || error ? null : void 0;
+    },
+    subject: "group"
+  });
   const api = {
     restoration: {
       status: restoration.error ? "error" : !storageReady || restoration.loading ? "resolving" : "ready",
       ready: active && storageReady && !restoration.loading && !restoration.error,
       error: restoration.error
     },
+    execution,
+    ...host && query.hostState ? {
+      definition: { query: withoutHostState(query), hostState: query.hostState },
+      setDefinition: (next) => {
+        const current = queryHistoryRef.current.query;
+        const value = typeof next === "function" ? next({ query: withoutHostState(current), hostState: current.hostState }) : next;
+        setQuery(withHostState({ ...normalizeQueryState3(value.query, defaults), hostState: value.hostState }, hostRef.current));
+      }
+    } : {},
     restoreLocation,
     links,
     schema: columnSchema,
-    ...itemDetails && detailsEnabled ? { itemDetails } : {},
+    ...itemDetails && detailsEnabled ? { itemDetails } : groupDetails ? { itemDetails: groupDetails } : {},
     query,
     defaults: resultDefaults,
     setQuery,
@@ -3310,6 +3618,25 @@ function useQueryTable(opts) {
     visibleFields,
     rowId
   };
+  const sourceFilterValues = useCallback12(async (name, search) => {
+    if (metadataTransport?.fetchDistinctValues) return metadataTransport.fetchDistinctValues({ field: name, search });
+    const field = groupingModel.sourceField(name);
+    return field && sourceRows ? { ...distinctValuesFromRows(field, sourceRows, search), hasNull: fieldHasNullInRows(field, sourceRows) } : { values: [], hasMore: false };
+  }, [metadataTransport, groupingModel, sourceRows]);
+  const sourceFieldStats = useCallback12(async (names, signal) => {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    const requested = [...new Set(names)];
+    if (metadataTransport?.fetchFieldStats) {
+      const backendFields = requested.filter(
+        (name) => sourceCatalogue.fields.find((field) => field.name === name)?.source.kind === "backend"
+      );
+      return backendFields.length ? metadataTransport.fetchFieldStats(backendFields, signal) : {};
+    }
+    return Object.fromEntries(requested.flatMap((name) => {
+      const field = groupingModel.sourceField(name);
+      return field && sourceRows ? [[name, { distinct: new Set(sourceRows.map((row) => JSON.stringify(readFieldValue4(field, row)))).size }]] : [];
+    }));
+  }, [metadataTransport, groupingModel, sourceRows, sourceCatalogue]);
   const sourceApi = {
     ...sourceFilters,
     loading,
@@ -3318,25 +3645,8 @@ function useQueryTable(opts) {
     setQuery: setSourceQuery,
     ...itemDetails ? { itemDetails } : {},
     schema: sourceCatalogue,
-    filterValues: async (name, search) => {
-      if (metadataTransport?.fetchDistinctValues) return metadataTransport.fetchDistinctValues({ field: name, search });
-      const field = groupingModel.sourceField(name);
-      return field && sourceRows ? { ...distinctValuesFromRows(field, sourceRows, search), hasNull: fieldHasNullInRows(field, sourceRows) } : { values: [], hasMore: false };
-    },
-    fieldStats: async (names, signal) => {
-      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
-      const requested = [...new Set(names)];
-      if (metadataTransport?.fetchFieldStats) {
-        const backendFields = requested.filter(
-          (name) => sourceCatalogue.fields.find((field) => field.name === name)?.source.kind === "backend"
-        );
-        return backendFields.length ? metadataTransport.fetchFieldStats(backendFields, signal) : {};
-      }
-      return Object.fromEntries(requested.flatMap((name) => {
-        const field = groupingModel.sourceField(name);
-        return field && sourceRows ? [[name, { distinct: new Set(sourceRows.map((row) => JSON.stringify(readFieldValue4(field, row)))).size }]] : [];
-      }));
-    }
+    filterValues: sourceFilterValues,
+    fieldStats: sourceFieldStats
   };
   const grouping = useGroupingController(
     api,
@@ -3350,7 +3660,7 @@ function useQueryTable(opts) {
   return {
     ...api,
     ...groupingSupported || query.grouping ? { grouping } : {},
-    select: { ...select, hide: (field) => query.grouping?.keys.includes(field) ? grouping.changeKeys(query.grouping.keys.filter((key) => key !== field)) : select.hide(field) }
+    select: { ...select, hide: (field) => query.grouping && groupKeyFields2(query.grouping.keys).includes(field) ? grouping.changeKeys(query.grouping.keys.filter((key) => groupKeyField(key) !== field)) : select.hide(field) }
   };
 }
 function nextOrderBy(existing, field, additive) {