@cratis/scene.blueprint.default 0.1.0

package/gallery/authTemplates.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScreenTemplate } from '@cratis/scene.model';
+import { ComponentName } from '../ComponentName';
+import { SlotName } from '../layouts';
+import { TemplateSlotName } from './TemplateSlotName';
+import { button, card, externalComponent, text } from './elements';
+import { field, formActions } from './widgets';
+
+/**
+ * The six screens that stand between someone and the application: sign in, register, forgotten password,
+ * new password, verification and the lock screen.
+ *
+ * All six fit the full-page layout's `content` slot and fill its `aside` with the branding half. That
+ * split - a colored panel of brand next to a narrow column of form - is the shape the premium PrimeTek
+ * templates use for every one of them, and the reason it works is that it gives the form somewhere to be
+ * *small*, which is what a sign-in form should be.
+ */
+
+/** The branding half every authentication screen shares. */
+function brandingAside(id: string, headline: string, supporting: string) {
+    return [
+        externalComponent(`${id}-logo`, ComponentName.Logo, { label: 'Contoso', initials: 'C' }),
+        text(`${id}-headline`, headline),
+        text(`${id}-supporting`, supporting),
+    ];
+}
+
+/** Sign in. */
+export const loginTemplate: ScreenTemplate = {
+    name: 'Login',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('login', 'Welcome back', 'Everything your team shipped since you were last here is waiting.'),
+        [TemplateSlotName.Body]: [
+            card('login-card', [
+                text('login-title', 'Sign in'),
+                field('login-email', 'Email', 'inputText', { placeholder: 'you@contoso.com' }),
+                field('login-password', 'Password', 'password', { feedback: false }),
+                field('login-remember', 'Keep me signed in', 'checkbox', {}),
+                formActions('login-actions', 'Sign in', 'Use a different account'),
+                button('login-forgot', 'I forgot my password', { link: true, targetScreen: 'ForgotPassword' }),
+            ]),
+        ],
+    },
+    displayName: 'Sign in',
+    description: 'Email and password beside the branding panel.',
+};
+
+/** Register. */
+export const registerTemplate: ScreenTemplate = {
+    name: 'Register',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('register', 'Start in two minutes', 'No card, no call, no sales engineer. Just an account.'),
+        [TemplateSlotName.Body]: [
+            card('register-card', [
+                text('register-title', 'Create your account'),
+                field('register-name', 'Full name', 'inputText', {}),
+                field('register-email', 'Work email', 'inputText', { placeholder: 'you@contoso.com' }),
+                field('register-password', 'Password', 'password', { feedback: true }),
+                field('register-terms', 'I accept the terms of service', 'checkbox', {}),
+                formActions('register-actions', 'Create account', 'I already have one'),
+            ]),
+        ],
+    },
+    displayName: 'Register',
+    description: 'Account creation with a password strength meter and the terms checkbox.',
+};
+
+/** Forgotten password: ask for the address. */
+export const forgotPasswordTemplate: ScreenTemplate = {
+    name: 'ForgotPassword',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('forgot', 'It happens', 'Tell us the address you signed up with and we will send a link.'),
+        [TemplateSlotName.Body]: [
+            card('forgot-card', [
+                text('forgot-title', 'Reset your password'),
+                field('forgot-email', 'Email', 'inputText', { placeholder: 'you@contoso.com' }),
+                formActions('forgot-actions', 'Send the link', 'Back to sign in'),
+            ]),
+        ],
+    },
+    displayName: 'Forgotten password',
+    description: 'One field and one button - the whole point is that it asks for nothing else.',
+};
+
+/** New password: the other end of the link. */
+export const newPasswordTemplate: ScreenTemplate = {
+    name: 'NewPassword',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('new-password', 'Almost there', 'Choose something you have not used anywhere else.'),
+        [TemplateSlotName.Body]: [
+            card('new-password-card', [
+                text('new-password-title', 'Choose a new password'),
+                field('new-password-value', 'New password', 'password', { feedback: true }),
+                field('new-password-confirm', 'Confirm it', 'password', { feedback: false }),
+                formActions('new-password-actions', 'Set the password', 'Cancel'),
+            ]),
+        ],
+    },
+    displayName: 'New password',
+    description: 'Where a reset link lands: choose it, confirm it, done.',
+};
+
+/** Verification: the code from the email. */
+export const verificationTemplate: ScreenTemplate = {
+    name: 'Verification',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('verification', 'Check your email', 'We sent a six-digit code. It expires in ten minutes.'),
+        [TemplateSlotName.Body]: [
+            card('verification-card', [
+                text('verification-title', 'Enter the code'),
+                externalComponent('verification-steps', 'steps', { model: ['Account', 'Verify', 'Done'], activeIndex: 1 }),
+                field('verification-code', 'Six-digit code', 'inputText', { maxLength: 6 }),
+                formActions('verification-actions', 'Verify', 'Send it again'),
+            ]),
+        ],
+    },
+    displayName: 'Verification',
+    description: 'The code step, with the progress indicator that tells you how much is left.',
+};
+
+/** Lock screen: the session is still there, the person has to prove they are. */
+export const lockScreenTemplate: ScreenTemplate = {
+    name: 'LockScreen',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: SlotName.Aside }, { name: TemplateSlotName.Body }],
+    content: {
+        [SlotName.Aside]: brandingAside('lock', 'Locked', 'Your work is exactly where you left it.'),
+        [TemplateSlotName.Body]: [
+            card('lock-card', [
+                externalComponent('lock-avatar', 'avatar', { label: 'AN', size: 'xlarge', shape: 'circle' }),
+                text('lock-name', 'Amelia Nyquist'),
+                field('lock-password', 'Password', 'password', { feedback: false }),
+                formActions('lock-actions', 'Unlock', 'Sign in as someone else'),
+            ]),
+        ],
+    },
+    displayName: 'Lock screen',
+    description: 'One person, one password, and no way to lose what was open.',
+};
+
+/** The six authentication templates. */
+export const authTemplates: ScreenTemplate[] = [
+    loginTemplate,
+    registerTemplate,
+    forgotPasswordTemplate,
+    newPasswordTemplate,
+    verificationTemplate,
+    lockScreenTemplate,
+];

