@cratis/scene.components 4.11.0 → 4.12.0

package/forms/CommandFormRuntime.tsx

@@ -4,9 +4,11 @@
 import type { ComponentType, ReactNode } from 'react';
 import { AutoCommandForm } from '@cratis/components/CommandForm';
 import { CommandForm } from '@cratis/arc.react/commands';
+import { formWidthToCss, normalizeCommandFormLayout, validateCommandFormLayout } from '@cratis/scene.engine';
 import { Guid } from '@cratis/fundamentals';
 import type { BoundConstructor } from '../bindings';
 import type { CommandInput } from './commandInputs';
+import type { CommandFormLayout } from '@cratis/scene.model';
 import { CommandFormSubmit } from './CommandFormSubmit';
 import { ExplicitCommandField } from './ExplicitCommandField';
 
@@ -16,6 +18,7 @@ interface CommandFormRuntimeProps {
     exclude?: string[];
     submitLabel: string;
     columns?: number;
+    layout?: CommandFormLayout;
 }
 
 // Runtime bindings erase the proxy's keys; the optional footer is a Components >=4.13 contract.
@@ -60,15 +63,21 @@ function capability(command: BoundConstructor, inputs?: CommandInput[], exclude?
 }
 
 /** Private lazy entry point: importing the Scene registry must not import Arc. */
