@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/views/metadata-admin/previews/simulator/flow-sim-validate.js

@@ -0,0 +1,113 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Preflight graph validation + CEL helpers for the flow simulator.
+ *
+ * Validation runs BEFORE a simulation so the debugger refuses to "Run" a
+ * structurally broken flow (which the real runtime would reject) instead of
+ * producing misleading partial output. Condition evaluation deliberately does
+ * NOT swallow errors the way the shared `evaluatePlainCondition` does — a
+ * debugger must tell the author *why* a branch was false (parse error, missing
+ * variable, type error), so we capture and surface the message.
+ */
+import { ExpressionEvaluator } from '@object-ui/core';
+const edgeCondString = (c) => typeof c === 'string' ? c : undefined;
+/** Evaluate a CEL condition, capturing (not swallowing) any failure. */
+export function evalCondition(expr, variables) {
+    const source = expr.trim();
+    if (!source)
+        return { result: false, error: 'Empty condition.' };
+    try {
+        const evaluator = new ExpressionEvaluator({ ...variables, data: variables });
+        const isTemplate = /\$\{/.test(source);
+        const raw = isTemplate
+            ? evaluator.evaluate(source, { throwOnError: true })
+            : evaluator.evaluateExpression(source);
+        return { result: raw === true };
+    }
+    catch (err) {
+        return { result: false, error: err.message || 'Evaluation failed.' };
+    }
+}
+/** Static structural checks; `errors` block Run, `warnings` are advisory. */
+export function validateFlowDraft(nodes, edges) {
+    const errors = [];
+    const warnings = [];
+    const ids = nodes.map((n) => n.id);
+    const idSet = new Set();
+    for (const id of ids) {
+        if (!id) {
+            errors.push({ level: 'error', message: 'A node is missing an id.' });
+            continue;
+        }
+        if (idSet.has(id))
+            errors.push({ level: 'error', nodeId: id, message: `Duplicate node id "${id}".` });
+        idSet.add(id);
+    }
+    for (const e of edges) {
+        if (!idSet.has(e.source))
+            errors.push({ level: 'error', message: `Edge source "${e.source}" does not exist.` });
+        if (!idSet.has(e.target))
+            errors.push({ level: 'error', message: `Edge target "${e.target}" does not exist.` });
+    }
+    // Entry resolution: prefer an explicit `start` node, else a node with no
+    // incoming edge. Zero or many → the author must fix it before running.
+    const incoming = new Set(edges.map((e) => e.target));
+    const startNodes = nodes.filter((n) => n.type === 'start');
+    const roots = nodes.filter((n) => !incoming.has(n.id));
+    let startNodeId;
+    if (startNodes.length === 1) {
+        startNodeId = startNodes[0].id;
+        if (incoming.has(startNodeId)) {
+            warnings.push({ level: 'warning', nodeId: startNodeId, message: 'Start node has an incoming edge.' });
+        }
+    }
+    else if (startNodes.length > 1) {
+        errors.push({ level: 'error', message: `Flow has ${startNodes.length} start nodes; expected one.` });
+    }
+    else if (roots.length === 1) {
+        startNodeId = roots[0].id;
+        warnings.push({ level: 'warning', nodeId: startNodeId, message: 'No "start" node; using the only root node as the entry.' });
+    }
+    else if (roots.length === 0) {
+        errors.push({ level: 'error', message: 'No entry node (every node has an incoming edge — the graph is fully cyclic).' });
+    }
+    else {
+        errors.push({ level: 'error', message: `Cannot determine a single entry node (${roots.length} candidates). Add a "start" node.` });
+    }
+    // Per-decision: at most one default; warn on missing default (possible dead end).
+    for (const n of nodes) {
+        if (n.type !== 'decision')
+            continue;
+        const out = edges.filter((e) => e.source === n.id);
+        const defaults = out.filter((e) => e.isDefault);
+        if (defaults.length > 1) {
+            errors.push({ level: 'error', nodeId: n.id, message: `Decision "${n.id}" has ${defaults.length} default branches.` });
+        }
+        if (out.length === 0) {
+            warnings.push({ level: 'warning', nodeId: n.id, message: `Decision "${n.id}" has no outgoing branches.` });
+        }
+        else if (defaults.length === 0 && out.every((e) => edgeCondString(e.condition))) {
+            warnings.push({ level: 'warning', nodeId: n.id, message: `Decision "${n.id}" has no default branch; it may dead-end when no condition matches.` });
+        }
+    }
+    // Unreachable nodes (advisory) — BFS from the resolved entry.
+    if (startNodeId) {
+        const reachable = new Set([startNodeId]);
+        const queue = [startNodeId];
+        while (queue.length) {
+            const cur = queue.shift();
+            for (const e of edges) {
+                if (e.source === cur && idSet.has(e.target) && !reachable.has(e.target)) {
+                    reachable.add(e.target);
+                    queue.push(e.target);
+                }
+            }
+        }
+        for (const n of nodes) {
+            if (!reachable.has(n.id)) {
+                warnings.push({ level: 'warning', nodeId: n.id, message: `Node "${n.id}" is unreachable from the entry.` });
+            }
+        }
+    }
+    return { errors, warnings, startNodeId };
+}

package/dist/views/metadata-admin/previews/simulator/flow-simulator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * FlowSimulator — a deterministic, backend-free interpreter that walks a flow
+ * draft for designer-time debugging. See `flow-sim-types.ts` for the contract.
+ *
+ * Supported faithfully: start, decision (edge-first CEL routing), the CRUD /
+ * get / http / connector / script(notification|code) side-effects (MOCKED), and
+ * end. `wait` and `screen` PAUSE for manual continuation. `loop` resolves its
+ * collection and exposes the iterator but is a labelled single pass (the edge
+ * model has no separate body/exit edge). `parallel_gateway` fans out WITHOUT
+ * join synchronization; the ADR-0031 structured containers (`parallel`,
+ * `try_catch` — nested body regions), `join_gateway`, `subflow` and
+ * `boundary_event` are marked unsupported rather than faked. A hard step
+ * ceiling guards cycles.
+ */
+import type { MockResults, SimEdge, SimNode, SimState, SimStep } from './flow-sim-types';
+export declare class FlowSimulator {
+    private nodes;
+    private edges;
+    private mocks;
+    private seq;
+    state: SimState;
+    constructor(nodes: SimNode[], edges: SimEdge[]);
+    /** Validate + seed variables and queue the entry node. Returns the validation. */
+    reset(seedVariables?: Record<string, unknown>, mocks?: MockResults): import("./flow-sim-types").FlowValidation;
+    get done(): boolean;
+    /** Execute one queued node. Returns the recorded step, or null when idle. */
+    step(): SimStep | null;
+    /** Run to completion (or until a pause / error). */
+    runToEnd(): SimState;
+    /** Continue a flow paused on a `wait` / `screen` node. */
+    resume(screenOutputs?: Record<string, unknown>): void;
+    private execute;
+    private executeDecision;
+    private executeLoop;
+    /** Resolve a `{var}` template ref or a plain variable name from `variables`. */
+    private resolveRef;
+    /** Apply a node's mock output to the simulation variables; returns what it wrote. */
+    private applyMock;
+    private mockNote;
+    /** Enqueue every outgoing target (linear nodes have one; parallel fans out). */
+    private enqueueSuccessors;
+    private traverse;
+    private record;
+}

package/dist/views/metadata-admin/previews/simulator/flow-simulator.js

@@ -0,0 +1,316 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { evalCondition, validateFlowDraft } from './flow-sim-validate';
+const MAX_STEPS = 500;
+const PASS_THROUGH = new Set(['start', 'assignment']);
+const MOCKED_SIDE_EFFECT = new Set([
+    'create_record',
+    'update_record',
+    'delete_record',
+    'get_record',
+    'http_request',
+    'connector_action',
+]);
+// `parallel` / `try_catch` carry nested body regions (ADR-0031) the flat
+// stepper can't walk — pass through honestly instead of faking their semantics.
+const UNSUPPORTED = new Set(['join_gateway', 'subflow', 'boundary_event', 'parallel', 'try_catch']);
+const edgeId = (e, i) => e.id || `${e.source}->${e.target}#${i}`;
+const condStr = (c) => (typeof c === 'string' ? c : undefined);
+const str = (v) => (typeof v === 'string' && v ? v : undefined);
+export class FlowSimulator {
+    constructor(nodes, edges) {
+        Object.defineProperty(this, "nodes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "edges", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "mocks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "seq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                status: 'idle',
+                variables: {},
+                steps: [],
+                frontier: [],
+                activeNodeId: null,
+                visitedNodeIds: [],
+                traversedEdgeIds: [],
+            }
+        });
+        for (const n of nodes)
+            this.nodes.set(n.id, n);
+        this.edges = edges;
+    }
+    /** Validate + seed variables and queue the entry node. Returns the validation. */
+    reset(seedVariables = {}, mocks = {}) {
+        const validation = validateFlowDraft([...this.nodes.values()], this.edges);
+        this.mocks = mocks;
+        this.seq = 0;
+        this.state = {
+            status: validation.errors.length ? 'error' : 'idle',
+            variables: { ...seedVariables },
+            steps: [],
+            frontier: validation.startNodeId ? [validation.startNodeId] : [],
+            activeNodeId: null,
+            visitedNodeIds: [],
+            traversedEdgeIds: [],
+            error: validation.errors.length ? validation.errors[0].message : undefined,
+        };
+        return validation;
+    }
+    get done() {
+        return this.state.status === 'done' || this.state.status === 'error';
+    }
+    /** Execute one queued node. Returns the recorded step, or null when idle. */
+    step() {
+        const s = this.state;
+        if (s.status === 'error' || s.status === 'done' || s.status === 'paused')
+            return null;
+        if (this.seq >= MAX_STEPS) {
+            s.status = 'error';
+            s.error = `Step limit (${MAX_STEPS}) exceeded — the flow may contain an infinite loop.`;
+            return null;
+        }
+        const nodeId = s.frontier.shift();
+        if (!nodeId) {
+            s.status = 'done';
+            s.activeNodeId = null;
+            return null;
+        }
+        const node = this.nodes.get(nodeId);
+        if (!node) {
+            return this.record(nodeId, 'unknown', nodeId, 'error', { error: `Node "${nodeId}" not found.` });
+        }
+        s.status = 'running';
+        s.activeNodeId = nodeId;
+        if (!s.visitedNodeIds.includes(nodeId))
+            s.visitedNodeIds.push(nodeId);
+        const step = this.execute(node);
+        // Settle the run status. A pause halts the queue until resume(); a decision
+        // dead-end / missing node already set 'error' inside execute(). Only a still
+        // -'running' branch that drained the frontier completes as 'done'.
+        if (s.status === 'running' && s.frontier.length === 0) {
+            s.status = 'done';
+            s.activeNodeId = null;
+        }
+        return step;
+    }
+    /** Run to completion (or until a pause / error). */
+    runToEnd() {
+        let guard = 0;
+        while (this.state.status !== 'done' && this.state.status !== 'error' && this.state.status !== 'paused') {
+            if (++guard > MAX_STEPS + 5)
+                break;
+            this.step();
+        }
+        return this.state;
+    }
+    /** Continue a flow paused on a `wait` / `screen` node. */
+    resume(screenOutputs) {
+        const s = this.state;
+        if (s.status !== 'paused' || !s.activeNodeId)
+            return;
+        const node = this.nodes.get(s.activeNodeId);
+        if (screenOutputs && node?.type === 'screen') {
+            Object.assign(s.variables, screenOutputs);
+        }
+        s.pausedReason = undefined;
+        s.status = 'running';
+        if (node)
+            this.enqueueSuccessors(node);
+        if (s.frontier.length === 0) {
+            s.status = 'done';
+            s.activeNodeId = null;
+        }
+    }
+    // ---- node execution -----------------------------------------------------
+    execute(node) {
+        const type = node.type;
+        if (type === 'end') {
+            // Terminate this branch only; other queued branches still run.
+            return this.record(node.id, type, node.label, 'ok', { note: 'Flow end reached.' });
+        }
+        if (type === 'decision')
+            return this.executeDecision(node);
+        if (UNSUPPORTED.has(type)) {
+            this.enqueueSuccessors(node);
+            return this.record(node.id, type, node.label, 'skipped', {
+                note: `"${type}" is not modelled by the simulator; passing through without its real semantics.`,
+            });
+        }
+        if (type === 'parallel_gateway') {
+            this.enqueueSuccessors(node);
+            return this.record(node.id, type, node.label, 'ok', {
+                note: 'Parallel split — branches fan out (no join synchronization is simulated).',
+            });
+        }
+        if (type === 'wait') {
+            this.state.status = 'paused';
+            this.state.pausedReason = 'wait';
+            return this.record(node.id, type, node.label, 'paused', { note: 'Wait reached — continue manually.' });
+        }
+        if (type === 'screen') {
+            this.state.status = 'paused';
+            this.state.pausedReason = 'screen';
+            return this.record(node.id, type, node.label, 'paused', { note: 'Screen reached — provide inputs, then continue.' });
+        }
+        if (type === 'loop') {
+            const step = this.executeLoop(node);
+            this.enqueueSuccessors(node);
+            return step;
+        }
+        if (MOCKED_SIDE_EFFECT.has(type) || type === 'script') {
+            const wrote = this.applyMock(node);
+            this.enqueueSuccessors(node);
+            return this.record(node.id, type, node.label, 'mocked', {
+                wrote,
+                note: this.mockNote(node),
+            });
+        }
+        // start / assignment / anything else: pass straight through.
+        this.enqueueSuccessors(node);
+        return this.record(node.id, type, node.label, 'ok', {
+            note: PASS_THROUGH.has(type) ? undefined : `Type "${type}" treated as pass-through.`,
+        });
+    }
+    executeDecision(node) {
+        const out = this.edges
+            .map((e, i) => ({ e, i }))
+            .filter((x) => x.e.source === node.id);
+        const evals = [];
+        let chosen;
+        let firstError;
+        // Evaluate conditional edges in declared order; first truthy wins.
+        for (const { e, i } of out) {
+            if (e.isDefault)
+                continue;
+            const cond = condStr(e.condition);
+            if (!cond) {
+                evals.push({ edgeId: edgeId(e, i), target: e.target, result: false, selected: false, error: 'Branch has no condition.' });
+                continue;
+            }
+            const r = evalCondition(cond, this.state.variables);
+            if (r.error && !firstError)
+                firstError = `${cond}: ${r.error}`;
+            const selected = r.result && !chosen;
+            if (selected)
+                chosen = { e, i };
+            evals.push({ edgeId: edgeId(e, i), target: e.target, condition: cond, result: r.result, error: r.error, selected });
+        }
+        // Fall back to the default branch when no condition matched.
+        if (!chosen) {
+            const def = out.find((x) => x.e.isDefault);
+            if (def) {
+                chosen = def;
+                evals.push({ edgeId: edgeId(def.e, def.i), target: def.e.target, isDefault: true, result: true, selected: true });
+            }
+        }
+        const multiMatch = evals.filter((x) => x.result && !x.isDefault).length > 1;
+        if (chosen)
+            this.traverse(chosen.e, chosen.i);
+        return this.record(node.id, 'decision', node.label, chosen ? 'ok' : 'error', {
+            edges: evals,
+            error: chosen ? undefined : firstError ?? 'No branch matched and there is no default branch.',
+            note: multiMatch ? 'Multiple conditions matched; the first declared branch was taken.' : undefined,
+        });
+    }
+    executeLoop(node) {
+        const ref = str(node.config?.collection);
+        const iterVar = str(node.config?.iteratorVariable);
+        let note = 'Loop simulated as a single pass (body re-execution is not modelled).';
+        if (ref) {
+            const resolved = this.resolveRef(ref);
+            if (Array.isArray(resolved)) {
+                note = `Collection "${ref}" has ${resolved.length} item(s); simulated as a single pass.`;
+                if (iterVar && resolved.length)
+                    this.state.variables[iterVar] = resolved[0];
+            }
+            else if (resolved !== undefined) {
+                note = `Collection "${ref}" is not an array; loop may not run at runtime.`;
+            }
+        }
+        return this.record(node.id, 'loop', node.label, 'ok', { note });
+    }
+    // ---- helpers ------------------------------------------------------------
+    /** Resolve a `{var}` template ref or a plain variable name from `variables`. */
+    resolveRef(ref) {
+        const m = ref.match(/^\{(.+)\}$/);
+        const key = (m ? m[1] : ref).trim();
+        return this.state.variables[key];
+    }
+    /** Apply a node's mock output to the simulation variables; returns what it wrote. */
+    applyMock(node) {
+        const cfg = node.config ?? {};
+        const mock = this.mocks[node.id];
+        const wrote = {};
+        const single = str(cfg.outputVariable);
+        if (single) {
+            wrote[single] = mock !== undefined ? mock : {};
+            this.state.variables[single] = wrote[single];
+        }
+        const list = Array.isArray(cfg.outputVariables) ? cfg.outputVariables : [];
+        if (list.length) {
+            const m = mock && typeof mock === 'object' ? mock : {};
+            for (const name of list) {
+                if (typeof name !== 'string')
+                    continue;
+                wrote[name] = name in m ? m[name] : undefined;
+                this.state.variables[name] = wrote[name];
+            }
+        }
+        return Object.keys(wrote).length ? wrote : undefined;
+    }
+    mockNote(node) {
+        if (node.type === 'script') {
+            const action = str(node.config?.actionType);
+            if (action && action !== 'code') {
+                const recips = Array.isArray(node.config?.recipients) ? node.config.recipients.length : 0;
+                return `Mocked ${action} notification${recips ? ` to ${recips} recipient(s)` : ''}.`;
+            }
+            return 'Mocked code script (no real code executed).';
+        }
+        return `Mocked ${node.type.replace(/_/g, ' ')} (no backend call).`;
+    }
+    /** Enqueue every outgoing target (linear nodes have one; parallel fans out). */
+    enqueueSuccessors(node) {
+        this.edges.forEach((e, i) => {
+            if (e.source === node.id)
+                this.traverse(e, i);
+        });
+    }
+    traverse(e, i) {
+        const id = edgeId(e, i);
+        if (!this.state.traversedEdgeIds.includes(id))
+            this.state.traversedEdgeIds.push(id);
+        if (this.nodes.has(e.target))
+            this.state.frontier.push(e.target);
+    }
+    record(nodeId, type, label, status, extra = {}) {
+        const step = { seq: this.seq++, nodeId, type, label: label || nodeId, status, ...extra };
+        this.state.steps.push(step);
+        if (status === 'error' && this.state.status !== 'paused') {
+            this.state.status = 'error';
+            this.state.error = extra.error;
+        }
+        return step;
+    }
+}

