@cratis/scene.react 4.27.0 → 4.29.0

package/navigation/SceneNavigationHost.tsx

@@ -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 { useMemo, useState } from 'react';
+import { ReactNode, useMemo, useState } from 'react';
 import { BindingScope } from '@cratis/scene.engine';
 import { DestinationReference, SceneElement } from '@cratis/scene.model';
 import { SceneElementView } from '../SceneElementView';
@@ -14,6 +14,9 @@ import { sceneRoutesFrom } from './sceneRoutesFrom';
 import { collectOutletOwners } from './collectOutletOwners';
 import { SceneOutletContext } from './SceneOutletContext';
 import { useSceneHistoryNavigation } from './useSceneHistoryNavigation';
+import { SceneNavigationModel } from './region/SceneNavigationModel';
+import { SceneNavigationModelProvider } from './region/SceneNavigationModelContext';
+import { navigationDestinations } from './region/navigationDestinations';
 
 export interface SceneNavigationHostProps {
     screens: Record<string, SceneElement>;
@@ -31,6 +34,18 @@ export interface SceneNavigationHostProps {
     /** The destinations the application navigates to, so their route overrides can be deep linked. */
     destinations?: DestinationReference[];
 
+    /**
+     * The application's structure and navigation. Navigation regions rendered inside the host (`NavigationRegionView`) read it,
+     * and - when `destinations` is not given - the destinations of every navigation item become the deep-linkable ones.
+     */
+    navigationModel?: SceneNavigationModel;
+
+    /**
+     * Wraps the primary outlet in the application's chrome - a topbar, a sidebar, a toolbar. The chrome is part of the host,
+     * so it stays mounted while the screens inside it change and navigation regions keep their state.
+     */
+    frame?(content: ReactNode): ReactNode;
+
     /** An explicit route table, used instead of the one derived from `screens` and `destinations`. */
     routes?: SceneRoute[];
 }
@@ -42,7 +57,10 @@ export interface SceneNavigationHostProps {
  * 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) {
+export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, registry, bindingScope = {}, history, destinations: authoredDestinations, routes, navigationModel, frame }: SceneNavigationHostProps) {
+    const destinations = useMemo(
+        () => authoredDestinations ?? (navigationModel ? navigationDestinations(navigationModel.structure, navigationModel.navigation, navigationModel.screenFor) : undefined),
+        [authoredDestinations, navigationModel]);
     const [memoryHistory] = useState(() => createMemorySceneHistory());
     const routeTable = useMemo(() => routes ?? sceneRoutesFrom(Object.keys(screens), destinations), [destinations, routes, screens]);
     const outletOwners = useMemo(() => collectOutletOwners(screens), [screens]);
@@ -52,12 +70,15 @@ export function SceneNavigationHost({ screens, dialogs = {}, initialScreen, regi
     const screen = screens[value.primaryScreen];
     const dialog = value.currentDialog ? dialogs[value.currentDialog] : undefined;
 
-    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>
+    const outlet = <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>;
+    const page = <SceneNavigationProvider value={value}><SceneOutletContext.Provider value={outletContext}>
+        {frame ? frame(outlet) : outlet}
         {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>}
     </SceneOutletContext.Provider></SceneNavigationProvider>;
+
+    return navigationModel ? <SceneNavigationModelProvider model={navigationModel}>{page}</SceneNavigationModelProvider> : page;
 }

package/navigation/index.ts

@@ -22,3 +22,11 @@ export * from './CoreOutlet';
 export * from './SceneOutletContext';
 export * from './collectOutletOwners';
 export * from './placeInOutlet';
+export * from './region/SceneNavigationModel';
+export * from './region/SceneNavigationModelContext';
+export * from './region/NavigationRegionClassNames';
+export * from './region/NavigationRegionView';
+export * from './region/currentModuleOf';
+export * from './region/navigationItemActive';
+export * from './region/navigationItemDestination';
+export * from './region/navigationDestinations';

package/navigation/region/NavigationRegionClassNames.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+
+/**
+ * The class names a {@link NavigationRegionView} puts on its nodes. The renderer carries no look of its own: a package
+ * gives the nodes its vocabulary (`blueprint.default` uses its `layout-menu` classes) and a stylesheet does the rest.
+ * State is always on data attributes as well - `data-active`, `data-expanded`, `data-read-only`, `data-origin`.
+ */
+export interface NavigationRegionClassNames {
+    /** The `nav` landmark. */
+    root: string;
+
+    /** Each list of items. */
+    list: string;
+
+    /** Each item's `li`. */
+    item: string;
+
+    /** The link of an item. */
+    link: string;
+
+    /** The icon of an item. */
+    icon: string;
+
+    /** The title of an item. */
+    label: string;
+
+    /** The button that expands or collapses an item's sub-items. */
+    toggle: string;
+
+    /** The list of an item's sub-items. */
+    submenu: string;
+}
+
+/** The class names used when a host passes none. */
+export const defaultNavigationRegionClassNames: NavigationRegionClassNames = {
+    root: 'scene-nav',
+    list: 'scene-nav-list',
+    item: 'scene-nav-item',
+    link: 'scene-nav-link',
+    icon: 'scene-nav-icon',
+    label: 'scene-nav-label',
+    toggle: 'scene-nav-toggle',
+    submenu: 'scene-nav-submenu',
+};

package/navigation/region/NavigationRegionView.tsx

@@ -0,0 +1,234 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { KeyboardEvent, MouseEvent, ReactNode, useContext, useMemo, useRef, useState } from 'react';
+import { DestinationReference, NavigationRegionKind, parseIconReference } from '@cratis/scene.model';
+import { ApplicationStructureIndex, EffectiveNavItem, EffectiveNavigationRegion, effectiveNavigation } from '@cratis/scene.engine';
+import { SceneIcon } from '../../icons/SceneIcon';
+import { useIconAdapters } from '../../icons/IconAdapterContext';
+import { resolveDestination } from '../resolveDestination';
+import { SceneNavigationContextInternal } from '../SceneNavigationContext';
+import { NavigationRegionClassNames, defaultNavigationRegionClassNames } from './NavigationRegionClassNames';
+import { SceneNavigationModel } from './SceneNavigationModel';
+import { useSceneNavigationModel } from './SceneNavigationModelContext';
+import { currentModuleOf } from './currentModuleOf';
+import { navigationItemActive } from './navigationItemActive';
+import { defaultScreenFor, navigationItemDestination } from './navigationItemDestination';
+
+export interface NavigationRegionViewProps {
+    /** Which region to show. */
+    region: NavigationRegionKind;
+
+    /**
+     * The module to show the region of. When absent the region follows the module of the screen on the page, so
+     * navigating to another module recomputes the effective items in place; outside every module it is the application's.
+     */
+    module?: string;
+
+    /** Pins the region to the application level, whatever screen is on the page. */
+    application?: boolean;
+
+    /** What to resolve against; the {@link SceneNavigationModelProvider}'s when absent. */
+    model?: SceneNavigationModel;
+
+    /**
+     * Which sub-items of a sidebar show: only those of the parents of the active item and of items the user expanded
+     * (`active`, the default), or all of them (`all`) - a design layer wants the whole hierarchy.
+     */
+    expand?: 'active' | 'all';
+
+    /** The accessible name of the `nav` landmark. */
+    label?: string;
+
+    /** The class names to put on the nodes. */
+    classNames?: Partial<NavigationRegionClassNames>;
+
+    /**
+     * Draws an item's icon from its qualified reference. By default the icon is drawn through the adapters of the
+     * enclosing `IconAdapterProvider`, or not at all without one.
+     */
+    renderIcon?(icon: string): ReactNode;
+
+    /**
+     * Content a host adds to an item after its title - Studio design mode draws the lock of an inherited item here; Stage
+     * ignores it. The item carries `origin` and `readOnly`.
+     */
+    renderAdornment?(item: EffectiveNavItem): ReactNode;
+
+    /** The href of an item's link, for opening it in a new tab; the hash route of the destination by default. */
+    hrefFor?(destination: DestinationReference, url: string | undefined): string | undefined;
+
+    /** Called after an item has been activated and the host has navigated. */
+    onActivate?(item: EffectiveNavItem, destination: DestinationReference): void;
+}
+
+function itemKey(path: string[]): string {
+    return path.join('/');
+}
+
+function containsActive(item: EffectiveNavItem, isActive: (item: EffectiveNavItem) => boolean): boolean {
+    return isActive(item) || (item.children ?? []).some(child => containsActive(child, isActive));
+}
+
+/**
+ * Renders the effective navigation of one region - a topbar or a sidebar - for the application or a module.
+ *
+ * - **Items** come from `effectiveNavigation`, so inherit/extend/override is already applied; nothing here re-implements
+ *   it. A topbar is flat; a sidebar nests, collapses, and expands the parents of the active item.
+ * - **Active state** follows what the navigation host shows: an item is active (`aria-current`, `data-active`) when the
+ *   screen it opens is the one in its slot, so items rendering into different slots are active at once.
+ * - **Activation** goes through the enclosing navigation host (`navigate`), which renders the target in the item's slot -
+ *   the `outlet` of the destination; outside a host it announces `cratis.scene.navigate`.
+ * - **Authorization**: `isVisible` of the model hides items, it does not disable them.
+ * - **Keyboard**: arrows (left/right in a topbar, up/down in a sidebar), Home and End move between items; in a sidebar
+ *   right expands and left collapses (or goes to the parent).
+ *
+ * Nothing here draws design chrome: items carry `data-read-only` and `data-origin` for a design layer to style.
+ */
+export function NavigationRegionView({ region, module, application = false, model: modelProp, label, expand = 'active', classNames, renderIcon, renderAdornment, hrefFor, onActivate }: NavigationRegionViewProps) {
+    const contextModel = useSceneNavigationModel();
+    const model = modelProp ?? contextModel;
+    if (!model) throw new Error('NavigationRegionView needs a navigation model: pass `model` or render it inside a SceneNavigationModelProvider.');
+
+    const navigation = useContext(SceneNavigationContextInternal);
+    const adapters = useIconAdapters();
+    const names = { ...defaultNavigationRegionClassNames, ...classNames };
+    const index = useMemo(() => model.structure instanceof ApplicationStructureIndex ? model.structure : new ApplicationStructureIndex(model.structure), [model.structure]);
+    const screenFor = model.screenFor ?? defaultScreenFor;
+
+    const sidebar = region === NavigationRegionKind.Sidebar;
+    const placement = useMemo(() => ({ primaryScreen: navigation?.primaryScreen, outlets: navigation?.outlets ?? {} }), [navigation?.outlets, navigation?.primaryScreen]);
+    const scope = application ? undefined : module ?? currentModuleOf(index, placement.primaryScreen);
+    const resolved: EffectiveNavigationRegion = useMemo(() => effectiveNavigation(index, model.navigation, scope, region), [index, model.navigation, scope, region]);
+
+    const isActive = (item: EffectiveNavItem) => placement.primaryScreen !== undefined && navigationItemActive(item, { primaryScreen: placement.primaryScreen, outlets: placement.outlets }, screenFor, !sidebar);
+    const isVisible = model.isVisible ?? (() => true);
+    const visible = useMemo(() => {
+        const keep = (items: EffectiveNavItem[]): EffectiveNavItem[] => items.filter(isVisible).map(item => item.children ? { ...item, children: keep(item.children) } : item);
+        return keep(resolved.items);
+    }, [resolved, model.isVisible]);
+
+    const activeKey = JSON.stringify([placement.primaryScreen, placement.outlets, scope]);
+    const [toggled, setToggled] = useState<{ key: string; state: Record<string, boolean> }>({ key: activeKey, state: {} });
+    const overrides = toggled.key === activeKey ? toggled.state : {};
+    const [focused, setFocused] = useState<string>();
+    const root = useRef<HTMLElement>(null);
+
+    const isExpanded = (item: EffectiveNavItem, key: string) => overrides[key] ?? (expand === 'all' || containsActive(item, isActive));
+    const toggle = (key: string, expanded: boolean) => setToggled({ key: activeKey, state: { ...overrides, [key]: expanded } });
+
+    const activate = (item: EffectiveNavItem) => {
+        const destination = navigationItemDestination(item, screenFor);
+        if (destination === undefined) return;
+        if (navigation) {
+            navigation.navigate(destination);
+        } else {
+            globalThis.dispatchEvent(new CustomEvent('cratis.scene.navigate', { detail: { targetScreen: destination.screen ?? '', destination, item } }));
+        }
+
+        onActivate?.(item, destination);
+    };
+
+    const links = () => Array.from(root.current?.querySelectorAll<HTMLElement>('[data-scene-nav-link]') ?? []);
+    const focusLink = (element: HTMLElement | undefined) => {
+        if (!element) return;
+        setFocused(element.getAttribute('data-scene-nav-link') ?? undefined);
+        element.focus();
+    };
+
+    const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+        const all = links();
+        const position = all.findIndex(link => link === document.activeElement);
+        if (position < 0) return;
+        const next = sidebar ? 'ArrowDown' : 'ArrowRight';
+        const previous = sidebar ? 'ArrowUp' : 'ArrowLeft';
+        const current = all[position];
+        const key = current.getAttribute('data-scene-nav-link')!;
+        const owner = current.closest('[data-scene-nav-item]') as HTMLElement | null;
+        const hasChildren = owner?.getAttribute('data-scene-nav-parent') === 'true';
+        const expanded = owner?.getAttribute('data-expanded') === 'true';
+
+        let target: HTMLElement | undefined;
+        if (event.key === next) target = all[Math.min(position + 1, all.length - 1)];
+        else if (event.key === previous) target = all[Math.max(position - 1, 0)];
+        else if (event.key === 'Home') target = all[0];
+        else if (event.key === 'End') target = all[all.length - 1];
+        else if (sidebar && event.key === 'ArrowRight' && hasChildren) {
+            if (!expanded) toggle(key, true);
+            else target = all[position + 1];
+        } else if (sidebar && event.key === 'ArrowLeft') {
+            if (hasChildren && expanded) toggle(key, false);
+            else {
+                const parent = owner?.parentElement?.closest('[data-scene-nav-item]')?.querySelector<HTMLElement>(':scope > [data-scene-nav-link]');
+                if (parent) target = parent;
+            }
+        } else return;
+
+        event.preventDefault();
+        focusLink(target);
+    };
+
+    const tabStop = focused ?? undefined;
+    const firstActive = (items: EffectiveNavItem[], path: string[]): string | undefined => {
+        for (const item of items) {
+            const key = itemKey([...path, item.id]);
+            if (isActive(item)) return key;
+            const inner = firstActive(item.children ?? [], [...path, item.id]);
+            if (inner !== undefined && isExpanded(item, key)) return inner;
+        }
+
+        return undefined;
+    };
+    const firstKey = visible.length > 0 ? itemKey([visible[0].id]) : undefined;
+    const stop = tabStop ?? firstActive(visible, []) ?? firstKey;
+
+    const icon = (item: EffectiveNavItem) => {
+        if (item.icon === undefined) return null;
+        const drawn = renderIcon ? renderIcon(item.icon) : adapters ? (() => {
+            const reference = parseIconReference(item.icon!);
+            return reference ? <SceneIcon reference={reference} adapters={adapters} /> : null;
+        })() : null;
+        return drawn === null ? null : <span className={names.icon} aria-hidden='true' data-scene-icon={item.icon}>{drawn}</span>;
+    };
+
+    const renderItems = (items: EffectiveNavItem[], path: string[], level: number): ReactNode => items.map(item => {
+        const key = itemKey([...path, item.id]);
+        const destination = navigationItemDestination(item, screenFor);
+        const active = isActive(item);
+        const children = item.children ?? [];
+        const parent = sidebar && children.length > 0;
+        const expanded = parent && isExpanded(item, key);
+        const url = destination ? resolveDestination(destination).url : undefined;
+        const href = destination ? (hrefFor ? hrefFor(destination, url) : url ? `#/${url}` : undefined) : undefined;
+        const onClick = (event: MouseEvent) => {
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0) return;
+            event.preventDefault();
+            if (destination) activate(item);
+            else if (parent) toggle(key, !expanded);
+        };
+        const content = <>
+            {icon(item)}
+            <span className={names.label}>{item.title}</span>
+            {renderAdornment?.(item)}
+        </>;
+
+        return <li key={item.id} className={names.item} data-scene-nav-item={item.id} data-scene-nav-parent={parent ? 'true' : undefined}
+            data-active={active} data-active-descendant={!active && parent && children.some(child => containsActive(child, isActive)) ? true : undefined} data-expanded={parent ? expanded : undefined} data-origin={item.origin} data-read-only={item.readOnly}
+            data-slot={item.slot} data-level={level}>
+            {destination || parent
+                ? <a className={names.link} href={href ?? '#'} data-scene-nav-link={key} aria-current={active ? 'page' : undefined}
+                    aria-expanded={parent && !destination ? expanded : undefined} tabIndex={key === stop ? 0 : -1}
+                    onClick={onClick} onFocus={() => setFocused(key)}>{content}</a>
+                : <span className={names.link} aria-disabled='true' data-scene-nav-link={key} tabIndex={-1}>{content}</span>}
+            {parent && <button type='button' className={names.toggle} tabIndex={-1} aria-expanded={expanded} aria-controls={`${key}-items`}
+                aria-label={`${expanded ? 'Collapse' : 'Expand'} ${item.title}`} onClick={() => toggle(key, !expanded)} />}
+            {parent && expanded && <ul id={`${key}-items`} className={`${names.list} ${names.submenu}`}>{renderItems(children, [...path, item.id], level + 1)}</ul>}
+        </li>;
+    });
+
+    return <nav ref={root} className={names.root} aria-label={label ?? (sidebar ? 'Sidebar' : 'Topbar')} data-scene-nav-region={region}
+        data-scene-nav-sources={resolved.sources.kind} data-scene-nav-sources-label={resolved.sources.label} data-scene-nav-module={scope}
+        data-scene-nav-mode={resolved.mode} onKeyDown={onKeyDown}>
+        <ul className={names.list}>{renderItems(visible, [], 0)}</ul>
+    </nav>;
+}

