@cratis/scene.model 4.2.0 → 4.3.0

package/editing/AddCollectionItemEdit.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 { ContributedItem } from '../exposure';
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Adds an item to an exposed collection from a template instance.
+ */
+export interface AddCollectionItemEdit {
+    kind: SceneEditKind.AddCollectionItem;
+    instance?: string;
+    component: string;
+    path: string;
+    item: ContributedItem;
+
+    /** Where among the instance's own items. Absent appends. */
+    index?: number;
+}
+
+export const AddCollectionItemEditPropertyNames: (keyof AddCollectionItemEdit)[] = ['kind', 'instance', 'component', 'path', 'item', 'index'];

package/editing/ChangeLayoutTypeEdit.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { LayoutType } from '../descriptors';
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Changes a layout node into another layout type, keeping its children.
+ */
+export interface ChangeLayoutTypeEdit {
+    kind: SceneEditKind.ChangeLayoutType;
+    nodeId: string;
+    to: `${LayoutType}`;
+
+    /**
+     * Whether the author has seen what the conversion drops and accepts it. Without it a lossy conversion is
+     * refused with a diagnostic naming what would be lost.
+     */
+    acceptLoss?: boolean;
+}
+
+export const ChangeLayoutTypeEditPropertyNames: (keyof ChangeLayoutTypeEdit)[] = ['kind', 'nodeId', 'to', 'acceptLoss'];

package/editing/DiagnosticCode.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The reasons inspection, editing, binding validation and configuration resolution report a problem. A host
+ * switches on the code; the message is for a person.
+ */
+export enum DiagnosticCode {
+    // Addressing
+    UnknownNode = 'unknownNode',
+    DuplicateElementId = 'duplicateElementId',
+    UnknownScope = 'unknownScope',
+    InvalidEdit = 'invalidEdit',
+
+    // Properties
+    UnknownProperty = 'unknownProperty',
+    InvalidValue = 'invalidValue',
+    ReadOnlyProperty = 'readOnlyProperty',
+    NodeNotEditable = 'nodeNotEditable',
+    MissingComponentDescriptor = 'missingComponentDescriptor',
+
+    // Layout
+    NotALayoutNode = 'notALayoutNode',
+    LayoutTypeNotConvertible = 'layoutTypeNotConvertible',
+    LossyConversionNotAccepted = 'lossyConversionNotAccepted',
+    LossyConversion = 'lossyConversion',
+
+    // Structure
+    TargetDoesNotAcceptChildren = 'targetDoesNotAcceptChildren',
+    UnknownSlot = 'unknownSlot',
+    ContainmentCycle = 'containmentCycle',
+    IndexOutOfRange = 'indexOutOfRange',
+    ElementIdInUse = 'elementIdInUse',
+    MaximumChildrenExceeded = 'maximumChildrenExceeded',
+    NodeNotRemovable = 'nodeNotRemovable',
+
+    // Query binding
+    MissingQuery = 'missingQuery',
+    IncompatibleResultShape = 'incompatibleResultShape',
+    MissingRequiredParameter = 'missingRequiredParameter',
+    UnknownParameter = 'unknownParameter',
+    ArgumentTypeMismatch = 'argumentTypeMismatch',
+    UnresolvedArgumentSource = 'unresolvedArgumentSource',
+    UnknownResultField = 'unknownResultField',
+
+    // Exposure and instance configuration
+    ExposureTargetMissing = 'exposureTargetMissing',
+    ExposureWidensOwner = 'exposureWidensOwner',
+    ReExposureBroken = 'reExposureBroken',
+    ContributionNotExposed = 'contributionNotExposed',
+    ContributionTargetMissing = 'contributionTargetMissing',
+    ContributionTypeMismatch = 'contributionTypeMismatch',
+    ContributionOperationNotPermitted = 'contributionOperationNotPermitted',
+    UnknownCollectionField = 'unknownCollectionField',
+    CollectionItemNotFound = 'collectionItemNotFound',
+    DuplicateCollectionItem = 'duplicateCollectionItem',
+    UnknownInstance = 'unknownInstance',
+}

