@cratis/scene.react 4.13.0 → 4.14.0

package/navigation/DestinationResolution.ts

@@ -8,6 +8,9 @@ export interface DestinationResolution {
     url?: string;
     outlet?: string;
     dialog?: string;
+
+    /** The resolved route parameters, by name, before they are written into the URL. */
+    parameters: Record<string, string>;
     action: 'navigate' | 'openDialog' | 'openExternal';
     diagnostics: string[];
 }

package/navigation/DialogResult.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** What a dialog returned when it closed, for the screen that opened it. */
+export interface DialogResult {
+    dialog: string;
+    result?: unknown;
+}

package/navigation/SceneHistory.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneNavigationState } from './SceneNavigationState';
+
+/**
+ * The history a navigation host records its entries in. The browser implementation drives `window.history`,
+ * so deep links, refresh and the browser's back and forward buttons work; the memory implementation keeps
+ * the same stack for embedded and design-time hosts that do not own the address bar.
+ */
+export interface SceneHistory {
+    /** The current URL relative to the base path, or undefined at the base path itself. */
+    location(): string | undefined;
+
+    /** The state stored with the current entry, if the host wrote it. */
+    state(): SceneNavigationState | undefined;
+
+    push(state: SceneNavigationState): void;
+    replace(state: SceneNavigationState): void;
+    back(): void;
+
+    /** Called with the entry's URL and stored state after back or forward. Returns the unsubscribe function. */
+    listen(listener: (url: string | undefined, state: SceneNavigationState | undefined) => void): () => void;
+}

package/navigation/SceneNavigationContext.tsx

@@ -5,15 +5,30 @@ import { ReactNode, createContext, useContext } from 'react';
 import { BindingScope } from '@cratis/scene.engine';
 import { DestinationReference } from '@cratis/scene.model';
 import { DestinationResolution } from './DestinationResolution';
+import { DialogResult } from './DialogResult';
 
 export interface SceneNavigationContextValue {
     currentScreen: string;
     currentUrl?: string;
     currentOutlet?: string;
     currentDialog?: string;
+
+    /** The route parameters of the current entry - from the destination that opened it, or the deep link. */
+    currentParameters: Record<string, string>;
+
+    /** What the last dialog returned when it closed. */
+    dialogResult?: DialogResult;
+
+    /** A deep link that matched no route; the host fell back to its initial screen. */
+    unresolvedUrl?: string;
     bindingScope: BindingScope;
     navigate(destination: DestinationReference): DestinationResolution;
-    closeDialog(): void;
+
+    /** Closes the open dialog, returning to the entry that opened it, and records its result. */
+    closeDialog(result?: unknown): void;
+
+    /** Goes back one history entry. */
+    back(): void;
 }
 
 const Context = createContext<SceneNavigationContextValue | undefined>(undefined);

package/navigation/SceneNavigationHost.tsx

@@ -1,13 +1,17 @@
 // 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 { useMemo, useState } from 'react';
 import { BindingScope } from '@cratis/scene.engine';
-import { DestinationKind, DestinationReference, SceneElement } from '@cratis/scene.model';
+import { DestinationReference, SceneElement } from '@cratis/scene.model';
 import { SceneElementView } from '../SceneElementView';
 import { ComponentRegistry } from '../renderer';
