@cratis/scene.model 0.1.0

package/forms/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './Form';
+export * from './FormField';
+export * from './PopulateSource';
+export * from './PopulateViaQuery';
+export * from './PopulateFromItem';

package/index.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.
+
+export * from './common';
+export * from './sizeClasses';
+export * from './elements';
+export * from './layouts';
+export * from './forms';
+export * from './contributionPoints';
+export * from './profiles';
+export * from './packages';
+export * from './screens';
+export * from './starters';

package/layouts/Arrangement.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.
+
+/**
+ * How content is arranged: {@link FlowArrangement} (reflowing, computed per size class) or
+ * {@link FreeformArrangement}/{@link FreeformSlotArrangement} (one placement variant per size class). Used
+ * at two levels - a {@link Layout}'s own `arrangement` positions its named {@link Slot}s relative to each
+ * other (leaves reference a slot by name: {@link FlowSlotLeaf}/{@link SlotPlacement}), while a
+ * {@link Slot}'s own `arrangement` positions that slot's own filled content elements (leaves carry the
+ * element itself: {@link FlowLeaf}/{@link ElementPlacement}).
+ */
+export interface Arrangement {}

package/layouts/ElementPlacement.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '../elements';
+
+/**
+ * The absolute position and size of one element within a {@link FreeformVariant}.
+ */
+export interface ElementPlacement {
+    element: SceneElement;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export const ElementPlacementPropertyNames: (keyof ElementPlacement)[] = ['element', 'x', 'y', 'width', 'height'];

package/layouts/FlowArrangement.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Arrangement } from './Arrangement';
+import { FlowNode } from './FlowNode';
+import { FlowOverride } from './FlowOverride';
+
+/**
+ * Arranges a slot's content by reflowing it with the neutral `flow` primitives ({@link FlowRow},
+ * {@link FlowColumn}, {@link FlowGrid}, {@link FlowLeaf}), recomputed against the current size class
+ * rather than fixed per breakpoint. Deliberately not CSS-flavored — a renderer maps these primitives to
+ * whatever native layout mechanism it has (flexbox/grid in `Scene.React`, something else in a future
+ * native renderer).
+ */
+export interface FlowArrangement extends Arrangement {
+    root: FlowNode;
+
+    /**
+     * Replacements for `root` targeting specific width/height size classes - the most specific match
+     * wins (both dimensions targeted beats one), and the last declared wins among equally specific
+     * matches. `undefined` or empty when the tree never varies by size class.
+     */
+    overrides?: FlowOverride[];
+}
+
+export const FlowArrangementPropertyNames: (keyof FlowArrangement)[] = ['root', 'overrides'];

package/layouts/FlowColumn.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FlowContainer } from './FlowContainer';
+import { FlowContainerKind } from './FlowContainerKind';
+
+/**
+ * A {@link FlowContainer} that arranges its children vertically.
+ */
+export interface FlowColumn extends FlowContainer {
+    kind: FlowContainerKind.Column;
+}
+
+export const FlowColumnPropertyNames: (keyof FlowColumn)[] = ['kind'];

package/layouts/FlowContainer.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 { FlowContainerKind } from './FlowContainerKind';
+import { FlowNode } from './FlowNode';
+
+/**
+ * A {@link FlowNode} that arranges child nodes ({@link FlowRow}, {@link FlowColumn} or {@link FlowGrid}).
+ */
+export interface FlowContainer extends FlowNode {
+    gap: number;
+    children: FlowNode[];
+
+    /**
+     * Which way this container arranges its children. Narrowed to a single member by each concrete
+     * container, which is what makes them a discriminated union rather than three identical shapes.
+     */
+    kind: FlowContainerKind;
+}
+
+export const FlowContainerPropertyNames: (keyof FlowContainer)[] = ['gap', 'children', 'kind'];

package/layouts/FlowContainerKind.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.
+
+/**
+ * Which way a {@link FlowContainer} arranges its children.
+ *
+ * C# distinguishes `FlowRow` from `FlowColumn` by type, but this mirror cannot: interfaces with identical
+ * members are the same type, and there are no runtime types to test. A renderer walking an arrangement
+ * tree would have no way to tell a row from a column — which is the one thing it most needs to know. This
+ * carries that decision as data, so both stacks read it the same way.
+ */
+export enum FlowContainerKind {
+    Row = 'Row',
+    Column = 'Column',
+    Grid = 'Grid',
+}

