@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/choice-card.d.ts

@@ -0,0 +1,273 @@
+import { type ChangeEventHandler, type ComponentProps, type ReactNode } from 'react';
+/**
+ * One choice in a ChoiceCard group, and every word about it.
+ *
+ * **A choice is a value and two pieces of text, and there is no fourth field.**
+ * There is no price, no badge, no illustration and no "recommended" flag, because
+ * each of those is a claim about a product this package has not seen. A card that
+ * drew a ribbon would be publishing a recommendation the consumer did not make,
+ * which is the defect the whole taxonomy refuses. A consumer who wants a price
+ * passes it as the description, because a price beside a plan is a line of the
+ * consumer's own copy, and a consumer who wants a recommendation passes their own
+ * control in the description or composes the card themselves.
+ */
+export type ChoiceCardOption = {
+    /**
+     * The value this choice contributes to the group, and the value the form
+     * submits.
+     *
+     * Required, and required as a `string` because that is what a radio's own
+     * `value` is and what a form posts. Two choices sharing a value are one choice
+     * to the browser and two to the reader, so the values must be unique inside the
+     * group, and the consumer's own keys are the right ones because they are what
+     * their store already holds.
+     */
+    value: string;
+    /**
+     * The choice's name, and the first half of the radio's accessible name.
+     *
+     * Required, and a node because a choice is often a name and a piece of emphasis,
+     * or a name and an inline figure, and a `string` prop would make a consumer
+     * reach for a wrapper element to smuggle either through. The node is also the
+     * text a sighted reader reads, which is what keeps the visible label and the
+     * announced name the same words rather than two copies of them.
+     */
+    label: ReactNode;
+    /**
+     * The supporting line under the choice: what it costs, what it covers, what
+     * committing to it means.
+     *
+     * Optional, and it is the second half of the radio's accessible name rather than
+     * a description reached separately, because it sits inside the label. See the
+     * note on `ChoiceCard` for why that is the arrangement and what it costs.
+     */
+    description?: ReactNode;
+    /**
+     * Whether this choice cannot be taken, and why the consumer decided that.
+     *
+     * Optional, and a disabled option is refused rather than drawn as enabled and
+     * ignored, and it stays in the accessibility tree so a reader is told the choice
+     * exists and is not available. A card that silently vanished is a card a reader
+     * will believe has been withdrawn.
+     */
+    disabled?: boolean;
+};
+/**
+ * How many cards sit on a row, as a closed set of three.
+ *
+ * A number rather than a Tailwind class, for the reason `ListPanel` gives about
+ * its own bound: the arrangement is a claim about the content rather than about
+ * the layout. A plan is usually a row of two or three and a region is usually a
+ * stack, and a consumer who could only write a column class would be picking one
+ * of those for the other. Three members and no more, because four cards on a row
+ * at this padding stop being readable at the measure a documentation page has.
+ */
+declare const CHOICE_CARD_COLUMNS: {
+    readonly 1: "";
+    readonly 2: "sm:grid-cols-2";
+    readonly 3: "sm:grid-cols-2 lg:grid-cols-3";
+};
+/**
+ * How many cards sit on a row.
+ *
+ * @defaultValue 1
+ */
+export type ChoiceCardColumns = keyof typeof CHOICE_CARD_COLUMNS;
+/**
+ * The props a ChoiceCard accepts.
+ *
+ * The fieldset's own props are forwarded with `children` and `onChange` removed.
+ * `children` goes because the group draws its own cards and a consumer who passed
+ * any would be reaching past the set. `onChange` goes because the group's handler
+ * is a selection report and the element's own `onChange` is a form event about the
+ * whole fieldset, which is a different thing under the same word; the selection
+ * handler is declared in this body instead, where its meaning is written down.
+ */
+export type ChoiceCardProps = {
+    /**
+     * The group's own name, drawn above the cards and announced as the group's
+     * name.
+     *
+     * Required, and required as a node because the name is content: it is often a
+     * heading with a count in it, and it is drawn as the fieldset's legend, so the
+     * element a sighted reader reads is the element a screen reader names the group
+     * by. There is no default and no generated name anywhere in this module, because
+     * a group of plans with no name is announced as an unnamed group and a reader
+     * learns nothing about what the question was. The sentence is the consumer's, in
+     * their language: "Plan", "Region", "Billing cadence".
+     */
+    label: ReactNode;
+    /**
+     * The choices, in the order a reader should meet them.
+     *
+     * Required, and order is the consumer's because which option reads first is a
+     * claim about their product rather than about this design system. A set of one
+     * is a legitimate value: a single choice with nothing to compare against is a
+     * field whose answer is fixed, and it renders as one card in a row of one.
+     */
+    options: readonly ChoiceCardOption[];
+    /**
+     * The chosen value, when the group is controlled.
+     *
+     * Optional, and paired with `onChange` in the ordinary controlled way. A value
+     * that names no option marks nothing, which is a real state and not a throw: a
+     * saved record naming an option the product has since withdrawn is the
+     * consumer's data problem, and taking the page down over it is worse than
+     * drawing a chooser with nothing selected.
+     */
+    value?: string;
+    /**
+     * The option selected initially, for a group nobody is controlling.
+     *
+     * Optional, and it is the whole of the no-JavaScript path. With this and no
+     * `onChange`, the group is a set of real radios in a real form: the browser holds
+     * the selection, the arrow keys move it, and the value is posted on submit, with
+     * no framework involved at any point. A controlled `value` with no `onChange` is
+     * a read-only group, and the browser's own warning is the honest report of it.
+     */
+    defaultValue?: string;
+    /**
+     * Called with the input's own change event when the reader takes a choice.
+     *
+     * Optional, and it is the platform's event rather than a `(value: string)`
+     * report, so `event.target.value` is the chosen value and nothing is reshaped
+     * on the way through. See the note on `ChoiceCard` for why this module is still
+     * a server Component, because that is the one place this Component departs from
+     * the package's usual rule and the departure is deliberate.
+     */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /**
+     * The form field name the chosen value is submitted under.
+     *
+     * Optional, and it is a field name rather than a label: this is the key the
+     * value arrives at on the server, and a consumer that omits it gets radios that
+     * still work, still announce and still constrain, and post nothing.
+     */
+    name?: string;
+    /**
+     * The `id` of the form that owns these radios, for a group rendered outside its
+     * own `<form>` element.
+     *
+     * Optional, and it is the same attribute a native input has, forwarded because a
+     * consumer whose chooser lives in a dialog has to say which form owns it.
+     */
+    form?: string;
+    /**
+     * Whether every choice ignores interaction.
+     *
+     * Optional, and it is put on each input rather than on the fieldset, because
+     * `<fieldset disabled>` is a second place the same state is written and the
+     * fieldset's own attribute is the browser's rather than this Component's. The
+     * visible dimming comes from the same place either way, since a card dims when
+     * the radio inside it is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether a value must be chosen before the form submits.
+     *
+     * Optional, and it is put on each input, which is how the platform expresses it:
+     * a required radio group is satisfied by any one of its members, and a form that
+     * submits without a choice is refused by the browser with a message in the
+     * reader's own language rather than by this package.
+     */
+    required?: boolean;
+    /** How many cards sit on a row. @defaultValue 1 */
+    columns?: ChoiceCardColumns;
+    /** Layout only, and the legend stays the first child of the fieldset. */
+    className?: string;
+} & Omit<ComponentProps<'fieldset'>, 'onChange' | 'children'>;
+/**
+ * A set of choices where each one is a card, and the reader takes exactly one.
+ *
+ * **It is a fieldset of real radios, and the argument for the native route is that
+ * every hard part is already solved by the platform.** A radio group has one Tab
+ * stop, arrow keys that move and choose, a checked state the platform owns, form
+ * participation, constraint validation, and a place in every browser's
+ * accessibility tree. The ARIA route, which is what `ToggleGroup` and
+ * `BillingSources` take, buys total control of the appearance and pays for it
+ * with a hidden input to submit, a roving tab stop to maintain, and a keyboard
+ * model a reader has to test rather than one the platform ships. This Component's
+ * whole subject is the appearance, and it is the one place in this package where
+ * the appearance is free and the semantics are not on offer: a card is a label
+ * around a radio, and a label is a native element.
+ *
+ * **The card is a `<label>` wrapping the radio, and that is what makes the whole
+ * card pressable.** The alternative is a 16 pixel circle with a line of text beside
+ * it, which is what `radio-group` draws, and it is right there because a radio row
+ * is a form field and a form field is compact by convention. A card is the size of
+ * a plan, a region and a cadence, and at that size a small target beside a
+ * sentence the reader also wants to press is a target a finger misses. So the
+ * label wraps the radio, the whole card is the target, and the radio's accessible
+ * name comes from the label element natively, with no generated id and nothing to
+ * keep in step. The cost is the one a wrapping label creates and it is not small:
+ * a control inside a card, a link in the description, a copy button beside the
+ * price, all of them select the radio when the reader presses them, because a
+ * label forwards the click to what it wraps. A consumer who needs an interactive
+ * element inside a choice puts that choice somewhere else.
+ *
+ * **The description is inside the label, so it is part of the name.** A screen
+ * reader announces the choice's label and then its description, in the order the
+ * reader sees them, and then the role and then its position in the group: "Team.
+ * Twelve agents, billed yearly. Radio button, 2 of 3." The rejected alternative is
+ * a description outside the label reached by `aria-describedby`, which would give
+ * a short name and a separate description, and it costs two things: an id to
+ * generate and to wire, and the whole-card hit area, because everything outside
+ * the label stops selecting. Given that the hit area is the reason this Component
+ * exists, the name carries the description. The cost is that a long description is
+ * a long name, so keep it to one line, which is the same rule the package states
+ * about a `CardDescription`.
+ *
+ * **The group is a `<fieldset>` with a `<legend>`, and it also carries
+ * `role="radiogroup"`.** The fieldset is what groups the radios and what names
+ * them, and the legend is the name. The explicit role is an addition rather than a
+ * replacement: an element with an explicit role is named by `aria-labelledby`
+ * rather than by its legend, so the legend is given an id and pointed at, and what
+ * is bought is that a screen reader announces a radio group rather than a
+ * grouping, which is the difference between a reader knowing this is one question
+ * and a reader having to infer it from six radios. The cost is stated: the name
+ * now depends on an id, so a consumer who takes the fieldset's props and replaces
+ * the legend with their own element has to carry the id, and `useId` is the reason
+ * this module still needs no `'use client'` of its own.
+ *
+ * **The selected card states its border and its indicator and not its fill, and
+ * that is a decision about competing signals.** A fill a `hover` can take over is a
+ * fill whose meaning changes under the pointer, and which of the two wins is a
+ * question about Tailwind's variant order rather than about this design system.
+ * The two things that carry selection here are the ones nothing else competes for:
+ * the radio's own dot fills, and the border takes the primary role. The cost is
+ * that a selected card is quieter than a filled one, so a consumer who wants a
+ * louder selected state adds their own `Tag` or `Badge` beside the choice, which is
+ * a claim about their product and therefore theirs to make.
+ *
+ * **The module is a server Component and it takes a function prop anyway, which is
+ * a deliberate departure from the rule the rest of this package follows.** The rule
+ * exists for a reason: a Component that *calls* a function prop during render, or
+ * that holds state the callback drives, has to be in the client graph, because a
+ * server component cannot hand a function down. This Component never calls
+ * `onChange`. It forwards it to an `<input>`, where it is an ordinary DOM handler
+ * the framework attaches at hydration, and the Component's own output is a pure
+ * function of its props with no hook, no state and no effect. `Metric` and
+ * `SearchField` are the precedents in this package for a server Component with a
+ * function prop, and the reasoning is theirs as much as this one's. The cost is
+ * real and is why it is stated: a consumer who passes `onChange` from a server
+ * file gets a build error in every framework that draws that line, and that error
+ * is correct, because a server component cannot hand an event handler down. A
+ * consumer who wants the value in their own state is already in a client module, and
+ * a consumer who does not is in a server one and gets a working radio group that
+ * ships no JavaScript at all.
+ *
+ * **It is distinct from `radio-group` and from `card`, and both differences are
+ * about the same thing.** `radio-group` is the compact form: a small circle beside
+ * a short label, one row, a form field. `card` is a surface with a title, a
+ * description, content and a footer, and it is not a control at all: it has no
+ * role, it is not focusable, and it submits nothing. This is the third thing, the
+ * one where the control and the surface are the same box, and neither of the other
+ * two can be turned into it. A `card` cannot become a choice without a role and a
+ * checked state; a `radio-group` cannot become a choice card without a label around
+ * each row and the row-sized target that brings. Composing them does not help
+ * either, because a card wrapped around a radio row is a card with a small target
+ * inside it, which is the arrangement this Component exists to replace.
+ */
+declare function ChoiceCard({ label, options, value, defaultValue, onChange, name, form, disabled, required, columns, className, ...props }: ChoiceCardProps): import("react").JSX.Element;
+export { ChoiceCard };
+//# sourceMappingURL=choice-card.d.ts.map

