@cratis/scene.blueprint.default 0.1.0

package/shell/AppShell.tsx

@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { LayoutConfigProvider, isPointerRevealMode, useLayoutConfig, useOptionalLayoutConfig } from '../configuration';
+import { SlotName } from '../layouts';
+import { LayoutMask } from './Mask';
+
+/**
+ * The application shell: the `AppShell` layout's slots, positioned.
+ *
+ * This owns the positioned boxes - the fixed topbar, the sliding sidebar panel, the pushed main column -
+ * while the components filling the slots own what goes inside them. Splitting it there is what lets a
+ * screen replace the entire menu without knowing anything about how `reveal` mode translates the panel it
+ * lives in.
+ *
+ * It puts a {@link LayoutConfigProvider} around itself when a host has not, because a gallery preview
+ * hands the renderer one `appShell` element and nothing else, and the shell still has to be able to
+ * switch modes.
+ */
+export function AppShell({ element, slots }: RegisteredComponentProps) {
+    const surface = <AppShellSurface elementId={element.id} slots={slots} />;
+    return useOptionalLayoutConfig() ? surface : <LayoutConfigProvider>{surface}</LayoutConfigProvider>;
+}
+
+interface AppShellSurfaceProps {
+    elementId: string;
+    slots: Record<string, ReactNode[]>;
+}
+
+function AppShellSurface({ elementId, slots }: AppShellSurfaceProps) {
+    const { config, effectiveMode, wrapperClasses, setSidebarRevealed } = useLayoutConfig();
+    const revealsOnPointer = isPointerRevealMode(effectiveMode);
+    const hasSidebar = filled(slots, SlotName.Sidebar) || filled(slots, SlotName.Menu);
+
+    return (
+        <div className={wrapperClasses.join(' ')} data-scene-id={elementId} data-layout-mode={config.mode}>
+            {filled(slots, SlotName.Topbar) && <header className='layout-topbar'>{slots[SlotName.Topbar]}</header>}
+
+            {hasSidebar && (
+                <aside
+                    className='layout-sidebar'
+                    onMouseEnter={revealsOnPointer ? () => setSidebarRevealed(true) : undefined}
+                    onMouseLeave={revealsOnPointer ? () => setSidebarRevealed(false) : undefined}>
+                    {slots[SlotName.Sidebar]}
+                    {slots[SlotName.Menu]}
+                </aside>
+            )}
+
+            <div className='layout-main'>
+                {filled(slots, SlotName.Breadcrumb) && <div className='layout-breadcrumb'>{slots[SlotName.Breadcrumb]}</div>}
+                <main className='layout-content'>{slots[SlotName.Content]}</main>
+                {filled(slots, SlotName.Footer) && <footer className='layout-footer'>{slots[SlotName.Footer]}</footer>}
+            </div>
+
+            {filled(slots, SlotName.RightPanel) && <aside className='layout-right-panel'>{slots[SlotName.RightPanel]}</aside>}
+            {slots[SlotName.ConfigPanel]}
+            <LayoutMask />
+        </div>
+    );
+}
+
+function filled(slots: Record<string, ReactNode[]>, name: SlotName): boolean {
+    return (slots[name]?.length ?? 0) > 0;
+}

package/shell/Breadcrumb.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 { BreadCrumb } from 'primereact/breadcrumb';
+import { MenuItem as PrimeMenuItem } from 'primereact/menuitem';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readOptionalString, readRecords, recordString } from './elementProperties';
+
+/**
+ * The trail above the content.
+ *
+ * PrimeReact's own `BreadCrumb` does the rendering rather than hand-written markup, because a breadcrumb
+ * is an ordinary component with no layout-mode behavior at all - it looks the same in every one of the
+ * eight modes. The shell only writes CSS where PrimeReact 10 genuinely has no answer, and this is not one
+ * of those places.
+ */
+export function Breadcrumb({ element }: RegisteredComponentProps) {
+    const home = readOptionalString(element, 'homeTargetScreen');
+    const model = readRecords(element, 'items').map(
+        (item): PrimeMenuItem => ({
+            label: recordString(item, 'label'),
+            url: recordString(item, 'targetScreen') ? `#/${recordString(item, 'targetScreen')}` : undefined,
+        }),
+    );
+
+    return (
+        <div data-scene-id={element.id}>
+            <BreadCrumb model={model} home={home ? { icon: 'pi pi-home', url: `#/${home}` } : undefined} />
+        </div>
+    );
+}

