@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,117 @@
+import type { ComponentProps } from 'react';
+import type { ChartColor } from './chart-frame.js';
+/** The props the Sparkline accepts. */
+export interface SparklineProps extends Omit<ComponentProps<'figure'>, 'children'> {
+    /**
+     * The readings, in order, in the caller's own units.
+     *
+     * Raw magnitudes rather than percentages of a maximum, for the reason
+     * `PulseSeries` gives for its columns and the reason `ChartFrame` gives for its
+     * scale: a caller that pre-normalises has two chances to get the axis wrong, and
+     * a mislabelled axis is a lie with a typeface on it. The tallest reading sets
+     * the top of the box here, and the smallest sets the bottom.
+     */
+    values: readonly number[];
+    /**
+     * The name of the series, and the only thing a screen reader reads before the
+     * numbers.
+     *
+     * Required rather than defaulted, and required for the same two reasons
+     * `ChartFrame` gives: two sparklines in a table of numbers are two pictures a
+     * reader cannot tell apart, and a picture with no name is not announced and not
+     * linkable. A sparkline named "Chart" is a Component shipping a sentence about a
+     * product it knows nothing about.
+     */
+    label: string;
+    /**
+     * The role the line is drawn in. @defaultValue 'chart-1'
+     *
+     * One of the five the token contract publishes, and never a raw colour: a
+     * series colour is a claim about what a thing is, and a Component that knows
+     * nothing about the caller's product has no business choosing one, so the caller
+     * chooses and gets the same ink in every pack and both modes. The default is
+     * `chart-1` because a sparkline is usually alone in its cell and has no series
+     * to be distinguished from.
+     */
+    tone?: ChartColor;
+    /**
+     * The width of the box, in pixels. @defaultValue 96
+     *
+     * A number in pixels rather than a token, and the cost is that a sparkline is
+     * not fluid: one in a column that resizes does not resize with it. The reason is
+     * that a sparkline lives in a table cell or a list row, where its job is to sit
+     * at one size in a column of rows and line up with the figures beside it, and a
+     * percentage of a fluid cell would make every row a different width.
+     */
+    width?: number;
+    /**
+     * The height of the box, in pixels. @defaultValue 24
+     *
+     * Two dozen pixels because a sparkline is a mark, not a plot: it is read beside
+     * its number rather than examined, and a box tall enough to read an axis would
+     * be a chart, which is `ChartFrame`.
+     */
+    height?: number;
+    /**
+     * Whether the last reading takes a mark.
+     *
+     * Off by default, because a line with a dot on its end is a claim that the end
+     * is special. On when the series is a live reading, where the last value is the
+     * one the reader came for and the shape behind it is context.
+     */
+    emphasizeLast?: boolean;
+}
+/**
+ * A series drawn small enough to sit in a cell, and the numbers behind it.
+ *
+ * **It is decorative and described, and both halves are needed.** The drawing is
+ * `aria-hidden` and carries no information a reader can use on its own: a
+ * 96-pixel line with no axis, no labels and no legend is a shape, and a shape a
+ * reader cannot query is the failure a chart exists to prevent. So the values are
+ * also rendered as a table in a visually hidden wrapper, generated from the same
+ * array the line is drawn from, which means a screen reader reaches every number,
+ * a reader's own table navigation can walk it, and a crawler indexing the page
+ * finds the figures rather than a picture. That is the honest answer for a figure
+ * whose entire claim is its shape, and the cost is real: a table of two hundred
+ * rows in the document for a sparkline that occupies ninety-six pixels.
+ *
+ * **The table has no column headings, and that is a gap with a reason.** The
+ * positions are numbered rather than named, because this Item has no words for
+ * what a position is called and inventing "Time" or "Index" would be a claim
+ * about the caller's data. The row head carries the position, the cell carries the
+ * number, and the caption is the caller's own `label`. A caller whose readings
+ * have names, a category axis, a legend, a second series or a visible table is
+ * looking for `ChartFrame`, which is the Component that has room for all of it.
+ *
+ * **Two inputs throw rather than draw, because a drawn lie is worse than a
+ * refusal.** An empty `values` array is a frame with no claim in it, and a series
+ * whose readings are all the same number is a straight stroke with no information
+ * in it. A reader cannot tell a flat line from a broken chart, and the only thing
+ * that separates them is a diagnostic the caller sees. The alternative was to draw
+ * a horizontal line, which is what a charting library does, and which answers
+ * "the data is flat" with a picture that also answers "the chart is broken".
+ *
+ * **A line is scaled to its own range, with no floor at zero, and the cost is
+ * named here.** A bar has to start at zero or its length is not a measurement,
+ * which is why `ChartFrame` floors every scale. A line is read for the shape
+ * between its points, and a series between 900 and 1,000 floored at zero is a
+ * flat line drawn faithfully, which is a picture that hides the thing it was put
+ * there to show. So the range is the data's own. The price is that a series that
+ * moves by two percent looks dramatic, and the answer is the table, which carries
+ * the numbers at the precision the caller gave them.
+ *
+ * **The geometry is `ChartFrame`'s geometry.** The `<svg>` has no `viewBox` and
+ * its coordinates are percentages of the box, so the stroke is pixels rather than
+ * user units and a two-pixel line is two pixels in every box size, and one
+ * `<line>` is drawn per pair of readings rather than a `polyline`, because a
+ * `points` attribute is a list of coordinate pairs joined by a space and a
+ * Component here ships no word-shaped literal. The tone is a semantic utility from
+ * the contract, so a scoped pack boundary restyles the line through the cascade
+ * rather than through a value the drawing is holding.
+ *
+ * It is a server Component. No hook, no state, and the line is arithmetic over
+ * props, so a dashboard full of sparklines costs no client code at all.
+ */
+declare function Sparkline({ className, values, label, tone, width, height, emphasizeLast, ...props }: SparklineProps): import("react").JSX.Element;
+export { Sparkline };
+//# sourceMappingURL=sparkline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sparkline.d.ts","sourceRoot":"","sources":["../../../src/components/ui/sparkline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AA2C/C,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAChF;;;;;;;;OAQG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,MAAM,EACN,KAAK,EACL,IAAgB,EAChB,KAAU,EACV,MAAW,EACX,aAAqB,EACrB,GAAG,KAAK,EACT,EAAE,cAAc,+BA6FhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/sparkline.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableRow } from './table.js';
+import { cn } from '../../lib/utils.js';
+/** The fill a series mark is drawn in, from the role the caller assigned it. */
+const FILL = {
+    'chart-1': 'bg-chart-1',
+    'chart-2': 'bg-chart-2',
+    'chart-3': 'bg-chart-3',
+    'chart-4': 'bg-chart-4',
+    'chart-5': 'bg-chart-5',
+};
+/**
+ * The stroke a line is drawn in, from the same role and no other.
+ *
+ * The same five entries `ChartFrame` draws from, spelled here because that
+ * Component keeps its maps to itself, and the honest cost is a sixth series role
+ * added to the token contract would have to be answered in two places. What keeps
+ * the restatement from drifting is the annotation: both maps are typed
+ * `Record<ChartColor, string>`, so a new role in `ChartColor` is a type error at
+ * the map rather than a mark that silently falls through to no ink.
+ */
+const STROKE = {
+    'chart-1': 'stroke-chart-1',
+    'chart-2': 'stroke-chart-2',
+    'chart-3': 'stroke-chart-3',
+    'chart-4': 'stroke-chart-4',
+    'chart-5': 'stroke-chart-5',
+};
+/**
+ * The band left empty at the top and bottom of the box, as a percentage.
+ *
+ * The stroke is a pixel and a half on a box two dozen pixels tall, with round
+ * caps, so a value at the very top of the range would put half its stroke outside
+ * the box and collide with whatever is on the line above. Ten percent of the
+ * height is a little over two pixels at the default size, which is the stroke and
+ * its cap, and it costs a fifth of the vertical range. A sparkline is read for its
+ * shape and not for its extremes, so that is the right thing to spend.
+ */
+const INSET = 10;
+/**
+ * A series drawn small enough to sit in a cell, and the numbers behind it.
+ *
+ * **It is decorative and described, and both halves are needed.** The drawing is
+ * `aria-hidden` and carries no information a reader can use on its own: a
+ * 96-pixel line with no axis, no labels and no legend is a shape, and a shape a
+ * reader cannot query is the failure a chart exists to prevent. So the values are
+ * also rendered as a table in a visually hidden wrapper, generated from the same
+ * array the line is drawn from, which means a screen reader reaches every number,
+ * a reader's own table navigation can walk it, and a crawler indexing the page
+ * finds the figures rather than a picture. That is the honest answer for a figure
+ * whose entire claim is its shape, and the cost is real: a table of two hundred
+ * rows in the document for a sparkline that occupies ninety-six pixels.
+ *
+ * **The table has no column headings, and that is a gap with a reason.** The
+ * positions are numbered rather than named, because this Item has no words for
+ * what a position is called and inventing "Time" or "Index" would be a claim
+ * about the caller's data. The row head carries the position, the cell carries the
+ * number, and the caption is the caller's own `label`. A caller whose readings
+ * have names, a category axis, a legend, a second series or a visible table is
+ * looking for `ChartFrame`, which is the Component that has room for all of it.
+ *
+ * **Two inputs throw rather than draw, because a drawn lie is worse than a
+ * refusal.** An empty `values` array is a frame with no claim in it, and a series
+ * whose readings are all the same number is a straight stroke with no information
+ * in it. A reader cannot tell a flat line from a broken chart, and the only thing
+ * that separates them is a diagnostic the caller sees. The alternative was to draw
+ * a horizontal line, which is what a charting library does, and which answers
+ * "the data is flat" with a picture that also answers "the chart is broken".
+ *
+ * **A line is scaled to its own range, with no floor at zero, and the cost is
+ * named here.** A bar has to start at zero or its length is not a measurement,
+ * which is why `ChartFrame` floors every scale. A line is read for the shape
+ * between its points, and a series between 900 and 1,000 floored at zero is a
+ * flat line drawn faithfully, which is a picture that hides the thing it was put
+ * there to show. So the range is the data's own. The price is that a series that
+ * moves by two percent looks dramatic, and the answer is the table, which carries
+ * the numbers at the precision the caller gave them.
+ *
+ * **The geometry is `ChartFrame`'s geometry.** The `<svg>` has no `viewBox` and
+ * its coordinates are percentages of the box, so the stroke is pixels rather than
+ * user units and a two-pixel line is two pixels in every box size, and one
+ * `<line>` is drawn per pair of readings rather than a `polyline`, because a
+ * `points` attribute is a list of coordinate pairs joined by a space and a
+ * Component here ships no word-shaped literal. The tone is a semantic utility from
+ * the contract, so a scoped pack boundary restyles the line through the cascade
+ * rather than through a value the drawing is holding.
+ *
+ * It is a server Component. No hook, no state, and the line is arithmetic over
+ * props, so a dashboard full of sparklines costs no client code at all.
+ */
+function Sparkline({ className, values, label, tone = 'chart-1', width = 96, height = 24, emphasizeLast = false, ...props }) {
+    if (values.length === 0) {
+        throw new Error('Sparkline: values is empty, so there is no series to draw. A sparkline with nothing in it ' +
+            'is a frame carrying no claim. Pass the readings, or render the number instead of a line.');
+    }
+    const lowest = Math.min(...values);
+    const tallest = Math.max(...values);
+    if (lowest === tallest) {
+        throw new Error('Sparkline: every reading in the series is the same number, so a line through them is a ' +
+            'stroke with no information in it and a reader cannot tell that from a broken chart. Pass ' +
+            'the series, or if the quantity genuinely never changes, render the number instead of a line.');
+    }
+    // The range is the data's own, so a narrow series is still a readable shape and
+    // the stroke stays a stroke at any box size. See the JSDoc above for why there
+    // is no floor at zero. A single reading has thrown above, because one value is
+    // a series whose readings are all equal, so the divisor below is never zero.
+    const span = tallest - lowest;
+    const at = (index) => (index / (values.length - 1)) * 100;
+    const up = (value) => INSET + (1 - (value - lowest) / span) * (100 - INSET * 2);
+    const last = values.length - 1;
+    return (_jsxs("figure", { "data-slot": "sparkline", "aria-label": label, className: cn('inline-flex shrink-0 flex-col', className), style: { width, height }, ...props, children: [_jsxs("span", { "data-slot": "sparkline-plot", "aria-hidden": "true", className: "relative block size-full", children: [_jsx("svg", { className: "pointer-events-none absolute inset-0 size-full overflow-visible", children: values.slice(1).map((value, index) => (_jsx("line", { x1: `${at(index)}%`, y1: `${up(values[index])}%`, x2: `${at(index + 1)}%`, y2: `${up(value)}%`, className: STROKE[tone], strokeWidth: 1.5, strokeLinecap: "round" }, index))) }), emphasizeLast ? (_jsx("span", { "data-slot": "sparkline-last", className: cn('absolute size-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full', FILL[tone]), style: { left: `${at(last)}%`, top: `${up(values[last])}%` } })) : null] }), _jsx("div", { "data-slot": "sparkline-table", className: "sr-only", children: _jsxs(Table, { children: [_jsx(TableCaption, { children: label }), _jsx(TableBody, { children: values.map((value, index) => (_jsxs(TableRow, { children: [_jsx(TableHead, { scope: "row", className: "font-medium tabular-nums", children: index + 1 }), _jsx(TableCell, { className: "tabular-nums", children: value })] }, index))) })] }) })] }));
+}
+export { Sparkline };

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

