@cratis/scene.primereact 1.1.0 → 3.0.0

package/overlay/PrimeSidebar.tsx

@@ -3,29 +3,55 @@
 
 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 { booleanProperty, stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:sidebar` component - a panel that slides in from an edge of the viewport.
  *
- * Worth knowing before a PrimeReact 11 port: v11 renames this component to `Drawer` *and* introduces an
- * unrelated new component called `Sidebar` for application-shell navigation. A port that follows the
- * name rather than the behavior silently swaps a slide-in overlay for a static shell element.
+ * **This is built on `primereact/drawer`, and that is not a mistake.** PrimeReact 11 renamed this
+ * component to `Drawer` *and* introduced an unrelated new component under the name `Sidebar` -
+ * `primereact/sidebar` in v11 is an application-shell primitive (`SidebarLayout`, `SidebarAside`,
+ * `SidebarPanel`, `SidebarMenu` and friends) for persistent navigation, with no slide-in overlay
+ * behavior anywhere in it. Importing `Sidebar` from v11 to port a v10 `Sidebar` compiles perfectly and
+ * silently replaces a dismissable overlay with a static shell element, which is why the module here is
+ * the one that does not match the name. The abstract Scene name stays `sidebar` so existing screens keep
+ * resolving; only the implementation moved.
+ *
+ * Visibility is owned locally and a trigger is always rendered, for the reason described on
+ * {@link PrimeDialog}, and v11's controlled `open` / `onOpenChange` pair is wired for the reason
+ * described there too.
+ *
+ * v10's `fullScreen` flag became a fifth `position` value rather than a separate prop, so the two Scene
+ * properties collapse into one: `fullScreen` wins when set, since a drawer covering the viewport has no
+ * edge left to slide in from.
  */
 export function PrimeSidebar({ element, slots }: RegisteredComponentProps) {
     const [visible, setVisible] = useState(booleanProperty(element, 'visible', false));
+    const position = booleanProperty(element, 'fullScreen', false) ? 'full' : stringProperty(element, 'position', 'left');
     return (
         <div data-scene-id={element.id}>
-            <Button label={stringProperty(element, 'triggerLabel', 'Open')} onClick={() => setVisible(true)} />
-            <Sidebar
-                visible={visible}
-                onHide={() => setVisible(false)}
-                position={stringProperty(element, 'position', 'left') as 'left' | 'right' | 'top' | 'bottom'}
-                fullScreen={booleanProperty(element, 'fullScreen', false)}>
-                {slots.content}
-            </Sidebar>
+            <Button onClick={() => setVisible(true)}>{stringProperty(element, 'triggerLabel', 'Open')}</Button>
+            <Drawer.Root
+                open={visible}
+                position={position as 'left' | 'right' | 'top' | 'bottom' | 'full'}
+                onOpenChange={(event) => {
+                    if (!event.value) setVisible(false);
+                }}>
+                <Drawer.Portal>
+                    <Drawer.Backdrop />
+                    <Drawer.Popup>
+                        <Drawer.Header>
+                            <Drawer.Title>{stringProperty(element, 'header')}</Drawer.Title>
+                            <Drawer.Close aria-label='Close'>
+                                <i className='pi pi-times' />
+                            </Drawer.Close>
+                        </Drawer.Header>
+                        <Drawer.Content>{slots.content}</Drawer.Content>
+                    </Drawer.Popup>
+                </Drawer.Portal>
+            </Drawer.Root>
         </div>
     );
 }

package/overlay/PrimeTooltip.tsx

@@ -8,19 +8,33 @@ import { stringProperty } from '../properties';
 /**
  * The `PrimeReact:tooltip` component - explanatory text shown on hover.
  *
- * Tooltip attaches itself to a CSS selector rather than wrapping anything, so the adapter renders the
- * hover target too and points the tooltip at it with a `data-` attribute selector. An attribute selector
- * is used rather than a class because a Scene element id is free-form and may legally start with a digit,
- * which is not a valid class selector.
+ * The adapter renders the hover target as well as the tooltip, because a tooltip with nothing to point
+ * at has nothing to do.
+ *
+ * PrimeReact 11 replaced the v10 mechanism entirely and this adapter got simpler for it. v10's `Tooltip`
+ * attached itself to a CSS selector and read its text from a `data-pr-tooltip` attribute on whatever it
+ * found, which forced this adapter to invent a unique attribute selector - and to use an attribute rather
+ * than a class, because a Scene element id is free-form and may legally start with a digit, which is not
+ * a valid class selector. v11 wraps the target instead: `Tooltip.Trigger` *is* the target, so the
+ * selector, the generated attribute and the whole indirection are gone.
+ *
+ * The trigger is rendered as a `span` rather than v11's default `button`, because the `content` slot may
+ * hold any Scene children at all - including a button, which nested inside another button is invalid
+ * markup that browsers silently restructure. The cost is that a bare label is not keyboard focusable and
+ * so shows on hover only; when a screen puts a real control in the slot, that control brings its own
+ * focus behavior.
  */
 export function PrimeTooltip({ element, slots }: RegisteredComponentProps) {
-    const target = `[data-scene-tooltip-target="${element.id}"]`;
     return (
-        <>
-            <Tooltip target={target} position={stringProperty(element, 'position', 'top') as 'top' | 'bottom' | 'left' | 'right'} />
-            <span data-scene-id={element.id} data-scene-tooltip-target={element.id} data-pr-tooltip={stringProperty(element, 'text', '')}>
+        <Tooltip.Root>
+            <Tooltip.Trigger as='span' data-scene-id={element.id}>
                 {slots.content?.length ? slots.content : stringProperty(element, 'label', 'Hover me')}
-            </span>
-        </>
+            </Tooltip.Trigger>
+            <Tooltip.Portal>
+                <Tooltip.Positioner side={stringProperty(element, 'position', 'top') as 'top' | 'bottom' | 'left' | 'right'}>
+                    <Tooltip.Popup>{stringProperty(element, 'text', '')}</Tooltip.Popup>
+                </Tooltip.Positioner>
+            </Tooltip.Portal>
+        </Tooltip.Root>
     );
 }

package/overlay/index.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './ConfirmDialog';
 export * from './PrimeDialog';
 export * from './PrimeConfirmDialog';
 export * from './PrimeOverlayPanel';

package/package.json

@@ -1,7 +1,17 @@
 {
     "name": "@cratis/scene.primereact",
-    "version": "1.1.0",
+    "version": "3.0.0",
     "description": "The PrimeReact component package: maps Scene's abstract component names onto real PrimeReact components, and PrimeReact's free themes onto Scene themes.",
+    "keywords": [
+        "cratis",
+        "scene",
+        "react",
+        "ui",
+        "primereact",
+        "components",
+        "themes",
+        "low-code"
+    ],
     "author": "Cratis",
     "license": "MIT",
     "repository": {
@@ -42,27 +52,33 @@
         "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",
+        "@primeuix/themes": "^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",
+        "@primereact/types": "11.1.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": {
-        "primeicons": "^7.0.0",
-        "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/panel/PanelGallery.stories.tsx

@@ -12,7 +12,7 @@ const meta = {
     tags: ['autodocs'],
     parameters: {
         layout: 'padded',
-        docs: { description: { component: 'The panel family. `accordion`, `tabView`, `splitter` and `stepper` pair a headers property with the content slot by position, because PrimeReact identifies their sections by React element type and a Scene adapter wrapping one would not be recognized.' } },
+        docs: { description: { component: 'The panel family, on PrimeReact 11. `accordion`, `tabView`, `splitter` and `stepper` pair a headers property with the content slot by position, because a slot arrives as a flat list of already-rendered children with nowhere to hang a per-child title. Every component here except `divider` is compositional in v11, so each adapter assembles the parts - a `tabView` with no `Tabs.Indicator`, or a `splitter` with no `Splitter.Gutter`, renders without an active underline or a drag bar rather than failing.' } },
     },
 } satisfies Meta<typeof SceneElementView>;
 

package/panel/PrimeAccordion.tsx

@@ -1,29 +1,47 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Accordion, AccordionTab } from 'primereact/accordion';
+import { Accordion } from 'primereact/accordion';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { numberProperty, stringArrayProperty } from '../properties';
 
 /**
  * The `PrimeReact:accordion` component - stacked sections of which one is open at a time.
  *
- * Accordion identifies its sections by React element type (`AccordionTab`), so a Scene adapter wrapping
- * one would not be recognized. Sections are therefore paired here: the `headers` property gives the
- * titles and the `content` slot gives the bodies, matched by position. A screen puts as many children in
- * the slot as it lists headers.
+ * Sections are paired by position: the `headers` property gives the titles and the `content` slot gives
+ * the bodies. That pairing is a consequence of the Scene model rather than of PrimeReact - a slot arrives
+ * as a flat list of already-rendered children with nowhere to hang a per-child title - so a screen puts as
+ * many children in the slot as it lists headers.
+ *
+ * PrimeReact 11 replaced `AccordionTab` with a `Accordion.Panel` / `Header` / `Trigger` / `Content`
+ * composition keyed by an explicit `value`, which retires the v10 constraint that sections had to *be*
+ * `AccordionTab` elements for the accordion to recognize them. The index doubles as that value, so the
+ * `activeIndex` property still means what it always did. It is passed as `defaultValue` rather than
+ * `value` because a screen states which section starts open - binding it as the controlled value would
+ * pin the accordion to that section and silently swallow every click.
  */
 export function PrimeAccordion({ element, slots }: RegisteredComponentProps) {
     const headers = stringArrayProperty(element, 'headers');
     const bodies = slots.content ?? [];
     const count = Math.max(headers.length, bodies.length);
     return (
-        <Accordion data-scene-id={element.id} activeIndex={numberProperty(element, 'activeIndex', 0)}>
+        <Accordion.Root data-scene-id={element.id} defaultValue={String(numberProperty(element, 'activeIndex', 0))}>
             {Array.from({ length: count }, (_, index) => (
-                <AccordionTab key={index} header={headers[index] ?? `Section ${index + 1}`}>
-                    {bodies[index]}
-                </AccordionTab>
+                <Accordion.Panel key={index} value={String(index)}>
+                    <Accordion.Header>
+                        <Accordion.Trigger>
+                            {headers[index] ?? `Section ${index + 1}`}
+                            <Accordion.Indicator match='open'>
+                                <i className='pi pi-chevron-up' />
+                            </Accordion.Indicator>
+                            <Accordion.Indicator match='closed'>
+                                <i className='pi pi-chevron-down' />
+                            </Accordion.Indicator>
+                        </Accordion.Trigger>
+                    </Accordion.Header>
+                    <Accordion.Content>{bodies[index]}</Accordion.Content>
+                </Accordion.Panel>
             ))}
-        </Accordion>
+        </Accordion.Root>
     );
 }

package/panel/PrimeCard.tsx

@@ -11,11 +11,26 @@ import { stringProperty } from '../properties';
  * One of the three names this package deliberately shares with `core` (alongside `text` and `button`), so
  * a profile that lists `core` and then `PrimeReact` upgrades every card on every screen to a themed one
  * without a single screen being edited.
+ *
+ * PrimeReact 11 turned `Card` into a namespace of parts, so the v10 `title` / `subTitle` props no longer
+ * exist - the caption is something the adapter assembles. The caption block is omitted entirely when a
+ * screen supplies neither, because an empty `Card.Caption` still reserves its spacing and would leave an
+ * unexplained gap above the body of an untitled card.
  */
 export function PrimeCard({ element, slots }: RegisteredComponentProps) {
+    const title = stringProperty(element, 'title');
+    const subtitle = stringProperty(element, 'subtitle');
     return (
-        <Card data-scene-id={element.id} title={stringProperty(element, 'title')} subTitle={stringProperty(element, 'subtitle')}>
-            {slots.content}
-        </Card>
+        <Card.Root data-scene-id={element.id}>
+            <Card.Body>
+                {(title !== undefined || subtitle !== undefined) && (
+                    <Card.Caption>
+                        {title !== undefined && <Card.Title>{title}</Card.Title>}
+                        {subtitle !== undefined && <Card.Subtitle>{subtitle}</Card.Subtitle>}
+                    </Card.Caption>
+                )}
+                <Card.Content>{slots.content}</Card.Content>
+            </Card.Body>
+        </Card.Root>
     );
 }

package/panel/PrimeDivider.tsx

@@ -7,13 +7,18 @@ import { stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:divider` component - a rule separating content, optionally with a caption in it.
+ *
+ * The last component in this family PrimeReact 11 left monolithic, so the port is only a prop rename:
+ * v10's `layout` is v11's `orientation`. The Scene property keeps the name `layout`, because a screen's
+ * property vocabulary is this package's contract with authored content and renaming it would break every
+ * screen that set it to buy nothing.
  */
 export function PrimeDivider({ element }: RegisteredComponentProps) {
     const label = stringProperty(element, 'label');
     return (
         <Divider
             data-scene-id={element.id}
-            layout={stringProperty(element, 'layout', 'horizontal') as 'horizontal' | 'vertical'}
+            orientation={stringProperty(element, 'layout', 'horizontal') as 'horizontal' | 'vertical'}
             align={stringProperty(element, 'align') as 'center' | 'left' | 'right' | 'top' | 'bottom' | undefined}
             type={stringProperty(element, 'type', 'solid') as 'solid' | 'dashed' | 'dotted'}>
             {label}

package/panel/PrimeFieldset.tsx

@@ -7,11 +7,33 @@ import { booleanProperty, stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:fieldset` component - a container whose legend sits on its border.
+ *
+ * PrimeReact 11 dropped the `toggleable` prop entirely: a compositional `Fieldset` is collapsible exactly
+ * when its legend contains a `Fieldset.Trigger`, and inert when it does not. The Scene `toggleable`
+ * property therefore selects between two legend shapes rather than setting a flag. Both are rendered as a
+ * real `<legend>` either way, so the non-toggleable case does not pay for a button it never uses - which
+ * also keeps a static fieldset out of the tab order.
  */
 export function PrimeFieldset({ element, slots }: RegisteredComponentProps) {
+    const legend = stringProperty(element, 'legend');
     return (
-        <Fieldset data-scene-id={element.id} legend={stringProperty(element, 'legend')} toggleable={booleanProperty(element, 'toggleable', false)}>
-            {slots.content}
-        </Fieldset>
+        <Fieldset.Root data-scene-id={element.id} defaultOpen>
+            <Fieldset.Legend>
+                {booleanProperty(element, 'toggleable', false) ? (
+                    <Fieldset.Trigger>
+                        <Fieldset.Title>{legend}</Fieldset.Title>
+                        <Fieldset.Indicator match='open'>
+                            <i className='pi pi-chevron-up' />
+                        </Fieldset.Indicator>
+                        <Fieldset.Indicator match='closed'>
+                            <i className='pi pi-chevron-down' />
+                        </Fieldset.Indicator>
+                    </Fieldset.Trigger>
+                ) : (
+                    <Fieldset.Title>{legend}</Fieldset.Title>
+                )}
+            </Fieldset.Legend>
+            <Fieldset.Content>{slots.content}</Fieldset.Content>
+        </Fieldset.Root>
     );
 }

package/panel/PrimePanel.tsx

@@ -7,15 +7,34 @@ import { booleanProperty, stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:panel` component - a titled container that can optionally collapse.
+ *
+ * PrimeReact 11 made `Panel` compositional, which moves one decision into the adapter that v10 made
+ * internally: the collapse affordance exists only if something renders a `Panel.Trigger`. Rendering one
+ * unconditionally would put a chevron on every panel, including the ones a screen declared as fixed, so
+ * the trigger is tied to the same `toggleable` property that enables the behavior.
+ *
+ * The `collapsed` property is expressed as `defaultOpen` rather than a controlled `open`, because a
+ * screen states the *initial* state; holding the panel open or shut against the user's clicks is not what
+ * `collapsed: true` means.
  */
 export function PrimePanel({ element, slots }: RegisteredComponentProps) {
+    const toggleable = booleanProperty(element, 'toggleable', false);
     return (
-        <Panel
-            data-scene-id={element.id}
-            header={stringProperty(element, 'header')}
-            toggleable={booleanProperty(element, 'toggleable', false)}
-            collapsed={booleanProperty(element, 'collapsed', false)}>
-            {slots.content}
-        </Panel>
+        <Panel.Root data-scene-id={element.id} toggleable={toggleable} defaultOpen={!booleanProperty(element, 'collapsed', false)}>
+            <Panel.Header>
+                <Panel.Title>{stringProperty(element, 'header')}</Panel.Title>
+                {toggleable && (
+                    <Panel.Trigger>
+                        <Panel.Indicator match='open'>
+                            <i className='pi pi-chevron-up' />
+                        </Panel.Indicator>
+                        <Panel.Indicator match='closed'>
+                            <i className='pi pi-chevron-down' />
+                        </Panel.Indicator>
+                    </Panel.Trigger>
+                )}
+            </Panel.Header>
+            <Panel.Content>{slots.content}</Panel.Content>
+        </Panel.Root>
     );
 }

package/panel/PrimeScrollPanel.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 { ScrollPanel } from 'primereact/scrollpanel';
+import { ScrollArea } from 'primereact/scrollarea';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { numberProperty } from '../properties';
 
 /**
  * The `PrimeReact:scrollPanel` component - a bounded region with themed scrollbars.
  *
- * A height is always applied: ScrollPanel with no bound grows to fit its content and never scrolls,
+ * A height is always applied: a scroll area with no bound grows to fit its content and never scrolls,
  * which looks like the component doing nothing at all.
  *
- * In PrimeReact 11 this component is renamed `ScrollArea`.
+ * PrimeReact 11 renamed `ScrollPanel` to `ScrollArea` and split it into parts. The viewport, the content
+ * wrapper and the scrollbar are all rendered here rather than by the component, because v11 renders no
+ * part it was not given - a `ScrollArea.Root` on its own clips nothing and shows no bar. Only the
+ * vertical scrollbar is composed in, matching the fixed-height-and-full-width shape this adapter imposes;
+ * the part hides itself when the content happens to fit, so it costs nothing when it is not needed. The
+ * abstract Scene name stays `scrollPanel` so existing screens keep resolving.
  */
 export function PrimeScrollPanel({ element, slots }: RegisteredComponentProps) {
     return (
-        <ScrollPanel
-            data-scene-id={element.id}
-            style={{ height: `${numberProperty(element, 'height', 200)}px`, width: '100%' }}>
-            {slots.content}
-        </ScrollPanel>
+        <ScrollArea.Root data-scene-id={element.id} style={{ height: `${numberProperty(element, 'height', 200)}px`, width: '100%' }}>
+            <ScrollArea.Viewport>
+                <ScrollArea.Content>{slots.content}</ScrollArea.Content>
+            </ScrollArea.Viewport>
+            <ScrollArea.Scrollbar orientation='vertical'>
+                <ScrollArea.Handle />
+            </ScrollArea.Scrollbar>
+        </ScrollArea.Root>
     );
 }

package/panel/PrimeSplitter.tsx

@@ -1,7 +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 { Splitter, SplitterPanel } from 'primereact/splitter';
+import { Fragment } from 'react';
+import { Splitter } from 'primereact/splitter';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { numberProperty, stringProperty } from '../properties';
 
@@ -10,20 +11,36 @@ import { numberProperty, stringProperty } from '../properties';
  *
  * One panel per child in the `content` slot, sized evenly. Splitter needs an explicit height because it
  * lays its panels out absolutely; without one the whole component collapses.
+ *
+ * PrimeReact 11 moved sizing off the individual panel and onto the root: a v10 `SplitterPanel size={50}`
+ * is now one entry in the root's `defaultSizes` array, so the even split is computed once up front rather
+ * than repeated per panel. It also stopped inserting the drag bars for you - `Splitter.Gutter` is a part
+ * the composition supplies between panels, and a splitter rendered without them is simply not resizable.
+ * `defaultSizes` is used rather than `sizes` so the component owns its sizes after the first drag; the
+ * controlled form would snap the panels back to the even split on every render.
+ *
+ * The Scene property keeps the name `layout` even though v11 calls the prop `orientation`, because a
+ * screen's property vocabulary is this package's contract with authored content.
  */
 export function PrimeSplitter({ element, slots }: RegisteredComponentProps) {
     const panels = slots.content ?? [];
     const count = Math.max(panels.length, 2);
     return (
-        <Splitter
+        <Splitter.Root
             data-scene-id={element.id}
-            layout={stringProperty(element, 'layout', 'horizontal') as 'horizontal' | 'vertical'}
+            orientation={stringProperty(element, 'layout', 'horizontal') as 'horizontal' | 'vertical'}
+            defaultSizes={Array.from({ length: count }, () => 100 / count)}
             style={{ height: `${numberProperty(element, 'height', 200)}px` }}>
             {Array.from({ length: count }, (_, index) => (
-                <SplitterPanel key={index} size={100 / count} className='flex items-center justify-center'>
-                    {panels[index]}
-                </SplitterPanel>
+                <Fragment key={index}>
+                    {index > 0 && (
+                        <Splitter.Gutter>
+                            <Splitter.Handle />
+                        </Splitter.Gutter>
+                    )}
+                    <Splitter.Panel className='flex items-center justify-center'>{panels[index]}</Splitter.Panel>
+                </Fragment>
             ))}
-        </Splitter>
+        </Splitter.Root>
     );
 }

package/panel/PrimeStepper.tsx

@@ -1,42 +1,79 @@
 // 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 { useState } from 'react';
 import { Button } from 'primereact/button';
 import { Stepper } from 'primereact/stepper';
-import { StepperPanel } from 'primereact/stepperpanel';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { booleanProperty, stringArrayProperty, stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:stepper` component - a wizard whose progress is shown as numbered steps.
  *
- * Stepper advances only when something calls `nextCallback` / `prevCallback` on its ref, so the adapter
- * renders the Back and Next buttons itself. Without them the steps render but nothing can move between
- * them, which is a stepper that does not step.
+ * The adapter renders the Back and Next buttons itself. Without them the steps render but nothing can
+ * move between them, which is a stepper that does not step.
+ *
+ * The reason changed with PrimeReact 11 even though the conclusion did not. In v10 the component owned
+ * the active step and exposed `nextCallback` / `prevCallback` on a ref for someone else to call; v11 is
+ * headless and owns nothing - the active step is `value` on `Stepper.Root`, so the adapter holds it in
+ * state and the buttons set it. That also makes the step headers work: clicking one arrives as
+ * `onValueChange`, which is routed into the same state rather than being handled separately.
+ *
+ * v11 also merged `primereact/stepperpanel` into `primereact/stepper`, splitting each step into a
+ * `Stepper.Step` in the header list and a matching `Stepper.Panel` in the body, joined by value.
+ *
+ * **Dropped:** v10's `orientation` property has no equivalent - v11's headless stepper lays out
+ * horizontally and leaves a vertical arrangement to CSS. The authored value is still forwarded as a
+ * `data-orientation` attribute so a theme can act on it, but nothing in the component reads it.
  */
 export function PrimeStepper({ element, slots }: RegisteredComponentProps) {
-    const stepper = useRef<Stepper>(null);
     const headers = stringArrayProperty(element, 'headers');
     const bodies = slots.content ?? [];
     const count = Math.max(headers.length, bodies.length);
+    const [activeStep, setActiveStep] = useState(0);
+
+    // A screen can shrink its step list between renders, which would leave the active step pointing past
+    // the end and show no panel at all. Clamping keeps the value inside the set of steps that exist.
+    const current = Math.min(activeStep, Math.max(count - 1, 0));
+
     return (
-        <Stepper
-            ref={stepper}
+        <Stepper.Root
             data-scene-id={element.id}
+            data-orientation={stringProperty(element, 'orientation', 'horizontal')}
+            value={String(current)}
             linear={booleanProperty(element, 'linear', false)}
-            orientation={stringProperty(element, 'orientation', 'horizontal') as 'horizontal' | 'vertical'}>
-            {Array.from({ length: count }, (_, index) => (
-                <StepperPanel key={index} header={headers[index] ?? `Step ${index + 1}`}>
-                    <div className='flex flex-col gap-4'>
-                        {bodies[index]}
-                        <div className='flex gap-2'>
-                            {index > 0 && <Button label='Back' severity='secondary' onClick={() => stepper.current?.prevCallback()} />}
-                            {index < count - 1 && <Button label='Next' onClick={() => stepper.current?.nextCallback()} />}
+            onValueChange={(event) => {
+                const selected = Number(event.value);
+                if (!Number.isNaN(selected)) setActiveStep(selected);
+            }}>
+            <Stepper.List>
+                {Array.from({ length: count }, (_, index) => (
+                    <Stepper.Step key={index} value={String(index)}>
+                        <Stepper.Header>
+                            <Stepper.Number>{index + 1}</Stepper.Number>
+                            <Stepper.Title>{headers[index] ?? `Step ${index + 1}`}</Stepper.Title>
+                        </Stepper.Header>
+                        {index < count - 1 && <Stepper.Separator />}
+                    </Stepper.Step>
+                ))}
+            </Stepper.List>
+            <Stepper.Panels>
+                {Array.from({ length: count }, (_, index) => (
+                    <Stepper.Panel key={index} value={String(index)}>
+                        <div className='flex flex-col gap-4'>
+                            {bodies[index]}
+                            <div className='flex gap-2'>
+                                {index > 0 && (
+                                    <Button severity='secondary' onClick={() => setActiveStep(index - 1)}>
+                                        Back
+                                    </Button>
+                                )}
+                                {index < count - 1 && <Button onClick={() => setActiveStep(index + 1)}>Next</Button>}
+                            </div>
                         </div>
-                    </div>
-                </StepperPanel>
-            ))}
-        </Stepper>
+                    </Stepper.Panel>
+                ))}
+            </Stepper.Panels>
+        </Stepper.Root>
     );
 }