@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/repo-stars.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The two steps a star readout is drawn at, as frame and figure together.
+ *
+ * The pair moves as one because a readout is a figure with a unit attached to it
+ * and the two are read as one sentence: a count at the `sm` step beside a noun
+ * at the `md` step is a count and a caption, and a reader scanning a page of them
+ * sees the numbers at one height and the nouns at another. `sm` is for a footer,
+ * a table row and a card description, and `md` is for a card header and a page
+ * header. There is no third step because a star count is never the headline
+ * figure of a page, and a Component that could be drawn at the title step would
+ * be a Component asking to be the thing it annotates.
+ */
+const REPO_STARS_SIZE = {
+    sm: 'items-center gap-1 text-xs',
+    md: 'items-center gap-1.5 text-sm',
+};
+/**
+ * The two halves of a readout, drawn once for the span and once for the anchor.
+ *
+ * A part rather than an Item, and it stays inside this module: DESIGN.md's
+ * authoring contract says compound parts ship from their parent module and do
+ * not form a second vocabulary, so this is a module-local function and not a
+ * fourth export. It exists because the mark has to sit inside the anchor when
+ * there is one, so that the whole readout is the hit area rather than the figure
+ * with a dead mark beside it, and writing the two spans twice is two places to
+ * change them.
+ */
+function StarBody({ mark, figure, className }) {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "repo-stars-mark", className: "flex size-4 shrink-0 items-center justify-center", children: mark }), _jsx("span", { "data-slot": "repo-stars-figure", className: cn('min-w-0 truncate font-medium tabular-nums', className), children: figure })] }));
+}
+/**
+ * How many people starred a source repository, beside the host's own mark.
+ *
+ * **The mark is a slot and the reason is a licence, not a preference.** Prism's
+ * icon lane is Lucide, and Lucide draws interface glyphs rather than other
+ * companies' trademarks, and a repository host's mark is a licensed asset with
+ * rules about its clear space, its colour, its minimum size and where it may
+ * appear. A package that shipped one would be distributing an asset it does not
+ * own, and it would be wrong within a year as hosts redraw. So the consumer passes
+ * the mark and this Component draws the frame around it. The cost is stated
+ * rather than hidden: a consumer who wants the readout in an afternoon has to
+ * source the mark, and a consumer with no host to point at cannot use this
+ * Component at all.
+ *
+ * **The count is printed by a callback and the fallback is the bare number.**
+ * There is no `Intl` default and the omission is the decision, for the reason
+ * `format` states: a compact count is a locale and a judgement, and a figure
+ * formatted in the runtime's locale changes when the deployment region changes.
+ * The visible cost is that a consumer with a six figure count and no formatter
+ * draws all six digits, which is honest and wider than they wanted.
+ *
+ * **There is no navigation region and no landmark, and the reason is that a
+ * count is not a place.** A `<nav>` is a set of routes and this is one figure
+ * beside a mark, so the readout renders a span or an anchor and nothing else. A
+ * consumer who puts one inside their own `<nav>` has made a claim about their own
+ * page that Prism neither makes nor checks, and the `href` is the consumer's to
+ * resolve: this Component validates nothing about it, and the package is router
+ * free and transport free by design.
+ *
+ * **A link here is an anchor, so there is no `target` and no `rel`.** Both belong
+ * to the anchor and the anchor is inside the readout, and an anchor-shaped root
+ * that changed element with `href` would put `rel` and `target` onto a `span` on
+ * every readout that has no link, which is invalid markup for a control Prism
+ * did not draw. A consumer who needs a new tab or a referrer policy writes their
+ * own anchor around the readout, which is one element and keeps every class here.
+ *
+ * **The link's ink is `brand-ink` and the readout's is `foreground`, and that
+ * split is DESIGN.md's Brand Ink Rule rather than a preference.** A readout that
+ * is not a link is a figure and takes the page's ink. A readout that is a link
+ * has to read as something a reader may follow, and the token gate measures
+ * `brand-ink` at 4.5:1 against the page, a card and the accent surface in both
+ * modes of all six sources. The focus ring is drawn at full strength on the
+ * anchor rather than left to the browser, so the indicator this Component owns
+ * is the indicator the gate can check.
+ *
+ * **It is a server Component, and the reason is that everything it draws is
+ * decided from props.** No hook, no state, no effect, no handler and no directive,
+ * so a page with four star readouts ships no JavaScript for them at all. The
+ * consequence worth stating is the one a reader would otherwise have to work out:
+ * with no `href` there is no interaction, and with one the only behaviour is the
+ * browser's own navigation, so there is nothing this Component could need a client
+ * runtime to do. The cost is that a consumer who wants the count to refresh
+ * itself is reaching for a `live` surface and a subscription Prism does not own.
+ */
+function RepoStars({ count, label, mark, format, href, size = 'md', className, ...props }) {
+    const shown = format === undefined ? String(count) : format(count);
+    const figure = `${shown} ${label}`;
+    return (_jsx("span", { "data-slot": "repo-stars", className: cn('inline-flex max-w-full', className), ...props, children: href === undefined ? (_jsx(StarBody, { mark: mark, figure: figure, className: cn(REPO_STARS_SIZE[size], 'text-foreground') })) : (_jsx("a", { "data-slot": "repo-stars-link", href: href, className: cn(REPO_STARS_SIZE[size], 'hover:underline focus-visible:ring-ring inline-flex min-w-0 rounded-sm underline-offset-2 outline-none focus-visible:ring-[3px]'), children: _jsx(StarBody, { mark: mark, figure: figure, className: "text-brand-ink" }) })) }));
+}
+export { RepoStars };

