@cratis/scene.primereact 1.1.0 → 3.0.0

package/form/TreeSelect.tsx

@@ -0,0 +1,158 @@
+// 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, useState } from 'react';
+import { Popover } from 'primereact/popover';
+import { Tree, type TreeNodeData } from 'primereact/tree';
+import { TreeNode } from '../TreeNode';
+
+/**
+ * What a {@link TreeSelect} needs from its host.
+ *
+ * Deliberately the small subset of PrimeReact 10's `TreeSelect` that a Scene element can actually author.
+ * The component is Cratis-owned (see {@link TreeSelect}), so this is a promise this package has to keep
+ * on its own - every prop added here is one more thing to implement, and a hierarchy picker earns its
+ * keep long before it grows options.
+ */
+export interface TreeSelectProps {
+    /**
+     * The key of the selected node. Controlled, because the only thing worth selecting from a tree is a
+     * node's identity and the host is what knows what to do with it.
+     */
+    value?: string;
+
+    /**
+     * The hierarchy to choose from, in Scene's own {@link TreeNode} shape rather than PrimeReact's -
+     * `TreeNode` is this package's type since v11 removed `primereact/treenode`, and translating it is
+     * this component's job rather than every caller's.
+     */
+    options: TreeNode[];
+
+    /**
+     * What the trigger shows when nothing is selected.
+     */
+    placeholder?: string;
+
+    /**
+     * Whether the trigger refuses to open.
+     */
+    disabled?: boolean;
+
+    /**
+     * Called with the newly selected node's key. Selecting also closes the panel, because a single-select
+     * picker has nothing left to ask once it has an answer.
+     */
+    onChange?: (value: string) => void;
+}
+
+/**
+ * A dropdown whose choices are a hierarchy - Cratis-owned, because PrimeReact 11 removed `TreeSelect`
+ * outright and left neither a replacement component nor a headless hook to build one from.
+ *
+ * It is assembled from the two v11 pieces that did survive and together cover the behavior: `Popover`
+ * provides the trigger, the portal and the outside-click and Escape handling, and `Tree` provides the
+ * node list, the expand/collapse state and keyboard navigation. Nothing here re-implements either - the
+ * component is the seam between them, plus the translation from Scene's {@link TreeNode} to the
+ * `TreeNodeData` the tree wants.
+ *
+ * What it deliberately does not carry over from v10, so that no caller is misled into expecting it:
+ * **checkbox multi-select** - selection is single, `onChange` yields one key, and there is no partial or
+ * "n selected" state to reason about; and **filtering** - v10's `filter` prop searched the node labels
+ * and rebuilt the visible tree around the matches, which is a real amount of behavior (match, keep
+ * ancestors, force-expand, restore on clear) and belongs in the component only once something actually
+ * needs it.
+ */
+export function TreeSelect({ value, options, placeholder, disabled, onChange }: TreeSelectProps) {
+    const [open, setOpen] = useState(false);
+    const nodes = useMemo(() => toTreeNodeData(options), [options]);
+    const label = findLabel(nodes, value);
+
+    return (
+        <Popover.Root open={open} onOpenChange={(event) => setOpen(event.value === true)}>
+            <Popover.Trigger disabled={disabled}>
+                <span>{label ?? placeholder}</span>
+                <i className='pi pi-chevron-down' />
+            </Popover.Trigger>
+            <Popover.Portal>
+                <Popover.Positioner>
+                    <Popover.Popup>
+                        <Popover.Content>
+                            <Tree.Root
+                                value={nodes}
+                                selectionMode='single'
+                                selectionKeys={value === undefined ? {} : { [value]: true }}
+                                onSelectionChange={(event) => {
+                                    const selected = Object.keys(event.value).find((key) => event.value[key] === true);
+                                    if (selected === undefined) return;
+                                    onChange?.(selected);
+                                    setOpen(false);
+                                }}>
+                                <Tree.Nodes>
+                                    {(row) => (
+                                        <Tree.Node uKey={row.node.key}>
+                                            <Tree.Content>
+                                                <Tree.Toggle>
+                                                    <Tree.ToggleIndicator>
+                                                        <i className={row.expanded ? 'pi pi-chevron-down' : 'pi pi-chevron-right'} />
+                                                    </Tree.ToggleIndicator>
+                                                </Tree.Toggle>
+                                                <Tree.Label>{row.node.label}</Tree.Label>
+                                            </Tree.Content>
+                                        </Tree.Node>
+                                    )}
+                                </Tree.Nodes>
+                            </Tree.Root>
+                        </Popover.Content>
+                    </Popover.Popup>
+                </Popover.Positioner>
+            </Popover.Portal>
+        </Popover.Root>
+    );
+}
+
+/**
+ * Converts Scene's {@link TreeNode} model into the one PrimeReact 11's `Tree` reads.
+ *
+ * The two shapes agree on everything that matters except one thing: `key` is optional on a Scene node and
+ * required on a PrimeReact one, because the tree keys expansion and selection off it. A missing key is
+ * synthesized from the node's position, which is unique and stable across re-renders - the same rule
+ * `toTreeNodes` applies, repeated here so this component is correct even when handed nodes that did not
+ * come through it.
+ *
+ * @param nodes The Scene nodes to convert.
+ * @param parentKey The key of the node these belong to, used to build unique child keys.
+ * @returns The converted nodes, in order.
+ */
+function toTreeNodeData(nodes: TreeNode[], parentKey = ''): TreeNodeData[] {
+    return nodes.map((node, index) => {
+        const key = node.key ?? (parentKey === '' ? `${index}` : `${parentKey}-${index}`);
+        return {
+            key,
+            label: node.label,
+            icon: node.icon,
+            children: node.children === undefined ? undefined : toTreeNodeData(node.children, key),
+        };
+    });
+}
+
+/**
+ * Finds the label to show on the trigger for a selected key.
+ *
+ * The selection is a key rather than a node because that is all the tree reports, so the label has to be
+ * looked back up - and it has to search the whole hierarchy, since the selected node is very rarely a
+ * root one.
+ *
+ * @param nodes The converted nodes to search.
+ * @param key The selected key, or `undefined` when nothing is selected.
+ * @returns The node's label, or `undefined` when nothing is selected or the key matches no node.
+ */
+function findLabel(nodes: TreeNodeData[], key: string | undefined): ReactNode {
+    if (key === undefined) return undefined;
+    for (const node of nodes) {
+        if (node.key === key) return node.label;
+        const found = node.children === undefined ? undefined : findLabel(node.children, key);
+        if (found !== undefined) return found;
+    }
+
+    return undefined;
+}