package/editing/DiagnosticSeverity.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How serious a diagnostic is. An edit with an `Error` is refused; a `Warning` is reported and the edit goes
+ * ahead.
+ */
+export enum DiagnosticSeverity {
+    Error = 'error',
+    Warning = 'warning',
+}

package/editing/EditCollectionItemEdit.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 { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Changes one field of an item an instance contributed.
+ */
+export interface EditCollectionItemEdit {
+    kind: SceneEditKind.EditCollectionItem;
+    instance?: string;
+    component: string;
+    path: string;
+    itemId: string;
+
+    /** The item field, as the collection's item descriptor states it. */
+    field: string;
+    value: unknown;
+}
+
+export const EditCollectionItemEditPropertyNames: (keyof EditCollectionItemEdit)[] = [
+    'kind', 'instance', 'component', 'path', 'itemId', 'field', 'value',
+];

package/editing/EditTarget.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Where an edit of a property goes.
+ */
+export enum EditTarget {
+    /** The node itself. */
+    Node = 'node',
+
+    /** An instance contribution, because the node is inherited and the property is exposed. */
+    Instance = 'instance',
+}

package/editing/EditingScope.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EditingScopeKind } from './EditingScopeKind';
+
+/**
+ * The thing being edited. What it owns is local and editable; what an outer layout or template owns is inherited,
+ * and can only be configured through what that owner exposed.
+ */
+export interface EditingScope {
+    kind: `${EditingScopeKind}`;
+
+    /** The name of the screen, template or layout. */
+    name: string;
+
+    /**
+     * For a template scope: the name of the layout the template ultimately sits in. A template does not say
+     * which layout it belongs to, so a document with several layouts needs to be told. A screen scope reads it
+     * from the screen itself.
+     */
+    layout?: string;
+}
+
+export const EditingScopePropertyNames: (keyof EditingScope)[] = ['kind', 'name', 'layout'];

package/editing/EditingScopeKind.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What is being edited. It decides what counts as local and what is inherited.
+ */
+export enum EditingScopeKind {
+    Screen = 'screen',
+    ScreenTemplate = 'screenTemplate',
+    DialogTemplate = 'dialogTemplate',
+    Layout = 'layout',
+}

package/editing/EffectiveCollectionItem.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One item of a collection after the owner's items and every instance's contributed items are put together.
+ */
+export interface EffectiveCollectionItem {
+    id: string;
+    values: Record<string, unknown>;
+
+    /** `owner` for an item the template author wrote; otherwise the id of the instance that contributed it. */
+    origin: string;
+
+    /** An owner's item. Consumers cannot change or remove it. */
+    fixed: boolean;
+}
+
+export const EffectiveCollectionItemPropertyNames: (keyof EffectiveCollectionItem)[] = ['id', 'values', 'origin', 'fixed'];

package/editing/EffectiveComponentConfiguration.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EffectivePropertyValue } from './EffectivePropertyValue';
+
+/**
+ * The resolved configuration of one component: the full property bag a renderer should use, and a record per
+ * exposed property of where it came from.
+ */
+export interface EffectiveComponentConfiguration {
+    /** The id of the element. */
+    component: string;
+
+    /** The name of the layout or template that owns the element. */
+    owner: string;
+
+    /** The element's `properties` with every valid contribution applied. */
+    properties: Record<string, unknown>;
+
+    /** One entry per exposed property. */
+    values: EffectivePropertyValue[];
+}
+
+export const EffectiveComponentConfigurationPropertyNames: (keyof EffectiveComponentConfiguration)[] = [
+    'component', 'owner', 'properties', 'values',
+];

