@cratis/scene.react 4.12.0 → 4.14.0

package/packages/DesignTimeExtensionPoint.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.
+
+/**
+ * The versioned design-time extension points a package can fill. The values are the keys shared by
+ * `PackageDesignTimeMetadata` (what a manifest declares) and `DesignTimeBundle` (what a bundle provides).
+ */
+export enum DesignTimeExtensionPoint {
+    Preview = 'previews',
+    Designer = 'designers',
+    PropertyEditor = 'propertyEditors',
+    PropertyDisplay = 'propertyDisplays',
+    Action = 'actions',
+}
+
+/** How a diagnostic names an extension point. */
+export const designTimeExtensionPointLabels: Record<DesignTimeExtensionPoint, string> = {
+    [DesignTimeExtensionPoint.Preview]: 'preview',
+    [DesignTimeExtensionPoint.Designer]: 'designer',
+    [DesignTimeExtensionPoint.PropertyEditor]: 'property editor',
+    [DesignTimeExtensionPoint.PropertyDisplay]: 'property display',
+    [DesignTimeExtensionPoint.Action]: 'action',
+};

package/packages/DesignTimeResolution.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.
+
+/**
+ * What a design-time host found for one extension point request.
+ *
+ * When `contribution` is absent the host renders its generic fallback - the default preview, the
+ * descriptor-driven inspector, the default editor for the property's value type - and `diagnostic` says
+ * why, unless nothing was requested in the first place.
+ */
+export interface DesignTimeResolution<T> {
+    /** The package-provided contribution, when one was found and loaded. */
+    contribution?: T;
+
+    /** The package that provided it. */
+    package?: string;
+
+    /** The host-provided editor kind used instead, for property editors the host implements itself. */
+    hostKind?: string;
+
+    /** Why the generic fallback is used. Absent when the request was satisfied or nothing was requested. */
+    diagnostic?: string;
+}

package/packages/PackageHostConfiguration.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { DialogTemplate, Layout, ScreenTemplate, Theme, UiProfile } from '@cratis/scene.model';
-import { resolvePackageDependencies } from '@cratis/scene.engine';
+import { TemplateCatalogEntry, describeTemplateCatalog, resolvePackageDependencies } from '@cratis/scene.engine';
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { ScenePackageBundle, mergePackageRegistries, validatePackageBundle } from './ScenePackageBundle';
 
