@cratis/scene.engine 4.14.0 → 4.15.0

package/forms/CommandFormLayoutKey.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The keys a designer maps to layout moves and resizes. */
+export enum CommandFormLayoutKey {
+    ArrowLeft = 'ArrowLeft',
+    ArrowRight = 'ArrowRight',
+    ArrowUp = 'ArrowUp',
+    ArrowDown = 'ArrowDown',
+}

package/forms/applyCommandFormLayoutKey.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandFormLayout, FormFieldPlacement } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+import { CommandFormLayoutKey } from './CommandFormLayoutKey';
+import { updateCommandFormFieldPlacement } from './updateCommandFormFieldPlacement';
+
+/**
+ * Moves or resizes one field from the keyboard, so the layout can be arranged without a pointer.
+ *
+ * An arrow key moves the field one cell; with `resize`, Left and Right narrow and widen its column span and
+ * Up and Down shorten and lengthen its row span. Positions are one-based and never go below one, and spans never below one.
+ * The result is a draft validated like any other placement change, so a move or resize past the last
+ * column is reported in its diagnostics and the committed layout is kept. Returns undefined for a field that is not placed.
+ */
+export function applyCommandFormLayoutKey(
+    committed: CommandFormLayout,
+    field: string,
+    key: CommandFormLayoutKey,
+    resize = false,
+    fields: readonly string[] = [],
+): CommandFormLayoutDraft | undefined {
+    const placement = committed.placements.find(candidate => candidate.field === field);
+    if (!placement) return undefined;
+    return updateCommandFormFieldPlacement(committed, resize ? resized(placement, key) : moved(placement, key), fields);
+}
+
+function moved(placement: FormFieldPlacement, key: CommandFormLayoutKey): FormFieldPlacement {
+    switch (key) {
+        case CommandFormLayoutKey.ArrowLeft: return { ...placement, column: Math.max(1, placement.column - 1) };
+        case CommandFormLayoutKey.ArrowRight: return { ...placement, column: placement.column + 1 };
+        case CommandFormLayoutKey.ArrowUp: return { ...placement, row: Math.max(1, placement.row - 1) };
+        case CommandFormLayoutKey.ArrowDown: return { ...placement, row: placement.row + 1 };
+    }
+}
+
+function resized(placement: FormFieldPlacement, key: CommandFormLayoutKey): FormFieldPlacement {
+    const columnSpan = placement.columnSpan ?? 1;
+    const rowSpan = placement.rowSpan ?? 1;
+    switch (key) {
+        case CommandFormLayoutKey.ArrowLeft: return { ...placement, columnSpan: Math.max(1, columnSpan - 1) };
+        case CommandFormLayoutKey.ArrowRight: return { ...placement, columnSpan: columnSpan + 1 };
+        case CommandFormLayoutKey.ArrowUp: return { ...placement, rowSpan: Math.max(1, rowSpan - 1) };
+        case CommandFormLayoutKey.ArrowDown: return { ...placement, rowSpan: rowSpan + 1 };
+    }
+}

package/forms/index.ts

@@ -13,3 +13,6 @@ export * from './preserveDirtyCommandValues';
 export * from './resizeCommandFormColumn';
 export * from './updateCommandFormFieldPlacement';
 export * from './validateCommandFormLayout';
+export * from './CommandFormLayoutKey';
+export * from './applyCommandFormLayoutKey';
+export * from './stackCommandFormLayout';