package/gallery/componentNames.ts

@@ -0,0 +1,55 @@
+// 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';
+import { isContentControl, isExternalComponent, isItemsControl, isPanel } from '@cratis/scene.engine';
+
+/**
+ * Every component name an element tree references.
+ *
+ * A blueprint's templates name components the blueprint itself does not provide - the widgets come from
+ * the component libraries it depends on - and a name no active package declares renders as a dashed red
+ * placeholder somewhere inside a screen, with nothing pointing back at the template that wrote it.
+ * Collecting the names up front is what lets that be a failed check at build or design time instead.
+ *
+ * The walk uses the engine's own kind guards rather than its own, so it visits exactly the branches the
+ * renderer visits and cannot drift from it.
+ *
+ * @param element The root to walk.
+ * @returns Every `componentName` found, in encounter order, with duplicates.
+ */
+export function componentNamesIn(element: SceneElement): string[] {
+    const names: string[] = [];
+
+    if (isExternalComponent(element)) {
+        names.push(element.componentName);
+        for (const children of Object.values(element.slots)) {
+            for (const child of children) {
+                names.push(...componentNamesIn(child));
+            }
+        }
+    }
+
+    if (isContentControl(element)) {
+        names.push(...componentNamesIn(element.content));
+    }
+
+    if (isItemsControl(element)) {
+        names.push(...componentNamesIn(element.itemTemplate));
+    }
+
+    if (isPanel(element)) {
+        for (const child of element.children) {
+            names.push(...componentNamesIn(child));
+        }
+    }
+
+    return names;
+}
+
+/**
+ * Every distinct component name a set of element trees references, sorted so a report of them is stable.
+ */
+export function distinctComponentNames(elements: SceneElement[]): string[] {
+    return [...new Set(elements.flatMap(componentNamesIn))].sort();
+}

