@cratis/scene.engine 4.24.0 → 4.26.0

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`;
+}