@cratis/scene.react 4.7.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.7.0",
+    "version": "4.9.0",
     "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
     "keywords": [
         "cratis",
@@ -51,12 +51,12 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.7.0",
-        "@cratis/scene.model": "4.7.0"
+        "@cratis/scene.engine": "4.9.0",
+        "@cratis/scene.model": "4.9.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.7.0",
-        "@cratis/scene.model": "4.7.0",
+        "@cratis/scene.engine": "4.9.0",
+        "@cratis/scene.model": "4.9.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/packages/ComponentsUiLibraryContract.ts

@@ -0,0 +1,89 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The web-only mapping between an independently authored Scene catalog and a Components renderer.
+ * Primitive slot identities are not Scene component names: composites such as DataTable remain
+ * library-independent. This contract belongs to the React bundle, never the platform-neutral model.
+ */
+export interface ComponentsUiLibraryContract {
+    /** The npm module the host loads through its explicit package allowlist. */
+    module: string;
+    /** The named export supplying the Components UiLibrary. */
+    exportName: string;
+    /** The expected runtime library identity. */
+    id: string;
+    /** The Components renderer ABI major required by this mapping. */
+    abi: number;
+    /** The renderer profile promised by the library. */
+    profile: string;
+    /** Primitive or presentation slots the Scene integration requires. */
+    requiredSlots: readonly string[];
+    /** Capabilities required by the integration, not inferred from library identity. */
+    requiredCapabilities?: readonly string[];
+}
+
+/**
+ * The structural part of Components' UiLibrary needed to check a mapping. The actual library may
+ * also contain providers and executable slot declarations; Scene does not load or reinterpret them.
+ * Keeping this structural avoids a Components ABI dependency in Scene.Model or Scene.Engine.
+ */
+export interface ComponentsUiLibraryManifest {
+    readonly id: string;
+    readonly abi: number;
+    readonly profile: string;
+    readonly slots: object;
+    readonly capabilities: readonly string[];
+}
+
+/** Checks a mapping before loading executable frontend code. */
+export function validateComponentsUiLibraryContract(contract: ComponentsUiLibraryContract): string[] {
+    const problems: string[] = [];
+    for (const field of ['module', 'exportName', 'id', 'profile'] as const) {
+        if (contract[field].trim().length === 0) problems.push(`Components UI library mapping has an empty '${field}'`);
+    }
+    if (!Number.isInteger(contract.abi) || contract.abi < 1) {
+        problems.push('Components UI library mapping requires a positive integer ABI major');
+    }
+    for (const [field, values] of [
+        ['requiredSlots', contract.requiredSlots],
+        ['requiredCapabilities', contract.requiredCapabilities ?? []],
+    ] as const) {
+        const seen = new Set<string>();
+        for (const value of values) {
+            if (value.trim().length === 0) problems.push(`Components UI library mapping has an empty '${field}' entry`);
+            if (seen.has(value)) problems.push(`Components UI library mapping repeats '${value}' in '${field}'`);
+            seen.add(value);
+        }
+    }
+    return problems;
+}
+
+/**
+ * Proves that an allowlisted module export satisfies its Scene mapping. Hosts must reject problems,
+ * rather than silently falling back to a different library. Additional slots are permitted: a
+ * renderer can support more than the bounded profile this integration consumes.
+ */
+export function validateComponentsUiLibraryMapping(
+    contract: ComponentsUiLibraryContract,
+    library: ComponentsUiLibraryManifest,
+): string[] {
+    const problems = validateComponentsUiLibraryContract(contract);
+    for (const field of ['id', 'abi', 'profile'] as const) {
+        if (library[field] !== contract[field]) {
+            problems.push(`Components UI library '${contract.id}' requires ${field} '${contract[field]}' but the loaded library supplies '${library[field]}'`);
+        }
+    }
+    const slots = new Map(Object.entries(library.slots));
+    for (const slot of contract.requiredSlots) {
+        if (!slots.has(slot) || slots.get(slot) === undefined || slots.get(slot) === null) {
+            problems.push(`Components UI library '${contract.id}' provides no implementation for required slot '${slot}'`);
+        }
+    }
+    for (const capability of contract.requiredCapabilities ?? []) {
+        if (!library.capabilities.includes(capability)) {
+            problems.push(`Components UI library '${contract.id}' does not support required capability '${capability}'`);
+        }
+    }
+    return problems;
+}

package/packages/DesignTimeAction.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentDescriptor, DesignTimeActionDescriptor, ExternalComponent, SceneEdit } from '@cratis/scene.model';
+
+export interface DesignTimeActionContext {
+    element: ExternalComponent;
+    descriptor: ComponentDescriptor;
+    commandMetadata?: { properties: { name: string; type: string; label?: string }[] };
+}
+
+export interface DesignTimeActionResult {
+    edits: SceneEdit[];
+    diagnostics: string[];
+}
+
+/**
+ * Executable package-owned design-time action. Hosts apply the returned edit batch through their own undo/redo.
+ */
+export interface DesignTimeAction {
+    descriptor: DesignTimeActionDescriptor;
+    isVisible(context: DesignTimeActionContext): boolean;
+    isEnabled(context: DesignTimeActionContext): boolean;
+    execute(context: DesignTimeActionContext): DesignTimeActionResult;
+}

