@cratis/scene.react 2.0.0 → 3.0.0

package/for_panelLayout/when_arranging_a_panel.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ColumnDefinition, Dock, DockPanel, Grid, GridUnitType, HorizontalAlignment, Orientation, RowDefinition, SceneElement, StackPanel, VerticalAlignment, Visibility, WrapPanel } from '@cratis/scene.model';
+import { childStyle, panelStyle } from '../renderer/panelLayout';
+
+const base = {
+    id: 'panel',
+    properties: {},
+    visibility: Visibility.Visible,
+    isEnabled: true,
+    opacity: 1,
+    zIndex: 0,
+    size: {},
+    name: 'panel',
+    minimumSize: {},
+    maximumSize: {},
+    margin: { left: 0, top: 0, right: 0, bottom: 0 },
+    horizontalAlignment: HorizontalAlignment.Stretch,
+    verticalAlignment: VerticalAlignment.Stretch,
+    children: [] as SceneElement[],
+};
+
+const child = (properties: Record<string, unknown> = {}): SceneElement => ({ id: 'child', properties });
+
+const star = (value: number): RowDefinition['height'] => ({ value, unitType: GridUnitType.Star });
+const row = (over: Partial<RowDefinition> = {}): RowDefinition => ({ height: star(1), minimumHeight: 0, maximumHeight: Number.POSITIVE_INFINITY, ...over });
+const column = (over: Partial<ColumnDefinition> = {}): ColumnDefinition => ({ width: star(1), minimumWidth: 0, maximumWidth: Number.POSITIVE_INFINITY, ...over });
+
+describe('when arranging a panel', () => {
+    it('should lay a stack panel out along its orientation', () => {
+        const panel: StackPanel = { ...base, orientation: Orientation.Horizontal, spacing: 8 };
+        panelStyle(panel)!.flexDirection!.should.equal('row');
+    });
+
+    it('should space a stack panel by its spacing', () => {
+        const panel: StackPanel = { ...base, orientation: Orientation.Vertical, spacing: 12 };
+        panelStyle(panel)!.gap!.should.equal('12px');
+    });
+
+    it('should wrap a wrap panel', () => {
+        const panel: WrapPanel = { ...base, orientation: Orientation.Horizontal };
+        panelStyle(panel)!.flexWrap!.should.equal('wrap');
+    });
+
+    it('should turn star tracks into fractions', () => {
+        const panel: Grid = { ...base, rows: [row(), row({ height: star(2) })], columns: [] };
+        panelStyle(panel)!.gridTemplateRows!.should.equal('1fr 2fr');
+    });
+
+    it('should turn an absolute track into pixels', () => {
+        const panel: Grid = { ...base, rows: [], columns: [column({ width: { value: 240, unitType: GridUnitType.Absolute } })] };
+        panelStyle(panel)!.gridTemplateColumns!.should.equal('240px');
+    });
+
+    it('should turn a content-sized track into auto', () => {
+        const panel: Grid = { ...base, rows: [], columns: [column({ width: { value: 0, unitType: GridUnitType.Auto } })] };
+        panelStyle(panel)!.gridTemplateColumns!.should.equal('auto');
+    });
+
+    it('should bound a track that states a minimum', () => {
+        const panel: Grid = { ...base, rows: [row({ minimumHeight: 40 })], columns: [] };
+        panelStyle(panel)!.gridTemplateRows!.should.equal('minmax(40px, 1fr)');
+    });
+
+    it('should leave a plain panel unstyled', () => (panelStyle({ ...base }) === undefined).should.be.true);
+});
+
+describe('when placing a child in a panel', () => {
+    it('should place a grid child in the cell it names, one-based for CSS', () => {
+        const panel: Grid = { ...base, rows: [row()], columns: [column()] };
+        childStyle(panel, child({ 'Grid.Row': 1, 'Grid.Column': 2 }), 0)!.gridRow!.should.equal('2 / span 1');
+    });
+
+    it('should span a grid child that asks for it', () => {
+        const panel: Grid = { ...base, rows: [row()], columns: [column()] };
+        childStyle(panel, child({ 'Grid.Column': 0, 'Grid.ColumnSpan': 3 }), 0)!.gridColumn!.should.equal('1 / span 3');
+    });
+
+    it('should leave a grid child that names no cell to the implicit flow', () => {
+        const panel: Grid = { ...base, rows: [row()], columns: [column()] };
+        (childStyle(panel, child(), 0) === undefined).should.be.true;
+    });
+
+    it('should let a dock panel last child fill what is left', () => {
+        const kid = child();
+        const panel: DockPanel = { ...base, lastChildFill: true, children: [kid] };
+        childStyle(panel, kid, 0)!.flex!.should.equal('1 1 auto');
+    });
+
+    it('should keep a docked child at its natural size', () => {
+        const first = child({ Dock: Dock.Top });
+        const panel: DockPanel = { ...base, lastChildFill: true, children: [first, child()] };
+        childStyle(panel, first, 0)!.flex!.should.equal('0 0 auto');
+    });
+
+    it('should not let the last child fill when the panel says not to', () => {
+        const kid = child();
+        const panel: DockPanel = { ...base, lastChildFill: false, children: [kid] };
+        childStyle(panel, kid, 0)!.flex!.should.equal('0 0 auto');
+    });
+
+    it('should size wrap panel children when the panel sizes them', () => {
+        const panel: WrapPanel = { ...base, orientation: Orientation.Horizontal, itemWidth: 120 };
+        childStyle(panel, child(), 0)!.width!.should.equal(120);
+    });
+
+    it('should leave wrap panel children their own size when the panel sizes neither axis', () => {
+        const panel: WrapPanel = { ...base, orientation: Orientation.Horizontal };
+        (childStyle(panel, child(), 0) === undefined).should.be.true;
+    });
+});