package/layouts/FlowGrid.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.
+
+import { FlowContainer } from './FlowContainer';
+import { FlowContainerKind } from './FlowContainerKind';
+
+/**
+ * A {@link FlowContainer} that arranges its children in a grid.
+ */
+export interface FlowGrid extends FlowContainer {
+    kind: FlowContainerKind.Grid;
+    columns?: number;
+    rows?: number;
+}
+
+export const FlowGridPropertyNames: (keyof FlowGrid)[] = ['kind', 'columns', 'rows'];

package/layouts/FlowLeaf.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FlowNode } from './FlowNode';
+import { SceneElement } from '../elements';
+
+/**
+ * A {@link FlowNode} leaf that positions one of the slot's own content elements within the flow tree.
+ */
+export interface FlowLeaf extends FlowNode {
+    content: SceneElement;
+}
+
+export const FlowLeafPropertyNames: (keyof FlowLeaf)[] = ['content'];

package/layouts/FlowNode.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.
+
+/**
+ * A node in a {@link FlowArrangement}'s tree: a container ({@link FlowRow}, {@link FlowColumn},
+ * {@link FlowGrid}) or a leaf positioning one of the slot's own content elements ({@link FlowLeaf}).
+ */
+export interface FlowNode {
+    grow?: number;
+    span?: number;
+}
+
+export const FlowNodePropertyNames: (keyof FlowNode)[] = ['grow', 'span'];

package/layouts/FlowOverride.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 { WidthSizeClass, HeightSizeClass } from '../sizeClasses';
+import { FlowNode } from './FlowNode';
+
+/**
+ * Replaces a {@link FlowArrangement}'s root tree for a targeted width and/or height size class.
+ */
+export interface FlowOverride {
+    /** The width size class this override targets, or `undefined` to target any width. */
+    width?: WidthSizeClass;
+
+    /** The height size class this override targets, or `undefined` to target any height. */
+    height?: HeightSizeClass;
+
+    /** The replacement tree. */
+    root: FlowNode;
+}
+
+export const FlowOverridePropertyNames: (keyof FlowOverride)[] = ['width', 'height', 'root'];

package/layouts/FlowRow.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FlowContainer } from './FlowContainer';
+import { FlowContainerKind } from './FlowContainerKind';
+
+/**
+ * A {@link FlowContainer} that arranges its children horizontally.
+ */
+export interface FlowRow extends FlowContainer {
+    kind: FlowContainerKind.Row;
+}
+
+export const FlowRowPropertyNames: (keyof FlowRow)[] = ['kind'];

package/layouts/FlowSlotLeaf.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 { FlowNode } from './FlowNode';
+
+/**
+ * A {@link FlowNode} leaf that positions one of a {@link Layout}'s own named {@link Slot}s within its
+ * macro `arrangement` tree - the counterpart to {@link FlowLeaf}, which positions an element within a
+ * single slot's own content instead of positioning a slot within the layout.
+ */
+export interface FlowSlotLeaf extends FlowNode {
+    slotName: string;
+}
+
+export const FlowSlotLeafPropertyNames: (keyof FlowSlotLeaf)[] = ['slotName'];

package/layouts/FreeformArrangement.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 { Arrangement } from './Arrangement';
+import { FreeformVariant } from './FreeformVariant';
+
+/**
+ * Arranges a slot's content with one placement variant per size class — the Xcode-storyboard model.
+ * The same data/action/form contract is shared across every variant; only placement differs.
+ */
+export interface FreeformArrangement extends Arrangement {
+    variants: FreeformVariant[];
+}
+
+export const FreeformArrangementPropertyNames: (keyof FreeformArrangement)[] = ['variants'];

package/layouts/FreeformSlotArrangement.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Arrangement } from './Arrangement';
+import { FreeformSlotVariant } from './FreeformSlotVariant';
+
+/**
+ * Arranges a {@link Layout}'s own named {@link Slot}s with one placement variant per size class - the
+ * Xcode-storyboard model applied to the layout's slots themselves, rather than to the content of one slot
+ * (see {@link FreeformArrangement}). The same slot set is shared across every variant; only placement
+ * differs.
+ */
+export interface FreeformSlotArrangement extends Arrangement {
+    variants: FreeformSlotVariant[];
+}
+
+export const FreeformSlotArrangementPropertyNames: (keyof FreeformSlotArrangement)[] = ['variants'];

