@cratis/scene.engine 4.2.0 → 4.3.0

package/editing/DescriptorCatalog.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentDescriptor, LayoutTypeDescriptor } from '@cratis/scene.model';
+import { layoutTypeDescriptors } from './layoutTypeDescriptors';
+
+/**
+ * Everything an editor knows how to describe: the component descriptors packages contribute, and the layout types
+ * the model itself defines.
+ *
+ * It is a derived view over what packages ship - not a registry anything registers into. Build one from the
+ * descriptors of the packages a profile lists, and rebuild it when the list changes.
+ */
+export interface DescriptorCatalog {
+    components: ComponentDescriptor[];
+    layoutTypes: LayoutTypeDescriptor[];
+}
+
+/**
+ * Builds a catalog from the component descriptors of the active packages, plus the built-in layout types.
+ *
+ * When two descriptors name the same component the later one wins, which is the same override-priority rule
+ * the profile's package order already means for components.
+ */
+export function createDescriptorCatalog(componentDescriptors: ComponentDescriptor[] = []): DescriptorCatalog {
+    const byComponent = new Map<string, ComponentDescriptor>();
+    for (const descriptor of componentDescriptors) byComponent.set(descriptor.component, descriptor);
+
+    return { components: [...byComponent.values()], layoutTypes: layoutTypeDescriptors };
+}
+
+/**
+ * Finds the descriptor of a component by the name an element carries.
+ *
+ * An exact match wins. Otherwise a bare name (`dataTable`) finds the one descriptor whose component ends in
+ * `:dataTable`; a bare name that several packages describe has no single answer, so it finds none.
+ */
+export function findComponentDescriptor(catalog: DescriptorCatalog, componentName: string): ComponentDescriptor | undefined {
+    const exact = catalog.components.find(descriptor => descriptor.component === componentName);
+    if (exact) return exact;
+
+    const matches = catalog.components.filter(descriptor => descriptor.component.endsWith(`:${componentName}`));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+
+/**
+ * Finds the descriptor of a layout type.
+ */
+export function findLayoutTypeDescriptor(catalog: DescriptorCatalog, type: string): LayoutTypeDescriptor | undefined {
+    return catalog.layoutTypes.find(descriptor => descriptor.type === type);
+}

package/editing/DocumentIndex.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneDiagnostic, SceneNodeKind } from '@cratis/scene.model';
+
+/**
+ * A route into a {@link SceneDocument}: property names and array indexes, outermost first.
+ */
+export type DocumentPath = (string | number)[];
+
+/**
+ * Where a node sits in an array it can be inserted into, removed from or moved within.
+ */
+export interface ListLocation {
+    /** The path of the array. */
+    path: DocumentPath;
+
+    /** The node's index in the array. */
+    index: number;
+}
+
+/**
+ * Everything the engine knows about one addressable node.
+ */
+export interface NodeRecord {
+    id: string;
+    kind: SceneNodeKind;
+
+    /** A `LayoutType` for a layout node, the component name for a component, otherwise the kind of element. */
+    typeId: string;
+
+    /** A name for a tree or an inspector title. */
+    label: string;
+
+    /** Where the node's value is in the document. */
+    path: DocumentPath;
+    value: unknown;
+
+    parentId?: string;
+
+    /** The name of the layout, template, dialog template or screen that physically contains the node. */
+    owner: string;
+    ownerKind: SceneNodeKind;
+
+    /** Set when the node is an item of an array: a child list or a slot's content. */
+    list?: ListLocation;
+
+    /** For an element held by a flow leaf: the id of that leaf. Removing or moving the element does so to the leaf. */
+    leafId?: string;
+
+    /** For an element positioned freeform: the ids of its placements, one per size-class variant. */
+    placementIds?: string[];
+
+    /**
+     * For nodes inside a freeform element, whose content repeats in every size-class variant: the path prefix of
+     * the copy this record describes, and the same prefix in each other variant. Edits are applied to every copy.
+     */
+    mirror?: { prefix: DocumentPath; others: DocumentPath[] };
+
+    /** For a slot: the name. */
+    slotName?: string;
+
+    /** For a slot: where its content array is (or would be, when empty). */
+    contentPath?: DocumentPath;
+}
+
+/**
+ * Every addressable node of a document, by id, with the problems found while indexing.
+ */
+export interface DocumentIndex {
+    nodes: Map<string, NodeRecord>;
+    diagnostics: SceneDiagnostic[];
+}

