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

package/src/components/combobox/index.ts

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

package/src/components/date-picker/date-input-form.test.tsx

@@ -0,0 +1,77 @@
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Button } from "../button/button";
+import { Field } from "../field/field";
+import { Form } from "../form/form";
+import { DateInput } from "./date-input";
+
+const setup = () => {
+  const onFormSubmit = vi.fn();
+  const user = userEvent.setup();
+  render(
+    <Form onFormSubmit={onFormSubmit}>
+      <Field
+        name="startDate"
+        label="Start date"
+        error={{ message: "Start date is required.", match: "valueMissing" }}
+      >
+        <DateInput required />
+      </Field>
+      <Button type="submit">Submit</Button>
+    </Form>,
+  );
+  return { onFormSubmit, user };
+};
+
+describe("DateInput + Form across flows", () => {
+  it("A: digits typed → submits iso", async () => {
+    const { onFormSubmit, user } = setup();
+    const input = screen.getByRole("textbox");
+    await user.click(input);
+    await user.type(input, "05062026");
+    await user.tab();
+    await user.click(screen.getByRole("button", { name: /submit/i }));
+    expect(onFormSubmit).toHaveBeenCalledTimes(1);
+    expect(onFormSubmit.mock.calls[0][0]).toMatchObject({
+      startDate: "2026-06-05",
+    });
+  });
+
+  it("B: open+close popover then digits → submits iso", async () => {
+    const { onFormSubmit, user } = setup();
+    await user.click(screen.getByRole("button", { name: "Seleccionar fecha" }));
+    await screen.findByRole("grid");
+    await user.keyboard("{Escape}");
+    const input = screen.getByRole("textbox");
+    await user.click(input);
+    await user.type(input, "05062026");
+    await user.tab();
+    await user.click(screen.getByRole("button", { name: /submit/i }));
+    expect(onFormSubmit).toHaveBeenCalledTimes(1);
+    expect(onFormSubmit.mock.calls[0][0]).toMatchObject({
+      startDate: "2026-06-05",
+    });
+  });
+
+  it("C: select from calendar → submits iso", async () => {
+    const { onFormSubmit, user } = setup();
+    await user.click(screen.getByRole("button", { name: "Seleccionar fecha" }));
+    const grid = await screen.findByRole("grid");
+    await user.click(
+      within(grid).getByRole("button", { name: /15 de junio de 2026/ }),
+    );
+    await user.click(screen.getByRole("button", { name: /submit/i }));
+    expect(onFormSubmit).toHaveBeenCalledTimes(1);
+    expect(onFormSubmit.mock.calls[0][0]).toMatchObject({
+      startDate: "2026-06-15",
+    });
+  });
+
+  it("D: empty → blocks submit with required error", async () => {
+    const { onFormSubmit, user } = setup();
+    await user.click(screen.getByRole("button", { name: /submit/i }));
+    expect(onFormSubmit).not.toHaveBeenCalled();
+    expect(screen.getByText("Start date is required.")).toBeInTheDocument();
+  });
+});

package/src/components/date-picker/date-input.stories.tsx