package/packages/DesignTimeBundle.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentType, ReactNode } from 'react';
+import { DesignTimeAction } from './DesignTimeAction';
+
+/**
+ * Optional React-only design-time surface a package may publish beside its runtime bundle.
+ */
+export interface DesignTimeBundle {
+    previews?: Record<string, ComponentType<{ children?: ReactNode }>>;
+    designers?: Record<string, ComponentType<{ children?: ReactNode }>>;
+    propertyEditors?: Record<string, ComponentType<Record<string, unknown>>>;
+    propertyDisplays?: Record<string, ComponentType<{ value: unknown }>>;
+    actions?: Record<string, DesignTimeAction>;
+}
+
+export function validateDesignTimeBundle(bundle: DesignTimeBundle | undefined): string[] {
+    if (!bundle) return [];
+    const problems: string[] = [];
+    for (const [name, action] of Object.entries(bundle.actions ?? {})) {
+        if (action.descriptor.id !== name) {
+            problems.push(`registers design-time action '${name}' with descriptor id '${action.descriptor.id}'`);
+        }
+    }
+    return problems;
+}

package/packages/PackageHostConfiguration.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UiProfile } from '@cratis/scene.model';
+import { ScenePackageBundle, mergePackageRegistries } from './ScenePackageBundle';
+
+export interface PackageHostPolicy {
+    allowExecutableImports: boolean;
+    allowNetworkAssets: boolean;
+}
+
+export interface PackageHostConfiguration {
+    bundles: ScenePackageBundle[];
+    profile: UiProfile;
+    policy: PackageHostPolicy;
+}
+
+export interface ResolvedPackageHost {
+    bundles: ScenePackageBundle[];
+    components: ReturnType<typeof mergePackageRegistries>;
+    diagnostics: string[];
+}
+
+/**
+ * Resolves the approved package set a standalone or embedded React host uses.
+ */
+export function resolvePackageHost(configuration: PackageHostConfiguration): ResolvedPackageHost {
+    const diagnostics: string[] = [];
+    const byName = new Map(configuration.bundles.map(bundle => [bundle.manifest.name, bundle]));
+    const bundles: ScenePackageBundle[] = [];
+    const runtimeSingletons = new Map<string, string>();
+
+    for (const packageName of configuration.profile.packages) {
+        const bundle = byName.get(packageName);
+        if (!bundle) {
+            diagnostics.push(`UI profile asks for '${packageName}' but the host did not approve a bundle for it`);
+            continue;
+        }
+
+        if (!configuration.policy.allowNetworkAssets && (bundle.manifest.assets ?? []).some(asset => /^https?:\/\//.test(asset))) {
+            diagnostics.push(`Package '${packageName}' declares network assets, but host policy forbids them`);
+        }
+
+        for (const dependency of bundle.manifest.runtimeSingletons ?? []) {
+            const owner = runtimeSingletons.get(dependency);
+            if (owner && owner !== packageName) {
+                diagnostics.push(`Runtime singleton '${dependency}' is provided by both '${owner}' and '${packageName}'`);
+            }
+            runtimeSingletons.set(dependency, packageName);
+        }
+
+        bundles.push(bundle);
+    }
+
+    return { bundles, components: mergePackageRegistries(bundles), diagnostics };
+}

package/packages/ScenePackageBundle.ts

@@ -5,6 +5,8 @@ import { ComponentDescriptor, DialogTemplate, Layout, PackageKind, PropertyValue
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { IconLibraryBundle } from '../icons/IconLibraryBundle';
 import { ComponentRegistry } from '../renderer';
+import { ComponentsUiLibraryContract, validateComponentsUiLibraryContract } from './ComponentsUiLibraryContract';
+import { DesignTimeBundle, validateDesignTimeBundle } from './DesignTimeBundle';
 
 /**
  * What a package actually ships to a React renderer, as opposed to what it *declares*.
@@ -70,6 +72,15 @@ export interface ScenePackageBundle {
      * manifest declares an icon library.
      */
     iconLibrary?: IconLibraryBundle;
+
+    /**
+     * Optional web-renderer mapping to a Components UiLibrary. Scene's catalog remains independently
+     * authored; hosts check the loaded export with validateComponentsUiLibraryMapping before rendering.
+     */
+    componentsUiLibrary?: ComponentsUiLibraryContract;
+
+    /** Optional React-only design-time tooling. Runtime hosts can omit it entirely. */
+    designTime?: DesignTimeBundle;
 }
 
 /**
@@ -140,8 +151,16 @@ export function validatePackageBundle(bundle: ScenePackageBundle): string[] {
         }
     }
 
+    if (bundle.componentsUiLibrary) {
+        if (manifest.kind !== PackageKind.ComponentLibrary) {
+            problems.push('declares a Components UI library mapping but is not of kind ComponentLibrary');
+        }
+        problems.push(...validateComponentsUiLibraryContract(bundle.componentsUiLibrary));
+    }
+
     problems.push(...validateIconLibrary(bundle));
     problems.push(...validateDescriptors(bundle));
+    problems.push(...validateDesignTimeBundle(bundle.designTime));
 
     return problems;
 }

package/packages/index.ts

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

package/renderer/BindingOutputContext.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+
+export interface ComponentBindingOutputs {
+    setOutput(property: string, value: unknown): void;
+    clearOutput(property: string): void;
+    clearAll(): void;
+}
+
+export interface BindingOutputProviderValue {
+    outputs: Record<string, Record<string, unknown>>;
+    outputFor(elementId: string): ComponentBindingOutputs;
+}
+
+const emptyOutputs: ComponentBindingOutputs = {
+    setOutput: () => undefined,
+    clearOutput: () => undefined,
+    clearAll: () => undefined,
+};
+
+const Context = createContext<BindingOutputProviderValue | undefined>(undefined);
+
+export interface BindingOutputProviderProps {
+    children: ReactNode;
+    onOutputsChanged?: (outputs: Record<string, Record<string, unknown>>) => void;
+}
+
+/**
+ * Tracks component output properties for typed component-property bindings and clears them with component lifecycle.
+ */
+export function BindingOutputProvider({ children, onOutputsChanged }: BindingOutputProviderProps) {
+    const [outputs, setOutputs] = useState<Record<string, Record<string, unknown>>>({});
+
+    useEffect(() => {
+        onOutputsChanged?.(outputs);
+    }, [onOutputsChanged, outputs]);
+
+    const outputFor = useCallback((elementId: string): ComponentBindingOutputs => ({
+        setOutput: (property: string, propertyValue: unknown) => setOutputs(current => ({
+            ...current,
+            [elementId]: { ...(current[elementId] ?? {}), [property]: propertyValue },
+        })),
+        clearOutput: (property: string) => setOutputs(current => {
+            const elementOutputs = { ...(current[elementId] ?? {}) };
+            delete elementOutputs[property];
+            return { ...current, [elementId]: elementOutputs };
+        }),
+        clearAll: () => setOutputs(current => {
+            const next = { ...current };
+            delete next[elementId];
+            return next;
+        }),
+    }), []);
+
+    const value = useMemo<BindingOutputProviderValue>(() => ({ outputs, outputFor }), [outputs, outputFor]);
+
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useBindingOutputs(elementId: string): ComponentBindingOutputs {
+    const outputFor = useContext(Context)?.outputFor;
+    return useMemo(() => outputFor?.(elementId) ?? emptyOutputs, [outputFor, elementId]);
+}
+
+export function useBindingOutputScope(): Record<string, Record<string, unknown>> {
+    return useContext(Context)?.outputs ?? {};
+}

package/renderer/ComponentRegistry.ts

@@ -4,6 +4,7 @@
 import { ComponentType, ReactNode } from 'react';
 import { ExternalComponent } from '@cratis/scene.model';
 import { InteractionHandlers } from '../interactions';
+import { ComponentBindingOutputs } from './BindingOutputContext';
 
 /**
  * The props every registered component receives.
@@ -21,6 +22,9 @@ export interface RegisteredComponentProps {
      * specification, or a gallery. Spreading it is safe either way.
      */
     interactions?: InteractionHandlers;
+
+    /** Component output property writer for typed element-to-element bindings. */
+    bindingOutputs?: ComponentBindingOutputs;
 }
 
 /**

package/renderer/InteractiveComponent.tsx

@@ -1,9 +1,10 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ComponentType, ReactNode, createElement } from 'react';
+import { ComponentType, ReactNode, createElement, useEffect } from 'react';
 import { ExternalComponent } from '@cratis/scene.model';
 import { useInteractions } from '../interactions';
+import { useBindingOutputs } from './BindingOutputContext';
 import { RegisteredComponentProps } from './ComponentRegistry';
 
 export interface InteractiveComponentProps {
@@ -21,5 +22,7 @@ export interface InteractiveComponentProps {
  */
 export function InteractiveComponent({ component, element, slots }: InteractiveComponentProps) {
     const interactions = useInteractions(element.id, element.behaviors);
-    return createElement(component, { element, slots, interactions });
+    const bindingOutputs = useBindingOutputs(element.id);
+    useEffect(() => () => bindingOutputs.clearAll(), [element.id]);
+    return createElement(component, { element, slots, interactions, bindingOutputs });
 }

package/renderer/index.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './BindingOutputContext';
 export * from './ComponentRegistry';
 export * from './UnresolvedComponent';
 export * from './createReactRenderer';