@cratis/scene.react 4.10.0 → 4.12.0

package/navigation/SceneNavigationContext.tsx

@@ -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 { ReactNode, createContext, useContext } from 'react';
+import { BindingScope } from '@cratis/scene.engine';
+import { DestinationReference } from '@cratis/scene.model';
+import { DestinationResolution } from './DestinationResolution';
+
+export interface SceneNavigationContextValue {
+    currentScreen: string;
+    currentUrl?: string;
+    currentOutlet?: string;
+    currentDialog?: string;
+    bindingScope: BindingScope;
+    navigate(destination: DestinationReference): DestinationResolution;
+    closeDialog(): void;
+}
+
+const Context = createContext<SceneNavigationContextValue | undefined>(undefined);
+
+export interface SceneNavigationProviderProps {
+    value: SceneNavigationContextValue;
+    children: ReactNode;
+}
+
+export function SceneNavigationProvider({ value, children }: SceneNavigationProviderProps) {
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useSceneNavigation(): SceneNavigationContextValue {
+    const context = useContext(Context);
+    if (!context) throw new Error('No Scene navigation context is available.');
+    return context;
+}

package/navigation/SceneNavigationHost.tsx

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useMemo, useState } from 'react';
+import { BindingScope } from '@cratis/scene.engine';
+import { DestinationKind, DestinationReference, SceneElement } from '@cratis/scene.model';
+import { SceneElementView } from '../SceneElementView';
+import { ComponentRegistry } from '../renderer';
+import { SceneNavigationContextValue, SceneNavigationProvider } from './SceneNavigationContext';
+import { resolveDestination } from './resolveDestination';
+
+export interface SceneNavigationHostProps {
+    screens: Record<string, SceneElement>;
+    dialogs?: Record<string, SceneElement>;
+    initialScreen: string;
+    registry: ComponentRegistry;
+    bindingScope?: BindingScope;
+}
+
+/**
+ * Executes Scene destinations against an in-memory rendered hierarchy: screen routes replace outlets,
+ * dialog destinations render dialog content, and external destinations only report their resolved action.
+ */
+export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, registry, bindingScope = {} }: SceneNavigationHostProps) {
+    const [currentScreen, setCurrentScreen] = useState(initialScreen);
+    const [currentUrl, setCurrentUrl] = useState<string | undefined>(initialScreen);
+    const [currentOutlet, setCurrentOutlet] = useState<string | undefined>();
+    const [currentDialog, setCurrentDialog] = useState<string | undefined>();
+
+    const navigate = useCallback((destination: DestinationReference) => {
+        const resolution = resolveDestination(destination, bindingScope);
+        if (resolution.kind === DestinationKind.Dialog) {
+            setCurrentDialog(resolution.dialog);
+            return resolution;
+        }
+
+        if (resolution.kind !== DestinationKind.External) {
+            setCurrentScreen(destination.screen ?? destination.slice ?? currentScreen);
+            setCurrentOutlet(resolution.outlet);
+        }
+
+        setCurrentUrl(resolution.url);
+        return resolution;
+    }, [bindingScope, currentScreen]);
+
+    const value = useMemo<SceneNavigationContextValue>(() => ({
+        currentScreen,
+        currentUrl,
+        currentOutlet,
+        currentDialog,
+        bindingScope,
+        navigate,
+        closeDialog: () => setCurrentDialog(undefined),
+    }), [bindingScope, currentDialog, currentOutlet, currentScreen, currentUrl, navigate]);
+
+    const screen = screens[currentScreen];
+    const dialog = currentDialog ? dialogs[currentDialog] : undefined;
+
+    return <SceneNavigationProvider value={value}>
+        <div data-scene-outlet={currentOutlet ?? 'primary'} data-scene-url={currentUrl}>
+            {screen && <SceneElementView element={screen} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />}
+        </div>
+        {dialog && <div role='dialog' data-scene-dialog={currentDialog}>
+            <SceneElementView element={dialog} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />
+        </div>}
+    </SceneNavigationProvider>;
+}

package/navigation/index.ts

@@ -2,4 +2,6 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './DestinationResolution';
+export * from './SceneNavigationContext';
+export * from './SceneNavigationHost';
 export * from './resolveDestination';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.10.0",