@@ -0,0 +1,79 @@
+import type { ComponentProps } from 'react';
+/**
+ * The props a Spinner accepts.
+ *
+ * `label` is required and there is no default, which is the Component's one
+ * design decision and the reason it is not simply "a div with a border on it".
+ */
+export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'children'> {
+    /**
+     * The words a screen reader hears while the work is happening.
+     *
+     * Required, and required to be a real sentence rather than a verb. A busy
+     * indicator with no name is an animation, and an animation is nothing to a
+     * reader who cannot see it; the whole reason this Component exists rather
+     * than a border on a `div` is that it has to be able to say what is busy in
+     * the consumer's own words, because a shared library cannot know whether the
+     * answer is "Loading invoices" or "Carregando faturas".
+     *
+     * The words name the work, not the Component. "Loading" alone is a weaker
+     * name than "Loading invoices", and a caller who has two spinners on a page
+     * needs to tell them apart in the same way a sighted reader does.
+     */
+    label: string;
+    /**
+     * The diameter of the ring, in one of three authored steps.
+     *
+     * A prop rather than something a caller sets through `className`, because a
+     * ring whose size is a layout decision is a ring that can be 2px and become
+     * invisible, and `className` is layout only on every Component in this
+     * package. Three steps is what a spinner is ever drawn at: beside body text,
+     * beside a control's label, and alone in a region of its own.
+     *
+     * @defaultValue 'default'
+     */
+    size?: 'sm' | 'default' | 'lg';
+}
+/**
+ * A mark that says work is happening and nothing about how much of it is left.
+ *
+ * **It is not a Progress and it is not a Skeleton, and the three are confused
+ * often enough to be worth stating.** A Skeleton stands in for content: it has
+ * the shape of the thing that is arriving, so the page does not move when the
+ * content lands. A Progress reports a position: it carries a value, a minimum
+ * and a maximum, and a screen reader is told "68 percent" rather than the width
+ * of a coloured bar. A Spinner reports exactly one fact, that something is
+ * happening, and carries neither a shape nor a value. Pick by the question:
+ * *what will arrive* is a Skeleton, *how far along* is a Progress, and *is
+ * anything happening at all* is a Spinner.
+ *
+ * **The honest reason a Spinner is often the wrong answer is that it causes a
+ * layout shift.** The ring is a fixed square, so the content it stands in for
+ * is not, and everything below it moves twice: once when the content is
+ * replaced by the ring, and again when the ring is replaced by the content.
+ * A reader's eye has to find the thing twice. That is the whole cost of this
+ * Component and it is not paid when the shape of what is coming is already
+ * known, which is why:
+ *
+ * - **Do not use a Spinner as a page-level loading state where the layout is
+ *   known.** A first paint of Skeletons is a better answer, and
+ *   `Skeleton` is the Component for it. A Spinner alone in the middle of an
+ *   empty page tells the reader nothing about the page they are about to get.
+ * - **Do not use a Spinner for a task of known length.** A countable upload
+ *   is a `Progress`, and a bar that shows real information beats a ring that
+ *   shows anxiety.
+ * - **Do not use a Spinner for a wait under about a second.** A control that
+ *   disables itself for 400ms and then re-enables is a control that flickers.
+ *   A `Skeleton` that never gets to paint, or nothing at all, is quieter.
+ * - **Do not use a Spinner inside a Button next to a label that already says
+ *   what is happening.** The label is the announcement; the ring is the
+ *   confirmation, and beside a label that already reads "Saving..." it is a
+ *   second copy of a sentence the reader can already see.
+ *
+ * **It is a server Component.** It reads its props and renders, so the client
+ * directive would be a claim about work this Component does not do. A hundred
+ * spinners on a page cost no JavaScript.
+ */
+declare function Spinner({ className, label, size, ...props }: SpinnerProps): import("react").JSX.Element;
+export { Spinner };
+//# sourceMappingURL=spinner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../../src/components/ui/spinner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC5E;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,IAAI,CAAA;CAC/B;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,iBAAS,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,IAAgB,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,+BA+B9E;AAED,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/dist/components/ui/spinner.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The ring, at each authored size.
+ *
+ * `size-*` on the box and `border-2` on the arc. A spinner is drawn as a
+ * rounded box with one transparent edge, which is the shape that reads as
+ * "turning" without a keyframe: the gap in the border is what moves, and the
+ * box is a fixed frame around it.
+ *
+ * The one animation is `animate-spin`, and it is the only motion in this
+ * package that is a *rotation* rather than a transition between two states.
+ * A keyframe cannot be authored here - the design system emits no keyframes
+ * and a Component cannot add one - and `animate-spin` is a Tailwind utility
+ * that already carries its own, so this is the honest ceiling: a spinner that
+ * cannot be built from a transition between two states needs a loop, and a
+ * loop is what `animate-spin` is. It is state feedback rather than decoration
+ * for the reason `Timeline`'s pulsing mark is: it is running because work is
+ * running, and it stops when the work does.
+ *
+ * **Under reduced motion the ring stops turning, and the reason it is not
+ * guarded here is that the stylesheet has already stopped it.** An unbounded
+ * loop is the one motion the setting was asked about, so
+ * `packages/ui/src/styles.css` ends with an unlayered `prefers-reduced-motion`
+ * rule that sets `animation: none` on the universal selector, and a
+ * `motion-safe:` beside an unguarded `animate-spin` would have been the inert
+ * shape `RangeField` shipped rather than a guard. What the reader gets instead
+ * is a still ring and the words beside it: the ring is `aria-hidden` and the
+ * name is on the `status`, so the announcement is unchanged and only the
+ * turning is gone. The cost is named rather than argued away, and it is the
+ * reason `label` is required: a caller who drew the ring with nothing beside it
+ * has no signal left, and there is one in this package that always worked.
+ */
+const RING = {
+    sm: 'size-4 border-2',
+    default: 'size-5 border-2',
+    lg: 'size-8 border-[3px]',
+};
+/**
+ * A mark that says work is happening and nothing about how much of it is left.
+ *
+ * **It is not a Progress and it is not a Skeleton, and the three are confused
+ * often enough to be worth stating.** A Skeleton stands in for content: it has
+ * the shape of the thing that is arriving, so the page does not move when the
+ * content lands. A Progress reports a position: it carries a value, a minimum
+ * and a maximum, and a screen reader is told "68 percent" rather than the width
+ * of a coloured bar. A Spinner reports exactly one fact, that something is
+ * happening, and carries neither a shape nor a value. Pick by the question:
+ * *what will arrive* is a Skeleton, *how far along* is a Progress, and *is
+ * anything happening at all* is a Spinner.
+ *
+ * **The honest reason a Spinner is often the wrong answer is that it causes a
+ * layout shift.** The ring is a fixed square, so the content it stands in for
+ * is not, and everything below it moves twice: once when the content is
+ * replaced by the ring, and again when the ring is replaced by the content.
+ * A reader's eye has to find the thing twice. That is the whole cost of this
+ * Component and it is not paid when the shape of what is coming is already
+ * known, which is why:
+ *
+ * - **Do not use a Spinner as a page-level loading state where the layout is
+ *   known.** A first paint of Skeletons is a better answer, and
+ *   `Skeleton` is the Component for it. A Spinner alone in the middle of an
+ *   empty page tells the reader nothing about the page they are about to get.
+ * - **Do not use a Spinner for a task of known length.** A countable upload
+ *   is a `Progress`, and a bar that shows real information beats a ring that
+ *   shows anxiety.
+ * - **Do not use a Spinner for a wait under about a second.** A control that
+ *   disables itself for 400ms and then re-enables is a control that flickers.
+ *   A `Skeleton` that never gets to paint, or nothing at all, is quieter.
+ * - **Do not use a Spinner inside a Button next to a label that already says
+ *   what is happening.** The label is the announcement; the ring is the
+ *   confirmation, and beside a label that already reads "Saving..." it is a
+ *   second copy of a sentence the reader can already see.
+ *
+ * **It is a server Component.** It reads its props and renders, so the client
+ * directive would be a claim about work this Component does not do. A hundred
+ * spinners on a page cost no JavaScript.
+ */
+function Spinner({ className, label, size = 'default', ...props }) {
+    return (_jsx("span", { "data-slot": "spinner", 
+        // The role is what makes the label legal, and the reason is the same one
+        // `LiveRegion` gives: a `span` with no role has no accessible name, so
+        // `aria-label` on one is prohibited rather than merely ignored. `status`
+        // is also the honest role, because a spinner is content that reports a
+        // state and is not waiting for the reader. It is deliberately NOT
+        // `aria-busy`: a busy *region* is still readable, and which regions are
+        // busy is the caller's knowledge rather than this Component's, so a
+        // consumer that wants it wraps the region in a `LiveRegion` and sets
+        // `busy` there.
+        role: "status", "aria-label": label, className: cn('inline-flex shrink-0', className), ...props, children: _jsx("span", { "data-slot": "spinner-ring", "aria-hidden": "true", className: cn('border-current animate-spin rounded-full border-transparent border-t-current', RING[size]) }) }));
+}
+export { Spinner };

