@cratis/scene.engine 4.23.0 → 4.25.0

package/index.ts

@@ -19,6 +19,7 @@ export * from './panelKind';
 export * from './flowNodeKind';
 export * from './ComponentResolution';
 export * from './icons';
+export * from './descriptors';
 export * from './resolveComponentName';
 export * from './computeSizeClass';
 export * from './evaluateFlowArrangement';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.23.0",
+    "version": "4.25.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.23.0"
+        "@cratis/scene.model": "4.25.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.23.0"
+        "@cratis/scene.model": "4.25.0"
     }
 }

package/templateApplicability.ts

@@ -4,7 +4,8 @@
 import { DialogTemplate, Layout, ScreenTemplate, TemplateMetadata, TemplateScope } from '@cratis/scene.model';
 
 type TemplateKind = 'Layout' | 'ScreenTemplate' | 'DialogTemplate';
-type TemplateContainer = Pick<Layout, 'name' | 'slots'>;
+/** The containing layout or screen template against which a fitsSlot selection is checked. */
+export type TemplateContainer = Pick<Layout, 'name' | 'slots'>;
 
 /** Validates application-shell selection without introducing a competing shell model. */
 export function validateLayoutApplicability(layout: Layout | undefined, scope: TemplateScope): string[] {

package/templates/ApplicableTemplateSet.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TemplateMetadata, TemplateReference } from '@cratis/scene.model';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+
+/** One template that can be applied at a target, with the reference that selects it. */
+export interface ApplicableTemplate {
+    /** The package that provides the template. */
+    package: string;
+
+    /** The version of that package. */
+    packageVersion: string;
+
+    kind: TemplateCatalogKind;
+    name: string;
+    displayName?: string;
+    description?: string;
+    metadata?: TemplateMetadata;
+
+    /** The reference that selects it: an own reference, or a blueprint reference pinned to `^<installed version>`. */
+    reference: TemplateReference;
+}
+
+/** The applicable templates sharing one browse category, in browse order. */
+export interface ApplicableTemplateGroup {
+    /** The category, or undefined for templates that declare none. Uncategorized templates are listed last. */
+    category?: string;
+
+    templates: ApplicableTemplate[];
+}
+
+/** A blueprint that has at least one template applicable at the target, with those templates by category. */
+export interface ApplicableBlueprint {
+    /** The blueprint package name. */
+    blueprint: string;
+
+    /** The installed version of the blueprint. */
+    version: string;
+
+    /** A human-readable name for a picker, falling back to `blueprint`. */
+    displayName?: string;
+
+    categories: ApplicableTemplateGroup[];
+}
+
+/** What a template picker offers at a target: own templates by category first, then the blueprints that have anything applicable. */
+export interface ApplicableTemplateSet {
+    /** The own templates that apply, grouped by category. */
+    own: ApplicableTemplateGroup[];
+
+    /** The blueprints with at least one applicable template. A blueprint with none is omitted, never listed empty. */
+    blueprints: ApplicableBlueprint[];
+}

package/templates/TemplateCatalogEntry.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { TemplateAttribution, TemplateCompatibility, TemplateScope } from '@cratis/scene.model';
+import { TemplateAttribution, TemplateCompatibility, TemplateScope, SliceKind } from '@cratis/scene.model';
 import { TemplateCatalogKind } from './TemplateCatalogKind';
 
 /**
@@ -22,6 +22,7 @@ export interface TemplateCatalogEntry {
     type?: string;
     category?: string;
     scopes?: TemplateScope[];
+    sliceKinds?: SliceKind[];
     compatibility?: TemplateCompatibility;
     attribution?: TemplateAttribution;
     license?: string;
@@ -32,4 +33,7 @@ export interface TemplateCatalogEntry {
 
     /** Why it is not - missing or invalid metadata, or an unmet Scene or package requirement. */
     problems: string[];