package/editing/EditOutcome.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneDiagnostic, SceneDocument } from '@cratis/scene.model';
+
+/**
+ * The outcome of {@link applyEdit}.
+ */
+export interface EditOutcome {
+    /**
+     * The document after the edit - a new object. When the edit was refused this is the document that was passed
+     * in, unchanged and the very same object.
+     */
+    model: SceneDocument;
+
+    /** What was found: errors when the edit was refused, warnings when it went ahead with a caveat. */
+    diagnostics: SceneDiagnostic[];
+
+    /** Whether the edit was applied. */
+    applied: boolean;
+}

package/editing/EditSession.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ProvenanceKind, SceneDocument } from '@cratis/scene.model';
+import { EditingContext } from './EditingContext';
+import { DocumentIndex, NodeRecord } from './DocumentIndex';
+import { ExposureGrant, ExposureGrants, computeExposureGrants } from './exposureGrants';
+import { indexDocument } from './indexDocument';
+import { provenanceOf } from './inspect';
+import { resolveEffectiveConfiguration } from './resolveEffectiveConfiguration';
+import { resolveTemplateChain } from './resolveTemplateChain';
+import { TemplateChain } from './TemplateChain';
+import { EffectiveConfiguration } from '@cratis/scene.model';
+
+/**
+ * Everything an edit needs to decide whether it is allowed, worked out once against the document as it was.
+ */
+export class EditSession {
+    readonly index: DocumentIndex;
+    readonly chain: TemplateChain;
+    readonly grants: ExposureGrants;
+    readonly configuration: EffectiveConfiguration;
+
+    constructor(readonly document: SceneDocument, readonly context: EditingContext) {
+        this.index = indexDocument(document);
+        this.chain = resolveTemplateChain(document, context.scope);
+        this.grants = computeExposureGrants(this.chain, context.catalog);
+        this.configuration = resolveEffectiveConfiguration(this.chain, document.instanceContributions, context.catalog);
+    }
+
+    /** The instance id the scope contributes as, or `undefined` when the scope was not found. */
+    get scopeInstance(): string | undefined {
+        return this.chain.levels.at(-1)?.instance;
+    }
+
+    /** What the scope's instance may configure on inherited components. */
+    get scopeGrants(): Map<string, ExposureGrant> {
+        return (this.scopeInstance === undefined ? undefined : this.grants.byInstance.get(this.scopeInstance)) ?? new Map();
+    }
+
+    /** Whether the scope itself owns the node. */
+    isLocal(record: NodeRecord): boolean {
+        return provenanceOf(record, this.chain, this.scopeGrants).kind === ProvenanceKind.Local;
+    }
+
+    /** Where an inherited node comes from, for a message. */
+    sourceOf(record: NodeRecord): string {
+        return record.owner;
+    }
+}

package/editing/EditingContext.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EditingScope, QueryCandidate } from '@cratis/scene.model';
+import { DescriptorCatalog } from './DescriptorCatalog';
+
+/**
+ * What inspection and editing need to know besides the document: what can be described, what is being edited,
+ * and which queries the host offers.
+ */
+export interface EditingContext {
+    /** The descriptors of the components and layout types in play. */
+    catalog: DescriptorCatalog;
+
+    /** The screen, template or layout being edited; it decides what is local. */
+    scope: EditingScope;
+
+    /**
+     * The queries a property may be bound to, as the host discovered them. When a `QueryReference` value is
+     * edited it is checked against these; without them it is checked for shape only.
+     */
+    queryCandidates?: QueryCandidate[];
+}

package/editing/TemplateChain.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExposedProperty, ExternalComponent, SceneDiagnostic, SceneNodeKind } from '@cratis/scene.model';
+
+/**
+ * One owner in a template chain: a layout, a template or the screen at the end.
+ */
+export interface TemplateChainLevel {
+    /** The name of the layout, template, dialog template or screen. */
+    owner: string;
+
+    kind: SceneNodeKind;
+
+    /** The instance this level contributes as: `layout:<name>`, `template:<name>`, `dialog:<name>` or `screen:<name>`. */
+    instance: string;
+
+    /** The components the owner contains, each once, by element id. */
+    elements: ExternalComponent[];
+
+    /** What the owner exposes - and, for a nested template, re-exposes - to what sits inside it. */
+    exposures: ExposedProperty[];
+}
+
+/**
+ * The nesting a configuration resolves over: the application layout first, then each template down to the one the
+ * screen fills, then the screen. A level can only configure what the levels above it exposed, and only reaches
+ * past its immediate parent when everything in between re-exposed it.
+ */
+export interface TemplateChain {
+    /** Outermost first. */
+    levels: TemplateChainLevel[];
+
+    /** Problems found assembling the chain, such as a template that could not be placed. */
+    diagnostics: SceneDiagnostic[];
+}

