@cratis/scene.blueprint.default 0.1.0

package/for_layoutConfigTransitions/when_the_viewport_crosses_the_mobile_breakpoint.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    LayoutMode,
+    defaultLayoutConfigState,
+    effectiveLayoutMode,
+    isMobileWidth,
+    layoutModes,
+    layoutWrapperClasses,
+    mobileBreakpoint,
+    toggleSidebar,
+    withMobile,
+    withMode,
+} from '../configuration';
+
+describe('when the viewport crosses the mobile breakpoint', () => {
+    const desktop = withMode(defaultLayoutConfigState(), LayoutMode.Slim);
+    const mobile = withMobile(desktop, true);
+    const backToDesktop = withMobile(mobile, false);
+
+    it('should treat the breakpoint itself as mobile, matching the stylesheet', () => {
+        isMobileWidth(mobileBreakpoint).should.be.true;
+        isMobileWidth(mobileBreakpoint + 1).should.be.false;
+    });
+
+    it('should force every mode off-canvas below the breakpoint', () => {
+        for (const mode of layoutModes) {
+            effectiveLayoutMode(withMobile(withMode(desktop, mode), true)).should.equal(LayoutMode.Overlay);
+        }
+    });
+
+    it('should keep the chosen mode rather than overwriting it', () => {
+        mobile.mode.should.equal(LayoutMode.Slim);
+    });
+
+    it('should close the sidebar on the way in so the page is not covered on arrival', () => {
+        mobile.isSidebarOpen.should.be.false;
+    });
+
+    it('should mark the wrapper mobile', () => {
+        layoutWrapperClasses(mobile).should.contain('layout-mobile');
+    });
+
+    it('should mark the wrapper mobile-active once the sidebar is opened', () => {
+        layoutWrapperClasses(toggleSidebar(mobile)).should.contain('layout-mobile-active');
+    });
+
+    it('should restore the chosen mode on the way back out', () => {
+        effectiveLayoutMode(backToDesktop).should.equal(LayoutMode.Slim);
+    });
+
+    it('should leave the state untouched when the regime has not actually changed', () => {
+        withMobile(mobile, true).should.equal(mobile);
+    });
+
+    it('should reopen a static sidebar on the way back out, since docked is its resting state', () => {
+        const staticMobile = withMobile(withMode(defaultLayoutConfigState(), LayoutMode.Static), true);
+        withMobile(staticMobile, false).isSidebarOpen.should.be.true;
+    });
+});

package/for_layoutWrapperClasses/when_rendering_each_mode.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    LayoutMode,
+    defaultLayoutConfigState,
+    isLayoutMaskVisible,
+    layoutModes,
+    layoutWrapperClasses,
+    toggleSidebar,
+    withMobile,
+    withMode,
+    withSidebarAnchored,
+    withSidebarRevealed,
+} from '../configuration';
+
+describe('when rendering each mode', () => {
+    const started = defaultLayoutConfigState();
+
+    it('should always start with the wrapper class', () => {
+        layoutWrapperClasses(started)[0].should.equal('layout-wrapper');
+    });
+
+    for (const mode of layoutModes) {
+        it(`should put the '${mode}' mode class on the wrapper`, () => {
+            layoutWrapperClasses(withMode(started, mode)).should.contain(`layout-${mode}`);
+        });
+    }
+
+    it('should mark a closed static sidebar inactive', () => {
+        layoutWrapperClasses(toggleSidebar(withMode(started, LayoutMode.Static))).should.contain('layout-static-inactive');
+    });
+
+    it('should not mark an open static sidebar inactive', () => {
+        layoutWrapperClasses(withMode(started, LayoutMode.Static)).should.not.contain('layout-static-inactive');
+    });
+
+    it('should mark an opened overlay sidebar active', () => {
+        layoutWrapperClasses(toggleSidebar(withMode(started, LayoutMode.Overlay))).should.contain('layout-overlay-active');
+    });
+
+    it('should mark a revealed sidebar active', () => {
+        layoutWrapperClasses(withSidebarRevealed(withMode(started, LayoutMode.Reveal), true)).should.contain('layout-sidebar-active');
+    });
+
+    it('should mark an anchored sidebar anchored', () => {
+        layoutWrapperClasses(withSidebarAnchored(withMode(started, LayoutMode.Drawer), true)).should.contain('layout-sidebar-anchored');
+    });
+
+    it('should not mark a static sidebar anchored, since only reveal and drawer answer to the pointer', () => {
+        layoutWrapperClasses(withSidebarAnchored(withMode(started, LayoutMode.Static), true)).should.not.contain('layout-sidebar-anchored');
+    });
+
+    it('should show the mask only while a floating sidebar is open', () => {
+        isLayoutMaskVisible(toggleSidebar(withMode(started, LayoutMode.Overlay))).should.be.true;
+        isLayoutMaskVisible(withMode(started, LayoutMode.Overlay)).should.be.false;
+        isLayoutMaskVisible(withMode(started, LayoutMode.Static)).should.be.false;
+    });
+
+    it('should show the mask on mobile once the sidebar is opened, whatever the chosen mode', () => {
+        isLayoutMaskVisible(toggleSidebar(withMobile(withMode(started, LayoutMode.Horizontal), true))).should.be.true;
+    });
+});

