@cratis/scene.engine 4.2.1 → 4.3.0

package/editing/exposureEdits.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    CollectionOperation, DiagnosticCode, ExposedProperty, ExposePropertyEdit, PropertyValueType, SceneDiagnostic,
+    SceneDocument, UnexposePropertyEdit,
+} from '@cratis/scene.model';
+import { findComponentDescriptor } from './DescriptorCatalog';
+import { errorDiagnostic } from './diagnostics';
+import { EditSession } from './EditSession';
+import { grantKey } from './exposureGrants';
+import { cloneData } from './pathAccess';
+
+function ownsDeclaration(session: EditSession, owner: string, diagnostics: SceneDiagnostic[]): boolean {
+    const level = session.chain.levels.at(-1);
+    if (!level || level.owner !== owner) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NodeNotEditable, `Exposure is declared by the layout or template that owns the component. '${owner}' is not what is being edited.`));
+        return false;
+    }
+
+    return true;
+}
+
+function validateExposure(session: EditSession, property: ExposedProperty, diagnostics: SceneDiagnostic[]): boolean {
+    const context = { component: property.component, path: property.path };
+    const level = session.chain.levels.at(-1)!;
+    const reExposed = property.reExposes !== undefined;
+
+    if (!reExposed && !level.elements.some(candidate => candidate.id === property.component)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ExposureTargetMissing, `'${level.owner}' has no component '${property.component}'.`, context));
+        return false;
+    }
+
+    const grant = reExposed ? session.scopeGrants.get(grantKey(property.component, property.path)) : undefined;
+    if (reExposed && (!grant || grant.owner !== property.reExposes)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ReExposureBroken, `'${property.reExposes}' does not expose '${property.path}' on '${property.component}' to '${level.owner}', so it cannot be passed on.`, context));
+        return false;
+    }
+
+    const element = level.elements.find(candidate => candidate.id === property.component);
+    const descriptor = grant
+        ? grant.descriptor
+        : findComponentDescriptor(session.context.catalog, element!.componentName)?.properties.find(candidate => candidate.path === property.path);
+    if (!descriptor) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ExposureTargetMissing, `There is no editable property '${property.path}' on '${property.component}'.`, context));
+        return false;
+    }
+
+    const operations = property.operations ?? [];
+    if (descriptor.valueType !== PropertyValueType.Collection) {
+        if (operations.length > 0 || property.editableFields !== undefined) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, `'${descriptor.label}' is not a collection, so operations and editable fields do not apply.`, context));
+            return false;
+        }
+
+        return true;
+    }
+
+    const known = Object.values(CollectionOperation) as string[];
+    const unknown = operations.find(operation => !known.includes(operation));
+    if (unknown !== undefined) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, `'${unknown}' is not a collection operation.`, context));
+        return false;
+    }
+
+    const fields = descriptor.item?.properties.map(candidate => candidate.path) ?? [];
+    const unknownField = property.editableFields?.find(field => !fields.includes(field));
+    if (unknownField !== undefined) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownCollectionField, `Items of '${descriptor.label}' have no field '${unknownField}'.`, context));
+        return false;
+    }
+
+    if (grant && (operations.some(operation => !grant.operations.includes(operation))
+        || (grant.editableFields !== undefined && (property.editableFields ?? fields).some(field => !grant.editableFields!.includes(field))))) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ExposureWidensOwner, `'${property.reExposes}' exposed less of '${descriptor.label}' than this re-exposes.`, context));
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Applies an exposure declaration to a copy of the document.
+ *
+ * Exposure only narrows: the property has to be one the component's descriptor supports, a collection's
+ * operations and fields have to exist, and a re-exposure cannot grant more than the owner it passes on.
+ */
+export function applyExposeProperty(session: EditSession, edit: ExposePropertyEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    if (!ownsDeclaration(session, edit.owner, diagnostics) || !validateExposure(session, edit.property, diagnostics)) return;
+
+    let declaration = clone.exposures.find(candidate => candidate.owner === edit.owner);
+    if (!declaration) {
+        declaration = { owner: edit.owner, properties: [] };
+        clone.exposures.push(declaration);
+    }
+
+    const same = (candidate: ExposedProperty) => candidate.component === edit.property.component
+        && candidate.path === edit.property.path && candidate.reExposes === edit.property.reExposes;
+    const position = declaration.properties.findIndex(same);
+    if (position >= 0) declaration.properties[position] = cloneData(edit.property);
+    else declaration.properties.push(cloneData(edit.property));
+}
+
+/**
+ * Applies an exposure withdrawal to a copy of the document. Values already saved against it are not touched.
+ */
+export function applyUnexposeProperty(session: EditSession, edit: UnexposePropertyEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    if (!ownsDeclaration(session, edit.owner, diagnostics)) return;
+
+    const declaration = clone.exposures.find(candidate => candidate.owner === edit.owner);
+    const remaining = declaration?.properties.filter(candidate => !(candidate.component === edit.component && candidate.path === edit.path));
+    if (!declaration || remaining!.length === declaration.properties.length) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ExposureTargetMissing, `'${edit.owner}' does not expose '${edit.path}' on '${edit.component}'.`, { component: edit.component, path: edit.path }));
+        return;
+    }
+
+    if (remaining!.length === 0) clone.exposures.splice(clone.exposures.indexOf(declaration), 1);
+    else declaration.properties = remaining!;
+}

