@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.15

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

@@ -1,22 +1,51 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
+import { Button } from "../button/button";
 import { Checkbox } from "../checkbox";
-import { CheckboxGroup } from "./checkbox-group";
+import { Field } from "../field/field";
+import { Form } from "../form/form";
+import { CheckboxGroup, CheckboxGroupRoot } from "./checkbox-group";
 
 /**
- * CheckboxGroup manages a set of `Checkbox` components as a single value
- * (`string[]`). Each child `Checkbox` must receive a `value` prop to be
- * tracked by the group.
+ * CheckboxGroup manages a set of checkboxes as a single `string[]` value.
+ * Built on `@base-ui/react/checkbox-group`.
  *
- * Use `defaultValue` for uncontrolled mode or `value` + `onValueChange` for
- * controlled mode. Pass `allValues` to enable the parent checkbox pattern:
- * a `Checkbox` with `parent` will automatically toggle between checked,
- * unchecked, and indeterminate based on how many items are selected — no manual
- * state needed.
+ * Designed to be used inside `Field` — `Field` provides the label, description,
+ * and error handling.
+ *
+ * **90% case** — pass `items` and let the composite render all checkboxes:
+ * ```tsx
+ * <CheckboxGroup
+ *   items={[{ value: "email", label: "Email" }, { value: "sms", label: "SMS" }]}
+ *   onValueChange={(values) => console.log(values)}
+ * />
+ * ```
+ *
+ * **Compound API** for custom layouts (parent checkbox, custom ordering):
+ * ```tsx
+ * <CheckboxGroup allValues={allValues} value={value} onValueChange={setValue}>
+ *   <Checkbox parent />
+ *   <Checkbox.Item value="email" label="Email" />
+ * </CheckboxGroup>
+ * ```
+ *
+ * Use `onValueChange` to react to selection changes.
+ *
+ * Pass `allValues` to enable the parent checkbox pattern: a `Checkbox` with
+ * `parent` computes checked/unchecked/indeterminate automatically.
+ *
+ * Reference: [CheckboxGroup – Base UI](https://base-ui.com/react/components/checkbox-group)
  */
 const meta: Meta<typeof CheckboxGroup> = {
   title: "Components/CheckboxGroup",
   component: CheckboxGroup,
+  parameters: { layout: "centered" },
+  argTypes: {
+    children: { control: false },
+    items: { control: false },
+    onValueChange: { control: false },
+  },
+  tags: ["new"],
 };
 
 export default meta;
