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

package/src/components/accordion/accordion.stories.tsx

@@ -0,0 +1,143 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import React from "react";
+
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from "./accordion";
+
+const richContent = (
+  <span>
+    Content can include <strong>rich markup</strong> like bold text, links, or
+    any React node.
+  </span>
+);
+
+/**
+ * Collapsible sections that expand/collapse to show or hide content.
+ * Use the composite `Accordion` for simple item lists, or compose primitives
+ * (`AccordionRoot`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`) for
+ * full control. Supports single or multiple open panels via `multiple`.
+ */
+const meta: Meta<typeof Accordion> = {
+  title: "Components/Accordion",
+  component: Accordion,
+  args: {
+    items: [
+      {
+        value: "item-1",
+        trigger: "What is this library?",
+        content:
+          "A collection of accessible, customizable UI components built on Base UI and styled with Tailwind CSS.",
+      },
+      {
+        value: "item-2",
+        trigger: "Is it open source?",
+        content: richContent,
+      },
+      {
+        value: "item-3",
+        trigger: "Can I customize the theme?",
+        content:
+          "Override any token via @theme in your CSS after importing the library stylesheet.",
+      },
+    ],
+  },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Accordion>;
+
+export const Default: Story = {};
+
+/**
+ * `className` styles the accordion root. `classNames` exposes the `item`,
+ * `trigger`, and `content` slots for fine-grained styling.
+ *
+ * For structural changes (extra slots, custom layouts) use the primitives.
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "max-w-md gap-2",
+    classNames: {
+      item: "rounded-md border border-input px-3 not-last:border-b",
+      trigger: "py-3 text-base",
+      content: "text-muted-foreground",
+    },
+  },
+};
+
+/**
+ * Allow multiple panels to be open simultaneously via `multiple`.
+ */
+export const Multiple: Story = {
+  args: {
+    multiple: true,
+    defaultValue: ["item-1", "item-2"],
+  },
+};
+
+/**
+ * Controlled accordion — external state drives which panel is open.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState<string[]>(["item-1"]);
+    return <Accordion {...args} value={value} onValueChange={setValue} />;
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    items: [
+      {
+        value: "item-1",
+        trigger: "Available section",
+        content: "This section can be opened.",
+      },
+      {
+        value: "item-2",
+        trigger: "Disabled section",
+        content: "This section is disabled.",
+        disabled: true,
+      },
+    ],
+  },
+};
+
+/**
+ * Build accordion manually using primitives when you need custom slots,
+ * additional markup between items, or conditional rendering.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <AccordionRoot defaultValue={["item-1"]}>
+      <AccordionItem value="item-1">
+        <AccordionTrigger>What is this library?</AccordionTrigger>
+        <AccordionContent>
+          A collection of accessible, customizable UI components.
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>Is it open source?</AccordionTrigger>
+        <AccordionContent>{richContent}</AccordionContent>
+      </AccordionItem>
+    </AccordionRoot>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<AccordionRoot defaultValue={["item-1"]}>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Question</AccordionTrigger>
+    <AccordionContent>Answer</AccordionContent>
+  </AccordionItem>
+</AccordionRoot>`,
+      },
+    },
+  },
+};

package/src/components/accordion/accordion.tsx

@@ -0,0 +1,135 @@
+import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion";
+import { ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+import { type ReactNode } from "react";
+
+import { cn } from "../../lib";
+
+export function AccordionRoot({
+  className,
+  ...props
+}: AccordionPrimitive.Root.Props) {
+  return (
+    <AccordionPrimitive.Root
+      data-slot="accordion"
+      className={cn("flex w-full flex-col", className)}
+      {...props}
+    />
+  );
+}
+
+export function AccordionItem({
+  className,
+  ...props
+}: AccordionPrimitive.Item.Props) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("not-last:border-b", className)}
+      {...props}
+    />
+  );
+}
+
+export function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Trigger.Props) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "group/accordion-trigger relative flex flex-1 items-start justify-between rounded-lg border border-transparent py-2.5 text-left text-sm font-medium transition-all outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:after:border-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon
+          data-slot="accordion-trigger-icon"
+          className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden"
+        />
+        <ChevronUpIcon
+          data-slot="accordion-trigger-icon"
+          className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline"
+        />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  );
+}
+
+export function AccordionContent({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Panel.Props) {
+  return (
+    <AccordionPrimitive.Panel
+      data-slot="accordion-content"
+      className="h-(--accordion-panel-height) overflow-hidden text-sm transition-[height] duration-150 ease-out data-starting-style:h-0 data-ending-style:h-0"
+      {...props}
+    >
+      <div
+        className={cn(
+          "pb-2.5 pt-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
+          className,
+        )}
+      >
+        {children}
+      </div>
+    </AccordionPrimitive.Panel>
+  );
+}
+
+interface AccordionItem {
+  value: string;
+  trigger: ReactNode;
+  content: ReactNode;
+  disabled?: boolean;
+}
+
+interface AccordionProps
+  extends Omit<AccordionPrimitive.Root.Props, "children" | "className"> {
+  items: AccordionItem[];
+  /** Styles the accordion root container. */
+  className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Each collapsible item wrapper. */
+    item?: string;
+    /** Trigger button that toggles the item. */
+    trigger?: string;
+    /** Panel that contains the item content. */
+    content?: string;
+  };
+}
+
+export function Accordion({
+  items,
+  className,
+  classNames,
+  ...props
+}: AccordionProps) {
+  return (
+    <AccordionRoot className={className} {...props}>
+      {items.map(({ value, trigger, content, disabled }) => (
+        <AccordionItem
+          key={value}
+          value={value}
+          disabled={disabled}
+          className={classNames?.item}
+        >
+          <AccordionTrigger className={classNames?.trigger}>
+            {trigger}
+          </AccordionTrigger>
+          <AccordionContent className={classNames?.content}>
+            {content}
+          </AccordionContent>
+        </AccordionItem>
+      ))}
+    </AccordionRoot>
+  );
+}
+
+export { AccordionPrimitive };