+
+    /** Recommendations that do not make the template unusable, such as an own template without a category. */
+    warnings: string[];
 }

package/templates/TemplateLibrary.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 { TemplateSource } from './TemplateSource';
+
+/**
+ * Every template a host can choose from: the ones the user created in the workspace and the ones blueprint
+ * packages ship.
+ */
+export interface TemplateLibrary {
+    /** The workspace's own templates. Its manifest is never treated as a blueprint. */
+    own?: TemplateSource;
+
+    /** The blueprint packages and the templates they ship, in browse order. */
+    blueprints: TemplateSource[];
+}

package/templates/TemplateReferenceResolution.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.
+
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+
+/** The outcome of resolving a template reference against a template library. */
+export enum TemplateReferenceStatus {
+    /** The reference names a template that exists, at a version the reference accepts. */
+    Resolved = 'Resolved',
+    /** The reference is not well formed: an own reference carrying a blueprint or version, a blueprint reference without a blueprint, or an invalid version range. */
+    Malformed = 'Malformed',
+    /** No blueprint package of that name is available. */
+    UnknownBlueprint = 'UnknownBlueprint',
+    /** The installed version of the blueprint is outside the reference's version range: the blueprint has drifted from what was chosen. */
+    VersionNotSatisfied = 'VersionNotSatisfied',
+    /** The blueprint or workspace has no template of that name. */
+    UnknownTemplate = 'UnknownTemplate',
+}
+
+/** The result of resolving a template reference. */
+export interface TemplateReferenceResolution {
+    status: TemplateReferenceStatus;
+
+    /** The package providing the template, when it was found or its blueprint was. */
+    package?: string;
+
+    /** The installed version of that package. */
+    packageVersion?: string;
+
+    /** Which kind of template was found, when the status is Resolved. */
+    kind?: TemplateCatalogKind;
+
+    /** A diagnostic when the reference did not resolve. */
+    message?: string;
+}

package/templates/TemplateTarget.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.
+
+import { TemplateScope, SliceKind } from '@cratis/scene.model';
+import { TemplateContainer } from '../templateApplicability';
+
+/** Where a template is about to be applied: a level of the application hierarchy and what it sits inside. */
+export interface TemplateTarget {
+    /** The hierarchy level. */
+    scope: TemplateScope;
+
+    /** The kind of the slice when `scope` is {@link TemplateScope.Slice}. */
+    sliceKind?: SliceKind;
+
+    /** The layout or template whose slots the template must fit, if known. */
+    container?: TemplateContainer;
+
+    /**
+     * The names of the templates already chosen above the target, outermost first. A template in the chain is not
+     * offered again, because nesting it inside itself would loop.
+     */
+    chain?: string[];
+}

package/templates/applicableTemplates.ts