@@ -18,6 +18,9 @@ export interface PackageHostConfiguration {
     bundles: ScenePackageBundle[];
     profile: UiProfile;
     policy: PackageHostPolicy;
+
+    /** The Scene version the host runs, checked against each template's compatibility range when given. */
+    sceneVersion?: string;
 }
 
 export interface ResolvedPackageHost {
@@ -27,6 +30,12 @@ export interface ResolvedPackageHost {
     screenTemplates: ScreenTemplate[];
     dialogTemplates: DialogTemplate[];
     themes: Theme[];
+
+    /**
+     * Every template the approved packages provide, with compatibility, attribution and license metadata and
+     * whether it can be used with this package set. Template browsers read this rather than the raw lists.
+     */
+    templates: TemplateCatalogEntry[];
     icons: IconAdapterRegistry;
     assets: string[];
     fonts: string[];
@@ -100,6 +109,7 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         screenTemplates: approved.flatMap(bundle => bundle.screenTemplates ?? []),
         dialogTemplates: approved.flatMap(bundle => bundle.dialogTemplates ?? []),
         themes: approved.flatMap(bundle => bundle.themes ?? []),
+        templates: describeTemplateCatalog(approved, configuration.sceneVersion),
         icons: createIconAdapterRegistry(approved.map(bundle => bundle.iconLibrary?.adapter).filter(adapter => adapter !== undefined)),
         assets: approvedAssets,
         fonts: approvedAssets.filter(isFontAsset),

package/packages/index.ts

@@ -2,18 +2,26 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './DesignTimeAction';
+export * from './DesignTimeActionOutcome';
+export * from './DesignTimeActionState';
 export * from './DesignTimeBundle';
 export * from './DesignTimeComponentProps';
 export * from './DesignTimeContext';
+export * from './DesignTimeContractVersion';
+export * from './DesignTimeExtensionPoint';
 export * from './DesignTimePropertyDisplayProps';
 export * from './DesignTimePropertyEditorProps';
 export * from './DesignTimeProvider';
+export * from './DesignTimeResolution';
 export * from '../navigation';
 export * from './EmbeddedPackageHost';
+export * from './loadDesignTimeContributions';
 export * from './PackageHostAssets';
 export * from './PackageHostConfiguration';
 export * from './PackageHostRenderMode';
 export * from './PackageHostView';
+export * from './resolveDesignTimeHost';
+export * from './runDesignTimeAction';
 export * from './ScenePackageBundle';
 export * from './StandalonePackageHost';
 export * from './WebViewPackageHost';

package/packages/loadDesignTimeContributions.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DesignTimeBundle } from './DesignTimeBundle';
+import { DesignTimeContractVersion } from './DesignTimeContractVersion';
+import { DesignTimeExtensionPoint, designTimeExtensionPointLabels } from './DesignTimeExtensionPoint';
+import { ScenePackageBundle } from './ScenePackageBundle';
+
+/**
+ * A package's design-time contributions as a host loaded them: only what the manifest declares, or nothing
+ * with the reason when the package cannot be loaded at all.
+ */
+export interface LoadedDesignTimeContributions {
+    contributions: Partial<Record<DesignTimeExtensionPoint, Record<string, unknown>>>;
+    unavailableReason?: string;
+}
+
+/**
+ * Loads the design-time contributions of approved bundles, checking each against the contract version this
+ * host implements and against what its manifest declares. Nothing is partially trusted: a package with an
+ * incompatible or unreadable contract version, or contributions its manifest does not declare at all,
+ * contributes nothing; a single undeclared contribution is left out; a declared one the bundle lacks is
+ * reported and falls back.
+ */
+export function loadDesignTimeContributions(
+    bundles: ScenePackageBundle[],
+    loadDesignTime: boolean,
+): { packages: Map<string, LoadedDesignTimeContributions>; diagnostics: string[] } {
+    const packages = new Map<string, LoadedDesignTimeContributions>();
+    const diagnostics: string[] = [];
+    const hostMajor = DesignTimeContractVersion.split('.')[0];
+
+    for (const { manifest, designTime } of bundles) {
+        const declared = manifest.designTime;
+        const unavailable = (reason: string) => {
+            diagnostics.push(reason);
+            packages.set(manifest.name, { contributions: {}, unavailableReason: reason });
+        };
+
+        if (!declared && !designTime) continue;
+        if (!loadDesignTime) {
+            packages.set(manifest.name, { contributions: {}, unavailableReason: `This host does not load design-time contributions, so package '${manifest.name}' uses generic editors` });
+            continue;
+        }
+
+        if (!declared) {
+            unavailable(`Package '${manifest.name}' provides design-time contributions its manifest does not declare; none are loaded`);
+            continue;
+        }
+
+        const version = declared.contractVersion ?? '1.0';
+        if (!/^\d+\.\d+$/.test(version)) {
+            unavailable(`Package '${manifest.name}' declares design-time contract version '${version}', which is not a major.minor version; none of its contributions are loaded`);
+            continue;
+        }
+
+        if (version.split('.')[0] !== hostMajor) {
+            unavailable(`Package '${manifest.name}' targets design-time contract ${version}, but this host implements ${DesignTimeContractVersion}; none of its contributions are loaded`);
+            continue;
+        }
+
+        packages.set(manifest.name, { contributions: declaredContributions(manifest.name, declared, designTime, diagnostics) });
+    }
+
+    return { packages, diagnostics };
+}
+
+function declaredContributions(
+    packageName: string,
+    declared: Record<DesignTimeExtensionPoint, string[]>,
+    provided: DesignTimeBundle | undefined,
+    diagnostics: string[],
+): LoadedDesignTimeContributions['contributions'] {
+    const contributions: LoadedDesignTimeContributions['contributions'] = {};
+
+    for (const point of Object.values(DesignTimeExtensionPoint)) {
+        const label = designTimeExtensionPointLabels[point];
+        const names = new Set(declared[point] ?? []);
+        const available = (provided?.[point] ?? {}) as Record<string, unknown>;
+        const loaded: Record<string, unknown> = {};
+
+        for (const name of names) {
+            if (name in available) {
+                loaded[name] = available[name];
+            } else {
+                diagnostics.push(`Package '${packageName}' declares the ${label} '${name}', but its design-time bundle does not provide it`);
+            }
+        }
+
+        for (const name of Object.keys(available).filter(name => !names.has(name))) {
+            diagnostics.push(`Package '${packageName}' provides the ${label} '${name}', which its manifest does not declare; it is not loaded`);
+        }
+
+        contributions[point] = loaded;
+    }
+
+    return contributions;
+}

package/packages/resolveDesignTimeHost.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentType } from 'react';
+import { ComponentDescriptor, PropertyDescriptor } from '@cratis/scene.model';
+import { DesignTimeAction, DesignTimeActionContext } from './DesignTimeAction';
+import { DesignTimeActionOutcome } from './DesignTimeActionOutcome';
+import { DesignTimeActionState } from './DesignTimeActionState';
+import { DesignTimeComponentProps } from './DesignTimeComponentProps';
+import { DesignTimeExtensionPoint, designTimeExtensionPointLabels } from './DesignTimeExtensionPoint';
+import { DesignTimePropertyDisplayProps } from './DesignTimePropertyDisplayProps';
+import { DesignTimePropertyEditorProps } from './DesignTimePropertyEditorProps';
+import { DesignTimeResolution } from './DesignTimeResolution';
+import { LoadedDesignTimeContributions, loadDesignTimeContributions } from './loadDesignTimeContributions';
+import { PackageHostConfiguration, ResolvedPackageHost, resolvePackageHost } from './PackageHostConfiguration';
+import { runDesignTimeAction } from './runDesignTimeAction';
+
+/**
+ * The generic design-time host contract: every package - first or third party - is reached through these
+ * lookups, so a designer never switches on package or component names.
+ */
+export interface DesignTimeHost {
+    /** The runtime package host the design-time contributions were loaded alongside. */
+    host: ResolvedPackageHost;
+
+    /** Package-level problems: the host's own, contract version mismatches and declared/provided disagreements. */
+    diagnostics: string[];
+
+    preview(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimeComponentProps>>;
+    designer(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimeComponentProps>>;
+    propertyEditor(descriptor: ComponentDescriptor, property: PropertyDescriptor): DesignTimeResolution<ComponentType<DesignTimePropertyEditorProps>>;
+    propertyDisplay(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimePropertyDisplayProps>>;
+
+    /** The component's actions, with the visibility and enablement their owning package decides. */
+    actions(descriptor: ComponentDescriptor, context: DesignTimeActionContext): DesignTimeActionState[];
+
+    /** Runs an action and submits its canonical edit batch to the host through `context.submitAction`. */
+    runAction(descriptor: ComponentDescriptor, actionId: string, context: DesignTimeActionContext): DesignTimeActionOutcome;
+
+    /** Every unknown or unavailable extension the approved packages' descriptors ask for. */
+    diagnoseDescriptors(): string[];
+}
+
+/** Options for {@link resolveDesignTimeHost}. */
+export interface DesignTimeHostOptions {
+    /** Property editor kinds the host implements itself, such as an icon picker or a query binder. */
+    hostEditorKinds?: string[];
+}
+
+/**
+ * Resolves a package host and the design-time contributions of its approved packages. Design-time code is
+ * only loaded when the host policy sets `loadDesignTime`; a runtime host gets generic fallbacks everywhere.
+ */
+export function resolveDesignTimeHost(configuration: PackageHostConfiguration, options: DesignTimeHostOptions = {}): DesignTimeHost {
+    const host = resolvePackageHost(configuration);
+    const loaded = loadDesignTimeContributions(host.bundles, configuration.policy.loadDesignTime === true);
+    const hostEditorKinds = new Set(options.hostEditorKinds ?? []);
+    const approved = new Set(host.bundles.map(bundle => bundle.manifest.name));
+
+    const lookup = <T>(descriptor: ComponentDescriptor, point: DesignTimeExtensionPoint, kind: string | undefined): DesignTimeResolution<T> => {
+        if (!kind) return {};
+        const label = designTimeExtensionPointLabels[point];
+        const separator = kind.indexOf(':');
+        const owner = separator > 0 ? kind.substring(0, separator) : ownerOf(descriptor);
+        const name = separator > 0 ? kind.substring(separator + 1) : kind;
+        const outcome = point === DesignTimeExtensionPoint.Action ? 'the host shows it disabled' : `the host uses its generic ${label}`;
+        const fallback = (reason: string) => ({ diagnostic: `'${descriptor.component}' asks for the ${label} '${kind}', ${reason}; ${outcome}` });
+
+        if (!approved.has(owner)) return fallback(`but package '${owner}' is not approved by this host`);
+        const contributions: LoadedDesignTimeContributions | undefined = loaded.packages.get(owner);
+        if (contributions?.unavailableReason) return fallback(`but design-time contributions from package '${owner}' are not loaded`);
+        const contribution = contributions?.contributions[point]?.[name] as T | undefined;
+        if (contribution !== undefined) return { contribution, package: owner };
+        if (point === DesignTimeExtensionPoint.PropertyEditor && separator < 0 && hostEditorKinds.has(kind)) return { hostKind: kind };
+        return fallback(`which package '${owner}' does not provide`);
+    };
+
+    const actionOf = (descriptor: ComponentDescriptor, actionId: string): DesignTimeAction | undefined =>
+        loaded.packages.get(ownerOf(descriptor))?.contributions[DesignTimeExtensionPoint.Action]?.[actionId] as DesignTimeAction | undefined;
+
+    const actions = (descriptor: ComponentDescriptor, context: DesignTimeActionContext): DesignTimeActionState[] =>
+        (descriptor.actions ?? []).map(action => {
+            const state = { descriptor: action, package: ownerOf(descriptor) };
+            const handler = actionOf(descriptor, action.id);
+            if (!handler) {
+                const resolution = lookup<DesignTimeAction>(descriptor, DesignTimeExtensionPoint.Action, action.id);
+                return { ...state, visible: true, enabled: false, diagnostic: resolution.diagnostic };
+            }
+
+            try {
+                return { ...state, visible: handler.isVisible(context), enabled: handler.isEnabled(context) };
+            } catch (error) {
+                return { ...state, visible: true, enabled: false, diagnostic: `Action '${action.id}' could not decide its availability: ${String(error)}` };
+            }
+        });
+
+    const descriptors = host.bundles.flatMap(bundle => bundle.descriptors ?? []);
+
+    return {
+        host,
+        diagnostics: [...host.diagnostics, ...loaded.diagnostics],
+        preview: descriptor => lookup(descriptor, DesignTimeExtensionPoint.Preview, descriptor.previewKind),
+        designer: descriptor => lookup(descriptor, DesignTimeExtensionPoint.Designer, descriptor.editorKind),
+        propertyEditor: (descriptor, property) => lookup(descriptor, DesignTimeExtensionPoint.PropertyEditor, property.editorKind),
+        propertyDisplay: descriptor => lookup(descriptor, DesignTimeExtensionPoint.PropertyDisplay, descriptor.propertyDisplayKind),
+        actions,
+        runAction: (descriptor, actionId, context) => {
+            const state = actions(descriptor, context).find(action => action.descriptor.id === actionId);
+            const handler = actionOf(descriptor, actionId);
+            if (!state || !handler || !state.visible || !state.enabled) {
+                const reason = state?.diagnostic ?? (state ? `Action '${actionId}' is not available here` : `'${descriptor.component}' has no action '${actionId}'`);
+                return { submitted: false, edits: [], diagnostics: [reason] };
+            }
+
+            return runDesignTimeAction(handler, context);
+        },
+        diagnoseDescriptors: () =>
+            descriptors.flatMap(descriptor => [
+                lookup(descriptor, DesignTimeExtensionPoint.Preview, descriptor.previewKind),
+                lookup(descriptor, DesignTimeExtensionPoint.Designer, descriptor.editorKind),
+                lookup(descriptor, DesignTimeExtensionPoint.PropertyDisplay, descriptor.propertyDisplayKind),
+                ...descriptor.properties.map(property => lookup(descriptor, DesignTimeExtensionPoint.PropertyEditor, property.editorKind)),
+                ...(descriptor.actions ?? []).map(action => lookup(descriptor, DesignTimeExtensionPoint.Action, action.id)),
+            ])
+                .map(resolution => resolution.diagnostic)
+                .filter((diagnostic): diagnostic is string => diagnostic !== undefined),
+    };
+}
+
+function ownerOf(descriptor: ComponentDescriptor): string {
+    const separator = descriptor.component.indexOf(':');
+    return separator > 0 ? descriptor.component.substring(0, separator) : descriptor.component;
+}

package/packages/runDesignTimeAction.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEdit, SceneEditKind } from '@cratis/scene.model';
+import { DesignTimeAction, DesignTimeActionContext } from './DesignTimeAction';
+import { DesignTimeActionOutcome } from './DesignTimeActionOutcome';
+
+const editKinds = new Set<string>(Object.values(SceneEditKind));
+
+/**
+ * Runs one design-time action and hands its edit batch to the host as a single canonical batch, so the host's
+ * own validation and undo/redo stay authoritative. A batch containing anything that is not a canonical Scene
+ * edit is rejected whole - a partially applied action is never reported as success.
+ */
+export function runDesignTimeAction(action: DesignTimeAction, context: DesignTimeActionContext): DesignTimeActionOutcome {
+    let result: { edits: SceneEdit[]; diagnostics: string[] };
+    try {
+        result = action.execute(context);
+    } catch (error) {
+        return { submitted: false, edits: [], diagnostics: [`Action '${action.descriptor.id}' failed: ${String(error)}`] };
+    }
+
+    const invalid = result.edits.filter(edit => !editKinds.has((edit as { kind?: string }).kind ?? ''));
+    if (invalid.length > 0) {
+        return {
+            submitted: false,
+            edits: result.edits,
+            diagnostics: [...result.diagnostics, `Action '${action.descriptor.id}' produced ${invalid.length} edit(s) that are not canonical Scene edits; nothing was submitted`],
+        };
+    }
+
+    if (result.edits.length === 0) return { submitted: false, edits: [], diagnostics: result.diagnostics };
+
+    context.submitAction(action.descriptor.id, result.edits);
+    return { submitted: true, edits: result.edits, diagnostics: result.diagnostics };
+}