package/dist/components/ui/resizable.d.ts

@@ -0,0 +1,153 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/**
+ * The divider's position, as a percentage along the group's main axis.
+ *
+ * A percentage rather than a pixel count because the group is a proportion of
+ * whatever the page gives it, and a divider measured in pixels is wrong the
+ * moment the window is resized or the group is put in a narrower column. A
+ * percentage is wrong for one case and that case is a pane whose content must
+ * not reflow, and a caller who needs one is measuring their content rather than
+ * asking for a split.
+ */
+type Position = number;
+/** How the panes are laid out, and therefore which pair of arrows moves a divider. */
+type ResizableOrientation = 'horizontal' | 'vertical';
+/** The props the Resizable group accepts. */
+export interface ResizableProps extends Omit<ComponentProps<'div'>, 'onChange'> {
+    /**
+     * The accessible name of the group.
+     *
+     * Required rather than defaulted, because a resizable is announced as two
+     * panes with a divider between them, and two unnamed panes side by side are a
+     * page where a reader is told "region" twice and cannot tell which is which.
+     */
+    label: string;
+    /** Whether the panes sit side by side or stacked. @defaultValue horizontal */
+    orientation?: ResizableOrientation;
+    /**
+     * The divider's starting position, as a percentage along the main axis.
+     * @defaultValue 50
+     */
+    defaultPosition?: Position;
+    /**
+     * The controlled divider position, as a percentage along the main axis.
+     *
+     * The position is a prop and a callback rather than something the group keeps
+     * to itself, and that is the decision this Component makes: **a split is
+     * worth remembering, and this Component will not remember it for you.** A
+     * reader who drags a sidebar to where their work fits and comes back to a
+     * reset split has been told the preference did not count, and the honest fix is
+     * the caller reading this and persisting it, because a design system cannot
+     * know a reader's storage, cannot know which of a reader's panes this one is,
+     * and cannot know whether a second reader of the same account wants the same
+     * number. Pass the stored value back as `position` and this is a controlled
+     * group with no storage of its own anywhere.
+     */
+    position?: Position;
+    /** Called when the divider moves, with the new position. */
+    onPositionChange?: (position: Position) => void;
+    /** Whether the divider ignores user interaction. @defaultValue false */
+    disabled?: boolean;
+    /** The panes and the divider between them. */
+    children?: ReactNode;
+}
+/** The props ResizablePanel accepts. */
+export interface ResizablePanelProps extends ComponentProps<'div'> {
+    /** The pane's share of the group, as a percentage. @defaultValue 50 */
+    size?: Position;
+}
+/**
+ * Two panes with a divider between them that both a pointer and a keyboard move.
+ *
+ * **The divider is the Component, and everything about it is a decision a
+ * consumer would otherwise make badly.** It is an ARIA separator that is
+ * focusable, so the split is operable without a pointer at all, and it reports
+ * `aria-valuenow` as the position along the split, so a reader is told where the
+ * divider is rather than only being able to feel it. Arrow keys move it by a
+ * small step, Home takes it to one end and End to the other, and both are
+ * clamped, so a reader who holds the key stops at the end rather than pushing a
+ * pane to nothing and being unable to get it back.
+ *
+ * **It remembers nothing across a reload, and that is deliberate.** The position
+ * is a prop and a callback, so a caller who wants a reader's split to survive a
+ * reload persists it and passes it back, and a design system that wrote to a
+ * reader's storage unasked would be making a claim about the product it does not
+ * know. The failure this prevents is a sidebar that silently resets, which is the
+ * same class of defect as a control that forgets a setting the reader chose and
+ * nobody can explain.
+ *
+ * **A drag reads the group's box once, at the press, and is arithmetic after
+ * that.** Every frame of a drag needs the group's travel, and reading it on each
+ * frame means reading it immediately after the frame before wrote the new position
+ * and therefore wrote new styles: one forced synchronous layout per frame, on the
+ * main thread, in the middle of the interaction the reader is holding. The box
+ * cannot change under a drag this Component started, because the panes are given a
+ * percentage of the group rather than the other way round, so the box is read where
+ * the press happened and reused. **A group resized by something else part way through
+ * a drag finishes that drag against the travel it started with**, which is the answer
+ * a reader mid-gesture can use; a caller who needs a drag that follows a changing
+ * group ends that drag and starts it again. The keyboard reads no box at all: an
+ * arrow key moves the divider by a share of its position, so current layout is never
+ * stale for a move that does not consult it.
+ *
+ * **A divider has a name and it is the caller's word.** There is no default,
+ * because a default would be the same word on every divider on every page and
+ * would be true of none of them.
+ *
+ * **The coarse-pointer floor is paid with a band, and the drag does not move.** A
+ * one pixel divider cannot be grown: the two panes are given percentages of the
+ * group and already fill it, so a 44 pixel divider would push a pane off the screen
+ * on a phone. A transparent 44 by 44 band centred on the line gives the target and
+ * leaves the drawing, the arithmetic and the layout exactly as they were, because the
+ * drag reads the group's box rather than this element's. The cost is that a press
+ * within 21 pixels of the line grabs the divider rather than the pane; it is stated
+ * at the class, which is where a reader changing that class will look. See
+ * `DESIGN.md`, The coarse-pointer floor.
+ *
+ * This is the one Component here that is not composed on a Base UI primitive,
+ * because Base UI 1.8.0 ships none: the package has no `Resizable` in it, so the
+ * separator role, the focusable-divider keyboard model and the drag are authored
+ * here rather than wrapped. Every other overlay in this batch is composed, and a
+ * hand-rolled focus trap or portal would be a second and worse answer; a divider
+ * is none of those five things.
+ */
+declare function Resizable({ className, label, orientation, defaultPosition, position: positionProp, onPositionChange, disabled, ...props }: ResizableProps): import("react").JSX.Element;
+/**
+ * One pane of the split.
+ *
+ * `size` is a prop rather than something computed from the content, because a
+ * pane whose width depends on what is in it is how a split ends up reporting a
+ * different position after a reload than before one, and the divider is measured
+ * against a box the reader cannot predict.
+ */
+declare function ResizablePanel({ className, size, style, ...props }: ResizablePanelProps): import("react").JSX.Element;
+/**
+ * The divider, and the whole of the Component's behaviour.
+ *
+ * A focusable ARIA separator with a value, so the split is operable and
+ * announced: `role="separator"`, `aria-valuenow` for the position, and
+ * `aria-orientation` for the axis, which is what tells a reader whether the left
+ * and right arrows or the up and down ones are the ones to press.
+ */
+declare function ResizableHandle({ className, label, onKeyDown, ...props }: ResizableHandleProps): import("react").JSX.Element;
+/**
+ * The props ResizableHandle accepts.
+ *
+ * The `label` is required for the same reason the group's is, and it is a prop
+ * rather than a default because there is no honest default: a divider named
+ * "Resize" in a page with a file tree, a preview and a comment thread tells a
+ * reader nothing about which one they are holding, and the words that would
+ * tell them are the words for that product's panes.
+ */
+export interface ResizableHandleProps extends Omit<ComponentProps<'div'>, 'onChange'> {
+    /**
+     * The accessible name of this divider.
+     *
+     * Required. A divider with no name is announced as "separator", and a page
+     * with three of them is a page where a screen reader user cannot tell which
+     * one they are about to move.
+     */
+    label: string;
+}
+export { Resizable, ResizablePanel, ResizableHandle };
+//# sourceMappingURL=resizable.d.ts.map