-import { SceneNavigationContextValue, SceneNavigationProvider } from './SceneNavigationContext';
-import { resolveDestination } from './resolveDestination';
+import { createMemorySceneHistory } from './createMemorySceneHistory';
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationProvider } from './SceneNavigationContext';
+import { SceneRoute } from './SceneRoute';
+import { sceneRoutesFrom } from './sceneRoutesFrom';
+import { useSceneHistoryNavigation } from './useSceneHistoryNavigation';
 
 export interface SceneNavigationHostProps {
     screens: Record<string, SceneElement>;
@@ -15,52 +19,38 @@ export interface SceneNavigationHostProps {
     initialScreen: string;
     registry: ComponentRegistry;
     bindingScope?: BindingScope;
+
+    /**
+     * Where entries are recorded. `createBrowserSceneHistory()` drives the address bar, so deep links,
+     * refresh and back/forward work; the default is an in-memory history for embedded hosts.
+     */
+    history?: SceneHistory;
+
+    /** The destinations the application navigates to, so their route overrides can be deep linked. */
+    destinations?: DestinationReference[];
+
+    /** An explicit route table, used instead of the one derived from `screens` and `destinations`. */
+    routes?: SceneRoute[];
 }
 
 /**
  * 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.
+ * 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 = {} }: 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]);
+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 screen = screens[currentScreen];
-    const dialog = currentDialog ? dialogs[currentDialog] : undefined;
+    const screen = screens[value.currentScreen];
+    const dialog = value.currentDialog ? dialogs[value.currentDialog] : undefined;
 
     return <SceneNavigationProvider value={value}>
-        <div data-scene-outlet={currentOutlet ?? 'primary'} data-scene-url={currentUrl}>
+        <div data-scene-outlet={value.currentOutlet ?? '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' data-scene-dialog={currentDialog}>
+        {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>;

package/navigation/SceneNavigationState.ts

@@ -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.
+
+/**
+ * Where a navigation host is: the screen in its outlet, the URL that reaches it, the route parameters
+ * that URL carries and the dialog open on top of it. It is what a history entry stores, so back, forward
+ * and refresh restore exactly this.
+ */
+export interface SceneNavigationState {
+    screen: string;
+
+    /** The URL relative to the host's base path, as `resolveDestination` builds it. */
+    url?: string;
+    outlet?: string;
+    dialog?: string;
+
+    /** Route parameters, from the path template and the query string. */
+    parameters: Record<string, string>;
+}

package/navigation/SceneRoute.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One route a navigation host can be deep linked to: a template such as `sales/orders/{orderId}` and the
+ * screen, and optionally the outlet, it opens.
+ */
+export interface SceneRoute {
+    route: string;
+    screen: string;
+    outlet?: string;
+}

package/navigation/createBrowserSceneHistory.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationState } from './SceneNavigationState';
+
+/** The part of `window` the browser history needs, so a host can pass its own frame's window. */
+export type SceneBrowserWindow = Pick<Window, 'history' | 'location' | 'addEventListener' | 'removeEventListener'>;
+
+const stateKey = 'sceneNavigation';
+
+/**
+ * A history backed by the browser's `history` API under a base path such as `/app/`. Entries carry their
+ * navigation state, so back and forward restore the screen, outlet, parameters and dialog without
+ * re-resolving; an entry without state - a typed or bookmarked URL - is reported by URL alone.
+ */
+export function createBrowserSceneHistory(browser: SceneBrowserWindow = window, basePath = '/'): SceneHistory {
+    const base = basePath.endsWith('/') ? basePath : `${basePath}/`;
+    const href = (url: string | undefined) => `${base}${url ?? ''}`;
+    const location = () => {
+        const current = `${browser.location.pathname}${browser.location.search}`;
+        if (!current.startsWith(base)) return undefined;
+        const relative = current.substring(base.length);
+        return relative.length ? relative : undefined;
+    };
+    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));
+            browser.addEventListener('popstate', onPopState);
+            return () => browser.removeEventListener('popstate', onPopState);
+        },
+    };
+}