package/navigation/region/SceneNavigationModel.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructure, NavigationModel } from '@cratis/scene.model';
+import { ApplicationStructureIndex, EffectiveNavItem } from '@cratis/scene.engine';
+
+/**
+ * What a navigation region needs to resolve the items it shows: the application's structure and its navigation, and
+ * the two hooks a host plugs.
+ */
+export interface SceneNavigationModel {
+    /** The modules, features and slices of the application. */
+    structure: ApplicationStructure | ApplicationStructureIndex;
+
+    /** The application and module navigation regions. */
+    navigation: NavigationModel;
+
+    /**
+     * The name of the screen an item opens. Defaults to the qualified id of the feature the item resolves to
+     * (`sales.orders`), which is how `ApplicationStructure` names a feature's screen.
+     */
+    screenFor?(item: EffectiveNavItem): string | undefined;
+
+    /**
+     * Whether an item is shown. An item for which this answers false is hidden, not disabled - Stage plugs permissions
+     * here. Applies to every level of a hierarchical region; hiding a parent hides its children.
+     */
+    isVisible?(item: EffectiveNavItem): boolean;
+}

package/navigation/region/SceneNavigationModelContext.tsx

@@ -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 { ReactNode, createContext, useContext } from 'react';
+import { SceneNavigationModel } from './SceneNavigationModel';
+
+const Context = createContext<SceneNavigationModel | undefined>(undefined);
+
+export interface SceneNavigationModelProviderProps {
+    model: SceneNavigationModel;
+    children?: ReactNode;
+}
+
+/**
+ * Supplies the application structure and navigation every navigation region below it renders - the topbar and sidebar
+ * components of a shell find what to show here, so a screen document does not carry the application's navigation.
+ */
+export function SceneNavigationModelProvider({ model, children }: SceneNavigationModelProviderProps) {
+    return <Context.Provider value={model}>{children}</Context.Provider>;
+}
+
+/** The navigation model in scope, or undefined outside a {@link SceneNavigationModelProvider}. */
+export function useSceneNavigationModel(): SceneNavigationModel | undefined {
+    return useContext(Context);
+}

