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

package/src/components/menu/menu.tsx

@@ -1,100 +1,192 @@
-import React, { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+"use client";
+import * as React from "react";
+import { cn } from "../../lib";
 import {
   MenuCheckboxItem,
-  MenuContent,
+  MenuGroup,
   MenuItem,
   MenuLabel,
+  MenuPopup,
+  MenuRadioGroup,
   MenuRadioItem,
   MenuRoot,
   MenuSeparator,
   MenuShortcut,
+  MenuSub,
+  MenuSubContent,
   MenuSubTrigger,
   MenuTrigger,
 } from "./menu-primitives";
-import { renderMenuItem } from "./util/render-menu-item";
 
-type MenuShortcutProps = ComponentPropsWithoutRef<typeof MenuShortcut>;
-
-type Shortcut = Partial<{
-  shortcut: MenuShortcutProps["keys"];
-  onShortcut: MenuShortcutProps["handler"];
-  shortcutOptions: MenuShortcutProps["options"];
-}>;
-
-type MenuItemBase<T extends ElementType> = ComponentPropsWithoutRef<T> & {
-  label?: ReactNode;
-  type: string;
-} & Shortcut;
-
-type MenuItemItem = MenuItemBase<typeof MenuItem> & {
+type MenuItemItem = {
   type: "item";
-};
-type MenuItemCheckbox = MenuItemBase<typeof MenuCheckboxItem> & {
+  label: React.ReactNode;
+  shortcut?: string;
+} & Omit<React.ComponentProps<typeof MenuItem>, "children">;
+
+type MenuItemCheckbox = {
   type: "checkbox";
-};
+  label: React.ReactNode;
+  shortcut?: string;
+} & Omit<React.ComponentProps<typeof MenuCheckboxItem>, "children">;
 
-type MenuItemRadio = MenuItemBase<typeof MenuRadioItem> & {
+type MenuItemRadio = {
   type: "radio";
+  label: React.ReactNode;
+  shortcut?: string;
+} & Omit<React.ComponentProps<typeof MenuRadioItem>, "children">;
+
+type MenuItemRadioGroup = {
+  type: "radio-group";
+  value?: string;
+  onValueChange?: (value: string) => void;
+  items: MenuItemRadio[];
 };
-type MenuItemLabel = MenuItemBase<typeof MenuLabel> & {
+
+type MenuItemLabel = {
   type: "label";
-};
+  label: React.ReactNode;
+} & Omit<React.ComponentProps<typeof MenuLabel>, "children">;
 
-type MenuItemSeparator = MenuItemBase<typeof MenuSeparator> & {
+type MenuItemSeparator = {
   type: "separator";
+} & React.ComponentProps<typeof MenuSeparator>;
+
+type MenuItemGroup = {
+  type: "group";
+  label?: React.ReactNode;
+  items: MenuItemType[];
 };
 
-type MenuItemSubmenu = MenuItemBase<typeof MenuSubTrigger> & {
+type MenuItemSubmenu = {
   type: "submenu";
+  label: React.ReactNode;
   items: MenuItemType[];
-};
+} & Omit<React.ComponentProps<typeof MenuSubTrigger>, "children">;
 
 export type MenuItemType =
   | MenuItemItem
   | MenuItemCheckbox
   | MenuItemRadio
+  | MenuItemRadioGroup
   | MenuItemLabel
   | MenuItemSeparator
+  | MenuItemGroup
   | MenuItemSubmenu;
 
-export interface GenericMenuProps {
-  trigger: React.ReactNode;
+function renderItem(item: MenuItemType, index: number): React.ReactNode {
+  switch (item.type) {
+    case "item": {
+      const { type: _, label, shortcut, ...props } = item;
+      return (
+        <MenuItem key={index} {...props}>
+          {label}
+          {shortcut && <MenuShortcut>{shortcut}</MenuShortcut>}
+        </MenuItem>
+      );
+    }
+    case "checkbox": {
+      const { type: _, label, shortcut, ...props } = item;
+      return (
+        <MenuCheckboxItem key={index} {...props}>
+          {label}
+          {shortcut && <MenuShortcut>{shortcut}</MenuShortcut>}
+        </MenuCheckboxItem>
+      );
+    }
+    case "radio": {
+      const { type: _, label, shortcut, ...props } = item;
+      return (
+        <MenuRadioItem key={index} {...props}>
+          {label}
+          {shortcut && <MenuShortcut>{shortcut}</MenuShortcut>}
+        </MenuRadioItem>
+      );
+    }
+    case "radio-group": {
+      const { type: _, value, onValueChange, items } = item;
+      return (
+        <MenuRadioGroup
+          key={index}
+          value={value}
+          onValueChange={onValueChange}
+        >
+          {items.map((subItem, i) => renderItem(subItem, i))}
+        </MenuRadioGroup>
+      );
+    }
+    case "label": {
+      const { type: _, label, ...props } = item;
+      return (
+        <MenuGroup key={index}>
+          <MenuLabel {...props}>{label}</MenuLabel>
+        </MenuGroup>
+      );
+    }
+    case "separator": {
+      const { type: _, ...props } = item;
+      return <MenuSeparator key={index} {...props} />;
+    }
+    case "group": {
+      const { type: _, label, items } = item;
+      return (
+        <MenuGroup key={index}>
+          {label && <MenuLabel>{label}</MenuLabel>}
+          {items.map((subItem, i) => renderItem(subItem, i))}
+        </MenuGroup>
+      );
+    }
+    case "submenu": {
+      const { type: _, label, items, ...props } = item;
+      return (
+        <MenuSub key={index}>
+          <MenuSubTrigger {...props}>{label}</MenuSubTrigger>
+          <MenuSubContent>
+            {items.map((subItem, i) => renderItem(subItem, i))}
+          </MenuSubContent>
+        </MenuSub>
+      );
+    }
+  }
+}
+
+export interface MenuProps {
+  trigger: React.ReactElement;
   items: MenuItemType[];
-  side?: "top" | "right" | "bottom" | "left";
-  offset?: ComponentPropsWithoutRef<typeof MenuContent>["sideOffset"];
-  contentProps?: ComponentPropsWithoutRef<typeof MenuContent>;
+  className?: string;
+  side?: React.ComponentProps<typeof MenuPopup>["side"];
+  align?: React.ComponentProps<typeof MenuPopup>["align"];
+  offset?: React.ComponentProps<typeof MenuPopup>["sideOffset"];
+  alignOffset?: React.ComponentProps<typeof MenuPopup>["alignOffset"];
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Popup panel that opens below the trigger. */
+    popup?: string;
+  };
 }
 
 export const Menu = ({
   trigger,
   items,
-  contentProps,
+  className,
   side = "bottom",
+  align = "start",
   offset,
-}: GenericMenuProps) => {
+  alignOffset,
+  classNames,
+}: MenuProps) => {
   return (
     <MenuRoot>
-      <MenuTrigger asChild>{trigger}</MenuTrigger>
-      <MenuContent side={side} sideOffset={offset} {...contentProps}>
-        {items.map(
-          ({ shortcut, onShortcut, shortcutOptions, ...item }, index) => (
-            <React.Fragment key={index}>
-              {renderMenuItem(
-                item,
-                shortcut && (
-                  <MenuShortcut
-                    keys={shortcut}
-                    handler={(event) => onShortcut?.(event)}
-                    options={shortcutOptions}
-                  >
-                    {shortcut}
-                  </MenuShortcut>
-                ),
-              )}
-            </React.Fragment>
-          ),
-        )}
-      </MenuContent>
+      <MenuTrigger render={trigger} />
+      <MenuPopup
+        className={cn(classNames?.popup, className)}
+        side={side}
+        align={align}
+        sideOffset={offset}
+        alignOffset={alignOffset}
+      >
+        {items.map((item, index) => renderItem(item, index))}
+      </MenuPopup>
     </MenuRoot>
   );
 };

package/src/components/number-input/number-input.stories.tsx

@@ -29,6 +29,9 @@ const meta: Meta<typeof NumberInput> = {
     name: "quantity",
     defaultValue: 0,
   },
+  argTypes: {
+    classNames: { control: false },
+  },
 };
 
 export default meta;
@@ -37,6 +40,22 @@ type Story = StoryObj<typeof NumberInput>;
 
 export const Default: Story = {};
 
+/**
+ * `className` estila el grupo (el contenedor con borde — root visual del
+ * componente). `classNames` expone los slots `input`, `controls`,
+ * `increment` y `decrement` para personalizar las partes internas.
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "outline-primary",
+    classNames: {
+      input: "font-mono text-primary",
+      increment: "text-primary",
+      decrement: "text-primary",
+    },
+  },
+};
+
 export const Disabled: Story = {
   args: {
     disabled: true,
@@ -89,15 +108,19 @@ export const Scrub: Story = {
 };
 
 /**
- * Usá `value` + `onChange` para controlar el valor externamente.
- * `onChange` recibe `number | null` — `null` cuando el campo está vacío o contiene un valor inválido.
+ * Usá `value` + `onValueChange` para controlar el valor externamente.
+ * `onValueChange` recibe `number | null` — `null` cuando el campo está vacío o contiene un valor inválido.
  */
 export const Controlled: Story = {
   render: () => {
     const [value, setValue] = useState<number | null>(0);
     return (
       <div className="flex w-48 flex-col gap-2">
-        <NumberInput name="quantity" value={value} onChange={setValue} />
+        <NumberInput
+          name="quantity"
+          value={value}
+          onValueChange={(v) => setValue(v)}
+        />
         <p className="text-muted-foreground text-xs">
           Valor: {value ?? "vacío"}
         </p>
@@ -118,7 +141,7 @@ export const Range: Story = {
         <NumberInput
           name="progress"
           value={value}
-          onChange={(v) => v !== null && setValue(v)}
+          onValueChange={(v) => v !== null && setValue(v)}
           min={0}
           max={100}
           step={10}

package/src/components/number-input/number-input.test.tsx

@@ -33,9 +33,9 @@ describe("NumberInput component", () => {
     expect(ref.current).toBeInstanceOf(HTMLInputElement);
   });
 
-  it("llama a onChange cuando el valor cambia", () => {
+  it("llama a onValueChange cuando el valor cambia", () => {
     const handleChange = vi.fn();
-    render(<NumberInput name="cantidad" onChange={handleChange} />);
+    render(<NumberInput name="cantidad" onValueChange={handleChange} />);
     const input = screen.getByRole("textbox");
 
     fireEvent.input(input, { target: { value: "5" } });

package/src/components/number-input/number-input.tsx

@@ -32,11 +32,12 @@ export function NumberInputGroup({
   return (
     <NumberFieldPrimitive.Group
       className={cn(
-        "flex w-full items-center overflow-hidden rounded-md border border-input bg-background text-sm transition-shadow",
-        "focus-within:border-ring",
-        "aria-invalid:border-error focus-within:aria-invalid:ring-error/20",
-        "has-aria-invalid:border-error focus-within:has-aria-invalid:ring-error/20",
-        "data-[invalid]:border-error focus-within:data-[invalid]:ring-error/20",
+        "flex h-10 w-full items-center overflow-hidden rounded-md bg-background text-sm transition-shadow",
+        "outline outline-1 outline-input [outline-offset:-1px]",
+        "focus-within:outline-ring",
+        "aria-invalid:outline-error focus-within:aria-invalid:ring-error/20",
+        "has-aria-invalid:outline-error focus-within:has-aria-invalid:ring-error/20",
+        "data-[invalid]:outline-error focus-within:data-[invalid]:ring-error/20",
         "data-disabled:cursor-not-allowed data-disabled:opacity-50 data-disabled:pointer-events-none",
         "[&_svg]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
@@ -153,70 +154,67 @@ export function NumberInputCursorIcon(props: ComponentProps<"svg">) {
 export interface NumberInputProps extends NumberFieldPrimitive.Root.Props {
   /** Hides the increment/decrement buttons. */
   hideControls?: boolean;
-  /** Shorthand for `onValueChange` — receives only the value, without event details. */
-  onChange?: (value: number | null) => void;
   /** Marks the field as invalid, adding the error border to the group. */
   invalid?: boolean;
   /** Forwarded to the underlying input element. */
   placeholder?: string;
-  groupProps?: NumberFieldPrimitive.Group.Props;
-  inputProps?: NumberFieldPrimitive.Input.Props;
-  decrementProps?: NumberFieldPrimitive.Decrement.Props;
-  incrementProps?: NumberFieldPrimitive.Increment.Props;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Native `<input>` element. */
+    input?: string;
+    /** Column wrapper around the increment/decrement buttons. */
+    controls?: string;
+    /** Increment button (Chevron up). */
+    increment?: string;
+    /** Decrement button (Chevron down). */
+    decrement?: string;
+  };
 }
 
 export function NumberInput({
   className,
   hideControls = false,
-  onChange,
   onValueChange,
   invalid,
   placeholder,
-  groupProps,
-  inputProps,
-  decrementProps,
-  incrementProps,
+  classNames,
   ...props
 }: NumberInputProps) {
   return (
-    <NumberInputRoot
-      onValueChange={(v, d) => {
-        onChange?.(v);
-        onValueChange?.(v, d);
-      }}
-      {...props}
-    >
+    <NumberInputRoot onValueChange={onValueChange} {...props}>
       <NumberInputGroup
         aria-invalid={invalid || undefined}
-        {...groupProps}
-        className={cn(className, groupProps?.className)}
+        className={className}
       >
         <NumberInputInput
           {...(invalid ? { "aria-invalid": true } : {})}
           placeholder={placeholder}
-          {...inputProps}
+          className={cn("self-stretch", classNames?.input)}
         />
         {!hideControls && (
-          <div className="flex flex-col self-stretch divide-y divide-input border-l border-input">
+          <div
+            className={cn(
+              "flex flex-col self-stretch divide-y divide-input border-l border-input",
+              classNames?.controls,
+            )}
+          >
             <NumberInputIncrement
               data-testid="increment-trigger"
-              {...incrementProps}
               className={cn(
                 "flex-1 border-l-0 py-0 [&_svg]:size-3",
-                incrementProps?.className,
+                classNames?.increment,
               )}
             >
-              {incrementProps?.children ?? <ChevronUpIcon />}
+              <ChevronUpIcon />
             </NumberInputIncrement>
             <NumberInputDecrement
               data-testid="decrement-trigger"
-              {...decrementProps}
               className={cn(
                 "flex-1 border-r-0 py-0 [&_svg]:size-3",
-                decrementProps?.className,
+                classNames?.decrement,
               )}
             >
-              {decrementProps?.children ?? <ChevronDownIcon />}
+              <ChevronDownIcon />
             </NumberInputDecrement>
           </div>
         )}

package/src/components/otp/index.ts

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

package/src/components/otp/otp.stories.tsx

@@ -0,0 +1,209 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import React from "react";
+
+import { Button } from "../button/button";
+import { Field } from "../field/field";
+import { Form } from "../form/form";
+import { OTP, OTPInput, OTPRoot, OTPSeparator } from "./otp";
+
+/**
+ * Segmented input for one-time passwords and verification codes.
+ * The composite `OTP` generates slots from `length` and places
+ * `OTPSeparator` automatically via `split`. Use `inputProps` to forward
+ * props to every slot. Compose primitives (`OTPRoot`, `OTPInput`,
+ * `OTPSeparator`) directly for full control over slot layout.
+ */
+const meta: Meta<typeof OTP> = {
+  title: "Components/OTP",
+  component: OTP,
+  parameters: { layout: "centered" },
+  args: {
+    length: 6,
+    "aria-label": "Verification code",
+  },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof OTP>;
+
+export const Default: Story = {};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <OTP aria-label="Default size" length={6} />
+      <OTP aria-label="Large size" length={6} size="lg" />
+    </div>
+  ),
+};
+
+/**
+ * `split={n}` inserts `OTPSeparator` after the nth slot (1-indexed).
+ */
+export const WithSeparator: Story = {
+  args: {
+    split: 3,
+  },
+};
+
+/**
+ * Associate a visible label using a `<label>` pointing to the root's `id`.
+ * When inside a `Field` with `FieldLabel`, the association is automatic.
+ */
+export const WithLabel: Story = {
+  render: () => (
+    <div className="flex flex-col gap-1.5">
+      <label className="text-sm font-medium" htmlFor="otp-with-label">
+        Verification code
+      </label>
+      <OTP
+        id="otp-with-label"
+        aria-label="Verification code"
+        length={6}
+        split={3}
+      />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    split: 3,
+  },
+};
+
+/**
+ * `validationType="alphanumeric"` for recovery, backup, or invite codes
+ * that mix letters and numbers. Forward `inputMode="text"` via `inputProps`
+ * so mobile keyboards show letters alongside digits.
+ */
+export const Alphanumeric: Story = {
+  args: {
+    validationType: "alphanumeric",
+    split: 3,
+    inputProps: { inputMode: "text" },
+  },
+};
+
+/**
+ * `mask` obscures typed characters in each slot while preserving keyboard
+ * navigation and paste behavior — useful on shared screens.
+ */
+export const Masked: Story = {
+  args: {
+    mask: true,
+  },
+};
+
+/**
+ * `placeholder` on each slot shows a hint character. Forward via `inputProps`
+ * alongside `focus-visible:placeholder:text-transparent` to hide the hint on
+ * the active slot so it does not compete with typed input.
+ */
+export const WithPlaceholder: Story = {
+  args: {
+    inputProps: {
+      placeholder: "1",
+      className: "focus-visible:placeholder:text-transparent",
+    },
+  },
+};
+
+/**
+ * Controlled via `value` + `onValueChange`. Fires with the full string on
+ * every keystroke. Check `value.length === length` to detect completion.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState("");
+    const done = value.length === 6;
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <OTP {...args} value={value} onValueChange={setValue} />
+        <p className="text-sm text-muted-foreground">
+          {done ? (
+            <span className="text-foreground font-medium">Code: {value}</span>
+          ) : (
+            <>{value.length} / 6 characters</>
+          )}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * Uncontrolled via `name` — value is read from `FormData` on submit.
+ * Declare constraint errors on `Field` so Base UI intercepts native browser
+ * validation and shows messages inline instead of the browser tooltip.
+ * `patternMismatch` fires when the OTP is partially filled; `valueMissing`
+ * when empty with `required`. `onFormSubmit` only runs when all constraints pass.
+ */
+export const WithForm: Story = {
+  render: () => {
+    const [result, setResult] = React.useState<string | null>(null);
+
+    return (
+      <Form
+        className="flex flex-col items-start gap-3"
+        onFormSubmit={(data) => setResult(data.code as string)}
+      >
+        <Field
+          name="code"
+          label="Verification code"
+          error={[
+            {
+              message: "Verification code is required.",
+              match: "valueMissing",
+            },
+            { message: "Enter all 6 digits.", match: "patternMismatch" },
+          ]}
+        >
+          <OTP length={6} split={3} required />
+        </Field>
+        <Button type="submit">Verify</Button>
+        {result && (
+          <p className="text-sm text-muted-foreground">
+            Submitted:{" "}
+            <span className="font-medium text-foreground">{result}</span>
+          </p>
+        )}
+      </Form>
+    );
+  },
+};
+
+/**
+ * Use primitives directly when you need custom slot layout, conditional
+ * rendering, or per-slot props that `inputProps` cannot express uniformly.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <OTPRoot aria-label="Verification code" length={6}>
+      <OTPInput aria-label="Character 1 of 6" />
+      <OTPInput aria-label="Character 2 of 6" />
+      <OTPInput aria-label="Character 3 of 6" />
+      <OTPSeparator />
+      <OTPInput aria-label="Character 4 of 6" />
+      <OTPInput aria-label="Character 5 of 6" />
+      <OTPInput aria-label="Character 6 of 6" />
+    </OTPRoot>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<OTPRoot aria-label="Verification code" length={6}>
+  <OTPInput aria-label="Character 1 of 6" />
+  <OTPInput aria-label="Character 2 of 6" />
+  <OTPInput aria-label="Character 3 of 6" />
+  <OTPSeparator />
+  <OTPInput aria-label="Character 4 of 6" />
+  <OTPInput aria-label="Character 5 of 6" />
+  <OTPInput aria-label="Character 6 of 6" />
+</OTPRoot>`,
+      },
+    },
+  },
+};