package/editing/applyEdit.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DiagnosticCode, SceneDiagnostic, SceneDocument, SceneEdit, SceneEditKind } from '@cratis/scene.model';
+import { errorDiagnostic, hasErrors } from './diagnostics';
+import { EditOutcome } from './EditOutcome';
+import { EditingContext } from './EditingContext';
+import { EditSession } from './EditSession';
+import { applyExposeProperty, applyUnexposeProperty } from './exposureEdits';
+import {
+    applyAddCollectionItem, applyEditCollectionItem, applyRemoveCollectionItem, applyReorderCollectionItem,
+    applyResetInstanceValue, applySetInstanceValue,
+} from './instanceEdits';
+import { applyChangeLayoutType } from './layoutTypeEdits';
+import { cloneData } from './pathAccess';
+import { applyResetProperty, applySetProperty } from './propertyEdits';
+import { applyInsertNode, applyMoveNode, applyRemoveNode } from './structureEdits';
+
+type Handler<TEdit extends SceneEdit> = (session: EditSession, edit: TEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]) => void;
+
+function run(session: EditSession, edit: SceneEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const handle = <TEdit extends SceneEdit>(handler: Handler<TEdit>) => handler(session, edit as TEdit, clone, diagnostics);
+
+    switch (edit.kind) {
+        case SceneEditKind.SetProperty: return handle(applySetProperty);
+        case SceneEditKind.ResetProperty: return handle(applyResetProperty);
+        case SceneEditKind.ChangeLayoutType: return handle(applyChangeLayoutType);
+        case SceneEditKind.InsertNode: return handle(applyInsertNode);
+        case SceneEditKind.MoveNode: return handle(applyMoveNode);
+        case SceneEditKind.RemoveNode: return handle(applyRemoveNode);
+        case SceneEditKind.SetInstanceValue: return handle(applySetInstanceValue);
+        case SceneEditKind.ResetInstanceValue: return handle(applyResetInstanceValue);
+        case SceneEditKind.AddCollectionItem: return handle(applyAddCollectionItem);
+        case SceneEditKind.RemoveCollectionItem: return handle(applyRemoveCollectionItem);
+        case SceneEditKind.ReorderCollectionItem: return handle(applyReorderCollectionItem);
+        case SceneEditKind.EditCollectionItem: return handle(applyEditCollectionItem);
+        case SceneEditKind.ExposeProperty: return handle(applyExposeProperty);
+        case SceneEditKind.UnexposeProperty: return handle(applyUnexposeProperty);
+        default:
+            diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, `'${(edit as { kind?: string }).kind}' is not an edit this engine knows.`));
+    }
+}
+
+/**
+ * Applies one edit to a document.
+ *
+ * Pure and immutable: the document passed in is never changed, and the result is a new document. Edits are plain
+ * data, so a host can persist them and build undo and redo by keeping the documents either side. On any error the
+ * prior document comes back - the same object - together with the diagnostics, so a refused edit leaves nothing
+ * half done.
+ *
+ * What an edit may touch follows the editing scope. Nodes the scope owns are edited directly; inherited nodes are
+ * read-only, and their exposed properties are configured with the instance edits, which are checked against what
+ * each owner exposed.
+ *
+ * @param model The document to edit.
+ * @param edit What to do.
+ * @param context The catalog and the editing scope.
+ */
+export function applyEdit(model: SceneDocument, edit: SceneEdit, context: EditingContext): EditOutcome {
+    const session = new EditSession(model, context);
+    const clone = cloneData(model);
+    const diagnostics: SceneDiagnostic[] = [];
+
+    run(session, edit, clone, diagnostics);
+
+    if (hasErrors(diagnostics)) return { model, diagnostics, applied: false };
+    return { model: clone, diagnostics, applied: true };
+}

