@cratis/scene.model 4.38.0 → 4.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.model",
-    "version": "4.38.0",
+    "version": "4.40.0",
     "description": "The TypeScript mirror of Cratis.Scene.Model — the platform-agnostic Screen object model.",
     "keywords": [
         "cratis",

package/packages/BlueprintMetadata.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BlueprintScreen } from './BlueprintScreen';
+
+/**
+ * What a domain blueprint declares about itself beyond what every package does: the business domain it serves, how it
+ * is described in a gallery, and the ready-to-use screens it brings with their navigation.
+ *
+ * A blueprint's own version is {@link ScenePackage.version}: there is deliberately no second version here to drift from
+ * it. That version is what a template reference pins (`TemplateReference.version`) and what "update available" compares.
+ * Its sample-data packs are {@link ScenePackage.sampleData}; {@link BlueprintMetadata.defaultSampleData} chooses among them.
+ */
+export interface BlueprintMetadata {
+    /** The business domain, as a lower-case slug (`crm`, `project-tracker`). Templates of the blueprint are categorised under `Business / <domain>`. */
+    domain: string;
+
+    /** One sentence, up to 200 characters, saying what the blueprint gives an application. Shown under the thumbnail in a gallery. */
+    description: string;
+
+    /** The package-relative path of the gallery thumbnail, `thumbnails/<name>.png`, `.webp`, `.jpg` or `.svg`. It is design-time only and never part of a runtime bundle. */
+    thumbnail: string;
+
+    /** The ready-to-use screens, in navigation order. */
+    screenSet: BlueprintScreen[];
+
+    /** The id of the sample-data pack a gallery preview and a new application start with; one of the package's `sampleData` ids. Required when the package ships more than one. */
+    defaultSampleData?: string;
+}
+
+export const BlueprintMetadataPropertyNames: (keyof BlueprintMetadata)[] = ['domain', 'description', 'thumbnail', 'screenSet', 'defaultSampleData'];

package/packages/BlueprintScreen.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconReference } from '../icons';
+
+/**
+ * One screen of a domain blueprint's ready-to-use screen set, with where it sits in the navigation the blueprint
+ * brings. The screen itself (its layout, template and content) is a `Screen` the package provides under the same
+ * name; this is the part a gallery and a navigation builder need without loading it.
+ */
+export interface BlueprintScreen {
+    /** The name of the {@link Screen} the package provides. Unique within the screen set. */
+    name: string;
+
+    /** The title shown in the navigation and in the gallery. */
+    title: string;
+
+    /** One sentence saying what the screen is for. */
+    description?: string;
+
+    /** The name of the screen template the screen is built from, when it is built from one. */
+    template?: string;
+
+    /** The name of the screen this one sits under in the navigation; absent for a top-level screen. */
+    parent?: string;
+
+    /** Where the screen sits among its siblings; lower comes first, and screens without an order keep the order they are written in. */
+    order?: number;
+
+    /** The icon beside the title in the navigation. */
+    icon?: IconReference;
+}
+
+export const BlueprintScreenPropertyNames: (keyof BlueprintScreen)[] = ['name', 'title', 'description', 'template', 'parent', 'order', 'icon'];

package/packages/ScenePackage.ts

@@ -5,6 +5,7 @@ import { PackageDesignTimeMetadata } from '../descriptors';
 import { IconLibrary } from '../icons';
 import { PackageDependency } from './PackageDependency';
 import { SampleDataPackReference } from '../sampleData';
+import { BlueprintMetadata } from './BlueprintMetadata';
 import { PackageKind } from './PackageKind';
 
 /**
@@ -109,6 +110,13 @@ export interface ScenePackage {
      * Stage production build never includes or resolves them.
      */
     sampleData?: SampleDataPackReference[];
+
+    /**
+     * What a domain blueprint declares about itself: its domain, gallery description and thumbnail, and its ready-to-use
+     * screen set. Present for a domain {@link PackageKind.Blueprint}; a blueprint that only provides foundation layouts
+     * and templates has none.
+     */
+    blueprint?: BlueprintMetadata;
 }
 
 export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
@@ -131,4 +139,5 @@ export const ScenePackagePropertyNames: (keyof ScenePackage)[] = [
     'assets',
     'runtimeSingletons',
     'sampleData',
+    'blueprint',
 ];

package/packages/index.ts

@@ -4,3 +4,5 @@
 export * from './PackageKind';
 export * from './PackageDependency';
 export * from './ScenePackage';
+export * from './BlueprintScreen';
+export * from './BlueprintMetadata';

package/screens/TemplateMetadata.ts

@@ -39,8 +39,11 @@ export interface TemplateMetadata {
      * presents something. Declaring slice kinds without scopes makes the default scope Slice.
      */
     sliceKinds?: SliceKind[];
+
+    /** The package-relative path of the template's gallery thumbnail (`thumbnails/<name>.png|webp|jpg|svg`); required of every template of a domain blueprint. */
+    thumbnail?: string;
 }
 
 export const TemplateMetadataPropertyNames: (keyof TemplateMetadata)[] = [
-    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl', 'sliceKinds',
+    'type', 'category', 'scopes', 'compatibility', 'attribution', 'license', 'licenseUrl', 'sliceKinds', 'thumbnail',
 ];