@cratis/scene.blueprint.default 0.1.0

package/themes/LayoutThemeProvider.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, useMemo } from 'react';
+import { Theme } from '@cratis/scene.model';
+import { SceneThemeProvider } from '@cratis/scene.react';
+import { useLayoutConfig } from '../configuration';
+import { defaultBlueprintThemes } from './defaultBlueprintThemes';
+
+export interface LayoutThemeProviderProps {
+    /** The themes to choose between. Defaults to the two this package ships. */
+    themes?: Theme[];
+
+    /** The shell the chosen theme applies to. */
+    children?: ReactNode;
+
+    /** A class name for the element the tokens land on. */
+    className?: string;
+}
+
+/**
+ * Applies whichever theme the shell's configuration currently names.
+ *
+ * This is the seam between the configurator and `SceneThemeProvider`: the configurator only ever records
+ * a name, and this resolves that name against the theme set a host offers. Keeping the shell's state
+ * free of the theme object itself is what lets a host swap in an entirely different theme set - its own
+ * brand palettes - without the configurator or any shell component changing.
+ *
+ * Switching is live re-resolution, not a reload: `SceneThemeProvider` writes the new tokens onto the same
+ * element, so nothing below it remounts and no state is lost.
+ */
+export function LayoutThemeProvider({ themes = defaultBlueprintThemes, children, className }: LayoutThemeProviderProps) {
+    const { config } = useLayoutConfig();
+    const theme = useMemo(() => themes.find(candidate => candidate.name === config.themeName) ?? themes[0], [themes, config.themeName]);
+
+    return (
+        <SceneThemeProvider theme={theme} className={className}>
+            {children}
+        </SceneThemeProvider>
+    );
+}

package/themes/Theming.stories.tsx

@@ -0,0 +1,89 @@
+// 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 { ColorScheme, LayoutConfigProvider, LayoutMode, useLayoutConfig } from '../configuration';
+import { GalleryScreenPreview, externalComponent } from '../gallery';
+import { ComponentName } from '../ComponentName';
+import { ThemeSwitcher } from '../shell';
+import { LayoutThemeProvider } from './LayoutThemeProvider';
+import { defaultBlueprintThemes } from './defaultBlueprintThemes';
+
+/**
+ * Switching theme is live re-resolution, not a reload.
+ *
+ * `SceneThemeProvider` writes the new token values onto the element that is already there, so nothing below
+ * it remounts - the sidebar stays where it was, an open menu stays open, and anything typed into a form is
+ * still there. The switcher below only ever records a theme *name*; resolving that name against the theme
+ * set is `LayoutThemeProvider`'s job, which is what lets a host substitute its own brand palettes without
+ * touching the switcher.
+ */
+const meta = {
+    title: 'Blueprint/Theming',
+    component: GalleryScreenPreview,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component: 'The two themes this blueprint ships, and a switcher proving the swap is live rather than a reload.',
+            },
+        },
+    },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryScreenPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** The dashboard on the light palette. */
+export const Light: Story = { args: { screenName: 'Dashboard', initialConfig: { themeName: 'Scene Default Light', colorScheme: ColorScheme.Light } } };
+
+/** The same dashboard on the dark palette - the same ten tokens, different values. */
+export const Dark: Story = {
+    args: { screenName: 'Dashboard', initialConfig: { themeName: 'Scene Default Dark', colorScheme: ColorScheme.Dark, mode: LayoutMode.Static } },
+};
+
+const switcherElement = externalComponent('theme-switcher', ComponentName.ThemeSwitcher, {
+    label: 'Theme',
+    themes: defaultBlueprintThemes.map(theme => ({ name: theme.name, label: theme.name, isDark: theme.isDark ?? false })),
+});
+
+function AppliedTheme() {
+    const { config } = useLayoutConfig();
+    return <output data-testid='applied-theme'>{`${config.themeName} · ${config.colorScheme}`}</output>;
+}
+
+function ThemeSwitchingDemo() {
+    return (
+        <LayoutConfigProvider storage={null}>
+            <LayoutThemeProvider>
+                <div style={{ padding: '1.5rem', display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+                    <ThemeSwitcher element={switcherElement} slots={{}} />
+                    <AppliedTheme />
+                </div>
+            </LayoutThemeProvider>
+        </LayoutConfigProvider>
+    );
+}
+
+/** Click a theme and the tokens are rewritten in place - no reload, no remount, no lost state. */
+export const Switcher: Story = {
+    args: { screenName: 'Dashboard' },
+    parameters: { layout: 'padded' },
+    render: () => <ThemeSwitchingDemo />,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getByRole('button', { name: 'Scene Default Dark' }));
+        await expect(canvas.getByTestId('applied-theme').textContent).toContain('Scene Default Dark');
+
+        const themed = canvasElement.querySelector('[data-scene-theme-root]') as HTMLElement;
+        await expect(themed.getAttribute('data-scene-color-scheme')).toBe('dark');
+        await expect(themed.style.getPropertyValue('--scene-surface-card')).toBe('#171a23');
+
+        await userEvent.click(canvas.getByRole('button', { name: 'Scene Default Light' }));
+        await expect(themed.getAttribute('data-scene-color-scheme')).toBe('light');
+        await expect(themed.style.getPropertyValue('--scene-surface-card')).toBe('#ffffff');
+    },
+};