package/shell/ConfigPanel.tsx

@@ -0,0 +1,105 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useState } from 'react';
+import { Button } from 'primereact/button';
+import { Sidebar } from 'primereact/sidebar';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ColorScheme, MenuTheme, colorSchemes, menuThemes, useLayoutConfig } from '../configuration';
+import { LayoutModeSwitcher } from './LayoutModeSwitcher';
+import { ThemeSwitcher } from './ThemeSwitcher';
+import { readBoolean, readString } from './elementProperties';
+
+/** What each color scheme is called in the configurator. */
+const colorSchemeLabels: Record<ColorScheme, string> = {
+    [ColorScheme.Light]: 'Light',
+    [ColorScheme.Dark]: 'Dark',
+};
+
+/** What each menu theme is called in the configurator. */
+const menuThemeLabels: Record<MenuTheme, string> = {
+    [MenuTheme.Light]: 'Light',
+    [MenuTheme.Dark]: 'Dark',
+    [MenuTheme.Primary]: 'Primary',
+};
+
+/**
+ * The floating configurator.
+ *
+ * The axes are the ones the modern PrimeTek templates expose - color scheme, menu mode, menu theme and
+ * theme - because those are the four choices that actually change how an application feels, and a
+ * configurator with more knobs than that becomes a settings screen nobody finishes reading.
+ *
+ * The panel itself is PrimeReact 10's `Sidebar`, which is an overlay drawer rather than an app-shell
+ * sidebar - this is the one use it was designed for. (v11 renames it `Drawer` precisely to stop the
+ * confusion, and gives the app-shell role to a new `Sidebar`.)
+ */
+export function ConfigPanel({ element, slots }: RegisteredComponentProps) {
+    const [isVisible, setIsVisible] = useState(false);
+    const { config, setColorScheme, setMenuTheme } = useLayoutConfig();
+    const title = readString(element, 'title', 'Settings');
+    const showsMenuTheme = readBoolean(element, 'showMenuTheme', true);
+    const showsMode = readBoolean(element, 'showLayoutMode', true);
+
+    return (
+        <>
+            <Button
+                type='button'
+                rounded
+                icon='pi pi-cog'
+                className='layout-config-button'
+                aria-label={title}
+                data-scene-id={element.id}
+                onClick={() => setIsVisible(true)}
+            />
+            <Sidebar visible={isVisible} position='right' header={title} onHide={() => setIsVisible(false)}>
+                <div className='layout-config-panel'>
+                    <div>
+                        <h3 className='layout-config-section-title'>Color scheme</h3>
+                        <div className='layout-config-options' role='group' aria-label='Color scheme'>
+                            {colorSchemes.map(scheme => (
+                                <button
+                                    key={scheme}
+                                    type='button'
+                                    className='layout-config-option'
+                                    aria-pressed={config.colorScheme === scheme}
+                                    onClick={() => setColorScheme(scheme)}>
+                                    {colorSchemeLabels[scheme]}
+                                </button>
+                            ))}
+                        </div>
+                    </div>
+
+                    <ThemeSwitcher
+                        element={{ ...element, id: `${element.id}-theme`, properties: { ...element.properties, label: 'Theme' } }}
+                        slots={{}}
+                    />
+
+                    {showsMode && (
+                        <LayoutModeSwitcher element={{ ...element, id: `${element.id}-mode`, properties: { label: 'Menu mode' } }} slots={{}} />
+                    )}
+
+                    {showsMenuTheme && (
+                        <div>
+                            <h3 className='layout-config-section-title'>Menu theme</h3>
+                            <div className='layout-config-options' role='group' aria-label='Menu theme'>
+                                {menuThemes.map(menuTheme => (
+                                    <button
+                                        key={menuTheme}
+                                        type='button'
+                                        className='layout-config-option'
+                                        aria-pressed={config.menuTheme === menuTheme}
+                                        onClick={() => setMenuTheme(menuTheme)}>
+                                        {menuThemeLabels[menuTheme]}
+                                    </button>
+                                ))}
+                            </div>
+                        </div>
+                    )}
+
+                    {slots.content}
+                </div>
+            </Sidebar>
+        </>
+    );
+}

