@cratis/scene.react 4.14.0 → 4.16.0

package/navigation/createHashSceneHistory.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneBrowserWindow } from './createBrowserSceneHistory';
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationState } from './SceneNavigationState';
+
+const stateKey = 'sceneNavigation';
+
+/**
+ * A history kept in the URL fragment - `index.html#/WorkItemDetails?workItemId=B` - for hosts that are served
+ * as a single file or from a path they do not control, such as a generated runtime or a webview. It behaves
+ * like `createBrowserSceneHistory`: entries are pushed with their navigation state, back and forward restore
+ * them, and a typed or bookmarked fragment is matched by URL alone. A fragment changed by hand, which fires
+ * `hashchange` rather than `popstate`, is reported the same way.
+ */
+export function createHashSceneHistory(browser: SceneBrowserWindow = window): SceneHistory {
+    const location = () => {
+        const fragment = browser.location.hash.replace(/^#\/?/, '');
+        return fragment.length ? fragment : undefined;
+    };
+    const href = (url: string | undefined) => `${browser.location.pathname}${browser.location.search}#/${url ?? ''}`;
+    const stored = (value: unknown) => (value as Record<string, SceneNavigationState> | null)?.[stateKey];
+
+    return {
+        location,
+        state: () => stored(browser.history.state),
+        push: state => browser.history.pushState({ [stateKey]: state }, '', href(state.url)),
+        replace: state => browser.history.replaceState({ [stateKey]: state }, '', href(state.url)),
+        back: () => browser.history.back(),
+        listen: listener => {
+            const onPopState = (event: PopStateEvent) => listener(location(), stored(event.state));
+            const onHashChange = () => listener(location(), stored(browser.history.state));
+            browser.addEventListener('popstate', onPopState);
+            browser.addEventListener('hashchange', onHashChange);
+            return () => {
+                browser.removeEventListener('popstate', onPopState);
+                browser.removeEventListener('hashchange', onHashChange);
+            };
+        },
+    };
+}

package/navigation/index.ts

@@ -9,6 +9,7 @@ export * from './SceneNavigationHost';
 export * from './SceneNavigationState';
 export * from './SceneRoute';
 export * from './createBrowserSceneHistory';
+export * from './createHashSceneHistory';
 export * from './createMemorySceneHistory';
 export * from './diagnoseRenderedNavigation';
 export * from './identityRoute';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.14.0",
+    "version": "4.16.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.16.0",
+        "@cratis/scene.model": "4.16.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.14.0",
-        "@cratis/scene.model": "4.14.0",
+        "@cratis/scene.engine": "4.16.0",
+        "@cratis/scene.model": "4.16.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,8 @@ export * from './BindingOutputContext';
 export * from './ComponentRegistry';
 export * from './RenderBindingScopeContext';
 export * from './UnresolvedComponent';
+export * from './useBoundQuery';
+export * from './useValueOutput';
+export * from './valueOutputProperty';
 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;
+}

package/renderer/useValueOutput.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useRef } from 'react';
+import { ComponentBindingOutputs } from './BindingOutputContext';
+
+/** The output property an input widget publishes its current value under. */
+export const valueOutputName = 'value';
+
+/**
+ * Publishes an input widget's current value as its `value` output: once when it mounts, with the initial
+ * value, and again on every change. Other elements bind to it with a `componentProperty` binding, and a
+ * command action maps it as `component.<id>.value`. The renderer clears the output when the widget unmounts.
+ *
+ * Values are published as JSON-compatible data so both engines read the same thing: a `Date` is published
+ * as its ISO 8601 string, and `undefined` as `null`.
+ */
+export function useValueOutput(bindingOutputs: ComponentBindingOutputs | undefined, value: unknown): void {
+    const published = value instanceof Date ? value.toISOString() : value ?? null;
+    const key = JSON.stringify(published);
+    const latest = useRef(published);
+    latest.current = published;
+
+    // Published by value through `key`: a new array or object with the same content is not a change.
+    useEffect(() => {
+        bindingOutputs?.setOutput(valueOutputName, latest.current);
+    }, [bindingOutputs, key]);
+}

package/renderer/valueOutputProperty.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 { BindingMode, PropertyDescriptor, PropertyValueType } from '@cratis/scene.model';
+import { valueOutputName } from './useValueOutput';
+
+/**
+ * The descriptor entry an input widget declares for the value it publishes with `useValueOutput`, so a
+ * designer can offer it as a binding source - for a detail component, a query argument or a command input.
+ *
+ * @param valueType The type of value the widget publishes.
+ * @param description What the value is, when the default sentence does not say enough.
+ */
+export function valueOutputProperty(valueType: PropertyValueType, description = 'What the user has entered, published as the input changes.'): PropertyDescriptor {
+    return {
+        path: valueOutputName,
+        label: 'Value',
+        group: 'Outputs',
+        valueType,
+        readOnly: true,
+        output: true,
+        bindingMode: BindingMode.OneWay,
+        description,
+    };
+}