@cratis/scene.blueprint.default 1.1.0 → 3.0.0

package/for_AppShell/when_rendering_a_gallery_screen.tsx

@@ -2,16 +2,25 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { render, screen } from '@testing-library/react';
+import { PrimeReactProvider } from '@primereact/core';
 import { SceneElementView, coreComponents, corePackage, mergePackageRegistries } from '@cratis/scene.react';
 import { defaultBlueprint } from '../defaultBlueprint';
 import { composeScreenElement, galleryComponentCatalog, galleryPreviewProfile, galleryScreen, resolveElementComponentNames } from '../gallery';
 
 const registry = mergePackageRegistries([corePackage, defaultBlueprint]);
 
+// PrimeReact 11 components resolve their configuration through `PrimeReactProvider` and throw without
+// one, and these screens render five of them - the topbar toggle, the sidebar pin, the user menu, the
+// breadcrumb and the configurator's drawer. No preset is handed over: these specs assert structure and
+// text, and a theme would only add runtime CSS nothing here reads.
 function renderGalleryScreen(name: string) {
     const galleryItem = galleryScreen(name)!;
     const element = resolveElementComponentNames(composeScreenElement(galleryItem), galleryPreviewProfile, galleryComponentCatalog);
-    render(<SceneElementView element={element} registry={registry} resolveBinding={() => undefined} />);
+    render(
+        <PrimeReactProvider>
+            <SceneElementView element={element} registry={registry} resolveBinding={() => undefined} />
+        </PrimeReactProvider>,
+    );
 }
 
 function has(selector: string): boolean {

package/package.json

@@ -1,7 +1,17 @@
 {
     "name": "@cratis/scene.blueprint.default",
-    "version": "1.1.0",
+    "version": "3.0.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",
+        "scene",
+        "react",
+        "ui",
+        "templates",
+        "blueprint",
+        "themes",
+        "low-code"
+    ],
     "author": "Cratis",
     "license": "MIT",
     "repository": {
@@ -43,26 +53,32 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "1.1.0",
-        "@cratis/scene.model": "1.1.0",
-        "@cratis/scene.react": "1.1.0"
+        "@cratis/scene.engine": "3.0.0",
+        "@cratis/scene.model": "3.0.0",
+        "@cratis/scene.react": "3.0.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "1.1.0",
-        "@cratis/scene.model": "1.1.0",
-        "@cratis/scene.react": "1.1.0",
+        "@cratis/scene.engine": "3.0.0",
+        "@cratis/scene.model": "3.0.0",
+        "@cratis/scene.react": "3.0.0",
+        "@primereact/core": "11.1.0",
+        "@primereact/headless": "11.1.0",
+        "@primeuix/themes": "^3.0.0",
         "@storybook/addon-links": "^10.4.1",
         "@storybook/react": "^10.4.1",
         "@storybook/react-vite": "^10.4.1",
-        "primeicons": "^7.0.0",
-        "primereact": "10.9.8",
+        "primeicons": "8.0.0",
+        "primereact": "11.1.0",
         "react": "^19.2.6",
         "react-dom": "^19.2.6",
         "storybook": "^10.4.1"
     },
     "peerDependencies": {
-        "primereact": "^10.9.0",
-        "react": "^18.0.0 || ^19.0.0",
-        "react-dom": "^18.0.0 || ^19.0.0"
+        "@primereact/core": "^11.0.0",
+        "@primereact/headless": "^11.0.0",
+        "primeicons": "^8.0.0",
+        "primereact": "^11.0.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
     }
 }

package/shell/Breadcrumb.tsx

@@ -1,23 +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 { Fragment } from 'react';
+import { Breadcrumb as PrimeBreadcrumb } from 'primereact/breadcrumb';
 import { RegisteredComponentProps } from '@cratis/scene.react';
+import { MenuEntry } from './MenuEntry';
 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
