@cratis/scene.blueprint.default 4.33.0 → 4.35.0

package/preview-host/ScenePreviewHost.tsx

@@ -0,0 +1,250 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { ApplicationStructure, NavigationModel, Screen, SliceKind, Theme } from '@cratis/scene.model';
+import { ApplicationStructureIndex, EffectiveNavItem, resolveToolbarButton } from '@cratis/scene.engine';
+import {
+    ComponentRegistry, SceneHistory, SceneThemeProvider, SliceCommandFieldsProvider, SliceCommandFieldsSource, SliceInvoker,
+    SliceInvokerProvider, createDryRunInvoker, createMemorySceneHistory, sliceDialogDestination, useSceneNavigation,
+} from '@cratis/scene.react';
+import { ComponentName } from '../ComponentName';
+import { externalComponent } from '../gallery/elements';
+import { LayoutName, SlotName } from '../layouts';
+import { previewProfile } from './previewProfile';
+import { ApplicationDocument } from './ApplicationDocument';
+import { ApplicationHost } from './ApplicationHost';
+import { CompositionOptions } from './composeApplication';
+import { diagnosePreview } from './diagnosePreview';
+import { PreviewProblem, PreviewProblemCode, PreviewProblemSeverity, hasBlockingProblem } from './PreviewProblem';
+import { PreviewProblemsView } from './PreviewProblemsView';
+import { PreviewSampleData, createPreviewSampleData } from './previewSampleData';
+import { findSliceFragment } from './PreviewSliceFragment';
+import { PreviewTarget } from './PreviewTarget';
+import { PreviewInvocation, PreviewToast } from './PreviewToast';
+import { PreviewPlan } from './resolvePreviewPlan';
+
+export interface ScenePreviewHostProps {
+    /** The document to preview - the in-memory one, unsaved edits included. */
+    document: ApplicationDocument;
+
+    /** The modules, features and slices of the application. */
+    structure: ApplicationStructure | ApplicationStructureIndex;
+
+    /** The application and module navigation regions; none when absent. */
+    navigation?: NavigationModel;
+
+    /** What to preview: a module, a feature or a slice. */
+    target: PreviewTarget;
+
+    /** The sample data to preview with; none when absent. */
+    sampleData?: PreviewSampleData;
+
+    /** The components to draw with. */
+    registry: ComponentRegistry;
+
+    /** What a submitted slice dialog goes through; a dry run, which only validates and reports, when absent (PRV5). */
+    invoker?: SliceInvoker;
+
+    /** Called for every dry run that passes validation, with what would have been sent. */
+    onInvoked?(invocation: PreviewInvocation): void;
+
+    /** The fields of a command, for the slice dialogs; the preview's sample rows fill their starting values. */
+    fieldsFor?: SliceCommandFieldsSource;
+
+    /** What the host decides about composition, such as the packages names resolve against. */
+    composition?: CompositionOptions;
+
+    /** The theme to apply; Studio passes the application's selected one (PRV9). */
+    theme?: Theme;
+
+    /** Hides a navigation item the preview user is not allowed to see. */
+    isVisible?(item: EffectiveNavItem): boolean;
+
+    /** Keeps the preview's navigation; an in-memory history by default, so a preview never touches the host's address (PRV4). */
+    history?: SceneHistory;
+
+    /** Called with the problems found - blocking or not - whenever they change (PRV8). */
+    onProblems?(problems: PreviewProblem[]): void;
+
+    /** Called when the author follows a problem to its node. */
+    onSelectProblem?(problem: PreviewProblem): void;
+
+    /** Called with what is being previewed, `Sales`, `Orders`, ... - the strip's breadcrumb (PRV7). */
+    onBreadcrumbChange?(breadcrumb: string[]): void;
+
+    /** Called when Escape is pressed with no dialog open: the host exits the preview (PRV7). */
+    onExit?(): void;
+
+    /** Extra content inside the host, such as a design layer's strip. */
+    children?: ReactNode;
+}
+
+const previewPageScreen = '#preview-page';
+const noNavigation: NavigationModel = { application: { regions: [] }, modules: [] };
+
+/** The page a slice preview happens over when its feature has no screen of its own, or a State View's fragment is shown. */
+function minimalPage(layout: string, content: Screen['slotContent'][string]): Screen {
+    return {
+        name: previewPageScreen,
+        layout,
+        slotContent: { [SlotName.Content]: content },
+        forms: [],
+        contributions: [],
+    };
+}
+
+/**
+ * Renders the effective application (spec 10, PRV1-PRV9) from an in-memory document: the real shell, its navigation regions, the
+ * first feature of a module, a feature, or a slice - a State Change slice as its task dialog over a minimal host page, a State View
+ * slice as its data fragment.
+ *
+ * - **One code path**: the composition and the host are the Stage's own (`composeApplicationScreen`, `ApplicationHost`); nothing
+ *   here draws a shell, a menu or a dialog (PRV9).
+ * - **Read-only**: no design affordances, no edits (PRV8) - a toolbar button without a slice shows no warning badge here; it is
+ *   reported as a problem instead. A model that cannot render - an unknown target, a feature without a screen,
+ *   a layout or template nobody provides - gives a {@link PreviewProblemsView} and `onProblems`, not a blank screen.
+ * - **Navigation** keeps to an in-memory history; a different module swaps the shell's effective navigation (PRV4).
+ * - **Dialogs** submit through the dry-run invoker unless one is given: validation runs, nothing is sent, a toast says so (PRV5).
+ * - **Data** is the active sample data pack's (PRV6); the same seed shows the same rows.
+ * - The strip (`Previewing`, sample data, `Exit preview · Esc`) is the host application's: this reports the breadcrumb and calls
+ *   `onExit` on Escape.
+ */
+export function ScenePreviewHost({
+    document: application, structure, navigation = noNavigation, target, sampleData, registry, invoker, onInvoked, fieldsFor, composition = {},
+    theme, isVisible, history, onProblems, onSelectProblem, onBreadcrumbChange, onExit, children,
+}: ScenePreviewHostProps) {
+    const index = useMemo(() => structure instanceof ApplicationStructureIndex ? structure : new ApplicationStructureIndex(structure), [structure]);
+    const compose = useMemo<CompositionOptions>(() => ({ logo: navigation.application.logo, ...composition }), [composition, navigation.application.logo]);
+    const diagnosis = useMemo(
+        () => diagnosePreview({ document: application, structure: index, navigation, target, packs: sampleData?.packs, composition: compose }),
+        [application, compose, index, navigation, sampleData?.packs, target]);
+
+    const problems = useMemo(() => {
+        const found = [...diagnosis.problems];
+        const { plan, screen } = diagnosis;
+        if (plan?.kind === 'stateView' && screen && plan.slice) {
+            const slice = index.findSlice(plan.slice);
+            if (slice && findSliceFragment(screen, plan.slice, slice).length === 0) {
+                found.push({ code: PreviewProblemCode.SliceFragmentMissing, severity: PreviewProblemSeverity.Warning, message: `Nothing on the screen '${screen.name}' is bound to the State View '${plan.slice}', so its page is shown.`, nodeId: plan.slice });
+            }
+        }
+
+        return found;
+    }, [diagnosis, index]);
+
+    const key = JSON.stringify(problems);
+    const reported = useRef<string | undefined>(undefined);
+    useEffect(() => {
+        if (reported.current === key) return;
+        reported.current = key;
+        onProblems?.(problems);
+    }, [key, onProblems, problems]);
+
+    const breadcrumb = diagnosis.plan?.breadcrumb;
+    const breadcrumbKey = breadcrumb?.join('\u0000');
+    useEffect(() => {
+        if (breadcrumb) onBreadcrumbChange?.(breadcrumb);
+        // `breadcrumbKey` is the value of `breadcrumb`.
+    }, [breadcrumbKey, onBreadcrumbChange]);
+
+    const [memoryHistory] = useState(() => createMemorySceneHistory());
+    const [toast, setToast] = useState<PreviewInvocation>();
+    const dryRun = useMemo(() => createDryRunInvoker({
+        onInvoked: invocation => {
+            setToast(invocation);
+            onInvoked?.(invocation);
+        },
+    }), [onInvoked]);
+
+    const samples = useMemo(() => createPreviewSampleData(application, sampleData), [application, sampleData]);
+    const fields = useMemo<SliceCommandFieldsSource>(() => (command, slice) => samples.commandFields(command, fieldsFor?.(command, slice) ?? []), [fieldsFor, samples]);
+
+    const page = useMemo(() => {
+        const { plan, screen } = diagnosis;
+        if (!plan) return undefined;
+
+        if (!screen) {
+            // A slice whose feature has no screen of its own: a minimal host page, headed with where it is.
+            if (plan.slice === undefined) return undefined;
+            const layout = previewProfile(application.uiProfiles).layout ?? LayoutName.AppShell;
+            const header = externalComponent('preview-page-header', ComponentName.PageHeader, { title: plan.breadcrumb.slice(0, -1).join(' › ') || plan.breadcrumb[0] });
+            return { screens: [...application.screens, minimalPage(layout, [header])], initial: previewPageScreen };
+        }
+
+        if (plan.kind === 'stateView' && plan.slice) {
+            const slice = index.findSlice(plan.slice);
+            const fragment = slice ? findSliceFragment(screen, plan.slice, slice) : [];
+            if (fragment.length > 0) return { screens: [...application.screens, minimalPage(screen.layout, fragment)], initial: previewPageScreen };
+        }
+
+        return { screens: application.screens, initial: screen.name };
+    }, [application.screens, application.uiProfiles, diagnosis, index]);
+
+    const hostApplication = useMemo(() => page ? { ...application, screens: page.screens } : application, [application, page]);
+    const navigationModel = useMemo(() => ({ structure: index, navigation, isVisible }), [index, isVisible, navigation]);
+
+    const onKeyDown = useCallback((event: KeyboardEvent) => {
+        if (event.key === 'Escape' && !event.defaultPrevented) onExit?.();
+    }, [onExit]);
+
+    if (hasBlockingProblem(problems) || !page) {
+        return <PreviewProblemsView problems={problems.filter(problem => problem.severity === PreviewProblemSeverity.Error)} onSelectProblem={onSelectProblem} />;
+    }
+
+    const body = (
+        <SliceInvokerProvider invoker={invoker ?? dryRun} warnEmptySlices={false}>
+            <SliceCommandFieldsProvider fieldsFor={fields}>
+                <div className='scene-preview-host' data-scene-preview={diagnosis.plan?.kind} data-preview-breadcrumb={breadcrumb?.join(' › ')}>
+                    <ApplicationHost
+                        application={hostApplication}
+                        composition={compose}
+                        navigationModel={navigationModel}
+                        registry={registry}
+                        initialScreen={page.initial}
+                        history={history ?? memoryHistory}
+                        resolveBinding={samples.resolveBinding}
+                        queryResults={samples.queryResults}>
+                        {diagnosis.plan?.kind === 'stateChange' && <OpenSliceDialog index={index} plan={diagnosis.plan} />}
+                        <EscapeToExit onKeyDown={onKeyDown} enabled={onExit !== undefined} />
+                        {toast && invoker === undefined && <PreviewToast invocation={toast} onDismiss={() => setToast(undefined)} />}
+                        {children}
+                    </ApplicationHost>
+                </div>
+            </SliceCommandFieldsProvider>
+        </SliceInvokerProvider>
+    );
+
+    return theme ? <SceneThemeProvider theme={theme}>{body}</SceneThemeProvider> : body;
+}
+
+/** Opens the task dialog of a State Change slice once the page is up - the slice preview (PRV3). */
+function OpenSliceDialog({ index, plan }: { index: ApplicationStructureIndex; plan: PreviewPlan }) {
+    const navigation = useSceneNavigation();
+    const opened = useRef(false);
+    useEffect(() => {
+        if (opened.current || plan.slice === undefined) return;
+        const slice = index.findSlice(plan.slice);
+        if (!slice || slice.kind !== SliceKind.StateChange) return;
+
+        const destination = sliceDialogDestination(resolveToolbarButton(index, { id: plan.slice, title: slice.name, slice: plan.slice }));
+        if (destination === undefined) return;
+        opened.current = true;
+        navigation.navigate(destination);
+    }, [index, navigation, plan.slice]);
+
+    return null;
+}
+
+/** Exits the preview on Escape, unless something - an open dialog - already used the key. */
+function EscapeToExit({ onKeyDown, enabled }: { onKeyDown(event: KeyboardEvent): void; enabled: boolean }) {
+    const navigation = useSceneNavigation();
+    const dialogOpen = navigation.currentDialog !== undefined;
+    useEffect(() => {
+        if (!enabled || dialogOpen) return undefined;
+        globalThis.addEventListener('keydown', onKeyDown);
+        return () => globalThis.removeEventListener('keydown', onKeyDown);
+    }, [dialogOpen, enabled, onKeyDown]);
+
+    return null;
+}

