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

package/src/components/combobox/index.ts

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

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

@@ -0,0 +1,158 @@
+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 } 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,
+  parameters: { layout: "centered" },
+  args: {
+    onChange: action("onChange"),
+  },
+  argTypes: {
+    onChange: { 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` + `onChange` 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
+      onChange={action("onChange")}
+      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` + `onChange` 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} onChange={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>
+    );
+  },
+};
+
+/**
+ * `name` and `required` enable native form participation.
+ * The value included in `FormData` is the date string in `DD/MM/YYYY` format.
+ * An empty field submits an empty string for the key.
+ */
+export const NativeForm: Story = {
+  render: () => (
+    <form
+      className="flex flex-col gap-2"
+      onSubmit={(e: React.FormEvent<HTMLFormElement>) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        alert(`date: ${data.get("date")}`);
+      }}
+    >
+      <DateInput name="date" required />
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+};

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

@@ -0,0 +1,163 @@
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import { isDate } from "date-fns";
+import { CalendarIcon } from "lucide-react";
+import { KeyboardEvent } from "react";
+import {
+  Calendar,
+  FieldControl,
+  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";
+
+export const DateInput = (props: DateInputProps) => {
+  const {
+    placeholder,
+    value: valueProp,
+    onChange,
+    defaultValue: defaultValueProp,
+    autoComplete,
+    className,
+    disabledDate,
+    renderFooter,
+    disabled,
+    onBlur: onBlurProp,
+    ...rest
+  } = props;
+
+  const [selectedDate, setSelectedDate] = useControllableState<Date | null>({
+    prop: valueProp,
+    onChange: (nextValue) => onChange?.(nextValue ?? null),
+    defaultProp: defaultValueProp ?? null,
+  });
+
+  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,
+          "flex items-center gap-2 h-10",
+          "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:ring-error/20",
+          "has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50",
+          !selectedDate && "text-muted-foreground",
+          className,
+          "field-error",
+        )}
+        onClick={(e) => {
+          if (e.target === e.currentTarget) inputRef.current?.focus();
+        }}
+      >
+        <PopoverTrigger
+          type="button"
+          disabled={disabled}
+          data-slot="date-input-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>
+        <FieldControl
+          render={
+            <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}
+            />
+          }
+        />
+      </div>
+      <PopoverPopup
+        className="w-auto p-0"
+        align="start"
+        data-slot="date-input-content"
+      >
+        <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>
+        )}
+      </PopoverPopup>
+    </PopoverRoot>
+  );
+};

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

