@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.12

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

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Checkbox } from "../checkbox";
+import { CheckboxGroup } 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.
+ *
+ * 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.
+ */
+const meta: Meta<typeof CheckboxGroup> = {
+  title: "Components/CheckboxGroup",
+  component: CheckboxGroup,
+};
+
+export default meta;
+type Story = StoryObj<typeof CheckboxGroup>;
+
+const NOTIFICATIONS = [
+  { label: "Comments on my posts", value: "comments" },
+  { label: "Mentions", value: "mentions" },
+  { label: "Direct messages", value: "messages" },
+  { label: "System updates", value: "system" },
+];
+
+export const Default: Story = {
+  render: () => (
+    <CheckboxGroup defaultValue={["comments"]}>
+      {NOTIFICATIONS.map(({ label, value }) => (
+        <Checkbox.Item key={value} value={value} label={label} />
+      ))}
+    </CheckboxGroup>
+  ),
+};
+
+/**
+ * `value` + `onValueChange` for controlled mode. `onValueChange` receives the
+ * updated array of selected values.
+ */
+export const Controlled: Story = {
+  render: () => {
+    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>
+        <p className="text-sm text-muted-foreground">
+          Active: {value.length > 0 ? value.join(", ") : "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * `allValues` enables the parent checkbox pattern. The `Checkbox` with `parent`
+ * computes its state automatically: checked when all items are selected,
+ * unchecked when none, indeterminate on partial selection — no manual state
+ * needed.
+ */
+export const WithParent: Story = {
+  render: () => {
+    const allValues = NOTIFICATIONS.map((n) => n.value);
+    const [value, setValue] = useState<string[]>(["comments"]);
+
+    return (
+      <CheckboxGroup
+        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>
+        </div>
+        <div className="ml-6 flex flex-col gap-3 border-l-2 pl-4">
+          {NOTIFICATIONS.map(({ label, value: v }) => (
+            <Checkbox.Item key={v} value={v} label={label} />
+          ))}
+        </div>
+      </CheckboxGroup>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <CheckboxGroup defaultValue={["comments"]} disabled>
+      {NOTIFICATIONS.map(({ label, value }) => (
+        <Checkbox.Item key={value} value={value} label={label} />
+      ))}
+    </CheckboxGroup>
+  ),
+};

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

@@ -0,0 +1,16 @@
+import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
+import type * as React from "react";
+import { cn } from "../../lib";
+
+export function CheckboxGroup({
+  className,
+  ...props
+}: CheckboxGroupPrimitive.Props): React.ReactElement {
+  return (
+    <CheckboxGroupPrimitive
+      className={cn("flex flex-col items-start gap-3", className)}
+      data-slot="checkbox-group"
+      {...props}
+    />
+  );
+}

package/src/components/checkbox-group/index.ts

@@ -0,0 +1 @@
+export * from "./checkbox-group";

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

@@ -0,0 +1,339 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../button";
+import { Field } from "../field";
+import { Form } from "../form";
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxPopup,
+  ComboboxRoot,
+  ComboboxValue,
+} from "./combobox";
+
+interface Item {
+  label: string;
+  value: string;
+}
+
+const items: Item[] = [
+  { label: "Apple", value: "apple" },
+  { label: "Banana", value: "banana" },
+  { label: "Orange", value: "orange" },
+  { label: "Grape", value: "grape" },
+  { label: "Strawberry", value: "strawberry" },
+  { label: "Mango", value: "mango" },
+  { label: "Pineapple", value: "pineapple" },
+  { label: "Kiwi", value: "kiwi" },
+  { label: "Peach", value: "peach" },
+  { label: "Pear", value: "pear" },
+];
+
+/**
+ * Composite combobox supporting single and multiple selection, built on Base UI.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * `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.
+ *
+ * Reference: [Combobox – Base UI](https://base-ui.com/react/components/combobox)
+ */
+const meta: Meta<typeof Combobox> = {
+  title: "Components/Combobox",
+  component: Combobox,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-84">
+        <Story />
+      </div>
+    ),
+  ],
+  argTypes: {
+    onChange: { control: false },
+    onOpenChange: { control: false },
+    onInputValueChange: { control: false },
+    onItemHighlighted: { control: false },
+    getLabel: { control: false },
+    getValue: { control: false },
+    renderItem: { control: false },
+    inputProps: { control: false },
+    chipsProps: { control: false },
+    chipsInputProps: { control: false },
+    popupProps: { control: false },
+    itemProps: { control: false },
+    listProps: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Combobox>;
+
+// ─── Composite stories ────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  render: () => <Combobox<Item> items={items} placeholder="Select a fruit…" />,
+};
+
+/**
+ * Fully controlled: selection state lives outside the component.
+ * Omitting `onChange` while providing `value` locks the selection.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<Item | null>(null);
+    return (
+      <div className="flex flex-col gap-4">
+        <Combobox<Item>
+          items={items}
+          placeholder="Select a fruit…"
+          value={value}
+          onChange={setValue}
+        />
+        <p className="text-sm text-muted-foreground">
+          Selected: {value ? value.label : "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <Combobox<Item> items={items} multiple placeholder="Select fruits…" />
+  ),
+};
+
+interface TechItem {
+  label: string;
+  value: string;
+  emoji: string;
+  description: string;
+}
+
+const TECH_ITEMS: TechItem[] = [
+  {
+    label: "TypeScript",
+    value: "typescript",
+    emoji: "🔷",
+    description: "Typed JavaScript superset",
+  },
+  {
+    label: "Python",
+    value: "python",
+    emoji: "🐍",
+    description: "General-purpose scripting",
+  },
+  {
+    label: "Rust",
+    value: "rust",
+    emoji: "⚙",
+    description: "Memory-safe systems language",
+  },
+  {
+    label: "Go",
+    value: "go",
+    emoji: "🔵",
+    description: "Concurrent, cloud-native",
+  },
+  {
+    label: "Swift",
+    value: "swift",
+    emoji: "🧡",
+    description: "Apple platforms",
+  },
+  {
+    label: "Kotlin",
+    value: "kotlin",
+    emoji: "🟣",
+    description: "JVM + Android",
+  },
+];
+
+/**
+ * `renderItem` controls the content **inside** each `ComboboxItem` — the
+ * checkmark indicator is always rendered by the item wrapper. Use it to show
+ * rich content: icons, subtitles, badges, or avatars alongside the label.
+ */
+export const WithRenderItem: Story = {
+  render: () => (
+    <Combobox<TechItem>
+      items={TECH_ITEMS}
+      placeholder="Select a language…"
+      renderItem={(item) => (
+        <span className="flex items-center gap-2.5 py-0.5">
+          <span className="text-base leading-none">{item.emoji}</span>
+          <span className="flex flex-col gap-0.5">
+            <span className="text-sm font-medium leading-none">
+              {item.label}
+            </span>
+            <span className="text-xs leading-none text-muted-foreground">
+              {item.description}
+            </span>
+          </span>
+        </span>
+      )}
+    />
+  ),
+};
+
+/**
+ * Plain strings require no extra props — `getLabel` and `getValue` default to
+ * `String(item)` when items are primitives.
+ */
+export const StringItems: Story = {
+  render: () => (
+    <Combobox
+      items={["Apple", "Banana", "Orange", "Grape", "Strawberry"]}
+      placeholder="Select a fruit…"
+    />
+  ),
+};
+
+export const LibraryForm: Story = {
+  name: "Form",
+  render: () => {
+    return (
+      <Form className="space-y-1" onSubmit={console.log}>
+        <Field name="fruit" label="Fruits">
+          <Combobox items={items} required />
+        </Field>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
+// ─── Primitive stories ────────────────────────────────────────────────────────
+
+/**
+ * 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`).
+ *
+ * `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}>
+ *   <ComboboxInput placeholder="…" />
+ *   <ComboboxPopup>
+ *     <ComboboxEmpty>No items found.</ComboboxEmpty>
+ *     <ComboboxList>
+ *       {(item) => (
+ *         <ComboboxItem key={item.value} value={item}>
+ *           {item.label}
+ *         </ComboboxItem>
+ *       )}
+ *     </ComboboxList>
+ *   </ComboboxPopup>
+ * </ComboboxRoot>
+ * ```
+ */
+export const PrimitiveControlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<Item | null>(null);
+    return (
+      <div className="flex flex-col gap-4">
+        <ComboboxRoot items={items} value={value} onChange={setValue}>
+          <ComboboxInput
+            aria-label="Select a fruit"
+            placeholder="Select a fruit…"
+          />
+          <ComboboxPopup>
+            <ComboboxEmpty>No items found.</ComboboxEmpty>
+            <ComboboxList>
+              {(item: Item) => (
+                <ComboboxItem key={item.value} value={item}>
+                  {item.label}
+                </ComboboxItem>
+              )}
+            </ComboboxList>
+          </ComboboxPopup>
+        </ComboboxRoot>
+        <p className="text-sm text-muted-foreground">
+          Selected: {value ? value.label : "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * Multiple selection using primitives. `ComboboxChipsInput` must be placed
+ * inside the `ComboboxValue` render function so it always sits after the last chip.
+ *
+ * ```tsx
+ * <ComboboxRoot items={items} multiple>
+ *   <ComboboxChips>
+ *     <ComboboxValue>
+ *       {(value: Item[]) => (
+ *         <>
+ *           {value.map((item) => (
+ *             <ComboboxChip key={item.value} aria-label={item.label}>
+ *               {item.label}
+ *             </ComboboxChip>
+ *           ))}
+ *           <ComboboxChipsInput placeholder={value.length === 0 ? "Select..." : undefined} />
+ *         </>
+ *       )}
+ *     </ComboboxValue>
+ *   </ComboboxChips>
+ *   <ComboboxPopup>...</ComboboxPopup>
+ * </ComboboxRoot>
+ * ```
+ */
+export const PrimitiveMultiple: Story = {
+  render: () => (
+    <ComboboxRoot items={items} multiple loopFocus>
+      <ComboboxChips>
+        <ComboboxValue>
+          {(value: Item[]) => (
+            <>
+              {value.map((item) => (
+                <ComboboxChip aria-label={item.label} key={item.value}>
+                  {item.label}
+                </ComboboxChip>
+              ))}
+              <ComboboxChipsInput
+                aria-label="Select a fruit"
+                placeholder={value.length > 0 ? undefined : "Select a fruit…"}
+              />
+            </>
+          )}
+        </ComboboxValue>
+      </ComboboxChips>
+      <ComboboxPopup>
+        <ComboboxEmpty>No items found.</ComboboxEmpty>
+        <ComboboxList>
+          {(item: Item) => (
+            <ComboboxItem key={item.value} value={item}>
+              {item.label}
+            </ComboboxItem>
+          )}
+        </ComboboxList>
+      </ComboboxPopup>
+    </ComboboxRoot>
+  ),
+};