package/editing/EffectiveConfiguration.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 { EffectiveComponentConfiguration } from './EffectiveComponentConfiguration';
+import { SceneDiagnostic } from './SceneDiagnostic';
+
+/**
+ * The outcome of resolving a template chain and its instances' contributions. The runtime renders from this, and
+ * the editor shows it - the same data, so what the editor shows is what Play renders.
+ */
+export interface EffectiveConfiguration {
+    /** Every configurable component in the chain. Components nothing is exposed on are absent. */
+    components: EffectiveComponentConfiguration[];
+
+    /**
+     * What went wrong: an exposure that no longer matches its component, a contribution to something no longer
+     * exposed, a saved value whose type changed. The affected contributions are ignored in `components` and left
+     * in the persisted data, so restoring the exposure brings the values back.
+     */
+    diagnostics: SceneDiagnostic[];
+}
+
+export const EffectiveConfigurationPropertyNames: (keyof EffectiveConfiguration)[] = ['components', 'diagnostics'];

package/editing/EffectivePropertyValue.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EffectiveCollectionItem } from './EffectiveCollectionItem';
+import { ValueSource } from './ValueSource';
+
+/**
+ * One property's value after configuration is resolved, with enough to show where it came from and what
+ * resetting it would give back.
+ */
+export interface EffectivePropertyValue {
+    path: string;
+
+    /** What the property is worth now. */
+    value: unknown;
+
+    source: `${ValueSource}`;
+
+    /** What the property would be worth with every instance contribution removed. */
+    inheritedValue: unknown;
+
+    /** The instance that set `value`, when `source` is `instance`. */
+    contributedBy?: string;
+
+    /** For a collection: the items, owner's first. */
+    items?: EffectiveCollectionItem[];
+}
+
+export const EffectivePropertyValuePropertyNames: (keyof EffectivePropertyValue)[] = [
+    'path', 'value', 'source', 'inheritedValue', 'contributedBy', 'items',
+];

package/editing/ExposePropertyEdit.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExposedProperty } from '../exposure';
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Exposes a property on a layout or template, or changes how it is exposed.
+ */
+export interface ExposePropertyEdit {
+    kind: SceneEditKind.ExposeProperty;
+
+    /** The layout or template making the declaration. */
+    owner: string;
+    property: ExposedProperty;
+}
+
+export const ExposePropertyEditPropertyNames: (keyof ExposePropertyEdit)[] = ['kind', 'owner', 'property'];

package/editing/InsertNodeEdit.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 { FlowNode } from '../layouts';
+import { SceneElement } from '../elements';
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Inserts a new element - or, into a flow container, a new flow node - under a target.
+ *
+ * The target is a slot node, an element (an `ExternalComponent` with `slot`, or a panel) or a flow container.
+ * Exactly one of `element` and `flowNode` is given.
+ */
+export interface InsertNodeEdit {
+    kind: SceneEditKind.InsertNode;
+
+    /** The id of the node to insert under. */
+    target: string;
+
+    /** The named slot of an `ExternalComponent` target to insert into. */
+    slot?: string;
+
+    /** Where among the target's children. Absent appends. */
+    index?: number;
+
+    element?: SceneElement;
+    flowNode?: FlowNode;
+}
+
+export const InsertNodeEditPropertyNames: (keyof InsertNodeEdit)[] = ['kind', 'target', 'slot', 'index', 'element', 'flowNode'];

package/editing/InspectedCollectionItem.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One item of an inspected collection.
+ */
+export interface InspectedCollectionItem {
+    id: string;
+    values: Record<string, unknown>;
+
+    /** `owner` for the template author's item; otherwise the contributing instance. */
+    origin: string;
+
+    /** Whether the editing scope may change or remove this item. */
+    editable: boolean;
+}
+
+export const InspectedCollectionItemPropertyNames: (keyof InspectedCollectionItem)[] = ['id', 'values', 'origin', 'editable'];

