@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/radio-group/radio-group.stories.tsx

@@ -0,0 +1,251 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { action } from "storybook/actions";
+import { Button } from "../../components";
+import { Field } from "../field/field";
+import {
+  RadioGroup,
+  RadioGroupRoot,
+  RadioIndicator,
+  RadioRoot,
+} from "./radio-group";
+
+/**
+ * RadioGroup manages single-selection across a set of radio buttons.
+ * Exactly one item can be selected at a time. Built on
+ * `@base-ui/react/radio-group` and `@base-ui/react/radio`.
+ *
+ * Designed to be used inside `Field` — `Field` provides the label, description,
+ * and error handling. Pass `name` to both `Field` (for server-error routing)
+ * and `RadioGroup` (for native `FormData`).
+ *
+ * **90% case** — pass `items` and let the composite render all radio buttons:
+ * ```tsx
+ * <RadioGroup
+ *   name="plan"
+ *   items={[{ value: "free", label: "Free" }, { value: "pro", label: "Pro" }]}
+ *   onValueChange={(value) => console.log(value)}
+ * />
+ * ```
+ *
+ * **Compound API** for custom layouts:
+ * - `RadioGroup` — group wrapper with value management and a11y fieldset
+ * - `RadioGroup.Item` — labeled radio button for use inside `RadioGroup`
+ * - `RadioGroup.Legend` — optional fieldset legend when extra semantic grouping is needed
+ *
+ * Use `onValueChange` to react to selection changes.
+ *
+ * `controlFirst` (default `true`) places the radio before the label on all
+ * `RadioGroup.Item` children via context.
+ *
+ * Reference: [Radio – Base UI](https://base-ui.com/react/components/radio)
+ */
+const meta: Meta<typeof RadioGroup> = {
+  title: "Components/RadioGroup",
+  component: RadioGroup,
+  parameters: { layout: "centered" },
+  args: {
+    legend: "Preferred contact",
+  },
+  argTypes: {
+    children: { control: false },
+    items: { control: false },
+    onValueChange: { control: false },
+  },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof RadioGroup>;
+
+const CONTACT_ITEMS = [
+  { value: "email", label: "Email" },
+  { value: "sms", label: "SMS" },
+  { value: "push", label: "Push notifications" },
+];
+
+export const Default: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} defaultValue="email" />
+  ),
+};
+
+/**
+ * Wrap `RadioGroup` with `Field` to add a label, description, and error handling.
+ * Pass `name` to both — `Field` uses it for server-error routing, `RadioGroup`
+ * uses it for native `FormData`.
+ */
+export const WithDescription: Story = {
+  render: ({ legend, ...args }) => (
+    <Field
+      label={legend}
+      description="We'll only contact you using this method."
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} defaultValue="email" />
+    </Field>
+  ),
+};
+
+/**
+ * Pass `error` to `Field` — the error message renders below the group and
+ * all `RadioGroup.Item` children receive `aria-invalid` (red borders).
+ * `description` is hidden while the field is invalid.
+ */
+export const WithError: Story = {
+  render: ({ legend, ...args }) => (
+    <Field
+      label={legend}
+      invalid
+      description="This text is hidden while error is present."
+      error="Please select a contact method."
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} />
+    </Field>
+  ),
+};
+
+/**
+ * `controlFirst={false}` places the label before the radio button.
+ * Default is `true` (radio → label). Applied to all items via context.
+ */
+export const LabelFirst: Story = {
+  render: (args) => (
+    <RadioGroup
+      {...args}
+      items={CONTACT_ITEMS}
+      controlFirst={false}
+      defaultValue="email"
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} disabled defaultValue="email" />
+  ),
+};
+
+/**
+ * `readOnly` prevents selection changes while keeping the group focusable
+ * for keyboard navigation. Unlike `disabled`, it does not apply opacity.
+ */
+export const ReadOnly: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} readOnly defaultValue="email" />
+  ),
+};
+
+/**
+ * Use `value` + `onValueChange` for controlled mode.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState("email");
+    return (
+      <RadioGroup
+        {...args}
+        items={CONTACT_ITEMS}
+        value={value}
+        onValueChange={setValue}
+      />
+    );
+  },
+};
+
+/**
+ * Base UI injects a hidden `<input type="radio">` per item so `name` and
+ * `required` work with native `FormData` — no extra wiring needed.
+ */
+export const Required: Story = {
+  render: (args) => (
+    <form
+      className="space-y-3"
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        action("submit")(Object.fromEntries(data));
+      }}
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} name="contact" required />
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+};
+
+/**
+ * Pass `items` to let the composite render all radio buttons — the 90% case.
+ * Each item supports `value`, `label`, and an optional `disabled` flag for
+ * per-item control independent of the group `disabled` prop.
+ */
+export const WithItems: Story = {
+  render: (args) => (
+    <RadioGroup
+      {...args}
+      defaultValue="email"
+      items={[
+        { value: "email", label: "Email" },
+        { value: "sms", label: "SMS" },
+        { value: "push", label: "Push notifications", disabled: true },
+      ]}
+    />
+  ),
+};
+
+/**
+ * `RadioGroup.Legend` can be placed as a direct child instead of the `legend`
+ * prop when you need custom styling or want to visually hide it with `sr-only`.
+ *
+ * ```tsx
+ * <RadioGroup>
+ *   <RadioGroup.Legend className="sr-only">Contact</RadioGroup.Legend>
+ *   <RadioGroup.Item value="email" label="Email" />
+ * </RadioGroup>
+ * ```
+ */
+export const ComposableLegend: Story = {
+  render: () => (
+    <RadioGroup defaultValue="email">
+      <RadioGroup.Legend className="text-base font-semibold">
+        Preferred contact method
+      </RadioGroup.Legend>
+      <RadioGroup.Item value="email" label="Email" />
+      <RadioGroup.Item value="sms" label="SMS" />
+      <RadioGroup.Item value="push" label="Push notifications" />
+    </RadioGroup>
+  ),
+};
+
+/**
+ * Direct composition with primitives for full structural control.
+ * Use when the composite layout is not enough — custom ordering,
+ * extra elements between items, or non-standard layouts.
+ *
+ * ```tsx
+ * <RadioGroupRoot name="plan">
+ *   <RadioRoot value="pro">
+ *     <RadioIndicator />
+ *   </RadioRoot>
+ * </RadioGroupRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <RadioGroupRoot name="plan" defaultValue="pro">
+      <div className="flex flex-col gap-2">
+        {(["free", "pro", "enterprise"] as const).map((plan) => (
+          <div key={plan} className="flex items-center gap-2">
+            <RadioRoot id={`primitive-${plan}`} value={plan}>
+              <RadioIndicator />
+            </RadioRoot>
+            <label
+              htmlFor={`primitive-${plan}`}
+              className="select-none text-sm capitalize"
+            >
+              {plan}
+            </label>
+          </div>
+        ))}
+      </div>
+    </RadioGroupRoot>
+  ),
+};

package/src/components/radio-group/radio-group.test.tsx

@@ -0,0 +1,175 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Field } from "../../components";
+import {
+  RadioGroup,
+  RadioGroupPrimitive,
+  RadioGroupRoot,
+  RadioIndicator,
+  RadioPrimitive,
+  RadioRoot,
+} from "./radio-group";
+
+const items = [
+  { value: "a", label: "Option A" },
+  { value: "b", label: "Option B" },
+  { value: "c", label: "Option C", disabled: true },
+];
+
+describe("RadioGroup primitives", () => {
+  it("RadioGroupRoot renders with data-slot='radio-group'", () => {
+    render(<RadioGroupRoot />);
+    expect(document.querySelector('[data-slot="radio-group"]')).toBeTruthy();
+  });
+
+  it("RadioRoot renders with data-slot='radio'", () => {
+    render(
+      <RadioGroupRoot>
+        <RadioRoot value="a">
+          <RadioIndicator />
+        </RadioRoot>
+      </RadioGroupRoot>,
+    );
+    expect(document.querySelector('[data-slot="radio"]')).toBeTruthy();
+  });
+
+  it("RadioIndicator renders with data-slot='radio-indicator'", () => {
+    render(
+      <RadioGroupRoot>
+        <RadioRoot value="a">
+          <RadioIndicator keepMounted />
+        </RadioRoot>
+      </RadioGroupRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="radio-indicator"]'),
+    ).toBeTruthy();
+  });
+});
+
+describe("RadioGroup composite", () => {
+  it("renders items from items array", () => {
+    render(<RadioGroup items={items} />);
+    expect(screen.getByRole("radio", { name: "Option A" })).toBeTruthy();
+    expect(screen.getByRole("radio", { name: "Option B" })).toBeTruthy();
+  });
+
+  it("renders legend", () => {
+    render(<RadioGroup items={items} legend="Choose one" />);
+    expect(screen.getByText("Choose one")).toBeTruthy();
+  });
+
+  it("marks defaultValue as checked", () => {
+    render(<RadioGroup items={items} defaultValue="b" />);
+    expect(screen.getByRole("radio", { name: "Option B" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+
+  it("fires onValueChange when selection changes", async () => {
+    const onValueChange = vi.fn();
+    render(<RadioGroup items={items} onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("radio", { name: "Option A" }));
+    expect(onValueChange).toHaveBeenCalledWith("a", expect.anything());
+  });
+
+  it("reflects controlled value", () => {
+    render(<RadioGroup items={items} value="a" onValueChange={vi.fn()} />);
+    expect(screen.getByRole("radio", { name: "Option A" })).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+
+  it("disables specific item", () => {
+    render(<RadioGroup items={items} />);
+    expect(screen.getByRole("radio", { name: "Option C" })).toHaveAttribute(
+      "data-disabled",
+    );
+  });
+
+  it("disables all items when disabled prop is set", () => {
+    render(<RadioGroup items={items} disabled />);
+    for (const radio of screen.getAllByRole("radio")) {
+      expect(radio).toHaveAttribute("data-disabled");
+    }
+  });
+
+  it("renders children slot when items not provided", () => {
+    render(
+      <RadioGroup>
+        <RadioGroupRoot>
+          <RadioRoot value="x">
+            <RadioIndicator />
+          </RadioRoot>
+        </RadioGroupRoot>
+      </RadioGroup>,
+    );
+    expect(document.querySelector('[data-slot="radio"]')).toBeTruthy();
+  });
+});
+
+describe("RadioGroup.Item", () => {
+  it("renders with label", () => {
+    render(
+      <RadioGroupRoot>
+        <RadioGroup.Item value="x" label="My Option" />
+      </RadioGroupRoot>,
+    );
+    expect(screen.getByText("My Option")).toBeTruthy();
+  });
+
+  it("associates radio with label via htmlFor", () => {
+    render(
+      <RadioGroupRoot>
+        <RadioGroup.Item value="x" label="My Option" />
+      </RadioGroupRoot>,
+    );
+    expect(screen.getByRole("radio", { name: "My Option" })).toBeTruthy();
+  });
+});
+
+describe("RadioGroup.Legend", () => {
+  it("renders children as legend", () => {
+    render(
+      <RadioGroupRoot>
+        <RadioGroup.Legend>Group Title</RadioGroup.Legend>
+      </RadioGroupRoot>,
+    );
+    expect(screen.getByText("Group Title")).toBeTruthy();
+  });
+});
+
+describe("RadioGroup controlFirst", () => {
+  it("applies flex-row-reverse when controlFirst=false", () => {
+    render(
+      <RadioGroup items={[{ value: "a", label: "A" }]} controlFirst={false} />,
+    );
+    const row = document.querySelector(".flex-row-reverse");
+    expect(row).toBeTruthy();
+  });
+});
+
+describe("RadioGroup Field integration", () => {
+  it("renders inside a Field without error", () => {
+    expect(() =>
+      render(
+        <Field name="preference">
+          <RadioGroup items={[{ value: "a", label: "A" }]} />
+        </Field>,
+      ),
+    ).not.toThrow();
+  });
+});
+
+describe("RadioGroup exports", () => {
+  it("exports RadioGroupPrimitive", () => {
+    expect(RadioGroupPrimitive).toBeDefined();
+  });
+
+  it("exports RadioPrimitive", () => {
+    expect(RadioPrimitive).toBeDefined();
+  });
+});

package/src/components/radio-group/radio-group.tsx

@@ -0,0 +1,214 @@
+"use client";
+
+import { Field as FieldBase } from "@base-ui/react/field";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
+import { createContext, type ReactNode, useContext, useId } from "react";
+import { cn } from "../../lib";
+import {
+  FieldLegend,
+  FieldSet,
+  FieldValidity,
+  useFieldName,
+  useIsInsideFieldRoot,
+} from "../field/field";
+import { Label } from "../label";
+
+// ── Primitives ─────────────────────────────────────────────────────────────────
+
+export function RadioGroupRoot({
+  className,
+  ...props
+}: RadioGroupPrimitive.Props) {
+  return (
+    <RadioGroupPrimitive
+      className={cn("grid w-full gap-2", className)}
+      data-slot="radio-group"
+      {...props}
+    />
+  );
+}
+
+export function RadioRoot({ className, ...props }: RadioPrimitive.Root.Props) {
+  return (
+    <RadioPrimitive.Root
+      className={cn(
+        "peer relative inline-flex size-4.5 shrink-0 items-center justify-center rounded-full border border-input bg-background not-dark:bg-clip-padding shadow-xs/5 outline-none ring-ring transition-shadow",
+        "before:pointer-events-none before:absolute before:inset-0 before:rounded-full",
+        "not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)]",
+        "focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "aria-invalid:border-error focus-visible:aria-invalid:border-error focus-visible:aria-invalid:ring-error",
+        "data-disabled:cursor-not-allowed data-disabled:opacity-64",
+        "sm:size-4",
+        "dark:not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+        "[[data-disabled],[data-checked],[aria-invalid]]:shadow-none",
+        "data-checked:border-primary data-checked:bg-primary",
+        className,
+      )}
+      data-slot="radio"
+      {...props}
+    />
+  );
+}
+
+export function RadioIndicator({
+  className,
+  children,
+  ...props
+}: RadioPrimitive.Indicator.Props) {
+  return (
+    <RadioPrimitive.Indicator
+      className={cn("flex size-full items-center justify-center", className)}
+      data-slot="radio-indicator"
+      {...props}
+    >
+      {children ?? (
+        <span className="size-2 rounded-full bg-primary-foreground" />
+      )}
+    </RadioPrimitive.Indicator>
+  );
+}
+
+// ── Group context ──────────────────────────────────────────────────────────────
+
+const RadioGroupContext = createContext<{
+  controlFirst: boolean;
+  invalid: boolean;
+}>({
+  controlFirst: true,
+  invalid: false,
+});
+
+// ── Composite: RadioGroup.Item ─────────────────────────────────────────────────
+
+export interface RadioItemProps
+  extends Omit<RadioPrimitive.Root.Props, "children"> {
+  label: ReactNode;
+}
+
+function RadioGroupItem({ className, label, id, ...props }: RadioItemProps) {
+  const { controlFirst, invalid } = useContext(RadioGroupContext);
+  const generatedId = useId();
+  const idToUse = id ?? generatedId;
+
+  return (
+    <FieldBase.Root invalid={invalid}>
+      <div
+        className={cn(
+          "flex select-none items-center gap-x-2",
+          !controlFirst && "flex-row-reverse justify-end",
+        )}
+      >
+        <RadioRoot id={idToUse} className={className} {...props}>
+          <RadioIndicator />
+        </RadioRoot>
+        <Label htmlFor={idToUse}>{label}</Label>
+      </div>
+    </FieldBase.Root>
+  );
+}
+
+// ── Composite: RadioGroup.Legend ───────────────────────────────────────────────
+
+export interface RadioGroupLegendProps {
+  children: ReactNode;
+  className?: string;
+}
+
+function RadioGroupLegend({ children, className }: RadioGroupLegendProps) {
+  return <FieldLegend className={className}>{children}</FieldLegend>;
+}
+
+// ── Composite: RadioGroup ──────────────────────────────────────────────────────
+
+export interface RadioOption {
+  value: string;
+  label: ReactNode;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  legend?: ReactNode;
+  children?: ReactNode;
+  items?: RadioOption[];
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (value: string) => void;
+  disabled?: boolean;
+  required?: boolean;
+  readOnly?: boolean;
+  controlFirst?: boolean;
+  className?: string;
+  name?: string;
+  form?: string;
+}
+
+function RadioGroupComposite({
+  legend,
+  children,
+  items,
+  defaultValue,
+  value,
+  onValueChange,
+  disabled,
+  required,
+  readOnly,
+  controlFirst = true,
+  className,
+  name: nameProp,
+  form,
+}: RadioGroupProps) {
+  const fieldName = useFieldName();
+  const isInsideField = useIsInsideFieldRoot();
+  const name = nameProp ?? fieldName;
+
+  const renderGroup = (invalid: boolean) => (
+    <RadioGroupContext.Provider value={{ controlFirst, invalid }}>
+      <RadioGroupPrimitive
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onValueChange}
+        disabled={disabled}
+        required={required}
+        readOnly={readOnly}
+        name={name}
+        form={form}
+      >
+        <FieldSet className={className}>
+          {legend && <RadioGroupLegend>{legend}</RadioGroupLegend>}
+          <div className="flex flex-col gap-2">
+            {items
+              ? items.map((item) => (
+                  <RadioGroupItem
+                    key={item.value}
+                    value={item.value}
+                    label={item.label}
+                    disabled={item.disabled}
+                  />
+                ))
+              : children}
+          </div>
+        </FieldSet>
+      </RadioGroupPrimitive>
+    </RadioGroupContext.Provider>
+  );
+
+  if (!isInsideField) return renderGroup(false);
+
+  return (
+    <FieldValidity>
+      {({ validity }) => renderGroup(validity.valid === false)}
+    </FieldValidity>
+  );
+}
+
+// ── Compound export ────────────────────────────────────────────────────────────
+
+export const RadioGroup = Object.assign(RadioGroupComposite, {
+  Item: RadioGroupItem,
+  Legend: RadioGroupLegend,
+});
+
+// ── Primitive escape hatch ─────────────────────────────────────────────────────
+
+export { RadioGroupPrimitive, RadioPrimitive };

package/src/components/scroll-area/index.ts

@@ -0,0 +1 @@
+export * from "./scroll-area.tsx";