package/editing/exposureGrants.ts

@@ -0,0 +1,159 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    CollectionOperation, DiagnosticCode, ExposedProperty, PropertyDescriptor, PropertyValueType, SceneDiagnostic,
+} from '@cratis/scene.model';
+import { DescriptorCatalog, findComponentDescriptor } from './DescriptorCatalog';
+import { errorDiagnostic } from './diagnostics';
+import { TemplateChain } from './TemplateChain';
+
+/**
+ * What one instance may configure on one property: the owner's exposure, narrowed by every re-exposure between the
+ * owner and that instance.
+ */
+export interface ExposureGrant {
+    /** The id of the element that owns the property. */
+    component: string;
+
+    path: string;
+    descriptor: PropertyDescriptor;
+
+    /** The name of the layout or template that owns the element. */
+    owner: string;
+
+    /** The index of the owner in the chain. */
+    ownerLevel: number;
+
+    /** For a collection: what may be done to it. Empty for any other property. */
+    operations: CollectionOperation[];
+
+    /** For a collection: the item fields that may be changed; absent means all of them. */
+    editableFields?: string[];
+
+    label?: string;
+}
+
+/**
+ * The outcome of working out who may configure what.
+ */
+export interface ExposureGrants {
+    /** Every valid exposure, one per owner-declared property, at the level of its owner. */
+    exposed: ExposureGrant[];
+
+    /** For each contributing instance id, what it may configure, keyed by {@link grantKey}. */
+    byInstance: Map<string, Map<string, ExposureGrant>>;
+
+    diagnostics: SceneDiagnostic[];
+}
+
+/**
+ * The key a grant is stored under.
+ */
+export function grantKey(component: string, path: string): string {
+    return `${component}\u0000${path}`;
+}
+
+function narrow(grant: ExposureGrant, reExposure: ExposedProperty): { grant: ExposureGrant; widened: boolean } {
+    const requested = reExposure.operations ?? [];
+    const operations = requested.filter(operation => grant.operations.includes(operation));
+    const fields = grant.editableFields === undefined
+        ? reExposure.editableFields
+        : (reExposure.editableFields === undefined ? grant.editableFields : reExposure.editableFields.filter(field => grant.editableFields!.includes(field)));
+
+    const widened = operations.length < requested.length
+        || (grant.editableFields !== undefined && reExposure.editableFields !== undefined && reExposure.editableFields.some(field => !grant.editableFields!.includes(field)));
+
+    return { grant: { ...grant, operations, editableFields: fields, label: reExposure.label ?? grant.label }, widened };
+}
+
+/**
+ * Works out, for every instance in a chain, which properties it may configure.
+ *
+ * An owner's exposure reaches the instance directly inside it. It reaches further only through explicit
+ * re-exposure by every level in between, and each re-exposure can only narrow what it passes on - a nested
+ * template that lists more operations or fields than its owner granted gets the owner's, not its own.
+ *
+ * @param chain The chain to analyze.
+ * @param catalog The descriptors that say what each component supports.
+ */
+export function computeExposureGrants(chain: TemplateChain, catalog: DescriptorCatalog): ExposureGrants {
+    const result: ExposureGrants = { exposed: [], byInstance: new Map(), diagnostics: [] };
+    for (const chainLevel of chain.levels) result.byInstance.set(chainLevel.instance, new Map());
+
+    const consumed = new Set<ExposedProperty>();
+
+    chain.levels.forEach((owner, ownerLevel) => {
+        for (const exposure of owner.exposures.filter(candidate => candidate.reExposes === undefined)) {
+            const element = owner.elements.find(candidate => candidate.id === exposure.component);
+            if (!element) {
+                result.diagnostics.push(errorDiagnostic(
+                    DiagnosticCode.ExposureTargetMissing,
+                    `'${owner.owner}' exposes '${exposure.path}' on '${exposure.component}', but it has no such component.`,
+                    { component: exposure.component, path: exposure.path }));
+                continue;
+            }
+
+            const descriptor = findComponentDescriptor(catalog, element.componentName);
+            if (!descriptor) {
+                result.diagnostics.push(errorDiagnostic(
+                    DiagnosticCode.MissingComponentDescriptor,
+                    `'${owner.owner}' exposes '${exposure.path}' on '${exposure.component}', but nothing describes the component '${element.componentName}'.`,
+                    { component: exposure.component, path: exposure.path }));
+                continue;
+            }
+
+            const property = descriptor.properties.find(candidate => candidate.path === exposure.path);
+            if (!property) {
+                result.diagnostics.push(errorDiagnostic(
+                    DiagnosticCode.ExposureTargetMissing,
+                    `'${owner.owner}' exposes '${exposure.path}' on '${exposure.component}', but '${element.componentName}' no longer has that property.`,
+                    { component: exposure.component, path: exposure.path }));
+                continue;
+            }
+
+            const isCollection = property.valueType === PropertyValueType.Collection;
+            let current: ExposureGrant = {
+                component: exposure.component,
+                path: exposure.path,
+                descriptor: property,
+                owner: owner.owner,
+                ownerLevel,
+                operations: isCollection ? [...new Set(exposure.operations ?? [])] : [],
+                editableFields: isCollection ? exposure.editableFields : undefined,
+                label: exposure.label,
+            };
+            result.exposed.push(current);
+
+            for (let contributor = ownerLevel + 1; contributor < chain.levels.length; contributor++) {
+                result.byInstance.get(chain.levels[contributor].instance)!.set(grantKey(exposure.component, exposure.path), current);
+
+                const reExposure = chain.levels[contributor].exposures.find(candidate =>
+                    candidate.reExposes === owner.owner && candidate.component === exposure.component && candidate.path === exposure.path);
+                if (!reExposure) break;
+
+                consumed.add(reExposure);
+                const narrowed = narrow(current, reExposure);
+                if (narrowed.widened) {
+                    result.diagnostics.push(errorDiagnostic(
+                        DiagnosticCode.ExposureWidensOwner,
+                        `'${chain.levels[contributor].owner}' re-exposes more of '${exposure.path}' than '${owner.owner}' exposed; only what the owner granted is passed on.`,
+                        { component: exposure.component, path: exposure.path }));
+                }
+
+                current = narrowed.grant;
+            }
+        }
+    });
+
+    for (const chainLevel of chain.levels) {
+        for (const reExposure of chainLevel.exposures.filter(candidate => candidate.reExposes !== undefined && !consumed.has(candidate))) {
+            result.diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ReExposureBroken,
+                `'${chainLevel.owner}' re-exposes '${reExposure.path}' on '${reExposure.component}' from '${reExposure.reExposes}', which does not expose it to this chain.`,
+                { component: reExposure.component, path: reExposure.path }));
+        }
+    }
+
+    return result;
+}