+ * 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.
+ * eight modes. The shell only writes CSS where PrimeReact genuinely has no answer, and this is not one of
+ * those places: `Breadcrumb.Root` still supplies the `nav`, its `aria-label` and the list semantics, which
+ * is the part that is easy to get wrong by hand.
+ *
+ * What PrimeReact 11 no longer supplies is the `model` array - the component is composed now, and the
+ * `primereact/menuitem` type the array was made of is gone with it, which is why the trail is mapped into
+ * this package's own {@link MenuEntry}. The last entry is `Breadcrumb.Current` rather than a link: a trail
+ * whose final crumb navigates to the page already open is a link that does nothing, and it takes
+ * `aria-current='page'` away from the one element that should carry it.
  */
 export function Breadcrumb({ element }: RegisteredComponentProps) {
     const home = readOptionalString(element, 'homeTargetScreen');
-    const model = readRecords(element, 'items').map(
-        (item): PrimeMenuItem => ({
+    const trail = readRecords(element, 'items').map(
+        (item): MenuEntry => ({
             label: recordString(item, 'label'),
             url: recordString(item, 'targetScreen') ? `#/${recordString(item, 'targetScreen')}` : undefined,
         }),
@@ -25,7 +33,35 @@ export function Breadcrumb({ element }: RegisteredComponentProps) {
 
     return (
         <div data-scene-id={element.id}>
-            <BreadCrumb model={model} home={home ? { icon: 'pi pi-home', url: `#/${home}` } : undefined} />
+            <PrimeBreadcrumb.Root>
+                <PrimeBreadcrumb.List>
+                    {home && (
+                        <PrimeBreadcrumb.Item>
+                            <PrimeBreadcrumb.Link as='a' href={`#/${home}`} aria-label='Home'>
+                                <i className='pi pi-home' aria-hidden='true' />
+                            </PrimeBreadcrumb.Link>
+                        </PrimeBreadcrumb.Item>
+                    )}
+                    {trail.map((entry, index) => (
+                        <Fragment key={`${index}-${entry.label}`}>
+                            {(!!home || index > 0) && (
+                                <PrimeBreadcrumb.Separator>
+                                    <i className='pi pi-chevron-right' aria-hidden='true' />
+                                </PrimeBreadcrumb.Separator>
+                            )}
+                            <PrimeBreadcrumb.Item>
+                                {entry.url ? (
+                                    <PrimeBreadcrumb.Link as='a' href={entry.url}>
+                                        {entry.label}
+                                    </PrimeBreadcrumb.Link>
+                                ) : (
+                                    <PrimeBreadcrumb.Current>{entry.label}</PrimeBreadcrumb.Current>
+                                )}
+                            </PrimeBreadcrumb.Item>
+                        </Fragment>
+                    ))}
+                </PrimeBreadcrumb.List>
+            </PrimeBreadcrumb.Root>
         </div>
     );
 }

package/shell/ConfigPanel.tsx

@@ -1,9 +1,8 @@
 // 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 { Drawer } from 'primereact/drawer';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { ColorScheme, MenuTheme, colorSchemes, menuThemes, useLayoutConfig } from '../configuration';
 import { LayoutModeSwitcher } from './LayoutModeSwitcher';
@@ -30,76 +29,88 @@ const menuThemeLabels: Record<MenuTheme, string> = {
  * 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`.)
+ * The panel is `primereact/drawer`, which is the slide-in overlay this component has always wanted.
+ * PrimeReact 11 gave the name `Sidebar` to something else entirely - a new app-shell primitive with
+ * `SidebarLayout`/`SidebarAside`/`SidebarPanel` parts - so the v10 `Sidebar` import this file used to
+ * carry would still resolve after the upgrade and would silently render an app shell inside the shell.
+ * That is the one rename in the whole library that fails quietly rather than loudly, which is why it is
+ * called out here: this is `Drawer`, deliberately, and it is not the {@link Sidebar} next door either -
+ * that one is this package's own component for the docked panel's chrome.
+ *
+ * Open state is the drawer's own. `Drawer.Trigger` renders in place through `Drawer.Root`'s fragment, so
+ * the floating cog sits exactly where it did while getting `aria-expanded`/`aria-controls` from the
+ * component rather than from hand-written props that can drift out of step with the panel.
  */
 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>
+        <Drawer.Root position='right'>
+            <Drawer.Trigger as={Button} rounded iconOnly className='layout-config-button' aria-label={title} data-scene-id={element.id}>
+                <i className='pi pi-cog' aria-hidden='true' />
+            </Drawer.Trigger>
+            <Drawer.Portal>
+                <Drawer.Backdrop />
+                <Drawer.Popup>
+                    <Drawer.Header>
+                        <Drawer.Title>{title}</Drawer.Title>
+                        <Drawer.Close aria-label={`Close ${title}`}>
+                            <i className='pi pi-times' aria-hidden='true' />
+                        </Drawer.Close>
+                    </Drawer.Header>
+                    <Drawer.Content>
+                        <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={{}}
-                    />
+                            <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={{}} />
-                    )}
+                            {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>
-                    )}
+                            {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>
-        </>
+                            {slots.content}
+                        </div>
+                    </Drawer.Content>
+                </Drawer.Popup>
+            </Drawer.Portal>
+        </Drawer.Root>
     );
 }

package/shell/MenuEntry.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 an overlay menu or a breadcrumb trail.
+ *
+ * PrimeReact 10 shipped this shape as `primereact/menuitem` and both the user menu and the breadcrumb
+ * handed an array of it to a `model` prop. PrimeReact 11 deleted that module along with every
+ * `model`-driven menu - the components are compositional now - so the *data* half of the contract no
+ * longer has an owner in the library. It belongs to whoever reads the element properties, which is this
+ * package: the shell is what turns a template's `{ label, icon, targetScreen }` records into rendered
+ * entries, so the type it maps them into lives beside the components that map them rather than being
+ * re-declared, slightly differently, in each one.
+ *
+ * It is deliberately the three fields the shell renders rather than a port of PrimeReact 10's full
+ * `MenuItem`. Fields nothing renders are fields nothing keeps honest.
+ */
+export interface MenuEntry {
+    /** What to show for the entry. */
+    label: string;
+
+    /** The icon font class to draw before the label, or undefined for a label on its own. */
+    icon?: string;
+
+    /** Where activating the entry navigates, or undefined when the entry is the page already shown. */
+    url?: string;
+}

package/shell/Sidebar.tsx

@@ -30,13 +30,14 @@ export function Sidebar({ element, slots }: RegisteredComponentProps) {
                 {isPinnable && (
                     <Button
                         type='button'
-                        text
+                        variant='text'
                         rounded
-                        icon={config.isSidebarAnchored ? 'pi pi-lock' : 'pi pi-lock-open'}
+                        iconOnly
                         aria-label={config.isSidebarAnchored ? 'Unpin the menu' : 'Pin the menu open'}
                         aria-pressed={config.isSidebarAnchored}
-                        onClick={toggleSidebarAnchor}
-                    />
+                        onClick={toggleSidebarAnchor}>
+                        <i className={config.isSidebarAnchored ? 'pi pi-lock' : 'pi pi-lock-open'} aria-hidden='true' />
+                    </Button>
                 )}
             </div>
             {slots.content}

package/shell/Topbar.tsx

@@ -27,13 +27,14 @@ export function Topbar({ element, slots }: RegisteredComponentProps) {
                 {showsToggle && (
                     <Button
                         type='button'
-                        text
+                        variant='text'
                         rounded
-                        icon='pi pi-bars'
+                        iconOnly
                         aria-label={config.isSidebarOpen ? 'Close the menu' : 'Open the menu'}
                         aria-expanded={config.isSidebarOpen}
-                        onClick={toggleSidebar}
-                    />
+                        onClick={toggleSidebar}>
+                        <i className='pi pi-bars' aria-hidden='true' />
+                    </Button>
                 )}
                 {slots.logo}
                 {slots.start}

package/shell/UserMenu.tsx

@@ -1,12 +1,11 @@
 // 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 { MenuEntry } from './MenuEntry';
 import { readRecords, readString, recordString } from './elementProperties';
 
 /**
@@ -14,16 +13,22 @@ import { readRecords, readString, recordString } from './elementProperties';
  *
  * 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
+ * how a shell ends up with its own subtly broken menu. The shell hand-writes CSS only where PrimeReact
  * has no primitive at all - the app-shell modes - and uses the library everywhere else.
+ *
+ * PrimeReact 11 replaced the `model` array with composition, so the entries are rendered here rather than
+ * handed over as data - and `primereact/menuitem`, the type that array was made of, went with it, which is
+ * why they are mapped into this package's own {@link MenuEntry}. The trade is worth taking: `Menu.Trigger`
+ * now owns opening the popup and reporting `aria-haspopup`/`aria-expanded` for it, so the ref, the toggle
+ * handler and the hand-maintained aria that used to sit here - and could drift out of step with the popup
+ * they described - are gone.
  */
 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 => ({
+        (item): MenuEntry => ({
             label: recordString(item, 'label'),
             icon: recordString(item, 'icon') || undefined,
             url: recordString(item, 'targetScreen') ? `#/${recordString(item, 'targetScreen')}` : undefined,
@@ -32,22 +37,32 @@ export function UserMenu({ element }: RegisteredComponentProps) {
 
     return (
         <div className='layout-user-menu' data-scene-id={element.id}>
-            <Avatar label={initials} shape='circle' />
+            <Avatar.Root shape='circle'>
+                <Avatar.Fallback>{initials}</Avatar.Fallback>
+            </Avatar.Root>
             <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)}
-            />
+            <PrimeMenu.Root>
+                <PrimeMenu.Trigger as={Button} variant='text' rounded iconOnly aria-label={`Open the menu for ${name}`}>
+                    <i className='pi pi-angle-down' aria-hidden='true' />
+                </PrimeMenu.Trigger>
+                <PrimeMenu.Portal>
+                    <PrimeMenu.Positioner>
+                        <PrimeMenu.Popup>
+                            <PrimeMenu.List>
+                                {items.map(item => (
+                                    <PrimeMenu.Item key={item.label} as='a' href={item.url}>
+                                        {item.icon && <i className={item.icon} aria-hidden='true' />}
+                                        <span>{item.label}</span>
+                                    </PrimeMenu.Item>
+                                ))}
+                            </PrimeMenu.List>
+                        </PrimeMenu.Popup>
+                    </PrimeMenu.Positioner>
+                </PrimeMenu.Portal>
+            </PrimeMenu.Root>
         </div>
     );
 }

package/shell/index.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './elementProperties';
+export * from './MenuEntry';
 export * from './ThemeOption';
 export * from './AppShell';
 export * from './FullPageShell';

package/shell/layout.css

@@ -4,11 +4,11 @@
 /*
  * Cratis Scene - default layout package stylesheet.
  *
- * Every mode this shell implements is hand-written here. PrimeReact 10 has no app-shell primitive to
- * lean on: its `Sidebar` is an overlay drawer (renamed `Drawer` in v11), not a dockable application
- * sidebar, so the docked/rail/reveal/drawer behaviors have to be CSS. PrimeReact 11 introduces a real
- * `Sidebar` with `variant`/`collapsible`/`side`/`overlay`/`openOnHover` props and a `Sidebar.Layout`
- * registry that would replace most of this file - see the README for what a v11 port collapses.
+ * Every mode this shell implements is hand-written here. PrimeReact 11 does ship a real app-shell
+ * `Sidebar` - a genuinely new primitive, not v10's overlay drawer, which is now `Drawer` - and adopting
+ * it would replace most of this file. That is a deliberate follow-up rather than something the version
+ * bump did: rewriting eight layout modes onto a new primitive is a behavior change. See the README for
+ * what such a port collapses and what would stay this package's own.
  *
  * TOKEN BRIDGE
  * ------------

package/.storybook/preview.ts

@@ -1,20 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import type { Preview } from '@storybook/react';
-
-// PrimeReact 10 ships its base styles and one theme per file, and the shell's own stylesheet layers on
-// top of them. Loading them here rather than from a story keeps every story looking the same and matches
-// what a host does once, at its entry point.
-import 'primereact/resources/primereact.min.css';
-import 'primereact/resources/themes/lara-light-indigo/theme.css';
-import 'primeicons/primeicons.css';
-import '../shell/layout.css';
-
-const preview: Preview = {
-    parameters: {
-        controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
-    },
-};
-
-export default preview;