package/gallery/composeScreen.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent, Layout, SceneElement, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { shellComponentForLayout } from '../layouts';
+import { externalComponent } from './elements';
+
+/**
+ * Turns a {@link ScreenTemplate}'s content into slot content on the {@link Layout} that contains it.
+ *
+ * The rule has two halves, and both matter. Content filed under a slot the *layout* also declares stays
+ * under that name - which is how a sign-in template's branding half reaches the full-page layout's `aside`
+ * region rather than being buried inside the form column. Everything else flows into the slot the
+ * template's `fitsSlot` names, because that is what `fitsSlot` means: this template occupies that region.
+ *
+ * @param template The template to place.
+ * @param layout The layout it is placed into.
+ * @returns Slot content keyed by the layout's own slot names.
+ */
+export function templateContentInLayout(template: ScreenTemplate, layout: Layout): Record<string, SceneElement[]> {
+    const layoutSlots = new Set(layout.slots.map(slot => slot.name));
+    const placed: Record<string, SceneElement[]> = {};
+    const ownSlotOrder = template.slots.map(slot => slot.name);
+    const content = template.content ?? {};
+
+    for (const slotName of ownSlotOrder) {
+        const elements = content[slotName];
+        if (!elements || elements.length === 0) {
+            continue;
+        }
+
+        const target = layoutSlots.has(slotName) ? slotName : template.fitsSlot;
+        if (!target) {
+            continue;
+        }
+
+        placed[target] = [...(placed[target] ?? []), ...elements];
+    }
+
+    return placed;
+}
+
+/**
+ * Folds a containment chain of screen templates into the outermost one.
+ *
+ * This is `fitsSlot` doing its job, applied repeatedly. A slice's template fits a slot on the feature's
+ * template, which fits a slot on the module's, which fits a slot on the application layout - so the way to
+ * place the slice is to place it in the feature, place *that* result in the module, and hand the module to
+ * the layout. Folding from the inside out means the rule is written once and the chain can be any depth.
+ *
+ * The alternative - filing a nested template's content under its own `fitsSlot` at the top level - looks
+ * right and is not: the layout has no `body` slot, so the content lands in a region nothing renders and
+ * the screen comes up empty with nothing to explain it.
+ *
+ * @param chain The templates from outermost to innermost. A chain of one is returned unchanged.
+ * @returns A template with the same slots and `fitsSlot` as the outermost, carrying the whole chain's content.
+ */
+export function nestScreenTemplates(chain: ScreenTemplate[]): ScreenTemplate {
+    return chain.reduceRight((inner, outer) => (inner === outer ? outer : placeInside(outer, inner)));
+}
+
+function placeInside(outer: ScreenTemplate, inner: ScreenTemplate): ScreenTemplate {
+    if (!inner.fitsSlot) {
+        return outer;
+    }
+
+    const innerContent = inner.slots.flatMap(slot => inner.content?.[slot.name] ?? []);
+    return {
+        ...outer,
+        content: {
+            ...outer.content,
+            [inner.fitsSlot]: [...(outer.content?.[inner.fitsSlot] ?? []), ...innerContent],
+        },
+    };
+}
+
+/**
+ * Builds the element tree that renders a {@link Screen}.
+ *
+ * The screen's slot content becomes the shell component's slots one-for-one, which is the whole trick: a
+ * layout's slots and a shell component's slots are the same vocabulary, so nothing has to translate
+ * between them and a slot filled under a name the shell does not read is a spec failure rather than a
+ * silently missing region.
+ *
+ * @param screen The screen to render.
+ * @returns The shell element, ready for `SceneElementView`.
+ */
+export function composeScreenElement(screen: Screen): ExternalComponent {
+    const shell = shellComponentForLayout(screen.layout);
+    if (!shell) {
+        throw new Error(`Screen '${screen.name}' names the layout '${screen.layout}', which this blueprint does not provide.`);
+    }
+
+    return externalComponent(`screen-${screen.name}`, shell, { screenName: screen.name }, screen.slotContent);
+}