package/layouts/FreeformSlotVariant.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SizeClass } from '../sizeClasses';
+import { SlotPlacement } from './SlotPlacement';
+
+/**
+ * One placement variant of a {@link FreeformSlotArrangement}, targeting a specific size class - the
+ * counterpart to {@link FreeformVariant}, which places elements within a single slot instead of placing a
+ * layout's own slots. A size class with no matching variant is a compiler/engine warning, never a silent
+ * fallback, matching {@link FreeformVariant}.
+ */
+export interface FreeformSlotVariant {
+    sizeClass: SizeClass;
+    placements: SlotPlacement[];
+}
+
+export const FreeformSlotVariantPropertyNames: (keyof FreeformSlotVariant)[] = ['sizeClass', 'placements'];

package/layouts/FreeformVariant.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.
+
+import { SizeClass } from '../sizeClasses';
+import { ElementPlacement } from './ElementPlacement';
+
+/**
+ * One placement variant of a {@link FreeformArrangement}, targeting a specific size class. A size class
+ * with no matching variant is a compiler/engine warning, never a silent fallback.
+ */
+export interface FreeformVariant {
+    sizeClass: SizeClass;
+    placements: ElementPlacement[];
+}
+
+export const FreeformVariantPropertyNames: (keyof FreeformVariant)[] = ['sizeClass', 'placements'];

package/layouts/Layout.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Arrangement } from './Arrangement';
+import { Slot } from './Slot';
+
+/**
+ * A named template of slots that a {@link Screen} fills with content. Mirrors Screenplay's `layout`
+ * construct: a bare layout with plain slots is a special case of a layout whose slots all use the
+ * default arrangement.
+ */
+export interface Layout {
+    name: string;
+    slots: Slot[];
+
+    /**
+     * How the layout's own `slots` position relative to each other - a {@link FlowArrangement} (leaves
+     * are {@link FlowSlotLeaf}) or {@link FreeformSlotArrangement}, or `undefined` for the slots'
+     * declaration order with no further positioning information. Distinct from each {@link Slot}'s own
+     * `arrangement`, which positions that one slot's filled content instead of positioning the slots
+     * themselves.
+     */
+    arrangement?: Arrangement;
+}
+
+export const LayoutPropertyNames: (keyof Layout)[] = ['name', 'slots', 'arrangement'];

package/layouts/Slot.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.
+
+import { Arrangement } from './Arrangement';
+
+/**
+ * A named placeholder within a {@link Layout}, filled with content by a screen and positioned by its
+ * {@link Arrangement}. A layout is not uniformly one arrangement mode — `flow` for most slots and
+ * `freeform` for one is a valid combination.
+ */
+export interface Slot {
+    name: string;
+    arrangement?: Arrangement;
+}
+
+export const SlotPropertyNames: (keyof Slot)[] = ['name', 'arrangement'];

package/layouts/SlotPlacement.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The absolute position and size of one of a {@link Layout}'s own named {@link Slot}s within a
+ * {@link FreeformSlotVariant} - the counterpart to {@link ElementPlacement}, which places an element
+ * within a single slot's own content instead of placing a slot within the layout.
+ */
+export interface SlotPlacement {
+    slotName: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export const SlotPlacementPropertyNames: (keyof SlotPlacement)[] = ['slotName', 'x', 'y', 'width', 'height'];

package/layouts/index.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.
+
+export * from './Layout';
+export * from './Slot';
+export * from './Arrangement';
+export * from './FlowArrangement';
+export * from './FlowOverride';
+export * from './FlowNode';
+export * from './FlowContainer';
+export * from './FlowContainerKind';
+export * from './FlowRow';
+export * from './FlowColumn';
+export * from './FlowGrid';
+export * from './FlowLeaf';
+export * from './FlowSlotLeaf';
+export * from './FreeformArrangement';
+export * from './FreeformVariant';
+export * from './ElementPlacement';
+export * from './FreeformSlotArrangement';
+export * from './FreeformSlotVariant';
+export * from './SlotPlacement';

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@cratis/scene.model",
+    "version": "0.1.0",
+    "description": "The TypeScript mirror of Cratis.Scene.Model — the platform-agnostic Screen object model.",
+    "author": "Cratis",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cratis/Scene.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "**/*.ts"
+    ],
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/esm/index.d.ts",
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn g:build",
+        "clean": "yarn g:clean",
+        "build": "yarn g:build",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "ci": "yarn g:ci",
+        "up": "yarn g:up"
+    }
+}