@@ -0,0 +1,90 @@
+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;
+};
+
+export type SingleDatePickerProps = DatePickerBaseProps & {
+  mode: "single";
+  value?: Date | null;
+  defaultValue?: Date | null;
+  onChange?: (value: Date | null) => void;
+  placeholder?: string;
+};
+
+export type RangeDatePickerProps = DatePickerBaseProps & {
+  mode: "range";
+  value?: DateRange;
+  defaultValue?: DateRange;
+  onChange?: (value: DateRange) => void;
+  placeholder?: string;
+};
+
+export type MultipleDatePickerProps = DatePickerBaseProps & {
+  mode: "multiple";
+  value?: Date[];
+  defaultValue?: Date[];
+  onChange?: (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;
+  onChange?: (value: Date | null) => void;
+  disabledDate?: (date: Date) => boolean;
+  renderFooter?: (props: DateInputFooterProps) => ReactNode;
+};

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

@@ -0,0 +1,200 @@
+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 } from "../../components";
+import { DatePicker } from "./date-picker";
+import type { DatePickerFooterProps, DateRange } from "./date-picker.model";
+
+/**
+ * Trigger button that opens a calendar in a `Popover`. Supports three modes
+ * via a discriminated union on `mode`:
+ *
+ * - `"single"` — selects one `Date | null`
+ * - `"range"` — selects `DateRange = { start: Date | null; end: Date | null }`
+ * - `"multiple"` — selects `Date[]`
+ *
+ * The types of `value`, `defaultValue`, and `onChange` are **inferred from `mode`** —
+ * TypeScript will error if `mode="range"` is paired with a `Date | null` value.
+ *
+ * `renderFooter` receives a mode-discriminated prop bag. Always narrow `mode` before
+ * accessing `selectToday` or single-mode `setValue`, which only exist in `"single"`.
+ */
+const meta: Meta<typeof DatePicker> = {
+  title: "Components/DatePicker",
+  component: DatePicker,
+  parameters: { layout: "centered" },
+  args: {
+    mode: "single",
+    onChange: action("onChange"),
+  },
+  argTypes: {
+    onChange: { control: false },
+    disabledDate: { control: false },
+    renderFooter: { control: false },
+    value: { control: false },
+    defaultValue: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DatePicker>;
+
+export const Default: Story = {};
+
+/**
+ * Pass `defaultValue` for one-shot initialisation without managing state.
+ * Use `value` + `onChange` for fully controlled usage.
+ */
+export const WithDefaultValue: Story = {
+  args: {
+    defaultValue: new Date(2025, 0, 15),
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * Dates matching the predicate are visually dimmed and unselectable.
+ * Clicking a disabled day has no effect on the current value.
+ */
+export const DisabledDates: Story = {
+  args: {
+    disabledDate: (date: Date) => date.getDay() === 0 || date.getDay() === 6,
+  },
+};
+
+/**
+ * Selects a contiguous date range. The first click sets `start`, the second
+ * sets `end`. A third click resets `start` and begins a new range.
+ * `value` and `onChange` use `DateRange = { start: Date | null; end: Date | null }`.
+ */
+export const Range: Story = {
+  args: { mode: "range", onChange: action("onChange") },
+};
+
+/**
+ * Selects multiple non-contiguous dates. Each click toggles the day on or off.
+ * `value` and `onChange` use `Date[]`.
+ */
+export const Multiple: Story = {
+  args: { mode: "multiple", onChange: action("onChange") },
+};
+
+/**
+ * `value` + `onChange` make the picker fully controlled. Setting `value`
+ * externally always updates the trigger label.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const [date, setDate] = useState<Date | null>(null);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DatePicker mode="single" value={date} onChange={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>
+    );
+  },
+};
+
+/**
+ * Range controlled state requires `DateRange`.
+ * The first click sets `start`, the second sets `end`.
+ * A third click starts a new range from the clicked date.
+ */
+export const ControlledRange: Story = {
+  render: () => {
+    const [range, setRange] = useState<DateRange>({ start: null, end: null });
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DatePicker mode="range" value={range} onChange={setRange} />
+        <p className="text-sm text-muted-foreground">
+          {range.start?.toLocaleDateString() ?? "—"} →{" "}
+          {range.end?.toLocaleDateString() ?? "—"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * Multiple controlled state. The array grows or shrinks on every click.
+ */
+export const ControlledMultiple: Story = {
+  render: () => {
+    const [dates, setDates] = useState<Date[]>([]);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <DatePicker mode="multiple" value={dates} onChange={setDates} />
+        <p className="text-sm text-muted-foreground">
+          {dates.length > 0
+            ? dates.map((d) => d.toLocaleDateString()).join(", ")
+            : "No selection"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * `renderFooter` receives a mode-discriminated object — always narrow `mode` first.
+ * `selectToday` and `setValue(Date | null)` are only available in `"single"` mode.
+ * Range and multiple expose only `clear` and `setValue` typed to their own value shape.
+ *
+ * ```tsx
+ * renderFooter={(props) => {
+ *   if (props.mode !== "single") return null;
+ *   return <Button onClick={props.selectToday}>Today</Button>;
+ * }}
+ * ```
+ */
+export const WithFooter: Story = {
+  render: () => {
+    const Footer = (props: DatePickerFooterProps) => {
+      if (props.mode !== "single") return null;
+      const { value, clear, selectToday, setValue } = props;
+
+      return (
+        <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>
+      );
+    };
+
+    return <DatePicker mode="single" renderFooter={Footer} />;
+  },
+};

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

@@ -0,0 +1,23 @@
+import { render } from "@testing-library/react";
+import { describe, it } from "vitest";
+import { DateInput, DatePicker } from "../../components";
+
+describe("DatePicker component", () => {
+  it("should render single mode", () => {
+    render(<DatePicker mode="single" />);
+  });
+
+  it("should render range mode", () => {
+    render(<DatePicker mode="range" />);
+  });
+
+  it("should render multiple mode", () => {
+    render(<DatePicker mode="multiple" />);
+  });
+});
+
+describe("DateInput component", () => {
+  it("should render correctly", () => {
+    render(<DateInput name="date" />);
+  });
+});