package/themes/blueprintThemeCompatibility.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { defaultBlueprintName } from '../packageName';
+
+/**
+ * The packages this blueprint's themes declare compatibility with.
+ *
+ * `core` is on the list on purpose. `incompatiblePackages` has no implicit exemption for it - a theme
+ * that omits it is reported incompatible for `core` with every profile that lists it, which is every
+ * profile, since `core` is the fallback vocabulary. The exemption was left out of the engine deliberately
+ * so that "compatible with everything active" has to be stated rather than assumed, and a theme shipped by
+ * a blueprint is exactly where stating it matters.
+ *
+ * The rest is the stack the shell is actually built on: this blueprint's own components, the PrimeReact
+ * primitives it uses, the Cratis Components library its screen templates draw from, and the styling
+ * package those are written against.
+ */
+export const blueprintThemeCompatibility: string[] = ['core', defaultBlueprintName, 'PrimeReact', 'Cratis.Components', 'Tailwind'];

package/themes/dark.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme } from '@cratis/scene.model';
+import { blueprintThemeCompatibility } from './blueprintThemeCompatibility';
+
+/**
+ * The dark theme the shell ships with.
+ *
+ * Deliberately the same ten token names as the light theme and nothing more. A dark theme that introduced
+ * extra tokens would work only for the parts of the shell written after it existed - the token set is the
+ * contract, and both themes filling it identically is what makes switching between them a swap rather than
+ * a re-render with holes in it.
+ */
+export const darkTheme: Theme = {
+    name: 'Scene Default Dark',
+    compatibleWith: blueprintThemeCompatibility,
+    isDark: true,
+    author: 'Cratis',
+    authorUrl: 'https://cratis.io',
+    license: 'MIT',
+    description: 'The default dark palette: a deep slate ramp with a lifted indigo accent.',
+    tokens: {
+        'primary.color': '#818cf8',
+        'primary.contrastColor': '#10131f',
+        'surface.background': '#0f1117',
+        'surface.card': '#171a23',
+        'surface.border': '#262a36',
+        'surface.hover': '#1f2431',
+        'surface.overlay': '#1c2030',
+        'text.color': '#e6e8ef',
+        'text.mutedColor': '#9aa1b1',
+        'highlight.background': '#232a45',
+        'highlight.color': '#c7ccff',
+        'content.borderRadius': '0.5rem',
+        'focus.ring': '0 0 0 2px rgb(129 140 248 / 0.45)',
+    },
+};

package/themes/defaultBlueprintThemes.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme } from '@cratis/scene.model';
+import { darkTheme } from './dark';
+import { lightTheme } from './light';
+
+/**
+ * The themes this blueprint ships, in the order a picker should offer them.
+ *
+ * The list is what the manifest's `themes` names and what the bundle provides, so it is the one place the
+ * two can be kept in step - `validatePackageBundle` proves they are.
+ */
+export const defaultBlueprintThemes: Theme[] = [lightTheme, darkTheme];

package/themes/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './blueprintThemeCompatibility';
+export * from './light';
+export * from './dark';
+export * from './defaultBlueprintThemes';
+export * from './LayoutThemeProvider';

package/themes/light.ts

@@ -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 { Theme } from '@cratis/scene.model';
+import { blueprintThemeCompatibility } from './blueprintThemeCompatibility';
+
+/**
+ * The light theme the shell ships with.
+ *
+ * The palette is original to Cratis - a neutral grey ramp with an indigo accent - rather than adopted from
+ * any existing preset, which is why `author` says so rather than being left blank. A theme with empty
+ * attribution reads as "nobody has checked", and once a palette is lifted from somewhere else without its
+ * credit, nobody can tell afterwards which of the two it was.
+ *
+ * The token set is the shell's whole styling contract: every rule in `layout.css` resolves back to one of
+ * these ten names. A theme that defines them defines the entire shell.
+ */
+export const lightTheme: Theme = {
+    name: 'Scene Default Light',
+    compatibleWith: blueprintThemeCompatibility,
+    isDark: false,
+    author: 'Cratis',
+    authorUrl: 'https://cratis.io',
+    license: 'MIT',
+    description: 'The default light palette: a neutral grey ramp with an indigo accent.',
+    tokens: {
+        'primary.color': '#4f46e5',
+        'primary.contrastColor': '#ffffff',
+        'surface.background': '#f4f5f7',
+        'surface.card': '#ffffff',
+        'surface.border': '#e2e5e9',
+        'surface.hover': '#eceef1',
+        'surface.overlay': '#ffffff',
+        'text.color': '#1f2430',
+        'text.mutedColor': '#6b7280',
+        'highlight.background': '#eef2ff',
+        'highlight.color': '#3730a3',
+        'content.borderRadius': '0.5rem',
+        'focus.ring': '0 0 0 2px rgb(79 70 229 / 0.4)',
+    },
+};