@blakesteve/roster 4.11.0 → 4.12.0

package/README.md

@@ -628,6 +628,18 @@ Every field therefore has a second prop, **named for the element it reaches**:
 | `PasswordInput`| `className` | `inputClassName`     | —                   |
 | `Select`       | `className` | `triggerClassName`   | `optionsClassName`  |
 | `Textarea`     | `className` | `textareaClassName`  | —                   |
+| `Combobox`     | `className` | `inputClassName`     | `optionsClassName`  |
+| `CheckboxGroup`| `className` | —                    | `optionsClassName`  |
+| `RadioGroup`   | `className` | `radioClassName`     | `optionsClassName`, `optionClassName`, `labelClassName`, `optionLabelClassName`, `descriptionClassName`, `messageClassName` |
+
+`CheckboxGroup` and `RadioGroup` have no single "control" to reach, since they
+hold one per option, so `RadioGroup`'s `radioClassName` lands on every radio
+rather than on one.
+
+`CheckboxGroup`'s options container was `panelClassName`, which named a variant
+rather than the element it reaches. Both groups now use `optionsClassName`.
+`panelClassName` still works and is deprecated; pass both and the current name
+wins.
 
 `Select` is the first component with two styleable inner parts, which is the
 case the naming scheme was chosen for: `optionsClassName` reaches the popup
@@ -1003,6 +1015,56 @@ invalid — the selection is — so nothing rings the individual controls.
 A rebuild sorts the result into declaration order, which reads tidier and
 silently drops any selected value whose option has not loaded yet.
 
+### One answer, and when it should not be a menu
+
+`RadioGroup` is `CheckboxGroup`'s sibling and deliberately the same component
+with one difference: `value` is a `string` and `onChange` receives a `string`,
+because a radio group has one answer. Label, per-option `description`, helper
+text and error message are the same shape in both, so a form using both does
+not read as two libraries.
+
+What it does not carry across is the point. There is no grouped form and no
+`maxHeight`:
+
+- **`RadioGroup`** when the options are few and the reader should see all of
+  them at once. Two to about six.
+- **`Select`** past that. A radio group with enough options to need scrolling
+  is a menu that forgot to close, and shipping a scroll cap here would invite
+  exactly that.
+
+Both hold one value of the same type, so moving between them is a prop change
+rather than a rewrite.
+
+```tsx
+<RadioGroup
+  label="Who can see this squad"
+  helperText="You can change this at any time."
+  value={visibility}
+  onChange={setVisibility}
+  options={[
+    { value: "public", label: "Public", description: "Anyone can find and join it." },
+    { value: "unlisted", label: "Unlisted", description: "Only people with the link." },
+    { value: "private", label: "Private", description: "Invite only." },
+  ]}
+/>
+```
+
+`orientation="horizontal"` lays the options out in a wrapping row, for the
+short scannable set that would otherwise spend three rows of a wide form. It
+sets `aria-orientation` to match.
+
+Every radio is a 44x44 target, and the component is built so that it stays one:
+each option's box is sized to contain its own target, which is why the options
+can sit close together without a target ever reaching into its neighbor.
+
+That containment is the option's own vertical padding, and `cn` is
+tailwind-merge, so it is the one thing `optionClassName` should leave alone. A
+background, a border, a radius and horizontal padding are all safe; a `py-*`,
+a height, or a `min-h` below `44px` replaces the padding and lets the target
+escape the box. Lay the options out across with `orientation` rather than
+through `optionsClassName`, for the same reason: the horizontal spacing that
+keeps two radios 44px apart rides on that prop.
+
 ### Components that render links
 
 `Breadcrumbs` renders a plain `<a>` by default, which is right for a static