package/for_navigation/when_aggregating_the_navigation_contributions.ts

@@ -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 { NavigationItem } from '@cratis/scene.model';
+import { aggregateContributions } from '@cratis/scene.engine';
+import { extractNavigationItem } from '@cratis/scene.react';
+import { galleryScreen, galleryScreenTemplates, navigationContributionPoint, navigationContributions, navigationEntries } from '../gallery';
+
+describe('when aggregating the navigation contributions', () => {
+    const aggregated = aggregateContributions(navigationContributions, navigationContributionPoint);
+    const items = aggregated.map(extractNavigationItem).filter((item): item is NavigationItem => item !== undefined);
+
+    it('should aggregate one contribution per navigation entry', () => {
+        aggregated.should.have.lengthOf(navigationEntries.length);
+    });
+
+    it('should extract every one of them as a navigation item', () => {
+        items.should.have.lengthOf(navigationEntries.length);
+    });
+
+    it('should carry the label and target screen through the property bag unchanged', () => {
+        const dashboard = items.find(item => item.targetScreen === 'Dashboard');
+        dashboard!.label.should.equal('Dashboard');
+    });
+
+    it('should carry the group so an aggregated navigation can section itself', () => {
+        items.filter(item => item.group === undefined).should.be.empty;
+    });
+
+    it('should carry a route parameter bag rather than leaving it undefined', () => {
+        items.filter(item => item.routeParameterBindings === undefined).should.be.empty;
+    });
+
+    it('should point every entry at a screen template this blueprint provides', () => {
+        const provided = new Set(galleryScreenTemplates.map(template => template.name));
+        items.filter(item => !provided.has(item.targetScreen)).map(item => item.targetScreen).should.be.empty;
+    });
+
+    it('should point every entry at a screen the gallery actually ships', () => {
+        items.filter(item => galleryScreen(item.targetScreen) === undefined).map(item => item.targetScreen).should.be.empty;
+    });
+
+    it('should carry the contributions on every application-shell screen', () => {
+        galleryScreen('Dashboard')!.contributions.should.have.lengthOf(navigationEntries.length);
+    });
+
+    it('should not carry navigation on a full-page screen, which has no navigation to render', () => {
+        galleryScreen('Login')!.contributions.should.be.empty;
+    });
+});

package/gallery/ApplicationScreens.stories.tsx

