@cratis/scene.model 0.1.0

package/profiles/Theme.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * A named token/styling layer, declaring which component packages it is known to work with. An
+ * incompatible theme/package pairing is a warning, not an error — the theme might still work by
+ * coincidence, but the gap must be visible.
+ */
+export interface Theme {
+    /**
+     * The theme's name.
+     */
+    name: string;
+
+    /**
+     * The component packages this theme is declared compatible with.
+     */
+    compatibleWith: string[];
+
+    /**
+     * The theme's design tokens, keyed by semantic name (`primary.color`, `surface.background`,
+     * `content.borderColor`, ...). Deliberately semantic rather than CSS: a renderer decides how a token
+     * becomes a custom property, a native style, or anything else. Absent for a theme a package applies
+     * by its own means rather than through tokens.
+     */
+    tokens?: Record<string, string>;
+
+    /**
+     * Whether the theme is a dark scheme, so a picker can group and preview it correctly.
+     */
+    isDark?: boolean;
+
+    /**
+     * Who created the theme. A theme adopted from somewhere else — PrimeTek's free presets, a community
+     * theme — must credit its original creator here rather than appear to be ours.
+     */
+    author?: string;
+
+    /**
+     * A link to the original creator or the theme's home, shown alongside `author`.
+     */
+    authorUrl?: string;
+
+    /**
+     * The license the theme is used under, so redistributing it stays honest.
+     */
+    license?: string;
+
+    /**
+     * A one-line description for a theme picker.
+     */
+    description?: string;
+}
+
+export const ThemePropertyNames: (keyof Theme)[] = [
+    'name',
+    'compatibleWith',
+    'tokens',
+    'isDark',
+    'author',
+    'authorUrl',
+    'license',
+    'description',
+];

package/profiles/UiProfile.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 { SizeClass } from '../sizeClasses';
+
+/**
+ * A named target: a platform, a default size class, and an ordered list of component packages.
+ * Declaration order in `packages` is override priority — a later package shadows an earlier one when
+ * both resolve the same bare component name. `core` is always the final fallback, so a minimum
+ * vocabulary resolves regardless of which packages a profile lists.
+ */
+export interface UiProfile {
+    name: string;
+    targetPlatform: string;
+    packages: string[];
+    defaultSizeClass?: SizeClass;
+}
+
+export const UiProfilePropertyNames: (keyof UiProfile)[] = ['name', 'targetPlatform', 'packages', 'defaultSizeClass'];

package/profiles/index.ts

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

package/screens/DialogTemplate.ts

@@ -0,0 +1,57 @@
+// 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';
+import { Arrangement, Slot } from '../layouts';
+
+/**
+ * A reusable dialog structure — the same idea as a {@link ScreenTemplate}, for content that opens over an
+ * application rather than sitting inside it.
+ *
+ * A dialog has no `fitsSlot` because it occupies no slot: it is an overlay, summoned by something rather
+ * than placed by a containing layout. Everything else is the same, which is deliberate — a confirmation
+ * dialog and a detail screen are both "slots with an arrangement, filled with content", and there is no
+ * reason for an author to learn that twice.
+ */
+export interface DialogTemplate {
+    /**
+     * The template's name.
+     */
+    name: string;
+
+    /**
+     * The slots this template offers to whatever it contains, in declaration order.
+     */
+    slots: Slot[];
+
+    /**
+     * How this template's own `slots` position relative to each other. Absent for declaration order with
+     * no further positioning.
+     */
+    arrangement?: Arrangement;
+
+    /**
+     * Content the template itself provides, keyed by slot name — a dialog's own chrome, such as its header
+     * and button bar.
+     */
+    content?: Record<string, SceneElement[]>;
+
+    /**
+     * A human-readable name for a template picker, falling back to `name`.
+     */
+    displayName?: string;
+
+    /**
+     * A one-line description for a template picker.
+     */
+    description?: string;
+}
+
+export const DialogTemplatePropertyNames: (keyof DialogTemplate)[] = [
+    'name',
+    'slots',
+    'arrangement',
+    'content',
+    'displayName',
+    'description',
+];

package/screens/Screen.ts

@@ -0,0 +1,50 @@
+// 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';
+import { Form } from '../forms';
+import { Contribution } from '../contributionPoints';
+
+/**
+ * A named screen: the structure it fills, the content that fills it, the forms it hosts, and whatever it
+ * contributes to contribution points elsewhere in the tree.
+ *
+ * A screen is an instance, not a shape. The shape comes from either the application's {@link Layout} — for
+ * a screen that sits directly in the application shell — or a {@link ScreenTemplate}, for one nested
+ * inside a module, feature or slice. Both declare slots; a screen only ever fills them.
+ */
+export interface Screen {
+    /**
+     * The screen's name.
+     */
+    name: string;
+
+    /**
+     * The resolved name of the application {@link Layout} this screen ultimately renders inside.
+     */
+    layout: string;
+
+    /**
+     * The content filling each slot, keyed by slot name.
+     */
+    slotContent: Record<string, SceneElement[]>;
+
+    /**
+     * The forms this screen hosts.
+     */
+    forms: Form[];
+
+    /**
+     * What this screen contributes to contribution points elsewhere in the tree.
+     */
+    contributions: Contribution[];
+
+    /**
+     * The resolved name of the {@link ScreenTemplate} this screen fills, or undefined when it fills the
+     * `layout`'s own slots directly. The template's `fitsSlot` is what decides where it lands, so a screen
+     * never has to state its own position.
+     */
+    screenTemplate?: string;
+}
+
+export const ScreenPropertyNames: (keyof Screen)[] = ['name', 'layout', 'slotContent', 'forms', 'contributions', 'screenTemplate'];

