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

package/src/components/empty/empty.tsx

@@ -0,0 +1,156 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { Inbox } from "lucide-react";
+import { type ComponentProps, type ReactNode } from "react";
+import { cn } from "../../lib";
+
+const emptyMediaVariants = cva(
+  "mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-transparent text-muted-foreground [&_.lucide:not([class*='size-'])]:size-12",
+        icon: "size-8 rounded-lg bg-muted text-foreground [&_.lucide:not([class*='size-'])]:size-4",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+export function EmptyRoot({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-xl p-6 text-center text-balance",
+        className,
+      )}
+      data-slot="empty"
+      {...props}
+    />
+  );
+}
+
+export function EmptyHeader({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("flex max-w-sm flex-col items-center gap-2", className)}
+      data-slot="empty-header"
+      {...props}
+    />
+  );
+}
+
+export function EmptyMedia({
+  className,
+  variant,
+  ...props
+}: ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
+  return (
+    <div
+      className={cn(emptyMediaVariants({ variant }), className)}
+      data-slot="empty-media"
+      data-variant={variant ?? "default"}
+      {...props}
+    />
+  );
+}
+
+export function EmptyTitle({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-title"
+      className={cn(
+        "cn-font-heading text-sm font-medium tracking-tight",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function EmptyDescription({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
+        className,
+      )}
+      data-slot="empty-description"
+      {...props}
+    />
+  );
+}
+
+export function EmptyContent({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5",
+        className,
+      )}
+      data-slot="empty-content"
+      {...props}
+    />
+  );
+}
+
+interface EmptyProps extends Omit<ComponentProps<typeof EmptyRoot>, "title"> {
+  icon?: ReactNode;
+  iconVariant?: VariantProps<typeof emptyMediaVariants>["variant"];
+  title?: ReactNode;
+  description?: ReactNode;
+  action?: ReactNode;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Wrapper around media, title and description. */
+    header?: string;
+    /** Box that frames the icon (chip when `iconVariant="icon"`). */
+    media?: string;
+    /** Title text. */
+    title?: string;
+    /** Description text below the title. */
+    description?: string;
+    /** Wrapper around the `action` slot. */
+    content?: string;
+  };
+}
+
+export function Empty({
+  icon = <Inbox />,
+  iconVariant = "default",
+  title = "No hay datos",
+  description,
+  action,
+  children,
+  classNames,
+  ...props
+}: EmptyProps) {
+  return (
+    <EmptyRoot {...props}>
+      <EmptyHeader className={classNames?.header}>
+        {icon && (
+          <EmptyMedia variant={iconVariant} className={classNames?.media}>
+            {icon}
+          </EmptyMedia>
+        )}
+        {title && (
+          <EmptyTitle className={classNames?.title}>{title}</EmptyTitle>
+        )}
+        {description && (
+          <EmptyDescription className={classNames?.description}>
+            {description}
+          </EmptyDescription>
+        )}
+      </EmptyHeader>
+      {action != null && (
+        <EmptyContent className={classNames?.content}>{action}</EmptyContent>
+      )}
+      {children}
+    </EmptyRoot>
+  );
+}

package/src/components/empty/index.ts

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

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

@@ -1,5 +1,8 @@
 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";
@@ -12,6 +15,7 @@ import {
   FieldLabel,
   FieldRoot,
   FieldValidity,
+  useFieldName,
 } from "./field";
 
 /**
@@ -48,9 +52,7 @@ const meta: Meta<typeof Field> = {
   },
   argTypes: {
     children: { control: false },
-    labelProps: { control: false },
-    descriptionProps: { control: false },
-    errorProps: { control: false },
+    classNames: { control: false },
     error: { control: false },
   },
 };
@@ -60,6 +62,21 @@ 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" />,
@@ -221,3 +238,209 @@ export const Primitive: Story = {
     </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>
+    );
+  },
+};

package/src/components/field/field.tsx

@@ -1,5 +1,6 @@
 import { Field as FieldPrimitive } from "@base-ui/react/field";
-import { type ReactNode } from "react";
+import { Fieldset as FieldsetPrimitive } from "@base-ui/react/fieldset";
+import { createContext, type ReactNode, useContext } from "react";
 import { cn } from "../../lib";
 import { Label } from "../label";
 
@@ -16,18 +17,34 @@ export type FieldErrorProp = string | FieldErrorItem | FieldErrorItem[];
 
 // ── Primitives ────────────────────────────────────────────────────────────────
 
+const FieldNameContext = createContext<string | undefined>(undefined);
+export function useFieldName(): string | undefined {
+  return useContext(FieldNameContext);
+}
+
+const FieldRootPresentContext = createContext(false);
+export function useIsInsideFieldRoot(): boolean {
+  return useContext(FieldRootPresentContext);
+}
+
 export function FieldRoot({
   className,
   required,
+  name,
   ...props
 }: FieldPrimitive.Root.Props & { required?: boolean }) {
   return (
-    <FieldPrimitive.Root
-      className={cn("group flex flex-col gap-1", className)}
-      data-slot="field"
-      data-required={required || undefined}
-      {...props}
-    />
+    <FieldRootPresentContext.Provider value={true}>
+      <FieldNameContext.Provider value={name}>
+        <FieldPrimitive.Root
+          name={name}
+          className={cn("group flex flex-col gap-1", className)}
+          data-slot="field"
+          data-required={required || undefined}
+          {...props}
+        />
+      </FieldNameContext.Provider>
+    </FieldRootPresentContext.Provider>
   );
 }
 
@@ -91,9 +108,37 @@ export const FieldControl: typeof FieldPrimitive.Control =
 export const FieldValidity: typeof FieldPrimitive.Validity =
   FieldPrimitive.Validity;
 
+export function FieldSet({
+  className,
+  ...props
+}: FieldsetPrimitive.Root.Props) {
+  return (
+    <FieldsetPrimitive.Root
+      className={cn("flex flex-col gap-3", className)}
+      data-slot="fieldset"
+      {...props}
+    />
+  );
+}
+
+export function FieldLegend({
+  className,
+  ...props
+}: FieldsetPrimitive.Legend.Props) {
+  return (
+    <FieldsetPrimitive.Legend
+      className={cn("text-sm font-medium leading-none", className)}
+      data-slot="fieldset-legend"
+      {...props}
+    />
+  );
+}
+
 // ── Composite ─────────────────────────────────────────────────────────────────
 
-function normalizeError(error: FieldErrorProp | undefined): FieldErrorItem[] {
+export function normalizeError(
+  error: FieldErrorProp | undefined,
+): FieldErrorItem[] {
   if (error === undefined) return [];
   if (typeof error === "string") return [{ message: error, match: true }];
   if (Array.isArray(error)) return error;
@@ -123,13 +168,15 @@ export interface FieldProps
    */
   inline?: boolean;
   children?: ReactNode;