package/navigation/region/currentModuleOf.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructureIndex } from '@cratis/scene.engine';
+
+/**
+ * The module the screen on the page belongs to: the screen's qualified id starts with its module id, so `sales.orders`
+ * is in `sales`. Undefined for a screen outside every module - the application level.
+ */
+export function currentModuleOf(index: ApplicationStructureIndex, screen: string | undefined): string | undefined {
+    if (screen === undefined) return undefined;
+    const module = screen.split('.')[0];
+    return index.findModule(module) ? module : undefined;
+}

package/navigation/region/navigationDestinations.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructure, DestinationReference, NavigationRegionKind, NavigationModel } from '@cratis/scene.model';
+import { ApplicationStructureIndex, EffectiveNavItem, effectiveNavigation } from '@cratis/scene.engine';
+import { navigationItemDestination } from './navigationItemDestination';
+
+function flatten(items: EffectiveNavItem[]): EffectiveNavItem[] {
+    return items.flatMap(item => [item, ...flatten(item.children ?? [])]);
+}
+
+/**
+ * Every destination the navigation of the application and of each module can lead to, once each: what a
+ * `SceneNavigationHost` is given as `destinations` so deep links to a navigation item resolve, and an item that renders
+ * into a nested outlet is placed with the screen that declares the outlet.
+ */
+export function navigationDestinations(
+    structure: ApplicationStructure | ApplicationStructureIndex,
+    navigation: NavigationModel,
+    screenFor?: (item: EffectiveNavItem) => string | undefined,
+): DestinationReference[] {
+    const index = structure instanceof ApplicationStructureIndex ? structure : new ApplicationStructureIndex(structure);
+    const modules = [undefined, ...index.structure.modules.map(module => module.id)];
+    const seen = new Set<string>();
+    const destinations: DestinationReference[] = [];
+
+    for (const module of modules) {
+        for (const region of [NavigationRegionKind.Topbar, NavigationRegionKind.Sidebar]) {
+            for (const item of flatten(effectiveNavigation(index, navigation, module, region).items)) {
+                const destination = navigationItemDestination(item, screenFor);
+                if (destination === undefined) continue;
+                const key = JSON.stringify(destination);
+                if (seen.has(key)) continue;
+                seen.add(key);
+                destinations.push(destination);
+            }
+        }
+    }
+
+    return destinations;
+}