@@ -1096,6 +1158,7 @@ function App() {
 | `ErrorState`      | Error display with retry action                                             |
 | `MatchupCard`     | Head-to-head comparison card                                                |
 | `Pullquote`       | A line lifted out of prose, as `<figure>` + `<blockquote>` + `<figcaption>` |
+| `RadioGroup`      | Radio set reporting one `string`; descriptions, error, 44px targets         |
 | `Toast`           | Transient floating notice; `Toaster` + the imperative `toast` handle        |
 
 ### Organisms

package/dist/components/molecules/CheckboxGroup/CheckboxGroup.d.ts

@@ -52,7 +52,17 @@ export interface CheckboxGroupProps extends Omit<React.HTMLAttributes<HTMLFieldS
     disabled?: boolean;
     colorScheme?: React.ComponentProps<typeof Checkbox>["colorScheme"];
     /** Classes for the options' container. `className` lands on the fieldset. */
+    optionsClassName?: string;
+    /**
+     * @deprecated Use `optionsClassName`. Both work, and `optionsClassName` wins
+     * if you pass both.
+     *
+     * Renamed so this component and `RadioGroup` spell one concept one way.
+     * `panel` named a variant rather than the element it reaches, which is the
+     * rule the README states. The old name stays because it has live call sites,
+     * and swapping it outright would be a major bump for a cosmetic gain.
+     */
     panelClassName?: string;
 }
-declare const CheckboxGroup: ({ options, value, onChange, label, helperText, errorMessage, maxHeight, disabled, variant, size, columns, colorScheme, className, panelClassName, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, ...props }: CheckboxGroupProps) => import("react/jsx-runtime").JSX.Element;
+declare const CheckboxGroup: ({ options, value, onChange, label, helperText, errorMessage, maxHeight, disabled, variant, size, columns, colorScheme, className, optionsClassName, panelClassName, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, ...props }: CheckboxGroupProps) => import("react/jsx-runtime").JSX.Element;
 export { CheckboxGroup };

package/dist/components/molecules/RadioGroup/RadioGroup.d.ts

