@cratis/scene.blueprint.default 4.27.0 → 4.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.blueprint.default",
-    "version": "4.27.0",
+    "version": "4.29.0",
     "description": "The default blueprint: application shell layouts, the screen and dialog templates that go inside them, the components that fill their slots, and two themes.",
     "keywords": [
         "cratis",
@@ -54,15 +54,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.27.0",
-        "@cratis/scene.model": "4.27.0",
-        "@cratis/scene.react": "4.27.0"
+        "@cratis/scene.engine": "4.29.0",
+        "@cratis/scene.model": "4.29.0",
+        "@cratis/scene.react": "4.29.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.27.0",
-        "@cratis/scene.model": "4.27.0",
-        "@cratis/scene.primereact": "4.27.0",
-        "@cratis/scene.react": "4.27.0",
+        "@cratis/scene.engine": "4.29.0",
+        "@cratis/scene.model": "4.29.0",
+        "@cratis/scene.primereact": "4.29.0",
+        "@cratis/scene.react": "4.29.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primeuix/themes": "^3.0.1",

package/shell/RegionNavigation.stories.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, within } from 'storybook/test';
+import { PrimeReactProvider } from '@primereact/core';
+import { ApplicationStructure, ExternalComponent, NavigationModel, NavigationRegionKind, NavigationRegionMode, SceneElement, Visibility } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '@cratis/scene.engine';
+import { CoreOutlet, RegisteredComponentProps, SceneNavigationHost } from '@cratis/scene.react';
+import { LayoutConfigProvider } from '../configuration';
+import { Sidebar } from './Sidebar';
+import { Topbar } from './Topbar';
+
+const structure = {
+    modules: [
+        { id: 'dashboard', name: 'Dashboard', features: [{ id: 'overview', name: 'Overview', features: [], slices: [] }] },
+        { id: 'sales', name: 'Sales', features: [{ id: 'orders', name: 'Orders', features: [{ id: 'returns', name: 'Returns', features: [], slices: [] }], slices: [] }, { id: 'customers', name: 'Customers', features: [], slices: [] }] },
+        { id: 'support', name: 'Support', features: [{ id: 'tickets', name: 'Tickets', features: [], slices: [] }, { id: 'kb', name: 'Knowledge base', features: [], slices: [] }] },
+    ],
+} as unknown as ApplicationStructure;
+
+const navigation: NavigationModel = {
+    application: { regions: [
+        { region: NavigationRegionKind.Topbar, items: [
+            { id: 'dashboard', title: 'Dashboard', target: { module: 'dashboard' } },
+            { id: 'sales', title: 'Sales', target: { module: 'sales' } },
+            { id: 'support', title: 'Support', target: { module: 'support' } },
+        ] },
+        { region: NavigationRegionKind.Sidebar, items: [{ id: 'dashboard', title: 'Dashboard', target: { module: 'dashboard', feature: 'overview' } }] },
+    ] },
+    modules: [
+        { module: 'sales', regions: [{ region: NavigationRegionKind.Sidebar, mode: NavigationRegionMode.Override, items: [
+            { id: 'orders', title: 'Orders', target: { module: 'sales', feature: 'orders' }, children: [{ id: 'returns', title: 'Returns', target: { module: 'sales', feature: 'orders.returns' } }] },
+            { id: 'customers', title: 'Customers', target: { module: 'sales', feature: 'customers' } },
+        ] }] },
+        { module: 'support', regions: [
+            { region: NavigationRegionKind.Topbar, mode: NavigationRegionMode.Extend, items: [{ id: 'help', title: 'Help center', target: { module: 'support', feature: 'kb' }, slot: 'side' }] },
+            { region: NavigationRegionKind.Sidebar, mode: NavigationRegionMode.Override, items: [
+                { id: 'tickets', title: 'Tickets', target: { module: 'support', feature: 'tickets' } },
+                { id: 'kb', title: 'Knowledge base', target: { module: 'support', feature: 'kb' }, slot: 'side' },
+            ] },
+        ] },
+    ],
+};
+
+const element = (id: string, componentName: string, properties: Record<string, unknown> = {}, content: SceneElement[] = []) =>
+    ({ id, componentName, properties, slots: content.length > 0 ? { content } : {}, visibility: Visibility.Visible }) as unknown as ExternalComponent;
+
+function Page({ element: page, slots }: RegisteredComponentProps) {
+    return <section style={{ padding: '1rem' }}><h2>{page.id}</h2>{slots.content}</section>;
+}
+
+const screens: Record<string, SceneElement> = {
+    'dashboard.overview': element('dashboard.overview', 'story:page'),
+    'sales.orders': element('sales.orders', 'story:page'),
+    'sales.orders.returns': element('sales.orders.returns', 'story:page'),
+    'sales.customers': element('sales.customers', 'story:page'),
+    'support.tickets': element('support.tickets', 'story:page', {}, [element('side', 'core:outlet', { name: 'side' })]),
+    'support.kb': element('support.kb', 'story:page'),
+};
+
+function Application({ initialScreen }: { initialScreen: string }) {
+    return <PrimeReactProvider><LayoutConfigProvider>
+        <SceneNavigationHost screens={screens} initialScreen={initialScreen} registry={{ 'story:page': Page, 'core:outlet': CoreOutlet }}
+            navigationModel={{ structure: new ApplicationStructureIndex(structure), navigation }}
+            frame={content => <div className='layout-wrapper layout-static'>
+                <div className='layout-topbar'><Topbar element={element('topbar', 'topbar')} slots={{}} /></div>
+                <div className='layout-sidebar'><Sidebar element={element('sidebar', 'sidebar')} slots={{}} /></div>
+                <div className='layout-content-wrapper'>{content}</div>
+            </div>} />
+    </LayoutConfigProvider></PrimeReactProvider>;
+}
+
+/**
+ * The topbar and sidebar of the shell showing the effective navigation of the module on the page: the application items, a
+ * module's own, hierarchical sidebar items, and items that render into a second slot.
+ */
+const meta = {
+    title: 'Blueprint/Navigation regions',
+    component: Application,
+    parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof Application>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A module whose sidebar replaces the application's and nests Returns under Orders. */
+export const HierarchicalSidebar: Story = { args: { initialScreen: 'sales.orders' } };
+
+/** Activating the Knowledge base item renders it into the side outlet while Tickets stays in the main one; both are active. */
+export const TwoSlots: Story = {
+    args: { initialScreen: 'support.tickets' },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getByRole('link', { name: 'Knowledge base' }));
+        await expect(canvasElement.querySelectorAll('.layout-region-sidebar [data-active="true"]').length).toBe(2);
+    },
+};