@@ -0,0 +1,178 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { lastDayOfMonth, nextSaturday } from "date-fns";
+import { useState } from "react";
+import { action } from "storybook/actions";
+import { Button, Field, Form } from "../../components";
+import { DateInput } from "./date-input";
+
+/**
+ * Typeable date field with `DD/MM/YYYY` auto-masking and a calendar popover.
+ * Built as a composite of an `<input>` and a `Popover`.
+ *
+ * Key behaviors:
+ * - The calendar icon button and **Spacebar** (while focused on the input) open the popover.
+ *   **Escape** closes it and reverts the text to the last committed value.
+ * - **Enter** or **blur** commits the typed text — invalid or empty input clears the field.
+ * - Short-year entry: `25` is normalised to `2025` on commit.
+ * - `disabledDate` enforces restrictions in both the calendar and the keyboard path:
+ *   if the user types a disabled date it is rejected and the last valid value is restored.
+ * - `aria-invalid` activates the error ring on the outer wrapper (not the inner `<input>`),
+ *   consistent with `Input`'s invalid state. Typically set by a wrapping `Field`.
+ * - Extends all native `<input>` HTML attributes: `name`, `required`, `autoComplete`, etc.
+ */
+const meta: Meta<typeof DateInput> = {
+  title: "Components/DateInput",
+  component: DateInput,
+  tags: ["new"],
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    onValueChange: action("onValueChange"),
+  },
+  argTypes: {
+    onValueChange: { control: false },
+    onBlur: { control: false },
+    disabledDate: { control: false },
+    renderFooter: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DateInput>;
+
+export const Default: Story = {};
+
+/**
+ * Pass `defaultValue` for one-shot initialisation without managing state.
+ * Use `value` + `onValueChange` for fully controlled usage.
+ */
+export const WithDefaultValue: Story = {
+  args: {
+    defaultValue: new Date(2025, 0, 15),
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * `aria-invalid` applies an error ring to the entire field wrapper.
+ * Typically injected by a parent `Field` rather than set directly.
+ */
+export const Invalid: Story = {
+  args: { "aria-invalid": true },
+};
+
+/**
+ * `disabledDate` blocks dates in both the calendar and the text input.
+ * If the user types a disabled date, the previous valid value is restored on blur or Enter.
+ */
+export const DisabledDates: Story = {
+  args: {
+    disabledDate: (date: Date) => date.getDay() === 0 || date.getDay() === 6,
+  },
+};
+
+/**
+ * `renderFooter` receives `{ value, clear, selectToday, setValue }`.
+ * The popover stays open while the user interacts with footer buttons.
+ * Selecting a date via `setValue` also updates the text input.
+ */
+export const WithFooter: Story = {
+  render: () => (
+    <DateInput
+      onValueChange={action("onValueChange")}
+      renderFooter={({ value, clear, selectToday, setValue }) => (
+        <div className="flex flex-col gap-2">
+          <Button variant="outline" size="sm" onClick={selectToday}>
+            Today
+          </Button>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setValue(nextSaturday(new Date()))}
+          >
+            Next Saturday
+          </Button>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setValue(lastDayOfMonth(new Date()))}
+          >
+            Last day of month
+          </Button>
+          <Button variant="error" size="sm" onClick={clear}>
+            Clear
+          </Button>
+          {value && (
+            <span className="text-xs text-muted-foreground">
+              {value.toLocaleDateString()}
+            </span>
+          )}
+        </div>
+      )}
+    />
+  ),
+};
+
+/**
+ * `value` + `onValueChange` make the field fully controlled. Updating `value`
+ * externally always syncs the text input and the calendar selection.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const [date, setDate] = useState<Date | null>(null);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DateInput value={date} onValueChange={setDate} />
+        <p className="text-sm text-muted-foreground">
+          {date ? date.toLocaleDateString() : "No selection"}
+        </p>
+        <Button variant="outline" size="sm" onClick={() => setDate(null)}>
+          Clear externally
+        </Button>
+      </div>
+    );
+  },
+};
+
+/**
+ * `Field` wires `required` validation and routes the error message automatically.
+ * The value submitted to the form is an ISO date string (`yyyy-MM-dd`);
+ * an empty field submits an empty string, which triggers `valueMissing`.
+ */
+export const WithForm: Story = {
+  render: () => {
+    const [submitted, setSubmitted] = useState<string | null>(null);
+
+    return (
+      <Form
+        className="flex flex-col gap-3"
+        onFormSubmit={(data) => setSubmitted(data.startDate as string)}
+      >
+        <Field
+          name="startDate"
+          label="Start date"
+          error={{ message: "Start date is required.", match: "valueMissing" }}
+        >
+          <DateInput required />
+        </Field>
+        <Button type="submit">Submit</Button>
+        {submitted !== null && (
+          <p className="text-sm text-muted-foreground">
+            Submitted:{" "}
+            <span className="font-mono">{submitted || "(empty)"}</span>
+          </p>
+        )}
+      </Form>
+    );
+  },
+};

package/src/components/date-picker/date-input.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import { format, isDate } from "date-fns";
+import { CalendarIcon } from "lucide-react";
+import { KeyboardEvent } from "react";
+import {
+  Calendar,
+  FieldControl,
+  FieldRoot,
+  inputBaseClasses,
+  PopoverPopup,
+  PopoverRoot,
+  PopoverTrigger,
+} from "../../components";
+import { cn } from "../../lib";
+import type { DateInputProps } from "./date-picker.model";
+import { useDateInput } from "./use-date-input";
+import { useDateInputPopover } from "./use-date-input-popover";
+import { useHiddenFieldValue } from "./use-hidden-field-value";
+
+export const DateInput = (props: DateInputProps) => {
+  const {
+    placeholder,
+    value: valueProp,
+    onValueChange,
+    defaultValue: defaultValueProp,
+    autoComplete,
+    className,
+    disabledDate,
+    renderFooter,
+    disabled,
+    onBlur: onBlurProp,
+    required,
+    ...rest
+  } = props;
+
+  const [selectedDate, setSelectedDate] = useControllableState<Date | null>({
+    prop: valueProp,
+    onChange: (nextValue) => onValueChange?.(nextValue ?? null),
+    defaultProp: defaultValueProp ?? null,
+  });
+
+  // Value handed to the form, derived from selectedDate. Empty string when no
+  // date so `required` triggers `valueMissing`.
+  const formValue = selectedDate ? format(selectedDate, "yyyy-MM-dd") : "";
+
+  const hiddenInputRef = useHiddenFieldValue(formValue);
+
+  const {
+    inputValue,
+    handleChange,
+    handleBlur,
+    handleKeyDown: handleInputKeyDown,
+    clear: clearInput,
+    setFromExternalDate,
+  } = useDateInput({
+    date: selectedDate ?? null,
+    onDateChange: (next) => setSelectedDate(next),
+    disabledDate,
+  });
+
+  const {
+    open,
+    setOpen,
+    handleInputKeyDown: handlePopoverKeyDown,
+    inputRef,
+  } = useDateInputPopover({ disabled });
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    handleInputKeyDown(event);
+    handlePopoverKeyDown(event);
+  };
+
+  const onClear = () => {
+    setFromExternalDate(null);
+    clearInput();
+  };
+
+  const onSelectToday = () => {
+    const today = new Date();
+    if (disabledDate?.(today)) return;
+    setFromExternalDate(today);
+  };
+
+  const footerContent = renderFooter?.({
+    value: selectedDate ?? null,
+    clear: onClear,
+    selectToday: onSelectToday,
+    setValue: (nextValue) => {
+      const next = nextValue && isDate(nextValue) ? nextValue : null;
+      setSelectedDate(next);
+      setFromExternalDate(next);
+    },
+  });
+
+  return (
+    <PopoverRoot data-slot="date-input" open={open} onOpenChange={setOpen}>
+      <div
+        className={cn(
+          inputBaseClasses,
+          "relative flex items-center gap-2 h-8",
+          "has-[:focus-visible]:border-ring",
+          "aria-invalid:border-error has-[:focus-visible]:aria-invalid:ring-error/20",
+          "has-aria-invalid:border-error has-[:focus-visible]:has-aria-invalid:border-error has-[:focus-visible]:has-aria-invalid:ring-error/20",
+          "has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50",
+          !selectedDate && "text-muted-foreground",
+          className,
+          "field-error",
+        )}
+        data-slot="date-input-trigger"
+        onClick={(e) => {
+          if (e.target === e.currentTarget) inputRef.current?.focus();
+        }}
+      >
+        {/* Hidden form control — owns the Field's name + validity. Left
+            uncontrolled and driven imperatively via `emitNativeInputChange`: a
+            controlled `value` keeps React's value tracker in sync, which would
+            suppress the synthetic `input` event Base UI needs to re-validate.
+            `onFocus` redirects to the visible input so that when the Form focuses
+            the invalid control on submit, focus does not trap on this sr-only node. */}
+        <FieldControl
+          render={
+            <input
+              ref={hiddenInputRef}
+              type="text"
+              className="sr-only"
+              tabIndex={-1}
+              aria-hidden="true"
+              required={required}
+              disabled={disabled}
+              onFocus={() => inputRef.current?.focus()}
+            />
+          }
+        />
+        <input
+          type="text"
+          value={inputValue}
+          onChange={handleChange}
+          onBlur={(e) => {
+            handleBlur();
+            onBlurProp?.(e);
+          }}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder ?? "dd/mm/aaaa"}
+          autoComplete={autoComplete ?? "off"}
+          disabled={disabled}
+          className="flex-1 min-w-0 bg-transparent outline-none text-start truncate pt-px"
+          aria-label={placeholder}
+          ref={inputRef}
+          {...rest}
+        />
+        <PopoverTrigger
+          type="button"
+          disabled={disabled}
+          data-slot="date-input-calendar-trigger"
+          className="flex shrink-0 items-center justify-center text-muted-foreground hover:text-foreground"
+        >
+          <CalendarIcon data-slot="date-input-icon" />
+          <span className="sr-only">Seleccionar fecha</span>
+        </PopoverTrigger>
+      </div>
+      <PopoverPopup
+        className="w-auto p-0"
+        align="start"
+        data-slot="date-input-content"
+      >
+        {/* Isolate the popover content in its own FieldRoot. The Calendar's
+            month/year `Select`s are Base UI form controls; without this they
+            connect to the OUTER Field and hijack its shared validation ref,
+            nulling it on close and breaking submit validation. */}
+        <FieldRoot className="contents">
+          <Calendar
+            className="border-none"
+            mode="single"
+            selected={selectedDate ?? undefined}
+            onSelect={(next) => {
+              if (!next || !isDate(next)) {
+                setFromExternalDate(null);
+                return;
+              }
+              if (disabledDate?.(next)) return;
+              setFromExternalDate(next);
+              setOpen(false);
+            }}
+            disabled={disabledDate}
+          />
+          {footerContent && (
+            <div className="p-2" data-slot="date-input-footer">
+              {footerContent}
+            </div>
+          )}
+        </FieldRoot>
+      </PopoverPopup>
+    </PopoverRoot>
+  );
+};