package/shell/Footer.tsx

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readString } from './elementProperties';
+
+/**
+ * The strip below the content.
+ *
+ * Kept as its own slot rather than folded into the content because it is application chrome, not part of
+ * a screen: the same footer is on every page, and a screen that had to render it would have to remember
+ * to.
+ */
+export function Footer({ element, slots }: RegisteredComponentProps) {
+    const text = readString(element, 'text');
+
+    return (
+        <>
+            <span data-scene-id={element.id}>{text}</span>
+            {slots.content}
+        </>
+    );
+}

package/shell/FullPageShell.tsx

@@ -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 { ReactNode } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { LayoutConfigProvider, useOptionalLayoutConfig } from '../configuration';
+import { SlotName } from '../layouts';
+
+/**
+ * The chrome-less shell: content, an optional branding aside, and the configurator.
+ *
+ * Login, register, password reset, verification, lock, error, access-denied, not-found and landing screens
+ * all render here rather than in a stripped-down application shell. That split is structural in every
+ * PrimeTek template, and for a good reason: those screens have no navigation state to hold, no sidebar to
+ * remember, and no breadcrumb to place, so hanging them off the application shell means every one of the
+ * eight modes has to have an answer for a page that has no menu.
+ *
+ * The configurator stays, because a sign-in page still has to honor the chosen theme - it is very often
+ * the first page anyone sees.
+ */
+export function FullPageShell({ element, slots }: RegisteredComponentProps) {
+    const surface = <FullPageSurface elementId={element.id} slots={slots} />;
+    return useOptionalLayoutConfig() ? surface : <LayoutConfigProvider>{surface}</LayoutConfigProvider>;
+}
+
+interface FullPageSurfaceProps {
+    elementId: string;
+    slots: Record<string, ReactNode[]>;
+}
+
+function FullPageSurface({ elementId, slots }: FullPageSurfaceProps) {
+    const hasAside = (slots[SlotName.Aside]?.length ?? 0) > 0;
+
+    return (
+        <div className='layout-full-page' data-scene-id={elementId}>
+            {hasAside && <aside className='layout-full-page-aside'>{slots[SlotName.Aside]}</aside>}
+            <main className='layout-full-page-content'>{slots[SlotName.Content]}</main>
+            {slots[SlotName.ConfigPanel]}
+        </div>
+    );
+}

package/shell/LayoutModeSwitcher.tsx

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { LayoutMode, layoutModes, useLayoutConfig } from '../configuration';
+import { readString } from './elementProperties';
+
+/** What each mode is called in the configurator - the same names the PrimeTek template line uses. */
+const modeLabels: Record<LayoutMode, string> = {
+    [LayoutMode.Static]: 'Static',
+    [LayoutMode.Overlay]: 'Overlay',
+    [LayoutMode.Slim]: 'Slim',
+    [LayoutMode.SlimPlus]: 'Slim+',
+    [LayoutMode.Compact]: 'Compact',
+    [LayoutMode.Horizontal]: 'Horizontal',
+    [LayoutMode.Reveal]: 'Reveal',
+    [LayoutMode.Drawer]: 'Drawer',
+};
+
+/**
+ * Switches between the layout modes.
+ *
+ * Below the mobile breakpoint every button is disabled and the panel says why, rather than the picker
+ * disappearing. A control that vanishes reads as a bug; a disabled control with a sentence next to it
+ * reads as a decision - and the choice is still recorded and still there when the window grows again.
+ */
+export function LayoutModeSwitcher({ element }: RegisteredComponentProps) {
+    const { config, setMode } = useLayoutConfig();
+    const label = readString(element, 'label', 'Menu mode');
+
+    return (
+        <div data-scene-id={element.id}>
+            <h3 className='layout-config-section-title'>{label}</h3>
+            <div className='layout-config-options' role='group' aria-label={label}>
+                {layoutModes.map(mode => (
+                    <button
+                        key={mode}
+                        type='button'
+                        className='layout-config-option'
+                        disabled={config.isMobile}
+                        aria-pressed={config.mode === mode}
+                        onClick={() => setMode(mode)}>
+                        {modeLabels[mode]}
+                    </button>
+                ))}
+            </div>
+            {config.isMobile && <p className='layout-config-note'>Below 991px every mode renders off-canvas, so the choice is kept but not applied.</p>}
+        </div>
+    );
+}