package/dist/views/metadata-admin/previews/useDatasetCatalog.d.ts

@@ -0,0 +1,47 @@
+export interface DatasetDimensionInfo {
+    /** Dimension name (snake_case, referenced by `report.rows`). */
+    name: string;
+    /** Raw field type id when declared (e.g. 'text', 'date'). */
+    type?: string;
+}
+export interface DatasetMeasureInfo {
+    /** Measure name (snake_case, referenced by `report.values`). */
+    name: string;
+    /** Aggregate function (sum / avg / count / …) — display hint only. */
+    aggregate?: string;
+    /** Whether the dataset author certified this measure. */
+    certified?: boolean;
+}
+export interface DatasetCatalogEntry {
+    /** Dataset unique name (what `report.dataset` stores). */
+    name: string;
+    /** Human label (falls back to the name). */
+    label: string;
+    dimensions: DatasetDimensionInfo[];
+    measures: DatasetMeasureInfo[];
+}
+export interface UseDatasetCatalogResult {
+    datasets: DatasetCatalogEntry[];
+    loading: boolean;
+    error: string | null;
+}
+/** Normalize a raw dataset document into a catalog entry. */
+export declare function toCatalogEntry(doc: Record<string, unknown>): DatasetCatalogEntry | null;
+export declare function useDatasetCatalog(
+/**
+ * Pre-resolved catalog. When supplied the hook skips the network fetch
+ * entirely and returns this list verbatim.
+ */
+override?: DatasetCatalogEntry[]): UseDatasetCatalogResult;
+export interface UseDatasetSemanticsResult {
+    dimensions: DatasetDimensionInfo[];
+    measures: DatasetMeasureInfo[];
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * Resolve the bound dataset's dimensions/measures from the catalog, lazily
+ * hydrating via `client.get('dataset', name)` when the list endpoint returned
+ * a summary without them (some servers list names only).
+ */
+export declare function useDatasetSemantics(name: string | undefined, catalog: UseDatasetCatalogResult): UseDatasetSemanticsResult;

package/dist/views/metadata-admin/previews/useDatasetCatalog.js

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * useDatasetCatalog — loads the analytics dataset catalog for the Report
+ * inspector's dataset binding controls (ADR-0021 single-form).
+ *
+ * A 9.0 report binds a semantic-layer `dataset` and selects its `values`
+ * (measure names) grouped by `rows` (dimension names) — so the editor needs
+ * (a) the list of datasets to bind, and (b) the bound dataset's
+ * dimensions/measures to offer as picker options.
+ *
+ * Mirrors {@link useObjectFields}: defensive (a 404 or transport error
+ * resolves to an empty catalog with `error` set, the inspector falls back to
+ * manual entry) and override-friendly (hosts that already hold the catalog
+ * pass it to keep the inspector network-free, e.g. tests and the runtime
+ * config panel).
+ */
+import * as React from 'react';
+import { useMetadataClient } from '../useMetadata';
+function resolveLabel(label, fallback) {
+    if (typeof label === 'string' && label)
+        return label;
+    if (label && typeof label === 'object') {
+        const def = label.default;
+        if (typeof def === 'string' && def)
+            return def;
+    }
+    return fallback;
+}
+/** Normalize a raw dataset document into a catalog entry. */
+export function toCatalogEntry(doc) {
+    const name = typeof doc.name === 'string' ? doc.name : '';
+    if (!name)
+        return null;
+    const dimensions = Array.isArray(doc.dimensions)
+        ? doc.dimensions
+            .filter((d) => d && typeof d.name === 'string' && d.name)
+            .map((d) => ({
+            name: d.name,
+            type: typeof d.type === 'string' ? d.type : undefined,
+        }))
+        : [];
+    const measures = Array.isArray(doc.measures)
+        ? doc.measures
+            .filter((m) => m && typeof m.name === 'string' && m.name)
+            .map((m) => ({
+            name: m.name,
+            aggregate: typeof m.aggregate === 'string' ? m.aggregate : undefined,
+            certified: m.certified === true,
+        }))
+        : [];
+    return { name, label: resolveLabel(doc.label, name), dimensions, measures };
+}
+export function useDatasetCatalog(
+/**
+ * Pre-resolved catalog. When supplied the hook skips the network fetch
+ * entirely and returns this list verbatim.
+ */
+override) {
+    const client = useMetadataClient();
+    const [state, setState] = React.useState({
+        datasets: override ?? [],
+        loading: !override,
+        error: null,
+    });
+    React.useEffect(() => {
+        if (override) {
+            setState({ datasets: override, loading: false, error: null });
+            return;
+        }
+        let cancelled = false;
+        setState((s) => ({ ...s, loading: true, error: null }));
+        client
+            .list('dataset')
+            .then((docs) => {
+            if (cancelled)
+                return;
+            const datasets = (Array.isArray(docs) ? docs : [])
+                .map(toCatalogEntry)
+                .filter((e) => e !== null);
+            setState({ datasets, loading: false, error: null });
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setState({ datasets: [], loading: false, error: err?.message ?? String(err) });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, override]);
+    return state;
+}
+/**
+ * Resolve the bound dataset's dimensions/measures from the catalog, lazily
+ * hydrating via `client.get('dataset', name)` when the list endpoint returned
+ * a summary without them (some servers list names only).
+ */
+export function useDatasetSemantics(name, catalog) {
+    const client = useMetadataClient();
+    const entry = name ? catalog.datasets.find((d) => d.name === name) : undefined;
+    const needsFetch = !!name && !catalog.loading &&
+        (!entry || (entry.dimensions.length === 0 && entry.measures.length === 0));
+    const [fetched, setFetched] = React.useState(null);
+    React.useEffect(() => {
+        if (!needsFetch || !name)
+            return;
+        if (fetched?.name === name)
+            return;
+        let cancelled = false;
+        client
+            .get('dataset', name)
+            .then((doc) => {
+            if (cancelled)
+                return;
+            setFetched({ name, entry: doc ? toCatalogEntry(doc) : null, error: doc ? null : 'Dataset not found' });
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setFetched({ name, entry: null, error: err?.message ?? String(err) });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, name, needsFetch, fetched]);
+    const resolved = needsFetch && fetched?.name === name ? fetched.entry : entry;
+    return {
+        dimensions: resolved?.dimensions ?? [],
+        measures: resolved?.measures ?? [],
+        loading: catalog.loading || (needsFetch && fetched?.name !== name),
+        error: (needsFetch && fetched?.name === name ? fetched.error : null) ?? catalog.error,
+    };
+}