@@ -0,0 +1,128 @@
+import { default as React } from 'react';
+import { VariantProps } from 'class-variance-authority';
+import { radioGroupOptionsVariants, radioVariants } from './radio-group-variants';
+export type RadioGroupOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /** Supporting text under the option's label. */
+    description?: string;
+};
+export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue">, Pick<VariantProps<typeof radioGroupOptionsVariants>, "size">, Pick<VariantProps<typeof radioVariants>, "colorScheme"> {
+    /**
+     * A flat list. There is no grouped form, and no `maxHeight`: both exist on
+     * `CheckboxGroup` because it is the long-list control, and a radio group
+     * with enough options to need scrolling wants a `Select` instead. Shipping
+     * the affordance would invite the wrong control.
+     */
+    options: RadioGroupOption[];
+    /**
+     * The selected value, as a string rather than an array. This is the whole
+     * difference from `CheckboxGroup`: a radio group has one answer, which is
+     * the reason it exists beside one.
+     *
+     * A value matching no option selects nothing and leaves the first option as
+     * the group's tab stop, which is the correct empty state — `""` is the
+     * ordinary way to spell "not answered yet".
+     */
+    value: string;
+    onChange: (value: string) => void;
+    /** The group's name. Becomes the group's accessible name. */
+    label?: string;
+    /** Supporting text under the options. */
+    helperText?: string;
+    /**
+     * The message for an invalid selection. Implies the error state, so a caller
+     * can not color the text red and forget to say why.
+     *
+     * The message is the whole of the error state, as it is in `CheckboxGroup`'s
+     * `plain` variant: there is no panel here to repaint, and a radio is not the
+     * thing that is invalid — the answer is.
+     *
+     * One difference from `CheckboxGroup` worth knowing before you rely on it:
+     * a caller's own `aria-describedby` is REPLACED here rather than merged.
+     * `CheckboxGroup` owns a `<fieldset>` and so owns the attribute;
+     * `aria-describedby` is one of the props Headless UI controls on a
+     * `RadioGroup`, and a controlled prop is spread last. Passing one is
+     * therefore a no-op rather than an addition. `aria-invalid` is not one of
+     * Headless UI's, so a caller's survives its spread — and is then outranked
+     * by this component's own error state, which is a different thing from the
+     * token-list merge `CheckboxGroup` does for `aria-describedby`.
+     */
+    errorMessage?: string;
+    /** Disables every option, and dims the label and helper text with them. */
+    disabled?: boolean;
+    /**
+     * Which way the options run. `vertical` stacks them, `horizontal` lays them
+     * out in a wrapping row for a short, scannable set.
+     *
+     * Named for the ARIA property it sets rather than for the flex direction it
+     * produces, because it does set it: `aria-orientation` tells a screen reader
+     * which arrow keys it is being offered, and `radiogroup` supports it.
+     * Headless UI's own key handling takes all four arrows in both orientations,
+     * which is the behavior worth having and is why this only ever widens what
+     * works rather than narrowing it.
+     */
+    orientation?: "vertical" | "horizontal";
+    /**
+     * Classes for the element holding the options. `className` lands on the
+     * group itself.
+     *
+     * Use `orientation` rather than this to lay the options out across. The
+     * horizontal guarantees ride on that prop: laying them out in a row from
+     * here keeps the vertical gap, which is 0 to 4px because each option's box
+     * contains its own target down the page but not across it, and two radios
+     * closer than 44px overlap. A `grid-cols-2` passed here puts 10px of one
+     * option's label inside its neighbor's target, and leaves
+     * `aria-orientation` saying `vertical`.
+     *
+     * `Select` and `Combobox` use this name for their floating popup panel. The
+     * sense is the same, the element that holds the options, and `CheckboxGroup`
+     * spells it this way too.
+     */
+    optionsClassName?: string;
+    /**
+     * Classes for one option's box. Applied to every option.
+     *
+     * This is the hook for turning the list into cards or rows with a border.
+     * Paint freely: a background, a border, a radius and horizontal padding all
+     * leave the targets alone.
+     *
+     * The VERTICAL padding is load-bearing, and `cn` is tailwind-merge, so a
+     * `py-*` or a height passed here deletes the component's own and takes the
+     * radio's target with it. The option's padding is what puts that target
+     * inside the option's box; at `sm`, `py-0` lets it overhang the box by 14px
+     * and `py-2` by 5. Style the box, and leave its height and vertical padding
+     * to the component.
+     *
+     * Headless UI puts `data-checked` and `data-disabled` on the control rather
+     * than on this box, so style the selected and disabled states from here with
+     * a `has-` variant reaching down to it.
+     */
+    optionClassName?: string;
+    /** Classes for the radio control itself. */
+    radioClassName?: string;
+    /** Classes for the group's own label. */
+    labelClassName?: string;
+    /** Classes for each option's label. */
+    optionLabelClassName?: string;
+    /** Classes for each option's `description`. */
+    descriptionClassName?: string;
+    /** Classes for the helper text or error message under the options. */
+    messageClassName?: string;
+}
+/**
+ * A labeled, validated set of radios that reports one `string`.
+ *
+ * A molecule rather than an atom, and `CheckboxGroup` is the precedent: a
+ * component that repeats a control and wraps it in a label, help and error
+ * shell is a molecule. `Checkbox` and `Switch` are atoms because each is a
+ * single control with no shell of its own.
+ *
+ * Built on Headless UI's `RadioGroup` rather than on a `Fieldset` holding
+ * radios, because that is the primitive and it already owns the parts worth
+ * not rewriting: the roving tabindex, arrow-key navigation that wraps, and the
+ * rule that a group with nothing selected still has exactly one tab stop.
+ */
+declare const RadioGroup: ({ options, value, onChange, label, helperText, errorMessage, disabled, size, orientation, colorScheme, className, optionsClassName, optionClassName, radioClassName, labelClassName, optionLabelClassName, descriptionClassName, messageClassName, "aria-invalid": ariaInvalid, ...props }: RadioGroupProps) => import("react/jsx-runtime").JSX.Element;
+export { RadioGroup };