package/src/components/accordion/index.ts

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

package/src/components/alert/alert.stories.tsx

@@ -20,10 +20,9 @@ import {
  * background tint, and icon color.
  *
  * Accepts `title`, `description`, `icon`, and `action` as props for the common case.
- * For full layout control, compose the primitives directly: `AlertRoot`, `AlertTitle`,
- * `AlertDescription`, and `AlertAction`. Each prop also has an escape-hatch counterpart
- * (`titleProps`, `descriptionProps`, `actionProps`) to override a specific primitive
- * without rebuilding the whole structure.
+ * `className` styles the alert root; `classNames` exposes the `title`, `description`,
+ * and `action` slots for fine-grained styling. For full layout control, compose the
+ * primitives directly: `AlertRoot`, `AlertTitle`, `AlertDescription`, and `AlertAction`.
  */
 const meta: Meta<typeof Alert> = {
   title: "Components/Alert",
@@ -46,7 +45,9 @@ const meta: Meta<typeof Alert> = {
     },
     title: { control: "text" },
     description: { control: "text" },
+    classNames: { control: false },
   },
+  tags: ["new"],
 };
 
 export default meta;
@@ -54,6 +55,25 @@ type Story = StoryObj<typeof Alert>;
 
 export const Default: Story = {};
 
