panelui-web 0.5.0 → 0.6.0

package/dist/components/avatar/index.d.ts

@@ -0,0 +1,66 @@
+import { type ComponentProps, type ReactNode } from 'react';
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarShape = 'circle' | 'square';
+export type AvatarColor = 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5' | 'muted';
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
+export interface AvatarProps extends Omit<ComponentProps<'span'>, 'color'> {
+    /** The picture. Without it, or until it has loaded, the initials show. */
+    src?: string;
+    /** Who it is. Gives the initials, the colour and what a screen reader says. */
+    name?: string;
+    /** Read out in place of `name`, when that is not the right thing to say. */
+    alt?: string;
+    /** Default `md`. In a group, the group's size. */
+    size?: AvatarSize;
+    /** `circle` for people, `square` for teams, projects and things. Default `circle`. */
+    shape?: AvatarShape;
+    /** The tint behind the initials. Picked from `name` when left out. */
+    color?: AvatarColor;
+    /** In place of the initials, such as an icon for a team or a bot. */
+    fallback?: ReactNode;
+    /** An `Avatar.Badge`. */
+    children?: ReactNode;
+}
+/** A picture of someone, or their initials in a colour of their own. */
+declare function AvatarRoot({ src, name, alt, size, shape, color, fallback, className, style, children, ...props }: AvatarProps): import("react").JSX.Element;
+declare namespace AvatarRoot {
+    var displayName: string;
+}
+export interface AvatarBadgeProps extends Omit<ComponentProps<'span'>, 'color'> {
+    /** A presence dot in the colour that says it. Leave out for a badge of your own. */
+    status?: AvatarStatus;
+    /** For a badge with an icon in it: the fill behind the icon. */
+    color?: AvatarColor;
+    /** What a screen reader says after the name. Defaults to the status. */
+    label?: string;
+    /** An icon, such as a check for a verified account. */
+    children?: ReactNode;
+}
+/**
+ * A dot or a small icon on the avatar's lower trailing edge. The avatar is
+ * cut away round it, so it reads on any background.
+ */
+declare function AvatarBadge({ status, color, label: _label, className, ...props }: AvatarBadgeProps): import("react").JSX.Element;
+declare namespace AvatarBadge {
+    var displayName: string;
+}
+export interface AvatarGroupProps extends ComponentProps<'div'> {
+    /** How many to show. The rest are counted in a last circle that lists them. */
+    max?: number;
+    /** The size of every avatar in it. Default `md`. */
+    size?: AvatarSize;
+    /** The shape of every avatar in it. Default `circle`. */
+    shape?: AvatarShape;
+    /** What a screen reader calls the group, such as "Members". */
+    label?: string;
+}
+/** A row of overlapping avatars, that opens up when it is hovered or focused. */
+declare function AvatarGroup({ max, size, shape, label, className, style, children, ...props }: AvatarGroupProps): import("react").JSX.Element;
+declare namespace AvatarGroup {
+    var displayName: string;
+}
+export declare const Avatar: typeof AvatarRoot & {
+    Badge: typeof AvatarBadge;
+    Group: typeof AvatarGroup;
+};
+export { AvatarBadge, AvatarGroup };

package/dist/components/avatar/index.js