package/dist/components/molecules/RadioGroup/radio-group-variants.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The radio control itself.
+ *
+ * Deliberately the same shape as `checkboxVariants`: the same three sizes, the
+ * same eight color schemes, the same `--roster-control-border` hairline when
+ * unchecked and the same `-ink` token on the mark. A radio and a checkbox on
+ * one form should differ in what they mean, not in how heavy their edges look.
+ *
+ * Two things differ. `rounded-full`, and the mark is a dot rather than a
+ * glyph — it reads `currentColor`, so the `-ink` token that guarantees
+ * contrast on each fill does the work here too. There is also no `soft`
+ * variant: `Checkbox` carries eight more compound rows for one, and
+ * `CheckboxGroup` surfaces only `colorScheme` to its consumers, so this
+ * follows the group rather than the atom.
+ *
+ * The 44x44 target is built in rather than left to the consumer. Same
+ * pseudo-element technique as `Checkbox`, for the same reason and with the
+ * same two consequences: `before:` generates no layout box, so the circle
+ * keeps its exact dimensions, and the target overhangs the box on all four
+ * sides, which means an `overflow: hidden` ancestor clips it and a tightly
+ * spaced column overlaps it. The size is stated as `size-11` rather than as a
+ * negative inset per size, because `inset` on an absolutely positioned
+ * pseudo-element resolves against the PADDING box: an inset measured from each
+ * circle's outer width lands 2px short at every size, once for each 1px of
+ * border, and looks correct in the source while measuring 42.
+ */
+export declare const radioVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    checked?: boolean | null | undefined;
+    colorScheme?: "primary" | "orange" | "teal" | "purple" | "amber" | "success" | "error" | "neutral" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+/**
+ * The dot inside the circle.
+ *
+ * `bg-current` rather than a color of its own, so it inherits the `-ink` token
+ * the control resolved for whichever fill it is sitting on. Sized to roughly
+ * 40% of the circle at every size — 6/16, 8/20, 10/24 — which is where a radio
+ * reads as a radio rather than as a filled dot or a faint speck.
+ */
+export declare const radioDotVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+/**
+ * One option.
+ *
+ * The rule the spacing rests on: **an option's box contains its own target.** A
+ * 44px target that can not reach past the option it belongs to can not reach
+ * into the one beside it either, at any gap, including zero. That is what lets
+ * the gaps be small.
+ *
+ * One layout covers every case, and the arithmetic is why. The radio is
+ * `self-start`, so it sits on the label's first line, and it needs no nudge to
+ * land there: the type scale and the size scale agree at every step — 16px
+ * line-height against a 16px circle at `sm`, 20 against 20 at `md`, 24 against
+ * 24 at `lg` — so the top of the circle and the top of the first line are the
+ * same edge. The padding is then whatever closes the gap to 44,
+ * `(44 - line-height) / 2`, which puts the radio's center at exactly 22px from
+ * the row's top at every size. The target spans the row and nothing else.
+ *
+ * That single rule holds for a one-line option, an option whose label wraps,
+ * and an option with a description, which is why there is no longer a branch
+ * for the last of those. Two earlier versions had one and both were wrong in a
+ * case they did not cover: a symmetric padding let a described row's target
+ * overhang its own top edge by 2 to 6px, and centering a plain row floated the
+ * radio into the middle of a two-line label — correct for one line, visibly
+ * wrong for two, on text a consumer supplies and can not control the width of.
+ *
+ * `horizontal` applies the same rule across instead of down, where the binding
+ * constraint is width rather than height: two radios less than 44px apart
+ * overlap however tall their boxes are. `min-w-11` guarantees it even for a
+ * one-character label.
+ */
+export declare const radioOptionVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+/**
+ * The options' container.
+ *
+ * `vertical` is the default because a radio group holds one answer, and options
+ * read as alternatives to each other when they are stacked. `horizontal` is for
+ * the short scannable set, two or three one-word answers that would otherwise
+ * spend three rows of a wide form, and it wraps rather than overflowing:
+ * a row of options that runs off the side of a phone is worse than the column
+ * it replaced.
+ *
+ * There is no `columns` prop. `CheckboxGroup` has one because it is the
+ * long-list control and a filter list of twenty wants the width; a radio group
+ * with that many options wants a `Select`.
+ *
+ * The gaps are small, and can be, because each option already contains its own
+ * target and its own padding. Across, they are larger than down: a horizontal
+ * gap separates two whole options rather than two stacked rows, and at the
+ * vertical scale two options sat 0 to 4px apart and read as one control.
+ */
+export declare const radioGroupOptionsVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;

package/dist/index.d.ts

@@ -54,6 +54,8 @@ export * from './components/molecules/Pullquote/Pullquote';
 export * from './components/molecules/Pullquote/pullquote-variants';
 export * from './components/molecules/CheckboxGroup/CheckboxGroup';
 export * from './components/molecules/CheckboxGroup/checkbox-group-variants';
+export * from './components/molecules/RadioGroup/RadioGroup';
+export * from './components/molecules/RadioGroup/radio-group-variants';
 export * from './components/molecules/Breadcrumbs/Breadcrumbs';
 export * from './components/molecules/Breadcrumbs/breadcrumb-variants';
 export * from './components/molecules/CallToAction/CallToAction';

package/dist/meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.11.0",
-  "tests": 1332,
-  "testFiles": 109
+  "version": "4.12.0",
+  "tests": 1420,
+  "testFiles": 111
 }