+/**
+ * `className` styles the alert root. `classNames` exposes the `title`,
+ * `description`, and `action` slots for fine-grained styling without
+ * dropping to primitives.
+ */
+export const WithClassNames: Story = {
+  args: {
+    variant: "info",
+    title: "Custom styled alert",
+    description: "Each slot can be styled independently.",
+    icon: <InfoIcon className="size-4" />,
+    className: "border-info/50 bg-info/10",
+    classNames: {
+      title: "text-base",
+      description: "text-foreground/80",
+    },
+  },
+};
+
 /**
  * Use `variant="error"` for validation failures or destructive outcomes.
  * Pair with an icon to reinforce the severity.

package/src/components/alert/alert.tsx

@@ -79,9 +79,15 @@ interface AlertProps extends Omit<ComponentProps<typeof AlertRoot>, "title"> {
   description?: ReactNode;
   icon?: ReactNode;
   action?: ReactNode;
-  titleProps?: ComponentProps<typeof AlertTitle>;
-  descriptionProps?: ComponentProps<typeof AlertDescription>;
-  actionProps?: ComponentProps<typeof AlertAction>;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Alert title text. */
+    title?: string;
+    /** Supporting description below the title. */
+    description?: string;
+    /** Action area on the right of the alert. */
+    action?: string;
+  };
 }
 
 export function Alert({
@@ -89,20 +95,22 @@ export function Alert({
   description,
   icon,
   action,
-  titleProps,
-  descriptionProps,
-  actionProps,
+  classNames,
   children,
   ...props
 }: AlertProps) {
   return (
     <AlertRoot {...props}>
       {icon}
-      {title && <AlertTitle {...titleProps}>{title}</AlertTitle>}
+      {title && <AlertTitle className={classNames?.title}>{title}</AlertTitle>}
       {description && (
-        <AlertDescription {...descriptionProps}>{description}</AlertDescription>
+        <AlertDescription className={classNames?.description}>
+          {description}
+        </AlertDescription>
+      )}
+      {action && (
+        <AlertAction className={classNames?.action}>{action}</AlertAction>
       )}
-      {action && <AlertAction {...actionProps}>{action}</AlertAction>}
       {children}
     </AlertRoot>
   );

package/src/components/alert-dialog/alert-dialog.stories.tsx

@@ -47,6 +47,7 @@ const meta: Meta<typeof AlertDialog> = {
       control: "select",
       options: ["default", "error", "secondary", "outline", "ghost"],
     },
+    classNames: { control: false },
   },
 };
 
@@ -55,6 +56,29 @@ type Story = StoryObj<typeof AlertDialog>;
 
 export const Default: Story = {};
 
+/**
+ * `className` styles the popup panel. `classNames` exposes the `backdrop`,
+ * `header`, `title`, `description`, `footer`, `closeButton`, and `actionButton`
+ * slots — use for fine-grained styling without dropping to primitives.
+ *
+ * For structural changes (custom layouts, extra slots) use the primitives directly.
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "max-w-md",
+    classNames: {
+      backdrop: "bg-black/70 backdrop-blur-sm",
+      title: "text-xl text-error",
+      description: "text-base",
+      footer: "sm:justify-between",
+      actionButton: "min-w-32",
+    },
+    title: "Custom styled dialog",
+    description: "Slots can be styled without touching the primitives.",
+    actionText: "Confirm",
+  },
+};
+
 /**
  * Use `variant="error"` for irreversible actions like deletes.
  * The error button signals danger — reserve it for data loss scenarios.

package/src/components/alert-dialog/alert-dialog.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { AlertDialog } from "../../components";
-import { click } from "../../utils";
+import { click } from "../../utils/tests";
 
 describe("AlertDialog component", () => {
   it("should show custom title and description", () => {

package/src/components/alert-dialog/alert-dialog.tsx

@@ -69,18 +69,26 @@ export function AlertDialogViewport({
 /**
  * Dialog content container. Includes Portal, Backdrop and Viewport internally.
  * Pass `portalProps` to configure the portal (e.g. a custom `container`).
+ * `classNames` styles the internal `backdrop` and `viewport` slots.
  */
 export function AlertDialogPopup({
   className,
+  classNames,
   portalProps,
   ...props
 }: AlertDialogBase.Popup.Props & {
   portalProps?: AlertDialogBase.Portal.Props;
+  classNames?: {
+    /** Overlay rendered behind the dialog. */
+    backdrop?: string;
+    /** Full-screen container that centers the popup. */
+    viewport?: string;
+  };
 }) {
   return (
     <AlertDialogBase.Portal {...portalProps}>
-      <AlertDialogBackdrop />
-      <AlertDialogViewport>
+      <AlertDialogBackdrop className={classNames?.backdrop} />
+      <AlertDialogViewport className={classNames?.viewport}>
         <AlertDialogBase.Popup
           data-slot="alert-dialog-popup"
           className={cn(
@@ -194,8 +202,25 @@ export type AlertDialogProps = Omit<AlertDialogBase.Root.Props, "children"> & {
   closeText?: ReactNode;
   /** Label for the action button. @default "Confirm" */
   actionText?: ReactNode;
-  /** Additional className forwarded to the popup panel. */
+  /** Styles the dialog popup panel. */
   className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Overlay rendered behind the dialog. */
+    backdrop?: string;
+    /** Layout wrapper for title and description. */
+    header?: string;
+    /** Dialog heading. */
+    title?: string;
+    /** Supporting text below the title. */
+    description?: string;
+    /** Layout wrapper for action buttons. */
+    footer?: string;
+    /** Cancel button. */
+    closeButton?: string;
+    /** Action button. */
+    actionButton?: string;
+  };
 };
 
 /**
@@ -205,6 +230,10 @@ export type AlertDialogProps = Omit<AlertDialogBase.Root.Props, "children"> & {
  * making it composable with `<Tooltip>` at the primitive level.
  * For full structural control, use the exported primitives directly.
  *
+ * `className` styles the popup panel. `classNames` exposes the `backdrop`,
+ * `header`, `title`, `description`, `footer`, `closeButton`, and `actionButton`
+ * slots for fine-grained tweaks without dropping to primitives.
+ *
  * @example
  * ```tsx
  * <AlertDialog
@@ -228,29 +257,48 @@ export function AlertDialog({
   closeText = "Cancel",
   actionText = "Confirm",
   className,
+  classNames,
   ...props
 }: AlertDialogProps) {
   return (
     <AlertDialogRoot {...props}>
       {trigger && <AlertDialogTrigger render={trigger} />}
-      <AlertDialogPopup className={className}>
+      <AlertDialogPopup
+        className={className}
+        classNames={{ backdrop: classNames?.backdrop }}
+      >
         {(title || description) && (
-          <AlertDialogHeader>
-            {title && <AlertDialogTitle>{title}</AlertDialogTitle>}
+          <AlertDialogHeader className={classNames?.header}>
+            {title && (
+              <AlertDialogTitle className={classNames?.title}>
+                {title}
+              </AlertDialogTitle>
+            )}
             {description && (
-              <AlertDialogDescription>{description}</AlertDialogDescription>
+              <AlertDialogDescription className={classNames?.description}>
+                {description}
+              </AlertDialogDescription>
             )}
           </AlertDialogHeader>
         )}
         {children}
-        <AlertDialogFooter>
+        <AlertDialogFooter className={classNames?.footer}>
           <AlertDialogClose
-            render={<Button variant="secondary">{closeText}</Button>}
+            render={
+              <Button variant="secondary" className={classNames?.closeButton}>
+                {closeText}
+              </Button>
+            }
             onClick={onClose}
           />
           <AlertDialogClose
             render={
-              <Button variant={variant ?? "default"}>{actionText}</Button>
+              <Button
+                variant={variant ?? "default"}
+                className={classNames?.actionButton}
+              >
+                {actionText}
+              </Button>
             }
             onClick={onAction}
           />