@@ -0,0 +1,251 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Avatar — a person or a team as a picture, with their initials when there
+ * is no picture to show.
+ *
+ * ```tsx
+ * <Avatar src="/noor.jpg" name="Noor Haddad" />
+ *
+ * <Avatar name="Tomás Ferreira" size="lg">
+ *   <Avatar.Badge status="online" />
+ * </Avatar>
+ *
+ * <Avatar.Group max={4}>
+ *   {people.map((person) => <Avatar key={person.id} src={person.photo} name={person.name} />)}
+ * </Avatar.Group>
+ * ```
+ *
+ * ## Initials in a colour of their own
+ *
+ * Without a picture, or while one loads, the avatar shows the initials of
+ * `name` on a tint of one of the theme's chart colours. The colour is picked
+ * from the name, so the same person has the same colour on every screen, and
+ * a row of people without pictures can still be told apart at a glance.
+ *
+ * ## Cut out, not ringed
+ *
+ * A badge, and the avatar overlapping the next one in a group, are not drawn
+ * with a ring in the page's background colour. The avatar underneath is cut
+ * away with a mask instead, so the gap round them is a real gap: it shows
+ * whatever the avatar sits on, a card, a tinted row, a photograph, and needs
+ * no colour to match it.
+ *
+ * ## A group opens up
+ *
+ * Avatars in a group overlap. Hovered or focused, they move apart, and the cut
+ * in each moves with the one beside it. Past `max`, the rest are counted in a
+ * last circle that opens a list of who they are.
+ */
+import { Avatar as BaseAvatar } from '@base-ui/react/avatar';
+import { Popover } from '@base-ui/react/popover';
+import { Children, createContext, isValidElement, useContext, useMemo, } from 'react';
+import { tv } from 'tailwind-variants';
+const SIZE = {
+    xs: '1.5rem',
+    sm: '2rem',
+    md: '2.5rem',
+    lg: '3.5rem',
+    xl: '4.5rem',
+};
+const COLORS = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5'];
+const avatarVariants = tv({
+    slots: {
+        root: 'relative inline-flex size-(--avatar-size) shrink-0 align-middle',
+        /*
+         * The face is what gets cut. Its hairline is inside it, so the cut takes
+         * the hairline with it and no stray arc of it is left in the gap.
+         */
+        face: [
+            'relative flex size-full overflow-hidden bg-muted select-none',
+            "after:pointer-events-none after:absolute after:inset-0 after:rounded-[inherit] after:ring-1 after:ring-inset after:ring-foreground/10 after:content-['']",
+            '[mask-repeat:no-repeat] [mask-composite:intersect]',
+        ],
+        image: 'size-full object-cover',
+        fallback: [
+            'flex size-full items-center justify-center font-medium leading-none tracking-tight',
+            'text-[calc(var(--avatar-size)*0.38)]',
+            'bg-[color-mix(in_oklab,var(--avatar-color)_22%,var(--card))] text-[color-mix(in_oklab,var(--avatar-color)_70%,var(--foreground))]',
+            '[&_svg]:size-[55%] [&_svg]:opacity-70',
+        ],
+        badge: [
+            'absolute flex size-(--badge-size) items-center justify-center rounded-full',
+            'left-[calc(var(--badge-center)-var(--badge-size)/2)] top-[calc(var(--badge-center)-var(--badge-size)/2)]',
+            'text-[calc(var(--badge-size)*0.6)] [&_svg]:size-[70%]',
+        ],
+        group: [
+            'group/avatars inline-flex items-center [--avatar-overlap:0.22]',
+            // Hovered or focused, the group opens up so each face can be seen whole.
+            'hover:[--avatar-overlap:0.08] has-focus-visible:[--avatar-overlap:0.08] motion-reduce:hover:[--avatar-overlap:0.22]',
+        ],
+        item: [
+            'not-first:ms-[calc(var(--avatar-size)*var(--avatar-overlap)*-1)]',
+            'transition-[margin] duration-300 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none',
+            // The face's cut follows the margin, in step with it.
+            '*:data-[slot=avatar-face]:transition-[mask-position] *:data-[slot=avatar-face]:duration-300 *:data-[slot=avatar-face]:ease-[cubic-bezier(0.2,0,0,1)]',
+        ],
+        count: [
+            'flex size-full cursor-pointer items-center justify-center bg-muted font-medium tabular-nums text-muted-foreground outline-none',
+            'text-[calc(var(--avatar-size)*0.34)] transition-colors hover:bg-accent hover:text-foreground',
+            'focus-visible:ring-2 focus-visible:ring-ring data-popup-open:bg-accent data-popup-open:text-foreground',
+        ],
+        popup: [
+            'z-50 min-w-52 origin-(--transform-origin) rounded-xl border bg-popover p-1 text-popover-foreground shadow-lg outline-none',
+            'max-h-(--available-height) overflow-y-auto',
+            'transition-[opacity,scale] duration-150 ease-out data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0',
+            'motion-reduce:transition-none',
+        ],
+        row: 'flex items-center gap-2.5 rounded-lg px-2 py-1.5 text-sm',
+    },
+    variants: {
+        shape: {
+            circle: { face: 'rounded-full', root: '[--badge-center:85.4%]' },
+            // The badge sits further in on a square, whose corner is further out.
+            square: { face: 'rounded-[28%]', root: '[--badge-center:calc(100%-var(--badge-size)*0.3)]' },
+        },
+        status: {
+            online: { badge: 'bg-success' },
+            away: { badge: 'bg-warning' },
+            busy: { badge: 'bg-destructive' },
+            // Hollow: there, but not reachable.
+            offline: { badge: 'border-[max(1.5px,calc(var(--badge-size)*0.2))] border-muted-foreground/70' },
+        },
+        color: {
+            'chart-1': { root: '[--avatar-color:var(--chart-1)]', badge: 'bg-chart-1 text-background' },
+            'chart-2': { root: '[--avatar-color:var(--chart-2)]', badge: 'bg-chart-2 text-background' },
+            'chart-3': { root: '[--avatar-color:var(--chart-3)]', badge: 'bg-chart-3 text-background' },
+            'chart-4': { root: '[--avatar-color:var(--chart-4)]', badge: 'bg-chart-4 text-background' },
+            'chart-5': { root: '[--avatar-color:var(--chart-5)]', badge: 'bg-chart-5 text-background' },
+            muted: { root: '[--avatar-color:var(--muted-foreground)]', badge: 'bg-foreground text-background' },
+        },
+    },
+    defaultVariants: { shape: 'circle' },
+});
+/** The same name always lands on the same colour. */
+function colorOf(name) {
+    if (!name)
+        return 'muted';
+    let hash = 0;
+    for (const char of name)
+        hash = (hash * 31 + char.codePointAt(0)) | 0;
+    return COLORS[Math.abs(hash) % COLORS.length];
+}
+/** First letter of the first and last words: "Noor al-Haddad" is "NA". */
+function initialsOf(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    const first = [...words[0]][0] ?? '';
+    const last = words.length > 1 ? ([...words[words.length - 1]][0] ?? '') : '';
+    return (first + last).toUpperCase();
+}
+const STATUS_LABEL = {
+    online: 'online',
+    away: 'away',
+    busy: 'busy',
+    offline: 'offline',
+};
+/* -------------------------------------------------------------------------- */
+/* Masks                                                                      */
+/* -------------------------------------------------------------------------- */
+/*
+ * Every face has two mask layers, intersected: one for the badge, one for the
+ * avatar overlapping it in a group. A layer with nothing to cut is solid.
+ *
+ * Each cut is a gradient drawn in a box bigger than the face and placed with
+ * `mask-position`, rather than a gradient placed by its own coordinates. A
+ * position animates; a gradient's coordinates do not. That is what lets the
+ * cut slide along with the next avatar as the group opens.
+ */
+const SOLID = 'linear-gradient(#000,#000)';
+const GAP = 'max(1.5px, calc(var(--avatar-size) * 0.05))';
+/** A hole round the badge. */
+const BADGE_CUT = `radial-gradient(circle at var(--badge-center) var(--badge-center), transparent calc(var(--badge-size) / 2 + ${GAP}), #000 calc(var(--badge-size) / 2 + ${GAP} + 0.5px))`;
+/**
+ * A hole where the next avatar lies over this one. The box is three faces
+ * wide with the hole at its centre, then shifted so the centre lands on the
+ * next avatar's centre: `size × (1 − overlap)` along.
+ */
+const CIRCLE_CUT = `radial-gradient(circle, transparent calc(var(--avatar-size) / 2 + ${GAP}), #000 calc(var(--avatar-size) / 2 + ${GAP} + 0.5px))`;
+const CIRCLE_CUT_SIZE = 'calc(var(--avatar-size) * 3) calc(var(--avatar-size) * 3)';
+const CIRCLE_CUT_AT = 'calc(var(--avatar-size) * var(--avatar-overlap) * -1) calc(var(--avatar-size) * -1)';
+/**
+ * A square's hole is the next square's own shape, a rounded square a little
+ * larger than it, drawn in the same three-face box so it moves the same way.
+ * A gradient cannot draw a rounded square, so this one is an SVG: 100 units
+ * to a face, with the corner at the face's 28% and the gap at 5%.
+ */
+const SQUARE_CUT = `url("data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 300" preserveAspectRatio="none"><path fill-rule="evenodd" d="M0 0H300V300H0Z M128 95H172A33 33 0 0 1 205 128V172A33 33 0 0 1 172 205H128A33 33 0 0 1 95 172V128A33 33 0 0 1 128 95Z"/></svg>')}")`;
+function maskStyle(shape, badge, overlapped) {
+    if (!badge && !overlapped)
+        return undefined;
+    const layers = [
+        badge ? [BADGE_CUT, '100% 100%', '0 0'] : [SOLID, '100% 100%', '0 0'],
+        overlapped
+            ? shape === 'circle'
+                ? [CIRCLE_CUT, CIRCLE_CUT_SIZE, CIRCLE_CUT_AT]
+                : [SQUARE_CUT, CIRCLE_CUT_SIZE, CIRCLE_CUT_AT]
+            : [SOLID, '100% 100%', '0 0'],
+    ];
+    return {
+        maskImage: layers.map((layer) => layer[0]).join(', '),
+        maskSize: layers.map((layer) => layer[1]).join(', '),
+        maskPosition: layers.map((layer) => layer[2]).join(', '),
+    };
+}
+const GroupContext = createContext(null);
+/** Set on every avatar in a group but the last, which nothing overlaps. */
+const OverlappedContext = createContext(false);
+/** A picture of someone, or their initials in a colour of their own. */
+function AvatarRoot({ src, name, alt, size, shape, color, fallback, className, style, children, ...props }) {
+    const group = useContext(GroupContext);
+    const overlapped = useContext(OverlappedContext);
+    const resolvedSize = size ?? group?.size ?? 'md';
+    const resolvedShape = shape ?? group?.shape ?? 'circle';
+    const slots = avatarVariants({ shape: resolvedShape, color: color ?? colorOf(name) });
+    // A badge's status is part of who it is, so it is said with the name.
+    const badge = Children.toArray(children).find((child) => isValidElement(child) && child.type === AvatarBadge);
+    const status = badge?.props.label ?? (badge?.props.status ? STATUS_LABEL[badge.props.status] : undefined);
+    const label = [alt ?? name, status].filter(Boolean).join(', ') || undefined;
+    return (_jsxs("span", { "data-slot": "avatar", "data-size": resolvedSize, "data-shape": resolvedShape, role: label ? 'img' : undefined, "aria-label": label, className: slots.root({ className }), style: {
+            ['--avatar-size']: SIZE[resolvedSize],
+            // Here and not on the badge, so the face's cut and the badge's place can both read it.
+            ['--badge-size']: 'max(0.5rem, calc(var(--avatar-size) * 0.28))',
+            ...style,
+        }, ...props, children: [_jsxs(BaseAvatar.Root, { "data-slot": "avatar-face", "aria-hidden": "true", className: slots.face(), style: maskStyle(resolvedShape, badge !== undefined, overlapped), children: [src ? _jsx(BaseAvatar.Image, { src: src, alt: "", className: slots.image() }) : null, _jsx(BaseAvatar.Fallback, { className: slots.fallback(), children: fallback ?? (name ? initialsOf(name) : _jsx(PersonGlyph, {})) })] }), children] }));
+}
+AvatarRoot.displayName = 'Avatar';
+function PersonGlyph() {
+    return (_jsxs("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "8.5", r: "4" }), _jsx("path", { d: "M4 20.5c0-4 3.6-6.5 8-6.5s8 2.5 8 6.5z" })] }));
+}
+/**
+ * A dot or a small icon on the avatar's lower trailing edge. The avatar is
+ * cut away round it, so it reads on any background.
+ */
+function AvatarBadge({ status, color, label: _label, className, ...props }) {
+    const slots = avatarVariants({ status, color: status ? undefined : (color ?? 'muted') });
+    return (_jsx("span", { "aria-hidden": "true", "data-slot": "avatar-badge", "data-status": status, className: slots.badge({ className }), ...props }));
+}
+AvatarBadge.displayName = 'Avatar.Badge';
+/** A row of overlapping avatars, that opens up when it is hovered or focused. */
+function AvatarGroup({ max, size = 'md', shape = 'circle', label, className, style, children, ...props }) {
+    const slots = avatarVariants({ shape });
+    const context = useMemo(() => ({ size, shape }), [size, shape]);
+    const all = Children.toArray(children).filter(isValidElement);
+    const shown = max !== undefined && all.length > max ? all.slice(0, Math.max(0, max)) : all;
+    const rest = all.slice(shown.length);
+    const items = shown.map((child, index) => (_jsx(OverlappedContext.Provider, { value: index < shown.length - 1 || rest.length > 0, children: _jsx("span", { "data-slot": "avatar-group-item", className: slots.item(), children: child }) }, child.key ?? index)));
+    return (_jsx(GroupContext.Provider, { value: context, children: _jsxs("div", { role: "group", "aria-label": label, "data-slot": "avatar-group", className: slots.group({ className }), style: { ['--avatar-size']: SIZE[size], ...style }, ...props, children: [items, rest.length > 0 ? (_jsx("span", { "data-slot": "avatar-group-item", className: slots.item(), children: _jsx(AvatarGroupCount, { people: rest, shape: shape }) })) : null] }) }));
+}
+AvatarGroup.displayName = 'Avatar.Group';
+/** "+3", which opens a list of the three. */
+function AvatarGroupCount({ people, shape }) {
+    const slots = avatarVariants({ shape });
+    const names = people.map((person) => person.props.alt ?? person.props.name).filter(Boolean);
+    return (_jsx("span", { "data-slot": "avatar", className: slots.root(), children: _jsxs(Popover.Root, { children: [_jsxs(Popover.Trigger, { "data-slot": "avatar-group-count", "aria-label": `${people.length} more${names.length ? `: ${names.join(', ')}` : ''}`, className: avatarVariants({ shape }).face({ className: slots.count() }), children: ["+", people.length] }), _jsx(Popover.Portal, { children: _jsx(Popover.Positioner, { side: "bottom", align: "start", sideOffset: 8, className: "z-50", children: _jsx(Popover.Popup, { className: slots.popup(), children: _jsx(GroupContext.Provider, { value: null, children: people.map((person, index) => (_jsxs("div", { className: slots.row(), children: [_jsx(AvatarRoot, { ...person.props, size: "xs", shape: shape, children: null }), _jsx("span", { className: "min-w-0 truncate", children: person.props.name ?? person.props.alt })] }, person.key ?? index))) }) }) }) })] }) }));
+}
+export const Avatar = Object.assign(AvatarRoot, {
+    Badge: AvatarBadge,
+    Group: AvatarGroup,
+});
+export { AvatarBadge, AvatarGroup };

package/dist/components/flow/index.d.ts

@@ -30,6 +30,10 @@
  * a new `position` and the node goes to it, which is how nodes are driven
  * from outside.
  *
+ * A node drawn inside a `Flow.Group` is positioned within it, and travels
+ * with it. `confine` keeps its drag inside the group's box; `pinned` gives the
+ * drag to the group instead, so the node moves only when the group does.
+ *
  * Edges are drawn from the boxes of the nodes they join, measured off the
  * page. An edge therefore follows a node whatever is inside it, and redraws
  * as either end is dragged.
@@ -124,6 +128,16 @@ export interface FlowNodeProps extends Omit<ComponentProps<'div'>, 'id'> {
     position: FlowNodePosition;
     /** Whether it can be dragged and moved with the arrow keys. */
     draggable?: boolean;
+    /**
+     * Inside a `Flow.Group`, stop a drag at the group's edge instead of letting
+     * the node leave it. Does nothing outside a group.
+     */
+    confine?: boolean;
+    /**
+     * Inside a `Flow.Group`, take no drag of its own: a drag that starts on it
+     * moves the group, and the node goes with it.
+     */
+    pinned?: boolean;
     /** Draws it as the one that has been picked. */
     selected?: boolean;
     /** Called when it is pressed without being dragged, or with Enter. */
@@ -134,19 +148,27 @@ export interface FlowNodeProps extends Omit<ComponentProps<'div'>, 'id'> {
     moveStep?: number;
 }
 /** A box on the graph. Fill it with the node parts below, or with anything of your own. */
-declare function FlowNode({ id, position, draggable, selected, onPress, onDelete, moveStep, className, style, children, ...props }: FlowNodeProps): import("react").JSX.Element;
+declare function FlowNode({ id, position, draggable, confine, pinned, selected, onPress, onDelete, moveStep, className, style, children, ...props }: FlowNodeProps): import("react").JSX.Element;
 declare namespace FlowNode {
     var displayName: string;
 }
-export interface FlowGroupProps extends FlowNodeProps {
+export interface FlowGroupProps extends Omit<FlowNodeProps, 'confine' | 'pinned'> {
     /** Written in the corner of the group. */
     label?: ReactNode;
+    /**
+     * A fixed size for the group. Give one when it holds `Flow.Node`s, which are
+     * placed inside it rather than laid out by it, so they do not size it.
+     */
+    size?: {
+        width: number;
+        height: number;
+    };
 }
 /**
  * A dashed box round a few things that belong together. It is a node like any
  * other: it is dragged as one, and an edge can be joined to it.
  */
-declare function FlowGroup({ id, position, draggable, selected: _selected, onPress, onDelete, moveStep, label, className, style, children, ...props }: FlowGroupProps): import("react").JSX.Element;
+declare function FlowGroup({ id, position, draggable, selected: _selected, onPress, onDelete, moveStep, label, size, className, style, children, ...props }: FlowGroupProps): import("react").JSX.Element;
 declare namespace FlowGroup {
     var displayName: string;
 }
@@ -211,7 +233,7 @@ declare namespace FlowHandle {
     var displayName: string;
 }
 export interface FlowEdgeProps {
-    /** Where it leaves from: a node's `id`, or `{ node, handle }`. */
+    /** Where it leaves from: a node's `id`, `"node.handle"` for one of its handles, or `{ node, handle }`. */
     from: FlowEndpointReference;
     /** Where it arrives. */
     to: FlowEndpointReference;

package/dist/components/flow/index.js

@@ -32,6 +32,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * a new `position` and the node goes to it, which is how nodes are driven
  * from outside.
  *
+ * A node drawn inside a `Flow.Group` is positioned within it, and travels
+ * with it. `confine` keeps its drag inside the group's box; `pinned` gives the
+ * drag to the group instead, so the node moves only when the group does.
+ *
  * Edges are drawn from the boxes of the nodes they join, measured off the
  * page. An edge therefore follows a node whatever is inside it, and redraws
  * as either end is dragged.
@@ -94,6 +98,8 @@ const flowVariants = tv({
 });
 const FlowContext = createContext(null);
 const NodeContext = createContext(null);
+/** The group a node is drawn inside, if any. */
+const GroupContext = createContext(null);
 function useFlow(part) {
     const flow = useContext(FlowContext);
     if (!flow)
@@ -111,7 +117,18 @@ function FlowRoot({ defaultViewport = { x: 0, y: 0, zoom: 1 }, minZoom = 0.3, ma
     const slots = flowVariants();
     const root = useRef(null);
     const [viewport, setViewportState] = useState(defaultViewport);
-    const [rects, setRects] = useState({});
+    const [local, setRects] = useState({});
+    const [parents, setParents] = useState({});
+    // A node in a group is placed relative to it; everything that draws or
+    // fits reads the box where it actually is on the graph.
+    const rects = useMemo(() => {
+        const out = {};
+        for (const [id, box] of Object.entries(local)) {
+            const parent = parents[id] ? local[parents[id]] : undefined;
+            out[id] = parent ? { ...box, x: parent.x + box.x, y: parent.y + box.y } : box;
+        }
+        return out;
+    }, [local, parents]);
     const [handles, setHandles] = useState({});
     const [locked, setLocked] = useState(false);
     const [size, setSize] = useState({ width: 0, height: 0 });
@@ -275,7 +292,15 @@ function FlowRoot({ defaultViewport = { x: 0, y: 0, zoom: 1 }, minZoom = 0.3, ma
         window.addEventListener('pointerup', up);
         window.addEventListener('pointercancel', up);
     }, [toGraph]);
-    const place = useCallback((id, position) => {
+    const place = useCallback((id, position, group) => {
+        if (group !== undefined) {
+            setParents((current) => {
+                if ((current[id] ?? null) === group)
+                    return current;
+                const { [id]: _was, ...rest } = current;
+                return group ? { ...rest, [id]: group } : rest;
+            });
+        }
         setRects((current) => {
             const before = current[id];
             if (before && before.x === position.x && before.y === position.y)
@@ -295,6 +320,12 @@ function FlowRoot({ defaultViewport = { x: 0, y: 0, zoom: 1 }, minZoom = 0.3, ma
         });
     }, []);
     const forget = useCallback((id) => {
+        setParents((current) => {
+            if (!(id in current))
+                return current;
+            const { [id]: _gone, ...rest } = current;
+            return rest;
+        });
         setRects((current) => {
             if (!(id in current))
                 return current;
@@ -311,6 +342,7 @@ function FlowRoot({ defaultViewport = { x: 0, y: 0, zoom: 1 }, minZoom = 0.3, ma
     const context = useMemo(() => ({
         viewport,
         rects,
+        local,
         handles,
         locked,
         size,
@@ -328,6 +360,7 @@ function FlowRoot({ defaultViewport = { x: 0, y: 0, zoom: 1 }, minZoom = 0.3, ma
     }), [
         viewport,
         rects,
+        local,
         handles,
         locked,
         size,
@@ -384,16 +417,28 @@ function FlowBackground({ variant = 'dots', gap = 24, size, className }) {
 }
 FlowBackground.displayName = 'Flow.Background';
 /** What a node and a group share: a box on the graph that can be moved. */
-function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
+function useMovable({ id, position, draggable, confine, pinned, group, onPress, onDelete, moveStep, }) {
     const flow = useFlow('Flow.Node');
     const element = useRef(null);
     const { place, measure, forget } = flow;
     const step = moveStep ?? 24;
+    const movable = draggable !== false && !pinned && !flow.locked;
     useLayoutEffect(() => {
-        place(id, position);
+        place(id, position, group);
         // Only when the caller's position changes, not on every drawing.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [id, position.x, position.y, place]);
+    }, [id, position.x, position.y, group, place]);
+    /** Where a move would put it, held inside its group when it is confined. */
+    const within = (next) => {
+        const box = group && confine ? flow.local[group] : undefined;
+        if (!box || box.width === 0)
+            return next;
+        const self = flow.local[id];
+        return {
+            x: clamp(next.x, 0, Math.max(0, box.width - (self?.width ?? 0))),
+            y: clamp(next.y, 0, Math.max(0, box.height - (self?.height ?? 0))),
+        };
+    };
     useLayoutEffect(() => {
         const node = element.current;
         if (!node)
@@ -405,7 +450,7 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
         return () => observer.disconnect();
     }, [id, measure]);
     useEffect(() => () => forget(id), [id, forget]);
-    const at = flow.rects[id] ?? { ...position, width: 0, height: 0 };
+    const at = flow.local[id] ?? { ...position, width: 0, height: 0 };
     const drag = useRef(null);
     const latest = useRef(at);
     latest.current = at;
@@ -416,6 +461,10 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
         if (event.target.closest('[data-flow-handle], button, a, input, textarea, select, [data-no-drag]')) {
             return;
         }
+        // A pinned node lets the press through to the group it is in, which
+        // takes the drag.
+        if (pinned && group)
+            return;
         // Kept from the pane, and from a group this node may be sitting in.
         event.stopPropagation();
         event.currentTarget.setPointerCapture(event.pointerId);
@@ -430,9 +479,9 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
         if (!state.moved && Math.hypot(dx, dy) < 3)
             return;
         state.moved = true;
-        if (draggable === false || flow.locked)
+        if (!movable)
             return;
-        place(id, { x: state.from.x + dx / flow.viewport.zoom, y: state.from.y + dy / flow.viewport.zoom });
+        place(id, within({ x: state.from.x + dx / flow.viewport.zoom, y: state.from.y + dy / flow.viewport.zoom }));
     };
     const onPointerUp = () => {
         const state = drag.current;
@@ -441,7 +490,7 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
             return;
         if (!state.moved)
             onPress?.();
-        else if (draggable !== false && !flow.locked) {
+        else if (movable) {
             flow.onNodeDragEnd?.(id, { x: latest.current.x, y: latest.current.y });
         }
     };
@@ -458,11 +507,11 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
         if (by) {
             // Kept from the canvas, which would pan on the same key.
             event.stopPropagation();
-            if (draggable === false || flow.locked)
+            if (!movable)
                 return;
             event.preventDefault();
             const far = step * (event.shiftKey ? 4 : 1);
-            const next = { x: at.x + by[0] * far, y: at.y + by[1] * far };
+            const next = within({ x: at.x + by[0] * far, y: at.y + by[1] * far });
             place(id, next);
             flow.onNodeDragEnd?.(id, next);
         }
@@ -492,18 +541,19 @@ function useMovable({ id, position, draggable, onPress, onDelete, moveStep, }) {
     };
 }
 /** A box on the graph. Fill it with the node parts below, or with anything of your own. */
-function FlowNode({ id, position, draggable = true, selected = false, onPress, onDelete, moveStep, className, style, children, ...props }) {
-    const movable = useMovable({ id, position, draggable, onPress, onDelete, moveStep });
-    return (_jsx(NodeContext.Provider, { value: id, children: _jsx("div", { ref: movable.element, "data-flow-node": id, tabIndex: 0, "aria-roledescription": "Node", "aria-selected": selected || undefined, className: flowVariants({ selected }).node({ className }), style: { ...movable.style, ...style }, ...movable.handlers, ...props, children: children }) }));
+function FlowNode({ id, position, draggable = true, confine = false, pinned = false, selected = false, onPress, onDelete, moveStep, className, style, children, ...props }) {
+    const group = useContext(GroupContext);
+    const movable = useMovable({ id, position, draggable, confine, pinned, group, onPress, onDelete, moveStep });
+    return (_jsx(NodeContext.Provider, { value: id, children: _jsx("div", { ref: movable.element, "data-flow-node": id, "data-pinned": pinned && group ? '' : undefined, tabIndex: 0, "aria-roledescription": "Node", "aria-selected": selected || undefined, className: flowVariants({ selected }).node({ className }), style: { ...movable.style, ...style }, ...movable.handlers, ...props, children: children }) }));
 }
 FlowNode.displayName = 'Flow.Node';
 /**
  * A dashed box round a few things that belong together. It is a node like any
  * other: it is dragged as one, and an edge can be joined to it.
  */
-function FlowGroup({ id, position, draggable = true, selected: _selected, onPress, onDelete, moveStep, label, className, style, children, ...props }) {
-    const movable = useMovable({ id, position, draggable, onPress, onDelete, moveStep });
-    return (_jsx(NodeContext.Provider, { value: id, children: _jsxs("div", { ref: movable.element, "data-flow-node": id, tabIndex: 0, "aria-roledescription": "Group", className: flowVariants().group({ className }), style: { ...movable.style, ...style }, ...movable.handlers, ...props, children: [label !== undefined ? _jsx("span", { className: flowVariants().groupLabel(), children: label }) : null, children] }) }));
+function FlowGroup({ id, position, draggable = true, selected: _selected, onPress, onDelete, moveStep, label, size, className, style, children, ...props }) {
+    const movable = useMovable({ id, position, draggable, group: null, onPress, onDelete, moveStep });
+    return (_jsx(GroupContext.Provider, { value: id, children: _jsx(NodeContext.Provider, { value: id, children: _jsxs("div", { ref: movable.element, "data-flow-node": id, tabIndex: 0, "aria-roledescription": "Group", className: flowVariants().group({ className }), style: { ...movable.style, ...(size ? { width: size.width, height: size.height } : null), ...style }, ...movable.handlers, ...props, children: [label !== undefined ? _jsx("span", { className: flowVariants().groupLabel(), children: label }) : null, children] }) }) }));
 }
 FlowGroup.displayName = 'Flow.Group';
 /** A strip across the top of a node, ruled off from the rest: a step number and a state. */
@@ -566,7 +616,18 @@ function FlowHandle({ id, position = 'right', offset = 0.5, className, style, ..
         }, ...props }));
 }
 FlowHandle.displayName = 'Flow.Handle';
-const endpoint = (reference) => typeof reference === 'string' ? { node: reference } : reference;
+/**
+ * `"node"`, `"node.handle"` or `{ node, handle }`. A string that is a node's
+ * whole id names that node, so an id with a dot in it still works.
+ */
+const endpoint = (reference, rects) => {
+    if (typeof reference !== 'string')
+        return reference;
+    const dot = reference.lastIndexOf('.');
+    if (dot <= 0 || reference in rects)
+        return { node: reference };
+    return { node: reference.slice(0, dot), handle: reference.slice(dot + 1) };
+};
 /** A line from one node to another, which follows them as they move. */
 function FlowEdge({ from, to, variant = 'bezier', animated = false, dashed = false, color, width = 2, arrow = false, fromSide, toSide, radius = 8, gap = 20, curvature = 0.25, }) {
     const flow = useFlow('Flow.Edge');
@@ -579,8 +640,8 @@ function FlowEdge({ from, to, variant = 'bezier', animated = false, dashed = fal
         query.addEventListener('change', read);
         return () => query.removeEventListener('change', read);
     }, []);
-    const source = endpoint(from);
-    const target = endpoint(to);
+    const source = endpoint(from, flow.rects);
+    const target = endpoint(to, flow.rects);
     const a = flow.rects[source.node];
     const b = flow.rects[target.node];
     // Nothing to draw until both ends have been measured.