package/editing/given/a_layout_document.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    EditingScopeKind, FlowContainerKind, HeightSizeClass, Orientation, SceneDocument, SceneElement, WidthSizeClass,
+} from '@cratis/scene.model';
+import { EditingContext } from '../../index';
+import { catalog, component, shell } from './a_scene_document';
+
+/** A panel-shaped element: everything a `FrameworkElement` has, plus its own properties and children. */
+export function panel(id: string, own: Record<string, unknown>, children: SceneElement[] = []): SceneElement {
+    const { componentName: _componentName, slots: _slots, ...frameworkElement } = component(id, 'ignored');
+    return { ...frameworkElement, children, ...own } as unknown as SceneElement;
+}
+
+export const stackPanel = (id: string, children: SceneElement[], spacing = 0) => panel(id, { orientation: Orientation.Vertical, spacing }, children);
+export const wrapPanel = (id: string, children: SceneElement[], itemWidth?: number) => panel(id, { orientation: Orientation.Horizontal, itemWidth }, children);
+
+export const table = (id: string) => component(id, 'test:table');
+
+const compact = { width: WidthSizeClass.Compact, height: HeightSizeClass.Compact };
+const regular = { width: WidthSizeClass.Regular, height: HeightSizeClass.Regular };
+
+export const mainSlot = 'screenTemplate:Page#slot:main';
+export const sideSlot = 'screenTemplate:Page#slot:side';
+export const canvasSlot = 'screenTemplate:Page#slot:canvas';
+
+/**
+ * A template with a flow column in `main` (a row of `a`, `b` above a growing `c`), a freeform `canvas` with `f`
+ * placed in two size-class variants, and a `side` slot holding a stack panel of `g` and `h` and a lone `i`. A
+ * screen `Home` fills it.
+ */
+export function createLayoutDocument(): SceneDocument {
+    return {
+        layouts: [{ ...shell, slots: [{ name: 'content' }] }],
+        screenTemplates: [{
+            name: 'Page',
+            fitsSlot: 'content',
+            slots: [
+                {
+                    name: 'main',
+                    arrangement: {
+                        root: {
+                            kind: FlowContainerKind.Column, gap: 8,
+                            children: [
+                                { kind: FlowContainerKind.Row, gap: 4, children: [{ content: table('a') }, { content: table('b') }] },
+                                { content: table('c'), grow: 1 },
+                            ],
+                        },
+                    } as never,
+                },
+                {
+                    name: 'canvas',
+                    arrangement: {
+                        variants: [
+                            { sizeClass: compact, placements: [{ element: stackPanel('freeStack', [table('f')]), x: 0, y: 0, width: 100, height: 50 }] },
+                            { sizeClass: regular, placements: [{ element: stackPanel('freeStack', [table('f')]), x: 10, y: 10, width: 200, height: 80 }] },
+                        ],
+                    } as never,
+                },
+                { name: 'side' },
+            ],
+            content: { side: [stackPanel('stack', [table('g'), table('h')], 6), table('i')] },
+        }],
+        dialogTemplates: [],
+        screens: [{ name: 'Home', layout: 'Shell', screenTemplate: 'Page', forms: [], contributions: [], slotContent: { side: [table('j')] } }],
+        exposures: [],
+        instanceContributions: [],
+    };
+}
+
+export function pageContext(extra: Partial<EditingContext> = {}): EditingContext {
+    return { catalog, scope: { kind: EditingScopeKind.ScreenTemplate, name: 'Page', layout: 'Shell' }, ...extra };
+}
+
+export function homeContext(extra: Partial<EditingContext> = {}): EditingContext {
+    return { catalog, scope: { kind: EditingScopeKind.Screen, name: 'Home' }, ...extra };
+}
+
+/** Freezes a document deeply, so any edit that mutates it throws instead of passing quietly. */
+export function deepFreeze<T>(value: T): T {
+    if (value !== null && typeof value === 'object') {
+        Object.freeze(value);
+        for (const child of Object.values(value)) deepFreeze(child);
+    }
+
+    return value;
+}

