@visns-studio/visns-components 6.1.7 → 6.2.0

package/src/components/generic/reportSemantics.js

@@ -0,0 +1,971 @@
+/**
+ * Semantic report model helpers.
+ *
+ * The semantic model lets a non-technical user design a report in business
+ * language: entities, labelled fields and labelled relations. Nothing in this
+ * module knows about database tables, columns or joins — field ids are opaque
+ * handles that the server maps back to storage.
+ *
+ * Everything here is pure. The network call lives in `useSemanticModel`, and
+ * the wizard UI lives in `./reportSemanticSteps/*`.
+ */
+
+/** Version stamped onto every definition this module produces. */
+export const SEMANTIC_SCHEMA_VERSION = 2;
+
+/** Default endpoint probed on mount when `setting.semanticModelUrl` is absent. */
+export const DEFAULT_SEMANTIC_MODEL_URL = '/ajax/reportBuilder/semanticModel';
+
+/** Field types the semantic model may declare. */
+export const FIELD_TYPES = [
+    'text',
+    'number',
+    'money',
+    'percent',
+    'date',
+    'datetime',
+    'boolean',
+    'enum',
+];
+
+/** Types that can be summed or averaged without an explicit `summable` flag. */
+const NUMERIC_TYPES = ['number', 'money', 'percent'];
+
+/** Types that carry an ordering, so min/max read as earliest/latest. */
+const TEMPORAL_TYPES = ['date', 'datetime'];
+
+/**
+ * Operators offered per field type, in the order they should appear in menus.
+ * Unknown types fall back to the text operators.
+ */
+export const OPERATORS_BY_TYPE = {
+    text: [
+        'equals',
+        'not_equals',
+        'contains',
+        'not_contains',
+        'is_empty',
+        'not_empty',
+    ],
+    number: [
+        'equals',
+        'not_equals',
+        'gt',
+        'gte',
+        'lt',
+        'lte',
+        'between',
+        'is_empty',
+        'not_empty',
+    ],
+    date: ['equals', 'before', 'after', 'between', 'is_empty', 'not_empty'],
+    boolean: ['is_true', 'is_false'],
+    enum: ['equals', 'not_equals', 'in', 'not_in'],
+};
+
+OPERATORS_BY_TYPE.money = OPERATORS_BY_TYPE.number;
+OPERATORS_BY_TYPE.percent = OPERATORS_BY_TYPE.number;
+OPERATORS_BY_TYPE.datetime = OPERATORS_BY_TYPE.date;
+
+/** Plain-language operator names shown to the user. */
+export const OPERATOR_LABELS = {
+    equals: 'is',
+    not_equals: 'is not',
+    contains: 'contains',
+    not_contains: 'does not contain',
+    is_empty: 'is blank',
+    not_empty: 'is not blank',
+    gt: 'is more than',
+    gte: 'is at least',
+    lt: 'is less than',
+    lte: 'is at most',
+    between: 'is between',
+    before: 'is before',
+    after: 'is after',
+    is_true: 'is yes',
+    is_false: 'is no',
+    in: 'is any of',
+    not_in: 'is none of',
+};
+
+/** Operators that take no value at all. */
+const VALUELESS_OPERATORS = ['is_empty', 'not_empty', 'is_true', 'is_false'];
+
+/** Operators that take an open-ended list of values. */
+const LIST_OPERATORS = ['in', 'not_in'];
+
+/** Aggregate ids, in menu order. An empty agg means "show the plain value". */
+export const AGGREGATES = ['sum', 'count', 'avg', 'min', 'max'];
+
+/** Field-type categories used to group the field picker. */
+export const FIELD_CATEGORIES = [
+    { id: 'text', label: 'Details', types: ['text'] },
+    {
+        id: 'amounts',
+        label: 'Amounts & numbers',
+        types: ['number', 'money', 'percent'],
+    },
+    { id: 'dates', label: 'Dates', types: ['date', 'datetime'] },
+    { id: 'status', label: 'Status & yes/no', types: ['boolean', 'enum'] },
+];
+
+/* -------------------------------------------------------------------------- */
+/* Model normalisation                                                        */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Pull the `{ entities }` map out of whatever shape the endpoint returned.
+ * Returns null when the payload carries no usable entities, which is the
+ * signal to stay in legacy mode.
+ *
+ * @param {*} payload Raw response body (or a CustomFetch response envelope).
+ * @returns {{entities: Object}|null}
+ */
+export const normalizeSemanticModel = (payload) => {
+    if (!payload || typeof payload !== 'object') return null;
+
+    // Accept `{success, data:{entities}}`, `{data:{entities}}`, `{entities}`,
+    // or a bare entity map — in that order of preference.
+    const candidates = [
+        payload?.data?.data?.entities,
+        payload?.data?.entities,
+        payload?.entities,
+        payload?.data?.data,
+        payload?.data,
+        payload,
+    ];
+
+    const entities = candidates.find(
+        (candidate) =>
+            candidate &&
+            typeof candidate === 'object' &&
+            !Array.isArray(candidate) &&
+            Object.values(candidate).some(
+                (entity) =>
+                    entity &&
+                    typeof entity === 'object' &&
+                    (entity.fields || entity.relations)
+            )
+    );
+
+    if (!entities) return null;
+
+    const usable = Object.entries(entities).filter(
+        ([, entity]) => entity && typeof entity === 'object' && entity.fields
+    );
+
+    if (usable.length === 0) return null;
+
+    return {
+        entities: usable.reduce((acc, [id, entity]) => {
+            acc[id] = {
+                ...entity,
+                label: entity.label || entity.plural || id,
+                fields: entity.fields || {},
+                relations: entity.relations || {},
+            };
+            return acc;
+        }, {}),
+    };
+};
+
+/**
+ * Entities offered as a starting point, sorted by label.
+ *
+ * `hidden` entities are left out: they are lookups ("Notes", "Task types")
+ * that exist so a relation has somewhere to land. They stay in the model — a
+ * path like `notes.subject` still resolves through them — they are just never
+ * something you start a report *about*.
+ *
+ * @returns {Array<{id: string, label, plural, description}>}
+ */
+export const listEntities = (model) => {
+    if (!model?.entities) return [];
+    return Object.entries(model.entities)
+        .filter(([, entity]) => !entity.hidden)
+        .map(([id, entity]) => ({
+            id,
+            label: entity.label || id,
+            plural: entity.plural || entity.label || id,
+            description: entity.description || '',
+            fieldCount: Object.keys(entity.fields || {}).length,
+            relationCount: Object.keys(entity.relations || {}).length,
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+};
+
+export const getEntity = (model, entityId) =>
+    (model?.entities && model.entities[entityId]) || null;
+
+export const getEntityLabel = (model, entityId) =>
+    getEntity(model, entityId)?.label || entityId || '';
+
+/** @returns {Array<{id, label, entity, cardinality, description}>} */
+export const listRelations = (model, entityId) => {
+    const entity = getEntity(model, entityId);
+    if (!entity) return [];
+    return Object.entries(entity.relations || {})
+        .map(([id, relation]) => ({
+            id,
+            label: relation.label || id,
+            entity: relation.entity,
+            cardinality: relation.cardinality === 'many' ? 'many' : 'one',
+            description: relation.description || '',
+            targetLabel: getEntityLabel(model, relation.entity),
+        }))
+        .filter((relation) => !!getEntity(model, relation.entity))
+        .sort((a, b) => a.label.localeCompare(b.label));
+};
+
+/** "one of these" vs "many of these", for the relation cardinality hint. */
+export const cardinalityHint = (relation) =>
+    relation?.cardinality === 'many'
+        ? 'Many per record — rows may repeat'
+        : 'One per record';
+
+/* -------------------------------------------------------------------------- */
+/* Field path resolution                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Walk a dot-path of relations (no trailing field), e.g. `adviser.team`.
+ *
+ * @returns {{entityId, label, cardinality, hops}|null} null when any hop is
+ * undeclared. `cardinality` is 'many' when any hop along the way is 'many'.
+ */
+export const resolveRelationPath = (model, rootEntityId, path) => {
+    if (!model || !rootEntityId) return null;
+    if (!path) {
+        return {
+            entityId: rootEntityId,
+            label: getEntityLabel(model, rootEntityId),
+            cardinality: 'one',
+            hops: [],
+        };
+    }
+
+    let entityId = rootEntityId;
+    let cardinality = 'one';
+    const hops = [];
+
+    const segments = String(path).split('.');
+    for (let index = 0; index < segments.length; index += 1) {
+        const relation = getEntity(model, entityId)?.relations?.[
+            segments[index]
+        ];
+        if (!relation || !getEntity(model, relation.entity)) return null;
+        if (relation.cardinality === 'many') cardinality = 'many';
+        hops.push({
+            id: segments[index],
+            label: relation.label || segments[index],
+        });
+        entityId = relation.entity;
+    }
+
+    return {
+        entityId,
+        label: hops.map((hop) => hop.label).join(' › '),
+        cardinality,
+        hops,
+    };
+};
+
+/**
+ * Walk a dot-path such as `adviser.name` (or a chained `adviser.team.name`)
+ * from a root entity down to a field.
+ *
+ * @returns {{
+ *   path: string,
+ *   fieldId: string,
+ *   field: Object,
+ *   entityId: string,
+ *   label: string,
+ *   fullLabel: string,
+ *   type: string,
+ *   relationPath: Array<{id, label, cardinality, entity}>,
+ * }|null} null when any hop is undeclared.
+ */
+export const resolveFieldPath = (model, rootEntityId, path) => {
+    if (!model || !rootEntityId || typeof path !== 'string' || !path) {
+        return null;
+    }
+
+    const segments = path.split('.');
+    const fieldId = segments.pop();
+    let entityId = rootEntityId;
+    const relationPath = [];
+
+    for (let index = 0; index < segments.length; index += 1) {
+        const entity = getEntity(model, entityId);
+        const relation = entity?.relations?.[segments[index]];
+        if (!relation || !getEntity(model, relation.entity)) return null;
+        relationPath.push({
+            id: segments[index],
+            label: relation.label || segments[index],
+            cardinality: relation.cardinality === 'many' ? 'many' : 'one',
+            entity: relation.entity,
+        });
+        entityId = relation.entity;
+    }
+
+    const entity = getEntity(model, entityId);
+    const field = entity?.fields?.[fieldId];
+    if (!field) return null;
+
+    const label = field.label || fieldId;
+    const fullLabel = relationPath.length
+        ? `${relationPath.map((hop) => hop.label).join(' › ')} › ${label}`
+        : label;
+
+    return {
+        path,
+        fieldId,
+        field,
+        entityId,
+        label,
+        fullLabel,
+        type: FIELD_TYPES.includes(field.type) ? field.type : 'text',
+        relationPath,
+    };
+};
+
+/**
+ * Every field directly on `entityId`, as resolved descriptors, sorted by label.
+ * `prefix` prepends a relation path so the returned `path` is root-relative.
+ */
+export const listEntityFields = (model, entityId, prefix = '') => {
+    const entity = getEntity(model, entityId);
+    if (!entity) return [];
+    return Object.entries(entity.fields || {})
+        .map(([id, field]) => ({
+            path: prefix ? `${prefix}.${id}` : id,
+            fieldId: id,
+            field,
+            entityId,
+            label: field.label || id,
+            type: FIELD_TYPES.includes(field.type) ? field.type : 'text',
+            summable: !!field.summable,
+            values: field.values || null,
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+};
+
+/** Bucket resolved field descriptors into the type categories. */
+export const categorizeSemanticFields = (fields) => {
+    const buckets = FIELD_CATEGORIES.map((category) => ({
+        ...category,
+        fields: [],
+    }));
+    const other = { id: 'other', label: 'Other', fields: [] };
+
+    (fields || []).forEach((entry) => {
+        const bucket = buckets.find((candidate) =>
+            candidate.types.includes(entry.type)
+        );
+        (bucket || other).fields.push(entry);
+    });
+
+    return [...buckets, other].filter((bucket) => bucket.fields.length > 0);
+};
+
+/* -------------------------------------------------------------------------- */
+/* Aggregates                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/** True when sum/avg make sense for this field. */
+export const isSummableField = (field) =>
+    !!field &&
+    (field.summable === true || NUMERIC_TYPES.includes(field.type || ''));
+
+/**
+ * Aggregates offered for a field.
+ *
+ * Contract fixes sum/avg (summable or numeric) and count (anything). min/max
+ * are unspecified there, so we also offer them on dates — "earliest"/"latest"
+ * is the one aggregate a non-technical user reliably wants from a date.
+ */
+export const aggregatesForField = (field) => {
+    if (!field) return [];
+    const type = field.type || 'text';
+    const available = ['count'];
+    if (isSummableField(field)) {
+        available.unshift('sum', 'avg');
+        available.push('min', 'max');
+    } else if (TEMPORAL_TYPES.includes(type)) {
+        available.push('min', 'max');
+    }
+    return AGGREGATES.filter((agg) => available.includes(agg));
+};
+
+/** Menu label for an aggregate applied to a field, e.g. "Earliest". */
+export const aggregateOptionLabel = (agg, field) => {
+    const temporal = TEMPORAL_TYPES.includes(field?.type || '');
+    switch (agg) {
+        case 'sum':
+            return 'Total';
+        case 'count':
+            return 'Count';
+        case 'avg':
+            return 'Average';
+        case 'min':
+            return temporal ? 'Earliest' : 'Lowest';
+        case 'max':
+            return temporal ? 'Latest' : 'Highest';
+        default:
+            return 'Value';
+    }
+};
+
+/**
+ * Default column heading for an aggregated field. This doubles as the row key
+ * the server echoes back, so it must be stable and human-readable.
+ */
+export const defaultAggregateLabel = (agg, fieldLabelText, field) => {
+    const temporal = TEMPORAL_TYPES.includes(field?.type || '');
+    switch (agg) {
+        case 'sum':
+            return `Total ${fieldLabelText.toLowerCase()}`;
+        case 'count':
+            return `Number of ${fieldLabelText.toLowerCase()}`;
+        case 'avg':
+            return `Average ${fieldLabelText.toLowerCase()}`;
+        case 'min':
+            return `${temporal ? 'Earliest' : 'Lowest'} ${fieldLabelText.toLowerCase()}`;
+        case 'max':
+            return `${temporal ? 'Latest' : 'Highest'} ${fieldLabelText.toLowerCase()}`;
+        default:
+            return fieldLabelText;
+    }
+};
+
+/* -------------------------------------------------------------------------- */
+/* Selected columns                                                           */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A selection is `{ path, agg, label }`. `agg` is '' for a plain value.
+ * The row key the server returns is the path for plain fields and the label
+ * for aggregates — see `selectionKey`.
+ */
+/**
+ * Default heading for a selection.
+ *
+ * A plain value keeps its relation context ("Their adviser › Name"), because
+ * a bare "Name" is ambiguous once two areas are in play. An aggregate uses the
+ * short field label so the heading still reads as English ("Total fee
+ * amount"); `dedupeSelectionLabels` resolves any collision that creates.
+ */
+export const defaultSelectionLabel = (resolved, agg = '') => {
+    if (!resolved) return '';
+    return agg
+        ? defaultAggregateLabel(agg, resolved.label, resolved.field)
+        : resolved.fullLabel;
+};
+
+export const createSelection = (model, rootEntityId, path, agg = '') => {
+    const resolved = resolveFieldPath(model, rootEntityId, path);
+    if (!resolved) return null;
+    return {
+        path,
+        agg: agg || '',
+        label: defaultSelectionLabel(resolved, agg),
+    };
+};
+
+/** The exact key this column will occupy in an executed row. */
+export const selectionKey = (selection) =>
+    selection?.agg ? selection.label : selection?.path;
+
+/** Heading shown to the user — always the label, never a raw server key. */
+export const selectionHeader = (model, rootEntityId, selection) => {
+    if (!selection) return '';
+    if (selection.agg) return selection.label || selection.path;
+    const resolved = resolveFieldPath(model, rootEntityId, selection.path);
+    if (!resolved) return selection.label || selection.path;
+    return selection.label || resolved.fullLabel;
+};
+
+/**
+ * Ensure aggregate labels stay unique — they are row keys, so a collision
+ * would silently drop a column.
+ */
+export const dedupeSelectionLabels = (selections) => {
+    const seen = new Map();
+    return (selections || []).map((selection) => {
+        const key = selectionKey(selection);
+        const count = seen.get(key) || 0;
+        seen.set(key, count + 1);
+        if (count === 0 || !selection.agg) return selection;
+        return { ...selection, label: `${selection.label} (${count + 1})` };
+    });
+};
+
+/* -------------------------------------------------------------------------- */
+/* Filter tree                                                                */
+/* -------------------------------------------------------------------------- */
+
+let nodeCounter = 0;
+
+const nextNodeId = () => {
+    nodeCounter += 1;
+    return `node_${nodeCounter}`;
+};
+
+/** How many values an operator consumes: 0, 1, 2, or 'list'. */
+export const operatorArity = (operator) => {
+    if (VALUELESS_OPERATORS.includes(operator)) return 0;
+    if (LIST_OPERATORS.includes(operator)) return 'list';
+    if (operator === 'between') return 2;
+    return 1;
+};
+
+/** Operators valid for a field type, defaulting to the text set. */
+export const operatorsForType = (type) =>
+    OPERATORS_BY_TYPE[type] || OPERATORS_BY_TYPE.text;
+
+export const operatorLabel = (operator) =>
+    OPERATOR_LABELS[operator] || operator || '';
+
+export const createFilterCondition = (path = '', operator = '') => ({
+    _id: nextNodeId(),
+    kind: 'condition',
+    field: path,
+    operator,
+    value: '',
+    values: [],
+    param: '',
+    askEachTime: false,
+});
+
+export const createFilterGroup = (op = 'and', items = []) => ({
+    _id: nextNodeId(),
+    kind: 'group',
+    op,
+    items,
+});
+
+export const isFilterGroup = (node) =>
+    !!node && (node.kind === 'group' || Array.isArray(node.items));
+
+/** Depth-first walk over every condition node in a tree. */
+export const forEachCondition = (node, visit) => {
+    if (!node) return;
+    if (isFilterGroup(node)) {
+        (node.items || []).forEach((child) => forEachCondition(child, visit));
+        return;
+    }
+    visit(node);
+};
+
+/** Immutably replace the node with `_id === id`; `updater` returns the new node
+ * or null to delete it. */
+export const updateFilterNode = (node, id, updater) => {
+    if (!node) return node;
+    if (node._id === id) return updater(node);
+    if (!isFilterGroup(node)) return node;
+    return {
+        ...node,
+        items: (node.items || [])
+            .map((child) => updateFilterNode(child, id, updater))
+            .filter((child) => child !== null),
+    };
+};
+
+/** Append `child` to the group with `_id === groupId`. */
+export const appendToFilterGroup = (node, groupId, child) =>
+    updateFilterNode(node, groupId, (group) => ({
+        ...group,
+        items: [...(group.items || []), child],
+    }));
+
+/** A condition is complete enough to serialise. */
+export const isConditionComplete = (condition) => {
+    if (!condition?.field || !condition?.operator) return false;
+    const arity = operatorArity(condition.operator);
+    if (arity === 0) return true;
+    if (condition.askEachTime) return !!condition.param;
+    if (arity === 'list') return (condition.values || []).length > 0;
+    if (arity === 2) {
+        const [from, to] = condition.values || [];
+        return from !== '' && from != null && to !== '' && to != null;
+    }
+    return condition.value !== '' && condition.value != null;
+};
+
+/** Parameter type inferred from the field type and the operator it feeds. */
+export const parameterTypeFor = (fieldType, operator) => {
+    if (operator === 'between') {
+        if (TEMPORAL_TYPES.includes(fieldType)) return 'date_range';
+        if (NUMERIC_TYPES.includes(fieldType)) return 'number_range';
+        return 'range';
+    }
+    if (LIST_OPERATORS.includes(operator)) {
+        return fieldType === 'enum' ? 'enum_multi' : 'list';
+    }
+    if (TEMPORAL_TYPES.includes(fieldType)) return fieldType;
+    if (NUMERIC_TYPES.includes(fieldType)) return 'number';
+    if (fieldType === 'boolean') return 'boolean';
+    if (fieldType === 'enum') return 'enum';
+    return 'text';
+};
+
+/** Slug used as a parameter id when the user has not named one. */
+export const suggestParameterId = (path, operator) =>
+    `${String(path || 'value')
+        .replace(/[^a-z0-9]+/gi, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase()}_${operator === 'between' ? 'range' : 'value'}`;
+
+/* -------------------------------------------------------------------------- */
+/* Serialisation                                                              */
+/* -------------------------------------------------------------------------- */
+
+const serializeCondition = (condition) => {
+    const node = {
+        field: condition.field,
+        operator: condition.operator,
+    };
+    const arity = operatorArity(condition.operator);
+    if (arity === 0) return node;
+    if (condition.askEachTime && condition.param) {
+        node.param = condition.param;
+        return node;
+    }
+    if (arity === 'list') {
+        node.value = [...(condition.values || [])];
+    } else if (arity === 2) {
+        node.value = [
+            condition.values?.[0] ?? '',
+            condition.values?.[1] ?? '',
+        ];
+    } else {
+        node.value = condition.value;
+    }
+    return node;
+};
+
+/**
+ * Serialise the editing tree into the wire format, dropping incomplete
+ * conditions and groups that end up empty. Returns null when nothing survives,
+ * so the caller can omit `filters` entirely.
+ */
+export const serializeFilterTree = (node) => {
+    if (!node) return null;
+    if (!isFilterGroup(node)) {
+        return isConditionComplete(node) ? serializeCondition(node) : null;
+    }
+    const items = (node.items || [])
+        .map((child) => serializeFilterTree(child))
+        .filter(Boolean);
+    if (items.length === 0) return null;
+    return { op: node.op === 'or' ? 'or' : 'and', items };
+};
+
+/** Inverse of `serializeFilterTree` — rebuilds the editing tree with `_id`s. */
+export const deserializeFilterTree = (node) => {
+    if (!node) return createFilterGroup('and', []);
+    if (isFilterGroup(node)) {
+        return createFilterGroup(
+            node.op === 'or' ? 'or' : 'and',
+            (node.items || []).map((child) => deserializeFilterTree(child))
+        );
+    }
+    const condition = createFilterCondition(node.field, node.operator);
+    const arity = operatorArity(node.operator);
+    if (node.param) {
+        condition.askEachTime = true;
+        condition.param = node.param;
+    } else if (arity === 'list' || arity === 2) {
+        condition.values = Array.isArray(node.value) ? [...node.value] : [];
+    } else if (arity === 1) {
+        condition.value = node.value ?? '';
+    }
+    return condition;
+};
+
+/**
+ * Collect parameter definitions declared by "ask each time" conditions.
+ * `existing` supplies previously edited labels so they survive a rebuild.
+ */
+export const collectParameters = (model, entityId, tree, existing = []) => {
+    const byId = new Map((existing || []).map((param) => [param.id, param]));
+    const collected = [];
+    const seen = new Set();
+
+    forEachCondition(tree, (condition) => {
+        if (!condition.askEachTime || !condition.param) return;
+        if (seen.has(condition.param)) return;
+        seen.add(condition.param);
+
+        const resolved = resolveFieldPath(model, entityId, condition.field);
+        const previous = byId.get(condition.param);
+        collected.push({
+            id: condition.param,
+            label:
+                previous?.label ||
+                (resolved
+                    ? `${resolved.fullLabel} ${operatorLabel(condition.operator)}`
+                    : condition.param),
+            type: parameterTypeFor(resolved?.type || 'text', condition.operator),
+            required: previous?.required !== false,
+        });
+    });
+
+    return collected;
+};
+
+/**
+ * Build the v2 report definition document.
+ *
+ * @param {Object} args
+ * @param {Object} args.model      Normalised semantic model.
+ * @param {string} args.entity     Root entity id.
+ * @param {Array}  args.selections Column selections (`{path, agg, label}`).
+ * @param {Object} args.filterTree Editing filter tree.
+ * @param {Array}  args.parameters Parameter definitions.
+ * @param {Array}  args.groupBy    Field paths to group by.
+ * @param {Array}  args.sort       `[{field, dir}]` where field is a path.
+ */
+export const buildDefinition = ({
+    model,
+    entity,
+    selections = [],
+    filterTree = null,
+    parameters = [],
+    groupBy = [],
+    sort = [],
+}) => {
+    const definition = {
+        schema_version: SEMANTIC_SCHEMA_VERSION,
+        entity,
+        fields: dedupeSelectionLabels(selections).map((selection) =>
+            selection.agg
+                ? {
+                      agg: selection.agg,
+                      field: selection.path,
+                      label: selection.label,
+                  }
+                : { field: selection.path }
+        ),
+    };
+
+    const filters = serializeFilterTree(filterTree);
+    if (filters) definition.filters = filters;
+
+    const usedParamIds = new Set();
+    forEachCondition(filterTree, (condition) => {
+        if (condition.askEachTime && condition.param) {
+            usedParamIds.add(condition.param);
+        }
+    });
+    const activeParameters = (parameters || []).filter((param) =>
+        usedParamIds.has(param.id)
+    );
+    if (activeParameters.length > 0) definition.parameters = activeParameters;
+
+    const validGroupBy = (groupBy || []).filter((path) =>
+        model ? !!resolveFieldPath(model, entity, path) : true
+    );
+    if (validGroupBy.length > 0) definition.groupBy = validGroupBy;
+
+    const validSort = (sort || []).filter((entry) => entry && entry.field);
+    if (validSort.length > 0) {
+        definition.sort = validSort.map((entry) => ({
+            field: entry.field,
+            dir: entry.dir === 'desc' ? 'desc' : 'asc',
+        }));
+    }
+
+    return definition;
+};
+
+/** True when a saved `detail` document is a v2 semantic definition. */
+export const isSemanticDefinition = (detail) => {
+    if (!detail || typeof detail !== 'object') return false;
+    if (detail.mainTable) return false;
+    return (
+        detail.schema_version === SEMANTIC_SCHEMA_VERSION ||
+        (!!detail.entity && Array.isArray(detail.fields))
+    );
+};
+
+/** Rehydrate wizard state from a saved v2 definition. */
+export const parseDefinition = (definition) => {
+    if (!isSemanticDefinition(definition)) return null;
+
+    const selections = (definition.fields || []).map((field) => ({
+        path: field.field,
+        agg: field.agg || '',
+        label: field.label || '',
+    }));
+
+    return {
+        entity: definition.entity,
+        selections,
+        filterTree: definition.filters
+            ? deserializeFilterTree(definition.filters)
+            : createFilterGroup('and', []),
+        parameters: Array.isArray(definition.parameters)
+            ? definition.parameters.map((param) => ({ ...param }))
+            : [],
+        groupBy: Array.isArray(definition.groupBy)
+            ? [...definition.groupBy]
+            : [],
+        sort: Array.isArray(definition.sort)
+            ? definition.sort.map((entry) => ({
+                  field: entry.field,
+                  dir: entry.dir === 'desc' ? 'desc' : 'asc',
+              }))
+            : [],
+    };
+};
+
+/**
+ * Recover the related areas a parsed definition reaches through, so the
+ * relations step can show them as already added after a load. Every prefix of
+ * every dot-path is included, which is what makes chained relations reappear.
+ */
+export const relationPathsFromDefinition = (parsed, model) => {
+    if (!parsed) return [];
+
+    const paths = new Set();
+    const addPath = (path) => {
+        if (typeof path !== 'string' || !path.includes('.')) return;
+        const segments = path.split('.');
+        segments.pop(); // the field itself
+        segments.forEach((segment, index) => {
+            paths.add(segments.slice(0, index + 1).join('.'));
+        });
+    };
+
+    (parsed.selections || []).forEach((selection) => addPath(selection.path));
+    (parsed.groupBy || []).forEach(addPath);
+    (parsed.sort || []).forEach((entry) => addPath(entry.field));
+    forEachCondition(parsed.filterTree, (condition) =>
+        addPath(condition.field)
+    );
+
+    const resolvable = Array.from(paths).filter((path) =>
+        model ? !!resolveRelationPath(model, parsed.entity, path) : true
+    );
+
+    // Shortest first, so a parent is always listed before anything nested.
+    return resolvable.sort(
+        (a, b) => a.split('.').length - b.split('.').length
+    );
+};
+
+/* -------------------------------------------------------------------------- */
+/* Runtime parameters                                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Find the field path a parameter feeds, by locating the condition that
+ * references it. The wire format for a parameter carries only id/label/type/
+ * required, so this is how the run screen recovers enum choices without
+ * extending the contract.
+ */
+export const parameterFieldPath = (tree, parameterId) => {
+    let found = '';
+    forEachCondition(tree, (condition) => {
+        if (!found && condition.param === parameterId) {
+            found = condition.field;
+        }
+    });
+    return found;
+};
+
+/** A blank runtime value shaped for the parameter's type. */
+export const emptyParameterValue = (type) => {
+    if (type === 'date_range' || type === 'number_range' || type === 'range') {
+        return ['', ''];
+    }
+    if (type === 'enum_multi' || type === 'list') return [];
+    if (type === 'boolean') return false;
+    return '';
+};
+
+/** True when every required parameter has been answered. */
+export const parametersSatisfied = (parameters, values) =>
+    (parameters || []).every((param) => {
+        if (param.required === false) return true;
+        const value = values?.[param.id];
+        if (Array.isArray(value)) {
+            return (
+                value.length > 0 &&
+                value.every((entry) => entry !== '' && entry != null)
+            );
+        }
+        if (typeof value === 'boolean') return true;
+        return value !== '' && value != null;
+    });
+
+/* -------------------------------------------------------------------------- */
+/* Display                                                                    */
+/* -------------------------------------------------------------------------- */
+
+const currencyFormatter = new Intl.NumberFormat('en-AU', {
+    style: 'currency',
+    currency: 'AUD',
+});
+
+const numberFormatter = new Intl.NumberFormat('en-AU');
+
+/**
+ * Format a cell for display using the semantic type — no name sniffing, the
+ * model already told us what the value is.
+ */
+export const formatSemanticValue = (value, type, field) => {
+    if (value === null || value === undefined || value === '') return '';
+
+    switch (type) {
+        case 'money': {
+            const numeric = Number(value);
+            return Number.isFinite(numeric)
+                ? currencyFormatter.format(numeric)
+                : String(value);
+        }
+        case 'percent': {
+            const numeric = Number(value);
+            return Number.isFinite(numeric)
+                ? `${numberFormatter.format(numeric)}%`
+                : String(value);
+        }
+        case 'number': {
+            const numeric = Number(value);
+            return Number.isFinite(numeric)
+                ? numberFormatter.format(numeric)
+                : String(value);
+        }
+        case 'date': {
+            const date = new Date(value);
+            return Number.isNaN(date.getTime())
+                ? String(value)
+                : date.toLocaleDateString();
+        }
+        case 'datetime': {
+            const date = new Date(value);
+            return Number.isNaN(date.getTime())
+                ? String(value)
+                : date.toLocaleString();
+        }
+        case 'boolean': {
+            if (value === true || value === 1 || value === '1') return 'Yes';
+            if (value === false || value === 0 || value === '0') return 'No';
+            return String(value);
+        }
+        case 'enum': {
+            const values = field?.values || {};
+            return values[value] ?? values[String(value)] ?? String(value);
+        }
+        default:
+            return String(value);
+    }
+};
+
+/** `{key, value}` pairs for an enum field's select options. */
+export const enumOptions = (field) =>
+    Object.entries(field?.values || {}).map(([value, label]) => ({
+        value,
+        label: String(label),
+    }));