package/form/index.ts

@@ -5,7 +5,6 @@ export * from './PrimeInputText';
 export * from './PrimeInputTextarea';
 export * from './PrimeInputNumber';
 export * from './PrimePassword';
-export * from './PrimeInputMask';
 export * from './PrimeFloatLabel';
 export * from './PrimeIconField';
 export * from './PrimeDropdown';
@@ -22,5 +21,5 @@ export * from './PrimeCalendar';
 export * from './PrimeColorPicker';
 export * from './PrimeChips';
 export * from './PrimeAutoComplete';
+export * from './TreeSelect';
 export * from './PrimeTreeSelect';
-export * from './PrimeCascadeSelect';

package/index.ts

@@ -2,6 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './SelectOption';
+export * from './MenuItem';
+export * from './PrimeSeverity';
+export * from './TreeNode';
 export * from './properties';
 export * from './menuItems';
 export * from './treeNodes';

package/media/Image.tsx

@@ -0,0 +1,104 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { HTMLAttributes, useState } from 'react';
+import { Dialog } from 'primereact/dialog';
+
+/**
+ * Configuration for {@link Image}.
+ */
+export interface ImageProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /**
+     * Where the picture comes from. Optional because a screen under construction routinely names an image
+     * before it has one, and that is not a failure worth taking a page down for.
+     */
+    src?: string;
+
+    /**
+     * The alternative text. Defaults to empty, which marks the image decorative - an image with no
+     * authored alternative is decorative until someone says otherwise, and inventing text from the file
+     * name would put a URL fragment in front of a screen reader.
+     */
+    alt?: string;
+
+    /**
+     * The rendered width, as any CSS length or a bare pixel count.
+     */
+    width?: string;
+
+    /**
+     * The rendered height, as any CSS length or a bare pixel count.
+     */
+    height?: string;
+
+    /**
+     * Whether clicking the image opens it full size in an overlay. Off by default: a picture that grows
+     * when clicked is a promise, and one made on every thumbnail in a layout is usually a mistake.
+     */
+    preview?: boolean;
+}
+
+/**
+ * A picture, optionally openable full size in an overlay.
+ *
+ * Cratis owns this component. PrimeReact 10 had `Image`; PrimeReact 11 removed it with no replacement and
+ * no headless hook, while `image` remains a name this package's manifest publishes. The plain case is a
+ * plain `img` - there was never much to a themed image - and the preview reuses PrimeReact 11's `Dialog`,
+ * which survived, so the overlay keeps the application's focus trapping, escape handling and stacking
+ * rather than growing a second, worse implementation of all three here.
+ *
+ * With no `src`, an empty element is rendered rather than a broken `img`. That keeps whatever identifying
+ * attributes the caller passed in the document, which is what lets a design-time tool still find and
+ * select the element it has not finished authoring.
+ *
+ * What it deliberately does not carry over from v10: the preview toolbar - zoom in and out, rotate, flip,
+ * download - which is a viewer rather than an image and is exactly what the `galleria` component is for;
+ * `indicatorIcon` and the hover indicator overlay; the `imageStyle` / `previewStyle` prop pairs, since
+ * `className` and `style` already reach the element; and `zoomInDisabled` / `zoomOutDisabled`, which only
+ * ever meant anything to that toolbar.
+ */
+export function Image({ src, alt = '', width, height, preview = false, className, ...rest }: ImageProps) {
+    const [open, setOpen] = useState(false);
+
+    if (src === undefined || src === '') return <span {...rest} className={className} />;
+
+    const image = <img src={src} alt={alt} width={width} height={height} className='max-w-full' />;
+
+    if (!preview) {
+        return (
+            <span {...rest} className={className}>
+                {image}
+            </span>
+        );
+    }
+
+    return (
+        <span {...rest} className={className}>
+            <button
+                type='button'
+                className='cursor-zoom-in border-0 bg-transparent p-0'
+                aria-label={alt === '' ? 'Open image preview' : `Open preview of ${alt}`}
+                onClick={() => setOpen(true)}>
+                {image}
+            </button>
+            <Dialog.Root open={open} onOpenChange={(event) => setOpen(event.value === true)} modal dismissable>
+                <Dialog.Portal>
+                    <Dialog.Backdrop />
+                    <Dialog.Positioner>
+                        <Dialog.Popup>
+                            <Dialog.Header>
+                                <Dialog.Title>{alt === '' ? 'Preview' : alt}</Dialog.Title>
+                                <Dialog.Close aria-label='Close preview'>
+                                    <i className='pi pi-times' aria-hidden='true' />
+                                </Dialog.Close>
+                            </Dialog.Header>
+                            <Dialog.Content>
+                                <img src={src} alt={alt} className='max-h-[80vh] max-w-[80vw]' />
+                            </Dialog.Content>
+                        </Dialog.Popup>
+                    </Dialog.Positioner>
+                </Dialog.Portal>
+            </Dialog.Root>
+        </span>
+    );
+}