@@ -0,0 +1,148 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate, Layout, ScreenTemplate, TemplateMetadata, TemplateReference, TemplateReferenceSource, TemplateScope, SliceKind } from '@cratis/scene.model';
+import { resolveScreenTemplates } from '../resolveScreenTemplates';
+import { validateDialogTemplateApplicability, validateLayoutApplicability, validateScreenTemplateApplicability } from '../templateApplicability';
+import { ApplicableBlueprint, ApplicableTemplate, ApplicableTemplateGroup, ApplicableTemplateSet } from './ApplicableTemplateSet';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+import { TemplateLibrary } from './TemplateLibrary';
+import { TemplateSource } from './TemplateSource';
+import { TemplateTarget } from './TemplateTarget';
+
+const screenScopes = [TemplateScope.Module, TemplateScope.Feature, TemplateScope.Subfeature];
+const dialogSliceKinds = [SliceKind.StateChange];
+const screenSliceKinds = [SliceKind.StateChange, SliceKind.StateView];
+
+/**
+ * Decides which templates a picker offers at a target, so no host re-implements the rules: own templates by
+ * category, then each blueprint that has at least one applicable template. A blueprint with none is omitted.
+ *
+ * It composes the applicability validators (kind and scope, explicit scopes override, category never implies a
+ * scope, slot fit against the container) and `resolveScreenTemplates` (a template must find exactly one home and
+ * nothing may nest inside itself) with the defaults of each hierarchy level, used when a template declares no scopes:
+ *
+ * - Application - layouts.
+ * - Module, Feature, Subfeature - screen templates, fitting a slot of the container.
+ * - Slice, state change - dialog templates.
+ * - Slice, state view - screen templates that declare the Slice scope or state view slice kinds.
+ *
+ * Declared `scopes` and `sliceKinds` always override the defaults. The C# engine (`ApplicableTemplates.Compute`)
+ * returns identical results; both are asserted against `template-applicability-fixtures.json`.
+ */
+export function applicableTemplates(library: TemplateLibrary, target: TemplateTarget): ApplicableTemplateSet {
+    const own = library.own ? groupByCategory(applicableIn(library.own, target, false)) : [];
+    const blueprints: ApplicableBlueprint[] = [];
+    for (const source of library.blueprints) {
+        const categories = groupByCategory(applicableIn(source, target, true));
+        if (categories.length > 0) {
+            blueprints.push({ blueprint: source.manifest.name, version: source.manifest.version, displayName: source.manifest.displayName, categories });
+        }
+    }
+    return { own, blueprints };
+}
+
+/** Why a layout does not apply at a target; empty when it does. */
+export function validateLayoutForTarget(layout: Layout, target: TemplateTarget): string[] {
+    return withDefaults(validateLayoutApplicability(layout, target.scope), layout.name, TemplateCatalogKind.Layout, layout.metadata, target);
+}
+
+/** Why a screen template does not apply at a target, including whether its slot nesting resolves; empty when it does. */
+export function validateScreenTemplateForTarget(template: ScreenTemplate, target: TemplateTarget): string[] {
+    const problems = withDefaults(
+        validateScreenTemplateApplicability(template, target.scope, target.container),
+        template.name,
+        TemplateCatalogKind.ScreenTemplate,
+        template.metadata,
+        target,
+    );
+    if (problems.length > 0) return problems;
+
+    if (target.chain?.includes(template.name)) {
+        return [`Template '${template.name}' is already chosen above this target; nesting it again would make the chain loop`];
+    }
+
+    if (template.fitsSlot !== undefined && target.container) {
+        const containerName = target.container.name;
+        const resolution = resolveScreenTemplates({ name: containerName, slots: target.container.slots } as Layout, [template]);
+        const valid = resolution.unplaced.length === 0 && resolution.cycles.length === 0;
+        if (!valid || !resolution.placements.some(placement => placement.template === template.name && placement.container === containerName)) {
+            return [`Template '${template.name}' cannot be placed in '${containerName}': its slot nesting does not resolve`];
+        }
+    }
+    return [];
+}
+
+/** Why a dialog template does not apply at a target; empty when it does. */
+export function validateDialogTemplateForTarget(template: DialogTemplate, target: TemplateTarget): string[] {
+    return withDefaults(validateDialogTemplateApplicability(template, target.scope), template.name, TemplateCatalogKind.DialogTemplate, template.metadata, target);
+}
+
+function applicableIn(source: TemplateSource, target: TemplateTarget, isBlueprint: boolean): ApplicableTemplate[] {
+    const { manifest } = source;
+    const referenceTo = (name: string): TemplateReference => isBlueprint
+        ? { source: TemplateReferenceSource.Blueprint, id: name, blueprint: manifest.name, version: `^${manifest.version}` }
+        : { source: TemplateReferenceSource.Own, id: name };
+
+    const applicable: ApplicableTemplate[] = [];
+    for (const layout of source.layouts ?? []) {
+        if (validateLayoutForTarget(layout, target).length > 0) continue;
+        applicable.push({
+            package: manifest.name, packageVersion: manifest.version, kind: TemplateCatalogKind.Layout, name: layout.name,
+            metadata: layout.metadata, reference: referenceTo(layout.name),
+        });
+    }
+    for (const template of source.screenTemplates ?? []) {
+        if (validateScreenTemplateForTarget(template, target).length > 0) continue;
+        applicable.push({
+            package: manifest.name, packageVersion: manifest.version, kind: TemplateCatalogKind.ScreenTemplate, name: template.name,
+            displayName: template.displayName, description: template.description, metadata: template.metadata, reference: referenceTo(template.name),
+        });
+    }
+    for (const template of source.dialogTemplates ?? []) {
+        if (validateDialogTemplateForTarget(template, target).length > 0) continue;
+        applicable.push({
+            package: manifest.name, packageVersion: manifest.version, kind: TemplateCatalogKind.DialogTemplate, name: template.name,
+            displayName: template.displayName, description: template.description, metadata: template.metadata, reference: referenceTo(template.name),
+        });
+    }
+    return applicable;
+}
+
+function groupByCategory(templates: ApplicableTemplate[]): ApplicableTemplateGroup[] {
+    const categoryOf = (template: ApplicableTemplate) => template.metadata?.category?.trim() ? template.metadata.category : undefined;
+    const categories = [...new Set(templates.map(categoryOf).filter((category): category is string => category !== undefined))];
+    const groups: ApplicableTemplateGroup[] = categories.map(category => ({ category, templates: templates.filter(template => categoryOf(template) === category) }));
+    const uncategorized = templates.filter(template => categoryOf(template) === undefined);
+    if (uncategorized.length > 0) groups.push({ templates: uncategorized });
+    return groups;
+}
+
+function withDefaults(problems: string[], name: string, kind: TemplateCatalogKind, metadata: TemplateMetadata | undefined, target: TemplateTarget): string[] {
+    if (problems.length > 0 || !Object.values(TemplateScope).includes(target.scope)) return problems;
+
+    if (metadata?.scopes === undefined && !defaultScopes(kind, metadata).includes(target.scope)) {
+        return [`Template '${name}' is not offered at scope '${target.scope}' unless it declares that scope`];
+    }
+
+    if (target.scope === TemplateScope.Slice && target.sliceKind !== undefined) {
+        const sliceKind = target.sliceKind;
+        if (!Object.values(SliceKind).includes(sliceKind)) return [`Template '${name}' has unknown target slice kind '${sliceKind}'`];
+        if (sliceKind === SliceKind.Automation) return [`Template '${name}' cannot be applied to an Automation slice, which has no presentation`];
+        const kinds = metadata?.sliceKinds ?? defaultSliceKinds(kind);
+        if (!kinds.includes(sliceKind)) return [`Template '${name}' does not apply to slice kind '${sliceKind}'`];
+    }
+    return [];
+}
+
+function defaultScopes(kind: TemplateCatalogKind, metadata: TemplateMetadata | undefined): TemplateScope[] {
+    switch (kind) {
+        case TemplateCatalogKind.Layout: return [TemplateScope.Application];
+        case TemplateCatalogKind.DialogTemplate: return [TemplateScope.Slice];
+        default: return metadata?.sliceKinds === undefined ? screenScopes : [TemplateScope.Slice];
+    }
+}
+
+function defaultSliceKinds(kind: TemplateCatalogKind): SliceKind[] {
+    return kind === TemplateCatalogKind.DialogTemplate ? dialogSliceKinds : screenSliceKinds;
+}