package/editing/applyEffectiveConfiguration.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ContentControl, EffectiveConfiguration, ExternalComponent, ItemsControl, Panel, SceneElement } from '@cratis/scene.model';
+import { isContentControl, isExternalComponent, isItemsControl, isPanel } from '../elementKind';
+
+/**
+ * Returns the element tree a renderer should draw once effective configuration is applied: each configurable
+ * component carries its resolved properties.
+ *
+ * Pure, and structure-sharing - an element with nothing to change comes back as the same object, so a renderer
+ * that memoizes on identity does not redraw what did not change. There is no design-time flag here or anywhere
+ * downstream: a screen being edited and a screen being played go through this same function.
+ *
+ * @param element The element tree from the template or screen.
+ * @param configuration What {@link resolveEffectiveConfiguration} produced for the chain the tree sits in.
+ */
+export function applyEffectiveConfiguration(element: SceneElement, configuration: EffectiveConfiguration): SceneElement {
+    if (isExternalComponent(element)) {
+        const resolved = configuration.components.find(candidate => candidate.component === element.id);
+        let changed = resolved !== undefined;
+
+        const slots: typeof element.slots = {};
+        for (const [name, children] of Object.entries(element.slots)) {
+            const mapped = children.map(child => applyEffectiveConfiguration(child, configuration));
+            if (mapped.some((child, index) => child !== children[index])) changed = true;
+            slots[name] = mapped;
+        }
+
+        const updated: ExternalComponent = { ...element, properties: resolved?.properties ?? element.properties, slots };
+        return changed ? updated : element;
+    }
+
+    if (isContentControl(element)) {
+        const content = applyEffectiveConfiguration(element.content, configuration);
+        const updated: ContentControl = { ...element, content };
+        return content === element.content ? element : updated;
+    }
+
+    if (isItemsControl(element)) {
+        const itemTemplate = applyEffectiveConfiguration(element.itemTemplate, configuration);
+        const updated: ItemsControl = { ...element, itemTemplate };
+        return itemTemplate === element.itemTemplate ? element : updated;
+    }
+
+    if (isPanel(element)) {
+        const children = element.children.map(child => applyEffectiveConfiguration(child, configuration));
+        const updated: Panel = { ...element, children };
+        return children.some((child, index) => child !== element.children[index]) ? updated : element;
+    }
+
+    return element;
+}

package/editing/collectComponents.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent } from '@cratis/scene.model';
+
+function isExternalComponentValue(value: object): value is ExternalComponent {
+    const candidate = value as Partial<ExternalComponent>;
+    return typeof candidate.id === 'string' && typeof candidate.componentName === 'string'
+        && candidate.properties !== null && typeof candidate.properties === 'object';
+}
+
+/**
+ * Finds every external component anywhere inside a layout, template, dialog template or screen, each once by id.
+ *
+ * It scans the value's structure rather than following a fixed list of properties, so a component is found
+ * wherever the model keeps it - slot content, a flow leaf, a freeform placement, a panel's children, another
+ * component's slot. A freeform arrangement repeats an element across its size-class variants; the first copy
+ * is the one returned.
+ */
+export function collectComponents(owner: unknown): ExternalComponent[] {
+    const found = new Map<string, ExternalComponent>();
+
+    const visit = (value: unknown): void => {
+        if (value === null || typeof value !== 'object') return;
+        if (Array.isArray(value)) {
+            for (const item of value) visit(item);
+            return;
+        }
+
+        if (isExternalComponentValue(value) && !found.has(value.id)) found.set(value.id, value);
+        for (const child of Object.values(value)) visit(child);
+    };
+
+    visit(owner);
+    return [...found.values()];
+}

