@cratis/scene.primereact 1.1.0 → 3.0.0

package/misc/PrimeInplace.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Inplace, InplaceContent, InplaceDisplay } from 'primereact/inplace';
+import { Inplace } from 'primereact/inplace';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { booleanProperty, stringProperty } from '../properties';
 
@@ -11,12 +11,24 @@ import { booleanProperty, stringProperty } from '../properties';
  * The collapsed view comes from the `label` property and the expanded view from the `content` slot,
  * because the two are different kinds of thing: one is a value, the other is whatever editor the screen
  * wants behind it.
+ *
+ * PrimeReact 11 turned the `closable` flag into a `Close` part, which is a better arrangement than it
+ * looks: the button now lives *inside* the editor, so it is reached by the same tab order as the editor
+ * itself instead of floating beside a region the reader has already left. The property is kept and simply
+ * decides whether that part is rendered, so screens written against v10 keep meaning what they said.
  */
 export function PrimeInplace({ element, slots }: RegisteredComponentProps) {
     return (
-        <Inplace data-scene-id={element.id} closable={booleanProperty(element, 'closable', true)}>
-            <InplaceDisplay>{stringProperty(element, 'label', 'Click to edit')}</InplaceDisplay>
-            <InplaceContent>{slots.content}</InplaceContent>
-        </Inplace>
+        <Inplace.Root data-scene-id={element.id}>
+            <Inplace.Display>{stringProperty(element, 'label', 'Click to edit')}</Inplace.Display>
+            <Inplace.Content>
+                {slots.content}
+                {booleanProperty(element, 'closable', true) && (
+                    <Inplace.Close aria-label='Close editor'>
+                        <i className='pi pi-times' aria-hidden='true' />
+                    </Inplace.Close>
+                )}
+            </Inplace.Content>
+        </Inplace.Root>
     );
 }

package/misc/PrimeProgressBar.tsx

@@ -10,16 +10,20 @@ import { booleanProperty, numberProperty } from '../properties';
  *
  * The mode follows whether a `value` was given at all: progress you cannot measure is exactly what
  * indeterminate mode is for, so an element with no value animates rather than sitting at zero.
+ *
+ * In PrimeReact 11 the root is a headless wrapper that renders no element of its own - `Track` is the
+ * first real DOM node and the one carrying the ARIA `progressbar` role - so `data-scene-id` and the bar's
+ * height belong there rather than on `Root`. `Indicator` renders its children only in determinate mode,
+ * which is why the value label can be handed to it unconditionally: an indeterminate bar has no
+ * percentage to print and drops it on its own.
  */
 export function PrimeProgressBar({ element }: RegisteredComponentProps) {
     const value = numberProperty(element, 'value');
     return (
-        <ProgressBar
-            data-scene-id={element.id}
-            value={value}
-            mode={value === undefined ? 'indeterminate' : 'determinate'}
-            showValue={booleanProperty(element, 'showValue', true)}
-            style={{ height: '1rem' }}
-        />
+        <ProgressBar.Root value={value} mode={value === undefined ? 'indeterminate' : 'determinate'}>
+            <ProgressBar.Track data-scene-id={element.id} style={{ height: '1rem' }}>
+                <ProgressBar.Indicator>{booleanProperty(element, 'showValue', true) && <ProgressBar.Value />}</ProgressBar.Indicator>
+            </ProgressBar.Track>
+        </ProgressBar.Root>
     );
 }

package/misc/PrimeProgressSpinner.tsx