package/shell/LayoutModes.stories.tsx

@@ -0,0 +1,83 @@
+// 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 { LayoutMode, MenuTheme } from '../configuration';
+import { GalleryScreenPreview } from '../gallery';
+
+/**
+ * One story per layout mode, all showing the same dashboard.
+ *
+ * Showing the *same* screen in every mode is the point: the difference between a docked sidebar, an icon
+ * rail, a horizontal strip and a panel that slides in on hover is entirely in the wrapper class and the
+ * stylesheet, and nothing about the screen changes. A story per mode is how that claim stays true.
+ */
+const meta = {
+    title: 'Blueprint/Layout modes',
+    component: GalleryScreenPreview,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component:
+                    'The eight menu modes, each rendering the same dashboard. Below 991px every one of them is forced off-canvas - resize the preview to see it.',
+            },
+        },
+    },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryScreenPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+function inMode(mode: LayoutMode, extra: Record<string, unknown> = {}): Story['args'] {
+    return { screenName: 'Dashboard', initialConfig: { mode, ...extra } };
+}
+
+/** The sidebar is docked and the content is pushed by a matching margin. */
+export const Static: Story = { args: inMode(LayoutMode.Static) };
+
+/** The sidebar is parked off-canvas; the topbar toggle floats it over the content behind the mask. */
+export const Overlay: Story = { args: inMode(LayoutMode.Overlay) };
+
+/** An icon-only rail with circular buttons; submenus pop out beside it. */
+export const Slim: Story = { args: inMode(LayoutMode.Slim) };
+
+/** The same rail, wider, with each label stacked under its icon. */
+export const SlimPlus: Story = { args: inMode(LayoutMode.SlimPlus) };
+
+/** The icon rail again, with square buttons and a topbar shifted by the rail width. */
+export const Compact: Story = { args: inMode(LayoutMode.Compact) };
+
+/** The sidebar stops being a sidebar and flows into the topbar as a row. */
+export const Horizontal: Story = { args: inMode(LayoutMode.Horizontal) };
+
+/** A full panel parked off-left behind a strip of icons - hover slides it in over the content. */
+export const Reveal: Story = { args: inMode(LayoutMode.Reveal) };
+
+/** A collapsed rail that grows its width on hover, and can be pinned open. */
+export const Drawer: Story = { args: inMode(LayoutMode.Drawer) };
+
+/** A pinned drawer, which pushes the content out to the full sidebar width instead of covering it. */
+export const DrawerAnchored: Story = { args: inMode(LayoutMode.Drawer, { isSidebarAnchored: true, isSidebarRevealed: true }) };
+
+/** A dark sidebar against a light page - the most common brand customization in the template line. */
+export const DarkMenu: Story = { args: inMode(LayoutMode.Static, { menuTheme: MenuTheme.Dark }) };
+
+/** The topbar toggle opens and closes the sidebar, and the wrapper class follows it. */
+export const Interactive: Story = {
+    args: inMode(LayoutMode.Static),
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        const wrapper = canvasElement.querySelector('.layout-wrapper')!;
+        await expect(wrapper.className).not.toContain('layout-static-inactive');
+
+        await userEvent.click(canvas.getByRole('button', { name: 'Close the menu' }));
+        await expect(canvasElement.querySelector('.layout-wrapper')!.className).toContain('layout-static-inactive');
+
+        await userEvent.click(canvas.getByRole('button', { name: 'Open the menu' }));
+        await expect(canvasElement.querySelector('.layout-wrapper')!.className).not.toContain('layout-static-inactive');
+    },
+};