package/shell/RegionNavigation.tsx

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationRegionKind } from '@cratis/scene.model';
+import { NavigationRegionClassNames, NavigationRegionView, useSceneNavigationModel } from '@cratis/scene.react';
+
+/** The `layout-menu` vocabulary the shell's stylesheet already styles, so a region looks like the menu it replaces. */
+const classNames: Partial<NavigationRegionClassNames> = {
+    root: 'layout-region',
+    list: 'layout-menu',
+    item: 'layout-menu-item',
+    link: 'layout-menu-link',
+    icon: 'layout-menu-icon',
+    label: 'layout-menu-label',
+    toggle: 'layout-menu-toggle',
+    submenu: 'layout-submenu',
+};
+
+/** Whether a navigation model is in scope, so the topbar and sidebar have a region to show. */
+export function useHasRegionNavigation(): boolean {
+    return useSceneNavigationModel() !== undefined;
+}
+
+/**
+ * The navigation a shell's topbar or sidebar shows when the application supplies a navigation model: the effective items of
+ * its region - inherit/extend/override already applied - as the shell's menu, with the active item, the hierarchy and
+ * the keyboard behaviour of `NavigationRegionView`.
+ */
+export function RegionNavigation({ region, label }: { region: NavigationRegionKind; label?: string }) {
+    return <NavigationRegionView region={region} label={label} classNames={{ ...classNames, root: `layout-region layout-region-${region}` }} />;
+}

package/shell/Sidebar.tsx

@@ -4,7 +4,9 @@
 import { Button } from 'primereact/button';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { isPointerRevealMode, useLayoutConfig } from '../configuration';
-import { readString } from './elementProperties';
+import { NavigationRegionKind } from '@cratis/scene.model';
+import { readBoolean, readString } from './elementProperties';
+import { RegionNavigation, useHasRegionNavigation } from './RegionNavigation';
 
 /**
  * The sidebar's own chrome, inside the panel {@link AppShell} positions.
@@ -14,11 +16,15 @@ import { readString } from './elementProperties';
  * the shell; everything about *what is in it* belongs to the screen. A template can replace this header
  * wholesale without any of the mode CSS noticing.
  *
+ * When the application supplies a navigation model and the sidebar has no `content` of its own, the content is the effective
+ * navigation of the sidebar region for the module on the page (set `regionNavigation` to false to opt out).
+ *
  * The pin button only appears in `reveal` and `drawer`, the two modes where the sidebar answers to the
  * pointer and therefore needs a way to be made to stay.
  */
 export function Sidebar({ element, slots }: RegisteredComponentProps) {
     const { effectiveMode, config, toggleSidebarAnchor } = useLayoutConfig();
+    const hasRegion = useHasRegionNavigation();
     const title = readString(element, 'title');
     const isPinnable = isPointerRevealMode(effectiveMode);
 
@@ -40,7 +46,7 @@ export function Sidebar({ element, slots }: RegisteredComponentProps) {
                     </Button>
                 )}
             </div>
