@cratis/scene.engine 4.27.0 → 4.28.0

package/index.ts

@@ -45,3 +45,4 @@ export * from './validateNavigationDestinations';
 export * from './editing';
 export * from './sampleData';
 export * from './structure';
+export * from './toolbar';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.27.0",
+    "version": "4.28.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.27.0"
+        "@cratis/scene.model": "4.28.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.27.0"
+        "@cratis/scene.model": "4.28.0"
     }
 }

package/structure/ApplicationStructureIndex.ts

@@ -104,6 +104,17 @@ export class ApplicationStructureIndex {
         return [...(this.featuresByName.get(name.toLowerCase()) ?? [])];
     }
 
+    /**
+     * Finds the state change slices that accept a command, so a command named by hand can be turned into the slice that owns it.
+     * @param command A command name - the slice's `command`, or its `id` when it names none - or a slice's qualified id.
+     * @returns The qualified ids of the matching state change slices, in declaration order.
+     */
+    findSlicesByCommand(command: string): string[] {
+        return [...this.slices.entries()]
+            .filter(([qualified, slice]) => slice.kind === SliceKind.StateChange && (qualified === command || (slice.command ?? slice.id) === command))
+            .map(([qualified]) => qualified);
+    }
+
     private indexContainer(path: string, features: FeatureNode[], slices: SliceNode[]): void {
         const seen = new Map<string, string>();
         const featureNames = new Map<string, string>();

package/toolbar/ResolvedToolbarButton.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 { ToolbarEmphasis } from '@cratis/scene.model';
+import { SliceDialog } from './SliceDialog';
+
+/**
+ * A toolbar button resolved against the application structure: what a renderer needs to draw it and to open its dialog.
+ */
+export interface ResolvedToolbarButton {
+    /** The button identity. */
+    id: string;
+
+    /** The text shown on the button. */
+    title: string;
+
+    /** How prominent the button is. */
+    emphasis: ToolbarEmphasis;
+
+    /** Qualified icon reference, when the button has one. */
+    icon?: string;
+
+    /** The qualified id of the slice the button invokes, when it names or resolves to one. */
+    slice?: string;
+
+    /** Whether the slice was found from a hand-authored command rather than named directly. */
+    converted: boolean;
+
+    /** The command the slice accepts; absent unless the slice is a known state change. */
+    command?: string;
+
+    /** The task dialog the button opens; absent unless the slice is a known state change. */
+    dialog?: SliceDialog;
+}

package/toolbar/SliceDialog.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 { SliceDialogSource } from './SliceDialogSource';
+
+/**
+ * The task dialog a state change slice opens: its command and the dialog template that shows the command's fields as a form.
+ */
+export interface SliceDialog {
+    /** The qualified id of the slice. */
+    slice: string;
+
+    /** The command the dialog submits. */
+    command: string;
+
+    /** The dialog template. */
+    template: string;
+
+    /** Whether the slice named the template or the default was used. */
+    source: SliceDialogSource;
+}

package/toolbar/SliceDialogSource.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 a slice's dialog template comes from.
+ */
+export enum SliceDialogSource {
+    /** The slice names its own dialog template. */
+    Slice = 'slice',
+
+    /** The slice names none, so the default form dialog is used. */
+    Default = 'default',
+}

package/toolbar/ToolbarDiagnostic.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 { ToolbarDiagnosticCode } from './ToolbarDiagnosticCode';
+import { ToolbarDiagnosticSeverity } from './ToolbarDiagnosticSeverity';
+
+/**
+ * One problem with a toolbar button.
+ */
+export interface ToolbarDiagnostic {
+    /** What kind of problem this is. */
+    code: ToolbarDiagnosticCode;
+
+    /** Whether the button cannot work or is only incomplete. */
+    severity: ToolbarDiagnosticSeverity;
+
+    /** A sentence naming the button and the slice. */
+    message: string;
+
+    /** The id of the button the problem was found on. */
+    button: string;
+}

package/toolbar/ToolbarDiagnosticCode.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.
+
+/**
+ * What is wrong with a toolbar button. The values are shared with the C# engine so both report the same code for
+ * the same toolbar.
+ */
+export enum ToolbarDiagnosticCode {
+    /** A button invokes a slice the application structure does not have. */
+    ToolbarButtonSliceNotFound = 'toolbarButtonSliceNotFound',
+
+    /** A button invokes a slice that is not a state change; state views and automations never take user input. */
+    ToolbarButtonSliceNotStateChange = 'toolbarButtonSliceNotStateChange',
+
+    /** A button has no slice yet. It is allowed while designing, and flagged. */
+    ToolbarButtonSliceEmpty = 'toolbarButtonSliceEmpty',
+}

package/toolbar/ToolbarDiagnosticSeverity.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.
+
+/**
+ * How serious a toolbar diagnostic is.
+ */
+export enum ToolbarDiagnosticSeverity {
+    /** The button cannot work. */
+    Error = 'error',
+
+    /** The button is allowed but incomplete. */
+    Warning = 'warning',
+}

package/toolbar/index.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.
+
+export * from './ToolbarDiagnosticCode';
+export * from './ToolbarDiagnosticSeverity';
+export * from './ToolbarDiagnostic';
+export * from './SliceDialogSource';
+export * from './SliceDialog';
+export * from './ResolvedToolbarButton';
+export * from './sliceDialogFor';
+export * from './toolbarButtons';
+export * from './validateToolbarButtons';

package/toolbar/sliceDialogFor.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 { SliceKind } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '../structure';
+import { SliceDialog } from './SliceDialog';
+import { SliceDialogSource } from './SliceDialogSource';
+
+/** The dialog template used when a slice names none. */
+export const defaultSliceDialogTemplate = 'FormDialog';
+
+/**
+ * Works out the task dialog a state change slice opens, once, so no host decides it again (TB4): the slice's own
+ * dialog template when it names one, else the default form dialog.
+ *
+ * The C# engine (`SliceDialogs.For`) resolves the same dialog; both are asserted against `toolbar-slice-fixtures.json`.
+ *
+ * @param index The modules, features and slices of the application.
+ * @param sliceId The slice's qualified id.
+ * @param defaultTemplate The template used when the slice names none; {@link defaultSliceDialogTemplate} when absent.
+ * @returns The dialog, or undefined when there is no such slice or it is not a state change.
+ */
+export function sliceDialogFor(index: ApplicationStructureIndex, sliceId: string, defaultTemplate?: string): SliceDialog | undefined {
+    const slice = index.findSlice(sliceId);
+    if (slice?.kind !== SliceKind.StateChange) return undefined;
+
+    const command = slice.command ?? slice.id;
+    return slice.dialogTemplate
+        ? { slice: sliceId, command, template: slice.dialogTemplate, source: SliceDialogSource.Slice }
+        : { slice: sliceId, command, template: defaultTemplate ?? defaultSliceDialogTemplate, source: SliceDialogSource.Default };
+}

package/toolbar/toolbarButtons.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ToolbarButton, ToolbarEmphasis } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '../structure';
+import { ResolvedToolbarButton } from './ResolvedToolbarButton';
+import { sliceDialogFor } from './sliceDialogFor';
+
+function text(properties: Record<string, unknown>, name: string): string | undefined {
+    const value = properties[name];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Reads a button from the properties of a `core:toolbarItem` element: `label` (or `name`), `kind`, `slice`,
+ * `emphasis`, `icon` and `target`.
+ *
+ * The C# engine (`ToolbarButtons.FromItem`) reads the same; both are asserted against `toolbar-slice-fixtures.json`.
+ *
+ * @param id The element id.
+ * @param properties The element properties.
+ * @returns The button, or undefined when the item does not invoke a command or slice - a navigate or dialog item.
+ */
+export function toolbarButtonFromItem(id: string, properties: Record<string, unknown>): ToolbarButton | undefined {
+    const slice = text(properties, 'slice');
+    const action = text(properties, 'kind')?.toLowerCase() === 'action';
+    if (slice === undefined && !action) return undefined;
+
+    const button: ToolbarButton = { id, title: text(properties, 'label') ?? text(properties, 'name') ?? id };
+    if (slice !== undefined) button.slice = slice;
+
+    const emphasis = text(properties, 'emphasis')?.toLowerCase();
+    if (emphasis === ToolbarEmphasis.Primary || emphasis === ToolbarEmphasis.Secondary || emphasis === ToolbarEmphasis.Quiet) button.emphasis = emphasis;
+
+    const icon = text(properties, 'icon');
+    if (icon !== undefined) button.icon = icon;
+
+    const target = text(properties, 'target');
+    if (target !== undefined) button.target = target;
+    return button;
+}
+
+/**
+ * Converts a hand-authored button to a slice-backed one: a button with no slice whose command is accepted by exactly
+ * one state change slice names that slice instead.
+ * @param index The modules, features and slices of the application.
+ * @param button The button.
+ * @returns The button to use, and whether it was converted. A button that cannot be converted is returned as it is.
+ */
+export function normalizeToolbarButton(index: ApplicationStructureIndex, button: ToolbarButton): { button: ToolbarButton; converted: boolean } {
+    if (button.slice || !button.target) return { button, converted: false };
+
+    const matches = index.findSlicesByCommand(button.target);
+    if (matches.length !== 1) return { button, converted: false };
+
+    const { target, ...rest } = button;
+    void target;
+    return { button: { ...rest, slice: matches[0] }, converted: true };
+}
+
+/**
+ * Resolves a button: its slice, command and task dialog, without any rendering. This is what a renderer, Stage and the
+ * Studio preview call.
+ *
+ * The C# engine (`ToolbarButtons.Resolve`) resolves the same; both are asserted against `toolbar-slice-fixtures.json`.
+ *
+ * @param index The modules, features and slices of the application.
+ * @param button The button.
+ * @param defaultDialogTemplate The dialog template used when a slice names none.
+ */
+export function resolveToolbarButton(index: ApplicationStructureIndex, button: ToolbarButton, defaultDialogTemplate?: string): ResolvedToolbarButton {
+    const { button: normalized, converted } = normalizeToolbarButton(index, button);
+    const dialog = normalized.slice ? sliceDialogFor(index, normalized.slice, defaultDialogTemplate) : undefined;
+    const resolved: ResolvedToolbarButton = { id: normalized.id, title: normalized.title, emphasis: normalized.emphasis ?? ToolbarEmphasis.Secondary, converted };
+    if (normalized.icon !== undefined) resolved.icon = normalized.icon;
+    if (normalized.slice) resolved.slice = normalized.slice;
+    if (dialog) {
+        resolved.command = dialog.command;
+        resolved.dialog = dialog;
+    }
+
+    return resolved;
+}

package/toolbar/validateToolbarButtons.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 { ApplicationStructure, SliceKind, Toolbar } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '../structure';
+import { ToolbarDiagnostic } from './ToolbarDiagnostic';
+import { ToolbarDiagnosticCode } from './ToolbarDiagnosticCode';
+import { ToolbarDiagnosticSeverity } from './ToolbarDiagnosticSeverity';
+import { normalizeToolbarButton } from './toolbarButtons';
+
+/**
+ * Validates the buttons of a toolbar against the application structure: a button must invoke a state change slice
+ * (TB3), and a button without a slice is allowed but flagged (TB5). A hand-authored button that names a command is
+ * converted first, and a button whose command no single slice accepts is a legacy button that still validates.
+ *
+ * The C# engine (`ToolbarButtonValidation.Validate`) reports the same codes, severities and messages in the same
+ * order; both are asserted against `toolbar-slice-fixtures.json`.
+ *
+ * @param structure The modules, features and slices of the application.
+ * @param toolbar The toolbar.
+ * @returns The problems found, in button order.
+ */
+export function validateToolbarButtons(structure: ApplicationStructure | ApplicationStructureIndex, toolbar: Toolbar): ToolbarDiagnostic[] {
+    const index = structure instanceof ApplicationStructureIndex ? structure : new ApplicationStructureIndex(structure);
+    const diagnostics: ToolbarDiagnostic[] = [];
+
+    for (const authored of toolbar.buttons) {
+        const { button } = normalizeToolbarButton(index, authored);
+        if (!button.slice) {
+            if (!button.target) {
+                diagnostics.push({
+                    code: ToolbarDiagnosticCode.ToolbarButtonSliceEmpty,
+                    severity: ToolbarDiagnosticSeverity.Warning,
+                    message: `Toolbar button '${button.id}' has no slice to invoke.`,
+                    button: button.id,
+                });
+            }
+
+            continue;
+        }
+
+        const slice = index.findSlice(button.slice);
+        if (!slice) {
+            diagnostics.push({
+                code: ToolbarDiagnosticCode.ToolbarButtonSliceNotFound,
+                severity: ToolbarDiagnosticSeverity.Error,
+                message: `Toolbar button '${button.id}' invokes slice '${button.slice}', which does not exist.`,
+                button: button.id,
+            });
+        } else if (slice.kind !== SliceKind.StateChange) {
+            diagnostics.push({
+                code: ToolbarDiagnosticCode.ToolbarButtonSliceNotStateChange,
+                severity: ToolbarDiagnosticSeverity.Error,
+                message: `Toolbar button '${button.id}' invokes slice '${button.slice}', which is ${slice.kind === SliceKind.StateView ? 'a state view' : 'an automation'}; only a state change can be invoked from a toolbar.`,
+                button: button.id,
+            });
+        }
+    }
+
+    return diagnostics;
+}