package/dist/components/ui/resizable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resizable.d.ts","sourceRoot":"","sources":["../../../src/components/ui/resizable.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId;;;;;;;;;GASG;AACH,KAAK,QAAQ,GAAG,MAAM,CAAA;AAEtB,sFAAsF;AACtF,KAAK,oBAAoB,GAAG,YAAY,GAAG,UAAU,CAAA;AAgDrD,6CAA6C;AAC7C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7E;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC;;;OAGG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAA;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,KAAK,EACL,WAA0B,EAC1B,eAAoB,EACpB,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAChB,QAAgB,EAChB,GAAG,KAAK,EACT,EAAE,cAAc,+BA0FhB;AAED;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,IAAS,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BAoBrF;AAED;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BAiKvF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnF;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAED,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA"}

package/dist/components/ui/resizable.js

@@ -0,0 +1,297 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useRef, useState, } from 'react';
+import { cn } from '../../lib/utils.js';
+/** The window the divider may travel in, as a percentage of the group. */
+const MIN = 10;
+const MAX = 90;
+/** How far one arrow-key press moves the divider, as a percentage of the group. */
+const STEP = 5;
+const ResizableContext = createContext(null);
+/**
+ * The group context, which a pane and a divider are both children of.
+ *
+ * The part name is a machine value and lowercase on purpose: it reaches a
+ * developer in a console and never a reader, and the gate that refuses shipped
+ * copy cannot tell a part's own name from a sentence. The diagnostic is the
+ * house's own shape, an error thrown when a caller has composed a part outside
+ * the group it belongs to, and the useful half of it is what to do about it.
+ */
+function useResizableContext(part) {
+    const context = useContext(ResizableContext);
+    if (context === null) {
+        throw new Error(`Resizable: the ${part} must be rendered inside a Resizable, because the split is owned by the group and neither part can know it on its own.`);
+    }
+    return context;
+}
+/**
+ * Two panes with a divider between them that both a pointer and a keyboard move.
+ *
+ * **The divider is the Component, and everything about it is a decision a
+ * consumer would otherwise make badly.** It is an ARIA separator that is
+ * focusable, so the split is operable without a pointer at all, and it reports
+ * `aria-valuenow` as the position along the split, so a reader is told where the
+ * divider is rather than only being able to feel it. Arrow keys move it by a
+ * small step, Home takes it to one end and End to the other, and both are
+ * clamped, so a reader who holds the key stops at the end rather than pushing a
+ * pane to nothing and being unable to get it back.
+ *
+ * **It remembers nothing across a reload, and that is deliberate.** The position
+ * is a prop and a callback, so a caller who wants a reader's split to survive a
+ * reload persists it and passes it back, and a design system that wrote to a
+ * reader's storage unasked would be making a claim about the product it does not
+ * know. The failure this prevents is a sidebar that silently resets, which is the
+ * same class of defect as a control that forgets a setting the reader chose and
+ * nobody can explain.
+ *
+ * **A drag reads the group's box once, at the press, and is arithmetic after
+ * that.** Every frame of a drag needs the group's travel, and reading it on each
+ * frame means reading it immediately after the frame before wrote the new position
+ * and therefore wrote new styles: one forced synchronous layout per frame, on the
+ * main thread, in the middle of the interaction the reader is holding. The box
+ * cannot change under a drag this Component started, because the panes are given a
+ * percentage of the group rather than the other way round, so the box is read where
+ * the press happened and reused. **A group resized by something else part way through
+ * a drag finishes that drag against the travel it started with**, which is the answer
+ * a reader mid-gesture can use; a caller who needs a drag that follows a changing
+ * group ends that drag and starts it again. The keyboard reads no box at all: an
+ * arrow key moves the divider by a share of its position, so current layout is never
+ * stale for a move that does not consult it.
+ *
+ * **A divider has a name and it is the caller's word.** There is no default,
+ * because a default would be the same word on every divider on every page and
+ * would be true of none of them.
+ *
+ * **The coarse-pointer floor is paid with a band, and the drag does not move.** A
+ * one pixel divider cannot be grown: the two panes are given percentages of the
+ * group and already fill it, so a 44 pixel divider would push a pane off the screen
+ * on a phone. A transparent 44 by 44 band centred on the line gives the target and
+ * leaves the drawing, the arithmetic and the layout exactly as they were, because the
+ * drag reads the group's box rather than this element's. The cost is that a press
+ * within 21 pixels of the line grabs the divider rather than the pane; it is stated
+ * at the class, which is where a reader changing that class will look. See
+ * `DESIGN.md`, The coarse-pointer floor.
+ *
+ * This is the one Component here that is not composed on a Base UI primitive,
+ * because Base UI 1.8.0 ships none: the package has no `Resizable` in it, so the
+ * separator role, the focusable-divider keyboard model and the drag are authored
+ * here rather than wrapped. Every other overlay in this batch is composed, and a
+ * hand-rolled focus trap or portal would be a second and worse answer; a divider
+ * is none of those five things.
+ */
+function Resizable({ className, label, orientation = 'horizontal', defaultPosition = 50, position: positionProp, onPositionChange, disabled = false, ...props }) {
+    const [internal, setInternal] = useState(defaultPosition);
+    const [dragging, setDragging] = useState(false);
+    const group = useRef(null);
+    const { ref: callerRef, ...rest } = props;
+    // Both refs, rather than mine and then the caller's. The drag measures the
+    // pointer against this element's box, so a caller who forwarded a ref and
+    // silently replaced ours would get a divider the keyboard moves and the pointer
+    // does not, which is a split that only half works.
+    const setGroup = useCallback((element) => {
+        group.current = element;
+        if (typeof callerRef === 'function')
+            callerRef(element);
+        else if (callerRef !== null && callerRef !== undefined)
+            callerRef.current = element;
+    }, [callerRef]);
+    const controlled = positionProp !== undefined;
+    const position = controlled ? positionProp : internal;
+    /**
+     * The position every move is measured from, kept in a ref rather than read
+     * from the rendered value.
+     *
+     * This is the whole of the keyboard model and it is not a style choice. A
+     * reader who holds ArrowRight produces four key events before React has
+     * re-rendered, and a move that read the rendered position each time would see
+     * the same number four times and travel one step instead of four. The divider
+     * would then feel broken to exactly the reader using it the way it is meant to
+     * be used, and a drag would run behind the pointer.
+     */
+    const latest = useRef(position);
+    latest.current = position;
+    const moveTo = useCallback((next) => {
+        if (disabled)
+            return;
+        const clamped = Math.min(MAX, Math.max(MIN, next));
+        latest.current = clamped;
+        if (!controlled)
+            setInternal(clamped);
+        onPositionChange?.(clamped);
+    }, [controlled, disabled, onPositionChange]);
+    const moveBy = useCallback((delta) => {
+        if (disabled)
+            return;
+        moveTo(latest.current + delta);
+    }, [disabled, moveTo]);
+    const value = useMemo(() => ({
+        orientation,
+        position,
+        moveTo,
+        moveBy,
+        min: MIN,
+        max: MAX,
+        disabled,
+        dragging,
+        setDragging,
+        groupElement: () => group.current,
+    }), [orientation, position, moveTo, moveBy, disabled, dragging]);
+    return (_jsx(ResizableContext.Provider, { value: value, children: _jsx("div", { "data-slot": "resizable", role: "group", "aria-label": label, "data-orientation": orientation, "data-dragging": dragging ? 'true' : undefined, ref: setGroup, className: cn('flex h-full w-full', orientation === 'vertical' ? 'flex-col' : 'flex-row', 'data-[dragging]:select-none', className), ...rest }) }));
+}
+/**
+ * One pane of the split.
+ *
+ * `size` is a prop rather than something computed from the content, because a
+ * pane whose width depends on what is in it is how a split ends up reporting a
+ * different position after a reload than before one, and the divider is measured
+ * against a box the reader cannot predict.
+ */
+function ResizablePanel({ className, size = 50, style, ...props }) {
+    const { orientation, disabled } = useResizableContext('panel');
+    return (_jsx("div", { "data-slot": "resizable-panel", "data-orientation": orientation, "data-disabled": disabled ? 'true' : undefined, style: {
+            flexBasis: `${size}%`,
+            flexGrow: 0,
+            flexShrink: 0,
+            minWidth: 0,
+            minHeight: 0,
+            ...style,
+        }, className: cn('overflow-hidden', className), ...props }));
+}
+/**
+ * The divider, and the whole of the Component's behaviour.
+ *
+ * A focusable ARIA separator with a value, so the split is operable and
+ * announced: `role="separator"`, `aria-valuenow` for the position, and
+ * `aria-orientation` for the axis, which is what tells a reader whether the left
+ * and right arrows or the up and down ones are the ones to press.
+ */
+function ResizableHandle({ className, label, onKeyDown, ...props }) {
+    const { orientation, position, moveTo, moveBy, min, max, disabled, dragging, setDragging, groupElement, } = useResizableContext('divider');
+    const last = useRef(null);
+    // The group's box, read once at the press and held for the drag.
+    //
+    // A pointer drag moves the divider by a share of the group's travel, so every frame
+    // of the drag needs that box, and reading it inside `onPointerMove` means reading
+    // it immediately after the frame before wrote the new position and therefore
+    // wrote new styles. That is one forced synchronous layout per frame of every drag,
+    // on the main thread, in the middle of the interaction a reader is holding, and it
+    // is the whole cost of the divider for a number that cannot change while the drag
+    // runs: the panes are given a percentage of the group and the group is not given a
+    // percentage of the panes, so moving the divider does not move the box it is
+    // measured against. So the box is read where the press happened, which is the last
+    // moment before the drag with no pending write in front of it, and every frame
+    // after that is arithmetic. `ReorderableList` measures its rows the same way, once
+    // at `pointerdown`, for the same reason.
+    //
+    // **The keyboard never reads it.** A key press moves the divider by a fixed share
+    // of the position rather than by a distance through the group, so the keyboard
+    // model needs no box, and current layout is never stale for a move that does not
+    // consult it.
+    //
+    // What this does not see is a group resized by something else part way through a
+    // drag, which a read per frame would have picked up on the next frame. The ordinary
+    // case of that is a window resized mid-drag, and there the drag finishes against
+    // the travel it started with, which is the answer a reader who is mid-gesture can
+    // use; a caller who changes the group's size while a pointer is down on it is a
+    // caller whose drag has to end and start again, and nothing here pretends to hold
+    // that case rather than holding it badly.
+    const box = useRef(null);
+    const onPointerDown = (event) => {
+        if (disabled || event.button !== 0)
+            return;
+        const group = groupElement();
+        if (group === null)
+            return;
+        box.current = group.getBoundingClientRect();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        // The pointer's own coordinate, and not the divider's, because a drag is a
+        // distance travelled and the first event is a press rather than a move.
+        last.current = orientation === 'horizontal' ? event.clientX : event.clientY;
+        setDragging(true);
+    };
+    const onPointerMove = (event) => {
+        if (last.current === null)
+            return;
+        const measured = box.current;
+        if (measured === null)
+            return;
+        // Measured along the group's own axis, so a horizontal split follows the x
+        // and a vertical one follows the y, and a caller that passes the wrong
+        // `orientation` cannot get a divider that tracks the wrong coordinate.
+        const here = orientation === 'horizontal' ? event.clientX : event.clientY;
+        const delta = here - last.current;
+        const travel = orientation === 'horizontal' ? measured.width : measured.height;
+        if (travel === 0)
+            return;
+        moveBy((delta / travel) * 100);
+        last.current = here;
+    };
+    const endDrag = (event) => {
+        if (last.current === null)
+            return;
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        last.current = null;
+        // The box belonged to the press that is ending here. A pointer move that arrives
+        // after the release is refused by `last` already, and holding a box a drag has
+        // given up is a number nothing could explain.
+        box.current = null;
+        setDragging(false);
+    };
+    const onKey = (event) => {
+        if (disabled)
+            return;
+        const decrease = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+        const increase = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+        if (event.key === decrease)
+            moveBy(-STEP);
+        else if (event.key === increase)
+            moveBy(STEP);
+        else if (event.key === 'Home')
+            moveTo(min);
+        else if (event.key === 'End')
+            moveTo(max);
+        else
+            return;
+        // Only the keys this Component owns are prevented, so a reader who binds
+        // something else to the divider still gets it.
+        event.preventDefault();
+        event.stopPropagation();
+    };
+    return (_jsx("div", { "data-slot": "resizable-handle", role: "separator", "aria-label": label, "aria-orientation": orientation, "aria-valuenow": Math.round(position), "aria-valuemin": min, "aria-valuemax": max, "aria-disabled": disabled ? 'true' : undefined, tabIndex: disabled ? -1 : 0, "data-orientation": orientation, "data-dragging": dragging ? 'true' : undefined, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: endDrag, onPointerCancel: endDrag, onKeyDown: (event) => {
+            onKey(event);
+            onKeyDown?.(event);
+        }, className: cn('bg-border relative shrink-0 touch-none outline-none', orientation === 'vertical' ? 'h-px w-full cursor-row-resize' : 'h-full w-px cursor-col-resize', 'transition-colors duration-fast ease-out', 'hover:bg-ring focus-visible:bg-ring data-[dragging]:bg-ring', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', 
+        // The coarse-pointer floor, as a band, and this is the least mechanical control
+        // in the package, so the reasoning is the whole of the note.
+        //
+        // **A step is impossible here, and the reason is arithmetic rather than
+        // taste.** The panes are given `flexBasis: <size>%` with `flexShrink: 0`, so the
+        // two of them already sum to the group's whole width and the divider is what
+        // overflows it, by exactly its own one pixel. A `w-11` divider would overflow the
+        // group by 44, which on a phone pushes the right pane's right edge off the screen.
+        // Making room would mean changing what `size` means, or giving the panes a
+        // coarse-pointer-only basis calculation, and either one re-derives the meaning of
+        // the number a caller passed. A one pixel divider cannot take a step.
+        //
+        // **A band works because three facts hold that the three conditions ask about.**
+        // It is a pseudo-element, so the box the drag measures stays the drawn box and the
+        // arithmetic above is untouched: `onPointerDown` reads the *group's* rect and
+        // `onPointerMove` divides by the group's travel, so nothing reads this element's
+        // own size at all. It paints above both panes without a `z-index`, because the
+        // handle is `relative` with `z-index: auto` and the panes are static, and a
+        // positioned descendant paints after non-positioned siblings. And the band is
+        // 44 by 44 rather than 44 by the handle's length, which is what keeps the overlap
+        // local: along the split the handle already spans the group, so 44 there is free,
+        // and across the split it reaches 21 pixels into each pane over a 44 pixel stretch
+        // of the line rather than the whole height of the group.
+        //
+        // **The cost is stated rather than hidden.** A press within 21 pixels of the line,
+        // over a 44 pixel stretch of it, grabs the divider rather than the pane, and
+        // `touch-none` travels with the band because the pseudo-element resolves its
+        // `touch-action` from this element. So text selection near the divider is
+        // unavailable inside that patch. That is the trade a resize gutter makes on every
+        // platform, and it is bounded to a patch rather than run the length of the panes.
+        // See DESIGN.md, The coarse-pointer floor.
+        'pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-[""]', className), ...props }));
+}
+export { Resizable, ResizablePanel, ResizableHandle };

