@cratis/scene.blueprint.default 0.1.0

package/shell/ThemeOption.ts

@@ -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 { ExternalComponent, Theme } from '@cratis/scene.model';
+import { ColorScheme } from '../configuration';
+import { readRecords, recordString } from './elementProperties';
+
+/**
+ * One entry a theme switcher offers.
+ *
+ * A switcher needs a name to record and a color scheme to record alongside it, but must not need the
+ * theme's tokens - the tokens belong to whoever applies the theme, and a switcher that carried them would
+ * force every page template to inline a full palette just to offer a choice.
+ */
+export interface ThemeOption {
+    /** The {@link Theme.name} to record when this option is chosen. */
+    name: string;
+
+    /** What to show on the button. */
+    label: string;
+
+    /** Which side of the light/dark axis choosing this option puts the shell on. */
+    colorScheme: ColorScheme;
+}
+
+/**
+ * Reads the themes a switcher should offer out of an element's properties, falling back to the ones
+ * supplied by the host.
+ *
+ * A template says which themes it wants offered; a host that renders the shell with a different theme set
+ * passes those as the fallback. Neither has to know the other's list.
+ *
+ * @param element The element carrying an optional `themes` property - an array of `{ name, label, isDark }`.
+ * @param fallback The options to offer when the element names none.
+ * @returns The options to render.
+ */
+export function readThemeOptions(element: ExternalComponent, fallback: ThemeOption[]): ThemeOption[] {
+    const declared = readRecords(element, 'themes').map(
+        (record): ThemeOption => ({
+            name: recordString(record, 'name'),
+            label: recordString(record, 'label') || recordString(record, 'name'),
+            colorScheme: record.isDark === true ? ColorScheme.Dark : ColorScheme.Light,
+        }),
+    );
+
+    const named = declared.filter(option => option.name.length > 0);
+    return named.length > 0 ? named : fallback;
+}
+
+/**
+ * Turns the {@link Theme}s a package ships into switcher options, so a host offering its own themes and a
+ * host offering this package's use the same code path.
+ */
+export function themeOptionsFor(themes: Theme[]): ThemeOption[] {
+    return themes.map(theme => ({
+        name: theme.name,
+        label: theme.name,
+        colorScheme: theme.isDark ? ColorScheme.Dark : ColorScheme.Light,
+    }));
+}

package/shell/ThemeSwitcher.tsx

@@ -0,0 +1,42 @@
+// 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 { useLayoutConfig } from '../configuration';
+import { defaultBlueprintThemes } from '../themes';
+import { readString } from './elementProperties';
+import { readThemeOptions, themeOptionsFor } from './ThemeOption';
+
+/**
+ * Switches between the themes a host offers.
+ *
+ * It records a name and a color scheme and nothing else - {@link LayoutThemeProvider} resolves the name
+ * against the real theme set. That split is what makes switching live: the tokens are rewritten on the
+ * element that already exists, so nothing below remounts and no form loses what was typed into it.
+ */
+export function ThemeSwitcher({ element }: RegisteredComponentProps) {
+    const { config, setThemeName, setColorScheme } = useLayoutConfig();
+    const label = readString(element, 'label', 'Theme');
+    const options = readThemeOptions(element, themeOptionsFor(defaultBlueprintThemes));
+
+    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}>
+                {options.map(option => (
+                    <button
+                        key={option.name}
+                        type='button'
+                        className='layout-config-option'
+                        aria-pressed={config.themeName === option.name}
+                        onClick={() => {
+                            setThemeName(option.name);
+                            setColorScheme(option.colorScheme);
+                        }}>
+                        {option.label}
+                    </button>
+                ))}
+            </div>
+        </div>
+    );
+}

package/shell/Topbar.tsx

