@cratis/scene.engine 4.14.0 → 4.16.0

package/editing/resolveEffectiveConfiguration.ts

@@ -162,6 +162,17 @@ export function resolveEffectiveConfiguration(
             }
         }
 
+        const maximumItems = grant.descriptor.constraints?.maximumItems;
+        if (isCollection && maximumItems !== undefined && items.length > maximumItems) {
+            // Saved items that no longer fit - the owner lowered the limit after they were added - are left out of
+            // the result in order and kept in the saved data, like any other saved value that no longer fits.
+            const dropped = items.splice(maximumItems);
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ContributionTypeMismatch,
+                `'${grant.path}' on '${grant.component}' allows at most ${maximumItems} items; ${dropped.map(item => `'${item.id}'`).join(', ')} ${dropped.length === 1 ? 'is' : 'are'} ignored and kept.`,
+                { instance: current.contributedBy ?? owner.instance, component: grant.component, path: grant.path }));
+        }
+
         if (isCollection) {
             current.items = items;
             current.inheritedValue = baseItems.map(toFlatItem);

package/editing/validateValue.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { CollectionItemDescriptor, PropertyDescriptor, PropertyValueType } from '@cratis/scene.model';
+import { BindingSourceKind, CollectionItemDescriptor, PropertyDescriptor, PropertyValueType } from '@cratis/scene.model';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -24,6 +24,13 @@ export function validateValue(descriptor: PropertyDescriptor, value: unknown): s
         return constraints.required ? 'a value is required' : undefined;
     }
 
+    const binding = bindingKindOf(value);
+    if (binding !== undefined && descriptor.acceptedBindingKinds !== undefined) {
+        return descriptor.acceptedBindingKinds.includes(binding.kind)
+            ? undefined
+            : `a ${binding.kind} binding is not accepted here; use ${descriptor.acceptedBindingKinds.join(' or ')}`;
+    }
+
     switch (descriptor.valueType) {
         case PropertyValueType.String: {
             if (typeof value !== 'string') return 'expected a string';
@@ -77,6 +84,19 @@ export function validateValue(descriptor: PropertyDescriptor, value: unknown): s
  * The deepest nesting a JSON value may have. Authored configuration (chart datasets, option lists) is shallow;
  * the limit turns a runaway or hostile structure into a validation message instead of a stack overflow.
  */
+const bindingKinds = new Set<string>(Object.values(BindingSourceKind));
+
+/**
+ * The source kind of a value that is a typed binding expression - an object with a known `kind` and a
+ * string `path` - rather than a value of the property's own type. Only consulted for properties that declare
+ * `acceptedBindingKinds`, so a collection property such as a command form's `inputs` can be bound to a
+ * table's `selectedItem` instead of listing its items.
+ */
+function bindingKindOf(value: unknown): { kind: BindingSourceKind } | undefined {
+    if (!isRecord(value) || typeof value.kind !== 'string' || !bindingKinds.has(value.kind) || typeof value.path !== 'string') return undefined;
+    return { kind: value.kind as BindingSourceKind };
+}
+
 const maximumJsonDepth = 64;
 
 /**

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,11 @@ export * from './BindingResolver';
 export * from './BindingScope';
 export * from './BindingDiagnostic';
 export * from './resolveBindingExpression';
+export * from './nestBindingScope';
+export * from './resolveArgumentSource';
+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.16.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.16.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.14.0"
+        "@cratis/scene.model": "4.16.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/resolveArgumentSource.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingSourceKind } from '@cratis/scene.model';
+import { BindingScope } from './BindingScope';
+import { resolveBindingExpression } from './resolveBindingExpression';
+
+/** The prefix of an argument source that reads another element's output. */
+export const componentArgumentSourcePrefix = 'component.';
+
+/**
+ * Resolves where a command argument comes from, as an action's argument mapping writes it.
+ *
+ * `component.<id>.<output>` reads an output another element publishes - an input's `value`, a table's
+ * `selectedItem.id` - from the same output scope a `componentProperty` binding reads. Element ids may contain
+ * dots, so the longest id with outputs in scope wins: `component.order.lines.value` reads `value` of
+ * `order.lines` when that element exists. Any other source is a path in the data context. An empty source,
+ * or an element with no outputs in scope, resolves as absent.
+ *
+ * The C# engine (`ArgumentSources.Resolve`) behaves identically; both run `argument-source-fixtures.json`.
+ */
+export function resolveArgumentSource(source: string, scope: BindingScope): unknown {
+    if (!source) return undefined;
+    if (!source.startsWith(componentArgumentSourcePrefix)) return resolveBindingExpression({ path: source }, scope);
+
+    const reference = source.substring(componentArgumentSourcePrefix.length);
+    const componentId = Object.keys(scope.componentOutputs ?? {})
+        .filter(id => reference === id || reference.startsWith(`${id}.`))
+        .sort((left, right) => right.length - left.length)[0];
+    if (componentId === undefined) return undefined;
+
+    return resolveBindingExpression({ kind: BindingSourceKind.ComponentProperty, componentId, path: reference.substring(componentId.length + 1) }, scope);
+}

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);
 }