package/src/components/date-picker/date-picker.model.ts

@@ -0,0 +1,99 @@
+import type { ComponentProps, ReactNode } from "react";
+
+export type DateRange = {
+  start: Date | null;
+  end: Date | null;
+};
+
+export type DatePickerMode = "single" | "range" | "multiple";
+
+type SingleFooterProps = {
+  mode: "single";
+  value: Date | null;
+  clear: () => void;
+  selectToday: () => void;
+  setValue: (value: Date | null) => void;
+};
+
+type RangeFooterProps = {
+  mode: "range";
+  value: DateRange;
+  clear: () => void;
+  setValue: (value: DateRange) => void;
+};
+
+type MultipleFooterProps = {
+  mode: "multiple";
+  value: Date[];
+  clear: () => void;
+  setValue: (value: Date[]) => void;
+};
+
+export type DatePickerFooterProps =
+  | SingleFooterProps
+  | RangeFooterProps
+  | MultipleFooterProps;
+
+type DatePickerBaseProps = {
+  disabled?: boolean;
+  disabledDate?: (date: Date) => boolean;
+  renderFooter?: (props: DatePickerFooterProps) => ReactNode;
+  className?: string;
+  required?: boolean;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Popup panel that opens below the trigger. */
+    popup?: string;
+    /** Calendar grid inside the popup. */
+    calendar?: string;
+    /** Footer wrapper rendered below the calendar when `renderFooter` is provided. */
+    footer?: string;
+  };
+};
+
+export type SingleDatePickerProps = DatePickerBaseProps & {
+  mode: "single";
+  value?: Date | null;
+  defaultValue?: Date | null;
+  onValueChange?: (value: Date | null) => void;
+  placeholder?: string;
+};
+
+export type RangeDatePickerProps = DatePickerBaseProps & {
+  mode: "range";
+  value?: DateRange;
+  defaultValue?: DateRange;
+  onValueChange?: (value: DateRange) => void;
+  placeholder?: string;
+};
+
+export type MultipleDatePickerProps = DatePickerBaseProps & {
+  mode: "multiple";
+  value?: Date[];
+  defaultValue?: Date[];
+  onValueChange?: (value: Date[]) => void;
+  placeholder?: string;
+};
+
+export type DatePickerProps =
+  | SingleDatePickerProps
+  | RangeDatePickerProps
+  | MultipleDatePickerProps;
+
+export type DateInputFooterProps = {
+  value: Date | null;
+  clear: () => void;
+  selectToday: () => void;
+  setValue: (value: Date | null) => void;
+};
+
+export type DateInputProps = Omit<
+  ComponentProps<"input">,
+  "value" | "onChange" | "defaultValue"
+> & {
+  value?: Date | null;
+  defaultValue?: Date | null;
+  onValueChange?: (value: Date | null) => void;
+  disabledDate?: (date: Date) => boolean;
+  renderFooter?: (props: DateInputFooterProps) => ReactNode;
+};