package/editing/given/a_scene_document.ts

@@ -0,0 +1,135 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    CollectionOperation, ComponentDescriptor, EditingScope, EditingScopeKind, ExternalComponent, FlowContainerKind,
+    HorizontalAlignment, Layout, PropertyValueType, QueryResultShape, SceneDocument, ScreenTemplate, Screen,
+    VerticalAlignment, Visibility,
+} from '@cratis/scene.model';
+import { createDescriptorCatalog, EditingContext } from '../../index';
+
+export function component(id: string, componentName: string, properties: Record<string, unknown> = {}, slots: ExternalComponent['slots'] = {}): ExternalComponent {
+    return {
+        id, name: id, componentName, properties, slots,
+        visibility: Visibility.Visible, isEnabled: true, opacity: 1, size: {}, zIndex: 0, minimumSize: {}, maximumSize: {},
+        margin: { left: 0, top: 0, right: 0, bottom: 0 },
+        horizontalAlignment: HorizontalAlignment.Stretch, verticalAlignment: VerticalAlignment.Stretch,
+    };
+}
+
+/** A navigation bar with a fixed Home item and a collection consumers can extend, like the real one. */
+export const navigationBarDescriptor: ComponentDescriptor = {
+    component: 'test:navigationBar',
+    displayName: 'Navigation bar',
+    properties: [
+        {
+            path: 'items', label: 'Items', group: 'Content', valueType: PropertyValueType.Collection,
+            item: {
+                label: 'Item',
+                properties: [
+                    { path: 'label', label: 'Label', group: 'Content', valueType: PropertyValueType.String, constraints: { required: true } },
+                    { path: 'icon', label: 'Icon', group: 'Content', valueType: PropertyValueType.Icon, editorKind: 'iconPicker' },
+                    { path: 'destination', label: 'Destination', group: 'Content', valueType: PropertyValueType.Destination },
+                ],
+            },
+            constraints: { maximumItems: 6 },
+        },
+        { path: 'title', label: 'Title', group: 'Content', valueType: PropertyValueType.String, default: 'Menu' },
+        { path: 'density', label: 'Density', group: 'Look', valueType: PropertyValueType.Enum, choices: [{ value: 'compact', label: 'Compact' }, { value: 'roomy', label: 'Roomy' }] },
+    ],
+};
+
+export const tableDescriptor: ComponentDescriptor = {
+    component: 'test:table',
+    properties: [
+        { path: 'query', label: 'Query', group: 'Data', valueType: PropertyValueType.QueryReference, editorKind: 'queryBinding', constraints: { resultShapes: [QueryResultShape.Collection] } },
+        { path: 'pageSize', label: 'Page size', group: 'Data', valueType: PropertyValueType.Number, constraints: { minimum: 1, maximum: 100, integer: true } },
+        { path: 'locked', label: 'Locked', group: 'Data', valueType: PropertyValueType.String, readOnly: true },
+    ],
+};
+
+export const homeItem = { id: 'home', label: 'Home', destination: { screen: 'Home' } };
+
+export const shell: Layout = { name: 'Shell', slots: [{ name: 'header' }, { name: 'content' }] };
+
+/**
+ * Two nested templates and two screens: `Module` (with a navigation bar) fits the shell, `Feature` fits `Module`'s
+ * body, and both `Invoices` and `Customers` fill `Feature`.
+ */
+export function createSceneDocument(): SceneDocument {
+    const module: ScreenTemplate = {
+        name: 'Module',
+        fitsSlot: 'content',
+        slots: [{ name: 'chrome' }, { name: 'body' }],
+        content: { chrome: [component('navbar', 'test:navigationBar', { items: [homeItem] })], body: [] },
+    };
+    const feature: ScreenTemplate = {
+        name: 'Feature',
+        fitsSlot: 'Module.body',
+        slots: [{ name: 'main' }],
+        content: {
+            main: [],
+        },
+        arrangement: {
+            root: {
+                kind: FlowContainerKind.Column, gap: 8, grow: 1,
+                children: [
+                    { kind: FlowContainerKind.Row, gap: 4, children: [{ slotName: 'main' }] },
+                ],
+            },
+        } as ScreenTemplate['arrangement'],
+    };
+    const invoices: Screen = {
+        name: 'Invoices', layout: 'Shell', screenTemplate: 'Feature', forms: [], contributions: [],
+        slotContent: { main: [component('invoiceTable', 'test:table', { pageSize: 25 })] },
+    };
+    const customers: Screen = {
+        name: 'Customers', layout: 'Shell', screenTemplate: 'Feature', forms: [], contributions: [],
+        slotContent: { main: [component('customerTable', 'test:table')] },
+    };
+
+    return {
+        layouts: [shell],
+        screenTemplates: [module, feature],
+        dialogTemplates: [],
+        screens: [invoices, customers],
+        exposures: [],
+        instanceContributions: [],
+    };
+}
+
+/** The same document with `Module` exposing the navigation bar's items and title to what sits inside it. */
+export function createExposedDocument(): SceneDocument {
+    const document = createSceneDocument();
+    document.exposures.push({
+        owner: 'Module',
+        properties: [
+            { component: 'navbar', path: 'items', operations: [CollectionOperation.Add, CollectionOperation.Remove, CollectionOperation.Reorder, CollectionOperation.EditFields], editableFields: ['label', 'icon', 'destination'] },
+            { component: 'navbar', path: 'title' },
+        ],
+    });
+    return document;
+}
+
+/** The same document with `Feature` re-exposing what `Module` exposed, so screens reach it. */
+export function createReExposedDocument(): SceneDocument {
+    const document = createExposedDocument();
+    document.exposures.push({
+        owner: 'Feature',
+        properties: [
+            { component: 'navbar', path: 'items', reExposes: 'Module', operations: [CollectionOperation.Add, CollectionOperation.EditFields] },
+            { component: 'navbar', path: 'title', reExposes: 'Module' },
+        ],
+    });
+    return document;
+}
+
+export const catalog = createDescriptorCatalog([navigationBarDescriptor, tableDescriptor]);
+
+export function scopeOf(kind: EditingScopeKind, name: string, layout?: string): EditingScope {
+    return { kind, name, layout };
+}
+
+export function contextFor(kind: EditingScopeKind, name: string, extra: Partial<EditingContext> = {}): EditingContext {
+    return { catalog, scope: scopeOf(kind, name, 'Shell'), ...extra };
+}

package/editing/index.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.
+
+export * from './diagnostics';
+export * from './nodeIds';
+export * from './layoutTypeDescriptors';
+export * from './DescriptorCatalog';
+export * from './validateValue';
+export * from './validateBinding';
+export * from './TemplateChain';
+export * from './collectComponents';
+export * from './resolveTemplateChain';
+export * from './exposureGrants';
+export * from './resolveEffectiveConfiguration';
+export * from './applyEffectiveConfiguration';
+export * from './DocumentIndex';
+export * from './indexDocument';
+export * from './EditingContext';
+export * from './inspect';
+export * from './EditOutcome';
+export * from './applyEdit';