@@ -7,8 +7,21 @@ import { numberProperty } from '../properties';
 
 /**
  * The `PrimeReact:progressSpinner` component - an indeterminate busy indicator.
+ *
+ * PrimeReact 11 opens the SVG up into parts: `Root` draws the `svg` and its viewBox, `Track` is the
+ * circle that stays put and `Range` the arc that turns. Both are needed for the spinner to read as a ring
+ * rather than a lone rotating stroke, so the adapter always supplies the pair - a Scene element has no
+ * property that would sensibly omit one.
+ *
+ * `strokeWidth` is a number in v11 where v10 took a string, and it is left at the component's own default
+ * because the only thing a screen sizes here is the diameter.
  */
 export function PrimeProgressSpinner({ element }: RegisteredComponentProps) {
     const size = numberProperty(element, 'size', 50);
-    return <ProgressSpinner data-scene-id={element.id} strokeWidth='4' style={{ width: `${size}px`, height: `${size}px` }} />;
+    return (
+        <ProgressSpinner.Root data-scene-id={element.id} style={{ width: `${size}px`, height: `${size}px` }}>
+            <ProgressSpinner.Track />
+            <ProgressSpinner.Range />
+        </ProgressSpinner.Root>
+    );
 }

package/misc/PrimeScrollTop.tsx

@@ -1,24 +1,32 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ScrollTop } from 'primereact/scrolltop';
+import { useRef } from 'react';
 import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ScrollTop } from './ScrollTop';
 import { numberProperty } from '../properties';
 
 /**
  * The `PrimeReact:scrollTop` component - a button that returns the reader to the top.
  *
- * Targets its own scrollable parent rather than the window, and the adapter provides that parent. A
- * window-targeted ScrollTop inside a composed screen would scroll something the element does not own,
- * and would stay invisible in any preview shorter than a page.
+ * PrimeReact 11 removed `ScrollTop` with no replacement and no headless hook, so the adapter renders
+ * Cratis's own {@link ScrollTop}. The element keeps the shape it had: a sized, scrollable box holding the
+ * `content` slot, with the button watching that box rather than the window. A window-targeted button
+ * inside a composed screen would scroll something the element does not own, and would stay invisible in
+ * any preview shorter than a page.
  *
- * In PrimeReact 11 this becomes a hook rather than a component.
+ * The box and the scrolling region are two elements rather than one, which is what lets the button sit
+ * still while the content moves under it. Anchored inside the scroller it would drift off with the
+ * content it is offering to escape.
  */
 export function PrimeScrollTop({ element, slots }: RegisteredComponentProps) {
+    const scroller = useRef<HTMLDivElement>(null);
     return (
-        <div data-scene-id={element.id} className='relative overflow-auto' style={{ height: `${numberProperty(element, 'height', 200)}px` }}>
-            {slots.content}
-            <ScrollTop target='parent' threshold={numberProperty(element, 'threshold', 100)} />
+        <div data-scene-id={element.id} className='relative'>
+            <div ref={scroller} className='overflow-auto' style={{ height: `${numberProperty(element, 'height', 200)}px` }}>
+                {slots.content}
+            </div>
+            <ScrollTop target={scroller} threshold={numberProperty(element, 'threshold', 100)} />
         </div>
     );
 }

package/misc/PrimeSkeleton.tsx