@@ -0,0 +1,70 @@
+// 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 { GalleryScreenPreview } from './GalleryScreenPreview';
+
+/**
+ * Every screen template that renders inside the application shell, booted through the real engine.
+ *
+ * Each story resolves the screen's bare component names against the gallery profile and renders the result
+ * with `SceneElementView` and the real registry - the same path Studio's preview and a shipped application
+ * take. Nothing is rendered by calling a shell component directly, because a story that did would prove
+ * only that the component compiles.
+ */
+const meta = {
+    title: 'Blueprint/Application screens',
+    component: GalleryScreenPreview,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component: 'The ten in-application screen templates plus the three-level nesting chain, each booted through the real engine as a screen.',
+            },
+        },
+    },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryScreenPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Four stat cards over two columns of widgets. */
+export const Dashboard: Story = { args: { screenName: 'Dashboard' } };
+
+/** A searchable product table with a header and a primary action. */
+export const List: Story = { args: { screenName: 'CrudList' } };
+
+/** One record: header, sections and a summary panel. */
+export const Detail: Story = { args: { screenName: 'DetailView' } };
+
+/** A grouped form covering the field types an application actually uses. */
+export const Form: Story = { args: { screenName: 'FormPage' } };
+
+/** The designed empty state for a list with nothing in it yet. */
+export const Empty: Story = { args: { screenName: 'Empty' } };
+
+/** Prose with a table of contents beside it. */
+export const Documentation: Story = { args: { screenName: 'Documentation' } };
+
+/** The signed-in user editing their own account. */
+export const ProfileSettings: Story = { args: { screenName: 'ProfileSettings' } };
+
+/** The people table, with roles and an invitation action. */
+export const UserManagement: Story = { args: { screenName: 'UserManagement' } };
+
+/** A printable document: parties, line items and totals. */
+export const Invoice: Story = { args: { screenName: 'Invoice' } };
+
+/** Searchable answers with a route to a human. */
+export const Help: Story = { args: { screenName: 'Help' } };
+
+/** Module level: a template fitting the application layout's content slot. */
+export const ModuleWorkspace: Story = { args: { screenName: 'ModuleWorkspace' } };
+
+/** Feature level: a template fitting a slot the module template declares. */
+export const FeatureSection: Story = { args: { screenName: 'FeatureSection' } };
+
+/** Slice level: three templates deep, still landing in the layout's content slot. */
+export const SliceSection: Story = { args: { screenName: 'SliceSection' } };

package/gallery/FullPageScreens.stories.tsx

@@ -0,0 +1,60 @@
+// 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 { GalleryScreenPreview } from './GalleryScreenPreview';
+
+/**
+ * Every screen template that renders in the chrome-less shell.
+ *
+ * These have no navigation, no breadcrumb and no sidebar - which is exactly why they use a different
+ * layout rather than a stripped-down application shell. The configurator is still there, because a sign-in
+ * page has to honor the chosen theme.
+ */
+const meta = {
+    title: 'Blueprint/Full-page screens',
+    component: GalleryScreenPreview,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component: 'The ten chrome-less screens: everything around signing in, the three status pages, and the landing page.',
+            },
+        },
+    },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryScreenPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Email and password beside the branding panel. */
+export const Login: Story = { args: { screenName: 'Login' } };
+
+/** Account creation, with a strength meter and the terms checkbox. */
+export const Register: Story = { args: { screenName: 'Register' } };
+
+/** One field and one button. */
+export const ForgotPassword: Story = { args: { screenName: 'ForgotPassword' } };
+
+/** Where a reset link lands. */
+export const NewPassword: Story = { args: { screenName: 'NewPassword' } };
+
+/** The code step, with its progress indicator. */
+export const Verification: Story = { args: { screenName: 'Verification' } };
+
+/** One person, one password, nothing lost. */
+export const LockScreen: Story = { args: { screenName: 'LockScreen' } };
+
+/** A server-side failure, said plainly. */
+export const Error: Story = { args: { screenName: 'Error' } };
+
+/** Signed in, and still not allowed. */
+export const AccessDenied: Story = { args: { screenName: 'AccessDenied' } };
+
+/** A wrong address, with a search box rather than a dead end. */
+export const NotFound: Story = { args: { screenName: 'NotFound' } };
+
+/** The marketing front door, with navigation of its own. */
+export const Landing: Story = { args: { screenName: 'Landing' } };