package/gallery/dependencyComponentNames.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The component names the gallery borrows from this blueprint's dependencies.
+ *
+ * A screen template names components by their **bare** name and lets `resolveComponentName` pick the
+ * package, which is what makes a template portable across profiles. The cost is that a template can
+ * reference a name no active package declares, and the only symptom is a dashed red placeholder in the
+ * middle of an otherwise fine screen.
+ *
+ * Every name below was checked against the owning package's own manifest - `primeReactPackage.ts` and
+ * `cratisComponentsPackage.ts` - rather than assumed. Two that a dashboard obviously wants, `chart` and
+ * `fileUpload`, are deliberately absent from both, so the templates use what does exist (a table of
+ * figures, an image beside a button) rather than referencing something that would not render.
+ *
+ * This list exists because this package does not take an npm dependency on either of those packages - a
+ * blueprint declares its dependencies in its manifest, not in its bundler graph. When a host wires the
+ * real manifests together, it should resolve against those instead, and any name that drifted will fail
+ * this blueprint's specs immediately.
+ */
+
+/**
+ * Names borrowed from the `PrimeReact` package, each present in its declared component list.
+ *
+ * `menu`, `breadcrumb` and `sidebar` are here even though the gallery uses this blueprint's versions of
+ * them, because PrimeReact really does declare all three - and leaving them out would hide the shadowing
+ * that makes a blueprint's own shell components win those bare names.
+ */
+export const primeReactComponentNames: string[] = [
+    'avatar',
+    'breadcrumb',
+    'calendar',
+    'card',
+    'checkbox',
+    'column',
+    'dataTable',
+    'dropdown',
+    'image',
+    'menu',
+    'sidebar',
+    'inputNumber',
+    'inputText',
+    'inputTextarea',
+    'message',
+    'password',
+    'progressBar',
+    'steps',
+    'tag',
+    'text',
+    'timeline',
+];
+
+/**
+ * Names borrowed from the `Cratis.Components` package.
+ *
+ * Deliberately short. The gallery's templates are built from primitives so that they stay legible as
+ * *structure*; an application replaces a seeded table with a real `dataPage` bound to a query, and that is
+ * the point at which the Arc-bound composites earn their place.
+ */
+export const cratisComponentsNames: string[] = ['dataPage', 'observableDataTable', 'commandDialog', 'dialog'];
+
+/** The names `core` guarantees, regardless of which packages a profile lists. */
+export const coreComponentNames: string[] = ['text', 'button', 'card'];

package/gallery/dialogTemplates.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate } from '@cratis/scene.model';
+import { TemplateSlotName } from './TemplateSlotName';
+import { button, card, externalComponent, panel, text } from './elements';
+import { field } from './widgets';
+
+/**
+ * The three dialog shapes an application repeats: confirm something destructive, capture a short form, and
+ * show a record without leaving the list behind it.
+ *
+ * A dialog template has no `fitsSlot`, and that absence is the whole distinction. A screen template is
+ * *placed* - it fills a slot on whatever contains it, and the containment chain is what decides where it
+ * appears. A dialog is *summoned*: it opens over the application from wherever the code that opened it
+ * happens to be, so there is no parent slot for it to name.
+ */
+
+/** Confirm: one question, two answers, and enough context to answer it. */
+export const confirmDialogTemplate: DialogTemplate = {
+    name: 'ConfirmDialog',
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [text('confirm-title', 'Archive this product?')],
+        [TemplateSlotName.Body]: [
+            text('confirm-message', 'Bamboo Watch will stop appearing in the catalog. Existing orders keep it.'),
+            externalComponent('confirm-note', 'message', { severity: 'warn', text: 'This can be undone from the archive.' }),
+        ],
+        [TemplateSlotName.Actions]: [
+            panel('confirm-actions', [button('confirm-yes', 'Archive', { severity: 'danger' }), button('confirm-no', 'Keep it', { severity: 'secondary' })]),
+        ],
+    },
+    displayName: 'Confirmation dialog',
+    description: 'One question with the consequence spelled out, and a way back.',
+};
+
+/** Form: a short capture that does not deserve a page of its own. */
+export const formDialogTemplate: DialogTemplate = {
+    name: 'FormDialog',
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [text('form-dialog-title', 'Invite someone')],
+        [TemplateSlotName.Body]: [
+            field('form-dialog-email', 'Email', 'inputText', { placeholder: 'them@contoso.com' }),
+            field('form-dialog-role', 'Role', 'dropdown', { options: ['Viewer', 'Editor', 'Administrator'] }),
+            field('form-dialog-message', 'Message', 'inputTextarea', { rows: 3 }),
+        ],
+        [TemplateSlotName.Actions]: [
+            panel('form-dialog-actions', [button('form-dialog-send', 'Send invitation', { severity: 'primary' }), button('form-dialog-cancel', 'Cancel', { severity: 'secondary' })]),
+        ],
+    },
+    displayName: 'Form dialog',
+    description: 'A handful of fields captured without leaving the page underneath.',
+};
+
+/** Detail: a record shown over the list it came from. */
+export const detailDialogTemplate: DialogTemplate = {
+    name: 'DetailDialog',
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.SidePanel }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [text('detail-dialog-title', 'ORD-4192')],
+        [TemplateSlotName.Body]: [
+            card('detail-dialog-summary', [
+                text('detail-dialog-customer', 'Northwind Traders'),
+                text('detail-dialog-total', '$1,240.00'),
+                externalComponent('detail-dialog-status', 'tag', { value: 'Shipped', severity: 'success' }),
+            ]),
+        ],
+        [TemplateSlotName.SidePanel]: [externalComponent('detail-dialog-timeline', 'timeline', { align: 'left' })],
+        [TemplateSlotName.Actions]: [
+            panel('detail-dialog-actions', [button('detail-dialog-open', 'Open full record', { severity: 'primary', targetScreen: 'DetailView' }), button('detail-dialog-close', 'Close', { severity: 'secondary' })]),
+        ],
+    },
+    displayName: 'Detail dialog',
+    description: 'A record over the list it came from, with a route to the full page.',
+};
+
+/** The dialog templates this blueprint provides. */
+export const galleryDialogTemplates: DialogTemplate[] = [confirmDialogTemplate, formDialogTemplate, detailDialogTemplate];

