@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/card/card.stories.tsx

@@ -0,0 +1,187 @@
+import { faker } from "@faker-js/faker";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ComponentType } from "react";
+import {
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardRoot,
+  CardTitle,
+} from "../../components";
+
+/**
+ * Composite card surface. Pass `title`, `description`, `action`, and `footer` as props
+ * to render the full structure without manually composing sub-components.
+ * Use `CardRoot` + primitives (`CardHeader`, `CardTitle`, `CardDescription`, `CardAction`,
+ * `CardContent`, `CardFooter`) directly for layouts the composite cannot express —
+ * for example, placing an `<img>` as the first child automatically clips it to the card's top corners.
+ * `CardAction` renders in the top-right of the header, spanning both title and description rows.
+ * `size="sm"` reduces padding and font size across all nested slots via `data-size` and CSS group selectors.
+ * Sub-components use `data-slot` attributes following the [Base UI](https://base-ui.com/react) slot convention.
+ */
+const meta: Meta<typeof Card> = {
+  title: "Components/Card",
+  component: Card,
+  subcomponents: {
+    CardRoot: CardRoot as ComponentType<unknown>,
+    CardHeader: CardHeader as ComponentType<unknown>,
+    CardTitle: CardTitle as ComponentType<unknown>,
+    CardDescription: CardDescription as ComponentType<unknown>,
+    CardAction: CardAction as ComponentType<unknown>,
+    CardContent: CardContent as ComponentType<unknown>,
+    CardFooter: CardFooter as ComponentType<unknown>,
+  },
+  args: {
+    className: "w-[350px]",
+    title: "How to Improve Your Productivity",
+    description: "By Jane Doe · 5 min read",
+  },
+  argTypes: {
+    classNames: { control: false },
+  },
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+/**
+ * `className` styles the card root. `classNames` exposes the `header`,
+ * `title`, `description`, `action`, `content`, and `footer` slots for
+ * fine-grained styling without dropping to primitives.
+ */
+export const WithClassNames: Story = {
+  args: {
+    children: "Card body content.",
+    classNames: {
+      title: "text-primary",
+      description: "italic",
+      content: "text-base",
+    },
+  },
+};
+
+export const Default: Story = {
+  render: (args) => (
+    <Card
+      {...args}
+      footer={
+        <>
+          <Button variant="outline">Read more</Button>
+          <Button className="ml-auto">Save</Button>
+        </>
+      }
+    >
+      <p className="text-muted-foreground leading-relaxed">
+        Discover strategies and tools to boost your productivity. Learn to
+        manage your time effectively and stay focused on what matters.
+      </p>
+    </Card>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-[350px]">
+      <Card title="Total Revenue" description="Compared to last month">
+        <p className="text-3xl font-bold">$45,231.89</p>
+        <p className="text-xs text-muted-foreground mt-1">
+          +20.1% from last month
+        </p>
+      </Card>
+      <Card size="sm" title="Active Users" description="Compared to last month">
+        <p className="text-3xl font-bold">2,350</p>
+        <p className="text-xs text-muted-foreground mt-1">+180 new users</p>
+      </Card>
+    </div>
+  ),
+};
+
+/**
+ * `CardAction` anchors to the top-right corner of the header and spans both the title and description rows.
+ * Pass any node — icon button, badge, menu trigger — via the `action` prop.
+ */
+export const WithAction: Story = {
+  render: (args) => (
+    <Card
+      {...args}
+      title="Team Members"
+      description="Manage your workspace members"
+      action={
+        <Button variant="outline" size="sm">
+          Invite
+        </Button>
+      }
+    >
+      <div className="flex flex-col gap-2">
+        {Array.from({ length: 3 }).map((_, i) => (
+          <div key={i} className="flex items-center justify-between">
+            <span className="text-sm">{faker.person.fullName()}</span>
+            <span className="text-xs text-muted-foreground">
+              {faker.internet.email()}
+            </span>
+          </div>
+        ))}
+      </div>
+    </Card>
+  ),
+};
+
+export const WithFooter: Story = {
+  render: (args) => (
+    <Card
+      {...args}
+      title="Delete Account"
+      description="This action is permanent and cannot be undone."
+      footer={
+        <div className="flex gap-2 w-full justify-end">
+          <Button variant="outline">Cancel</Button>
+          <Button variant="error">Delete</Button>
+        </div>
+      }
+    >
+      <p className="text-muted-foreground text-sm leading-relaxed">
+        All your data, settings, and integrations will be permanently removed
+        from our servers.
+      </p>
+    </Card>
+  ),
+};
+
+/**
+ * Use `CardRoot` + sub-components for layouts the composite cannot express.
+ * An `<img>` placed as the first child of `CardRoot` auto-clips to the card's top-rounded corners
+ * via the `has-[>img:first-child]:pt-0` and `*:[img:first-child]:rounded-t-xl` selectors.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <CardRoot className="w-[350px]">
+      <img
+        src={faker.image.urlPicsumPhotos({ width: 350, height: 150 })}
+        alt="Villa Luxury"
+        className="w-full h-[150px] object-cover"
+      />
+      <CardHeader>
+        <CardTitle>Villa Luxury</CardTitle>
+        <CardDescription>Ocean views and private pool.</CardDescription>
+        <CardAction>
+          <Button variant="ghost" size="sm">
+            ♡
+          </Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent>
+        <span className="text-2xl font-semibold">$750</span>
+        <span className="ml-2 text-sm text-muted-foreground">/ night</span>
+      </CardContent>
+      <CardFooter>
+        <Button variant="outline">Details</Button>
+        <Button className="ml-auto">Book</Button>
+      </CardFooter>
+    </CardRoot>
+  ),
+};

package/src/components/card/card.test.tsx

@@ -0,0 +1,205 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardRoot,
+  CardTitle,
+} from "../../components";
+
+describe("Card composite", () => {
+  it("renders the root with default size", () => {
+    render(<Card data-testid="card">Body</Card>);
+
+    const root = screen.getByTestId("card");
+    expect(root).toHaveAttribute("data-slot", "card");
+    expect(root).toHaveAttribute("data-size", "default");
+  });
+
+  it("applies the sm size variant", () => {
+    render(
+      <Card data-testid="card" size="sm">
+        Body
+      </Card>,
+    );
+
+    expect(screen.getByTestId("card")).toHaveAttribute("data-size", "sm");
+  });
+
+  it("renders the content slot when children are provided", () => {
+    render(<Card>Hello body</Card>);
+
+    const content = document.querySelector('[data-slot="card-content"]');
+    expect(content).not.toBeNull();
+    expect(content).toHaveTextContent("Hello body");
+  });
+
+  it("omits the header when title, description, and action are all absent", () => {
+    render(<Card>Only body</Card>);
+
+    expect(document.querySelector('[data-slot="card-header"]')).toBeNull();
+  });
+
+  it("renders the header with title", () => {
+    render(<Card title="My title">Body</Card>);
+
+    expect(document.querySelector('[data-slot="card-header"]')).not.toBeNull();
+    const titleEl = document.querySelector('[data-slot="card-title"]');
+    expect(titleEl).toHaveTextContent("My title");
+  });
+
+  it("renders the header from description alone (no title)", () => {
+    render(<Card description="Just a description">Body</Card>);
+
+    expect(document.querySelector('[data-slot="card-header"]')).not.toBeNull();
+    expect(document.querySelector('[data-slot="card-title"]')).toBeNull();
+    expect(
+      document.querySelector('[data-slot="card-description"]'),
+    ).toHaveTextContent("Just a description");
+  });
+
+  it("renders the header from action alone (no title/description)", () => {
+    render(<Card action={<button type="button">Go</button>}>Body</Card>);
+
+    expect(document.querySelector('[data-slot="card-header"]')).not.toBeNull();
+    expect(document.querySelector('[data-slot="card-title"]')).toBeNull();
+    expect(document.querySelector('[data-slot="card-description"]')).toBeNull();
+    const action = document.querySelector('[data-slot="card-action"]');
+    expect(action).toHaveTextContent("Go");
+  });
+
+  it("renders the footer when provided", () => {
+    render(<Card footer={<span>Footer text</span>}>Body</Card>);
+
+    const footer = document.querySelector('[data-slot="card-footer"]');
+    expect(footer).not.toBeNull();
+    expect(footer).toHaveTextContent("Footer text");
+  });
+
+  it("omits content and footer slots when not provided", () => {
+    render(<Card title="Title only" />);
+
+    expect(document.querySelector('[data-slot="card-content"]')).toBeNull();
+    expect(document.querySelector('[data-slot="card-footer"]')).toBeNull();
+  });
+
+  it("renders a full card with every region populated", () => {
+    render(
+      <Card
+        title="Title"
+        description="Description"
+        action={<span>Action</span>}
+        footer={<span>Footer</span>}
+      >
+        Content
+      </Card>,
+    );
+
+    expect(
+      document.querySelector('[data-slot="card-title"]'),
+    ).toHaveTextContent("Title");
+    expect(
+      document.querySelector('[data-slot="card-description"]'),
+    ).toHaveTextContent("Description");
+    expect(
+      document.querySelector('[data-slot="card-action"]'),
+    ).toHaveTextContent("Action");
+    expect(
+      document.querySelector('[data-slot="card-content"]'),
+    ).toHaveTextContent("Content");
+    expect(
+      document.querySelector('[data-slot="card-footer"]'),
+    ).toHaveTextContent("Footer");
+  });
+
+  it("applies className to the root and classNames to each slot", () => {
+    render(
+      <Card
+        data-testid="card"
+        className="root-class"
+        title="T"
+        description="D"
+        action={<span>A</span>}
+        footer={<span>F</span>}
+        classNames={{
+          header: "header-class",
+          title: "title-class",
+          description: "description-class",
+          action: "action-class",
+          content: "content-class",
+          footer: "footer-class",
+        }}
+      >
+        Body
+      </Card>,
+    );
+
+    expect(screen.getByTestId("card")).toHaveClass("root-class");
+    expect(document.querySelector('[data-slot="card-header"]')).toHaveClass(
+      "header-class",
+    );
+    expect(document.querySelector('[data-slot="card-title"]')).toHaveClass(
+      "title-class",
+    );
+    expect(
+      document.querySelector('[data-slot="card-description"]'),
+    ).toHaveClass("description-class");
+    expect(document.querySelector('[data-slot="card-action"]')).toHaveClass(
+      "action-class",
+    );
+    expect(document.querySelector('[data-slot="card-content"]')).toHaveClass(
+      "content-class",
+    );
+    expect(document.querySelector('[data-slot="card-footer"]')).toHaveClass(
+      "footer-class",
+    );
+  });
+});
+
+describe("Card primitives", () => {
+  it("CardRoot defaults size to 'default' and merges className", () => {
+    render(
+      <CardRoot className="extra" data-testid="root">
+        x
+      </CardRoot>,
+    );
+
+    const root = screen.getByTestId("root");
+    expect(root).toHaveAttribute("data-size", "default");
+    expect(root).toHaveClass("extra", "rounded-xl");
+  });
+
+  it("CardRoot honors an explicit sm size", () => {
+    render(
+      <CardRoot size="sm" data-testid="root">
+        x
+      </CardRoot>,
+    );
+
+    expect(screen.getByTestId("root")).toHaveAttribute("data-size", "sm");
+  });
+
+  it.each([
+    [CardHeader, "card-header"],
+    [CardTitle, "card-title"],
+    [CardDescription, "card-description"],
+    [CardAction, "card-action"],
+    [CardContent, "card-content"],
+    [CardFooter, "card-footer"],
+  ])("%o renders its data-slot and merges className", (Cmp, slot) => {
+    render(
+      <Cmp className="merged" data-testid="el">
+        content
+      </Cmp>,
+    );
+
+    const el = screen.getByTestId("el");
+    expect(el).toHaveAttribute("data-slot", slot);
+    expect(el).toHaveClass("merged");
+    expect(el).toHaveTextContent("content");
+  });
+});

package/src/components/card/card.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import React from "react";
+import { cn } from "../../lib";
+
+export function CardRoot({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardTitle({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "cn-font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardDescription({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function CardAction({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function CardContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
+      {...props}
+    />
+  );
+}
+
+export function CardFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+interface CardProps
+  extends Omit<React.ComponentProps<"div">, "children" | "title"> {
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  action?: React.ReactNode;
+  footer?: React.ReactNode;
+  children?: React.ReactNode;
+  size?: "default" | "sm";
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Header wrapper holding title, description, and action. */
+    header?: string;
+    /** Card title text. */
+    title?: string;
+    /** Supporting description below the title. */
+    description?: string;
+    /** Action area on the right of the header. */
+    action?: string;
+    /** Body content rendered between the header and the footer. */
+    content?: string;
+    /** Footer area below the content. */
+    footer?: string;
+  };
+}
+
+export function Card({
+  title,
+  description,
+  action,
+  footer,
+  children,
+  size,
+  className,
+  classNames,
+  ...props
+}: CardProps) {
+  const hasHeader = title || description || action;
+
+  return (
+    <CardRoot size={size} className={className} {...props}>
+      {hasHeader && (
+        <CardHeader className={classNames?.header}>
+          {title && (
+            <CardTitle className={classNames?.title}>{title}</CardTitle>
+          )}
+          {description && (
+            <CardDescription className={classNames?.description}>
+              {description}
+            </CardDescription>
+          )}
+          {action && (
+            <CardAction className={classNames?.action}>{action}</CardAction>
+          )}
+        </CardHeader>
+      )}
+      {children && (
+        <CardContent className={classNames?.content}>{children}</CardContent>
+      )}
+      {footer && (
+        <CardFooter className={classNames?.footer}>{footer}</CardFooter>
+      )}
+    </CardRoot>
+  );
+}