package/gallery/GalleryScreenPreview.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { Theme } from '@cratis/scene.model';
+import { ComponentRegistry, SceneElementView, coreComponents } from '@cratis/scene.react';
+import { LayoutConfigProvider, LayoutConfigState } from '../configuration';
+import { defaultBlueprintComponents } from '../defaultBlueprintComponents';
+import { LayoutThemeProvider, defaultBlueprintThemes } from '../themes';
+import { composeScreenElement } from './composeScreen';
+import { galleryComponentCatalog, galleryPreviewProfile } from './previewProfile';
+import { resolveElementComponentNames } from './resolveElementNames';
+import { galleryScreen } from './screens';
+
+/**
+ * The registry a preview resolves against when a host does not supply one: `core` plus this blueprint.
+ *
+ * Merged by hand rather than through `mergePackageRegistries`, because reaching for this blueprint's
+ * *bundle* here would be circular - the bundle is assembled from the gallery this file belongs to. Registry
+ * keys carry their package name, so merge order cannot cause a collision either way.
+ */
+export const galleryPreviewRegistry: ComponentRegistry = { ...coreComponents, ...defaultBlueprintComponents };
+
+export interface GalleryScreenPreviewProps {
+    /** The name of the gallery screen to boot. */
+    screenName: string;
+
+    /** Configuration to start from - a story pinning a mode, or a host restoring a session. */
+    initialConfig?: Partial<LayoutConfigState>;
+
+    /** The themes the configurator may switch between. Defaults to the two this blueprint ships. */
+    themes?: Theme[];
+
+    /** The component registry to render against. Defaults to `core` plus this blueprint's own components. */
+    registry?: ComponentRegistry;
+}
+
+/**
+ * Boots one gallery screen through the real engine.
+ *
+ * Nothing here is a preview-only path: the screen is a real {@link Screen}, its element tree is resolved by
+ * the real `resolveComponentName`, and it is rendered by the real `SceneElementView` against the real
+ * registry. That is the point of shipping a gallery at all - a mockup proves that someone can draw a
+ * dashboard, and this proves the blueprint renders one.
+ *
+ * Component names belonging to packages the host has not loaded resolve but find no implementation, and
+ * come out as `UnresolvedComponent`'s dashed red box naming what is missing. That is the designed outcome:
+ * a preview of a blueprint against half a profile should look visibly incomplete rather than quietly
+ * wrong.
+ */
+export function GalleryScreenPreview({ screenName, initialConfig, themes = defaultBlueprintThemes, registry = galleryPreviewRegistry }: GalleryScreenPreviewProps) {
+    const element = useMemo(() => {
+        const screen = galleryScreen(screenName);
+        if (!screen) {
+            throw new Error(`The gallery has no screen named '${screenName}'.`);
+        }
+
+        return resolveElementComponentNames(composeScreenElement(screen), galleryPreviewProfile, galleryComponentCatalog);
+    }, [screenName]);
+
+    return (
+        <LayoutConfigProvider initialConfig={initialConfig} storage={null}>
+            <LayoutThemeProvider themes={themes}>
+                <SceneElementView element={element} registry={registry} resolveBinding={() => undefined} />
+            </LayoutThemeProvider>
+        </LayoutConfigProvider>
+    );
+}

package/gallery/NavigationEntry.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One entry in the gallery's navigation.
+ *
+ * The fields are deliberately the ones {@link NavigationItem} carries, plus an icon. That is what lets a
+ * single declaration become both a sidebar entry and a `Navigation` contribution: the element built from
+ * it carries these values in its `properties` bag, `extractNavigationItem` reads them straight back out,
+ * and neither side has to be kept in step with the other by hand.
+ */
+export interface NavigationEntry {
+    /** What the entry is called. */
+    label: string;
+
+    /** The screen it navigates to. */
+    targetScreen: string;
+
+    /** A PrimeIcons class for the entry's icon. */
+    icon: string;
+
+    /** The section it belongs to, so the menu and an aggregated navigation group it the same way. */
+    group: string;
+
+    /** Where it sorts within its group. */
+    order: number;
+}

package/gallery/TemplateSlotName.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The slots the gallery's screen templates offer to whatever they contain.
+ *
+ * Distinct from {@link SlotName}, which is the *layout's* vocabulary. A screen template declares its own
+ * slots, and a template nested inside it names one of these in `fitsSlot` - so the same name means
+ * different places at different depths, and that is fine: `fitsSlot` is always resolved against the direct
+ * parent, never globally.
+ */
+export enum TemplateSlotName {
+    /** A template's own title area. */
+    Header = 'header',
+
+    /** The main region a nested template fits into. */
+    Body = 'body',
+
+    /** An optional column beside the body. */
+    SidePanel = 'sidePanel',
+
+    /** The action strip above a body. */
+    Toolbar = 'toolbar',
+
+    /** Buttons belonging to a header or a form. */
+    Actions = 'actions',
+
+    /** The row of figures a dashboard opens with. */
+    Stats = 'stats',
+
+    /** The larger left-hand column of a dashboard. */
+    Primary = 'primary',
+
+    /** The narrower right-hand column of a dashboard. */
+    Secondary = 'secondary',
+}

package/gallery/applicationChrome.ts