package/editing/describeNode.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DiagnosticCode, LayoutCapabilities, LayoutType, PropertyDescriptor, SceneDiagnostic, SceneNodeKind,
+} from '@cratis/scene.model';
+import { DescriptorCatalog, findComponentDescriptor, findLayoutTypeDescriptor } from './DescriptorCatalog';
+import { NodeRecord } from './DocumentIndex';
+import { warningDiagnostic } from './diagnostics';
+import { getValueAtPath } from './pathAccess';
+import { placementProperties, templateProperties } from './layoutTypeDescriptors';
+
+/**
+ * What describes a node: its editable properties, and for a layout node what the type can do.
+ */
+export interface NodeDescription {
+    properties: PropertyDescriptor[];
+    capabilities?: LayoutCapabilities;
+    diagnostics: SceneDiagnostic[];
+}
+
+const layoutTypes = new Set<string>(Object.values(LayoutType));
+
+/**
+ * Works out which descriptors apply to a node.
+ *
+ * A component takes its descriptor from the catalog by the name it carries; a layout node takes its layout type's;
+ * a placement and a template have their own fixed sets. A component nothing describes has no editable
+ * properties, and says so rather than failing.
+ */
+export function describeNode(record: NodeRecord, catalog: DescriptorCatalog): NodeDescription {
+    const diagnostics: SceneDiagnostic[] = [];
+
+    if (record.kind === SceneNodeKind.Placement) return { properties: placementProperties, diagnostics };
+    if (record.kind === SceneNodeKind.ScreenTemplate || record.kind === SceneNodeKind.DialogTemplate) return { properties: templateProperties, diagnostics };
+
+    if (layoutTypes.has(record.typeId)) {
+        const descriptor = findLayoutTypeDescriptor(catalog, record.typeId);
+        return { properties: descriptor?.properties ?? [], capabilities: descriptor?.capabilities, diagnostics };
+    }
+
+    if (record.kind === SceneNodeKind.Element && (record.value as { componentName?: unknown }).componentName !== undefined) {
+        const descriptor = findComponentDescriptor(catalog, record.typeId);
+        if (!descriptor) {
+            diagnostics.push(warningDiagnostic(DiagnosticCode.MissingComponentDescriptor, `Nothing describes the component '${record.typeId}', so none of its properties can be edited.`, { nodeId: record.id }));
+        }
+
+        return { properties: descriptor?.properties ?? [], diagnostics };
+    }
+
+    return { properties: [], diagnostics };
+}
+
+/**
+ * Reads a descriptor's value from a node: from the property bag of a component, from the node itself otherwise.
+ */
+export function readNodeValue(record: NodeRecord, path: string): unknown {
+    const value = record.value as Record<string, unknown>;
+    const isComponent = record.kind === SceneNodeKind.Element && value.componentName !== undefined;
+    return getValueAtPath(isComponent ? (value.properties as Record<string, unknown>) : value, path);
+}

package/editing/diagnostics.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DiagnosticCode, DiagnosticSeverity, SceneDiagnostic } from '@cratis/scene.model';
+
+/**
+ * The context a diagnostic can carry besides its code and message.
+ */
+export type DiagnosticContext = Partial<Omit<SceneDiagnostic, 'code' | 'severity' | 'message'>>;
+
+/**
+ * Builds an error diagnostic: the edit or resolution step that produced it did not happen.
+ */
+export function errorDiagnostic(code: DiagnosticCode, message: string, context: DiagnosticContext = {}): SceneDiagnostic {
+    return { code, severity: DiagnosticSeverity.Error, message, ...context };
+}
+
+/**
+ * Builds a warning diagnostic: the work went ahead, and the author should know something about it.
+ */
+export function warningDiagnostic(code: DiagnosticCode, message: string, context: DiagnosticContext = {}): SceneDiagnostic {
+    return { code, severity: DiagnosticSeverity.Warning, message, ...context };
+}
+
+/**
+ * Whether any diagnostic is an error.
+ */
+export function hasErrors(diagnostics: SceneDiagnostic[]): boolean {
+    return diagnostics.some(diagnostic => diagnostic.severity === DiagnosticSeverity.Error);
+}

package/editing/documentPaths.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DocumentPath } from './DocumentIndex';
+
+/**
+ * Reads the value at a document path.
+ */
+export function getAtPath(root: unknown, path: DocumentPath): unknown {
+    let current = root;
+    for (const key of path) {
+        if (current === null || typeof current !== 'object') return undefined;
+        current = (current as Record<string | number, unknown>)[key];
+    }
+
+    return current;
+}
+
+/**
+ * Reads the array at a path, creating it - and any objects on the way - when it is not there yet. Mutates `root`,
+ * which callers hold a copy of.
+ */
+export function ensureArrayAt(root: unknown, path: DocumentPath): unknown[] {
+    let current = root as Record<string | number, unknown>;
+    path.forEach((key, position) => {
+        if (current[key] === undefined) current[key] = position === path.length - 1 ? [] : {};
+        current = current[key] as Record<string | number, unknown>;
+    });
+
+    return current as unknown as unknown[];
+}
+
+/**
+ * The paths a change to `path` must be made at: the path itself and, for a node inside a freeform element, the same
+ * place in every other size-class variant's copy.
+ */
+export function mirroredPaths(mirror: { prefix: DocumentPath; others: DocumentPath[] } | undefined, path: DocumentPath): DocumentPath[] {
+    if (!mirror || mirror.prefix.some((key, position) => path[position] !== key)) return [path];
+    return [path, ...mirror.others.map(other => [...other, ...path.slice(mirror.prefix.length)])];
+}