package/editing/InspectedProperty.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CollectionOperation, PropertyDescriptor } from '../descriptors';
+import { EditTarget } from './EditTarget';
+import { InspectedCollectionItem } from './InspectedCollectionItem';
+import { ValueSource } from './ValueSource';
+
+/**
+ * One property of an inspected node: its descriptor, its current and effective values, and whether - and
+ * through what - the editing scope can change it.
+ */
+export interface InspectedProperty {
+    descriptor: PropertyDescriptor;
+
+    /** The value stored on the node, or `undefined` when none is. */
+    currentValue: unknown;
+
+    /** What the property is worth after defaults and instance contributions. */
+    effectiveValue: unknown;
+
+    /** Where `effectiveValue` came from. */
+    source: `${ValueSource}`;
+
+    /** Whether the editing scope can change the property at all. */
+    editable: boolean;
+
+    /** Where an edit goes. Absent when the property is not editable. */
+    editTarget?: `${EditTarget}`;
+
+    /** Why the property is not editable. */
+    reason?: string;
+
+    /** For an exposed collection: what the editing scope may do with it. */
+    operations?: CollectionOperation[];
+
+    /** For a collection: the items, owner's first. */
+    items?: InspectedCollectionItem[];
+}
+
+export const InspectedPropertyPropertyNames: (keyof InspectedProperty)[] = [
+    'descriptor', 'currentValue', 'effectiveValue', 'source', 'editable', 'editTarget', 'reason', 'operations', 'items',
+];

package/editing/MoveNodeEdit.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Moves a node - reordering it within its parent or reparenting it - checking containment and cycles.
+ */
+export interface MoveNodeEdit {
+    kind: SceneEditKind.MoveNode;
+    nodeId: string;
+
+    /** The id of the node to move under. */
+    target: string;
+    slot?: string;
+    index?: number;
+}
+
+export const MoveNodeEditPropertyNames: (keyof MoveNodeEdit)[] = ['kind', 'nodeId', 'target', 'slot', 'index'];

package/editing/NodeInspection.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { LayoutCapabilities } from '../descriptors';
+import { InspectedProperty } from './InspectedProperty';
+import { NodeProvenance } from './NodeProvenance';
+import { SceneDiagnostic } from './SceneDiagnostic';
+import { SceneNodeKind } from './SceneNodeKind';
+
+/**
+ * What an editor needs to know about one node: what it is, where it comes from, what can be edited on it and
+ * what can be done with it.
+ */
+export interface NodeInspection {
+    nodeId: string;
+    kind: `${SceneNodeKind}`;
+
+    /**
+     * What sort of node: a {@link LayoutType} for a layout node, the component name for an element
+     * that is a component, otherwise the element's kind.
+     */
+    typeId: string;
+
+    /** A name for a tree or an inspector title. */
+    label: string;
+
+    /** The id of the node that contains this one, when there is one. */
+    parentId?: string;
+
+    provenance: NodeProvenance;
+
+    /** Every property with a descriptor, with its values and editability. */
+    properties: InspectedProperty[];
+
+    /** For a layout node: what the layout type can do. */
+    capabilities?: LayoutCapabilities;
+
+    /** Whether the node can be removed or moved by the editing scope. */
+    removable: boolean;
+
+    diagnostics: SceneDiagnostic[];
+}
+
+export const NodeInspectionPropertyNames: (keyof NodeInspection)[] = [
+    'nodeId', 'kind', 'typeId', 'label', 'parentId', 'provenance', 'properties', 'capabilities', 'removable', 'diagnostics',
+];

package/editing/NodeProvenance.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ProvenanceKind } from './ProvenanceKind';
+
+/**
+ * Whether a node is the editing scope's own or comes from further out, and from where.
+ */
+export interface NodeProvenance {
+    kind: `${ProvenanceKind}`;
+
+    /** For an inherited node: the name of the layout or template that owns it. */
+    source?: string;
+}
+
+export const NodeProvenancePropertyNames: (keyof NodeProvenance)[] = ['kind', 'source'];