package/shell/Logo.tsx

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { useSceneTheme } from '@cratis/scene.react';
+import { readOptionalString, readString } from './elementProperties';
+
+/**
+ * The brand mark.
+ *
+ * This is the one place in the shell that reads the active theme directly rather than through a token,
+ * because picking between a light-background and a dark-background logo asset is a decision no CSS custom
+ * property can express - the two are different files. `useSceneTheme` exists for exactly this case.
+ */
+export function Logo({ element }: RegisteredComponentProps) {
+    const theme = useSceneTheme();
+    const label = readString(element, 'label', 'Cratis');
+    const initials = readString(element, 'initials', label.slice(0, 1).toUpperCase());
+    const lightSource = readOptionalString(element, 'lightImageUrl');
+    const darkSource = readOptionalString(element, 'darkImageUrl');
+    const source = theme?.isDark ? darkSource ?? lightSource : lightSource ?? darkSource;
+    const targetScreen = readString(element, 'targetScreen', 'Dashboard');
+
+    return (
+        <a className='layout-logo' href={`#/${targetScreen}`} data-scene-id={element.id}>
+            {source ? <img src={source} alt={label} height={28} /> : <span className='layout-logo-mark'>{initials}</span>}
+            <span>{label}</span>
+        </a>
+    );
+}

package/shell/Mask.tsx

@@ -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 { useLayoutConfig } from '../configuration';
+
+/**
+ * The scrim behind a floating sidebar.
+ *
+ * It is a `button` rather than a `div` because its only job is to close the sidebar, and a click target
+ * that is not focusable or reachable from the keyboard traps anyone not using a mouse behind an open
+ * overlay with no way out. It renders nothing at all when no sidebar is floating, so it never sits
+ * invisibly over the page swallowing clicks.
+ */
+export function LayoutMask() {
+    const { isMaskVisible, setSidebarOpen } = useLayoutConfig();
+    if (!isMaskVisible) {
+        return undefined;
+    }
+
+    return <button type='button' className='layout-mask' aria-label='Close the menu' onClick={() => setSidebarOpen(false)} />;
+}
+
+/**
+ * The `mask` component, for a template that wants to place the scrim itself rather than let
+ * {@link AppShell} do it.
+ */
+export function Mask() {
+    return <LayoutMask />;
+}

package/shell/Menu.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readString } from './elementProperties';
+
+/**
+ * A navigation list.
+ *
+ * One markup shape - a `nav` around a `ul` of {@link MenuItem}s - serves every mode; the difference
+ * between a docked list, a circular icon rail, a stacked label rail and a horizontal strip with drop-down
+ * submenus is entirely in the stylesheet. That is the point of the mode class vocabulary: the menu does
+ * not know which mode it is in, so a screen's navigation cannot be written for one mode and broken in
+ * another.
+ */
+export function Menu({ element, slots }: RegisteredComponentProps) {
+    const title = readString(element, 'title');
+    const label = readString(element, 'label', 'Main');
+
+    return (
+        <nav data-scene-id={element.id} aria-label={label}>
+            {title && <div className='layout-menu-section-title'>{title}</div>}
+            <ul className='layout-menu'>{slots.items}</ul>
+        </nav>
+    );
+}

package/shell/MenuItem.tsx