package/navigation/region/navigationItemActive.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EffectiveNavItem, primarySlot } from '@cratis/scene.engine';
+import { defaultScreenFor } from './navigationItemDestination';
+import { SceneNavigationContextValue } from '../SceneNavigationContext';
+
+/** Where the navigation host is: the part of {@link SceneNavigationContextValue} that says what is on the page. */
+export type NavigationPlacement = Pick<SceneNavigationContextValue, 'primaryScreen' | 'outlets'>;
+
+/**
+ * Whether a navigation item is the one the page shows.
+ *
+ * An item is active when the screen it opens is the one in the slot it renders into: the primary region for the
+ * `content` slot, the nested outlet of that name otherwise. So several items can be active at once - each is shown in
+ * its own slot - and closing a slot's screen un-highlights its item. With `matchModule` - a topbar - an item that targets
+ * a module without a feature is also active while any screen of that module is in its slot.
+ *
+ * @param item The effective item.
+ * @param placement What the host currently shows.
+ * @param screenFor Names the screen an item opens; the feature the item resolves to when absent.
+ * @param matchModule Whether a module item is active on any screen of the module; a topbar's are, a sidebar's are not.
+ */
+export function navigationItemActive(
+    item: EffectiveNavItem,
+    placement: NavigationPlacement,
+    screenFor: (item: EffectiveNavItem) => string | undefined = defaultScreenFor,
+    matchModule = false,
+): boolean {
+    const screen = screenFor(item);
+    if (screen === undefined) return false;
+
+    const shown = item.slot === primarySlot ? placement.primaryScreen : placement.outlets[item.slot];
+    if (shown === undefined) return false;
+    if (shown === screen) return true;
+
+    const target = item.target;
+    return matchModule && target !== undefined && target.feature === undefined && shown.startsWith(`${target.module}.`);
+}