package/editing/ProvenanceKind.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Where a node comes from, relative to the editing scope.
+ */
+export enum ProvenanceKind {
+    /** Owned by the thing being edited. Fully editable. */
+    Local = 'local',
+
+    /** Owned by an outer layout or template that exposed nothing on it. Read-only here. */
+    Inherited = 'inherited',
+
+    /** Owned by an outer layout or template that exposed some of its properties. Those can be configured here. */
+    ConfigurableInherited = 'configurableInherited',
+}

package/editing/RemoveCollectionItemEdit.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Removes an item an instance contributed to an exposed collection.
+ */
+export interface RemoveCollectionItemEdit {
+    kind: SceneEditKind.RemoveCollectionItem;
+    instance?: string;
+    component: string;
+    path: string;
+    itemId: string;
+}
+
+export const RemoveCollectionItemEditPropertyNames: (keyof RemoveCollectionItemEdit)[] = ['kind', 'instance', 'component', 'path', 'itemId'];

package/editing/RemoveNodeEdit.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Removes a node and everything under it.
+ */
+export interface RemoveNodeEdit {
+    kind: SceneEditKind.RemoveNode;
+    nodeId: string;
+}
+
+export const RemoveNodeEditPropertyNames: (keyof RemoveNodeEdit)[] = ['kind', 'nodeId'];

package/editing/ReorderCollectionItemEdit.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Moves an item an instance contributed to another place among that instance's own items.
+ */
+export interface ReorderCollectionItemEdit {
+    kind: SceneEditKind.ReorderCollectionItem;
+    instance?: string;
+    component: string;
+    path: string;
+    itemId: string;
+    index: number;
+}
+
+export const ReorderCollectionItemEditPropertyNames: (keyof ReorderCollectionItemEdit)[] = [
+    'kind', 'instance', 'component', 'path', 'itemId', 'index',
+];

package/editing/ResetInstanceValueEdit.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Removes what an instance set on an exposed property, so the inherited value applies again. For a collection it
+ * removes every item the instance contributed.
+ */
+export interface ResetInstanceValueEdit {
+    kind: SceneEditKind.ResetInstanceValue;
+    instance?: string;
+    component: string;
+    path: string;
+}
+
+export const ResetInstanceValueEditPropertyNames: (keyof ResetInstanceValueEdit)[] = ['kind', 'instance', 'component', 'path'];

package/editing/ResetPropertyEdit.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEditKind } from './SceneEditKind';
+
+/**
+ * Removes a property's stored value, so the descriptor's default applies again.
+ */
+export interface ResetPropertyEdit {
+    kind: SceneEditKind.ResetProperty;
+    nodeId: string;
+    path: string;
+}
+
+export const ResetPropertyEditPropertyNames: (keyof ResetPropertyEdit)[] = ['kind', 'nodeId', 'path'];

package/editing/SceneDiagnostic.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DiagnosticCode } from './DiagnosticCode';
+import { DiagnosticSeverity } from './DiagnosticSeverity';
+
+/**
+ * One finding from inspecting, editing, validating or resolving. Plain data, so a host can show it, persist it or
+ * ship it to another process.
+ */
+export interface SceneDiagnostic {
+    code: `${DiagnosticCode}`;
+    severity: `${DiagnosticSeverity}`;
+    message: string;
+
+    /** The node the finding is about, when there is one. */
+    nodeId?: string;
+
+    /** The instance the finding is about. */
+    instance?: string;
+
+    /** The id of the component the finding is about. */
+    component?: string;
+
+    /** The property path the finding is about. */
+    path?: string;
+
+    /** The collection item the finding is about. */
+    itemId?: string;
+}
+
+export const SceneDiagnosticPropertyNames: (keyof SceneDiagnostic)[] = [
+    'code', 'severity', 'message', 'nodeId', 'instance', 'component', 'path', 'itemId',
+];