package/dist/components/ui/choice-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/choice-card.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAI3F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;GASG;AACH,QAAA,MAAM,mBAAmB;;;;CAIf,CAAA;AAEV;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,mBAAmB,CAAA;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACpC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;IAC/C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,iBAAS,UAAU,CAAC,EAClB,KAAK,EACL,OAAO,EACP,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,QAAgB,EAChB,QAAgB,EAChB,OAAW,EACX,SAAS,EACT,GAAG,KAAK,EACT,EAAE,eAAe,+BAqGjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/choice-card.js

@@ -0,0 +1,138 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * How many cards sit on a row, as a closed set of three.
+ *
+ * A number rather than a Tailwind class, for the reason `ListPanel` gives about
+ * its own bound: the arrangement is a claim about the content rather than about
+ * the layout. A plan is usually a row of two or three and a region is usually a
+ * stack, and a consumer who could only write a column class would be picking one
+ * of those for the other. Three members and no more, because four cards on a row
+ * at this padding stop being readable at the measure a documentation page has.
+ */
+const CHOICE_CARD_COLUMNS = {
+    1: '',
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-2 lg:grid-cols-3',
+};
+/**
+ * A set of choices where each one is a card, and the reader takes exactly one.
+ *
+ * **It is a fieldset of real radios, and the argument for the native route is that
+ * every hard part is already solved by the platform.** A radio group has one Tab
+ * stop, arrow keys that move and choose, a checked state the platform owns, form
+ * participation, constraint validation, and a place in every browser's
+ * accessibility tree. The ARIA route, which is what `ToggleGroup` and
+ * `BillingSources` take, buys total control of the appearance and pays for it
+ * with a hidden input to submit, a roving tab stop to maintain, and a keyboard
+ * model a reader has to test rather than one the platform ships. This Component's
+ * whole subject is the appearance, and it is the one place in this package where
+ * the appearance is free and the semantics are not on offer: a card is a label
+ * around a radio, and a label is a native element.
+ *
+ * **The card is a `<label>` wrapping the radio, and that is what makes the whole
+ * card pressable.** The alternative is a 16 pixel circle with a line of text beside
+ * it, which is what `radio-group` draws, and it is right there because a radio row
+ * is a form field and a form field is compact by convention. A card is the size of
+ * a plan, a region and a cadence, and at that size a small target beside a
+ * sentence the reader also wants to press is a target a finger misses. So the
+ * label wraps the radio, the whole card is the target, and the radio's accessible
+ * name comes from the label element natively, with no generated id and nothing to
+ * keep in step. The cost is the one a wrapping label creates and it is not small:
+ * a control inside a card, a link in the description, a copy button beside the
+ * price, all of them select the radio when the reader presses them, because a
+ * label forwards the click to what it wraps. A consumer who needs an interactive
+ * element inside a choice puts that choice somewhere else.
+ *
+ * **The description is inside the label, so it is part of the name.** A screen
+ * reader announces the choice's label and then its description, in the order the
+ * reader sees them, and then the role and then its position in the group: "Team.
+ * Twelve agents, billed yearly. Radio button, 2 of 3." The rejected alternative is
+ * a description outside the label reached by `aria-describedby`, which would give
+ * a short name and a separate description, and it costs two things: an id to
+ * generate and to wire, and the whole-card hit area, because everything outside
+ * the label stops selecting. Given that the hit area is the reason this Component
+ * exists, the name carries the description. The cost is that a long description is
+ * a long name, so keep it to one line, which is the same rule the package states
+ * about a `CardDescription`.
+ *
+ * **The group is a `<fieldset>` with a `<legend>`, and it also carries
+ * `role="radiogroup"`.** The fieldset is what groups the radios and what names
+ * them, and the legend is the name. The explicit role is an addition rather than a
+ * replacement: an element with an explicit role is named by `aria-labelledby`
+ * rather than by its legend, so the legend is given an id and pointed at, and what
+ * is bought is that a screen reader announces a radio group rather than a
+ * grouping, which is the difference between a reader knowing this is one question
+ * and a reader having to infer it from six radios. The cost is stated: the name
+ * now depends on an id, so a consumer who takes the fieldset's props and replaces
+ * the legend with their own element has to carry the id, and `useId` is the reason
+ * this module still needs no `'use client'` of its own.
+ *
+ * **The selected card states its border and its indicator and not its fill, and
+ * that is a decision about competing signals.** A fill a `hover` can take over is a
+ * fill whose meaning changes under the pointer, and which of the two wins is a
+ * question about Tailwind's variant order rather than about this design system.
+ * The two things that carry selection here are the ones nothing else competes for:
+ * the radio's own dot fills, and the border takes the primary role. The cost is
+ * that a selected card is quieter than a filled one, so a consumer who wants a
+ * louder selected state adds their own `Tag` or `Badge` beside the choice, which is
+ * a claim about their product and therefore theirs to make.
+ *
+ * **The module is a server Component and it takes a function prop anyway, which is
+ * a deliberate departure from the rule the rest of this package follows.** The rule
+ * exists for a reason: a Component that *calls* a function prop during render, or
+ * that holds state the callback drives, has to be in the client graph, because a
+ * server component cannot hand a function down. This Component never calls
+ * `onChange`. It forwards it to an `<input>`, where it is an ordinary DOM handler
+ * the framework attaches at hydration, and the Component's own output is a pure
+ * function of its props with no hook, no state and no effect. `Metric` and
+ * `SearchField` are the precedents in this package for a server Component with a
+ * function prop, and the reasoning is theirs as much as this one's. The cost is
+ * real and is why it is stated: a consumer who passes `onChange` from a server
+ * file gets a build error in every framework that draws that line, and that error
+ * is correct, because a server component cannot hand an event handler down. A
+ * consumer who wants the value in their own state is already in a client module, and
+ * a consumer who does not is in a server one and gets a working radio group that
+ * ships no JavaScript at all.
+ *
+ * **It is distinct from `radio-group` and from `card`, and both differences are
+ * about the same thing.** `radio-group` is the compact form: a small circle beside
+ * a short label, one row, a form field. `card` is a surface with a title, a
+ * description, content and a footer, and it is not a control at all: it has no
+ * role, it is not focusable, and it submits nothing. This is the third thing, the
+ * one where the control and the surface are the same box, and neither of the other
+ * two can be turned into it. A `card` cannot become a choice without a role and a
+ * checked state; a `radio-group` cannot become a choice card without a label around
+ * each row and the row-sized target that brings. Composing them does not help
+ * either, because a card wrapped around a radio row is a card with a small target
+ * inside it, which is the arrangement this Component exists to replace.
+ */
+function ChoiceCard({ label, options, value, defaultValue, onChange, name, form, disabled = false, required = false, columns = 1, className, ...props }) {
+    const generated = useId();
+    const legendId = `${generated}-legend`;
+    return (
+    /*
+     * A block, not a flex column, and the legend is its first child. A fieldset
+     * whose display is not `block` takes its legend out of the ordinary flow in
+     * some engines, and the legend is what names the group, so the layout is
+     * arranged on the grid below rather than on the fieldset.
+     */
+    _jsxs("fieldset", { "data-slot": "choice-card", 
+        // The role states what the set is rather than leaving a reader to infer it
+        // from six radios, and the name comes from the legend through the id
+        // because an element with an explicit role is not named by its contents.
+        role: "radiogroup", "aria-labelledby": legendId, className: cn('w-full min-w-0', className), ...props, children: [_jsx("legend", { id: legendId, "data-slot": "choice-card-legend", className: "mb-3 text-sm font-medium", children: label }), _jsx("div", { "data-slot": "choice-card-grid", className: cn('grid gap-3', CHOICE_CARD_COLUMNS[columns]), children: options.map((option) => (_jsxs("label", { "data-slot": "choice-card-option", "data-value": option.value, className: cn(
+                    // Both halves of the resting surface are stated here rather than
+                    // inherited, for the Stated Ink Rule: a fill with no ink of its own is
+                    // the same card on the page ground and a different one inside any
+                    // Block that draws a filled surface.
+                    'border-border bg-background text-foreground hover:bg-muted', 'flex cursor-pointer items-start gap-3 rounded-lg border p-4', 'transition-colors duration-fast ease-out', 'has-[:checked]:border-primary', 
+                    // The focus ring is drawn on the card rather than on the radio, so it
+                    // bounds the thing the reader is choosing instead of a small circle
+                    // inside it. The radio is `sr-only` rather than hidden, so there is no
+                    // outline to suppress on either element and the browser's own
+                    // indicator is not competing with this one.
+                    'has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-[3px]', 'has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50'), children: [_jsxs("span", { "data-slot": "choice-card-indicator", className: cn('border-input text-primary bg-background mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-full border', 'transition-colors duration-fast ease-out', 'has-[:checked]:border-primary'), children: [_jsx("input", { "data-slot": "choice-card-input", className: "peer sr-only", type: "radio", name: name, form: form, value: option.value, checked: value === undefined ? undefined : value === option.value, defaultChecked: value === undefined ? defaultValue === option.value : undefined, disabled: disabled || option.disabled === true, required: required, onChange: onChange }), _jsx("span", { "data-slot": "choice-card-dot", "aria-hidden": "true", className: "bg-primary text-primary size-2 rounded-full opacity-0 peer-checked:opacity-100" })] }), _jsxs("span", { "data-slot": "choice-card-body", className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsx("span", { "data-slot": "choice-card-label", className: "text-sm font-medium", children: option.label }), option.description === undefined ? null : (_jsx("span", { "data-slot": "choice-card-description", className: "text-muted-foreground text-sm", children: option.description }))] })] }, option.value))) })] }));
+}
+export { ChoiceCard };