package/navigation/region/navigationItemDestination.ts

@@ -0,0 +1,29 @@
+// 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 { EffectiveNavItem, primarySlot } from '@cratis/scene.engine';
+
+/** The screen an item opens by default: the qualified id of the feature it resolves to. */
+export function defaultScreenFor(item: EffectiveNavItem): string | undefined {
+    return item.target?.resolvedFeature;
+}
+
+/**
+ * Where activating a navigation item goes: its stable module/feature identity, the screen it opens, and the slot it
+ * renders into as the outlet - the primary `content` slot is the host's primary outlet.
+ *
+ * @param item The effective item.
+ * @param screenFor Names the screen an item opens; {@link defaultScreenFor} when absent.
+ * @returns The destination, or undefined when the item leads nowhere.
+ */
+export function navigationItemDestination(item: EffectiveNavItem, screenFor: (item: EffectiveNavItem) => string | undefined = defaultScreenFor): DestinationReference | undefined {
+    const screen = screenFor(item);
+    if (screen === undefined || item.target === undefined) return undefined;
+
+    const resolved = item.target.resolvedFeature;
+    const destination: DestinationReference = { kind: DestinationKind.Outlet, module: item.target.module, screen };
+    if (resolved !== undefined && resolved.startsWith(`${item.target.module}.`)) destination.feature = resolved.substring(item.target.module.length + 1);
+    if (item.slot !== primarySlot) destination.outlet = item.slot;
+    return destination;
+}

package/package.json

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