+    "version": "4.12.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.10.0",
-        "@cratis/scene.model": "4.10.0"
+        "@cratis/scene.engine": "4.12.0",
+        "@cratis/scene.model": "4.12.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.10.0",
-        "@cratis/scene.model": "4.10.0",
+        "@cratis/scene.engine": "4.12.0",
+        "@cratis/scene.model": "4.12.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/packages/EmbeddedPackageHost.tsx

@@ -0,0 +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 { PackageHostView, PackageHostViewProps } from './PackageHostView';
+import { PackageHostRenderMode } from './PackageHostRenderMode';
+
+/** An embedded package host example surface for application or designer panes. */
+export function EmbeddedPackageHost(props: Omit<PackageHostViewProps, 'mode'>) {
+    return <PackageHostView {...props} mode={PackageHostRenderMode.Embedded} />;
+}

package/packages/PackageHostAssets.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export interface PackageHostAssetsProps {
+    assets: string[];
+    fonts: string[];
+}
+
+/**
+ * Emits package-declared browser assets for a package host example.
+ */
+export function PackageHostAssets({ assets, fonts }: PackageHostAssetsProps) {
+    const fontSet = new Set(fonts);
+    return <>
+        {assets.filter(asset => !fontSet.has(asset)).map(asset => <link key={asset} rel='stylesheet' href={asset} data-scene-package-asset={asset} />)}
+        {fonts.map(font => <link key={font} rel='preload' href={font} as='font' crossOrigin='' data-scene-package-font={font} />)}
+    </>;
+}

package/packages/PackageHostConfiguration.ts

@@ -9,6 +9,9 @@ import { ScenePackageBundle, mergePackageRegistries, validatePackageBundle } fro
 export interface PackageHostPolicy {
     allowExecutableImports: boolean;
     allowNetworkAssets: boolean;
+
+    /** Whether this host is resolving optional design-time bundles in addition to runtime contributions. */
+    loadDesignTime?: boolean;
 }
 
 export interface PackageHostConfiguration {
@@ -26,6 +29,8 @@ export interface ResolvedPackageHost {
     themes: Theme[];
     icons: IconAdapterRegistry;
     assets: string[];
+    fonts: string[];
+    blocked: boolean;
     diagnostics: string[];
 }
 
@@ -63,7 +68,7 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         }
 
         diagnostics.push(...validatePackageBundle(bundle).map(problem => `${packageName}: ${problem}`));
-        if (!configuration.policy.allowExecutableImports && bundle.designTime) {
+        if (configuration.policy.loadDesignTime === true && !configuration.policy.allowExecutableImports && bundle.designTime) {
             diagnostics.push(`Package '${packageName}' provides executable design-time contributions, but host policy forbids them`);
         }
 
@@ -84,15 +89,25 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         bundles.push(bundle);
     }
 
+    const blocked = diagnostics.length > 0;
+    const approved = blocked ? [] : bundles;
+    const approvedAssets = blocked ? [] : assets;
+
     return {
-        bundles,
-        components: mergePackageRegistries(bundles),
-        layouts: bundles.flatMap(bundle => bundle.layouts ?? []),
-        screenTemplates: bundles.flatMap(bundle => bundle.screenTemplates ?? []),
-        dialogTemplates: bundles.flatMap(bundle => bundle.dialogTemplates ?? []),
-        themes: bundles.flatMap(bundle => bundle.themes ?? []),
-        icons: createIconAdapterRegistry(bundles.map(bundle => bundle.iconLibrary?.adapter).filter(adapter => adapter !== undefined)),
-        assets,
+        bundles: approved,
+        components: mergePackageRegistries(approved),
+        layouts: approved.flatMap(bundle => bundle.layouts ?? []),
+        screenTemplates: approved.flatMap(bundle => bundle.screenTemplates ?? []),
+        dialogTemplates: approved.flatMap(bundle => bundle.dialogTemplates ?? []),
+        themes: approved.flatMap(bundle => bundle.themes ?? []),
+        icons: createIconAdapterRegistry(approved.map(bundle => bundle.iconLibrary?.adapter).filter(adapter => adapter !== undefined)),
+        assets: approvedAssets,
+        fonts: approvedAssets.filter(isFontAsset),
+        blocked,
         diagnostics,
     };
 }
+
+function isFontAsset(asset: string): boolean {
+    return /\.(woff2?|otf|ttf)(\?|$)/.test(asset) || asset.includes('/fonts/');
+}

