@cratis/scene.engine 4.11.0 → 4.12.0

package/forms/CommandFormLayoutDiagnostic.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.
+
+import { CommandFormLayoutDiagnosticCode } from './CommandFormLayoutDiagnosticCode';
+
+/**
+ * A validation problem in authored command-form geometry.
+ */
+export interface CommandFormLayoutDiagnostic {
+    code: CommandFormLayoutDiagnosticCode;
+    message: string;
+    path: string;
+}

package/forms/CommandFormLayoutDiagnosticCode.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.
+
+/**
+ * Diagnostic codes for command-form geometry validation.
+ */
+export enum CommandFormLayoutDiagnosticCode {
+    EmptyColumns = 'emptyColumns',
+    DuplicateColumn = 'duplicateColumn',
+    InvalidColumnIndex = 'invalidColumnIndex',
+    InvalidWidth = 'invalidWidth',
+    DuplicatePlacement = 'duplicatePlacement',
+    InvalidPlacement = 'invalidPlacement',
+    MissingField = 'missingField',
+    OutOfBoundsPlacement = 'outOfBoundsPlacement',
+}

package/forms/CommandFormLayoutDraft.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 { CommandFormLayout } from '@cratis/scene.model';
+import { CommandFormLayoutDiagnostic } from './CommandFormLayoutDiagnostic';
+
+/**
+ * Separates invalid editing state from the last committed form geometry.
+ */
+export interface CommandFormLayoutDraft {
+    committed: CommandFormLayout;
+    draft: CommandFormLayout;
+    diagnostics: CommandFormLayoutDiagnostic[];
+    isValid: boolean;
+}

package/forms/commitCommandFormLayoutDraft.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.
+
+import { CommandFormLayout } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+
+/**
+ * Commits a draft layout only when it is valid; otherwise returns the previous committed metadata.
+ */
+export function commitCommandFormLayoutDraft(draft: CommandFormLayoutDraft): CommandFormLayout {
+    return draft.isValid ? draft.draft : draft.committed;
+}