package/navigation/createMemorySceneHistory.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationState } from './SceneNavigationState';
+
+/**
+ * A history kept in memory with the same push, replace and back semantics as the browser's: pushing
+ * discards any forward entries, and going back notifies listeners. `forward` is exposed for hosts and specs
+ * that drive the stack themselves.
+ */
+export function createMemorySceneHistory(initialUrl?: string): SceneHistory & { forward(): void; entries(): SceneNavigationState[] } {
+    const entries: { url?: string; state?: SceneNavigationState }[] = [{ url: initialUrl }];
+    let index = 0;
+    const listeners = new Set<(url: string | undefined, state: SceneNavigationState | undefined) => void>();
+    const notify = () => listeners.forEach(listener => listener(entries[index].url, entries[index].state));
+
+    return {
+        location: () => entries[index].url,
+        state: () => entries[index].state,
+        push: state => {
+            entries.splice(index + 1, entries.length, { url: state.url, state });
+            index = entries.length - 1;
+        },
+        replace: state => {
+            entries[index] = { url: state.url, state };
+        },
+        back: () => {
+            if (index === 0) return;
+            index--;
+            notify();
+        },
+        forward: () => {
+            if (index === entries.length - 1) return;
+            index++;
+            notify();
+        },
+        entries: () => entries.map(entry => entry.state).filter((state): state is SceneNavigationState => state !== undefined),
+        listen: listener => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/navigation/index.ts

@@ -2,9 +2,18 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './DestinationResolution';
+export * from './DialogResult';
+export * from './SceneHistory';
 export * from './SceneNavigationContext';
 export * from './SceneNavigationHost';
-export * from './resolveDestination';
+export * from './SceneNavigationState';
+export * from './SceneRoute';
+export * from './createBrowserSceneHistory';
+export * from './createMemorySceneHistory';
 export * from './diagnoseRenderedNavigation';
 export * from './identityRoute';
+export * from './matchSceneRoute';
 export * from './navigationRouteKey';
+export * from './resolveDestination';
+export * from './sceneRoutesFrom';
+export * from './useSceneHistoryNavigation';

package/navigation/matchSceneRoute.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneRoute } from './SceneRoute';
+
+/** A URL matched to the route that opens it. */
+export interface SceneRouteMatch {
+    route: SceneRoute;
+    parameters: Record<string, string>;
+}
+
+/**
+ * Matches a URL - as a deep link, a refresh or a typed address delivers it - against route templates.
+ * `{name}` segments capture path parameters; the query string adds the rest. Literal segments win over
+ * parameters, so `orders/new` beats `orders/{orderId}`, and routes are otherwise tried in the given order.
+ */
+export function matchSceneRoute(url: string, routes: SceneRoute[]): SceneRouteMatch | undefined {
+    const [path, query = ''] = url.split('?', 2);
+    const segments = path.split('/').filter(segment => segment.length > 0).map(decodeURIComponent);
+    const queryParameters = Object.fromEntries(new URLSearchParams(query));
+
+    const candidates = routes
+        .map((route, order) => ({ route, order, template: route.route.split('/').filter(segment => segment.length > 0) }))
+        .filter(candidate => candidate.template.length === segments.length)
+        .sort((left, right) => literalCount(right.template) - literalCount(left.template) || left.order - right.order);
+
+    for (const { route, template } of candidates) {
+        const parameters: Record<string, string> = {};
+        const matches = template.every((part, index) => {
+            const name = /^\{([^}]+)\}$/.exec(part)?.[1];
+            if (name) {
+                parameters[name] = segments[index];
+                return true;
+            }
+            return part === segments[index];
+        });
+        if (matches) return { route, parameters: { ...queryParameters, ...parameters } };
+    }
+
+    return undefined;
+}
+
+function literalCount(template: string[]): number {
+    return template.filter(part => !/^\{[^}]+\}$/.test(part)).length;
+}

package/navigation/resolveDestination.ts

@@ -23,6 +23,7 @@ export function resolveDestination(destination: DestinationReference, scope: Bin
         url,
         outlet: destination.outlet,
         dialog: destination.dialog,
+        parameters: Object.fromEntries(parameters),
         action: kind === DestinationKind.Dialog ? 'openDialog' : kind === DestinationKind.External ? 'openExternal' : 'navigate',
         diagnostics,
     };

