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

package/src/components/field/field.stories.tsx

@@ -0,0 +1,446 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../button/button";
+import { CheckboxIndicator, CheckboxRoot } from "../checkbox/checkbox";
+import { Form } from "../form/form";
+import { Input } from "../input/input";
+import { SwitchRoot, SwitchThumb } from "../switch/switch";
+import { Textarea } from "../textarea/textarea";
+import {
+  Field,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldItem,
+  FieldLabel,
+  FieldRoot,
+  FieldValidity,
+  useFieldName,
+} from "./field";
+
+/**
+ * Layout wrapper that connects a label, description, and errors to any form
+ * control via Base UI's field context. Auto-wires `htmlFor`/`aria-describedby`.
+ *
+ * The composite `Field` promotes `label`, `description`, `error`, `required`,
+ * `tooltip`, and `inline` as top-level props — covers ~90% of use cases.
+ * `error` accepts a string, a `{ message, match }` object (scoped to a
+ * `ValidityState` key), or an array for multiple errors.
+ *
+ * For full structural control (custom ordering, extra elements between parts,
+ * non-standard error rendering), use `FieldRoot` + primitives directly.
+ *
+ * Reference: [Field – Base UI](https://base-ui.com/react/components/field.md)
+ */
+const meta: Meta<typeof Field> = {
+  title: "Components/Field",
+  component: Field,
+  subcomponents: {
+    FieldRoot,
+    FieldLabel,
+    FieldItem,
+    FieldDescription,
+    FieldError,
+    FieldControl,
+    FieldValidity,
+  },
+  parameters: { layout: "centered" },
+  args: {
+    label: "Email",
+    description: "We'll never share your email.",
+    children: <Input type="email" placeholder="you@example.com" />,
+  },
+  argTypes: {
+    children: { control: false },
+    classNames: { control: false },
+    error: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Field>;
+
+export const Default: Story = {};
+
+/**
+ * `className` estila el root del Field. `classNames` expone los slots
+ * `label`, `description` y `error` para personalizar cada parte interna.
+ */
+export const WithClassNames: Story = {
+  args: {
+    error: "Enter a valid email address.",
+    classNames: {
+      label: "text-primary",
+      description: "italic",
+      error: "font-mono",
+    },
+  },
+};
+
+export const Required: Story = {
+  args: {
+    children: <Input type="email" required placeholder="you@example.com" />,
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * `tooltip` renders an info icon next to the label with an accessible popup.
+ */
+export const WithTooltip: Story = {
+  args: {
+    tooltip: "Used to send you a confirmation link.",
+  },
+};
+
+/**
+ * `error` as a string auto-marks the field invalid — no `invalid` prop needed.
+ */
+export const WithError: Story = {
+  args: {
+    error: "Enter a valid email address.",
+  },
+};
+
+/**
+ * `error` as an array maps each message to a specific `ValidityState` key via
+ * `match`. Submit the form to trigger native HTML validation.
+ */
+export const WithMatchedErrors: Story = {
+  render: () => (
+    <form className="flex flex-col gap-3" onSubmit={(e) => e.preventDefault()}>
+      <Field
+        label="Email"
+        required
+        error={[
+          { message: "Email is required.", match: "valueMissing" },
+          { message: "Enter a valid email address.", match: "typeMismatch" },
+        ]}
+      >
+        <Input type="email" required placeholder="you@example.com" />
+      </Field>
+      <button
+        type="submit"
+        className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+      >
+        Submit
+      </button>
+    </form>
+  ),
+};
+
+/**
+ * `FieldValidity` render prop exposes the full `ValidityState` for custom
+ * error rendering without going through the `error` prop.
+ */
+export const WithValidity: Story = {
+  render: () => (
+    <form className="flex flex-col gap-3" onSubmit={(e) => e.preventDefault()}>
+      <Field label="Email" required className="w-72">
+        <Input type="email" required placeholder="you@example.com" />
+        <FieldValidity>
+          {({ validity }) =>
+            !validity.valid && (
+              <p className="text-error-foreground text-xs">
+                {validity.valueMissing
+                  ? "Email is required."
+                  : "Enter a valid email address."}
+              </p>
+            )
+          }
+        </FieldValidity>
+      </Field>
+      <button
+        type="submit"
+        className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+      >
+        Submit
+      </button>
+    </form>
+  ),
+};
+
+export const TextareaField: Story = {
+  args: {
+    label: "Bio",
+    description: "Max 160 characters.",
+    children: <Textarea placeholder="Tell us about yourself..." />,
+  },
+};
+
+/**
+ * `inline` renders control + label side-by-side. Use for single checkboxes and
+ * switches. Description and error still wrap to the row below.
+ */
+export const CheckboxField: Story = {
+  args: {
+    inline: true,
+    label: "I accept the terms and conditions",
+    description: undefined,
+    className: undefined,
+    error: { message: "You must accept the terms.", match: "valueMissing" },
+    children: (
+      <CheckboxRoot required>
+        <CheckboxIndicator />
+      </CheckboxRoot>
+    ),
+  },
+};
+
+export const SwitchField: Story = {
+  args: {
+    inline: true,
+    label: "Email notifications",
+    description: "Receive a weekly digest.",
+    className: undefined,
+    children: (
+      <SwitchRoot>
+        <SwitchThumb />
+      </SwitchRoot>
+    ),
+  },
+};
+
+/**
+ * `FieldRoot` + primitives for full structural control. `FieldControl` registers
+ * a non-Base-UI input with the field context so it participates in labelling,
+ * validation, and error state.
+ *
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldLabel>Website</FieldLabel>
+ *   <FieldControl render={<MyCustomInput />} />
+ *   <FieldDescription>Helper text</FieldDescription>
+ *   <FieldError>Error message</FieldError>
+ * </FieldRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <FieldRoot className="w-72">
+      <FieldLabel>Website</FieldLabel>
+      <FieldControl
+        render={
+          <input
+            className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50"
+            type="url"
+            required
+            placeholder="https://example.com"
+          />
+        }
+      />
+      <FieldDescription>Your public profile URL.</FieldDescription>
+      <FieldError match="valueMissing">Website is required.</FieldError>
+      <FieldError match="typeMismatch">Enter a valid URL.</FieldError>
+    </FieldRoot>
+  ),
+};
+
+// ── Custom control helpers ────────────────────────────────────────────────────
+
+const TAG_CLASSES =
+  "inline-flex items-center gap-1 rounded bg-muted px-2 py-0.5 text-xs select-none";
+
+function TagChips({
+  items,
+  onRemove,
+}: {
+  items: string[];
+  onRemove: (item: string) => void;
+}) {
+  if (!items.length) return null;
+  return (
+    <div className="flex flex-wrap gap-1.5">
+      {items.map((item) => (
+        <span key={item} className={TAG_CLASSES}>
+          {item}
+          <button
+            type="button"
+            onClick={() => onRemove(item)}
+            className="text-muted-foreground hover:text-foreground leading-none"
+            aria-label={`Remove ${item}`}
+          >
+            ×
+          </button>
+        </span>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Approach 1 — `FieldControl` + hidden input (public API).
+ * `FieldControl` registers the element with Field and exposes an `inputRef`
+ * pointing to a real DOM input. The serialized value flows through that input
+ * so `Field.validate` receives it as a string — parse it back inside validate.
+ */
+function TagInputHidden() {
+  const [items, setItems] = useState<string[]>([]);
+  const [draft, setDraft] = useState("");
+
+  function add() {
+    const tag = draft.trim();
+    if (tag && !items.includes(tag)) {
+      setItems((prev) => [...prev, tag]);
+      setDraft("");
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Hidden input = what FieldControl registers as the field control.
+          value keeps it in sync so validate() receives the serialized list. */}
+      <FieldControl
+        render={<input type="hidden" />}
+        value={JSON.stringify(items)}
+      />
+      <TagChips
+        items={items}
+        onRemove={(t) => setItems((p) => p.filter((i) => i !== t))}
+      />
+      <div className="flex gap-2">
+        <Input
+          value={draft}
+          onChange={(value) => setDraft(value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") {
+              e.preventDefault();
+              add();
+            }
+          }}
+          placeholder="Add a tag…"
+        />
+        <Button type="button" variant="outline" size="sm" onClick={add}>
+          Add
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Approach 2 — native hidden input + form-level validation.
+ * The component renders a `<input type="hidden">` for native `FormData`
+ * participation. `useFieldName` reads the `name` from the parent `Field`
+ * context automatically. Validation runs in `Form.onFormSubmit` and errors
+ * route back via `Form.errors` — no `Field.validate` needed.
+ */
+function TagInputNative() {
+  const [items, setItems] = useState<string[]>([]);
+  const [draft, setDraft] = useState("");
+  const fieldName = useFieldName();
+
+  function add() {
+    const tag = draft.trim();
+    if (tag && !items.includes(tag)) {
+      setItems((prev) => [...prev, tag]);
+      setDraft("");
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Hidden input participates in FormData under the Field's name.
+          No FieldControl needed — validation is handled at the form level. */}
+      <input type="hidden" name={fieldName} value={JSON.stringify(items)} />
+      <TagChips
+        items={items}
+        onRemove={(t) => setItems((p) => p.filter((i) => i !== t))}
+      />
+      <div className="flex gap-2">
+        <Input
+          value={draft}
+          onChange={(value) => setDraft(value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") {
+              e.preventDefault();
+              add();
+            }
+          }}
+          placeholder="Add a tag…"
+        />
+        <Button type="button" variant="outline" size="sm" onClick={add}>
+          Add
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+// ── Custom control stories ────────────────────────────────────────────────────
+
+/**
+ * **Approach 1 — `FieldControl` + `Field.validate` (per-field validation).**
+ * `FieldControl render={<input type="hidden" />}` registers a hidden input as
+ * the field control. Pass `value={JSON.stringify(state)}` to keep it in sync.
+ * `Field.validate` receives the serialized string — parse it back to validate.
+ *
+ * Best for: inline async validation, per-field error display, custom rules
+ * that run outside of `onFormSubmit`.
+ */
+export const CustomControlHiddenInput: Story = {
+  render: () => (
+    <Form className="flex w-80 flex-col gap-4">
+      <Field
+        name="tags"
+        label="Tags"
+        description="1–3 tags. Submit to validate."
+        validate={(value) => {
+          const tags = JSON.parse(String(value || "[]")) as string[];
+          if (!tags.length) return "Add at least one tag.";
+          if (tags.length > 3) return "Max 3 tags.";
+          return null;
+        }}
+      >
+        <TagInputHidden />
+      </Field>
+      <Button type="submit">Submit</Button>
+    </Form>
+  ),
+};
+
+/**
+ * **Approach 2 — native hidden input + `Form.onFormSubmit` (form-level validation).**
+ * The component renders `<input type="hidden" name={fieldName}>` — no
+ * `FieldControl` needed. `useFieldName` reads the name from parent `Field`
+ * context. Validation runs in `onFormSubmit`; errors route back via `Form.errors`.
+ *
+ * Best for: synchronous validation, cross-field rules, or when you want to
+ * keep the component decoupled from Field's validation lifecycle.
+ */
+export const CustomControlNativeInput: Story = {
+  render: () => {
+    const [errors, setErrors] = useState<Record<string, string>>({});
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        errors={errors}
+        onFormSubmit={(data) => {
+          const tags = JSON.parse(String(data.tags || "[]")) as string[];
+          if (!tags.length) {
+            setErrors({ tags: "Add at least one tag." });
+            return;
+          }
+          if (tags.length > 3) {
+            setErrors({ tags: "Max 3 tags." });
+            return;
+          }
+          setErrors({});
+        }}
+      >
+        <Field
+          name="tags"
+          label="Tags"
+          description="1–3 tags. Submit to validate."
+        >
+          <TagInputNative />
+        </Field>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};