-export default function CommandFormRuntime({ command, inputs, exclude, submitLabel, columns = 1 }: CommandFormRuntimeProps) {
+export default function CommandFormRuntime({ command, inputs, exclude, submitLabel, columns = 1, layout }: CommandFormRuntimeProps) {
     const error = capability(command, inputs, exclude);
     if (error) return <div role='alert'>{error}</div>;
     // The registry's never-argument constructor is erased; Arc creates this checked proxy with no args.
-    if (inputs) return <CommandForm command={command as unknown as new () => object} showTitles={false}>
-        <div style={{ display: 'grid', gridTemplateColumns: `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`, gap: '1rem' }}>
-            {inputs.map(input => <ExplicitCommandField key={input.property} input={input} />)}
-        </div>
-        <CommandFormSubmit label={submitLabel} />
-    </CommandForm>;
+    if (inputs) {
+        const formLayout = normalizeCommandFormLayout(layout, inputs);
+        const diagnostics = validateCommandFormLayout(formLayout, inputs.map(input => input.property));
+        if (diagnostics.length) return <div role='alert'>{diagnostics[0].message}</div>;
+        const columnsCss = formLayout.columns.map(column => formWidthToCss(column.width) ?? 'minmax(0, 1fr)').join(' ') || `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`;
+        return <CommandForm command={command as unknown as new () => object} showTitles={false}>
+            <div style={{ display: 'grid', gridTemplateColumns: columnsCss, columnGap: formWidthToCss(formLayout.columnGap) ?? '1rem', rowGap: formWidthToCss(formLayout.rowGap) ?? '1rem' }}>
+                {inputs.map(input => <ExplicitCommandField key={input.property} input={input} placement={formLayout.placements.find(placement => placement.field === input.property) ?? input.placement} />)}
+            </div>
+            <CommandFormSubmit label={submitLabel} />
+        </CommandForm>;
+    }
     return <NativeAutoCommandForm command={command} exclude={exclude} footer={<CommandFormSubmit label={submitLabel} />} />;
 }

package/forms/ExplicitCommandField.tsx

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { useId, useLayoutEffect, useRef, useState } from 'react';
+import { formWidthToCss } from '@cratis/scene.engine';
+import { FormFieldPlacement } from '@cratis/scene.model';
 import { asCommandFormField, useCommandFormContext } from '@cratis/arc.react/commands';
 import { Guid } from '@cratis/fundamentals';
 import type { CommandInput } from './commandInputs';
@@ -80,8 +82,14 @@ function TextControl({ value, onChange, onBlur, invalid, required, errors, label
 const NativeTextField = asCommandFormField<TextProps>(TextControl, { defaultValue: '' });
 
 /** Opaque child is self-bound by Arc's native runtime binding, with an exact fieldName. */
-export function ExplicitCommandField({ input }: { input: CommandInput }) {
-    return <div style={{ gridColumn: input.column === undefined ? undefined : `${input.column}`, width: input.width }}>
+export function ExplicitCommandField({ input, placement }: { input: CommandInput; placement?: FormFieldPlacement }) {
+    const effectivePlacement = placement ?? input.placement;
+    const columnSpan = effectivePlacement?.columnSpan ?? 1;
+    return <div style={{
+        gridColumn: effectivePlacement ? `${effectivePlacement.column} / span ${columnSpan}` : undefined,
+        gridRow: effectivePlacement ? `${effectivePlacement.row} / span ${effectivePlacement.rowSpan ?? 1}` : undefined,
+        width: formWidthToCss(effectivePlacement?.width),
+    }}>
         <NativeTextField fieldName={input.property} value={(command: Record<string, unknown>) => command[input.property]}
             property={input.property} guid={input.type === 'guid'} label={input.label} title={input.label} />
     </div>;

package/forms/SceneCommandForm.tsx

@@ -6,6 +6,7 @@ import { RegisteredComponentProps } from '@cratis/scene.react';
 import { ArcRuntimeBoundary, BindingKind, MissingBinding, resolveElementBinding } from '../bindings';
 import type { BoundConstructor } from '../bindings';
 import { numberProperty, stringArrayProperty, stringProperty, unionProperty } from '../properties';
+import { commandFormLayout } from './commandFormLayout';
 import { commandInputs } from './commandInputs';
 
 const CommandFormRuntime = lazy(() => import('./CommandFormRuntime'));
@@ -44,6 +45,7 @@ export function SceneCommandForm({ element }: RegisteredComponentProps) {
                 exclude={stringArrayProperty(element.properties, 'exclude')}
                 submitLabel={stringProperty(element.properties, 'submitLabel') ?? 'Submit'}
                 {...(numberProperty(element.properties, 'columns') === undefined ? {} : { columns: numberProperty(element.properties, 'columns') })}
+                {...(commandFormLayout(element.properties) === undefined ? {} : { layout: commandFormLayout(element.properties) })}
             />
         </ArcRuntimeBoundary>
     );

package/forms/commandFormLayout.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 { CommandFormLayout, FormColumn, FormFieldPlacement, FormWidth, FormWidthUnit } from '@cratis/scene.model';
+import { objectProperty } from '../properties';
+
+/** Reads typed command-form layout metadata from an external component property bag. */
+export function commandFormLayout(properties: Record<string, unknown>): CommandFormLayout | undefined {
+    const layout = objectProperty(properties, 'layout');
+    if (!layout) return undefined;
+    const columns = arrayOfObjects(layout.columns)?.map(readColumn).filter((column): column is FormColumn => column !== undefined);
+    const placements = arrayOfObjects(layout.placements)?.map(readPlacement).filter((placement): placement is FormFieldPlacement => placement !== undefined);
+    if (!columns || !placements) return undefined;
+    return {
+        columns,
+        placements,
+        ...(readWidth(layout.columnGap) ? { columnGap: readWidth(layout.columnGap) } : {}),
+        ...(readWidth(layout.rowGap) ? { rowGap: readWidth(layout.rowGap) } : {}),
+    };
+}
+
+function readColumn(value: Record<string, unknown>): FormColumn | undefined {
+    const index = numberValue(value.index);
+    if (index === undefined) return undefined;
+    return {
+        index,
+        ...(readWidth(value.width) ? { width: readWidth(value.width) } : {}),
+        ...(readWidth(value.minWidth) ? { minWidth: readWidth(value.minWidth) } : {}),
+        ...(readWidth(value.maxWidth) ? { maxWidth: readWidth(value.maxWidth) } : {}),
+    };
+}
+
+function readPlacement(value: Record<string, unknown>): FormFieldPlacement | undefined {
+    const field = typeof value.field === 'string' ? value.field : undefined;
+    const row = numberValue(value.row);
+    const column = numberValue(value.column);
+    if (!field || row === undefined || column === undefined) return undefined;
+    return {
+        field,
+        row,
+        column,
+        ...(numberValue(value.rowSpan) ? { rowSpan: numberValue(value.rowSpan) } : {}),
+        ...(numberValue(value.columnSpan) ? { columnSpan: numberValue(value.columnSpan) } : {}),
+        ...(readWidth(value.width) ? { width: readWidth(value.width) } : {}),
+    };
+}
+
+function readWidth(value: unknown): FormWidth | undefined {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+    const record = value as Record<string, unknown>;
+    if (!Object.values(FormWidthUnit).includes(record.unit as FormWidthUnit)) return undefined;
+    return { unit: record.unit as FormWidthUnit, ...(numberValue(record.value) !== undefined ? { value: numberValue(record.value) } : {}) };
+}
+
+function arrayOfObjects(value: unknown): Record<string, unknown>[] | undefined {
+    return Array.isArray(value) && value.every(item => typeof item === 'object' && item !== null && !Array.isArray(item)) ? value as Record<string, unknown>[] : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+    return typeof value === 'number' && !Number.isNaN(value) ? value : undefined;
+}

package/forms/commandInputs.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { FormFieldPlacement } from '@cratis/scene.model';
+import { parseFormWidth } from '@cratis/scene.engine';
 import { arrayProperty, numberProperty, objectProperty, stringProperty } from '../properties';
 
 /** Exact, case-sensitive names from a generated command's propertyDescriptors. */
@@ -8,8 +10,7 @@ export interface CommandInput {
     property: string;
     type: 'string' | 'guid';
     label: string;
-    column?: number;
-    width?: string;
+    placement?: FormFieldPlacement;
 }
 
 /** An absent declaration selects legacy auto mode; a present but invalid declaration never does. */
@@ -27,7 +28,9 @@ export function commandInputs(properties: Record<string, unknown>): CommandInput
         seen.add(property);
         const column = numberProperty(input, 'column');
         const width = stringProperty(input, 'width');
-        inputs.push({ property, type: input.type, label, column, width });
+        inputs.push({ property, type: input.type, label, ...(column === undefined && width === undefined ? {} : {
+            placement: { field: property, row: inputs.length + 1, column: column ?? 1, ...(parseFormWidth(width) ? { width: parseFormWidth(width) } : {}) },
+        }) });
     }
     return inputs;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.components",
-    "version": "4.11.0",
+    "version": "4.12.0",
     "description": "The Cratis Components package: exposes @cratis/components' Arc-bound data, form and dialog composites as Scene components. Built on PrimeReact and Tailwind, and declares both as dependencies.",
     "keywords": [
         "cratis",
@@ -54,17 +54,17 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.11.0",
-        "@cratis/scene.model": "4.11.0",
-        "@cratis/scene.react": "4.11.0"
+        "@cratis/scene.engine": "4.12.0",
+        "@cratis/scene.model": "4.12.0",
+        "@cratis/scene.react": "4.12.0"
     },
     "devDependencies": {
         "@cratis/arc": "22.50.5",
         "@cratis/arc.react": "22.50.5",
         "@cratis/components": "4.25.0",
-        "@cratis/scene.engine": "4.11.0",
-        "@cratis/scene.model": "4.11.0",
-        "@cratis/scene.react": "4.11.0",
+        "@cratis/scene.engine": "4.12.0",
+        "@cratis/scene.model": "4.12.0",
+        "@cratis/scene.react": "4.12.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",