package/preview-host/composeApplication.ts

@@ -0,0 +1,273 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DestinationReference, DialogTemplate, EditingScopeKind, Form, Layout, SceneElement, Screen, ScreenTemplate, UiProfile,
+    type ApplicationLogo, type EffectiveConfiguration,
+} from '@cratis/scene.model';
+import {
+    DescriptorCatalog, PackageCatalog, resolveEffectiveConfiguration, resolveScreenTemplates, resolveTemplateChain,
+} from '@cratis/scene.engine';
+import { ComponentName } from '../ComponentName';
+import { externalComponent } from '../gallery/elements';
+import { resolveElementComponentNames } from '../gallery/resolveElementNames';
+import { galleryScreenTemplates } from '../gallery/screens';
+import { SlotName, defaultLayouts, shellComponentForLayout } from '../layouts';
+import { ApplicationDocument, completeDocument } from './ApplicationDocument';
+import { defaultApplicationChrome } from './defaultApplicationChrome';
+import { previewTemplateComponent } from './PreviewTemplate';
+import { blueprintPackageCatalog, previewProfile } from './previewProfile';
+
+/** What a host decides about how a screen is composed; everything else is the document's. */
+export interface CompositionOptions {
+    /** The profile names are resolved with; {@link previewProfile} of the document's profiles when absent. */
+    profile?: UiProfile;
+
+    /** What each package declares; the core and default blueprint packages when absent. */
+    catalog?: PackageCatalog;
+
+    /**
+     * The chrome the shell is given in its slots - topbar, sidebar, menu, breadcrumb, footer. Absent, the shell shows the
+     * application's navigation regions (`defaultApplicationChrome`). A full-page shell gets none of it unless the host says so.
+     */
+    chrome?(screen: Screen, shell: string): Record<string, SceneElement[]>;
+
+    /** The element a screen's form becomes; the Cratis `commandForm` component when absent. */
+    form?(screenName: string, form: Form): SceneElement;
+
+    /** Elements placed after the screen's content in the shell's content slot - Stage's status line. */
+    trailing?: SceneElement[];
+
+    /** A last pass over the composed tree before names are resolved - Stage binds data sources here. */
+    decorate?(element: SceneElement): SceneElement;
+
+    /** The templates the blueprint provides, for a screen that names one the document does not declare; the gallery's when absent. */
+    blueprintTemplates?: ScreenTemplate[];
+
+    /** The layouts the blueprint provides; the default blueprint's when absent. */
+    blueprintLayouts?: Layout[];
+
+    /** What each component exposes, so the templates' instance contributions can be resolved; without it no configuration is resolved. */
+    descriptors?: DescriptorCatalog;
+
+    /** The application's logo, shown in the default chrome's topbar. */
+    logo?: ApplicationLogo;
+}
+
+/** One screen composed for the application shell. */
+export interface ComposedScreen {
+    /** The shell with its chrome, the screen's template chain and the screen, names resolved. */
+    element: SceneElement;
+
+    /** What each scope configured on the components the templates contribute; absent when nothing was configured. */
+    configuration?: EffectiveConfiguration;
+
+    /** The templates around the screen, outermost first. */
+    templates: string[];
+}
+
+function previewCatalog(options: CompositionOptions): PackageCatalog {
+    return options.catalog ?? blueprintPackageCatalog;
+}
+
+function profileOf(application: ApplicationDocument, options: CompositionOptions): UiProfile {
+    return options.profile ?? previewProfile(application.uiProfiles);
+}
+
+function defaultForm(screenName: string, form: Form): SceneElement {
+    return externalComponent(`form-${screenName}-${form.name}`, 'commandForm', {
+        command: form.forCommand,
+        label: form.name,
+        generationMode: form.generationMode,
+        layout: form.layout,
+        fields: form.fields,
+    });
+}
+
+function mergeSlots(...sources: (Record<string, SceneElement[]> | undefined)[]): Record<string, SceneElement[]> {
+    const merged: Record<string, SceneElement[]> = {};
+    for (const source of sources) {
+        for (const [slot, elements] of Object.entries(source ?? {})) merged[slot] = [...(merged[slot] ?? []), ...elements];
+    }
+
+    return merged;
+}
+
+/** The layout a screen names: the document's own, or one the blueprint provides. */
+export function findLayout(application: ApplicationDocument, name: string, options: CompositionOptions = {}): Layout | undefined {
+    return application.layouts.find(candidate => candidate.name === name)
+        ?? (options.blueprintLayouts ?? defaultLayouts).find(candidate => candidate.name === name);
+}
+
+/**
+ * The templates a screen is composed with: the document's own, then the blueprint's for any name the document does not declare.
+ * A model that writes `template CrudList` without declaring it is naming one of the blueprint's templates; the document's
+ * own declaration always wins the name.
+ */
+export function templatesOf(application: ApplicationDocument, options: CompositionOptions = {}): ScreenTemplate[] {
+    const own = application.screenTemplates;
+    return [...own, ...(options.blueprintTemplates ?? galleryScreenTemplates).filter(template => !own.some(candidate => candidate.name === template.name))];
+}
+
+/**
+ * The templates a screen's template chain is worked out among: the document's own when the screen's template is one of them,
+ * otherwise the blueprint's as well. The blueprint's templates are never mixed into a document's own chain - several of them fit
+ * the same slot name, which would make every slot ambiguous.
+ */
+export function templatePoolFor(application: ApplicationDocument, screen: Screen, options: CompositionOptions = {}): ScreenTemplate[] {
+    return application.screenTemplates.some(candidate => candidate.name === screen.screenTemplate)
+        ? application.screenTemplates
+        : templatesOf(application, options);
+}
+
+/** The slot of the layout a template chain's outermost template fits: its declared slot, or `content`. */
+function layoutSlotOf(layout: Layout | undefined, outermost: ScreenTemplate): string {
+    const fits = outermost.fitsSlot;
+    if (fits === undefined) return SlotName.Content;
+    const slot = fits.includes('.') ? fits.slice(fits.lastIndexOf('.') + 1) : fits;
+    return layout === undefined || layout.slots.some(candidate => candidate.name === slot) ? slot : SlotName.Content;
+}
+
+/** The templates a screen's own template sits inside, outermost first, ending with the screen's own template. */
+export function templateChainOf(application: ApplicationDocument, screen: Screen, options: CompositionOptions = {}): ScreenTemplate[] {
+    if (!screen.screenTemplate) return [];
+    const templates = templatePoolFor(application, screen, options);
+    const own = templates.find(candidate => candidate.name === screen.screenTemplate);
+    if (!own) return [];
+
+    const layout = findLayout(application, screen.layout, options);
+    const placements = layout ? resolveScreenTemplates(layout, templates).placements : [];
+    const chain: ScreenTemplate[] = [own];
+    for (let guard = 0; guard <= templates.length; guard++) {
+        const placement = placements.find(candidate => candidate.template === chain[0].name);
+        if (!placement || placement.container === layout?.name) break;
+        const parent = templates.find(candidate => candidate.name === placement.container);
+        if (!parent || chain.includes(parent)) break;
+        chain.unshift(parent);
+    }
+
+    return chain;
+}
+
+/**
+ * What a screen puts in the shell's content slot: the screen - inside the template chain it names, when it names one - and the
+ * forms it hosts. The same content fills the shell on the primary region and a nested outlet.
+ *
+ * The innermost template takes the screen's own slot content; each template outside it holds the one inside in the slot it
+ * declared (`fitsSlot`), so the chain's arrangements all apply.
+ */
+export function screenContent(application: ApplicationDocument, screen: Screen, options: CompositionOptions = {}): { content: SceneElement[]; templates: string[]; slot: string } {
+    const form = options.form ?? defaultForm;
+    const forms = screen.forms.map(candidate => form(screen.name, candidate));
+    const chain = templateChainOf(application, screen, options);
+    if (chain.length === 0) {
+        return { content: [...Object.values(screen.slotContent).flat(), ...forms], templates: [], slot: SlotName.Content };
+    }
+
+    let inner: SceneElement | undefined;
+    for (let index = chain.length - 1; index >= 0; index--) {
+        const template = chain[index];
+        const slots = index === chain.length - 1
+            ? mergeSlots(template.content, screen.slotContent, { forms })
+            : mergeSlots(template.content, { [slotName(chain[index + 1])]: [inner!] });
+        inner = externalComponent(`template-${screen.name}-${template.name}`, previewTemplateComponent, { arrangement: template.arrangement }, slots);
+    }
+
+    const layout = findLayout(application, screen.layout, options);
+    return { content: [inner!], templates: chain.map(template => template.name), slot: layoutSlotOf(layout, chain[0]) };
+}
+
+function slotName(template: ScreenTemplate): string {
+    const fits = template.fitsSlot ?? SlotName.Content;
+    return fits.includes('.') ? fits.slice(fits.lastIndexOf('.') + 1) : fits;
+}
+
+function finish(element: SceneElement, profile: UiProfile, catalog: PackageCatalog, options: CompositionOptions): SceneElement {
+    const decorated = options.decorate ? options.decorate(element) : element;
+    return resolveElementComponentNames(decorated, profile, catalog);
+}
+
+/**
+ * Composes one screen the way the application shows it: the shell for the screen's layout, the chrome every screen shares in the
+ * shell's slots, and the screen - inside the template chain it names - in the slot the chain fits. Stage and the preview host
+ * both compose through this, so a screen is the same screen in both (spec PRV9, REN2).
+ *
+ * A layout the selected package set does not provide stays unresolved in the rendered tree: showing that missing component is
+ * deliberate, because silently substituting a default shell would hide a package/profile problem.
+ *
+ * @param application The document and profiles.
+ * @param screen The screen to compose.
+ * @param options What the host decides.
+ * @returns The element to render, the configuration its templates resolved, and the templates around the screen.
+ */
+export function composeApplicationScreen(application: ApplicationDocument, screen: Screen, options: CompositionOptions = {}): ComposedScreen {
+    const profile = profileOf(application, options);
+    const { content, templates, slot } = screenContent(application, screen, options);
+
+    const shell = shellComponentForLayout(screen.layout) ?? screen.layout;
+    const chrome = options.chrome
+        ? options.chrome(screen, shell)
+        : shell === ComponentName.FullPageShell ? {} : defaultApplicationChrome(options.logo);
+    const composed = externalComponent(`screen-${screen.name}`, shell, { screenName: screen.name }, {
+        ...chrome,
+        [slot]: [...(chrome[slot] ?? []), ...content, ...(slot === SlotName.Content ? options.trailing ?? [] : [])],
+    });
+
+    return { element: finish(composed, profile, previewCatalog(options), options), configuration: configurationOf(application, screen, options), templates };
+}
+
+/**
+ * A screen as it appears inside an outlet of another screen: its content alone, without the shell the primary region wraps
+ * every screen in, with the same name resolution.
+ */
+export function composeOutletScreen(application: ApplicationDocument, screen: Screen, options: CompositionOptions = {}): SceneElement {
+    const { content } = screenContent(application, screen, options);
+    const element = content.length === 1 ? content[0] : { id: `outlet-${screen.name}`, children: content } as unknown as SceneElement;
+    return finish(element, profileOf(application, options), previewCatalog(options), options);
+}
+
+/**
+ * A dialog template as it is shown over the application: its slot content inside the template wrapper, with the arrangement the
+ * template wrote, names resolved - the same wrapper a screen's template gets.
+ */
+export function composeDialog(application: ApplicationDocument, template: DialogTemplate, options: CompositionOptions = {}): SceneElement {
+    const element = externalComponent(`dialog-${template.name}`, previewTemplateComponent, { arrangement: template.arrangement }, template.content ?? {});
+    return finish(element, profileOf(application, options), previewCatalog(options), options);
+}
+
+function configurationOf(application: ApplicationDocument, screen: Screen, options: CompositionOptions): EffectiveConfiguration | undefined {
+    if (!options.descriptors || (application.instanceContributions ?? []).length === 0) return undefined;
+
+    const templates = templatesOf(application, options);
+    const document = { ...completeDocument(application), screenTemplates: templates, layouts: [...application.layouts, ...(options.blueprintLayouts ?? defaultLayouts).filter(layout => !application.layouts.some(own => own.name === layout.name))] };
+    const chain = resolveTemplateChain(document, { kind: EditingScopeKind.Screen, name: screen.name });
+    return resolveEffectiveConfiguration(chain, document.instanceContributions, options.descriptors);
+}
+
+/**
+ * Every destination the document authors - on actions, navigations, contributions and toolbar items - wherever it sits, so a
+ * route override on one of them can be deep linked.
+ */
+export function collectDestinations(application: ApplicationDocument): DestinationReference[] {
+    const found: DestinationReference[] = [];
+    const visit = (value: unknown) => {
+        if (value === null || typeof value !== 'object') return;
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+
+        for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+            if (key === 'destination' && entry !== null && typeof entry === 'object' && !Array.isArray(entry)) found.push(entry as DestinationReference);
+            visit(entry);
+        }
+    };
+
+    for (const screen of application.screens) {
+        visit(screen.slotContent);
+        visit(screen.contributions);
+    }
+
+    for (const template of [...application.screenTemplates, ...(application.dialogTemplates ?? [])]) visit(template.content);
+    return found;
+}