package/package.json

@@ -1,7 +1,17 @@
 {
     "name": "@cratis/scene.react",
-    "version": "2.0.0",
+    "version": "3.0.0",
     "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
+    "keywords": [
+        "cratis",
+        "scene",
+        "react",
+        "ui",
+        "renderer",
+        "event-modeling",
+        "cqrs",
+        "low-code"
+    ],
     "author": "Cratis",
     "license": "MIT",
     "repository": {
@@ -40,12 +50,12 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "2.0.0",
-        "@cratis/scene.model": "2.0.0"
+        "@cratis/scene.engine": "3.0.0",
+        "@cratis/scene.model": "3.0.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "2.0.0",
-        "@cratis/scene.model": "2.0.0",
+        "@cratis/scene.engine": "3.0.0",
+        "@cratis/scene.model": "3.0.0",
         "@storybook/addon-links": "^10.4.1",
         "@storybook/react": "^10.4.1",
         "@storybook/react-vite": "^10.4.1",

package/renderer/createReactRenderer.tsx

@@ -5,13 +5,16 @@ import { ReactNode, createElement } from 'react';
 import { Renderer } from '@cratis/scene.engine';
 import { ContentControl, ExternalComponent, ItemsControl, Panel } from '@cratis/scene.model';
 import { ComponentRegistry } from './ComponentRegistry';
+import { childStyle, panelStyle } from './panelLayout';
 import { UnresolvedComponent } from './UnresolvedComponent';
 
 /**
- * Creates a {@link Renderer} that turns a Scene element tree into React elements. `Panel`, `ItemsControl`
- * and `ContentControl` render as plain wrapping `div`s here - arranging them according to a layout's
- * `flow`/`freeform` arrangement is Scene#4's job, layered on top of this renderer rather than folded
- * into it.
+ * Creates a {@link Renderer} that turns a Scene element tree into React elements.
+ *
+ * `ItemsControl` and `ContentControl` render as plain wrapping `div`s. A `Panel` renders as the
+ * arrangement it declares - a grid, a stack, a wrap or a dock - because that is what those panels are
+ * for; see `panelLayout` for the mapping. Arranging a *layout's slots* by `flow`/`freeform` is a
+ * different thing and stays Scene#4's, layered on top of this renderer rather than folded into it.
  */
 export function createReactRenderer(registry: ComponentRegistry): Renderer<ReactNode> {
     return {
@@ -29,7 +32,20 @@ export function createReactRenderer(registry: ComponentRegistry): Renderer<React
         },
 
         renderPanel(element: Panel, children: ReactNode[]): ReactNode {
-            return createElement('div', { key: element.id, 'data-scene-id': element.id, 'data-scene-kind': 'Panel' }, children);
+            // The rendered children arrive in the same order as `element.children`, so a panel that places
+            // its children individually - a grid cell, a docked edge - can wrap each one in the box that
+            // places it without needing to re-render anything.
+            const placed = children.map((child, index) => {
+                const style = childStyle(element, element.children[index], index);
+                return style
+                    ? createElement('div', { key: `${element.id}-${index}`, 'data-scene-placement': index, style }, child)
+                    : child;
+            });
+
+            return createElement(
+                'div',
+                { key: element.id, 'data-scene-id': element.id, 'data-scene-kind': 'Panel', style: panelStyle(element) },
+                placed);
         },
     };
 }

package/renderer/panelLayout.ts

@@ -0,0 +1,109 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { CSSProperties } from 'react';
+import { isDockPanel, isGrid, isStackPanel, isWrapPanel } from '@cratis/scene.engine';
+import { Dock, GridUnitType, Orientation } from '@cratis/scene.model';
+import type { ColumnDefinition, GridLength, Panel, RowDefinition, SceneElement } from '@cratis/scene.model';
+
+/**
+ * Turns a panel into the CSS that arranges it, and a child into the CSS that places it inside one.
+ *
+ * The panels say what an arrangement *is*; this says what it looks like on the web. A second renderer -
+ * native, desktop - answers the same question with its own platform's layout primitives, which is why
+ * this lives in `Scene.React` rather than in the model or the engine.
+ *
+ * Where a panel needs to say something about an individual child - which grid cell, which edge - it does
+ * so through that child's own `properties` bag, because the model has no attached properties of its own.
+ * The keys are the ones the model's documentation names: `Grid.Row`, `Grid.Column`, `Grid.RowSpan`,
+ * `Grid.ColumnSpan` and `Dock`.
+ */
+
+const track = (length: GridLength): string => {
+    switch (length.unitType) {
+        case GridUnitType.Auto: return 'auto';
+        case GridUnitType.Absolute: return `${length.value}px`;
+        case GridUnitType.Star: return `${length.value}fr`;
+    }
+};
+
+const bound = (minimum: number, maximum: number, size: string): string =>
+    minimum === 0 && !Number.isFinite(maximum)
+        ? size
+        : `minmax(${minimum}px, ${Number.isFinite(maximum) ? `${maximum}px` : size})`;
+
+const rowTrack = (row: RowDefinition): string => bound(row.minimumHeight, row.maximumHeight, track(row.height));
+const columnTrack = (column: ColumnDefinition): string => bound(column.minimumWidth, column.maximumWidth, track(column.width));
+
+const number = (value: unknown): number | undefined => (typeof value === 'number' ? value : undefined);
+
+/** The CSS that arranges a panel's own children. */
+export function panelStyle(panel: Panel): CSSProperties | undefined {
+    if (isGrid(panel)) {
+        return {
+            display: 'grid',
+            gridTemplateRows: panel.rows.map(rowTrack).join(' ') || undefined,
+            gridTemplateColumns: panel.columns.map(columnTrack).join(' ') || undefined,
+        };
+    }
+
+    if (isDockPanel(panel)) {
+        // Docking has no single CSS primitive. A column of rows with a middle that grows is the shape a
+        // dock panel actually produces, and `lastChildFill` decides whether the final child is that
+        // middle or just another docked edge.
+        return { display: 'flex', flexDirection: 'column' };
+    }
+
+    if (isStackPanel(panel)) {
+        return {
+            display: 'flex',
+            flexDirection: panel.orientation === Orientation.Horizontal ? 'row' : 'column',
+            gap: panel.spacing ? `${panel.spacing}px` : undefined,
+        };
+    }
+
+    if (isWrapPanel(panel)) {
+        return {
+            display: 'flex',
+            flexWrap: 'wrap',
+            flexDirection: panel.orientation === Orientation.Horizontal ? 'row' : 'column',
+        };
+    }
+
+    return undefined;
+}
+
+/** The CSS that places one child within its panel, or `undefined` when the panel places children implicitly. */
+export function childStyle(panel: Panel, child: SceneElement, index: number): CSSProperties | undefined {
+    const properties = child.properties ?? {};
+
+    if (isGrid(panel)) {
+        const row = number(properties['Grid.Row']);
+        const column = number(properties['Grid.Column']);
+        const rowSpan = number(properties['Grid.RowSpan']) ?? 1;
+        const columnSpan = number(properties['Grid.ColumnSpan']) ?? 1;
+        if (row === undefined && column === undefined) return undefined;
+        return {
+            gridRow: row === undefined ? undefined : `${row + 1} / span ${rowSpan}`,
+            gridColumn: column === undefined ? undefined : `${column + 1} / span ${columnSpan}`,
+        };
+    }
+
+    if (isDockPanel(panel)) {
+        const dock = properties['Dock'] as Dock | undefined;
+        const isFill = panel.lastChildFill && index === (panel.children?.length ?? 0) - 1;
+        if (isFill) return { flex: '1 1 auto', minHeight: 0 };
+        // Left and right dock along the cross axis of the column the panel lays out, so they become a row
+        // of their own rather than a sibling in the column.
+        return dock === Dock.Left || dock === Dock.Right
+            ? { alignSelf: dock === Dock.Left ? 'flex-start' : 'flex-end', flex: '0 0 auto' }
+            : { flex: '0 0 auto' };
+    }
+
+    if (isWrapPanel(panel)) {
+        if (panel.itemWidth === undefined && panel.itemHeight === undefined) return undefined;
+        return { width: panel.itemWidth, height: panel.itemHeight, flex: '0 0 auto' };
+    }
+
+    return undefined;
+}