@@ -7,6 +7,10 @@ import { stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:skeleton` component - the shape of content that has not arrived yet.
+ *
+ * One of the few components PrimeReact 11 left whole, and the props survived with it. The defaults are
+ * repeated here rather than left to the component because a skeleton is only ever authored for a specific
+ * gap in a layout, and a full-width one-line bar is the gap a screen most often has.
  */
 export function PrimeSkeleton({ element }: RegisteredComponentProps) {
     return (

package/misc/PrimeTag.tsx

@@ -3,19 +3,30 @@
 
 import { Tag } from 'primereact/tag';
 import { RegisteredComponentProps } from '@cratis/scene.react';
-import { booleanProperty, stringProperty } from '../properties';
+import {booleanProperty, severityProperty, stringProperty} from '../properties';
 
 /**
  * The `PrimeReact:tag` component - a colored status label, the read-only counterpart to a chip.
+ *
+ * PrimeReact 11 dropped the `value` and `icon` props; a tag renders its children now. The icon is marked
+ * decorative because the value beside it already carries the meaning - a screen reader announcing
+ * "check-circle Published" would be reading the styling out loud.
+ *
+ * The v10 severity `warning` is translated to v11's `warn` rather than passed through, so a screen
+ * authored against the old vocabulary keeps its color instead of quietly rendering in the default one.
  */
 export function PrimeTag({ element }: RegisteredComponentProps) {
+    const icon = stringProperty(element, 'icon');
+    // Tag and Badge are the two components PrimeReact 11 gives no `help` variant, so an authored
+    // `help` degrades to the default styling rather than failing to compile.
+    const severity = severityProperty(element, 'severity');
     return (
         <Tag
             data-scene-id={element.id}
-            value={stringProperty(element, 'value', '')}
-            icon={stringProperty(element, 'icon')}
-            severity={stringProperty(element, 'severity') as 'success' | 'info' | 'warning' | 'danger' | 'secondary' | 'contrast' | undefined}
-            rounded={booleanProperty(element, 'rounded', false)}
-        />
+            severity={severity === 'help' ? undefined : severity}
+            rounded={booleanProperty(element, 'rounded', false)}>
+            {icon !== undefined && <i className={icon} aria-hidden='true' />}
+            {stringProperty(element, 'value', '')}
+        </Tag>
     );
 }

package/misc/PrimeTerminal.tsx

@@ -8,17 +8,26 @@ import { stringProperty } from '../properties';
 /**
  * The `PrimeReact:terminal` component - a command-line surface.
  *
- * Terminal publishes typed commands on `TerminalService` and waits for something to answer. Nothing in
- * this package answers, because responding to a command is application behavior and a Scene element
- * cannot express it. The component therefore accepts input and prints nothing back until the hosting
- * application subscribes - which is the honest shape of a terminal with no backend, not a broken one.
+ * Terminal accepts input and waits for something to answer. Nothing in this package answers, because
+ * responding to a command is application behavior and a Scene element cannot express it. The component
+ * therefore echoes what is typed and prints nothing back until the hosting application supplies an
+ * answer - which is the honest shape of a terminal with no backend, not a broken one.
+ *
+ * PrimeReact 11 changed how that answer arrives: v10 published commands on a global `TerminalService`
+ * that any listener could subscribe to, and v11 takes an `onCommand` callback on the component instead.
+ * That is a real improvement for an application - the wiring is local and typed rather than a global
+ * channel keyed by nothing - but it is also why the gap cannot be closed here: a callback has to come from
+ * whoever mounts the screen, and the adapter only has the element.
+ *
+ * `CommandList` and `Prompt` render themselves from the component's own state when given no children, so
+ * the composition is just naming the three regions a terminal has.
  */
 export function PrimeTerminal({ element }: RegisteredComponentProps) {
     return (
-        <Terminal
-            data-scene-id={element.id}
-            welcomeMessage={stringProperty(element, 'welcomeMessage', 'Welcome')}
-            prompt={stringProperty(element, 'prompt', '$')}
-        />
+        <Terminal.Root data-scene-id={element.id} prompt={stringProperty(element, 'prompt', '$')}>
+            <Terminal.Welcome>{stringProperty(element, 'welcomeMessage', 'Welcome')}</Terminal.Welcome>
+            <Terminal.CommandList />
+            <Terminal.Prompt />
+        </Terminal.Root>
     );
 }

package/misc/ScrollTop.tsx

@@ -0,0 +1,81 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { HTMLAttributes, RefObject, useEffect, useState } from 'react';
+import { Button } from 'primereact/button';
+
+/**
+ * Configuration for {@link ScrollTop}.
+ */
+export interface ScrollTopProps extends Omit<HTMLAttributes<HTMLButtonElement>, 'children'> {
+    /**
+     * How far the target has to have scrolled, in pixels, before the button appears. A button that is
+     * always there is clutter; one that appears too late is never found.
+     */
+    threshold?: number;
+
+    /**
+     * The element to watch and return to the top of. Left out, the button watches the window - which is
+     * the right default for a page, and the wrong one for a component embedded in a composed screen,
+     * which is why the caller supplies it.
+     */
+    target?: RefObject<HTMLElement | null>;
+
+    /**
+     * The icon class to show, so an application using its own icon font is not forced onto `primeicons`.
+     */
+    icon?: string;
+}
+
+/**
+ * A button that appears once its target has been scrolled past a threshold and takes the reader back to
+ * the top.
+ *
+ * Cratis owns this component. PrimeReact 10 had `ScrollTop`; PrimeReact 11 removed it with no replacement
+ * and no headless hook, and `scrollTop` is a name this package's manifest publishes, so screens are
+ * written against it. The button itself is a PrimeReact `Button` - the piece that survived - so the
+ * component still picks up whatever theme the application is running, and only the scroll watching is
+ * ours.
+ *
+ * The listener is registered on the target and removed when the component unmounts or the target changes.
+ * That is not incidental tidiness: this button is typically mounted inside a scrolling region that a
+ * screen creates and destroys as the reader navigates, and a leaked `scroll` handler on a detached
+ * element keeps the whole subtree alive.
+ *
+ * What it deliberately does not carry over from v10: the enter/leave transition (the button appears and
+ * disappears outright), `behavior` as a prop - scrolling is always smooth, since an instant jump to the
+ * top is disorienting and the only reason v10 exposed it was browsers that lacked support - and the
+ * `pt` / passthrough styling hooks, which have no meaning outside PrimeReact's own component base.
+ */
+export function ScrollTop({ threshold = 400, target, icon = 'pi pi-chevron-up', className, ...rest }: ScrollTopProps) {
+    const [visible, setVisible] = useState(false);
+
+    useEffect(() => {
+        const element = target?.current;
+        const source: EventTarget = element ?? window;
+        const update = () => setVisible((element ? element.scrollTop : window.scrollY) > threshold);
+
+        update();
+        source.addEventListener('scroll', update, { passive: true });
+        return () => source.removeEventListener('scroll', update);
+    }, [target, threshold]);
+
+    if (!visible) return null;
+
+    const scrollToTop = () => {
+        const element = target?.current;
+        if (element) element.scrollTo({ top: 0, behavior: 'smooth' });
+        else window.scrollTo({ top: 0, behavior: 'smooth' });
+    };
+
+    return (
+        <Button
+            aria-label='Scroll to top'
+            {...rest}
+            rounded
+            className={[target === undefined ? 'fixed bottom-6 right-6 z-40' : 'absolute bottom-3 right-3 z-10', className].filter(Boolean).join(' ')}
+            onClick={scrollToTop}>
+            <i className={icon} aria-hidden='true' />
+        </Button>
+    );
+}

package/misc/index.ts

@@ -12,3 +12,5 @@ export * from './PrimeScrollTop';
 export * from './PrimeBlockUI';
 export * from './PrimeInplace';
 export * from './PrimeTerminal';
+export * from './BlockUI';
+export * from './ScrollTop';

package/overlay/ConfirmDialog.tsx

@@ -0,0 +1,135 @@
+// 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 { Button } from 'primereact/button';
+import { Dialog } from 'primereact/dialog';
+
+/**
+ * Configuration for {@link ConfirmDialog}.
+ */
+export interface ConfirmDialogProps {
+    /**
+     * Whether the dialog is showing. The dialog is a controlled overlay - it never hides itself - so the
+     * owner keeps this in state and lowers it from {@link ConfirmDialogProps.onHide}.
+     */
+    visible: boolean;
+
+    /**
+     * The question being asked. Typed as a node rather than a string so a caller can pose a question that
+     * needs emphasis or a name in it, which is exactly the kind of question worth confirming.
+     */
+    message?: ReactNode;
+
+    /**
+     * The dialog's title.
+     */
+    header?: string;
+
+    /**
+     * A PrimeIcons class shown beside the message. Omitted entirely when absent rather than defaulted,
+     * because the icon on a confirmation carries tone - a warning triangle on a harmless question is
+     * misleading - and only the caller knows which is right.
+     */
+    icon?: string;
+
+    /**
+     * Label for the accepting button.
+     */
+    acceptLabel?: string;
+
+    /**
+     * Label for the rejecting button.
+     */
+    rejectLabel?: string;
+
+    /**
+     * Called when the user accepts. Always followed by {@link ConfirmDialogProps.onHide}.
+     */
+    onAccept?: () => void;
+
+    /**
+     * Called when the user rejects. Always followed by {@link ConfirmDialogProps.onHide}.
+     */
+    onReject?: () => void;
+
+    /**
+     * Called whenever the dialog should close - after either answer, and on every dismissal gesture
+     * (the close button, `Escape`, a click on the backdrop). Answering and closing are reported
+     * separately so a caller can lower `visible` in one place instead of in three.
+     */
+    onHide?: () => void;
+}
+
+/**
+ * A Cratis-owned confirmation dialog - a question, an accepting answer and a rejecting one.
+ *
+ * This component is owned by Cratis because PrimeReact 11 removed `primereact/confirmdialog` outright.
+ * There is no renamed successor to adapt to: what v11 ships instead is the compositional `Dialog` this is
+ * built from, on the reasoning that a confirmation is a dialog with a known footer rather than a distinct
+ * component. That is a fair reading, but it would otherwise push the same header/message/two-buttons
+ * assembly into every caller, so this package assembles it once here and keeps the shape v10 callers
+ * already expect.
+ *
+ * Two v10 capabilities are deliberately **not** carried over:
+ *
+ * - **The imperative `confirmDialog()` service API.** v10 let any code open a confirmation by calling a
+ *   module-level function that reached a singleton mounted elsewhere. That needs a caller and a global
+ *   mount point; this component is rendered and controlled by whoever owns the answer, which is the only
+ *   form a Scene element - configuration, not a caller - can use anyway.
+ * - **`appendTo`.** v10 needed it to escape stacking contexts. v11 renders through `Dialog.Portal` under
+ *   an overlay manager that handles layering, so the prop existed only to work around a problem that is
+ *   now gone.
+ *
+ * @param props - {@link ConfirmDialogProps}.
+ */
+export function ConfirmDialog({ visible, message, header, icon, acceptLabel, rejectLabel, onAccept, onReject, onHide }: ConfirmDialogProps) {
+    const accept = () => {
+        onAccept?.();
+        onHide?.();
+    };
+
+    const reject = () => {
+        onReject?.();
+        onHide?.();
+    };
+
+    return (
+        <Dialog.Root
+            open={visible}
+            modal
+            dismissable
+            closeOnEscape
+            onOpenChange={(event) => {
+                if (!event.value) onHide?.();
+            }}>
+            <Dialog.Portal>
+                <Dialog.Backdrop />
+                <Dialog.Positioner>
+                    <Dialog.Popup style={{ width: '30rem' }}>
+                        <Dialog.Header>
+                            <Dialog.Title>{header}</Dialog.Title>
+                            <Dialog.Close aria-label='Close'>
+                                <i className='pi pi-times' />
+                            </Dialog.Close>
+                        </Dialog.Header>
+                        <Dialog.Content>
+                            <div className='flex items-center gap-3'>
+                                {icon !== undefined && <i className={icon} />}
+                                <span>{message}</span>
+                            </div>
+                        </Dialog.Content>
+                        <Dialog.Footer>
+                            <div className='flex justify-end gap-2'>
+                                <Button variant='outlined' onClick={reject}>
+                                    {rejectLabel}
+                                </Button>
+                                <Button onClick={accept}>{acceptLabel}</Button>
+                            </div>
+                        </Dialog.Footer>
+                    </Dialog.Popup>
+                </Dialog.Positioner>
+            </Dialog.Portal>
+        </Dialog.Root>
+    );
+}

package/overlay/OverlayGallery.stories.tsx

@@ -12,7 +12,7 @@ const meta = {
     tags: ['autodocs'],
     parameters: {
         layout: 'padded',
-        docs: { description: { component: 'The overlay family. Each one renders its own trigger: an overlay is only interesting while it is open, and a Scene element has nowhere to record that a user closed it, so the adapter owns visibility and keeps a way back.' } },
+        docs: { description: { component: 'The overlay family, on PrimeReact 11. Each one renders its own trigger: an overlay is only interesting while it is open, and a Scene element has nowhere to record that a user closed it, so something has to keep a way back. `dialog`, `confirmDialog` and `sidebar` hold that visibility in the adapter and answer v11\'s `onOpenChange`; `overlayPanel` and `tooltip` let the v11 composition own it, because their trigger is part of the component rather than a button beside it. `sidebar` is built on `primereact/drawer` - v11\'s `Sidebar` is an unrelated application-shell primitive.' } },
     },
 } satisfies Meta<typeof SceneElementView>;
 

package/overlay/PrimeConfirmDialog.tsx

@@ -3,28 +3,33 @@
 
 import { useState } from 'react';
 import { Button } from 'primereact/button';
-import { ConfirmDialog } from 'primereact/confirmdialog';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { stringProperty } from '../properties';
+import { ConfirmDialog } from './ConfirmDialog';
 
 /**
  * The `PrimeReact:confirmDialog` component - a yes/no question before a consequential action.
  *
- * Uses ConfirmDialog's declarative form rather than the imperative `confirmDialog()` call, because the
- * imperative one needs a caller and a Scene element is configuration, not a caller. Visibility is owned
- * locally for the reason described on {@link PrimeDialog}.
+ * Adapts {@link ConfirmDialog}, which this package owns because PrimeReact 11 removed
+ * `primereact/confirmdialog` and shipped no successor - see that component for what the replacement
+ * deliberately leaves behind. The adapter itself is unchanged in spirit from the v10 one: it was already
+ * using the declarative form rather than the imperative `confirmDialog()` call, because that call needs a
+ * caller and a Scene element is configuration, not a caller. That choice is what made this the one
+ * removal in the family that cost nothing at the adapter boundary.
  *
- * In PrimeReact 11 the sibling `ConfirmPopup` is removed; `ConfirmDialog` remains.
+ * Visibility is owned locally for the reason described on {@link PrimeDialog}.
+ *
+ * A Scene element has nowhere to send an answer - there is no handler to bind to - so accepting and
+ * rejecting differ only in closing the dialog. The two callbacks are still wired rather than omitted, so
+ * the seam is here the moment Scene grows a way to express an action.
  */
 export function PrimeConfirmDialog({ element }: RegisteredComponentProps) {
     const [visible, setVisible] = useState(false);
     return (
         <div data-scene-id={element.id}>
-            <Button
-                label={stringProperty(element, 'triggerLabel', 'Confirm')}
-                severity={stringProperty(element, 'severity', 'danger') as 'secondary' | 'success' | 'info' | 'warning' | 'danger' | 'help'}
-                onClick={() => setVisible(true)}
-            />
+            <Button severity={stringProperty(element, 'severity', 'danger')} onClick={() => setVisible(true)}>
+                {stringProperty(element, 'triggerLabel', 'Confirm')}
+            </Button>
             <ConfirmDialog
                 visible={visible}
                 onHide={() => setVisible(false)}

package/overlay/PrimeDialog.tsx

@@ -15,22 +15,49 @@ import { booleanProperty, stringProperty } from '../properties';
  * property, and always renders a trigger button beside it. That keeps a dialog reachable again after it
  * is dismissed - without the trigger, closing a previewed dialog would leave a permanently blank spot on
  * the screen with no way back.
+ *
+ * PrimeReact 11 made `Dialog` compositional, which turns that local visibility into a two-way
+ * arrangement: `open` pushes the state down, and every dismissal gesture - the close button, `Escape`, a
+ * click on the backdrop - comes back as `onOpenChange`. Both have to be wired, because a v11 dialog never
+ * hides itself; ignoring the callback would leave a dialog that opens once and can never be closed.
+ *
+ * The parts are assembled here rather than by the component: `Dialog.Portal` and `Dialog.Backdrop` are
+ * what make it modal, and `Dialog.Close` is the only reason the header gets an X.
+ *
+ * **Not available in v11:** the headless dialog has no resize handle, so a dialog cannot be made
+ * user-resizable. No Scene property is lost to this - this adapter never exposed one - but `draggable`,
+ * which v11 does still support, is the only direct-manipulation affordance left.
  */
 export function PrimeDialog({ element, slots }: RegisteredComponentProps) {
     const [visible, setVisible] = useState(booleanProperty(element, 'visible', false));
     const header = stringProperty(element, 'header', 'Dialog');
     return (
         <div data-scene-id={element.id}>
-            <Button label={stringProperty(element, 'triggerLabel', header)} onClick={() => setVisible(true)} />
-            <Dialog
-                header={header}
-                visible={visible}
-                onHide={() => setVisible(false)}
+            <Button onClick={() => setVisible(true)}>{stringProperty(element, 'triggerLabel', header)}</Button>
+            <Dialog.Root
+                open={visible}
                 modal={booleanProperty(element, 'modal', true)}
                 draggable={booleanProperty(element, 'draggable', false)}
-                style={{ width: stringProperty(element, 'width', '32rem') }}>
-                {slots.content}
-            </Dialog>
+                dismissable
+                closeOnEscape
+                onOpenChange={(event) => {
+                    if (!event.value) setVisible(false);
+                }}>
+                <Dialog.Portal>
+                    <Dialog.Backdrop />
+                    <Dialog.Positioner>
+                        <Dialog.Popup style={{ width: stringProperty(element, 'width', '32rem') }}>
+                            <Dialog.Header>
+                                <Dialog.Title>{header}</Dialog.Title>
+                                <Dialog.Close aria-label='Close'>
+                                    <i className='pi pi-times' />
+                                </Dialog.Close>
+                            </Dialog.Header>
+                            <Dialog.Content>{slots.content}</Dialog.Content>
+                        </Dialog.Popup>
+                    </Dialog.Positioner>
+                </Dialog.Portal>
+            </Dialog.Root>
         </div>
     );
 }

package/overlay/PrimeOverlayPanel.tsx

@@ -1,26 +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 { useRef } from 'react';
 import { Button } from 'primereact/button';
-import { OverlayPanel } from 'primereact/overlaypanel';
+import { Popover } from 'primereact/popover';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:overlayPanel` component - content revealed next to whatever opened it.
  *
- * OverlayPanel positions itself against the event that toggled it, so it is meaningless without a
- * trigger; the adapter renders one and wires `toggle` to it.
+ * A popover positions itself against the thing that opened it, so it is meaningless without a trigger;
+ * the adapter renders one.
  *
- * In PrimeReact 11 this component is renamed `Popover`.
+ * PrimeReact 11 renamed `OverlayPanel` to `Popover` and changed how that trigger is wired. v10 needed a
+ * ref and a `toggle(event)` call because it positioned against the *event*; v11 positions against the
+ * trigger *element*, which `Popover.Trigger` registers itself. That removes the ref, the click handler
+ * and the local visibility state in one go - the composition owns all three - so the trigger here is a
+ * real `Button` supplied as `Popover.Trigger`'s `as`, rather than a separate button wired to a ref.
+ *
+ * The abstract Scene name stays `overlayPanel` so existing screens keep resolving.
  */
 export function PrimeOverlayPanel({ element, slots }: RegisteredComponentProps) {
-    const overlay = useRef<OverlayPanel>(null);
     return (
         <div data-scene-id={element.id}>
-            <Button label={stringProperty(element, 'triggerLabel', 'Show')} onClick={(event) => overlay.current?.toggle(event)} />
-            <OverlayPanel ref={overlay}>{slots.content}</OverlayPanel>
+            <Popover.Root>
+                <Popover.Trigger as={Button}>{stringProperty(element, 'triggerLabel', 'Show')}</Popover.Trigger>
+                <Popover.Portal>
+                    <Popover.Positioner side='bottom'>
+                        <Popover.Popup>
+                            <Popover.Content>{slots.content}</Popover.Content>
+                        </Popover.Popup>
+                    </Popover.Positioner>
+                </Popover.Portal>
+            </Popover.Root>
         </div>
     );
 }