package/navigation/sceneRoutesFrom.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationKind, DestinationReference } from '@cratis/scene.model';
+import { identityRoute } from './identityRoute';
+import { SceneRoute } from './SceneRoute';
+
+/**
+ * The routes a host can deep link to: every screen at its own name, and every outlet destination at its
+ * authored route override or identity route. A destination listed earlier wins a route it shares with a
+ * later one, and authored overrides come before the screen-name defaults.
+ */
+export function sceneRoutesFrom(screens: string[], destinations: DestinationReference[] = []): SceneRoute[] {
+    const routes: SceneRoute[] = [];
+    for (const destination of destinations) {
+        const kind = destination.kind ?? (destination.dialog ? DestinationKind.Dialog : DestinationKind.Outlet);
+        const screen = destination.screen ?? destination.slice;
+        const route = destination.route ?? identityRoute(destination);
+        if (kind !== DestinationKind.Outlet || !screen || !route) continue;
+        routes.push({ route, screen, ...(destination.outlet ? { outlet: destination.outlet } : {}) });
+    }
+
+    return [...routes, ...screens.map(screen => ({ route: screen, screen }))];
+}

package/navigation/useSceneHistoryNavigation.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { BindingScope } from '@cratis/scene.engine';
+import { DestinationKind, DestinationReference } from '@cratis/scene.model';
+import { DialogResult } from './DialogResult';
+import { matchSceneRoute } from './matchSceneRoute';
+import { resolveDestination } from './resolveDestination';
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationContextValue } from './SceneNavigationContext';
+import { SceneNavigationState } from './SceneNavigationState';
+import { SceneRoute } from './SceneRoute';
+
+/**
+ * Keeps a navigation host's state in a {@link SceneHistory}: every navigation and every dialog is an entry,
+ * 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 {
+    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]);
+    const fallback = useMemo<SceneNavigationState>(() => ({ screen: initialScreen, url: initialScreen, parameters: {} }), [initialScreen]);
+
+    const [unresolvedUrl] = useState(() => {
+        const url = history.location();
+        return !history.state() && url && !fromLocation(url) ? url : undefined;
+    });
+    const [state, setState] = useState<SceneNavigationState>(() => history.state() ?? fromLocation(history.location()) ?? fallback);
+    const [dialogResult, setDialogResult] = useState<DialogResult>();
+
+    // Back and forward restore the stored entry, or match a URL the host never wrote against the current routes.
+    const restore = useRef((url: string | undefined, stored: SceneNavigationState | undefined) => stored ?? fromLocation(url) ?? fallback);
+    restore.current = (url, stored) => stored ?? fromLocation(url) ?? fallback;
+    const initialState = useRef(state);
+
+    // The current entry is written once, when a history is attached; later entries are written by navigate.
+    useEffect(() => {
+        history.replace(initialState.current);
+        return history.listen((url, stored) => setState(restore.current(url, stored)));
+    }, [history]);
+
+    const go = useCallback((next: SceneNavigationState) => {
+        history.push(next);
+        setState(next);
+    }, [history]);
+
+    const navigate = useCallback((destination: DestinationReference) => {
+        const resolution = resolveDestination(destination, bindingScope);
+        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 });
+        }
+
+        return resolution;
+    }, [bindingScope, go, state]);
+
+    const closeDialog = useCallback((result?: unknown) => {
+        if (!state.dialog) return;
+        setDialogResult({ dialog: state.dialog, result });
+        history.back();
+    }, [history, state.dialog]);
+
+    return useMemo(() => ({
+        currentScreen: state.screen,
+        currentUrl: state.url,
+        currentOutlet: state.outlet,
+        currentDialog: state.dialog,
+        currentParameters: state.parameters,
+        dialogResult,
+        unresolvedUrl,
+        bindingScope,
+        navigate,
+        closeDialog,
+        back: () => history.back(),
+    }), [bindingScope, closeDialog, dialogResult, history, navigate, state, unresolvedUrl]);
+}

package/package.json

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