package/preview-host/defaultApplicationChrome.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ApplicationLogo } from '@cratis/scene.model';
+import type { SceneElement } from '@cratis/scene.model';
+import { ComponentName } from '../ComponentName';
+import { externalComponent } from '../gallery/elements';
+import { SlotName } from '../layouts';
+
+/**
+ * The chrome the application shell wraps every screen in when the model supplies navigation: a topbar and a sidebar. Neither
+ * carries items - each shows the effective navigation of its region (`NavigationRegionView`), so inherit/extend/override
+ * applies and nothing here knows the items. The logo is the application's (`navigation.application.logo`).
+ *
+ * @param logo The application's logo, when it has one.
+ * @returns The slot content to give the shell.
+ */
+export function defaultApplicationChrome(logo?: ApplicationLogo): Record<string, SceneElement[]> {
+    const slots: Record<string, SceneElement[]> = {};
+    if (logo) {
+        slots.logo = [externalComponent('topbar-logo', ComponentName.Logo, {
+            label: logo.title,
+            initials: logo.title.slice(0, 1).toUpperCase(),
+            lightImageUrl: logo.image || undefined,
+            targetScreen: '',
+        })];
+    }
+
+    return {
+        [SlotName.Topbar]: [externalComponent('topbar', ComponentName.Topbar, {}, slots)],
+        [SlotName.Sidebar]: [externalComponent('sidebar', ComponentName.Sidebar, {})],
+    };
+}