package/dist/components/ui/split-button.d.ts

@@ -0,0 +1,207 @@
+import type { ReactNode } from 'react';
+/**
+ * One command in the split button's menu.
+ *
+ * Data rather than a slot, because a menu is a list and a slot in a list is an
+ * array a caller has to build by hand. The `id` is the caller's own identity for
+ * the command and never the label, for the reason every keyed list in this
+ * package says: labels are localised, and a menu keyed on a localised label
+ * remounts the row the moment the reader changes language.
+ */
+export type SplitButtonAction = {
+    /**
+     * The caller's own identity for the command.
+     *
+     * Required, and stable across renders. It is what `onSecondaryAction` reports,
+     * so it is the caller's handle on the command rather than a key the Component
+     * invented.
+     */
+    id: string;
+    /**
+     * The command's label, read in place in the menu.
+     *
+     * A `ReactNode`, so a caller can put an emphasis or an icon inside it. Every
+     * word in it is the caller's; Prism ships none.
+     */
+    label: ReactNode;
+    /**
+     * The mark for the command.
+     *
+     * A `ReactNode` and not an icon name, because the vocabulary a product uses for
+     * its own commands is its own. Pass an `svg` or an `img` and keep it
+     * `aria-hidden`, because `label` already names the row.
+     */
+    icon?: ReactNode;
+    /**
+     * How the menu row reads.
+     *
+     * `danger` and not `destructive`, so a consumer's tone and this package's tone
+     * stay two vocabularies. It applies to the menu row only: the cap is the menu
+     * trigger and the dominant action is a `Button`, and neither takes a tone from
+     * here, because a destructive menu row beside a destructive dominant action is
+     * one claim rather than two.
+     */
+    tone?: 'default' | 'danger';
+    /** Whether the command refuses the press. */
+    disabled?: boolean;
+};
+/**
+ * The props the Split button accepts.
+ *
+ * A declared interface rather than a forwarded native one: the Component draws a
+ * group and two controls, so there is no single native element to forward to, and
+ * a forwarded `onClick` would be a fourth way to say what the dominant action
+ * does alongside `onPrimaryAction`.
+ */
+export interface SplitButtonProps {
+    /**
+     * The accessible name of the joined group.
+     *
+     * Required, because a group of two buttons is announced as two buttons and
+     * nothing else, and a reader who tabs into one of the split buttons on a page
+     * carrying three of them cannot tell which they are in. This is `ButtonGroup`'s
+     * own requirement and it is passed straight through, so the name describes the
+     * pair rather than either half of it.
+     */
+    label: string;
+    /**
+     * The dominant action's visible label.
+     *
+     * Required and a `ReactNode`, because a caller may need an emphasis or an icon
+     * inside it. "Save", "Publish", "Export". The Component takes no default: this
+     * is the word a reader presses, and four products in at least two languages
+     * cannot all be told what it says.
+     */
+    primaryLabel: ReactNode;
+    /**
+     * The menu trigger's accessible name.
+     *
+     * Required, and the reason is the same one `Toast` states for its close
+     * control. The trigger is an icon, and an icon a reader reaches towards has to
+     * say what it is before they press it. "More actions", "Other options". It is
+     * a name rather than a visible label because the trigger is a chevron and a
+     * chevron is not a word.
+     */
+    menuLabel: string;
+    /**
+     * The commands in the menu, in the order the reader walks them.
+     *
+     * Required and a list rather than a slot, because the menu is what the trigger
+     * opens and an empty menu is a control that lies: a split button with no
+     * commands here draws its trigger as unavailable rather than opening a surface
+     * with nothing in it. The order is the caller's, because an order is a claim
+     * about how often each command is used.
+     */
+    actions: readonly SplitButtonAction[];
+    /**
+     * Runs the dominant action.
+     *
+     * Required. Prism does not know what saving, publishing or exporting means to
+     * the caller, so it neither performs the work nor holds a promise about it.
+     * Nothing here disables itself after the press: the caller owns the request,
+     * and a caller who wants the control to refuse a second press composes
+     * `LifecycleButton` for the dominant half and this for the menu.
+     */
+    onPrimaryAction: () => void;
+    /**
+     * Called with the `id` of the command chosen from the menu.
+     *
+     * One callback for the whole menu rather than one per command, so the caller's
+     * handler is a single dispatch over its own data instead of a set of closures
+     * rebuilt on every render. It fires before the menu closes and carries no
+     * label, because a label is a word Prism cannot translate for the caller.
+     */
+    onSecondaryAction: (id: string) => void;
+    /**
+     * The fill the dominant action is drawn in.
+     *
+     * Three and not four, and `outline` is the default because it is the one that
+     * makes the pair read as a single shape: the menu trigger keeps the frame
+     * `DropdownMenuTrigger` already draws, which is an outlined one, so an outlined
+     * dominant action is literally the same button as the cap beside it. See the
+     * JSDoc on the Component for why the cap is not restyled to match.
+     *
+     * @defaultValue 'outline'
+     */
+    variant?: 'outline' | 'default' | 'destructive';
+    /**
+     * Whether the whole group refuses interaction.
+     *
+     * Set on the menu rather than drawn, for the reason the JSDoc states in full:
+     * the menu already owns a disabled state and reimplementing it would be a
+     * second menu trigger. The dominant action is drawn as unavailable instead of
+     * natively disabled, because it is a control whose press this Component can
+     * simply decline.
+     */
+    disabled?: boolean;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * One dominant action and a menu, joined as a single shape.
+ *
+ * **The split is a boundary, and a boundary has a focus contract of its own.**
+ * That is the whole of this Component. The dominant action is one tab stop and
+ * the menu trigger is another, so the reader reaches the control twice and knows
+ * both times that they are still inside one thing; and the two halves are drawn
+ * as one shape, because a `Button` beside a `DropdownMenuTrigger` is two controls
+ * that happen to be near each other. `ButtonGroup` already owns the first half of
+ * that claim and `DropdownMenu` already owns the second, and this is the
+ * composition, so neither is redrawn: the joined frame, the single ring drawn
+ * around the pair and the collapsed inner borders are `ButtonGroup`'s, and the
+ * menu, its typeahead and its Escape handling are `DropdownMenu`'s.
+ *
+ * **Why this is a Component and not a call site, which is the question every
+ * audited upstream variant had to answer.** The composition is three lines, so the
+ * honest case cannot be that it is impossible to write. It is that the boundary
+ * carries three decisions a caller gets wrong in the same direction every time,
+ * and none of the three has anywhere to live but a Component:
+ *
+ * 1. **The cap's frame.** The trigger's frame is `DropdownMenuTrigger`'s, and
+ *    that Component may not be restyled from here: doing so is the override path
+ *    this package does not have. So the cap stays outlined whatever the dominant
+ *    action is, and a caller who wants the cap filled has to write a second menu
+ *    trigger, which is a second focus contract for one control. Publishing
+ *    `capTone` would not fix this; it would be a two-member union whose members
+ *    mean "the menu trigger" and "not the menu trigger", which is a boolean with
+ *    a vocabulary attached to it.
+ * 2. **The step.** The cap's height is the trigger's, and the trigger takes no
+ *    height prop. So there is no `size` here at all: a `size` a caller could
+ *    forward to one half and not the other is a joined group with a notch in it,
+ *    and a notch is the one thing a joined group may not have. Refusing the prop
+ *    is a smaller surface than documenting the trap.
+ * 3. **The three names.** `ButtonGroup` requires a name for the pair and the
+ *    trigger requires a name for itself, so the composition has two mandatory
+ *    accessible names describing one control, supplied on two unrelated
+ *    Components, with nothing tying them together. A caller who forgets the
+ *    trigger's produces a chevron announced as "button", which is the defect this
+ *    gate exists to catch and which no prop combination can catch.
+ *
+ * **The honest cost of the cap, stated rather than restyled away.** The two halves
+ * do not always match, because only one of them may be restyled. With
+ * `variant="default"` or `variant="destructive"` the dominant action is filled and
+ * the cap is outlined, and the group is two-tone. That is a real visual cost and
+ * it is not fixed here on purpose: the fix is a second menu trigger. A caller who
+ * wants one filled shape across both halves needs an upstream request, and
+ * `CONTRIBUTING.md` is where it goes.
+ *
+ * **The second cost is JavaScript, and it is paid by a page that may never open
+ * the menu.** `ButtonGroup` is a server Component and `DropdownMenu` is not, so
+ * composing the two makes this one client Component. A static page whose dominant
+ * action is the only thing it offers pays for a menu it might never open. That is
+ * the price of a menu, and a caller who has no menu to offer composes
+ * `ButtonGroup` and a `Button` instead, which is the arrangement this Component
+ * is not for.
+ *
+ * **An unavailable dominant action is drawn rather than removed, and an
+ * unavailable trigger is the menu's own.** The asymmetry is deliberate and it is
+ * not smoothed over. The dominant action's press this Component can decline
+ * outright, so it carries `aria-disabled`, keeps its place in the tab order and
+ * keeps its half of the shape. The trigger's open state belongs to
+ * `DropdownMenu`, and asking that Component for a drawn-unavailable state would
+ * mean reimplementing the control, so `disabled` goes to the menu and the
+ * trigger takes the state it already had.
+ */
+declare function SplitButton({ label, primaryLabel, menuLabel, actions, onPrimaryAction, onSecondaryAction, variant, disabled, className, }: SplitButtonProps): import("react").JSX.Element;
+export { SplitButton };
+//# sourceMappingURL=split-button.d.ts.map

package/dist/components/ui/split-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-button.d.ts","sourceRoot":"","sources":["../../../src/components/ui/split-button.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAYtC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;OAKG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACrC;;;;;;;;OAQG;IACH,eAAe,EAAE,MAAM,IAAI,CAAA;IAC3B;;;;;;;OAOG;IACH,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;IAC/C;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,YAAY,EACZ,SAAS,EACT,OAAO,EACP,eAAe,EACf,iBAAiB,EACjB,OAAmB,EACnB,QAAgB,EAChB,SAAS,GACV,EAAE,gBAAgB,+BAkClB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}