package/gallery/elements.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent, HorizontalAlignment, Panel, SceneElement, VerticalAlignment, Visibility } from '@cratis/scene.model';
+
+/**
+ * Constructors for the element trees the gallery templates are built from.
+ *
+ * `ExternalComponent` inherits fifteen required members from `FrameworkElement` and `VisualElement` -
+ * visibility, opacity, z-index, both size constraints, margin and both alignments - before it gets to the
+ * two that matter to a template author. Written as object literals, a page of realistic content is
+ * ninety percent boilerplate and unreadable. These put the defaults in one place so a template reads as
+ * the tree it is.
+ */
+
+const elementDefaults = {
+    properties: {},
+    visibility: Visibility.Visible,
+    isEnabled: true,
+    opacity: 1,
+    size: {},
+    zIndex: 0,
+    minimumSize: {},
+    maximumSize: {},
+    margin: { left: 0, top: 0, right: 0, bottom: 0 },
+    horizontalAlignment: HorizontalAlignment.Stretch,
+    verticalAlignment: VerticalAlignment.Stretch,
+};
+
+/**
+ * An {@link ExternalComponent} naming a component by its **bare** name.
+ *
+ * Bare rather than package-qualified on purpose: `resolveComponentName` then decides which active package
+ * wins the name against the profile's priority order, so the same template renders with PrimeReact's
+ * widgets in one profile and somebody else's in another. A template that qualified its names would pin
+ * itself to one library and stop being a template.
+ */
+export function externalComponent(
+    id: string,
+    componentName: string,
+    properties: Record<string, unknown> = {},
+    slots: Record<string, SceneElement[]> = {},
+): ExternalComponent {
+    return { ...elementDefaults, id, name: id, properties, componentName, slots };
+}
+
+/** A {@link Panel} grouping children, for a row or column of content inside a slot. */
+export function panel(id: string, children: SceneElement[]): Panel {
+    return { ...elementDefaults, id, name: id, children };
+}
+
+/** A `core:text` run - the one component name guaranteed to resolve in every profile. */
+export function text(id: string, value: string): ExternalComponent {
+    return externalComponent(id, 'text', { text: value });
+}
+
+/** A `core:button`. */
+export function button(id: string, label: string, properties: Record<string, unknown> = {}): ExternalComponent {
+    return externalComponent(id, 'button', { label, ...properties });
+}
+
+/** A `core:card` wrapping content. */
+export function card(id: string, content: SceneElement[], properties: Record<string, unknown> = {}): ExternalComponent {
+    return externalComponent(id, 'card', properties, { content });
+}

