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

package/src/components/combobox/combobox.tsx

@@ -3,6 +3,7 @@ import { Field as FieldPrimitive } from "@base-ui/react/field";
 import { ChevronsUpDownIcon, XIcon } from "lucide-react";
 import * as React from "react";
 import { cn } from "../../lib";
+import { useIsInsideFieldRoot } from "../field";
 import { Input, inputBaseClasses } from "../input";
 import { ScrollArea } from "../scroll-area";
 
@@ -25,15 +26,12 @@ export function ComboboxRoot<
   Value,
   Multiple extends boolean | undefined = false,
 >({
-  onChange,
   ...props
-}: Omit<ComboboxPrimitive.Root.Props<Value, Multiple>, "onValueChange"> & {
-  onChange?: ComboboxPrimitive.Root.Props<Value, Multiple>["onValueChange"];
-}): React.ReactElement {
+}: ComboboxPrimitive.Root.Props<Value, Multiple>): React.ReactElement {
   const chipsRef = React.useRef<Element | null>(null);
   return (
     <ComboboxContext.Provider value={{ chipsRef, multiple: !!props.multiple }}>
-      <ComboboxPrimitive.Root onValueChange={onChange} {...props} />
+      <ComboboxPrimitive.Root {...props} />
     </ComboboxContext.Provider>
   );
 }
@@ -95,12 +93,7 @@ export function ComboboxInput({
         )}
         data-slot="combobox-input"
         render={(props) => (
-          <Input
-            className="has-disabled:opacity-100"
-            nativeInput
-            {...props}
-            onChange={(_, event) => props?.onChange?.(event)}
-          />
+          <Input className="has-disabled:opacity-100" nativeInput {...props} />
         )}
         {...props}
       />