@@ -30,30 +59,29 @@ const NOTIFICATIONS = [
 ];
 
 export const Default: Story = {
-  render: () => (
-    <CheckboxGroup defaultValue={["comments"]}>
-      {NOTIFICATIONS.map(({ label, value }) => (
-        <Checkbox.Item key={value} value={value} label={label} />
-      ))}
-    </CheckboxGroup>
+  render: (args) => (
+    <CheckboxGroup
+      {...args}
+      items={NOTIFICATIONS}
+      defaultValue={["comments"]}
+    />
   ),
 };
 
 /**
- * `value` + `onValueChange` for controlled mode. `onValueChange` receives the
- * updated array of selected values.
+ * `value` + `onValueChange` for controlled mode.
  */
 export const Controlled: Story = {
-  render: () => {
+  render: (args) => {
     const [value, setValue] = useState<string[]>(["comments", "mentions"]);
-
     return (
       <div className="space-y-4">
-        <CheckboxGroup value={value} onValueChange={setValue}>
-          {NOTIFICATIONS.map(({ label, value: v }) => (
-            <Checkbox.Item key={v} value={v} label={label} />
-          ))}
-        </CheckboxGroup>
+        <CheckboxGroup
+          {...args}
+          items={NOTIFICATIONS}
+          value={value}
+          onValueChange={setValue}
+        />
         <p className="text-sm text-muted-foreground">
           Active: {value.length > 0 ? value.join(", ") : "none"}
         </p>
@@ -69,19 +97,20 @@ export const Controlled: Story = {
  * needed.
  */
 export const WithParent: Story = {
-  render: () => {
+  render: (args) => {
     const allValues = NOTIFICATIONS.map((n) => n.value);
     const [value, setValue] = useState<string[]>(["comments"]);
 
     return (
       <CheckboxGroup
+        {...args}
         value={value}
         onValueChange={setValue}
         allValues={allValues}
       >
         <div className="flex items-center gap-2">
           <Checkbox parent />
-          <span className="text-sm select-none">Enable all notifications</span>
+          <span className="select-none text-sm">Enable all notifications</span>
         </div>
         <div className="ml-6 flex flex-col gap-3 border-l-2 pl-4">
           {NOTIFICATIONS.map(({ label, value: v }) => (
@@ -94,11 +123,70 @@ export const WithParent: Story = {
 };
 
 export const Disabled: Story = {
+  render: (args) => (
+    <CheckboxGroup
+      {...args}
+      items={NOTIFICATIONS}
+      defaultValue={["comments"]}
+      disabled
+    />
+  ),
+};
+
+/**
+ * Wrap `CheckboxGroup` with `Field` to add a label, description, and error
+ * handling. Since `CheckboxGroup` has no native `required`, use `Field`'s
+ * `validate` prop — it receives the current `string[]` and runs on submit.
+ * Return a string to show an error, `null` to pass.
+ */
+export const WithForm: Story = {
+  render: () => {
+    const [submitted, setSubmitted] = useState<string[] | null>(null);
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onFormSubmit={(data) => setSubmitted(data.notifications as string[])}
+      >
+        <Field
+          name="notifications"
+          label="Notifications"
+          required
+          description="Select the notifications you want to receive."
+          validate={(value) =>
+            Array.isArray(value) && value.length === 0
+              ? "Select at least one notification."
+              : null
+          }
+        >
+          <CheckboxGroup items={NOTIFICATIONS} />
+        </Field>
+        <Button type="submit">Submit</Button>
+        {submitted && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            {JSON.stringify(submitted, null, 2)}
+          </pre>
+        )}
+      </Form>
+    );
+  },
+};
+
+/**
+ * Direct composition with the primitive for full structural control.
+ *
+ * ```tsx
+ * <CheckboxGroupRoot allValues={allValues}>
+ *   <Checkbox.Item value="email" label="Email" />
+ * </CheckboxGroupRoot>
+ * ```
+ */
+export const Primitive: Story = {
   render: () => (
-    <CheckboxGroup defaultValue={["comments"]} disabled>
+    <CheckboxGroupRoot defaultValue={["comments"]}>
       {NOTIFICATIONS.map(({ label, value }) => (
         <Checkbox.Item key={value} value={value} label={label} />
       ))}
-    </CheckboxGroup>
+    </CheckboxGroupRoot>
   ),
 };

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

@@ -1,11 +1,20 @@
 import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
-import type * as React from "react";
+import { type ReactNode } from "react";
 import { cn } from "../../lib";
+import { Checkbox, CheckboxGroupContext } from "../checkbox/checkbox";
+import {
+  FieldLegend,
+  FieldSet,
+  FieldValidity,
+  useIsInsideFieldRoot,
+} from "../field/field";
 
-export function CheckboxGroup({
+// ── Root (primitive escape hatch) ─────────────────────────────────────────────
+
+export function CheckboxGroupRoot({
   className,
   ...props
-}: CheckboxGroupPrimitive.Props): React.ReactElement {
+}: CheckboxGroupPrimitive.Props) {
   return (
     <CheckboxGroupPrimitive
       className={cn("flex flex-col items-start gap-3", className)}
@@ -14,3 +23,75 @@ export function CheckboxGroup({
     />
   );
 }
+
+// ── Composite ─────────────────────────────────────────────────────────────────
+
+export interface CheckboxOption {
+  value: string;
+  label: ReactNode;
+  disabled?: boolean;
+}
+
+export interface CheckboxGroupProps {
+  legend?: ReactNode;
+  children?: ReactNode;
+  items?: CheckboxOption[];
+  defaultValue?: string[];
+  value?: string[];
+  onValueChange?: (value: string[]) => void;
+  allValues?: string[];
+  disabled?: boolean;
+  controlFirst?: boolean;
+  className?: string;
+}
+
+export function CheckboxGroup({
+  legend,
+  children,
+  items,
+  defaultValue,
+  value,
+  onValueChange,
+  allValues,
+  disabled,
+  controlFirst = true,
+  className,
+}: CheckboxGroupProps) {
+  const isInsideField = useIsInsideFieldRoot();
+
+  const renderGroup = (invalid: boolean) => (
+    <CheckboxGroupContext.Provider value={{ controlFirst, invalid }}>
+      <CheckboxGroupPrimitive
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onValueChange}
+        allValues={allValues}
+        disabled={disabled}
+      >
+        <FieldSet className={className}>
+          {legend && <FieldLegend>{legend}</FieldLegend>}
+          <div className="flex flex-col gap-2">
+            {items
+              ? items.map((item) => (
+                  <Checkbox.Item
+                    key={item.value}
+                    value={item.value}
+                    label={item.label}
+                    disabled={item.disabled}
+                  />
+                ))
+              : children}
+          </div>
+        </FieldSet>
+      </CheckboxGroupPrimitive>
+    </CheckboxGroupContext.Provider>
+  );
+
+  if (!isInsideField) return renderGroup(false);
+
+  return (
+    <FieldValidity>
+      {({ validity }) => renderGroup(validity.valid === false)}
+    </FieldValidity>
+  );
+}

package/src/components/combobox/combobox.stories.tsx

@@ -40,8 +40,8 @@ const items: Item[] = [
  *
  * Renders a text input as the trigger. `multiple` mode renders a chip input that
  * fits as many chips as the container allows — extras show as "+N más". Items shaped
- * as `{ label, value }` or plain strings/numbers need no extra props; provide
- * `getLabel` / `getValue` for other shapes.
+ * as `{ id, name }`, `{ label, value }`, or plain strings/numbers need no extra props;
+ * provide `getLabel` / `getId` for other shapes.
  *
  * `showClear` (default `true`) shows a clear button when a value is selected —
  * in single mode the chevron switches to X; in multiple mode only X appears.
@@ -49,10 +49,8 @@ const items: Item[] = [
  * `renderItem` customizes the content inside each dropdown item — the checkmark
  * indicator is always rendered by the item wrapper.
  *
- * Exposes `onChange` instead of Base UI's `onValueChange`. For controlled usage,
- * pass `value` + `onChange` together. Use `ComboboxRoot` + primitives for full
- * structural control beyond what escape-hatch props (`inputProps`, `popupProps`,
- * etc.) offer.
+ * For controlled usage pass `value` + `onValueChange` together. Use `ComboboxRoot` +
+ * primitives for full structural control.
  *
  * Reference: [Combobox – Base UI](https://base-ui.com/react/components/combobox)
  */
@@ -68,19 +66,14 @@ const meta: Meta<typeof Combobox> = {
     ),
   ],
   argTypes: {
-    onChange: { control: false },
+    onValueChange: { control: false },
     onOpenChange: { control: false },
     onInputValueChange: { control: false },
     onItemHighlighted: { control: false },
     getLabel: { control: false },
-    getValue: { control: false },
+    getId: { control: false },
     renderItem: { control: false },
-    inputProps: { control: false },
-    chipsProps: { control: false },
-    chipsInputProps: { control: false },
-    popupProps: { control: false },
-    itemProps: { control: false },
-    listProps: { control: false },
+    classNames: { control: false },
   },
 };
 
@@ -93,9 +86,27 @@ export const Default: Story = {
   render: () => <Combobox<Item> items={items} placeholder="Select a fruit…" />,
 };
 
+/**
+ * `className` styles the root input. `classNames` exposes the `input`, `chips`,
+ * `chipsInput`, `popup`, `list`, `item`, and `empty` slots.
+ */
+export const WithClassNames: Story = {
+  render: () => (
+    <Combobox<Item>
+      items={items}
+      placeholder="Select a fruit…"
+      classNames={{
+        popup: "min-w-56",
+        item: "font-mono",
+        empty: "italic",
+      }}
+    />
+  ),
+};
+
 /**
  * Fully controlled: selection state lives outside the component.
- * Omitting `onChange` while providing `value` locks the selection.
+ * Omitting `onValueChange` while providing `value` locks the selection.
  */
 export const Controlled: Story = {
   render: () => {
@@ -106,7 +117,7 @@ export const Controlled: Story = {
           items={items}
           placeholder="Select a fruit…"
           value={value}
-          onChange={setValue}
+          onValueChange={setValue}
         />
         <p className="text-sm text-muted-foreground">
           Selected: {value ? value.label : "none"}
@@ -196,7 +207,7 @@ export const WithRenderItem: Story = {
 };
 
 /**
- * Plain strings require no extra props — `getLabel` and `getValue` default to
+ * Plain strings require no extra props — `getLabel` and `getId` default to
  * `String(item)` when items are primitives.
  */
 export const StringItems: Story = {
@@ -226,17 +237,16 @@ export const LibraryForm: Story = {
 
 /**
  * Fully controlled single selection using primitives. Use this pattern when
- * composite escape-hatch props (`inputProps`, `popupProps`, etc.) are not
- * enough — for example to insert custom elements between parts, swap the input
- * for a select-style trigger (`ComboboxSelectTrigger`), or add a search input
- * inside the popup (`ComboboxSearchInput`).
+ * `classNames` is not enough — for example to insert custom elements between
+ * parts, swap the input for a select-style trigger (`ComboboxSelectTrigger`),
+ * or add a search input inside the popup (`ComboboxSearchInput`).
  *
  * `ComboboxRoot` requires `items` so Base UI can manage the hidden form input
  * and built-in filtering. `itemToStringLabel` / `itemToStringValue` are
  * inferred automatically for `{ label, value }` shapes.
  *
  * ```tsx
- * <ComboboxRoot items={items} value={value} onChange={setValue}>
+ * <ComboboxRoot items={items} value={value} onValueChange={setValue}>
  *   <ComboboxInput placeholder="…" />
  *   <ComboboxPopup>
  *     <ComboboxEmpty>No items found.</ComboboxEmpty>
@@ -256,7 +266,7 @@ export const PrimitiveControlled: Story = {
     const [value, setValue] = useState<Item | null>(null);
     return (
       <div className="flex flex-col gap-4">
-        <ComboboxRoot items={items} value={value} onChange={setValue}>
+        <ComboboxRoot items={items} value={value} onValueChange={setValue}>
           <ComboboxInput
             aria-label="Select a fruit"
             placeholder="Select a fruit…"