package/forms/stackCommandFormLayout.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 { CommandFormLayout, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * The layout a command form uses at a compact width: one full-width column, every field on its own row,
+ * in reading order - row first, then column, then authored order. Spans and per-field widths are dropped
+ * because there is nothing to span. The authored layout is not changed, so the form returns to its columns
+ * at a regular width.
+ */
+export function stackCommandFormLayout(layout: CommandFormLayout): CommandFormLayout {
+    const ordered = layout.placements
+        .map((placement, order) => ({ placement, order }))
+        .sort((left, right) => left.placement.row - right.placement.row || left.placement.column - right.placement.column || left.order - right.order);
+
+    return {
+        ...layout,
+        columns: [{ index: 1, width: { unit: FormWidthUnit.Fraction, value: 1 } }],
+        placements: ordered.map(({ placement }, index) => ({ field: placement.field, row: index + 1, column: 1 })),
+    };
+}

package/index.ts

@@ -6,6 +6,10 @@ export * from './BindingResolver';
 export * from './BindingScope';
 export * from './BindingDiagnostic';
 export * from './resolveBindingExpression';
+export * from './nestBindingScope';
+export * from './removeComponentOutputs';
+export * from './QueryBindingState';
+export * from './QueryBindingTicket';
 export * from './validateBindingExpression';
 export * from './renderElement';
 export * from './forms';

package/nestBindingScope.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 { BindingScope } from './BindingScope';
+
+/**
+ * The scope a nested template or region sees. A data context it declares replaces the inherited one - a
+ * detail region bound to the selected row reads that row, not the screen's - while query results and
+ * component outputs are inherited, with its own entries shadowing the parent's of the same name. A null
+ * data context inherits, as in the C# engine, which cannot tell null from absent. The parent scope is not
+ * changed.
+ */
+export function nestBindingScope(parent: BindingScope, nested: BindingScope): BindingScope {
+    return {
+        dataContext: nested.dataContext ?? parent.dataContext,
+        queryResults: { ...(parent.queryResults ?? {}), ...(nested.queryResults ?? {}) },
+        componentOutputs: { ...(parent.componentOutputs ?? {}), ...(nested.componentOutputs ?? {}) },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.14.0",
+    "version": "4.15.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.14.0"
+        "@cratis/scene.model": "4.15.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.14.0"
+        "@cratis/scene.model": "4.15.0"
     }
 }

package/removeComponentOutputs.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 { BindingScope } from './BindingScope';
+
+/**
+ * The scope after elements leave the tree - unmounted, deleted or renamed to a new id. Their output
+ * properties are removed, so a binding to them resolves as absent and validates as `unknownComponent`
+ * instead of reading a value from an element that no longer exists.
+ */
+export function removeComponentOutputs(scope: BindingScope, elementIds: string[]): BindingScope {
+    const removed = new Set(elementIds);
+    const componentOutputs = Object.fromEntries(Object.entries(scope.componentOutputs ?? {}).filter(([id]) => !removed.has(id)));
+    return { ...scope, componentOutputs };
+}

package/resolveBindingExpression.ts

@@ -9,10 +9,12 @@ import { BindingScope } from './BindingScope';
  */
 export function resolveBindingExpression(binding: BindingExpression, scope: BindingScope): unknown {
     const kind = binding.kind ?? BindingSourceKind.DataContext;
-    if (kind === BindingSourceKind.Literal) return binding.value;
 
-    const source = sourceValue(binding, scope, kind);
-    const value = readPath(source, sourcePath(binding, kind));
+    // A literal without a value is absent, whether the author wrote `null` or nothing: the C# model cannot
+    // tell the two apart, and both engines must resolve the same document to the same value.
+    const value = kind === BindingSourceKind.Literal
+        ? binding.value ?? undefined
+        : readPath(sourceValue(binding, scope, kind), sourcePath(binding, kind));
     if (value !== null && value !== undefined) return value;
 
     if (binding.nullBehavior === BindingNullBehavior.Preserve) return undefined;
@@ -30,7 +32,7 @@ export function createBindingResolver(scope: BindingScope): (binding: BindingExp
 function sourceValue(binding: BindingExpression, scope: BindingScope, kind: BindingSourceKind): unknown {
     switch (kind) {
         case BindingSourceKind.DataContext:
-            return scope.dataContext;
+            return scope.dataContext ?? undefined;
         case BindingSourceKind.QueryResult:
             return binding.query ? scope.queryResults?.[binding.query] : undefined;
         case BindingSourceKind.ComponentProperty:
@@ -45,11 +47,16 @@ function sourcePath(binding: BindingExpression, kind: BindingSourceKind): string
     return binding.path;
 }
 
+/**
+ * Reads a dotted path. Only own properties and array indexes are read - never inherited members such as
+ * `constructor` - and anything that is not an object or array ends the walk, so the C# engine can follow
+ * exactly the same rule over JSON.
+ */
 function readPath(source: unknown, path: string): unknown {
     if (!path) return source;
     return path.split('.').reduce<unknown>((current, segment) => {
-        if (current === null || current === undefined) return undefined;
-        if (typeof current !== 'object') return undefined;
-        return (current as Record<string, unknown>)[segment];
+        if (current === null || current === undefined || typeof current !== 'object') return undefined;
+        if (Array.isArray(current)) return /^(0|[1-9][0-9]*)$/.test(segment) ? current[Number(segment)] : undefined;
+        return Object.hasOwn(current, segment) ? (current as Record<string, unknown>)[segment] : undefined;
     }, source);
 }