@@ -486,37 +479,44 @@ export function ComboboxChips({
   startAddon?: React.ReactNode;
 }): React.ReactElement {
   const { chipsRef } = React.useContext(ComboboxContext);
+  const insideField = useIsInsideFieldRoot();
 
-  return (
-    <FieldPrimitive.Validity>
-      {({ validity }) => (
-        <ComboboxPrimitive.Chips
-          aria-invalid={validity.valid === false ? true : undefined}
-          className={cn(
-            inputBaseClasses,
-            "relative inline-flex pr-6 w-full flex-wrap gap-1",
-            "placeholder:text-muted-foreground",
-            "focus-within:border-ring",
-            "aria-invalid:border-error focus-within:aria-invalid:ring-error/20",
-            "has-disabled:cursor-not-allowed has-disabled:opacity-50",
-            className,
-          )}
-          data-slot="combobox-chips"
-          ref={chipsRef as React.Ref<HTMLDivElement> | null}
-          {...props}
+  const renderChips = (ariaInvalid: true | undefined) => (
+    <ComboboxPrimitive.Chips
+      aria-invalid={ariaInvalid}
+      className={cn(
+        inputBaseClasses,
+        "relative inline-flex pr-6 w-full flex-wrap gap-1",
+        "placeholder:text-muted-foreground",
+        "focus-within:border-ring",
+        "aria-invalid:border-error focus-within:aria-invalid:ring-error/20",
+        "has-disabled:cursor-not-allowed has-disabled:opacity-50",
+        className,
+      )}
+      data-slot="combobox-chips"
+      ref={chipsRef as React.Ref<HTMLDivElement> | null}
+      {...props}
+    >
+      {startAddon && (
+        <div
+          aria-hidden="true"
+          className="flex shrink-0 items-center ps-2 opacity-80 has-[+[data-slot=combobox-chip]]:pe-2 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:-ms-0.5 [&_svg]:-me-1.5"
+          data-slot="combobox-start-addon"
         >
-          {startAddon && (
-            <div
-              aria-hidden="true"
-              className="flex shrink-0 items-center ps-2 opacity-80 has-[+[data-slot=combobox-chip]]:pe-2 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:-ms-0.5 [&_svg]:-me-1.5"
-              data-slot="combobox-start-addon"
-            >
-              {startAddon}
-            </div>
-          )}
-          {children}
-        </ComboboxPrimitive.Chips>
+          {startAddon}
+        </div>
       )}
+      {children}
+    </ComboboxPrimitive.Chips>
+  );
+
+  if (!insideField) return renderChips(undefined);
+
+  return (
+    <FieldPrimitive.Validity>
+      {({ validity }) =>
+        renderChips(validity.valid === false ? true : undefined)
+      }
     </FieldPrimitive.Validity>
   );
 }
@@ -642,11 +642,11 @@ function useChipOverflow(
 function ComboboxMultipleChipsContent({
   value,
   getLabel,
-  getValue,
+  getId,
 }: {
   value: unknown[];
   getLabel: (item: unknown) => string;
-  getValue: (item: unknown) => string;
+  getId: (item: unknown) => string;
 }): React.ReactElement {
   const { chipsRef } = React.useContext(ComboboxContext);
   const { visibleCount, isMeasuring } = useChipOverflow(value.length, chipsRef);
@@ -657,7 +657,7 @@ function ComboboxMultipleChipsContent({
   return (
     <>
       {visibleItems.map((item) => (
-        <ComboboxChip key={getValue(item)} aria-label={getLabel(item)}>
+        <ComboboxChip key={getId(item)} aria-label={getLabel(item)}>
           {getLabel(item)}
         </ComboboxChip>
       ))}
@@ -675,103 +675,117 @@ function ComboboxMultipleChipsContent({
 function defaultGetLabel(item: unknown): string {
   if (item == null) return "";
   if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object" && "label" in item)
-    return String((item as Record<string, unknown>).label);
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("label" in record) return String(record.label);
+    if ("name" in record) return String(record.name);
+    if ("title" in record) return String(record.title);
+  }
   return String(item);
 }
 
-function defaultGetValue(item: unknown): string {
+function defaultGetId(item: unknown): string {
   if (item == null) return "";
   if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object" && "value" in item)
-    return String((item as Record<string, unknown>).value);
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("id" in record) return String(record.id);
+    if ("value" in record) return String(record.value);
+  }
   return String(item);
 }
 
 function ComboboxSingleTrigger({
   placeholder,
   showClear,
-  inputProps,
+  startAddon,
+  className,
 }: {
   placeholder?: string;
   showClear?: boolean;
-  inputProps?: React.ComponentProps<typeof ComboboxInput>;
+  startAddon?: React.ReactNode;
+  className?: string;
 }): React.ReactElement {
   return (
     <ComboboxInput
+      className={className}
       placeholder={placeholder}
       showClear={showClear}
-      {...inputProps}
+      startAddon={startAddon}
     />
   );
 }
 
 function ComboboxMultipleTrigger({
   getLabel,
-  getValue,
-  chipsProps,
+  getId,
   showClear,
-  clearProps,
+  startAddon,
+  className,
 }: {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   getLabel: (item: any) => string;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  getValue: (item: any) => string;
-  chipsProps?: React.ComponentProps<typeof ComboboxChips>;
+  getId: (item: any) => string;
   showClear?: boolean;
-  clearProps?: ComboboxPrimitive.Clear.Props;
+  startAddon?: React.ReactNode;
+  className?: string;
 }): React.ReactElement {
   return (
-    <ComboboxChips {...chipsProps}>
+    <ComboboxChips className={className} startAddon={startAddon}>
       <ComboboxValue>
         {(value: unknown[]) => (
           <ComboboxMultipleChipsContent
             value={value}
             getLabel={getLabel}
-            getValue={getValue}
+            getId={getId}
           />
         )}
       </ComboboxValue>
-      <ComboboxEndAdornment
-        showTrigger={!showClear}
-        showClear={showClear}
-        clearProps={clearProps}
-      />
+      <ComboboxEndAdornment showTrigger={!showClear} showClear={showClear} />
     </ComboboxChips>
   );
 }
 
-type ComboboxRootPropsAlias<V, M extends boolean | undefined = false> = Omit<
-  ComboboxPrimitive.Root.Props<V, M>,
-  "onValueChange"
-> & {
-  onChange?: ComboboxPrimitive.Root.Props<V, M>["onValueChange"];
-};
-
 type ComboboxBaseProps<TItem = unknown> = Omit<
-  ComboboxRootPropsAlias<TItem, boolean>,
+  ComboboxPrimitive.Root.Props<TItem, boolean>,
   | "items"
   | "itemToStringLabel"
   | "itemToStringValue"
   | "children"
   | "multiple"
-  | "onChange"
+  | "onValueChange"
   | "value"
   | "defaultValue"
 > & {
   items: readonly TItem[];
+  /** Returns the display text for an item. Used for filter matching, ARIA, and the trigger input. Defaults to `item.label`, `item.name`, `item.title`, or the stringified primitive. */
   getLabel?: (item: TItem) => string;
-  getValue?: (item: TItem) => string;
+  /** Returns a stable string identifier for an item. Used as the React key and as the hidden form value when `name` is set. Defaults to `item.id`, `item.value`, or the stringified primitive. */
+  getId?: (item: TItem) => string;
   renderItem?: (item: TItem) => React.ReactNode;
   placeholder?: string;
   emptyText?: string;
-  inputProps?: React.ComponentProps<typeof ComboboxInput>;
-  chipsProps?: React.ComponentProps<typeof ComboboxChips>;
-  chipsInputProps?: React.ComponentProps<typeof ComboboxChipsInput>;
-  popupProps?: React.ComponentProps<typeof ComboboxPopup>;
-  itemProps?: ComboboxPrimitive.Item.Props;
-  listProps?: Omit<ComboboxPrimitive.List.Props, "children">;
+  /** Icon or element displayed before the input text (single mode) or chips (multiple mode). */
+  startAddon?: React.ReactNode;
   showClear?: boolean;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Text input field in single-select mode. */
+    input?: string;
+    /** Chips container in multiple-select mode. */
+    chips?: string;
+    /** Search input inside the popup in multiple-select mode. */
+    chipsInput?: string;
+    /** Popup panel containing the item list. */
+    popup?: string;
+    /** Scrollable item list inside the popup. */
+    list?: string;
+    /** Individual item row. */
+    item?: string;
+    /** Rendered when no items match the search. */
+    empty?: string;
+  };
 };
 
 export type ComboboxProps<TItem = unknown> =
@@ -779,20 +793,20 @@ export type ComboboxProps<TItem = unknown> =
       multiple?: false;
       value?: TItem | null;
       defaultValue?: TItem | null;
-      onChange?: (value: TItem | null) => void;
+      onValueChange?: (value: TItem | null) => void;
     })
   | (ComboboxBaseProps<TItem> & {
       multiple: true;
       value?: TItem[];
       defaultValue?: TItem[];
-      onChange?: (value: TItem[]) => void;
+      onValueChange?: (value: TItem[]) => void;
     });
 
 /**
  * Composite combobox for single and multiple selection.
  *
- * Items shaped as `{ label, value }` or plain strings/numbers work with no
- * extra props. For other shapes, provide `getLabel` and/or `getValue`.
+ * Items shaped as `{ id, name }`, `{ label, value }`, or plain strings/numbers
+ * work with no extra props. For other shapes, provide `getLabel` and/or `getId`.
  *
  * In multiple mode, chips are fit dynamically based on the container width —
  * overflowing items show as "+N más". The popup anchors to the chips container automatically.
@@ -812,39 +826,35 @@ export function Combobox<TItem = unknown>(
   const {
     items,
     getLabel: getLabelProp,
-    getValue: getValueProp,
+    getId: getIdProp,
     renderItem,
     placeholder,
     emptyText = "Sin resultados.",
     multiple,
-    onChange,
+    onValueChange,
     value,
     defaultValue,
-    inputProps,
-    chipsProps,
-    chipsInputProps,
-    popupProps,
-    itemProps,
-    listProps,
+    startAddon,
+    classNames,
     showClear = true,
     ...rest
   } = allProps as ComboboxBaseProps<TItem> & {
     multiple?: boolean;
-    onChange?: (value: any, eventDetails?: any) => void;
+    onValueChange?: (value: any, eventDetails?: any) => void;
     value?: any;
     defaultValue?: any;
   };
 
   const getLabel: (item: TItem) => string = getLabelProp ?? defaultGetLabel;
-  const getValue: (item: TItem) => string = getValueProp ?? defaultGetValue;
+  const getId: (item: TItem) => string = getIdProp ?? defaultGetId;
 
   return (
     <ComboboxRoot
       items={items}
       itemToStringLabel={getLabel}
-      itemToStringValue={getValue}
+      itemToStringValue={getId}
       multiple={multiple as boolean}
-      onChange={onChange}
+      onValueChange={onValueChange}
       value={value}
       defaultValue={defaultValue}
       autoHighlight
@@ -854,33 +864,39 @@ export function Combobox<TItem = unknown>(
       {multiple ? (
         <ComboboxMultipleTrigger
           getLabel={getLabel}
-          getValue={getValue}
-          chipsProps={chipsProps}
+          getId={getId}
           showClear={showClear}
+          startAddon={startAddon}
+          className={classNames?.chips}
         />
       ) : (
         <ComboboxSingleTrigger
           placeholder={placeholder}
           showClear={showClear}
-          inputProps={inputProps}
+          startAddon={startAddon}
+          className={classNames?.input}
         />
       )}
-      <ComboboxPopup {...popupProps}>
+      <ComboboxPopup className={classNames?.popup}>
         {multiple && (
           <div
             className="border-b p-2"
             data-slot="combobox-chips-input-wrapper"
           >
             <ComboboxChipsInput
+              className={classNames?.chipsInput}
               placeholder={placeholder}
-              {...chipsInputProps}
             />
           </div>
         )}
-        <ComboboxEmpty>{emptyText}</ComboboxEmpty>
-        <ComboboxList {...listProps}>
+        <ComboboxEmpty className={classNames?.empty}>{emptyText}</ComboboxEmpty>
+        <ComboboxList className={classNames?.list}>
           {(item: TItem) => (
-            <ComboboxItem key={getValue(item)} value={item} {...itemProps}>
+            <ComboboxItem
+              key={getId(item)}
+              value={item}
+              className={classNames?.item}
+            >
               {renderItem ? renderItem(item) : getLabel(item)}
             </ComboboxItem>
           )}

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

@@ -23,12 +23,20 @@ import { DateInput } from "./date-input";
 const meta: Meta<typeof DateInput> = {
   title: "Components/DateInput",
   component: DateInput,
+  tags: ["new"],
   parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
   args: {
-    onChange: action("onChange"),
+    onValueChange: action("onValueChange"),
   },
   argTypes: {
-    onChange: { control: false },
+    onValueChange: { control: false },
     onBlur: { control: false },
     disabledDate: { control: false },
     renderFooter: { control: false },
@@ -42,7 +50,7 @@ export const Default: Story = {};
 
 /**
  * Pass `defaultValue` for one-shot initialisation without managing state.
- * Use `value` + `onChange` for fully controlled usage.
+ * Use `value` + `onValueChange` for fully controlled usage.
  */
 export const WithDefaultValue: Story = {
   args: {
@@ -80,7 +88,7 @@ export const DisabledDates: Story = {
 export const WithFooter: Story = {
   render: () => (
     <DateInput
-      onChange={action("onChange")}
+      onValueChange={action("onValueChange")}
       renderFooter={({ value, clear, selectToday, setValue }) => (
         <div className="flex flex-col gap-2">
           <Button variant="outline" size="sm" onClick={selectToday}>
@@ -115,7 +123,7 @@ export const WithFooter: Story = {
 };
 
 /**
- * `value` + `onChange` make the field fully controlled. Updating `value`
+ * `value` + `onValueChange` make the field fully controlled. Updating `value`
  * externally always syncs the text input and the calendar selection.
  */
 export const Controlled: Story = {
@@ -124,7 +132,7 @@ export const Controlled: Story = {
 
     return (
       <div className="flex flex-col gap-4">
-        <DateInput value={date} onChange={setDate} />
+        <DateInput value={date} onValueChange={setDate} />
         <p className="text-sm text-muted-foreground">
           {date ? date.toLocaleDateString() : "No selection"}
         </p>

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

@@ -19,7 +19,7 @@ export const DateInput = (props: DateInputProps) => {
   const {
     placeholder,
     value: valueProp,
-    onChange,
+    onValueChange,
     defaultValue: defaultValueProp,
     autoComplete,
     className,
@@ -32,7 +32,7 @@ export const DateInput = (props: DateInputProps) => {
 
   const [selectedDate, setSelectedDate] = useControllableState<Date | null>({
     prop: valueProp,
-    onChange: (nextValue) => onChange?.(nextValue ?? null),
+    onChange: (nextValue) => onValueChange?.(nextValue ?? null),
     defaultProp: defaultValueProp ?? null,
   });
 

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

@@ -40,13 +40,22 @@ type DatePickerBaseProps = {
   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;
-  onChange?: (value: Date | null) => void;
+  onValueChange?: (value: Date | null) => void;
   placeholder?: string;
 };
 
@@ -54,7 +63,7 @@ export type RangeDatePickerProps = DatePickerBaseProps & {
   mode: "range";
   value?: DateRange;
   defaultValue?: DateRange;
-  onChange?: (value: DateRange) => void;
+  onValueChange?: (value: DateRange) => void;
   placeholder?: string;
 };
 
@@ -62,7 +71,7 @@ export type MultipleDatePickerProps = DatePickerBaseProps & {
   mode: "multiple";
   value?: Date[];
   defaultValue?: Date[];
-  onChange?: (value: Date[]) => void;
+  onValueChange?: (value: Date[]) => void;
   placeholder?: string;
 };
 
@@ -84,7 +93,7 @@ export type DateInputProps = Omit<
 > & {
   value?: Date | null;
   defaultValue?: Date | null;
-  onChange?: (value: Date | null) => void;
+  onValueChange?: (value: Date | null) => void;
   disabledDate?: (date: Date) => boolean;
   renderFooter?: (props: DateInputFooterProps) => ReactNode;
 };

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

@@ -14,7 +14,7 @@ import type { DatePickerFooterProps, DateRange } from "./date-picker.model";
  * - `"range"` — selects `DateRange = { start: Date | null; end: Date | null }`
  * - `"multiple"` — selects `Date[]`
  *
- * The types of `value`, `defaultValue`, and `onChange` are **inferred from `mode`** —
+ * The types of `value`, `defaultValue`, and `onValueChange` 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
@@ -24,16 +24,28 @@ const meta: Meta<typeof DatePicker> = {
   title: "Components/DatePicker",
   component: DatePicker,
   parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
   args: {
     mode: "single",
-    onChange: action("onChange"),
+    onValueChange: action("onValueChange"),
   },
   argTypes: {
-    onChange: { control: false },
+    mode: {
+      control: { type: "radio" },
+      options: ["single", "range", "multiple"],
+    },
+    onValueChange: { control: false },
     disabledDate: { control: false },
     renderFooter: { control: false },
     value: { control: false },
     defaultValue: { control: false },
+    classNames: { control: false },
   },
 };
 
@@ -42,9 +54,23 @@ type Story = StoryObj<typeof DatePicker>;
 
 export const Default: Story = {};
 
+/**
+ * `className` styles the trigger button. `classNames` exposes the
+ * `popup`, `calendar`, and `footer` slots.
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "w-60",
+    classNames: {
+      popup: "shadow-lg",
+      calendar: "p-3",
+    },
+  },
+};
+
 /**
  * Pass `defaultValue` for one-shot initialisation without managing state.
- * Use `value` + `onChange` for fully controlled usage.
+ * Use `value` + `onValueChange` for fully controlled usage.
  */
 export const WithDefaultValue: Story = {
   args: {
@@ -69,22 +95,22 @@ export const DisabledDates: Story = {
 /**
  * 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 }`.
+ * `value` and `onValueChange` use `DateRange = { start: Date | null; end: Date | null }`.
  */
 export const Range: Story = {
-  args: { mode: "range", onChange: action("onChange") },
+  args: { mode: "range", onValueChange: action("onValueChange") },
 };
 
 /**
  * Selects multiple non-contiguous dates. Each click toggles the day on or off.
- * `value` and `onChange` use `Date[]`.
+ * `value` and `onValueChange` use `Date[]`.
  */
 export const Multiple: Story = {
-  args: { mode: "multiple", onChange: action("onChange") },
+  args: { mode: "multiple", onValueChange: action("onValueChange") },
 };
 
 /**
- * `value` + `onChange` make the picker fully controlled. Setting `value`
+ * `value` + `onValueChange` make the picker fully controlled. Setting `value`
  * externally always updates the trigger label.
  */
 export const Controlled: Story = {
@@ -93,7 +119,7 @@ export const Controlled: Story = {
 
     return (
       <div className="flex flex-col gap-4">
-        <DatePicker mode="single" value={date} onChange={setDate} />
+        <DatePicker mode="single" value={date} onValueChange={setDate} />
         <p className="text-sm text-muted-foreground">
           {date ? date.toLocaleDateString() : "No selection"}
         </p>
@@ -116,7 +142,7 @@ export const ControlledRange: Story = {
 
     return (
       <div className="flex flex-col gap-4">
-        <DatePicker mode="range" value={range} onChange={setRange} />
+        <DatePicker mode="range" value={range} onValueChange={setRange} />
         <p className="text-sm text-muted-foreground">
           {range.start?.toLocaleDateString() ?? "—"} →{" "}
           {range.end?.toLocaleDateString() ?? "—"}
@@ -135,7 +161,7 @@ export const ControlledMultiple: Story = {
 
     return (
       <div className="flex flex-col gap-4">
-        <DatePicker mode="multiple" value={dates} onChange={setDates} />
+        <DatePicker mode="multiple" value={dates} onValueChange={setDates} />
         <p className="text-sm text-muted-foreground">
           {dates.length > 0
             ? dates.map((d) => d.toLocaleDateString()).join(", ")