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

package/src/components/center/center.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Inbox, Phone } from "lucide-react";
+import { Stack } from "../stack";
+import { Center } from ".";
+
+/**
+ * Layout primitive that centers its children both horizontally and vertically using flexbox.
+ * Supports polymorphic rendering via `as` and an `inline` mode for `inline-flex` contexts.
+ */
+const meta: Meta<typeof Center> = {
+  title: "Components/Center",
+  component: Center,
+  argTypes: {
+    children: { control: false },
+    className: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Center>;
+
+export const Default: Story = {
+  render: () => (
+    <Center className="h-[300px] w-full border rounded-lg border-dashed">
+      <Stack
+        direction="vertical"
+        align="center"
+        gap={8}
+        className="text-muted-foreground"
+      >
+        <Inbox className="size-10 stroke-1" />
+        <span className="text-sm font-medium">No results found</span>
+        <span className="text-xs">Try adjusting your search or filters</span>
+      </Stack>
+    </Center>
+  ),
+};
+
+export const Icon: Story = {
+  render: () => (
+    <Center className="w-fit p-4 bg-primary text-white rounded-full">
+      <Phone />
+    </Center>
+  ),
+};
+
+/**
+ * `inline` switches the display to `inline-flex`, allowing the Center to sit inline with text
+ * or other inline elements without breaking the flow.
+ */
+export const Inline: Story = {
+  render: () => (
+    <p className="text-sm">
+      Text before{" "}
+      <Center
+        inline
+        className="w-8 h-8 bg-primary text-white rounded-full text-xs"
+      >
+        42
+      </Center>{" "}
+      text after
+    </p>
+  ),
+};
+
+/**
+ * `as` renders the Center as a different HTML element for semantic markup.
+ * Common use cases: `main` for page root, `section` for content areas.
+ */
+export const As: Story = {
+  render: () => (
+    <Center
+      as="main"
+      className="bg-secondary w-[400px] aspect-square rounded p-4"
+    >
+      <div className="bg-primary text-primary-foreground rounded p-4">
+        Rendered as &lt;main&gt;
+      </div>
+    </Center>
+  ),
+};

package/src/components/center/center.tsx

@@ -0,0 +1,24 @@
+import { ComponentProps, ElementType } from "react";
+import { cn } from "../../lib";
+
+interface CenterProps extends ComponentProps<"div"> {
+  as?: ElementType;
+  inline?: boolean;
+}
+
+export const Center = ({
+  as: Tag = "div",
+  inline = false,
+  className,
+  ...props
+}: CenterProps) => (
+  <Tag
+    className={cn(
+      inline ? "inline-flex" : "flex",
+      "items-center justify-center",
+      className,
+    )}
+    {...props}
+    data-slot="center"
+  />
+);

package/src/components/center/index.ts

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

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

@@ -0,0 +1,307 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { action } from "storybook/actions";
+import { Button } from "../../components";
+import { useSelection } from "../../hooks";
+import { Checkbox, CheckboxIndicator, CheckboxRoot } from "./checkbox";
+
+/**
+ * Checkbox built on Base UI. Handles checked, unchecked, and indeterminate
+ * states natively. Built on `@base-ui/react/checkbox`.
+ *
+ * Compound API:
+ * - `Checkbox` — single checkbox, renders the control only
+ * - `Checkbox.Item` — labeled checkbox for use inside `Checkbox.Group`
+ * - `Checkbox.Group` — group wrapper with value management and a11y fieldset
+ * - `Checkbox.Legend` — composable legend for `Checkbox.Group`
+ *
+ * `controlFirst` (default `true`) on `Checkbox.Group` places the checkbox before
+ * the label on all `Checkbox.Item` children via context.
+ *
+ * When `Checkbox.Group` has an `error`, all `Checkbox.Item` children
+ * automatically receive `aria-invalid` so their border turns red.
+ *
+ * Reference: [Checkbox – Base UI](https://base-ui.com/react/components/checkbox)
+ */
+const meta: Meta<typeof Checkbox> = {
+  title: "Components/Checkbox",
+  component: Checkbox,
+  parameters: { layout: "centered" },
+  args: {
+    name: "checkbox",
+  },
+  argTypes: {
+    onCheckedChange: { control: false },
+    indicatorProps: { control: false },
+    tooltip: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {};
+
+/**
+ * Pass `label` for a linked `<label>` element. `children` works as an alias —
+ * `label` takes priority when both are provided.
+ */
+export const WithLabel: Story = {
+  args: {
+    label: "Receive marketing emails",
+  },
+};
+
+/**
+ * Pass `children` as an alternative to `label`.
+ */
+export const WithChildren: Story = {
+  render: () => <Checkbox>I accept the terms and conditions</Checkbox>,
+};
+
+/**
+ * `required` shows a `*` in the label. `tooltip` renders an info icon next
+ * to the label that opens a tooltip on hover/focus.
+ */
+export const WithRequired: Story = {
+  args: {
+    label: "I accept the terms and conditions",
+    required: true,
+    tooltip: "You must accept the terms to continue.",
+  },
+};
+
+/**
+ * `controlFirst={false}` places the label before the checkbox.
+ * Default is `true` (checkbox → label).
+ */
+export const ControlFirst: Story = {
+  args: {
+    controlFirst: false,
+    label: "I accept the terms and conditions",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    defaultChecked: true,
+  },
+};
+
+/**
+ * `aria-invalid="true"` applies error border and ring — no Field wrapper needed.
+ */
+export const Invalid: Story = {
+  args: { "aria-invalid": "true" },
+};
+
+/**
+ * Use `checked` + `onCheckedChange` for controlled mode.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return <Checkbox checked={checked} onCheckedChange={setChecked} />;
+  },
+};
+
+/**
+ * `indeterminate` is a first-class prop — Base UI sets `aria-checked="mixed"`
+ * and manages the visual state automatically. Clicking an indeterminate
+ * checkbox moves it to checked.
+ */
+export const Indeterminate: Story = {
+  render: () => {
+    const ITEMS = [1, 2, 3, 4];
+    const { selected, toggle, toggleAll, isAllSelected, isSomeSelected } =
+      useSelection(ITEMS);
+
+    return (
+      <div className="space-y-2">
+        <Checkbox
+          checked={isAllSelected}
+          indeterminate={isSomeSelected}
+          onCheckedChange={() => toggleAll()}
+        >
+          Select all
+        </Checkbox>
+        <div className="ml-6 space-y-2 border-l-2 pl-4">
+          {ITEMS.map((item) => (
+            <Checkbox
+              key={item}
+              checked={selected.includes(item)}
+              onCheckedChange={() => toggle(item)}
+            >
+              Option {item}
+            </Checkbox>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Base UI injects a hidden `<input type="checkbox">` so `name` and `required`
+ * work with native `FormData` out of the box.
+ */
+export const Required: Story = {
+  args: {
+    name: "terms",
+    required: true,
+    label: "I accept the terms and conditions",
+  },
+  render: (args) => (
+    <form
+      className="space-y-3"
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        action("submit")(Object.fromEntries(data));
+      }}
+    >
+      <Checkbox {...args} />
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+};
+
+/**
+ * `Checkbox.Group` manages selected values and provides an accessible
+ * `<fieldset>` wrapper. Each `Checkbox.Item` needs a `value` prop to
+ * participate in the group's state.
+ *
+ * Use `defaultValue` for uncontrolled groups.
+ */
+export const Group: Story = {
+  render: () => (
+    <Checkbox.Group
+      legend="Notifications"
+      defaultValue={["email"]}
+      onChange={action("onChange")}
+    >
+      <Checkbox.Item value="email" label="Email" />
+      <Checkbox.Item value="sms" label="SMS" />
+      <Checkbox.Item value="push" label="Push notifications" />
+    </Checkbox.Group>
+  ),
+};
+
+/**
+ * `error` takes visual priority over `description` — both props can coexist,
+ * but description only renders when there is no error. When `error` is set,
+ * all items in the group receive `aria-invalid` and their borders turn red.
+ */
+export const GroupWithError: Story = {
+  render: () => (
+    <Checkbox.Group
+      legend="Preferences"
+      description="Select at least one option."
+      error="You must select at least one option."
+    >
+      <Checkbox.Item value="email" label="Email" />
+      <Checkbox.Item value="sms" label="SMS" />
+    </Checkbox.Group>
+  ),
+};
+
+/**
+ * `allValues` enables the select-all pattern: Base UI derives the indeterminate
+ * state automatically when only some items are checked. The parent checkbox
+ * controls the entire group when clicked.
+ */
+export const GroupParent: Story = {
+  render: () => {
+    const ALL = ["email", "sms", "push"];
+    const [value, setValue] = useState(["email"]);
+
+    const isAll = value.length === ALL.length;
+    const isSome = value.length > 0 && !isAll;
+
+    return (
+      <div className="space-y-2">
+        <Checkbox
+          checked={isAll}
+          indeterminate={isSome}
+          onCheckedChange={(checked) => setValue(checked ? ALL : [])}
+        />
+        <div className="ml-6 border-l-2 pl-4">
+          <Checkbox.Group value={value} onChange={setValue} allValues={ALL}>
+            <Checkbox.Item value="email" label="Email" />
+            <Checkbox.Item value="sms" label="SMS" />
+            <Checkbox.Item value="push" label="Push notifications" />
+          </Checkbox.Group>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Use `value` + `onChange` for a controlled group.
+ */
+export const GroupControlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<string[]>(["email"]);
+    return (
+      <Checkbox.Group
+        legend="Contact channel"
+        value={value}
+        onChange={setValue}
+      >
+        <Checkbox.Item value="email" label="Email" />
+        <Checkbox.Item value="sms" label="SMS" />
+        <Checkbox.Item value="push" label="Push notifications" />
+      </Checkbox.Group>
+    );
+  },
+};
+
+/**
+ * `Checkbox.Legend` can be placed as a direct child of `Checkbox.Group`
+ * instead of the `legend` prop when you need custom styling or want to
+ * visually hide it with `className="sr-only"`.
+ *
+ * ```tsx
+ * <Checkbox.Group>
+ *   <Checkbox.Legend className="sr-only">Preferences</Checkbox.Legend>
+ *   <Checkbox.Item value="a" label="Option A" />
+ * </Checkbox.Group>
+ * ```
+ */
+export const ComposableLegend: Story = {
+  render: () => (
+    <Checkbox.Group>
+      <Checkbox.Legend className="text-base font-semibold">
+        Contact preferences
+      </Checkbox.Legend>
+      <Checkbox.Item value="email" label="Email" />
+      <Checkbox.Item value="sms" label="SMS" />
+    </Checkbox.Group>
+  ),
+};
+
+/**
+ * Direct composition with primitives for full structural control.
+ * Use when the composite props are not enough — custom ordering,
+ * extra elements between parts, or non-standard layouts.
+ *
+ * ```tsx
+ * <CheckboxRoot id="custom">
+ *   <CheckboxIndicator />
+ * </CheckboxRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <CheckboxRoot id="primitive-example">
+        <CheckboxIndicator />
+      </CheckboxRoot>
+      <label htmlFor="primitive-example" className="text-sm select-none">
+        Manual composition
+      </label>
+    </div>
+  ),
+};

package/src/components/checkbox/checkbox.tsx

@@ -0,0 +1,273 @@
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
+import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
+import { Field as FieldBase } from "@base-ui/react/field";
+import { Fieldset } from "@base-ui/react/fieldset";
+import type * as React from "react";
+import { createContext, type ReactNode, useContext, useId } from "react";
+import { cn } from "../../lib";
+import { Label } from "../label";
+
+// ── Primitives ─────────────────────────────────────────────────────────────────
+
+export function CheckboxRoot({
+  className,
+  ...props
+}: CheckboxPrimitive.Root.Props): React.ReactElement {
+  return (
+    <CheckboxPrimitive.Root
+      className={cn(
+        "peer relative inline-flex size-4.5 shrink-0 items-center justify-center rounded-[.25rem] 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-[3px]",
+        "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",
+        className,
+      )}
+      data-slot="checkbox"
+      {...props}
+    />
+  );
+}
+
+export function CheckboxIndicator({
+  className,
+  ...props
+}: CheckboxPrimitive.Indicator.Props): React.ReactElement {
+  return (
+    <CheckboxPrimitive.Indicator
+      className={cn(
+        "absolute -inset-px flex items-center justify-center rounded-[.25rem] text-primary-foreground",
+        "data-unchecked:hidden data-checked:bg-primary data-indeterminate:text-foreground",
+        className,
+      )}
+      data-slot="checkbox-indicator"
+      render={(
+        renderProps: React.ComponentProps<"span">,
+        state: CheckboxPrimitive.Indicator.State,
+      ) => (
+        <span {...renderProps}>
+          {state.indeterminate ? (
+            <svg
+              aria-hidden="true"
+              className="size-3.5 sm:size-3"
+              fill="none"
+              height="24"
+              stroke="currentColor"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="3"
+              viewBox="0 0 24 24"
+              width="24"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path d="M5.252 12h13.496" />
+            </svg>
+          ) : (
+            <svg
+              aria-hidden="true"
+              className="size-3.5 sm:size-3"
+              fill="none"
+              height="24"
+              stroke="currentColor"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="3"
+              viewBox="0 0 24 24"
+              width="24"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
+            </svg>
+          )}
+        </span>
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Group context ──────────────────────────────────────────────────────────────
+
+const CheckboxGroupContext = createContext<{
+  controlFirst: boolean;
+  invalid: boolean;
+}>({
+  controlFirst: true,
+  invalid: false,
+});
+
+// ── Composite: Checkbox (single) ───────────────────────────────────────────────
+
+interface CheckboxProps extends Omit<CheckboxPrimitive.Root.Props, "children"> {
+  children?: ReactNode;
+  label?: ReactNode;
+  tooltip?: ReactNode;
+  indicatorProps?: CheckboxPrimitive.Indicator.Props;
+  controlFirst?: boolean;
+}
+
+function CheckboxSingle({
+  className,
+  indicatorProps,
+  label,
+  children,
+  tooltip,
+  controlFirst = true,
+  required,
+  id,
+  ...props
+}: CheckboxProps): React.ReactElement {
+  const generatedId = useId();
+  const idToUse = id ?? generatedId;
+  const labelContent = label ?? children;
+
+  const checkbox = (
+    <CheckboxRoot
+      id={idToUse}
+      className={className}
+      required={required}
+      {...props}
+    >
+      <CheckboxIndicator {...indicatorProps} />
+    </CheckboxRoot>
+  );
+
+  if (labelContent !== undefined) {
+    return (
+      <div
+        className={cn(
+          "flex select-none items-center gap-x-2",
+          !controlFirst && "flex-row-reverse justify-end",
+        )}
+      >
+        {checkbox}
+        <Label htmlFor={idToUse} required={required} tooltip={tooltip}>
+          {labelContent}
+        </Label>
+      </div>
+    );
+  }
+
+  return checkbox;
+}
+
+// ── Composite: Checkbox.Item (for use in Checkbox.Group) ──────────────────────
+
+export interface CheckboxItemProps
+  extends Omit<CheckboxPrimitive.Root.Props, "children"> {
+  label: ReactNode;
+}
+
+function CheckboxItem({
+  className,
+  label,
+  id,
+  ...props
+}: CheckboxItemProps): React.ReactElement {
+  const { controlFirst, invalid } = useContext(CheckboxGroupContext);
+  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",
+        )}
+      >
+        <CheckboxRoot id={idToUse} className={className} {...props}>
+          <CheckboxIndicator />
+        </CheckboxRoot>
+        <Label htmlFor={idToUse}>{label}</Label>
+      </div>
+    </FieldBase.Root>
+  );
+}
+
+// ── Composite: Checkbox.Legend ─────────────────────────────────────────────────
+
+export interface CheckboxLegendProps {
+  children: ReactNode;
+  className?: string;
+}
+
+function CheckboxLegend({
+  children,
+  className,
+}: CheckboxLegendProps): React.ReactElement {
+  return (
+    <Fieldset.Legend
+      className={cn("text-sm font-medium leading-none", className)}
+    >
+      {children}
+    </Fieldset.Legend>
+  );
+}
+
+// ── Composite: Checkbox.Group ──────────────────────────────────────────────────
+
+export interface CheckboxGroupProps {
+  legend?: ReactNode;
+  children: ReactNode;
+  error?: string;
+  description?: ReactNode;
+  defaultValue?: string[];
+  value?: string[];
+  onChange?: (value: string[]) => void;
+  allValues?: string[];
+  disabled?: boolean;
+  controlFirst?: boolean;
+  className?: string;
+}
+
+function CheckboxGroup({
+  legend,
+  children,
+  error,
+  description,
+  defaultValue,
+  value,
+  onChange,
+  allValues,
+  disabled,
+  controlFirst = true,
+  className,
+}: CheckboxGroupProps): React.ReactElement {
+  return (
+    <CheckboxGroupContext.Provider value={{ controlFirst, invalid: !!error }}>
+      <CheckboxGroupPrimitive
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onChange}
+        allValues={allValues}
+        disabled={disabled}
+      >
+        <Fieldset.Root className={cn("flex flex-col gap-3", className)}>
+          {legend && <CheckboxLegend>{legend}</CheckboxLegend>}
+          <div className="flex flex-col gap-2">{children}</div>
+          {error && <p className="text-sm font-medium text-error">{error}</p>}
+          {!error && description && (
+            <p className="text-sm text-muted-foreground">{description}</p>
+          )}
+        </Fieldset.Root>
+      </CheckboxGroupPrimitive>
+    </CheckboxGroupContext.Provider>
+  );
+}
+
+// ── Compound export ────────────────────────────────────────────────────────────
+
+export const Checkbox = Object.assign(CheckboxSingle, {
+  Item: CheckboxItem,
+  Group: CheckboxGroup,
+  Legend: CheckboxLegend,
+});
+
+// ── Primitive escape hatch ─────────────────────────────────────────────────────
+
+export { CheckboxPrimitive };

package/src/components/checkbox/index.ts

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