package/media/MediaGallery.stories.tsx

@@ -12,7 +12,7 @@ const meta = {
     tags: ['autodocs'],
     parameters: {
         layout: 'padded',
-        docs: { description: { component: 'The media family. `galleria` and `carousel` both ship without a default template, so each adapter supplies one built from the fields the element names.' } },
+        docs: { description: { component: 'The media family. `galleria` and `carousel` are compositions in PrimeReact 11 rather than components taking render-prop templates, so each adapter writes out the item list itself from the fields the element names - `galleria` from `{ src, thumbnail, alt }`, `carousel` from `titleField` and `descriptionField`. `image` is a Cratis-owned rebuild: PrimeReact 11 removed its `Image` with no replacement, and the preview overlay here is a PrimeReact `Dialog`.' } },
     },
 } satisfies Meta<typeof SceneElementView>;
 

package/media/PrimeCarousel.tsx

@@ -8,25 +8,46 @@ import { booleanProperty, numberProperty, recordArrayProperty, stringProperty }
 /**
  * The `PrimeReact:carousel` component - a row of items paged through horizontally.
  *
- * Supplies an item template from the `titleField` and `descriptionField` properties, for the same reason
- * `dataView` does: without one, every item renders empty.
+ * The item body is built from the `titleField` and `descriptionField` properties, for the same reason
+ * `dataView` does it: the element carries records, not markup, and something has to decide which two
+ * fields a reader sees. PrimeReact 11 takes that as children rather than as an `itemTemplate` callback,
+ * which is why the mapping is written out here instead of passed in.
+ *
+ * v10's `numScroll` has no v11 counterpart and is not read: the new carousel scrolls by a page, and a page
+ * is `numVisible` items. Honoring a `numScroll` that differs from it would mean re-implementing paging
+ * against a component that has its own.
+ *
+ * Navigation and page indicators appear only when there is more than one page's worth of items. A control
+ * that cannot do anything is worse than an absent one - it invites a click and answers with nothing.
  */
 export function PrimeCarousel({ element }: RegisteredComponentProps) {
+    const items = recordArrayProperty(element, 'items');
     const titleField = stringProperty(element, 'titleField', 'title');
     const descriptionField = stringProperty(element, 'descriptionField', 'description');
+    const numVisible = numberProperty(element, 'numVisible', 3);
     return (
-        <Carousel
-            data-scene-id={element.id}
-            value={recordArrayProperty(element, 'items')}
-            numVisible={numberProperty(element, 'numVisible', 3)}
-            numScroll={numberProperty(element, 'numScroll', 1)}
-            circular={booleanProperty(element, 'circular', false)}
-            itemTemplate={(item: Record<string, unknown>) => (
-                <div className='m-2 flex flex-col gap-1 border p-3'>
-                    <span className='font-semibold'>{String(item[titleField] ?? '')}</span>
-                    <span className='text-sm opacity-75'>{String(item[descriptionField] ?? '')}</span>
-                </div>
+        <Carousel.Root data-scene-id={element.id} slidesPerPage={numVisible} loop={booleanProperty(element, 'circular', false)}>
+            <Carousel.Content>
+                {items.map((item, index) => (
+                    <Carousel.Item key={index}>
+                        <div className='m-2 flex flex-col gap-1 border p-3'>
+                            <span className='font-semibold'>{String(item[titleField] ?? '')}</span>
+                            <span className='text-sm opacity-75'>{String(item[descriptionField] ?? '')}</span>
+                        </div>
+                    </Carousel.Item>
+                ))}
+            </Carousel.Content>
+            {items.length > numVisible && (
+                <>
+                    <Carousel.Prev aria-label='Previous items'>
+                        <i className='pi pi-chevron-left' aria-hidden='true' />
+                    </Carousel.Prev>
+                    <Carousel.Next aria-label='Next items'>
+                        <i className='pi pi-chevron-right' aria-hidden='true' />
+                    </Carousel.Next>
+                    <Carousel.Indicators />
+                </>
             )}
-        />
+        </Carousel.Root>
     );
 }

package/media/PrimeGalleria.tsx

@@ -1,35 +1,60 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Galleria } from 'primereact/galleria';
+import { Gallery } from 'primereact/gallery';
 import { RegisteredComponentProps } from '@cratis/scene.react';
 import { booleanProperty, numberProperty, recordArrayProperty } from '../properties';
 
 /**
  * The `PrimeReact:galleria` component - a gallery with thumbnails and a large view.
  *
- * Galleria ships no default templates, so the adapter supplies both; each item is read as
- * `{ src, thumbnail, alt }` with the thumbnail falling back to the full image, which is the common case
- * for a small gallery that has no separately generated thumbnails.
+ * PrimeReact 11 renamed the module to `gallery` and turned it into a composition, which removes the
+ * awkwardness the v10 adapter had to work around: there are no `item` and `thumbnail` render-prop
+ * templates to supply, only two lists the adapter writes out itself. Each entry is still read as
+ * `{ src, thumbnail, alt }`, with the thumbnail falling back to the full image - the common case for a
+ * small gallery that has no separately generated thumbnails.
  *
- * In PrimeReact 11 this component is renamed `Gallery`.
+ * The abstract name stays `galleria`. Renaming it would be renaming Scene's vocabulary because PrimeReact
+ * renamed a module, and every screen that says `galleria` today would have to be edited to say the same
+ * thing.
+ *
+ * Navigation and the thumbnail rail are rendered only when there is something to navigate: a single image
+ * needs no previous and next, and no items at all leave a bare, empty gallery rather than a frame of
+ * chrome around nothing.
  */
 export function PrimeGalleria({ element }: RegisteredComponentProps) {
     const items = recordArrayProperty(element, 'items');
+    const showThumbnails = booleanProperty(element, 'showThumbnails', true);
     return (
-        <Galleria
-            data-scene-id={element.id}
-            value={items}
-            numVisible={numberProperty(element, 'numVisible', 5)}
-            circular={booleanProperty(element, 'circular', true)}
-            showThumbnails={booleanProperty(element, 'showThumbnails', true)}
-            style={{ maxWidth: `${numberProperty(element, 'maxWidth', 480)}px` }}
-            item={(item: Record<string, unknown>) => (
-                <img src={String(item.src ?? '')} alt={String(item.alt ?? '')} className='block w-full' />
-            )}
-            thumbnail={(item: Record<string, unknown>) => (
-                <img src={String(item.thumbnail ?? item.src ?? '')} alt={String(item.alt ?? '')} className='block h-12' />
+        <Gallery.Root data-scene-id={element.id} style={{ maxWidth: `${numberProperty(element, 'maxWidth', 480)}px` }}>
+            <Gallery.Content>
+                {items.map((item, index) => (
+                    <Gallery.Item key={index}>
+                        <img src={String(item.src ?? '')} alt={String(item.alt ?? '')} className='block w-full' />
+                    </Gallery.Item>
+                ))}
+                {items.length > 1 && (
+                    <>
+                        <Gallery.Prev aria-label='Previous image'>
+                            <i className='pi pi-chevron-left' aria-hidden='true' />
+                        </Gallery.Prev>
+                        <Gallery.Next aria-label='Next image'>
+                            <i className='pi pi-chevron-right' aria-hidden='true' />
+                        </Gallery.Next>
+                    </>
+                )}
+            </Gallery.Content>
+            {showThumbnails && items.length > 1 && (
+                <Gallery.Thumbnail slidesPerPage={numberProperty(element, 'numVisible', 5)} loop={booleanProperty(element, 'circular', true)}>
+                    <Gallery.ThumbnailContent>
+                        {items.map((item, index) => (
+                            <Gallery.ThumbnailItem key={index} index={index}>
+                                <img src={String(item.thumbnail ?? item.src ?? '')} alt={String(item.alt ?? '')} className='block h-12' />
+                            </Gallery.ThumbnailItem>
+                        ))}
+                    </Gallery.ThumbnailContent>
+                </Gallery.Thumbnail>
             )}
-        />
+        </Gallery.Root>
     );
 }

package/media/PrimeImage.tsx

@@ -1,13 +1,17 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Image } from 'primereact/image';
 import { RegisteredComponentProps } from '@cratis/scene.react';
+import { Image } from './Image';
 import { booleanProperty, stringProperty } from '../properties';
 
 /**
  * The `PrimeReact:image` component - an image with an optional full-screen preview.
  *
+ * PrimeReact 11 removed `Image` with no replacement and no headless hook, so the adapter renders Cratis's
+ * own {@link Image}. The element's authored contract is unchanged, which is the point: which library
+ * happens to draw an `img` is not something a screen should have to be rewritten over.
+ *
  * `alt` defaults to an empty string rather than to the file name: an image with no authored alternative
  * text is decorative until someone says otherwise, and inventing one would put a URL fragment in front of
  * a screen reader.
@@ -16,7 +20,7 @@ export function PrimeImage({ element }: RegisteredComponentProps) {
     return (
         <Image
             data-scene-id={element.id}
-            src={stringProperty(element, 'src', '')}
+            src={stringProperty(element, 'src')}
             alt={stringProperty(element, 'alt', '')}
             width={stringProperty(element, 'width')}
             height={stringProperty(element, 'height')}

package/media/index.ts

@@ -4,3 +4,4 @@
 export * from './PrimeImage';
 export * from './PrimeGalleria';
 export * from './PrimeCarousel';
+export * from './Image';

package/menu/Dock.tsx

@@ -0,0 +1,109 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CSSProperties, HTMLAttributes } from 'react';
+import { MenuItem } from '../MenuItem';
+import { DockPosition } from './DockPosition';
+
+const dockStyle: CSSProperties = {
+    position: 'absolute',
+    background: 'var(--scene-surface-overlay)',
+    border: '1px solid var(--scene-surface-border)',
+    borderRadius: 'var(--scene-content-border-radius)',
+    color: 'var(--scene-text-color)',
+};
+
+const entryStyle: CSSProperties = {
+    background: 'transparent',
+    border: 'none',
+    color: 'inherit',
+    cursor: 'pointer',
+    font: 'inherit',
+    fontSize: '1.5rem',
+    lineHeight: 1,
+    textDecoration: 'none',
+};
+
+/**
+ * Where the dock sits within its container, for one edge.
+ *
+ * The offset lives here rather than in four CSS classes because this package ships no component
+ * stylesheets, and because the two axes are genuinely coupled: an edge decides both which side is pinned
+ * and which axis is centered, so writing them together is what keeps them consistent.
+ */
+function anchor(position: DockPosition): CSSProperties {
+    switch (position) {
+        case DockPosition.Top:
+            return { top: 0, left: '50%', transform: 'translateX(-50%)' };
+        case DockPosition.Left:
+            return { left: 0, top: '50%', transform: 'translateY(-50%)' };
+        case DockPosition.Right:
+            return { right: 0, top: '50%', transform: 'translateY(-50%)' };
+        default:
+            return { bottom: 0, left: '50%', transform: 'translateX(-50%)' };
+    }
+}
+
+/**
+ * The configuration {@link Dock} takes.
+ */
+export interface DockProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The entries to show. Each is shown as its icon alone, with its label as the accessible name.
+     */
+    items?: MenuItem[];
+
+    /**
+     * The edge of the containing box to anchor against.
+     */
+    position?: DockPosition;
+}
+
+/**
+ * A small strip of icons anchored to one edge of its container. Cratis-owned.
+ *
+ * This exists because PrimeReact 11 removed `primereact/dock` outright, with no successor and no headless
+ * hook. It positions itself absolutely, so it expects a positioned container to sit in - dropped straight
+ * into a page it would pin itself to the page, which is why the Scene adapter wraps it in a sized relative
+ * box.
+ *
+ * Entries are icon-only, and that is precisely why each one carries its label as `aria-label` and as a
+ * `title`: a control whose only content is a decorative glyph has no accessible name at all otherwise, and
+ * a dock is exactly the shape of component where that gets forgotten. An entry with no icon still renders,
+ * as a neutral placeholder glyph, so a half-authored screen shows a gap rather than an invisible control.
+ *
+ * What it deliberately does not carry over from the v10 `Dock`: there is no magnification of the icon under
+ * the pointer, which was the component's signature effect and is pure decoration; there are no tooltips
+ * beyond the browser's own `title`; and item templates are not supported.
+ */
+export function Dock({ items = [], position = DockPosition.Bottom, ...rest }: DockProps) {
+    const vertical = position === DockPosition.Left || position === DockPosition.Right;
+
+    return (
+        <div
+            {...rest}
+            role='toolbar'
+            aria-orientation={vertical ? 'vertical' : 'horizontal'}
+            className={vertical ? 'flex flex-col items-center gap-2 p-3' : 'flex items-center gap-2 p-3'}
+            style={{ ...dockStyle, ...anchor(position) }}>
+            {items.map((item, index) =>
+                item.url === undefined ? (
+                    <button
+                        key={index}
+                        type='button'
+                        style={entryStyle}
+                        disabled={item.disabled}
+                        title={item.label}
+                        aria-label={item.label}
+                        onClick={() => item.command?.()}>
+                        <i className={item.icon ?? 'pi pi-circle'} aria-hidden='true' />
+                    </button>
+                ) : (
+                    <a key={index} href={item.url} style={entryStyle} title={item.label} aria-label={item.label}>
+                        <i className={item.icon ?? 'pi pi-circle'} aria-hidden='true' />
+                    </a>
+                )
+            )}
+        </div>
+    );
+}

package/menu/DockPosition.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The edge a {@link Dock} is anchored to.
+ *
+ * This is an enum rather than a union of string literals so the four edges are discoverable from the type
+ * itself and a `switch` over them stays exhaustive: adding a fifth edge becomes a compile error at every
+ * place that maps an edge onto a position, instead of a silently missing case. The values are the same
+ * lowercase words a screen authors, so an authored `position` maps straight onto a member.
+ */
+export enum DockPosition {
+    /**
+     * Anchored to the top edge, laid out across.
+     */
+    Top = 'top',
+
+    /**
+     * Anchored to the bottom edge, laid out across. The macOS-style default.
+     */
+    Bottom = 'bottom',
+
+    /**
+     * Anchored to the left edge, laid out down.
+     */
+    Left = 'left',
+
+    /**
+     * Anchored to the right edge, laid out down.
+     */
+    Right = 'right',
+}