package/gallery/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './elements';
+export * from './widgets';
+export * from './TemplateSlotName';
+export * from './NavigationEntry';
+export * from './navigation';
+export * from './applicationChrome';
+export * from './composeScreen';
+export * from './nesting';
+export * from './workspaceTemplates';
+export * from './supportTemplates';
+export * from './authTemplates';
+export * from './statusTemplates';
+export * from './dialogTemplates';
+export * from './screens';
+export * from './dependencyComponentNames';
+export * from './componentNames';
+export * from './previewProfile';
+export * from './resolveElementNames';
+export * from './GalleryScreenPreview';

package/gallery/navigation.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Contribution, SceneElement } from '@cratis/scene.model';
+import { ComponentName } from '../ComponentName';
+import { NavigationEntry } from './NavigationEntry';
+import { externalComponent } from './elements';
+
+/** The contribution point the built-in navigation aggregation reads. */
+export const navigationContributionPoint = 'Navigation';
+
+/**
+ * The gallery's navigation, declared once.
+ *
+ * One list, two consumers: the sidebar menu renders it as `menuItem` elements, and the same elements go to
+ * the `Navigation` contribution point where `aggregateContributions` + `extractNavigationItem` turn them
+ * back into navigation items. A blueprint that maintained a menu *and* a separate navigation declaration
+ * would have two lists that agree right up until someone adds a screen to one of them.
+ */
+export const navigationEntries: NavigationEntry[] = [
+    { label: 'Dashboard', targetScreen: 'Dashboard', icon: 'pi pi-home', group: 'Workspace', order: 10 },
+    { label: 'Products', targetScreen: 'CrudList', icon: 'pi pi-box', group: 'Workspace', order: 20 },
+    { label: 'Product detail', targetScreen: 'DetailView', icon: 'pi pi-file', group: 'Workspace', order: 30 },
+    { label: 'New product', targetScreen: 'FormPage', icon: 'pi pi-plus-circle', group: 'Workspace', order: 40 },
+    { label: 'Invoices', targetScreen: 'Invoice', icon: 'pi pi-receipt', group: 'Workspace', order: 50 },
+    { label: 'Nothing yet', targetScreen: 'Empty', icon: 'pi pi-inbox', group: 'Workspace', order: 60 },
+    { label: 'Users', targetScreen: 'UserManagement', icon: 'pi pi-users', group: 'Administration', order: 10 },
+    { label: 'Your profile', targetScreen: 'ProfileSettings', icon: 'pi pi-user', group: 'Administration', order: 20 },
+    { label: 'Documentation', targetScreen: 'Documentation', icon: 'pi pi-book', group: 'Support', order: 10 },
+    { label: 'Help', targetScreen: 'Help', icon: 'pi pi-question-circle', group: 'Support', order: 20 },
+];
+
+/**
+ * The element one navigation entry becomes.
+ *
+ * `routeParameterBindings` is present and empty rather than omitted, because that is what
+ * `extractNavigationItem` expects to read - and an omitted bag and an empty one are the same thing right
+ * up until something iterates it.
+ */
+export function navigationElement(entry: NavigationEntry, activeScreen?: string): SceneElement {
+    return externalComponent(`nav-${entry.targetScreen}`, ComponentName.MenuItem, {
+        label: entry.label,
+        targetScreen: entry.targetScreen,
+        routeParameterBindings: {},
+        order: entry.order,
+        group: entry.group,
+        icon: entry.icon,
+        isActive: entry.targetScreen === activeScreen,
+    });
+}
+
+/**
+ * The navigation as contributions to the `Navigation` contribution point.
+ *
+ * A screen carries these in its `contributions`, and anything bound to the contribution point recomputes
+ * from whatever is currently in scope - so a screen that contributes an extra entry gets it in the
+ * navigation without the navigation knowing that screen exists.
+ */
+export const navigationContributions: Contribution[] = navigationEntries.map(entry => ({
+    contributionPointName: navigationContributionPoint,
+    content: navigationElement(entry),
+    order: entry.order,
+}));
+
+/** The navigation entries of one group, in order. */
+export function entriesInGroup(group: string): NavigationEntry[] {
+    return navigationEntries.filter(entry => entry.group === group).sort((first, second) => first.order - second.order);
+}
+
+/** Every group named by the navigation, in first-declared order. */
+export const navigationGroups: string[] = [...new Set(navigationEntries.map(entry => entry.group))];