package/templates/describeTemplateCatalog.ts

@@ -1,12 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ScenePackage, TemplateMetadata } from '@cratis/scene.model';
+import { PackageKind, ScenePackage, TemplateMetadata } from '@cratis/scene.model';
 import { isVersionSatisfiedBy } from '../packageVersionRange';
 import { TemplateCatalogEntry } from './TemplateCatalogEntry';
 import { TemplateCatalogKind } from './TemplateCatalogKind';
 import { TemplateSource } from './TemplateSource';
-import { validateTemplateMetadata } from './validateTemplateMetadata';
+import { validateTemplateCategory, validateTemplateMetadata } from './validateTemplateMetadata';
 
 /**
  * Describes every template the given packages provide, in package then layout, screen template, dialog
@@ -14,7 +14,8 @@ import { validateTemplateMetadata } from './validateTemplateMetadata';
  *
  * A template is compatible when its metadata is complete and valid, the Scene version (when given) satisfies
  * its Scene range, and every package it requires is among the given packages at a satisfying version and is
- * either its own package or one that package depends on. Nothing is filtered out: a browser shows incompatible
+ * either its own package or one that package depends on. A blueprint template without a category is a problem; an
+ * own template without one is a warning. Nothing is filtered out: a browser shows incompatible
  * templates with their problems rather than hiding why they are unavailable.
  */
 export function describeTemplateCatalog(sources: TemplateSource[], sceneVersion?: string): TemplateCatalogEntry[] {
@@ -31,10 +32,11 @@ export function describeTemplateCatalog(sources: TemplateSource[], sceneVersion?
         for (const { kind, template } of templates) {
             const metadata = template.metadata;
             const describable = template as { displayName?: string; description?: string };
-            const problems = [
-                ...validateTemplateMetadata(template.name, metadata),
-                ...requirementProblems(template.name, metadata, source.manifest, versions, sceneVersion),
-            ];
+            const problems = validateTemplateMetadata(template.name, metadata);
+            const warnings: string[] = [];
+            const missingCategory = validateTemplateCategory(template.name, metadata);
+            if (missingCategory) (source.manifest.kind === PackageKind.Blueprint ? problems : warnings).push(missingCategory);
+            problems.push(...requirementProblems(template.name, metadata, source.manifest, versions, sceneVersion));
 
             entries.push({
                 package: source.manifest.name,
@@ -46,12 +48,14 @@ export function describeTemplateCatalog(sources: TemplateSource[], sceneVersion?
                 type: metadata?.type,
                 category: metadata?.category,
                 scopes: metadata?.scopes,
+                sliceKinds: metadata?.sliceKinds,
                 compatibility: metadata?.compatibility,
                 attribution: metadata?.attribution,
                 license: metadata?.license,
                 licenseUrl: metadata?.licenseUrl,
                 compatible: problems.length === 0,
                 problems,
+                warnings,
             });
         }
     }

package/templates/index.ts

@@ -1,9 +1,15 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './ApplicableTemplateSet';
 export * from './TemplateCatalogEntry';
 export * from './TemplateCatalogKind';
+export * from './TemplateLibrary';
+export * from './TemplateReferenceResolution';
 export * from './TemplateSource';
+export * from './TemplateTarget';
+export * from './applicableTemplates';
 export * from './describeTemplateCatalog';
+export * from './resolveTemplateReference';
 export * from './templateMetadataRules';
 export * from './validateTemplateMetadata';

package/templates/resolveTemplateReference.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TemplateReference, TemplateReferenceSource } from '@cratis/scene.model';
+import { isValidVersionRange, isVersionSatisfiedBy } from '../packageVersionRange';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+import { TemplateLibrary } from './TemplateLibrary';
+import { TemplateReferenceResolution, TemplateReferenceStatus } from './TemplateReferenceResolution';
+import { TemplateSource } from './TemplateSource';
+
+/**
+ * Resolves a template reference against the templates that exist, including the blueprint version pin. The C#
+ * engine (`TemplateReferenceResolver.Resolve`) reports the same outcomes and messages; both are asserted against
+ * `template-applicability-fixtures.json`.
+ */
+export function resolveTemplateReference(reference: TemplateReference, library: TemplateLibrary): TemplateReferenceResolution {
+    if (!reference.id?.trim()) {
+        return { status: TemplateReferenceStatus.Malformed, message: 'A template reference must name a template' };
+    }
+
+    if (reference.source === TemplateReferenceSource.Own) {
+        if (reference.blueprint !== undefined || reference.version !== undefined) {
+            return { status: TemplateReferenceStatus.Malformed, message: `Own template reference '${reference.id}' must not name a blueprint or a version` };
+        }
+        return library.own ? find(reference.id, library.own, reference) : unknown(reference, undefined);
+    }
+
+    if (!reference.blueprint?.trim()) {
+        return { status: TemplateReferenceStatus.Malformed, message: `Blueprint template reference '${reference.id}' must name its blueprint` };
+    }
+
+    const blueprint = library.blueprints.find(source => source.manifest.name === reference.blueprint);
+    if (!blueprint) {
+        return { status: TemplateReferenceStatus.UnknownBlueprint, message: `Blueprint '${reference.blueprint}' referenced by template '${reference.id}' is not available` };
+    }
+
+    const installed = blueprint.manifest.version;
+    if (reference.version !== undefined) {
+        if (!isValidVersionRange(reference.version)) {
+            return {
+                status: TemplateReferenceStatus.Malformed, package: blueprint.manifest.name, packageVersion: installed,
+                message: `Template reference '${reference.id}' declares an invalid version range '${reference.version}'`,
+            };
+        }
+        if (!isVersionSatisfiedBy(installed, reference.version)) {
+            return {
+                status: TemplateReferenceStatus.VersionNotSatisfied, package: blueprint.manifest.name, packageVersion: installed,
+                message: `Template '${reference.id}' was chosen from blueprint '${blueprint.manifest.name}' ${reference.version} but version ${installed} is installed`,
+            };
+        }
+    }
+
+    return find(reference.id, blueprint, reference);
+}
+
+function find(name: string, source: TemplateSource, reference: TemplateReference): TemplateReferenceResolution {
+    const kind = kindOf(name, source);
+    return kind === undefined
+        ? unknown(reference, source)
+        : { status: TemplateReferenceStatus.Resolved, package: source.manifest.name, packageVersion: source.manifest.version, kind };
+}
+
+function unknown(reference: TemplateReference, source: TemplateSource | undefined): TemplateReferenceResolution {
+    return {
+        status: TemplateReferenceStatus.UnknownTemplate,
+        package: source?.manifest.name,
+        packageVersion: source?.manifest.version,
+        message: reference.source === TemplateReferenceSource.Own
+            ? `Own template '${reference.id}' does not exist`
+            : `Blueprint '${reference.blueprint}' has no template '${reference.id}'`,
+    };
+}
+
+function kindOf(name: string, source: TemplateSource): TemplateCatalogKind | undefined {
+    if (source.screenTemplates?.some(template => template.name === name)) return TemplateCatalogKind.ScreenTemplate;
+    if (source.dialogTemplates?.some(template => template.name === name)) return TemplateCatalogKind.DialogTemplate;
+    if (source.layouts?.some(layout => layout.name === name)) return TemplateCatalogKind.Layout;
+    return undefined;
+}

package/templates/validateTemplateMetadata.ts

@@ -53,3 +53,14 @@ export function validateTemplateMetadata(name: string, metadata: TemplateMetadat
 
     return problems;
 }
+
+/**
+ * The diagnostic code reported for a template without a category. Category is required for blueprint templates
+ * (an error) and recommended for own templates (a warning).
+ */
+export const templateCategoryMissingCode = 'templateCategoryMissing';
+
+/** Checks that a template declares a browse category; returns the problem, or undefined when it does. */
+export function validateTemplateCategory(name: string, metadata: TemplateMetadata | undefined): string | undefined {
+    return metadata?.category?.trim() ? undefined : `Template '${name}' declares no category`;
+}