@cratis/scene.react 4.14.0 → 4.15.0

package/package.json

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

package/packages/PackageHostConfiguration.ts

@@ -2,9 +2,10 @@
 // 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 { TemplateCatalogEntry, describeTemplateCatalog, resolvePackageDependencies } from '@cratis/scene.engine';
+import { TemplateCatalogEntry, describeTemplateCatalog, incompatiblePackages, resolvePackageDependencies } from '@cratis/scene.engine';
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { ScenePackageBundle, mergePackageRegistries, validatePackageBundle } from './ScenePackageBundle';
+import { isNetworkAsset } from './isNetworkAsset';
 
 export interface PackageHostPolicy {
     allowExecutableImports: boolean;
@@ -31,6 +32,12 @@ export interface ResolvedPackageHost {
     dialogTemplates: DialogTemplate[];
     themes: Theme[];
 
+    /** The layout the UI profile names, from the approved packages. Absent when the profile names none. */
+    layout?: Layout;
+
+    /** The theme the UI profile names, from the approved packages. Absent when the profile names none. */
+    theme?: 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.
@@ -82,8 +89,9 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         }
 
         const packageAssets = bundle.manifest.assets ?? [];
-        if (!configuration.policy.allowNetworkAssets && packageAssets.some(asset => /^https?:\/\//.test(asset))) {
-            diagnostics.push(`Package '${packageName}' declares network assets, but host policy forbids them`);
+        const networkAssets = packageAssets.filter(isNetworkAsset);
+        if (!configuration.policy.allowNetworkAssets && networkAssets.length > 0) {
+            diagnostics.push(`Package '${packageName}' declares network assets (${networkAssets.join(', ')}), but host policy forbids them`);
         }
         assets.push(...packageAssets);
 
@@ -98,6 +106,19 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         bundles.push(bundle);
     }
 
+    const layouts = bundles.flatMap(bundle => bundle.layouts ?? []);
+    const themes = bundles.flatMap(bundle => bundle.themes ?? []);
+    const layout = configuration.profile.layout ? layouts.find(candidate => candidate.name === configuration.profile.layout) : undefined;
+    const theme = configuration.profile.theme ? themes.find(candidate => candidate.name === configuration.profile.theme) : undefined;
+    if (configuration.profile.layout && !layout) {
+        diagnostics.push(`UI profile '${configuration.profile.name}' uses layout '${configuration.profile.layout}', which no approved package provides`);
+    }
+    if (configuration.profile.theme && !theme) {
+        diagnostics.push(`UI profile '${configuration.profile.name}' uses theme '${configuration.profile.theme}', which no approved package provides`);
+    } else if (theme && incompatiblePackages(theme, configuration.profile).length > 0) {
+        diagnostics.push(`Theme '${theme.name}' is not compatible with ${incompatiblePackages(theme, configuration.profile).join(', ')} in UI profile '${configuration.profile.name}'`);
+    }
+
     const blocked = diagnostics.length > 0;
     const approved = blocked ? [] : bundles;
     const approvedAssets = blocked ? [] : assets;
@@ -109,6 +130,8 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         screenTemplates: approved.flatMap(bundle => bundle.screenTemplates ?? []),
         dialogTemplates: approved.flatMap(bundle => bundle.dialogTemplates ?? []),
         themes: approved.flatMap(bundle => bundle.themes ?? []),
+        layout: blocked ? undefined : layout,
+        theme: blocked ? undefined : theme,
         templates: describeTemplateCatalog(approved, configuration.sceneVersion),
         icons: createIconAdapterRegistry(approved.map(bundle => bundle.iconLibrary?.adapter).filter(adapter => adapter !== undefined)),
         assets: approvedAssets,

package/packages/index.ts

@@ -16,6 +16,7 @@ export * from './DesignTimeResolution';
 export * from '../navigation';
 export * from './EmbeddedPackageHost';
 export * from './loadDesignTimeContributions';
+export * from './isNetworkAsset';
 export * from './PackageHostAssets';
 export * from './PackageHostConfiguration';
 export * from './PackageHostRenderMode';

package/packages/isNetworkAsset.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Whether loading an asset reaches beyond the host: an absolute URL with any scheme other than `data:`
+ * or `blob:` (`https://`, `http://`, `ws://`, `ftp://`), or a protocol-relative `//host/...` reference. A
+ * package-relative path or a bare module specifier such as `@cratis/components/styles` is resolved by the
+ * host from what it bundled, so it is not a network asset.
+ */
+export function isNetworkAsset(asset: string): boolean {
+    const trimmed = asset.trim();
+    if (trimmed.startsWith('//')) return true;
+    const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(trimmed)?.[1]?.toLowerCase();
+    return scheme !== undefined && scheme !== 'data' && scheme !== 'blob';
+}

package/renderer/RenderBindingScopeContext.tsx

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { ReactNode, createContext, useCallback, useContext, useMemo, useRef } from 'react';
-import { BindingResolver, BindingScope, resolveBindingExpression } from '@cratis/scene.engine';
+import { BindingResolver, BindingScope, nestBindingScope, resolveBindingExpression } from '@cratis/scene.engine';
 import { BindingExpression, BindingNullBehavior } from '@cratis/scene.model';
 import { BindingOutputProvider, useBindingOutputScope } from './BindingOutputContext';
 
@@ -24,10 +24,15 @@ export interface RenderBindingScopeProviderProps {
 
 /**
  * Provides the inherited reactive binding scope for a rendered Scene tree.
+ *
+ * The outermost provider owns the component output scope. A provider rendered inside another - a nested
+ * template or region - nests its own data context, query results and component outputs over the inherited
+ * scope with `nestBindingScope`, so a detail region bound to the selected row reads that row while still
+ * seeing the screen's queries and every component's outputs.
  */
 export function RenderBindingScopeProvider(props: RenderBindingScopeProviderProps) {
     const current = useContext(Context);
-    if (current) return <>{props.children}</>;
+    if (current) return <RenderBindingScopeInner {...props} parent={current.scope} />;
 
     return (
         <BindingOutputProvider onOutputsChanged={props.onComponentOutputsChanged}>
@@ -36,14 +41,13 @@ export function RenderBindingScopeProvider(props: RenderBindingScopeProviderProp
     );
 }
 
-function RenderBindingScopeInner({ children, dataContext, queryResults, componentOutputs, resolveBinding }: RenderBindingScopeProviderProps) {
+function RenderBindingScopeInner({ children, dataContext, queryResults, componentOutputs, resolveBinding, parent }: RenderBindingScopeProviderProps & { parent?: BindingScope }) {
     const outputs = useBindingOutputScope();
     const previousValues = useRef(new Map<string, unknown>());
-    const scope = useMemo<BindingScope>(() => ({
-        dataContext,
-        queryResults,
-        componentOutputs: { ...(componentOutputs ?? {}), ...outputs },
-    }), [componentOutputs, dataContext, outputs, queryResults]);
+    const scope = useMemo<BindingScope>(() => {
+        const own = { dataContext, queryResults, componentOutputs: { ...(componentOutputs ?? {}), ...outputs } };
+        return parent ? nestBindingScope(parent, own) : own;
+    }, [componentOutputs, dataContext, outputs, parent, queryResults]);
 
     const resolver = useCallback<BindingResolver>((binding: BindingExpression) => {
         if (!binding.kind && resolveBinding) return resolveBinding(binding);

package/renderer/index.ts

@@ -6,5 +6,6 @@ export * from './BindingOutputContext';
 export * from './ComponentRegistry';
 export * from './RenderBindingScopeContext';
 export * from './UnresolvedComponent';
+export * from './useBoundQuery';
 export * from './createReactRenderer';
 export * from './InteractiveComponent';

package/renderer/useBoundQuery.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { QueryBindingState } from '@cratis/scene.engine';
+import { QueryPerformer } from './AbortableQueryRunner';
+
+/**
+ * Runs a bound query whenever its arguments change and returns the accepted query results.
+ *
+ * Each change of arguments rebinds the query: the previous run is aborted and, should its answer still
+ * arrive, discarded by `QueryBindingState` - a slow result for a previous selection never replaces the
+ * current one. Arguments of `undefined` mean the binding is cleared, as when a selection is cleared, so the
+ * result is removed, and so is it when the current run fails - a failed rebind must not leave the previous
+ * selection's data on screen. The results are keyed by `query`, ready to pass as a scope's `queryResults`.
+ */
+export function useBoundQuery(query: string, argumentsValue: unknown, perform: QueryPerformer): Record<string, unknown> {
+    const state = useMemo(() => new QueryBindingState(), []);
+    const [results, setResults] = useState<Record<string, unknown>>({});
+    const key = argumentsValue === undefined ? undefined : JSON.stringify(argumentsValue);
+    const latestArguments = useRef(argumentsValue);
+    latestArguments.current = argumentsValue;
+
+    // The arguments are compared by value through `key`; the effect reads them from `latestArguments`.
+    useEffect(() => {
+        const argumentsForRun = latestArguments.current;
+        if (argumentsForRun === undefined) {
+            state.clear(query);
+            setResults(state.queryResults);
+            return undefined;
+        }
+
+        const controller = new AbortController();
+        const ticket = state.begin(query);
+        perform(query, argumentsForRun, controller.signal).then(
+            result => {
+                if (state.complete(ticket, result)) setResults(state.queryResults);
+            },
+            () => {
+                if (controller.signal.aborted || !state.complete(ticket, undefined)) return;
+                state.clear(query);
+                setResults(state.queryResults);
+            },
+        );
+
+        return () => controller.abort();
+    }, [key, perform, query, state]);
+
+    return results;
+}