@@ -0,0 +1,49 @@
+// 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 { LayoutMode, useLayoutConfig } from '../configuration';
+import { readBoolean } from './elementProperties';
+
+/**
+ * The fixed strip across the top of the application shell.
+ *
+ * It owns the one control every mode needs: the sidebar toggle. In `horizontal` mode it also hosts the
+ * 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.
+ *
+ * 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 showsToggle = readBoolean(element, 'showToggle', true) && togglesSidebar(effectiveMode);
+
+    return (
+        <>
+            <div className='layout-topbar-start' data-scene-id={element.id}>
+                {showsToggle && (
+                    <Button
+                        type='button'
+                        text
+                        rounded
+                        icon='pi pi-bars'
+                        aria-label={config.isSidebarOpen ? 'Close the menu' : 'Open the menu'}
+                        aria-expanded={config.isSidebarOpen}
+                        onClick={toggleSidebar}
+                    />
+                )}
+                {slots.logo}
+                {slots.start}
+            </div>
+            {slots.menu}
+            <div className='layout-topbar-end'>{slots.end}</div>
+        </>
+    );
+}
+
+function togglesSidebar(mode: LayoutMode): boolean {
+    return mode === LayoutMode.Static || mode === LayoutMode.Overlay;
+}

package/shell/UserMenu.tsx

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useRef } from 'react';
+import { Avatar } from 'primereact/avatar';
+import { Button } from 'primereact/button';
+import { Menu as PrimeMenu } from 'primereact/menu';
+import { MenuItem as PrimeMenuItem } from 'primereact/menuitem';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readRecords, readString, recordString } from './elementProperties';
+
+/**
+ * The signed-in user's avatar and menu.
+ *
+ * The popup is PrimeReact's `Menu` rather than hand-written markup: an overlay that positions itself,
+ * traps focus and closes on escape is framework behavior, and re-implementing it in a layout package is
+ * how a shell ends up with its own subtly broken menu. The shell hand-writes CSS only where PrimeReact 10
+ * has no primitive at all - the app-shell modes - and uses the library everywhere else.
+ */
+export function UserMenu({ element }: RegisteredComponentProps) {
+    const menu = useRef<PrimeMenu>(null);
+    const name = readString(element, 'name');
+    const role = readString(element, 'role');
+    const initials = readString(element, 'initials', name.slice(0, 1).toUpperCase());
+    const items = readRecords(element, 'items').map(
+        (item): PrimeMenuItem => ({
+            label: recordString(item, 'label'),
+            icon: recordString(item, 'icon') || undefined,
+            url: recordString(item, 'targetScreen') ? `#/${recordString(item, 'targetScreen')}` : undefined,
+        }),
+    );
+
+    return (
+        <div className='layout-user-menu' data-scene-id={element.id}>
+            <Avatar label={initials} shape='circle' />
+            <span className='layout-user-menu-name'>
+                <span>{name}</span>
+                {role && <span className='layout-user-menu-role'>{role}</span>}
+            </span>
+            <PrimeMenu ref={menu} model={items} popup id={`${element.id}-menu`} />
+            <Button
+                type='button'
+                text
+                rounded
+                icon='pi pi-angle-down'
+                aria-label={`Open the menu for ${name}`}
+                aria-controls={`${element.id}-menu`}
+                aria-haspopup
+                onClick={event => menu.current?.toggle(event)}
+            />
+        </div>
+    );
+}

package/shell/elementProperties.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.
+
+import { ExternalComponent } from '@cratis/scene.model';
+
+/**
+ * Typed reads out of a {@link SceneElement}'s open `properties` bag.
+ *
+ * The bag is `Record<string, unknown>` by design - it carries whatever a page template author wrote, and
+ * Scene never re-validates it. A shell component that trusts it and reads `properties.label as string`
+ * renders `[object Object]` or crashes the moment a template has a typo, so every read goes through one of
+ * these instead and falls back to something renderable.
+ */
+
+/** Reads a string property, or the fallback when it is absent or not a string. */
+export function readString(element: ExternalComponent, name: string, fallback = ''): string {
+    const value = element.properties[name];
+    return typeof value === 'string' ? value : fallback;
+}
+
+/** Reads an optional string property, or `undefined` when it is absent or not a string. */
+export function readOptionalString(element: ExternalComponent, name: string): string | undefined {
+    const value = element.properties[name];
+    return typeof value === 'string' ? value : undefined;
+}
+
+/** Reads a boolean property, or the fallback when it is absent or not a boolean. */
+export function readBoolean(element: ExternalComponent, name: string, fallback = false): boolean {
+    const value = element.properties[name];
+    return typeof value === 'boolean' ? value : fallback;
+}
+
+/** Reads a number property, or the fallback when it is absent or not a number. */
+export function readNumber(element: ExternalComponent, name: string, fallback = 0): number {
+    const value = element.properties[name];
+    return typeof value === 'number' ? value : fallback;
+}
+
+/** Reads an array of strings, or an empty array when the property is absent or holds anything else. */
+export function readStrings(element: ExternalComponent, name: string): string[] {
+    const value = element.properties[name];
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/**
+ * Reads an array of objects - a breadcrumb trail, a set of table columns, a user menu's items.
+ *
+ * Entries that are not objects are dropped rather than rendered, for the same reason the scalar reads
+ * fall back: half a table is a better failure than a thrown render.
+ */
+export function readRecords(element: ExternalComponent, name: string): Record<string, unknown>[] {
+    const value = element.properties[name];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry));
+}
+
+/** Reads a string out of one of {@link readRecords}' entries. */
+export function recordString(record: Record<string, unknown>, name: string, fallback = ''): string {
+    const value = record[name];
+    return typeof value === 'string' ? value : fallback;
+}

package/shell/index.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './elementProperties';
+export * from './ThemeOption';
+export * from './AppShell';
+export * from './FullPageShell';
+export * from './Topbar';
+export * from './Sidebar';
+export * from './Menu';
+export * from './MenuItem';
+export * from './Breadcrumb';
+export * from './Footer';
+export * from './RightPanel';
+export * from './ConfigPanel';
+export * from './PageHeader';
+export * from './Mask';
+export * from './Logo';
+export * from './UserMenu';
+export * from './ThemeSwitcher';
+export * from './LayoutModeSwitcher';