package/packages/PackageDependency.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.
+
+/**
+ * One package a {@link ScenePackage} needs present in the same {@link UiProfile} to work.
+ * `@cratis/components` is written against PrimeReact and Tailwind, so it declares both - a profile
+ * listing it without them is stating something that cannot render, and that has to be visible rather
+ * than discovered at runtime.
+ */
+export interface PackageDependency {
+    /**
+     * The name of the package depended on, matching that package's `name`.
+     */
+    name: string;
+
+    /**
+     * An optional semver range the dependency must satisfy. Left undefined when any version will do -
+     * which is the common case, since a profile only ever activates one version of a package.
+     */
+    versionRange?: string;
+}
+
+export const PackageDependencyPropertyNames: (keyof PackageDependency)[] = ['name', 'versionRange'];

package/packages/PackageKind.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a {@link ScenePackage} contributes to a {@link UiProfile}. A profile's package list mixes all
+ * three kinds freely - the kind says what a package is for, never where it sits in the override-priority
+ * order.
+ */
+export enum PackageKind {
+    /**
+     * Declares component names a screen can resolve against. A package with no dependency on another
+     * `ComponentLibrary` is a base library (PrimeReact, `core`); one that depends on another layers on
+     * top of it.
+     */
+    ComponentLibrary = 'ComponentLibrary',
+
+    /**
+     * Contributes styling rather than components - a utility CSS system such as Tailwind. A styling
+     * package usually declares no components at all; component libraries depend on it to say "my
+     * components are written against this styling system".
+     */
+    Styling = 'Styling',
+
+    /**
+     * Provides the shape of an application: its {@link Layout}s, the {@link ScreenTemplate}s and
+     * {@link DialogTemplate}s built on them, and the components that fill their slots. An application
+     * selects one blueprint, and gets a coherent set rather than assembling layouts and templates from
+     * unrelated sources.
+     *
+     * A blueprint depends on the component libraries it is built from — the default blueprint is written
+     * against PrimeReact and Cratis Components, and says so. That is what makes "which blueprints can I
+     * use" answerable from the packages a profile already has.
+     */
+    Blueprint = 'Blueprint',
+}

package/packages/ScenePackage.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageDependency } from './PackageDependency';
+import { PackageKind } from './PackageKind';
+
+/**
+ * What a {@link UiProfile}'s `packages` entry actually names. A profile lists packages by name only;
+ * this is the declaration behind the name - what it contributes, and what else has to be active for it
+ * to work.
+ */
+export interface ScenePackage {
+    /**
+     * The name a {@link UiProfile} lists, and the name a {@link PackageDependency} refers to.
+     */
+    name: string;
+
+    /**
+     * The package's own version, so a {@link PackageDependency.versionRange} has something to check against.
+     */
+    version: string;
+
+    /**
+     * What the package contributes.
+     */
+    kind: PackageKind;
+
+    /**
+     * Other packages that must be active in the same profile for this one to work.
+     */
+    dependencies: PackageDependency[];
+
+    /**
+     * The component names this package declares - the catalog entry {@link UiProfile} resolution walks.
+     */
+    components: string[];
+
+    /**
+     * The names of the {@link Layout}s this package provides — an application's base navigational shells.
+     * Empty for anything that is not a {@link PackageKind.Blueprint}.
+     */
+    layouts: string[];
+
+    /**
+     * The names of the {@link ScreenTemplate}s this package provides — the shapes that go inside a layout,
+     * at module, feature and slice level.
+     */
+    screenTemplates: string[];
+
+    /**
+     * The names of the {@link DialogTemplate}s this package provides.
+     */
+    dialogTemplates: string[];
+
+    /**
+     * The names of the {@link Theme}s this package ships, empty for a package that ships none.
+     */
+    themes: string[];
+
+    /**
+     * A human-readable name for a package picker, falling back to `name` when absent.
+     */
+    displayName?: string;
+
+    /**
+     * A one-line description for a package picker.
+     */
+    description?: string;
+
+    /**
+     * The module that implements the package - an npm package name for a web renderer. Design-time
+     * tooling needs it to know what to import; the model itself never loads anything.
+     */
+    module?: string;
+}
+
+export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
+    'name',
+    'version',
+    'kind',
+    'dependencies',
+    'components',
+    'layouts',
+    'screenTemplates',
+    'dialogTemplates',
+    'themes',
+    'displayName',
+    'description',
+    'module',
+];

package/packages/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './PackageKind';
+export * from './PackageDependency';
+export * from './ScenePackage';