package/dist/components/ui/scroll-area.d.ts

@@ -0,0 +1,97 @@
+import type { ComponentProps, ReactNode } from 'react';
+/** Which axis the region is expected to scroll on. */
+export type ScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
+/** The props the ScrollArea accepts. */
+export interface ScrollAreaProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * The content the region scrolls through.
+     *
+     * Ordinary children, not a render prop and not a measured height. A consumer
+     * sizes the region from the outside with `className` and puts whatever they like
+     * inside, which is the arrangement that lets a region hold a table, a list of
+     * anything, or a form.
+     */
+    children?: ReactNode;
+    /**
+     * Which scrollbars to draw.
+     *
+     * `both` is the default rather than `vertical` because a region that overflows
+     * on an axis nobody asked about is still a region a reader has to be able to
+     * scroll on that axis, and a scrollbar that is missing is a scrollbar that has
+     * to be found in the browser's own chrome, which is the thing this Component
+     * exists to replace. Pass `vertical` when the content is known never to scroll
+     * sideways, and the horizontal bar is not drawn at all.
+     */
+    orientation?: ScrollAreaOrientation;
+    /**
+     * Keeps the scrollbar in the DOM when the region has nothing to scroll.
+     *
+     * Off by default, and that default is the decision: a region with nothing to
+     * scroll has no scroll position, so a bar drawn beside it is a claim that there
+     * is something past the edge. Turn it on only where a region is expected to
+     * grow and the reader should see the affordance before the content arrives.
+     */
+    keepMounted?: boolean;
+    /**
+     * The accessible name of the region.
+     *
+     * Required rather than defaulted. A scroll region with no name is announced as
+     * a group of focusable nothing, and a page with three of them is a page where a
+     * keyboard reader tabs into a region and cannot tell what is in it or what is
+     * past the edge. The name is the caller's word.
+     */
+    label: string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A scrollable region whose scrollbar belongs to this design system.
+ *
+ * **The browser's scrollbar is the one piece of a page that belongs to no design
+ * system at all.** Every other surface a consumer draws is a token from here, and
+ * the scrollbar beside it is a rectangle the operating system drew, in a colour
+ * chosen for the OS's own background rather than for the card the content is on.
+ * It is also the only control on a page that is resized by dragging, and the only
+ * one that appears and disappears on a timer, so the browser's version is the one
+ * control a design system cannot restyle at all. This is where the package takes
+ * it over, and it is worth saying plainly that the native scrollbar is not
+ * available to restyle: `::-webkit-scrollbar` is one engine, `scrollbar-width` is
+ * two values, and neither can express a track and a thumb in tokens.
+ *
+ * **The scrolling is still the browser's.** This is the decision that matters most
+ * and the one worth arguing with, so here is the argument. The tempting version of
+ * this Component is a `div` with `overflow: hidden` whose content is moved by a
+ * transform on a wheel handler, with a `div` above it pretending to be a
+ * scrollbar. That version has no scroll position at all, so there is nothing for
+ * a keyboard to move, nothing for a screen reader to announce, no momentum, no
+ * scroll-into-view, and no way for a reader to know how far through they are. A
+ * custom scrollbar that is a `div` is worse than the browser's, because the browser
+ * gives a reader all of that for free and the `div` version takes it away.
+ *
+ * So the region here is a real scrollable element in the document: the browser
+ * scrolls it, the browser gives it keyboard focus when it overflows, the arrow
+ * keys, Page Up, Page Down, Home and End all work because it is a scroll
+ * container and not a picture of one. Only the appearance of the bar is taken
+ * over, and the bar is a real control layered over the native one rather than a
+ * replacement for the scrolling.
+ *
+ * **A native scrollbar cannot be styled, so this one is a sibling of the scroll
+ * container rather than a part of it.** That is the whole reason a consumer cannot
+ * assemble this from `overflow-auto` and a coloured box, and it is why the region
+ * is a named landmark: a scrollable region that a keyboard reader can tab into and
+ * that has no name is a tab stop that says nothing. The name is a prop.
+ *
+ * **A region with nothing to scroll draws no scrollbar.** Not a disabled one and
+ * not a faint one: a bar beside a region with no overflow is a claim that there is
+ * something past the edge, and a reader who is told that twice loses trust in the
+ * third bar they meet. The bar is absent, and a caller who wants it present before
+ * the content arrives says so with `keepMounted`.
+ *
+ * It is a client Component, because measuring overflow and positioning a thumb is
+ * a measurement and a measurement is not something a server can do. Everything it
+ * draws is a semantic utility, so a scoped pack boundary restyles the thumb and the
+ * track through the cascade exactly as it restyles the text beside them.
+ */
+declare function ScrollArea({ className, children, orientation, keepMounted, label, ...props }: ScrollAreaProps): import("react").JSX.Element;
+export { ScrollArea };
+//# sourceMappingURL=scroll-area.d.ts.map

package/dist/components/ui/scroll-area.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../../src/components/ui/scroll-area.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAA;AAEtE,wCAAwC;AACxC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC9E;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,QAAQ,EACR,WAAoB,EACpB,WAAmB,EACnB,KAAK,EACL,GAAG,KAAK,EACT,EAAE,eAAe,+BAiEjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}