package/forms/defaultCommandFormLayout.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.
+
+import { CommandFormLayout, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Backward-compatible command form geometry: one flexible column and no authored placements.
+ */
+export const defaultCommandFormLayout: CommandFormLayout = {
+    columns: [{ index: 1, width: { unit: FormWidthUnit.Fraction, value: 1 } }],
+    placements: [],
+};

package/forms/formWidthToCss.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 { FormWidth, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Converts a platform-neutral form width to a browser CSS width token.
+ */
+export function formWidthToCss(width: FormWidth | undefined): string | undefined {
+    if (!width) return undefined;
+    switch (width.unit) {
+        case FormWidthUnit.Auto:
+            return 'auto';
+        case FormWidthUnit.Fraction:
+            return `${width.value ?? 1}fr`;
+        case FormWidthUnit.Pixels:
+            return `${width.value ?? 0}px`;
+        case FormWidthUnit.Percent:
+            return `${width.value ?? 0}%`;
+    }
+}

package/forms/index.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.
+
+export * from './CommandFormLayoutDiagnostic';
+export * from './CommandFormLayoutDiagnosticCode';
+export * from './CommandFormLayoutDraft';
+export * from './commitCommandFormLayoutDraft';
+export * from './defaultCommandFormLayout';
+export * from './formWidthToCss';
+export * from './normalizeCommandFormLayout';
+export * from './parseFormWidth';
+export * from './preserveDirtyCommandValues';
+export * from './resizeCommandFormColumn';
+export * from './updateCommandFormFieldPlacement';
+export * from './validateCommandFormLayout';

package/forms/normalizeCommandFormLayout.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandFormLayout, FormColumn, FormFieldPlacement, FormWidth, FormWidthUnit } from '@cratis/scene.model';
+import { defaultCommandFormLayout } from './defaultCommandFormLayout';
+import { parseFormWidth } from './parseFormWidth';
+
+export interface LegacyCommandFormInputGeometry {
+    property: string;
+    column?: number;
+    width?: string;
+}
+
+/**
+ * Normalizes authored command form layout, including legacy per-input column/width metadata.
+ */
+export function normalizeCommandFormLayout(layout: CommandFormLayout | undefined, inputs: readonly LegacyCommandFormInputGeometry[] = []): CommandFormLayout {
+    if (layout) return layout;
+    if (!inputs.length) return defaultCommandFormLayout;
+    const placements = inputs.map((input, index): FormFieldPlacement => ({
+        field: input.property,
+        row: index + 1,
+        column: positiveInteger(input.column) ?? 1,
+        width: parseFormWidth(input.width),
+    }));
+    const columnCount = Math.max(1, ...placements.map(placement => placement.column));
+    return {
+        columns: Array.from({ length: columnCount }, (_, index): FormColumn => ({ index: index + 1, width: fraction(1) })),
+        placements,
+    };
+}
+
+function fraction(value: number): FormWidth {
+    return { unit: FormWidthUnit.Fraction, value };
+}
+
+function positiveInteger(value: number | undefined): number | undefined {
+    return value !== undefined && Number.isInteger(value) && value > 0 ? value : undefined;
+}

package/forms/parseFormWidth.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 { FormWidth, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Parses a legacy width token into typed form geometry. Arbitrary strings are intentionally rejected.
+ */
+export function parseFormWidth(value: unknown): FormWidth | undefined {
+    if (!value || typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    if (trimmed === 'auto') return { unit: FormWidthUnit.Auto };
+    const match = /^([0-9]+(?:\.[0-9]+)?)(fr|px|%)$/.exec(trimmed);
+    if (!match) return undefined;
+    const widthValue = Number(match[1]);
+    if (!Number.isFinite(widthValue) || widthValue < 0) return undefined;
+    if (match[2] === 'fr') return { unit: FormWidthUnit.Fraction, value: widthValue };
+    if (match[2] === 'px') return { unit: FormWidthUnit.Pixels, value: widthValue };
+    return { unit: FormWidthUnit.Percent, value: widthValue };
+}

package/forms/preserveDirtyCommandValues.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.
+
+/**
+ * Merges refreshed command values without overwriting dirty fields a user is editing.
+ */
+export function preserveDirtyCommandValues(
+    current: Record<string, unknown>,
+    refreshed: Record<string, unknown>,
+    dirtyFields: ReadonlySet<string>,
+): Record<string, unknown> {
+    return Object.fromEntries(Object.entries(refreshed).map(([field, value]) => [field, dirtyFields.has(field) ? current[field] : value]));
+}

package/forms/resizeCommandFormColumn.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 { CommandFormLayout, FormWidth } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+import { validateCommandFormLayout } from './validateCommandFormLayout';
+
+/**
+ * Resizes a column as draft geometry, keeping the last committed layout separate when invalid.
+ */
+export function resizeCommandFormColumn(
+    committed: CommandFormLayout,
+    columnIndex: number,
+    width: FormWidth,
+    fields: readonly string[] = [],
+): CommandFormLayoutDraft {
+    const draft: CommandFormLayout = {
+        ...committed,
+        columns: committed.columns.map(column => column.index === columnIndex ? { ...column, width } : column),
+    };
+    const diagnostics = validateCommandFormLayout(draft, fields);
+    return { committed, draft, diagnostics, isValid: diagnostics.length === 0 };
+}

package/forms/updateCommandFormFieldPlacement.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, FormFieldPlacement } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+import { validateCommandFormLayout } from './validateCommandFormLayout';
+
+/**
+ * Updates a field placement as draft geometry, keeping the committed layout separate when invalid.
+ */
+export function updateCommandFormFieldPlacement(
+    committed: CommandFormLayout,
+    placement: FormFieldPlacement,
+    fields: readonly string[] = [],
+): CommandFormLayoutDraft {
+    const draft: CommandFormLayout = {
+        ...committed,
+        placements: [...committed.placements.filter(existing => existing.field !== placement.field), placement],
+    };
+    const diagnostics = validateCommandFormLayout(draft, fields);
+    return { committed, draft, diagnostics, isValid: diagnostics.length === 0 };
+}

package/forms/validateCommandFormLayout.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandFormLayout, FormWidth, FormWidthUnit } from '@cratis/scene.model';
+import { CommandFormLayoutDiagnostic } from './CommandFormLayoutDiagnostic';
+import { CommandFormLayoutDiagnosticCode } from './CommandFormLayoutDiagnosticCode';
+
+/**
+ * Validates authored command-form geometry without rewriting invalid drafts.
+ */
+export function validateCommandFormLayout(layout: CommandFormLayout, fields: readonly string[] = []): CommandFormLayoutDiagnostic[] {
+    const diagnostics: CommandFormLayoutDiagnostic[] = [];
+    const columnIndexes = new Set<number>();
+    const knownFields = new Set(fields);
+
+    if (!layout.columns.length) diagnostics.push(problem(CommandFormLayoutDiagnosticCode.EmptyColumns, 'At least one column is required.', 'columns'));
+    layout.columns.forEach((column, index) => {
+        if (!Number.isInteger(column.index) || column.index < 1) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidColumnIndex, `Column ${index + 1} must have a one-based integer index.`, `columns.${index}.index`));
+        }
+        if (columnIndexes.has(column.index)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.DuplicateColumn, `Column ${column.index} is declared more than once.`, `columns.${index}.index`));
+        }
+        columnIndexes.add(column.index);
+        validateWidth(column.width, `columns.${index}.width`, diagnostics);
+        validateWidth(column.minWidth, `columns.${index}.minWidth`, diagnostics);
+        validateWidth(column.maxWidth, `columns.${index}.maxWidth`, diagnostics);
+    });
+
+    validateWidth(layout.columnGap, 'columnGap', diagnostics);
+    validateWidth(layout.rowGap, 'rowGap', diagnostics);
+
+    const placements = new Set<string>();
+    layout.placements.forEach((placement, index) => {
+        if (!placement.field.trim()) diagnostics.push(problem(CommandFormLayoutDiagnosticCode.MissingField, 'A placement must name its field.', `placements.${index}.field`));
+        if (knownFields.size && !knownFields.has(placement.field)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.MissingField, `Placement targets unknown field '${placement.field}'.`, `placements.${index}.field`));
+        }
+        if (placements.has(placement.field)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.DuplicatePlacement, `Field '${placement.field}' is placed more than once.`, `placements.${index}.field`));
+        }
+        placements.add(placement.field);
+        if (!Number.isInteger(placement.row) || placement.row < 1 || !Number.isInteger(placement.column) || placement.column < 1 ||
+            (placement.rowSpan !== undefined && (!Number.isInteger(placement.rowSpan) || placement.rowSpan < 1)) ||
+            (placement.columnSpan !== undefined && (!Number.isInteger(placement.columnSpan) || placement.columnSpan < 1))) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidPlacement, `Placement for '${placement.field}' must use positive integer row, column and span values.`, `placements.${index}`));
+        }
+        const span = placement.columnSpan ?? 1;
+        if (layout.columns.length && placement.column + span - 1 > layout.columns.length) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.OutOfBoundsPlacement, `Placement for '${placement.field}' extends beyond the declared columns.`, `placements.${index}.columnSpan`));
+        }
+        validateWidth(placement.width, `placements.${index}.width`, diagnostics);
+    });
+
+    return diagnostics;
+}
+
+function validateWidth(width: FormWidth | undefined, path: string, diagnostics: CommandFormLayoutDiagnostic[]): void {
+    if (!width) return;
+    if (!Object.values(FormWidthUnit).includes(width.unit)) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Width at '${path}' uses an unsupported unit.`, path));
+        return;
+    }
+    if (width.unit === FormWidthUnit.Auto && width.value !== undefined) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Automatic width at '${path}' must not carry a numeric value.`, path));
+    }
+    if (width.unit !== FormWidthUnit.Auto && (width.value === undefined || width.value < 0 || !Number.isFinite(width.value))) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Width at '${path}' must carry a non-negative numeric value.`, path));
+    }
+}
+
+function problem(code: CommandFormLayoutDiagnosticCode, message: string, path: string): CommandFormLayoutDiagnostic {
+    return { code, message, path };
+}

package/index.ts

@@ -8,6 +8,7 @@ export * from './BindingDiagnostic';
 export * from './resolveBindingExpression';
 export * from './validateBindingExpression';
 export * from './renderElement';
+export * from './forms';
 export * from './elementKind';
 export * from './panelKind';
 export * from './flowNodeKind';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.11.0",
+    "version": "4.12.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.11.0"
+        "@cratis/scene.model": "4.12.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.11.0"
+        "@cratis/scene.model": "4.12.0"
     }
 }