-            {slots.content}
+            {slots.content?.length ? slots.content : hasRegion && readBoolean(element, 'regionNavigation', true) ? <RegionNavigation region={NavigationRegionKind.Sidebar} label='Sidebar' /> : null}
         </>
     );
 }

package/shell/Topbar.tsx

@@ -4,7 +4,9 @@
 import { Button } from 'primereact/button';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { LayoutMode, useLayoutConfig } from '../configuration';
+import { NavigationRegionKind } from '@cratis/scene.model';
 import { readBoolean } from './elementProperties';
+import { RegionNavigation, useHasRegionNavigation } from './RegionNavigation';
 
 /**
  * The fixed strip across the top of the application shell.
@@ -13,12 +15,16 @@ import { readBoolean } from './elementProperties';
  * menu itself, which is why the menu arrives here as a slot rather than being hard-wired into the
  * sidebar - the same navigation markup has to be able to render in two places.
  *
+ * When the application supplies a navigation model and the topbar has no `menu` slot of its own, the menu is the effective
+ * navigation of the topbar region for the module on the page (set `regionNavigation` to false to opt out).
+ *
  * The toggle hides itself in the rail modes, where there is nothing to toggle: `slim`, `slim-plus` and
  * `compact` are always showing, `reveal` and `drawer` answer to the pointer and the pin, and `horizontal`
  * has no sidebar at all. A button that does nothing is worse than no button.
  */
 export function Topbar({ element, slots }: RegisteredComponentProps) {
     const { effectiveMode, config, toggleSidebar } = useLayoutConfig();
+    const hasRegion = useHasRegionNavigation();
     const showsToggle = readBoolean(element, 'showToggle', true) && togglesSidebar(effectiveMode);
 
     return (
@@ -39,7 +45,7 @@ export function Topbar({ element, slots }: RegisteredComponentProps) {
                 {slots.logo}
                 {slots.start}
             </div>
-            {slots.menu}
+            {slots.menu?.length ? slots.menu : hasRegion && readBoolean(element, 'regionNavigation', true) ? <RegionNavigation region={NavigationRegionKind.Topbar} label='Modules' /> : null}
             <div className='layout-topbar-end'>{slots.end}</div>
         </>
     );

package/shell/layout.css

@@ -825,3 +825,64 @@
         padding: 2rem;
     }
 }
+
+/* ---------------------------------------------------------------------------
+ * Navigation regions - the effective topbar / sidebar items of a NavigationRegionView.
+ * The renderer carries no design chrome; state is on data attributes.
+ * ------------------------------------------------------------------------ */
+
+.layout-region-topbar .layout-menu {
+    flex-direction: row;
+    flex-wrap: nowrap;
+    align-items: center;
+    gap: 0.25rem;
+}
+
+.layout-region-topbar .layout-menu-item[data-active='true'] > .layout-menu-link {
+    background: transparent;
+    color: inherit;
+    font-weight: 700;
+    border-radius: var(--layout-radius) var(--layout-radius) 0.5rem 0.5rem;
+    box-shadow: inset 0 -0.2rem 0 var(--layout-primary);
+}
+
+.layout-region-sidebar .layout-menu-item {
+    position: relative;
+}
+
+.layout-region-sidebar .layout-menu-item[data-active-descendant='true'] > .layout-menu-link {
+    font-weight: 600;
+}
+
+.layout-menu-toggle {
+    position: absolute;
+    inset-block-start: 0.35rem;
+    inset-inline-end: 0.5rem;
+    width: 1.75rem;
+    height: 1.75rem;
+    padding: 0;
+    color: inherit;
+    cursor: pointer;
+    background: transparent;
+    border: 0;
+    border-radius: var(--layout-radius);
+}
+
+.layout-menu-toggle::before {
+    content: '\25B8';
+    display: inline-block;
+    transition: transform var(--layout-transition);
+}
+
+.layout-menu-toggle[aria-expanded='true']::before {
+    transform: rotate(90deg);
+}
+
+.layout-menu-toggle:hover {
+    background: var(--layout-sidebar-hover);
+}
+
+.layout-menu-toggle:focus-visible {
+    outline: none;
+    box-shadow: var(--layout-focus-ring);
+}