package/packages/PackageHostRenderMode.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The host surface rendering a resolved package profile.
+ */
+export enum PackageHostRenderMode {
+    Standalone = 'standalone',
+    Embedded = 'embedded',
+    WebView = 'webView',
+}

package/packages/PackageHostView.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { SceneElementView } from '../SceneElementView';
+import { PackageHostAssets } from './PackageHostAssets';
+import { PackageHostConfiguration, resolvePackageHost } from './PackageHostConfiguration';
+import { PackageHostRenderMode } from './PackageHostRenderMode';
+
+export interface PackageHostViewProps {
+    configuration: PackageHostConfiguration;
+    element: SceneElement;
+    mode?: PackageHostRenderMode;
+    dataContext?: unknown;
+    queryResults?: Record<string, unknown>;
+    componentOutputs?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Renders a Scene element through an approved package host. Diagnostics are blocking: no rejected bundle,
+ * component, asset or design-time contribution is rendered after policy/dependency validation fails.
+ */
+export function PackageHostView({
+    configuration,
+    element,
+    mode = PackageHostRenderMode.Embedded,
+    dataContext,
+    queryResults,
+    componentOutputs,
+}: PackageHostViewProps) {
+    const host = resolvePackageHost(configuration);
+    if (host.blocked) {
+        return <section role='alert' data-scene-host-mode={mode} data-scene-host-blocked='true'>
+            <h2>Scene package host blocked rendering</h2>
+            <ul>{host.diagnostics.map(diagnostic => <li key={diagnostic}>{diagnostic}</li>)}</ul>
+        </section>;
+    }
+
+    return <section data-scene-host-mode={mode} data-scene-host-blocked='false'>
+        <PackageHostAssets assets={host.assets} fonts={host.fonts} />
+        <SceneElementView element={element} registry={host.components} dataContext={dataContext} queryResults={queryResults} componentOutputs={componentOutputs} />
+    </section>;
+}

package/packages/StandalonePackageHost.tsx

@@ -0,0 +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 { PackageHostView, PackageHostViewProps } from './PackageHostView';
+import { PackageHostRenderMode } from './PackageHostRenderMode';
+
+/** A standalone browser package host example surface. */
+export function StandalonePackageHost(props: Omit<PackageHostViewProps, 'mode'>) {
+    return <PackageHostView {...props} mode={PackageHostRenderMode.Standalone} />;
+}

package/packages/WebViewPackageHost.tsx

@@ -0,0 +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 { PackageHostView, PackageHostViewProps } from './PackageHostView';
+import { PackageHostRenderMode } from './PackageHostRenderMode';
+
+/** A constrained webview package host example surface. */
+export function WebViewPackageHost(props: Omit<PackageHostViewProps, 'mode'>) {
+    return <PackageHostView {...props} mode={PackageHostRenderMode.WebView} />;
+}

package/packages/index.ts

@@ -9,6 +9,12 @@ export * from './DesignTimePropertyDisplayProps';
 export * from './DesignTimePropertyEditorProps';
 export * from './DesignTimeProvider';
 export * from '../navigation';
+export * from './EmbeddedPackageHost';
+export * from './PackageHostAssets';
 export * from './PackageHostConfiguration';
+export * from './PackageHostRenderMode';
+export * from './PackageHostView';
 export * from './ScenePackageBundle';
+export * from './StandalonePackageHost';
+export * from './WebViewPackageHost';
 export * from './ComponentsUiLibraryContract';

package/renderer/InteractiveComponent.tsx

@@ -39,6 +39,7 @@ function resolveProperties(properties: Record<string, unknown>, resolveBinding:
 
 function resolveValue(value: unknown, resolveBinding: (binding: BindingExpression) => unknown): unknown {
     if (isBindingExpression(value)) return resolveBinding(value);
+    if (isDestinationReference(value)) return value;
     if (Array.isArray(value)) return value.map(entry => resolveValue(entry, resolveBinding));
     if (value !== null && typeof value === 'object') {
         return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([name, entry]) => [name, resolveValue(entry, resolveBinding)]));
@@ -50,3 +51,7 @@ function resolveValue(value: unknown, resolveBinding: (binding: BindingExpressio
 function isBindingExpression(value: unknown): value is BindingExpression {
     return value !== null && typeof value === 'object' && !Array.isArray(value) && typeof (value as Record<string, unknown>).path === 'string';
 }
+
+function isDestinationReference(value: unknown): boolean {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && 'routeParameterBindings' in value;
+}