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

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, 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, 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">;
@@ -101,6 +101,8 @@ interface ItemDetailRecord<Row> {
 interface ItemDetailsOptions<Row> {
     /** Detail catalogue; defaults to the table catalogue. Useful for non-column properties. */
     schema?: FieldSchema<Row>;
+    /** Optional semantic reveal service, shared with host attention navigation. */
+    attention?: AttentionRegistry;
     /** Legacy collection URL parameter. useQueryTable.queryParameter takes precedence. */
     queryParameter?: string;
     /** Creator-approved modalities; users can enable/disable these in Select columns. Defaults to all. */
@@ -119,6 +121,14 @@ interface ItemDetailsApi<Row> {
     /** "group" details describe grouped result rows, identified by their group identity. */
     subject?: "item" | "group";
     links?: QueryLinksApi;
+    jsonInspections?: readonly ScopedJsonInspectionState[];
+    setJsonInspection?: (inspection: ScopedJsonInspectionState) => void;
+    attention?: AttentionRegistry;
+    preserveFocus?: boolean;
+    /** Ephemeral request counter; virtual tables rematerialize an expanded row per reveal. */
+    attentionRevision?: number;
+    /** Keep the requested virtual detail materialized until its reveal settles. */
+    attentionPending?: boolean;
     schema: FieldSchema<Row>;
     /** Collection catalogue used to resolve Page template fields. */
     pageSchema: FieldSchema<Row>;

package/dist/index.js

@@ -348,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";
@@ -646,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) => {
@@ -661,11 +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,
@@ -675,7 +731,7 @@ function useItemDetails({
     active,
     page,
     pageSchema: schema,
-    record: lookupRow ? looked ?? null : currentResult ? result.record : 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 } : {},
@@ -690,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,
@@ -699,6 +757,7 @@ function useItemDetails({
       } }));
     },
     close() {
+      config?.attention?.cancel();
       setQuery((current) => {
         if (!current.itemDetails?.active) return current;
         const { active: _active, ...state } = current.itemDetails;