package/src/components/card/index.ts

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

package/src/components/center/center.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Center } from ".";
+
+/**
+ * Layout primitive that centers its single child on both axes via flexbox.
+ * Defaults to `display: flex`. `inline` switches to `inline-flex` for inline contexts.
+ * `as` renders any HTML element for semantic markup.
+ */
+const meta: Meta<typeof Center> = {
+  title: "Components/Center",
+  component: Center,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    children: { control: false },
+    className: { control: false },
+    as: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Center>;
+
+export const Default: Story = {
+  render: () => (
+    <Center className="h-48 w-72 border border-dashed rounded-lg">
+      <span className="text-sm text-muted-foreground">Centered</span>
+    </Center>
+  ),
+};
+
+/**
+ * `inline` swaps `flex` for `inline-flex` so the Center flows with surrounding inline content
+ * instead of starting a new block. Useful for badges, counters, and icon chips inside text.
+ */
+export const Inline: Story = {
+  render: () => (
+    <p className="text-sm max-w-sm">
+      You have{" "}
+      <Center
+        inline
+        className="w-6 h-6 bg-primary text-primary-foreground rounded-full text-xs font-medium"
+      >
+        3
+      </Center>{" "}
+      unread messages in your inbox.
+    </p>
+  ),
+};
+
+/**
+ * `as` swaps the rendered element while keeping the centering behavior.
+ * Pick the tag that matches the role: `main`, `section`, `header`, `footer`.
+ */
+export const As: Story = {
+  render: () => (
+    <Center as="section" className="h-48 w-72 bg-muted rounded-lg">
+      <code className="text-xs px-2 py-1 bg-background rounded">
+        &lt;section&gt;
+      </code>
+    </Center>
+  ),
+};

package/src/components/center/center.test.tsx

@@ -0,0 +1,63 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Center } from "../../components";
+
+describe("Center component", () => {
+  it("renders a div with flex centering by default", () => {
+    render(<Center data-testid="center">content</Center>);
+
+    const el = screen.getByTestId("center");
+    expect(el.tagName.toLowerCase()).toBe("div");
+    expect(el).toHaveAttribute("data-slot", "center");
+    expect(el).toHaveClass("flex", "items-center", "justify-center");
+    expect(el).not.toHaveClass("inline-flex");
+  });
+
+  it("uses inline-flex when inline is true", () => {
+    render(
+      <Center data-testid="center" inline>
+        content
+      </Center>,
+    );
+
+    const el = screen.getByTestId("center");
+    expect(el).toHaveClass("inline-flex");
+    expect(el).not.toHaveClass("flex items-center");
+  });
+
+  it("renders as a custom element via the 'as' prop", () => {
+    render(
+      <Center data-testid="center" as="section">
+        content
+      </Center>,
+    );
+
+    const el = screen.getByTestId("center");
+    expect(el.tagName.toLowerCase()).toBe("section");
+    expect(el).toHaveAttribute("data-slot", "center");
+  });
+
+  it("merges a custom className with the base classes", () => {
+    render(
+      <Center data-testid="center" className="gap-2">
+        content
+      </Center>,
+    );
+
+    const el = screen.getByTestId("center");
+    expect(el).toHaveClass("gap-2", "flex", "items-center");
+  });
+
+  it("renders children and forwards arbitrary props", () => {
+    render(
+      <Center data-testid="center" aria-label="centered" role="group">
+        <span>inner</span>
+      </Center>,
+    );
+
+    const el = screen.getByTestId("center");
+    expect(el).toHaveAttribute("aria-label", "centered");
+    expect(el).toHaveAttribute("role", "group");
+    expect(el).toHaveTextContent("inner");
+  });
+});