@cratis/scene.react 4.16.0 → 4.18.0

package/navigation/CoreOutlet.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useContext } from 'react';
+import { RegisteredComponentProps } from '../renderer/ComponentRegistry';
+import { SceneElementView } from '../SceneElementView';
+import { SceneNavigationContextInternal } from './SceneNavigationContext';
+import { useSceneOutlets } from './SceneOutletContext';
+
+/**
+ * A nested outlet a screen declares: `core:outlet` with a `name`. Inside a navigation host it renders the
+ * screen placed in that outlet - which may declare outlets of its own, so composition nests to any depth -
+ * and nothing while the outlet is empty. Outside a navigation host it renders the empty region.
+ */
+export function CoreOutlet({ element }: RegisteredComponentProps) {
+    const name = typeof element.properties.name === 'string' ? element.properties.name : '';
+    const navigation = useContext(SceneNavigationContextInternal);
+    const outlets = useSceneOutlets();
+    const placed = navigation?.outlets[name];
+    const screen = placed && outlets ? outlets.screens[placed] : undefined;
+
+    return <div data-scene-outlet={name} data-scene-outlet-screen={placed}>
+        {screen && outlets && <SceneElementView element={screen} registry={outlets.registry}
+            dataContext={navigation?.bindingScope.dataContext} queryResults={navigation?.bindingScope.queryResults} />}
+    </div>;
+}

package/navigation/SceneNavigationContext.tsx

