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

package/src/components/password/password.stories.tsx

@@ -28,7 +28,8 @@ const meta: Meta<typeof Password> = {
     hideIcon: { control: false },
     onShow: { control: false },
     onHide: { control: false },
-    onChange: { control: false },
+    onValueChange: { control: false },
+    classNames: { control: false },
   },
   decorators: [
     (Story) => (
@@ -71,7 +72,7 @@ export const NonToggleable: Story = {
 };
 
 /**
- * `onChange` receives the string value as first argument, so no
+ * `onValueChange` receives the string value as first argument, so no
  * `event.target.value` needed.
  */
 export const Controlled: Story = {
@@ -81,12 +82,26 @@ export const Controlled: Story = {
       <Password
         placeholder="Enter your password"
         value={value}
-        onChange={(val) => setValue(val)}
+        onValueChange={(val) => setValue(val)}
       />
     );
   },
 };
 
+/**
+ * `className` estila el wrapper (el field visible). `classNames` expone los
+ * slots `input` (texto interno) y `toggle` (botón del ojo).
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "border-primary focus-within:border-primary",
+    classNames: {
+      input: "font-mono",
+      toggle: "text-primary hover:text-primary/80",
+    },
+  },
+};
+
 export const CustomIcons: Story = {
   args: {
     showIcon: <Lock className="h-4 w-4" />,

package/src/components/password/password.tsx

@@ -10,6 +10,13 @@ export type PasswordProps = Omit<InputProps, "unstyled" | "nativeInput"> & {
   onShow?: () => void;
   onHide?: () => void;
   toggleable?: boolean;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Native `<input>` element (transparent inside the wrapper). */
+    input?: string;
+    /** Show/hide toggle button on the right. */
+    toggle?: string;
+  };
 };
 
 export function Password({
@@ -19,7 +26,8 @@ export function Password({
   onShow,
   onHide,
   toggleable = true,
-  onChange,
+  onValueChange,
+  classNames,
   ...rest
 }: PasswordProps) {
   const [showPassword, toggleShowPassword] = useToggle(false);
@@ -29,16 +37,21 @@ export function Password({
     showPassword ? onHide?.() : onShow?.();
   };
 
-  const handleChange = onChange
+  const handleChange = onValueChange
     ? (event: ChangeEvent<HTMLInputElement>) =>
-        onChange(event.target.value, event)
+        onValueChange(event.target.value, event)
     : undefined;
 
   return (
     <div
       className={cn(
-        "relative inline-flex w-full",
+        "relative inline-flex h-10 w-full items-center text-sm",
+        "rounded-md border border-input bg-background 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",
         "has-disabled:cursor-not-allowed has-disabled:opacity-50",
+        "[&::-ms-clear]:hidden [&::-ms-reveal]:hidden",
         className,
       )}
       data-slot="password"
@@ -48,12 +61,10 @@ export function Password({
         onChange={handleChange}
         type={showPassword ? "text" : "password"}
         className={cn(
-          "h-10 w-full min-w-0 rounded-md border border-input bg-background",
-          "pl-3 pr-10 text-sm outline-none transition-shadow placeholder:text-muted-foreground",
-          "focus-visible:border-ring",
-          "aria-invalid:border-error focus-visible:aria-invalid:ring-error/20",
+          "min-w-0 flex-1 bg-transparent pl-3 outline-none",
+          "placeholder:text-muted-foreground",
           "disabled:cursor-not-allowed",
-          "[&::-ms-clear]:hidden [&::-ms-reveal]:hidden",
+          classNames?.input,
         )}
       />
       <button
@@ -61,7 +72,12 @@ export function Password({
         type="button"
         onClick={handleToggle}
         disabled={!toggleable}
-        className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50"
+        className={cn(
+          "flex shrink-0 items-center px-2 text-muted-foreground transition-colors",
+          "hover:text-foreground",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          classNames?.toggle,
+        )}
       >
         {showPassword ? hideIcon : showIcon}
       </button>

package/src/components/popover/popover.stories.tsx

@@ -19,15 +19,19 @@ import {
  * Provides two APIs: `Popover` (composite, single-component) and primitives
  * (`PopoverRoot` + `PopoverTrigger` + `PopoverPopup`) for full layout control.
  *
- * `trigger` accepts a `ReactElement` passed as the `render` prop of `PopoverTrigger` — no
- * wrapper is added. Use `popupClassName` to style the popup without going through `popupProps`.
- * `title` and `description` render `PopoverTitle` / `PopoverDescription` with automatic ARIA
- * wiring. Supports controlled state via `open` / `onOpenChange` and imperative control via
- * `PopoverCreateHandle`.
+ * `trigger` accepts a `ReactElement` passed as the `render` prop of
+ * `PopoverTrigger` — no wrapper is added. Style the popup via `className`
+ * (the visual root) or use `classNames.viewport` for the inner viewport.
+ * `title` and `description` render `PopoverTitle` / `PopoverDescription`
+ * with automatic ARIA wiring. Supports controlled state via `open` /
+ * `onOpenChange` and imperative control via `PopoverCreateHandle`.
  */
 const meta: Meta<typeof Popover> = {
   title: "Components/Popover",
   component: Popover,
+  argTypes: {
+    classNames: { control: false },
+  },
 };
 
 export default meta;
@@ -43,6 +47,23 @@ export const Default: Story = {
   ),
 };
 
+/**
+ * `className` estila el popup (root visual). `classNames` expone el slot
+ * `viewport` para el contenedor interno con padding y overflow.
+ */
+export const WithClassNames: Story = {
+  render: (args) => (
+    <Popover
+      {...args}
+      className="border-primary"
+      classNames={{ viewport: "py-6" }}
+      trigger={<Button variant="outline">Open</Button>}
+    >
+      Custom popup + viewport styling.
+    </Popover>
+  ),
+};
+
 /**
  * `tooltipStyle` renders the popup compact — smaller padding, `rounded-md`, and `w-fit`.
  * Intended for brief contextual hints that don't need a full panel.

package/src/components/popover/popover.tsx

@@ -39,9 +39,11 @@ export function PopoverPopup({
   matchTriggerWidth = false,
   anchor,
   portalProps,
+  viewportClassName,
   ...props
 }: PopoverPrimitive.Popup.Props & {
   portalProps?: PopoverPrimitive.Portal.Props;
+  viewportClassName?: string;
   side?: PopoverPrimitive.Positioner.Props["side"];
   align?: PopoverPrimitive.Positioner.Props["align"];
   sideOffset?: PopoverPrimitive.Positioner.Props["sideOffset"];
@@ -79,6 +81,7 @@ export function PopoverPopup({
               tooltipStyle
                 ? "py-1 [--viewport-inline-padding:--spacing(2)]"
                 : "not-data-transitioning:overflow-y-auto",
+              viewportClassName,
             )}
             data-slot="popover-viewport"
           >
@@ -126,18 +129,6 @@ export { PopoverPrimitive, PopoverPopup as PopoverContent };
 
 // --- Composite ---
 
-type PopoverPopupOverrideProps = Omit<
-  React.ComponentPropsWithoutRef<typeof PopoverPopup>,
-  | "children"
-  | "side"
-  | "align"
-  | "sideOffset"
-  | "alignOffset"
-  | "tooltipStyle"
-  | "matchTriggerWidth"
-  | "anchor"
->;
-
 interface PopoverProps extends Omit<PopoverPrimitive.Root.Props, "children"> {
   trigger?: React.ReactElement;
   children: ReactNode;
@@ -150,9 +141,13 @@ interface PopoverProps extends Omit<PopoverPrimitive.Root.Props, "children"> {
   tooltipStyle?: boolean;
   matchTriggerWidth?: boolean;
   anchor?: PopoverPrimitive.Positioner.Props["anchor"];
-  popupClassName?: string;
-  triggerProps?: Omit<PopoverPrimitive.Trigger.Props, "render" | "children">;
-  popupProps?: PopoverPopupOverrideProps;
+  /** Styles the popup (visual root). */
+  className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Inner viewport that holds the popup content (padding, overflow). */
+    viewport?: string;
+  };
 }
 
 export function Popover({
@@ -167,18 +162,14 @@ export function Popover({
   tooltipStyle,
   matchTriggerWidth,
   anchor,
-  popupClassName,
-  triggerProps,
-  popupProps,
+  className,
+  classNames,
   ...rootProps
 }: PopoverProps): React.ReactElement {
   return (
     <PopoverRoot {...rootProps}>
-      {trigger !== undefined && (
-        <PopoverTrigger render={trigger} {...triggerProps} />
-      )}
+      {trigger !== undefined && <PopoverTrigger render={trigger} />}
       <PopoverPopup
-        {...popupProps}
         side={side}
         align={align}
         sideOffset={sideOffset}
@@ -186,7 +177,8 @@ export function Popover({
         tooltipStyle={tooltipStyle}
         matchTriggerWidth={matchTriggerWidth}
         anchor={anchor}
-        className={cn(popupProps?.className, popupClassName)}
+        className={className}
+        viewportClassName={classNames?.viewport}
       >
         {(title ?? description) && (
           <div className="mb-2">

package/src/components/progress/progress.stories.tsx

@@ -22,6 +22,7 @@ const meta: Meta<typeof Progress> = {
     value: 60,
     "aria-label": "Loading",
   },
+  tags: ["new"],
 };
 
 export default meta;

package/src/components/radio-group/index.ts

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

package/src/components/radio-group/radio-group.stories.tsx

@@ -0,0 +1,251 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { action } from "storybook/actions";
+import { Button } from "../../components";
+import { Field } from "../field/field";
+import {
+  RadioGroup,
+  RadioGroupRoot,
+  RadioIndicator,
+  RadioRoot,
+} from "./radio-group";
+
+/**
+ * RadioGroup manages single-selection across a set of radio buttons.
+ * Exactly one item can be selected at a time. Built on
+ * `@base-ui/react/radio-group` and `@base-ui/react/radio`.
+ *
+ * Designed to be used inside `Field` — `Field` provides the label, description,
+ * and error handling. Pass `name` to both `Field` (for server-error routing)
+ * and `RadioGroup` (for native `FormData`).
+ *
+ * **90% case** — pass `items` and let the composite render all radio buttons:
+ * ```tsx
+ * <RadioGroup
+ *   name="plan"
+ *   items={[{ value: "free", label: "Free" }, { value: "pro", label: "Pro" }]}
+ *   onValueChange={(value) => console.log(value)}
+ * />
+ * ```
+ *
+ * **Compound API** for custom layouts:
+ * - `RadioGroup` — group wrapper with value management and a11y fieldset
+ * - `RadioGroup.Item` — labeled radio button for use inside `RadioGroup`
+ * - `RadioGroup.Legend` — optional fieldset legend when extra semantic grouping is needed
+ *
+ * Use `onValueChange` to react to selection changes.
+ *
+ * `controlFirst` (default `true`) places the radio before the label on all
+ * `RadioGroup.Item` children via context.
+ *
+ * Reference: [Radio – Base UI](https://base-ui.com/react/components/radio)
+ */
+const meta: Meta<typeof RadioGroup> = {
+  title: "Components/RadioGroup",
+  component: RadioGroup,
+  parameters: { layout: "centered" },
+  args: {
+    legend: "Preferred contact",
+  },
+  argTypes: {
+    children: { control: false },
+    items: { control: false },
+    onValueChange: { control: false },
+  },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof RadioGroup>;
+
+const CONTACT_ITEMS = [
+  { value: "email", label: "Email" },
+  { value: "sms", label: "SMS" },
+  { value: "push", label: "Push notifications" },
+];
+
+export const Default: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} defaultValue="email" />
+  ),
+};
+
+/**
+ * Wrap `RadioGroup` with `Field` to add a label, description, and error handling.
+ * Pass `name` to both — `Field` uses it for server-error routing, `RadioGroup`
+ * uses it for native `FormData`.
+ */
+export const WithDescription: Story = {
+  render: ({ legend, ...args }) => (
+    <Field
+      label={legend}
+      description="We'll only contact you using this method."
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} defaultValue="email" />
+    </Field>
+  ),
+};
+
+/**
+ * Pass `error` to `Field` — the error message renders below the group and
+ * all `RadioGroup.Item` children receive `aria-invalid` (red borders).
+ * `description` is hidden while the field is invalid.
+ */
+export const WithError: Story = {
+  render: ({ legend, ...args }) => (
+    <Field
+      label={legend}
+      invalid
+      description="This text is hidden while error is present."
+      error="Please select a contact method."
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} />
+    </Field>
+  ),
+};
+
+/**
+ * `controlFirst={false}` places the label before the radio button.
+ * Default is `true` (radio → label). Applied to all items via context.
+ */
+export const LabelFirst: Story = {
+  render: (args) => (
+    <RadioGroup
+      {...args}
+      items={CONTACT_ITEMS}
+      controlFirst={false}
+      defaultValue="email"
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} disabled defaultValue="email" />
+  ),
+};
+
+/**
+ * `readOnly` prevents selection changes while keeping the group focusable
+ * for keyboard navigation. Unlike `disabled`, it does not apply opacity.
+ */
+export const ReadOnly: Story = {
+  render: (args) => (
+    <RadioGroup {...args} items={CONTACT_ITEMS} readOnly defaultValue="email" />
+  ),
+};
+
+/**
+ * Use `value` + `onValueChange` for controlled mode.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState("email");
+    return (
+      <RadioGroup
+        {...args}
+        items={CONTACT_ITEMS}
+        value={value}
+        onValueChange={setValue}
+      />
+    );
+  },
+};
+
+/**
+ * Base UI injects a hidden `<input type="radio">` per item so `name` and
+ * `required` work with native `FormData` — no extra wiring needed.
+ */
+export const Required: Story = {
+  render: (args) => (
+    <form
+      className="space-y-3"
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        action("submit")(Object.fromEntries(data));
+      }}
+    >
+      <RadioGroup {...args} items={CONTACT_ITEMS} name="contact" required />
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+};
+
+/**
+ * Pass `items` to let the composite render all radio buttons — the 90% case.
+ * Each item supports `value`, `label`, and an optional `disabled` flag for
+ * per-item control independent of the group `disabled` prop.
+ */
+export const WithItems: Story = {
+  render: (args) => (
+    <RadioGroup
+      {...args}
+      defaultValue="email"
+      items={[
+        { value: "email", label: "Email" },
+        { value: "sms", label: "SMS" },
+        { value: "push", label: "Push notifications", disabled: true },
+      ]}
+    />
+  ),
+};
+
+/**
+ * `RadioGroup.Legend` can be placed as a direct child instead of the `legend`
+ * prop when you need custom styling or want to visually hide it with `sr-only`.
+ *
+ * ```tsx
+ * <RadioGroup>
+ *   <RadioGroup.Legend className="sr-only">Contact</RadioGroup.Legend>
+ *   <RadioGroup.Item value="email" label="Email" />
+ * </RadioGroup>
+ * ```
+ */
+export const ComposableLegend: Story = {
+  render: () => (
+    <RadioGroup defaultValue="email">
+      <RadioGroup.Legend className="text-base font-semibold">
+        Preferred contact method
+      </RadioGroup.Legend>
+      <RadioGroup.Item value="email" label="Email" />
+      <RadioGroup.Item value="sms" label="SMS" />
+      <RadioGroup.Item value="push" label="Push notifications" />
+    </RadioGroup>
+  ),
+};
+
+/**
+ * Direct composition with primitives for full structural control.
+ * Use when the composite layout is not enough — custom ordering,
+ * extra elements between items, or non-standard layouts.
+ *
+ * ```tsx
+ * <RadioGroupRoot name="plan">
+ *   <RadioRoot value="pro">
+ *     <RadioIndicator />
+ *   </RadioRoot>
+ * </RadioGroupRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <RadioGroupRoot name="plan" defaultValue="pro">
+      <div className="flex flex-col gap-2">
+        {(["free", "pro", "enterprise"] as const).map((plan) => (
+          <div key={plan} className="flex items-center gap-2">
+            <RadioRoot id={`primitive-${plan}`} value={plan}>
+              <RadioIndicator />
+            </RadioRoot>
+            <label
+              htmlFor={`primitive-${plan}`}
+              className="select-none text-sm capitalize"
+            >
+              {plan}
+            </label>
+          </div>
+        ))}
+      </div>
+    </RadioGroupRoot>
+  ),
+};