package/dist/components/ui/code-block.d.ts

@@ -0,0 +1,182 @@
+import type { ComponentProps, ReactNode } from 'react';
+/** What every arm of `CodeBlockProps` carries. */
+type CodeBlockFigure = {
+    /**
+     * The source, exactly as it is in the file.
+     *
+     * A string and not a `ReactNode`, and the reason is that this is a code
+     * surface: the whole claim is that what a reader copies is what the caller
+     * holds. A `ReactNode` would be a set of elements a caller could mark up, and
+     * then the thing on the page and the thing in the clipboard are two different
+     * strings, which is the failure a code block is the last place to allow.
+     */
+    code: string;
+    /**
+     * The language, in whatever form the caller's own documentation uses it.
+     *
+     * Drawn in the header in the mono face and never read as a claim about what
+     * the code means. It is the one word that says what the syntax is, and it is
+     * also the one word that cannot be a promise: this Component does not know
+     * what `ts` is, so it draws what it was given. `tsx`, `ts`, `typescript` and
+     * `TypeScript` are all defensible in different code bases, and the value that
+     * is right is the one the caller's own pages already use.
+     */
+    language?: string;
+    /**
+     * The file the snippet is from, drawn in the header beside the language.
+     *
+     * Both are in the mono face and both are machine notation: a filename and a
+     * language tag are names in a machine's alphabet, not prose, and setting them
+     * in the sans face would make the header look like a sentence when the one
+     * thing in it that is not a sentence is the caller's actions slot. The
+     * filename also replaces the language where a snippet is one file rather than
+     * one language, so a caller can pass either and the header stays one item.
+     */
+    filename?: string;
+    /**
+     * Draws a number against each line. @defaultValue false
+     *
+     * Off by default because the numbers are the answer to a question only some
+     * readers ask, and a reader who is not in a file does not want a gutter
+     * pushing the code two characters to the right. The number is a reference, not
+     * part of the text: see the note on the gutter.
+     */
+    lineNumbers?: boolean;
+    /**
+     * Layout only, exactly as on every Component. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * The props the CodeBlock accepts.
+ *
+ * The name is a union rather than `label?: string` for the reason
+ * `DiagramProps` and `PulseGraphProps` state: only a union lets the type system
+ * see the exception. A figure whose accessible name is optional is a figure
+ * whose name a caller forgets, and here the forgetting has a cost that is easy
+ * to name: a copy control beside a figure with no name is a button whose label
+ * says "copy" and whose target is unnamed, so a screen reader user is told to
+ * copy something and then cannot find out what. So `label` is required in the
+ * arm that takes `actions` and optional in the arm that does not, and the type
+ * makes the second case impossible to reach by accident. `label?: string` on
+ * its own was the shape rejected: it is the same type as the pair above and it
+ * states none of it.
+ */
+export type CodeBlockProps = CodeBlockFigure & ({
+    /**
+     * The accessible name of the figure, and the only name the snippet has.
+     *
+     * A path, a command, the thing the snippet shows. Required whenever the
+     * caller brings a control, because a control that acts on a figure acts
+     * on something and the something has to be nameable.
+     */
+    label: string;
+    /**
+     * The caller's own controls for this figure, in the header.
+     *
+     * A slot rather than a copy button, and the reason is the copy gate's:
+     * this package ships no word a consumer cannot localise, and a copy
+     * control is the clearest case of one. A button whose label reads "Copy"
+     * in a product that never uses that word is a control the consumer
+     * cannot fix without patching the library, and the fix would be a fork
+     * rather than a prop. So the surface is drawn, the header has a place for
+     * the caller's own button, and the caller names it.
+     */
+    actions?: ReactNode;
+} | {
+    /**
+     * The accessible name of the figure. Optional here, and only here,
+     * because a snippet with no control beside it is identified by the
+     * sentence around it.
+     */
+    label?: string;
+    /** A figure with no control beside it has no slot to fill. */
+    actions?: never;
+});
+/**
+ * A snippet of source: a mono surface with a header for the words that say what
+ * it is.
+ *
+ * **Prism ships a code surface and no syntax highlighter, and that is the
+ * decision worth defending.** A highlighter is not a presentation detail, it is
+ * a dependency that arrives with its own answer to the question "what does this
+ * token mean", and it is a second source of truth for exactly the kind of thing
+ * this system is built to have one of. Prism's law is that a value is authored
+ * once and reaches a consumer through the tokens; a highlighter decides on its
+ * own that `const` is a keyword and that a string is a string, and it decides
+ * that in a vocabulary of its own, published as a theme file, styled with class
+ * names that have to be reconciled against six packs and two modes. The
+ * reconciliation is where a highlighter stops being a convenience. The moment
+ * one is in the product, the token source and the highlight theme are two files
+ * that have to be kept in step, and a pack that moves a step leaves the second
+ * one behind, and the result is a code surface in the wrong hue that every
+ * colour gate in this repository reports as correct.
+ *
+ * So nothing here is highlighted, and the cost of that is real and worth naming:
+ * a long snippet is a wall of one colour, a reader scanning for a name has no
+ * colour to catch it, and Prism gives them the table of contents instead, which
+ * is the line numbers and the filename. A caller who has decided they want
+ * highlighting composes it themselves, and the two places to do it are named on
+ * the props: `actions` takes a control the caller built, and the whole item is a
+ * plain figure with a `code` string, so anything a caller wraps around it is
+ * theirs. What Prism will not do is hold the highlighting itself, because the
+ * day it does there are two answers to what a token means in every product that
+ * installs it.
+ *
+ * **The figure is named by `label`, and the naming is required whenever the
+ * caller brings a control.** See the union on `CodeBlockProps`: a copy button
+ * beside an unnamed figure is a button that acts on nothing a reader can
+ * identify. When the caller brings no control the name is optional, because a
+ * snippet inside a sentence is identified by the sentence.
+ *
+ * **The line numbers are a gutter, not part of the text.** They sit outside the
+ * `<pre>`, hidden from assistive technology, and the code inside the `<pre>` is
+ * the caller's `code` and nothing else. That is what keeps a copy clean: a copy
+ * that carries `1  2  3` down its left edge is a snippet pasted into a file
+ * that does not compile, and the alternative, numbers inside the `<pre>`, is
+ * exactly that. The cost of the gutter is alignment, because two parallel
+ * renderings of the same lines line up only while the lines do not wrap, which
+ * is why the body is `whitespace-pre` and scrolls horizontally. A snippet that
+ * soft-wrapped would put the numbers a line out of step after the first long
+ * line, and horizontal scroll is the honest answer: source is read by the line
+ * and not reflowed to the viewport.
+ *
+ * **It spreads no other prop.** `Kbd` and `Separator` spread a native element's
+ * props because there is no other route to them. A `<pre>` is a different case,
+ * and the reason is specific: a code surface is the one place in a component
+ * library where a caller might reasonably reach for `dangerouslySetInnerHTML`,
+ * because highlighting is usually done that way and this file has just argued
+ * against highlighting. A spread would hand them the attribute that bypasses
+ * every claim on the page in one prop, so the surface is `code`, `language`,
+ * `filename`, `lineNumbers`, `actions`, `label` and `className`, and nothing
+ * else.
+ *
+ * **The header is a header, and it is not always there.** It is drawn when
+ * there is something to put in it: a filename, a language, or a control. A
+ * snippet with no filename, no language and no control is a tinted box of
+ * monospace, and an empty strip above it would be a bar of ink saying nothing.
+ */
+declare function CodeBlock({ code, language, filename, lineNumbers, actions, label, className, }: CodeBlockProps): import("react").JSX.Element;
+/**
+ * An inline run of source: a symbol, a command, a filename, a prop.
+ *
+ * The inline form of the same idea `CodeBlock` states at length, and the reason
+ * it is its own export rather than a size of the block is that the two answer
+ * different questions. A `CodeBlock` is something a reader may copy, so it is a
+ * figure with a name, a header and a gutter. A `Code` is a word inside a
+ * sentence, and the whole treatment is that it is visibly not prose: the mono
+ * face is the signal, and the muted surface is what stops a long symbol from
+ * reading as a run of emphasised text.
+ *
+ * Use it for a symbol the reader types (`--strict`), a component or a function
+ * name (`ChartFrame`), a file (`dialog.tsx`), a prop (`tone`) or a command. Do
+ * not use it for a value that is a number with a unit, for a key the reader
+ * presses, which is `Kbd`, or for anything the reader is meant to remember as
+ * prose. It renders a native `<code>`, so a screen reader identifies it as
+ * source rather than as text to read through, and it spreads a `<code>`'s own
+ * props because that is the only route to a title, a `lang` or an `id` on one.
+ */
+declare function Code({ className, ...props }: ComponentProps<'code'>): import("react").JSX.Element;
+export { CodeBlock, Code };
+//# sourceMappingURL=code-block.d.ts.map

package/dist/components/ui/code-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-block.d.ts","sourceRoot":"","sources":["../../../src/components/ui/code-block.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD,kDAAkD;AAClD,KAAK,eAAe,GAAG;IACrB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAC1C,CACI;IACE;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,GACD;IACE;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB,CACJ,CAAA;AAkBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,iBAAS,SAAS,CAAC,EACjB,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,WAAmB,EACnB,OAAO,EACP,KAAK,EACL,SAAS,GACV,EAAE,cAAc,+BA4FhB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,MAAM,CAAC,+BAW5D;AAED,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAA"}