package/screens/ScreenTemplate.ts

@@ -0,0 +1,70 @@
+// 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';
+import { Arrangement, Slot } from '../layouts';
+
+/**
+ * A reusable screen structure that fills a named slot on whatever contains it, and offers slots of its
+ * own for what it contains in turn.
+ *
+ * A {@link Layout} and a screen template are deliberately different things. A layout is the application's
+ * base navigational look — the shell with its top bar, navigation and content region — and an application
+ * has one. A screen template is what goes *inside* that shell, and an application has many: one per
+ * module, feature or slice that needs a shape of its own.
+ *
+ * `fitsSlot` is what makes them compose. A module's screen template fits the application layout's content
+ * slot; a feature's screen template fits a slot the module's template declares; a slice's fits one the
+ * feature's declares. The same rule at every level, so nesting is arbitrarily deep without a second
+ * mechanism — and a template always states where it belongs rather than being told by whatever happens to
+ * host it.
+ */
+export interface ScreenTemplate {
+    /**
+     * The template's name, which a {@link Screen} refers to.
+     */
+    name: string;
+
+    /**
+     * The name of the slot on the containing {@link Layout} or screen template this one fills, or
+     * undefined for a template that is placed explicitly rather than by declaration.
+     */
+    fitsSlot?: string;
+
+    /**
+     * The slots this template offers to whatever it contains, in declaration order.
+     */
+    slots: Slot[];
+
+    /**
+     * How this template's own `slots` position relative to each other — the same shape a {@link Layout}
+     * uses, evaluated by the same engine. Absent for declaration order with no further positioning.
+     */
+    arrangement?: Arrangement;
+
+    /**
+     * Content the template itself provides, keyed by slot name — the chrome a template brings with it, as
+     * opposed to what a {@link Screen} based on it fills in.
+     */
+    content?: Record<string, SceneElement[]>;
+
+    /**
+     * A human-readable name for a template picker, falling back to `name`.
+     */
+    displayName?: string;
+
+    /**
+     * A one-line description for a template picker.
+     */
+    description?: string;
+}
+
+export const ScreenTemplatePropertyNames: (keyof ScreenTemplate)[] = [
+    'name',
+    'fitsSlot',
+    'slots',
+    'arrangement',
+    'content',
+    'displayName',
+    'description',
+];

package/screens/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 './Screen';
+export * from './ScreenTemplate';
+export * from './DialogTemplate';

package/sizeClasses/HeightSizeClass.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 height axis of a {@link SizeClass}.
+ */
+export enum HeightSizeClass {
+    Compact = 'Compact',
+    Regular = 'Regular',
+}

package/sizeClasses/SizeClass.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 { WidthSizeClass } from './WidthSizeClass';
+import { HeightSizeClass } from './HeightSizeClass';
+
+/**
+ * A width x height size class, UIKit-style. Phone portrait/landscape, tablet and desktop all fall out
+ * of this matrix — there is deliberately no separate orientation concept.
+ */
+export interface SizeClass {
+    width: WidthSizeClass;
+    height: HeightSizeClass;
+}
+
+export const SizeClassPropertyNames: (keyof SizeClass)[] = ['width', 'height'];

package/sizeClasses/WidthSizeClass.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 width axis of a {@link SizeClass}.
+ */
+export enum WidthSizeClass {
+    Compact = 'Compact',
+    Regular = 'Regular',
+}

package/sizeClasses/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 './WidthSizeClass';
+export * from './HeightSizeClass';
+export * from './SizeClass';

package/starters/UiStarter.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.
+
+/**
+ * A packaged, versioned UI starting point: a package list, the themes it ships compatible with, and a
+ * gallery of ordinary screens shipped alongside it - part of Cratis/Scene#6. A starter is data, not a
+ * `.play` language construct; Studio's "new project" flow scaffolds from it, and its gallery boots
+ * through the real `Scene.Engine` + `Scene.React` inside a sandboxed `UiProfile` built from `packages` -
+ * there is no separate preview pipeline and no mocked screens.
+ */
+export interface UiStarter {
+    name: string;
+    packages: string[];
+    themes: string[];
+    gallery: string[];
+}
+
+export const UiStarterPropertyNames: (keyof UiStarter)[] = ['name', 'packages', 'themes', 'gallery'];

package/starters/index.ts

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