-  // Escape hatches for each sub-component
-  labelProps?: FieldPrimitive.Label.Props;
-  labelClassName?: string;
-  descriptionProps?: FieldPrimitive.Description.Props;
-  descriptionClassName?: string;
-  errorProps?: Omit<FieldPrimitive.Error.Props, "match" | "children">;
-  errorClassName?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Label rendered above (or beside, when `inline`) the control. */
+    label?: string;
+    /** Helper text below the control. */
+    description?: string;
+    /** Error message rendered when the field is invalid. */
+    error?: string;
+  };
 }
 
 export function Field({
@@ -141,12 +188,7 @@ export function Field({
   inline = false,
   children,
   className,
-  labelProps,
-  labelClassName,
-  descriptionProps,
-  descriptionClassName,
-  errorProps,
-  errorClassName,
+  classNames,
   invalid,
   ...rootProps
 }: FieldProps) {
@@ -158,8 +200,7 @@ export function Field({
   const labelNode = label && (
     <FieldLabel
       render={tooltip ? <Label tooltip={tooltip} /> : undefined}
-      className={labelClassName}
-      {...labelProps}
+      className={classNames?.label}
     >
       <span className="after:text-error group-has-[*:required]:after:content-['*'] group-data-[required]:after:content-['*']">
         {label}
@@ -186,36 +227,30 @@ export function Field({
         </>
       )}
       {description && (
-        <FieldDescription
-          className={descriptionClassName}
-          {...descriptionProps}
-        >
+        <FieldDescription className={classNames?.description}>
           {description}
         </FieldDescription>
       )}
       {errors.map((item, i) => (
-        <FieldError
-          key={i}
-          match={item.match}
-          className={errorClassName}
-          {...errorProps}
-        >
+        <FieldError key={i} match={item.match} className={classNames?.error}>
           {item.message}
         </FieldError>
       ))}
-      {/* Catch-all for server errors propagated via `Form.errors` (React context,
-          not `setCustomValidity`). When all user errors have a `match`, none of
-          them fire for server-side errors — render a plain `FieldError` guarded
-          by `FieldValidity` so it only shows when the field is invalid AND native
-          validation passed (validity.error === ""). */}
+      {/* Catch-all for errors not covered by any specific `match`:
+          - Server errors via `Form.errors`: field marked invalid externally,
+            validityData.error stays "" → caught by `error === ""`
+          - `Field.validate` errors: setCustomValidity(msg) → customError = true,
+            error = msg → caught by `validity.customError`
+          Native constraint failures have customError = false and are handled by
+          their specific `match` items, so this won't double-render them. */}
       {!errors.some((item) => item.match === undefined) &&
         (errors.length === 0 ? (
-          <FieldError {...errorProps} />
+          <FieldError className={classNames?.error} />
         ) : (
           <FieldValidity>
             {({ validity, error }) =>
-              !validity.valid && error === "" ? (
-                <FieldError {...errorProps} />
+              !validity.valid && (error === "" || validity.customError) ? (
+                <FieldError className={classNames?.error} />
               ) : null
             }
           </FieldValidity>
@@ -226,4 +261,4 @@ export function Field({
 
 // ── Primitive escape hatch ────────────────────────────────────────────────────
 
-export { FieldPrimitive };
+export { FieldPrimitive, FieldsetPrimitive };