@@ -8,7 +8,14 @@ import { DestinationResolution } from './DestinationResolution';
 import { DialogResult } from './DialogResult';
 
 export interface SceneNavigationContextValue {
+    /** The screen the last navigation opened. */
     currentScreen: string;
+
+    /** The screen in the primary region. */
+    primaryScreen: string;
+
+    /** Which screen each nested outlet shows, by outlet name. */
+    outlets: Record<string, string>;
     currentUrl?: string;
     currentOutlet?: string;
     currentDialog?: string;
@@ -33,6 +40,9 @@ export interface SceneNavigationContextValue {
 
 const Context = createContext<SceneNavigationContextValue | undefined>(undefined);
 
+/** The navigation context itself, for components that render outside a host as well as inside one. */
+export const SceneNavigationContextInternal = Context;
+
 export interface SceneNavigationProviderProps {
     value: SceneNavigationContextValue;
     children: ReactNode;

package/navigation/SceneNavigationHost.tsx

@@ -11,6 +11,8 @@ import { SceneHistory } from './SceneHistory';
 import { SceneNavigationProvider } from './SceneNavigationContext';
 import { SceneRoute } from './SceneRoute';
 import { sceneRoutesFrom } from './sceneRoutesFrom';
+import { collectOutletOwners } from './collectOutletOwners';
+import { SceneOutletContext } from './SceneOutletContext';
 import { useSceneHistoryNavigation } from './useSceneHistoryNavigation';
 
 export interface SceneNavigationHostProps {
@@ -34,24 +36,28 @@ export interface SceneNavigationHostProps {
 }
 
 /**
- * Executes Scene destinations against an in-memory rendered hierarchy: screen routes replace outlets,
+ * Executes Scene destinations against an in-memory rendered hierarchy: a destination into a nested outlet -
+ * one a screen declares with `core:outlet` - places its screen there and keeps the screens above it, to any
+ * depth; any other screen route replaces the primary region,
  * dialog destinations render dialog content over the screen that opened them, and external destinations
  * only report their resolved action. Every navigation is a history entry.
  */
 export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, registry, bindingScope = {}, history, destinations, routes }: SceneNavigationHostProps) {
     const [memoryHistory] = useState(() => createMemorySceneHistory());
     const routeTable = useMemo(() => routes ?? sceneRoutesFrom(Object.keys(screens), destinations), [destinations, routes, screens]);
-    const value = useSceneHistoryNavigation(history ?? memoryHistory, routeTable, initialScreen, bindingScope);
+    const outletOwners = useMemo(() => collectOutletOwners(screens), [screens]);
+    const value = useSceneHistoryNavigation(history ?? memoryHistory, routeTable, initialScreen, bindingScope, outletOwners, destinations);
+    const outletContext = useMemo(() => ({ screens, registry }), [registry, screens]);
 
-    const screen = screens[value.currentScreen];
+    const screen = screens[value.primaryScreen];
     const dialog = value.currentDialog ? dialogs[value.currentDialog] : undefined;
 
-    return <SceneNavigationProvider value={value}>
-        <div data-scene-outlet={value.currentOutlet ?? 'primary'} data-scene-url={value.currentUrl}>
+    return <SceneNavigationProvider value={value}><SceneOutletContext.Provider value={outletContext}>
+        <div data-scene-outlet={value.primaryScreen === value.currentScreen ? value.currentOutlet ?? 'primary' : 'primary'} data-scene-url={value.currentUrl}>
             {screen && <SceneElementView element={screen} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />}
         </div>
         {dialog && <div role='dialog' aria-modal='true' aria-label={value.currentDialog} data-scene-dialog={value.currentDialog}>
             <SceneElementView element={dialog} registry={registry} dataContext={bindingScope.dataContext} queryResults={bindingScope.queryResults} componentOutputs={bindingScope.componentOutputs} />
         </div>}
-    </SceneNavigationProvider>;
+    </SceneOutletContext.Provider></SceneNavigationProvider>;
 }

package/navigation/SceneNavigationState.ts

@@ -7,8 +7,21 @@
  * and refresh restore exactly this.
  */
 export interface SceneNavigationState {
+    /** The screen the last navigation opened - in the primary region or in a nested outlet. */
     screen: string;
 
+    /**
+     * The screen in the primary region. Absent means `screen`: a navigation into an outlet no rendered screen
+     * declares replaces the primary region, as before nested outlets existed.
+     */
+    primary?: string;
+
+    /**
+     * Which screen each nested outlet shows, by outlet name. An outlet is nested when a screen declares it with
+     * a `core:outlet` element; placing a screen there keeps every screen above it on the page.
+     */
+    outlets?: Record<string, string>;
+
     /** The URL relative to the host's base path, as `resolveDestination` builds it. */
     url?: string;
     outlet?: string;

package/navigation/SceneOutletContext.tsx

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createContext, useContext } from 'react';
+import { SceneElement } from '@cratis/scene.model';
+import { ComponentRegistry } from '../renderer';
+
+/** What a nested outlet needs to render the screen placed in it. */
+export interface SceneOutletContextValue {
+    screens: Record<string, SceneElement>;
+    registry: ComponentRegistry;
+}
+
+export const SceneOutletContext = createContext<SceneOutletContextValue | undefined>(undefined);
+
+/** The screens and registry of the enclosing navigation host, or undefined outside one. */
+export function useSceneOutlets(): SceneOutletContextValue | undefined {
+    return useContext(SceneOutletContext);
+}

package/navigation/collectOutletOwners.ts

@@ -0,0 +1,30 @@
+// 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';
+
+/** The registry key of the component that declares a nested outlet. */
+export const outletComponentName = 'core:outlet';
+
+/**
+ * Which screen declares each nested outlet: every `core:outlet` element, by its `name`, mapped to the screen
+ * whose tree contains it. A screen that declares an outlet another screen also declares keeps the first one,
+ * in screen order - the same rule navigation diagnostics report as a duplicate outlet.
+ */
+export function collectOutletOwners(screens: Record<string, SceneElement>): Record<string, string> {
+    const owners: Record<string, string> = {};
+    for (const [screen, element] of Object.entries(screens)) {
+        for (const outlet of outletNames(element)) {
+            if (!(outlet in owners)) owners[outlet] = screen;
+        }
+    }
+
+    return owners;
+}
+
+function outletNames(element: SceneElement): string[] {
+    const node = element as { componentName?: string; properties?: Record<string, unknown>; slots?: Record<string, SceneElement[]>; children?: SceneElement[] };
+    const own = node.componentName === outletComponentName && typeof node.properties?.name === 'string' ? [node.properties.name] : [];
+    const children = [...Object.values(node.slots ?? {}).flat(), ...(Array.isArray(node.children) ? node.children : [])];
+    return [...own, ...children.flatMap(outletNames)];
+}

package/navigation/index.ts

@@ -18,3 +18,7 @@ export * from './navigationRouteKey';
 export * from './resolveDestination';
 export * from './sceneRoutesFrom';
 export * from './useSceneHistoryNavigation';
+export * from './CoreOutlet';
+export * from './SceneOutletContext';
+export * from './collectOutletOwners';
+export * from './placeInOutlet';

package/navigation/placeInOutlet.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationReference } from '@cratis/scene.model';
+import { SceneNavigationState } from './SceneNavigationState';
+
+/** The most levels of nesting a placement follows before it stops, so a cyclic model cannot loop forever. */
+const maximumDepth = 32;
+
+/**
+ * Places a screen, recursively composing nested outlets.
+ *
+ * When `outlet` is a nested outlet - one a screen declares with `core:outlet` - the screen goes into it, and
+ * the screen that declares it is placed first: where it already is, or, when it is not on the page, where a
+ * known destination puts it, up to the primary region. Outlets declared by screens that are no longer on the
+ * page are dropped. Any other outlet replaces the primary region and clears every nested placement.
+ */
+export function placeInOutlet(
+    current: SceneNavigationState,
+    screen: string,
+    outlet: string | undefined,
+    owners: Record<string, string>,
+    destinations: DestinationReference[] = [],
+): Pick<SceneNavigationState, 'primary' | 'outlets'> {
+    const primary = current.primary ?? current.screen;
+    const placements: Record<string, string> = { ...(current.outlets ?? {}) };
+    let root = primary;
+
+    let target: { screen: string; outlet: string | undefined } | undefined = { screen, outlet };
+    for (let depth = 0; target && depth < maximumDepth; depth++) {
+        const owner = target.outlet === undefined ? undefined : owners[target.outlet];
+        if (owner === undefined) {
+            root = target.screen;
+            break;
+        }
+
+        placements[target.outlet!] = target.screen;
+        if (isOnPage(owner, root, placements, owners)) break;
+        target = { screen: owner, outlet: destinations.find(destination => destination.screen === owner && destination.outlet)?.outlet };
+    }
+
+    return { primary: root, outlets: reachable(root, placements, owners) };
+}
+
+/** Whether a screen is the root or shown in an outlet reachable from it. */
+function isOnPage(screen: string, root: string, placements: Record<string, string>, owners: Record<string, string>): boolean {
+    return screen === root || Object.values(reachable(root, placements, owners)).includes(screen);
+}
+
+/** Only the placements reachable from the root through the outlets each placed screen declares. */
+function reachable(root: string, placements: Record<string, string>, owners: Record<string, string>): Record<string, string> {
+    const kept: Record<string, string> = {};
+    const pending = [root];
+    const seen = new Set<string>();
+    while (pending.length > 0) {
+        const screen = pending.shift()!;
+        if (seen.has(screen)) continue;
+        seen.add(screen);
+        for (const [outlet, placed] of Object.entries(placements)) {
+            if (owners[outlet] === screen) {
+                kept[outlet] = placed;
+                pending.push(placed);
+            }
+        }
+    }
+
+    return kept;
+}

package/navigation/useSceneHistoryNavigation.ts

@@ -6,6 +6,7 @@ import { BindingScope } from '@cratis/scene.engine';
 import { DestinationKind, DestinationReference } from '@cratis/scene.model';
 import { DialogResult } from './DialogResult';
 import { matchSceneRoute } from './matchSceneRoute';
+import { placeInOutlet } from './placeInOutlet';
 import { resolveDestination } from './resolveDestination';
 import { SceneHistory } from './SceneHistory';
 import { SceneNavigationContextValue } from './SceneNavigationContext';
@@ -17,11 +18,21 @@ import { SceneRoute } from './SceneRoute';
  * so back and forward step through them, a refresh restores the stored entry, and a deep link is matched
  * against the route table. Closing a dialog goes back to the entry that opened it.
  */
-export function useSceneHistoryNavigation(history: SceneHistory, routes: SceneRoute[], initialScreen: string, bindingScope: BindingScope): SceneNavigationContextValue {
+export function useSceneHistoryNavigation(
+    history: SceneHistory,
+    routes: SceneRoute[],
+    initialScreen: string,
+    bindingScope: BindingScope,
+    outletOwners: Record<string, string> = {},
+    destinations: DestinationReference[] = [],
+): SceneNavigationContextValue {
     const fromLocation = useCallback((url: string | undefined): SceneNavigationState | undefined => {
         const match = url ? matchSceneRoute(url, routes) : undefined;
-        return match ? { screen: match.route.screen, url, outlet: match.route.outlet, parameters: match.parameters } : undefined;
-    }, [routes]);
+        if (!match) return undefined;
+        const start: SceneNavigationState = { screen: initialScreen, parameters: {} };
+        const placement = placeInOutlet(start, match.route.screen, match.route.outlet, outletOwners, destinations);
+        return { screen: match.route.screen, url, outlet: match.route.outlet, parameters: match.parameters, ...placement };
+    }, [destinations, initialScreen, outletOwners, routes]);
     const fallback = useMemo<SceneNavigationState>(() => ({ screen: initialScreen, url: initialScreen, parameters: {} }), [initialScreen]);
 
     const [unresolvedUrl] = useState(() => {
@@ -52,11 +63,13 @@ export function useSceneHistoryNavigation(history: SceneHistory, routes: SceneRo
         if (resolution.kind === DestinationKind.Dialog) {
             if (resolution.dialog) go({ ...state, dialog: resolution.dialog });
         } else if (resolution.kind !== DestinationKind.External) {
-            go({ screen: destination.screen ?? destination.slice ?? state.screen, url: resolution.url, outlet: resolution.outlet, parameters: resolution.parameters });
+            const screen = destination.screen ?? destination.slice ?? state.screen;
+            const placement = placeInOutlet(state, screen, resolution.outlet, outletOwners, destinations);
+            go({ screen, url: resolution.url, outlet: resolution.outlet, parameters: resolution.parameters, ...placement });
         }
 
         return resolution;
-    }, [bindingScope, go, state]);
+    }, [bindingScope, destinations, go, outletOwners, state]);
 
     const closeDialog = useCallback((result?: unknown) => {
         if (!state.dialog) return;
@@ -66,6 +79,8 @@ export function useSceneHistoryNavigation(history: SceneHistory, routes: SceneRo
 
     return useMemo(() => ({
         currentScreen: state.screen,
+        primaryScreen: state.primary ?? state.screen,
+        outlets: state.outlets ?? {},
         currentUrl: state.url,
         currentOutlet: state.outlet,
         currentDialog: state.dialog,

package/package.json

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

package/packages/ScenePackageBundle.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ComponentDescriptor, DialogTemplate, Layout, PackageKind, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
+import { ComponentDescriptor, DialogTemplate, Layout, PackageKind, PropertyDescriptor, PropertyValueType, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { IconLibraryBundle } from '../icons/IconLibraryBundle';
 import { ComponentRegistry } from '../renderer';
@@ -203,6 +203,34 @@ function validateIconLibrary(bundle: ScenePackageBundle): string[] {
     return problems;
 }
 
+function validateProperties(component: string, properties: PropertyDescriptor[], parent: string, problems: string[]): void {
+    const paths = new Set<string>();
+    for (const property of properties) {
+        const path = `${parent}${property.path}`;
+        if (paths.has(property.path)) {
+            problems.push(`'${component}' describes the property '${path}' more than once`);
+        }
+
+        paths.add(property.path);
+
+        if (property.valueType === PropertyValueType.Collection && property.item === undefined) {
+            problems.push(`'${component}' describes the collection '${path}' without describing its items`);
+        }
+
+        if (property.valueType === PropertyValueType.Collection && property.item !== undefined) {
+            validateProperties(component, property.item.properties, `${path}[].`, problems);
+        }
+
+        if (property.valueType === PropertyValueType.Object && property.properties !== undefined) {
+            validateProperties(component, property.properties, `${path}.`, problems);
+        }
+
+        if (property.valueType === PropertyValueType.Enum && (property.choices ?? []).length === 0) {
+            problems.push(`'${component}' describes the enum '${path}' without choices`);
+        }
+    }
+}
+
 function validateDescriptors(bundle: ScenePackageBundle): string[] {
     const problems: string[] = [];
     const declared = new Set(bundle.manifest.components.map((name) => componentRegistryKey(bundle.manifest.name, name)));
@@ -219,22 +247,7 @@ function validateDescriptors(bundle: ScenePackageBundle): string[] {
 
         described.add(descriptor.component);
 
-        const paths = new Set<string>();
-        for (const property of descriptor.properties) {
-            if (paths.has(property.path)) {
-                problems.push(`'${descriptor.component}' describes the property '${property.path}' more than once`);
-            }
-
-            paths.add(property.path);
-
-            if (property.valueType === PropertyValueType.Collection && property.item === undefined) {
-                problems.push(`'${descriptor.component}' describes the collection '${property.path}' without describing its items`);
-            }
-
-            if (property.valueType === PropertyValueType.Enum && (property.choices ?? []).length === 0) {
-                problems.push(`'${descriptor.component}' describes the enum '${property.path}' without choices`);
-            }
-        }
+        validateProperties(descriptor.component, descriptor.properties, '', problems);
     }
 
     return problems;