@@ -0,0 +1,110 @@
+// 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 { ComponentName } from '../ComponentName';
+import { SlotName } from '../layouts';
+import { defaultBlueprintThemes } from '../themes';
+import { externalComponent } from './elements';
+import { entriesInGroup, navigationElement, navigationGroups } from './navigation';
+
+/**
+ * The chrome every screen in the application shell shares: the topbar, the sidebar, the menu, the footer
+ * and the configurator.
+ *
+ * It is built once, per screen, rather than repeated in twenty templates. A screen template describes what
+ * is *different* about a screen; if it also had to describe the topbar, then adding an item to the menu
+ * would mean editing twenty files, and nineteen of them would eventually be missed.
+ */
+
+/** The brand mark, shared by the topbar and the sidebar header. */
+function logo(id: string): SceneElement {
+    return externalComponent(id, ComponentName.Logo, { label: 'Contoso', initials: 'C', targetScreen: 'Dashboard' });
+}
+
+/** One menu section per navigation group, each holding that group's entries. */
+function menuSections(activeScreen: string): SceneElement[] {
+    return navigationGroups.map(group =>
+        externalComponent(
+            `menu-${group.toLowerCase()}`,
+            ComponentName.Menu,
+            { title: group, label: group },
+            { items: entriesInGroup(group).map(entry => navigationElement(entry, activeScreen)) },
+        ),
+    );
+}
+
+/** The configurator, offering the themes this blueprint ships. */
+function configPanel(): SceneElement {
+    return externalComponent(ComponentName.ConfigPanel, ComponentName.ConfigPanel, {
+        title: 'Settings',
+        themes: defaultBlueprintThemes.map(theme => ({ name: theme.name, label: theme.name, isDark: theme.isDark ?? false })),
+    });
+}
+
+/** One trail entry: a label, and the screen it goes back to. */
+export interface BreadcrumbEntry {
+    /** What the entry is called. */
+    label: string;
+
+    /** The screen it navigates back to, or undefined for the current page. */
+    targetScreen?: string;
+}
+
+/**
+ * The application shell's slot content for one screen.
+ *
+ * Only the breadcrumb and which menu entry is marked active differ from screen to screen - everything else
+ * is identical, which is the point of chrome.
+ *
+ * @param activeScreen The screen being rendered, so its menu entry is marked current.
+ * @param breadcrumb The trail above the content.
+ * @returns Slot content keyed by the {@link SlotName}s the `AppShell` layout declares.
+ */
+export function applicationChrome(activeScreen: string, breadcrumb: BreadcrumbEntry[]): Record<string, SceneElement[]> {
+    return {
+        [SlotName.Topbar]: [
+            externalComponent(
+                'topbar',
+                ComponentName.Topbar,
+                {},
+                {
+                    logo: [logo('topbar-logo')],
+                    end: [
+                        externalComponent('topbar-user', ComponentName.UserMenu, {
+                            name: 'Amelia Nyquist',
+                            role: 'Owner',
+                            initials: 'AN',
+                            items: [
+                                { label: 'Your profile', icon: 'pi pi-user', targetScreen: 'ProfileSettings' },
+                                { label: 'Help', icon: 'pi pi-question-circle', targetScreen: 'Help' },
+                                { label: 'Lock', icon: 'pi pi-lock', targetScreen: 'LockScreen' },
+                            ],
+                        }),
+                    ],
+                },
+            ),
+        ],
+        [SlotName.Sidebar]: [externalComponent('sidebar', ComponentName.Sidebar, { title: 'Contoso' }, { logo: [logo('sidebar-logo')] })],
+        [SlotName.Menu]: menuSections(activeScreen),
+        [SlotName.Breadcrumb]: [
+            externalComponent('breadcrumb', ComponentName.Breadcrumb, {
+                homeTargetScreen: 'Dashboard',
+                items: breadcrumb,
+            }),
+        ],
+        [SlotName.Footer]: [externalComponent('footer', ComponentName.Footer, { text: '© Contoso · Built with Cratis Scene' })],
+        [SlotName.ConfigPanel]: [configPanel()],
+    };
+}
+
+/**
+ * The full-page shell's slot content: the configurator and nothing else.
+ *
+ * A sign-in screen has no navigation to render, but it does have to honor the chosen theme - it is very
+ * often the first page anyone sees, and arriving at a light sign-in page before a dark application is a
+ * jarring way to start.
+ */
+export function fullPageChrome(): Record<string, SceneElement[]> {
+    return { [SlotName.ConfigPanel]: [configPanel()] };
+}