@@ -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 { RegisteredComponentProps } from '@cratis/scene.react';
+import { readBoolean, readOptionalString, readString } from './elementProperties';
+
+/**
+ * One entry in a navigation list, optionally with a submenu.
+ *
+ * Its properties are deliberately the {@link NavigationItem} contract - `label`, `targetScreen`,
+ * `routeParameterBindings`, `order`, `group` - so the very same element can be handed to the
+ * `Navigation` contribution point and read back by `extractNavigationItem`. A screen therefore declares
+ * its navigation once and gets both the sidebar entry and the aggregated navigation for free, instead of
+ * maintaining a menu and a contribution that drift apart.
+ *
+ * The route is rendered as a hash route against the target screen's name. A host with a real router
+ * renders the shell inside it and rewrites these; hashes keep the gallery navigable with no router at all,
+ * which is what a preview needs.
+ */
+export function MenuItem({ element, slots }: RegisteredComponentProps) {
+    const label = readString(element, 'label');
+    const icon = readOptionalString(element, 'icon');
+    const badge = readOptionalString(element, 'badge');
+    const targetScreen = readOptionalString(element, 'targetScreen');
+    const isActive = readBoolean(element, 'isActive');
+    const hasSubmenu = (slots.items?.length ?? 0) > 0;
+
+    return (
+        <li className='layout-menu-item' data-scene-id={element.id} data-active={isActive} data-target-screen={targetScreen}>
+            <a className='layout-menu-link' href={targetScreen ? `#/${targetScreen}` : undefined} aria-current={isActive ? 'page' : undefined}>
+                {icon && <i className={`layout-menu-icon ${icon}`} aria-hidden='true' />}
+                <span className='layout-menu-label'>{label}</span>
+                {badge && <span className='layout-menu-badge'>{badge}</span>}
+                {hasSubmenu && <i className='pi pi-angle-down' aria-hidden='true' />}
+            </a>
+            {hasSubmenu && <ul className='layout-submenu'>{slots.items}</ul>}
+        </li>
+    );
+}

package/shell/PageHeader.tsx

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readString } from './elementProperties';
+
+/**
+ * A screen's title, subtitle and actions.
+ *
+ * This belongs to the layout package rather than to each screen because it is the one piece of page
+ * furniture every page template repeats. Centralizing it means the title/actions relationship is spaced
+ * and aligned identically across the whole page set, which is most of what makes a template set look like
+ * one product rather than twenty pages.
+ */
+export function PageHeader({ element, slots }: RegisteredComponentProps) {
+    const title = readString(element, 'title');
+    const subtitle = readString(element, 'subtitle');
+
+    return (
+        <div className='layout-page-header' data-scene-id={element.id}>
+            <div>
+                <h1 className='layout-page-header-title'>{title}</h1>
+                {subtitle && <p className='layout-page-header-subtitle'>{subtitle}</p>}
+            </div>
+            {(slots.actions?.length ?? 0) > 0 && <div className='layout-page-header-actions'>{slots.actions}</div>}
+        </div>
+    );
+}

package/shell/RightPanel.tsx

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readString } from './elementProperties';
+
+/**
+ * The inspector panel down the right-hand edge.
+ *
+ * Sakai has no right panel; the premium PrimeTek templates all do, and it is where activity feeds, recent
+ * items and inline help live. It is exposed as a slot the shell simply does not render when nothing fills
+ * it, so a screen pays nothing for a region it does not use.
+ */
+export function RightPanel({ element, slots }: RegisteredComponentProps) {
+    const title = readString(element, 'title');
+
+    return (
+        <section data-scene-id={element.id} aria-label={title || 'Panel'}>
+            {title && <h2 className='layout-page-header-title'>{title}</h2>}
+            {slots.content}
+        </section>
+    );
+}

package/shell/Sidebar.tsx

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Button } from 'primereact/button';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { isPointerRevealMode, useLayoutConfig } from '../configuration';
+import { readString } from './elementProperties';
+
+/**
+ * The sidebar's own chrome, inside the panel {@link AppShell} positions.
+ *
+ * The panel and its contents are deliberately different components. Everything about *where* the sidebar
+ * is - translated off-canvas, collapsed to a rail, growing on hover - belongs to the mode and therefore to
+ * 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.
+ *
+ * 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 title = readString(element, 'title');
+    const isPinnable = isPointerRevealMode(effectiveMode);
+
+    return (
+        <>
+            <div className='layout-sidebar-header' data-scene-id={element.id}>
+                {slots.logo}
+                {title && <span className='layout-sidebar-title'>{title}</span>}
+                {isPinnable && (
+                    <Button
+                        type='button'
+                        text
+                        rounded
+                        icon={config.isSidebarAnchored ? 'pi pi-lock' : 'pi pi-lock-open'}
+                        aria-label={config.isSidebarAnchored ? 'Unpin the menu' : 'Pin the menu open'}
+                        aria-pressed={config.isSidebarAnchored}
+                        onClick={toggleSidebarAnchor}
+                    />
+                )}
+            </div>
+            {slots.content}
+        </>
+    );
+}