@emara/ui 1.1.0

package/components/ui/card.stories.tsx

@@ -0,0 +1,279 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiArrowRightLine, RiCheckLine, RiMoreLine } from "@remixicon/react";
+
+import { Avatar, AvatarFallback, AvatarImage } from "./avatar";
+import { Badge } from "./badge";
+import { Button } from "./button";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./card";
+
+const meta: Meta<typeof Card> = {
+  title: "Foundations/Card",
+  component: Card,
+  parameters: { layout: "centered" },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "outline", "elevated", "filled", "ghost"],
+    },
+    padding: { control: "select", options: ["none", "sm", "md", "lg"] },
+    interactive: { control: "boolean" },
+    selected: { control: "boolean" },
+    loading: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+/** Standard Card with title, description, body, and footer actions. */
+export const Default: Story = {
+  render: (args) => (
+    <Card {...args} className="w-96">
+      <CardHeader>
+        <CardTitle>Email notifications</CardTitle>
+        <CardDescription>Choose which messages get delivered to your inbox.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm leading-relaxed">
+          We&apos;ll only email you about the things you&apos;ve opted in to. You can change this at
+          any time from your account settings.
+        </p>
+      </CardContent>
+      <CardFooter className="justify-end gap-2">
+        <Button variant="ghost">Cancel</Button>
+        <Button>Save changes</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+/** Side-by-side comparison of the five spec variants. */
+export const Variants: Story = {
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-3">
+      {(["default", "outline", "elevated", "filled", "ghost"] as const).map((v) => (
+        <Card key={v} variant={v} className="w-72">
+          <CardHeader>
+            <CardTitle>{v}</CardTitle>
+            <CardDescription>variant=&quot;{v}&quot;</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <p className="text-sm">
+              {v === "default"
+                ? "No border — assumes the host theme tints --card vs --background."
+                : v === "outline"
+                  ? "Border + card background. The safe default for most apps."
+                  : v === "elevated"
+                    ? "Shadow-md, no border. Reads as floating above the page."
+                    : v === "filled"
+                      ? "--muted background. Use for nested cards inside another Card."
+                      : "Transparent. Pure spacing wrapper for headings + body."}
+            </p>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+export const PaddingScale: Story = {
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-4">
+      {(["none", "sm", "md", "lg"] as const).map((p) => (
+        <Card key={p} padding={p} className="w-56">
+          <CardTitle>padding={p}</CardTitle>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+/** Whole card is a real `<button>` via `asChild`. Hover + focus styles applied. */
+export const Interactive: Story = {
+  render: () => (
+    <Card asChild interactive className="w-80">
+      <button type="button" onClick={() => console.log("card clicked")} className="text-start">
+        <CardHeader>
+          <CardTitle>Click anywhere on this card</CardTitle>
+          <CardDescription>The whole surface is a real button.</CardDescription>
+        </CardHeader>
+        <CardContent className="flex items-center justify-between">
+          <span className="text-muted-foreground text-sm">View details</span>
+          <RiArrowRightLine className="rtl-mirror text-muted-foreground size-4" />
+        </CardContent>
+      </button>
+    </Card>
+  ),
+};
+
+/** Selected card — used for grid selection states (filter chips, plan picker, etc.). */
+export const Selected: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Card className="w-56">
+        <CardHeader>
+          <CardTitle>Starter</CardTitle>
+          <CardDescription>$0 / month</CardDescription>
+        </CardHeader>
+      </Card>
+      <Card selected className="w-56">
+        <CardHeader>
+          <CardTitle>Pro</CardTitle>
+          <CardDescription>$12 / month</CardDescription>
+        </CardHeader>
+      </Card>
+      <Card className="w-56">
+        <CardHeader>
+          <CardTitle>Team</CardTitle>
+          <CardDescription>$48 / month</CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  ),
+};
+
+/** Skeleton placeholder while data loads. Carries `aria-busy` / `aria-live`. */
+export const Loading: Story = {
+  args: { loading: true },
+  render: (args) => <Card {...args} className="w-96" />,
+};
+
+/** `CardTitle as="h2"` keeps the document outline intact when a Card sits
+ *  directly under a `PageHeader` whose title is an `<h1>`. */
+export const TitleAsH2: Story = {
+  render: () => (
+    <Card className="w-96">
+      <CardHeader>
+        <CardTitle as="h2">Title rendered as &lt;h2&gt;</CardTitle>
+        <CardDescription>
+          Use <code>as=&quot;h2&quot;</code> when the Card sits directly under a PageHeader.
+        </CardDescription>
+      </CardHeader>
+    </Card>
+  ),
+};
+
+// ----------------------------------------------------------------------------
+// Real-world composition examples
+// ----------------------------------------------------------------------------
+
+/** Profile-style card composing Avatar, Badge, and CardTitle in a header row. */
+export const ProfileCard: Story = {
+  render: () => (
+    <Card className="w-96">
+      <CardHeader className="flex flex-row items-center gap-3 space-y-0">
+        <Avatar size="lg">
+          <AvatarImage src="https://i.pravatar.cc/96?img=12" alt="" />
+          <AvatarFallback>AB</AvatarFallback>
+        </Avatar>
+        <div className="flex-1">
+          <CardTitle>Alice Bouchaib</CardTitle>
+          <CardDescription>alice@example.com</CardDescription>
+        </div>
+        <Badge dot variant="success">
+          Active
+        </Badge>
+      </CardHeader>
+      <CardContent>
+        <dl className="grid grid-cols-2 gap-3 text-sm">
+          <div>
+            <dt className="text-muted-foreground">Role</dt>
+            <dd className="font-medium">Designer</dd>
+          </div>
+          <div>
+            <dt className="text-muted-foreground">Joined</dt>
+            <dd className="font-medium">2024-03-12</dd>
+          </div>
+        </dl>
+      </CardContent>
+      <CardFooter className="justify-between">
+        <Button variant="ghost" size="sm">
+          Message
+        </Button>
+        <Button size="sm">View profile</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+/** Stat-style card with a primary metric, secondary detail, and a trend badge. */
+export const StatCard: Story = {
+  render: () => (
+    <Card className="w-72">
+      <CardHeader className="flex flex-row items-start justify-between space-y-0">
+        <div>
+          <CardDescription>Monthly recurring revenue</CardDescription>
+          <CardTitle className="mt-1 text-3xl tabular-nums">$24,580</CardTitle>
+        </div>
+        <Badge variant="success" icon={<RiCheckLine />}>
+          +12.3%
+        </Badge>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground text-xs">vs. $21,890 last month</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** Header with a leading icon-button action — common for cards that get
+ *  dismissed, pinned, or expanded individually. */
+export const WithHeaderAction: Story = {
+  render: () => (
+    <Card className="w-96">
+      <CardHeader className="flex flex-row items-start justify-between space-y-0">
+        <div className="space-y-1">
+          <CardTitle>API keys</CardTitle>
+          <CardDescription>Manage authentication tokens for this workspace.</CardDescription>
+        </div>
+        <Button variant="ghost" size="icon-sm" aria-label="More actions">
+          <RiMoreLine />
+        </Button>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground text-sm">3 active keys, 1 revoked.</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+/** Grid of selectable plan cards — demonstrates the selected state in a real
+ *  picker pattern with `asChild` + `<button>` for keyboard accessibility. */
+export const PlanPicker: Story = {
+  parameters: { layout: "padded" },
+  render: () => {
+    const plans = [
+      { id: "starter", name: "Starter", price: "$0", perks: "Up to 3 projects" },
+      { id: "pro", name: "Pro", price: "$12", perks: "Unlimited projects", selected: true },
+      { id: "team", name: "Team", price: "$48", perks: "Seats + roles" },
+    ];
+    return (
+      <div className="grid grid-cols-3 gap-4">
+        {plans.map((plan) => (
+          <Card
+            key={plan.id}
+            asChild
+            interactive
+            selected={plan.selected}
+            className="w-full text-start"
+          >
+            <button type="button">
+              <CardHeader>
+                <CardTitle>{plan.name}</CardTitle>
+                <CardDescription>{plan.perks}</CardDescription>
+              </CardHeader>
+              <CardContent>
+                <p className="text-2xl font-semibold tabular-nums">
+                  {plan.price}
+                  <span className="text-muted-foreground ms-1 text-sm font-normal">/mo</span>
+                </p>
+              </CardContent>
+            </button>
+          </Card>
+        ))}
+      </div>
+    );
+  },
+};

package/components/ui/card.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+import { forwardRef } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+import { Skeleton } from "./skeleton";
+
+// Per docs/emara-ui-phase-1-components.md §5.
+
+// ----------------------------------------------------------------------------
+// Card root
+// ----------------------------------------------------------------------------
+
+const cardVariants = cva(
+  "rounded-lg transition-colors transition-shadow",
+  {
+    variants: {
+      // Spec-faithful per docs/emara-ui-phase-1-components.md §5. Note that
+      // `default` carries no border because the spec assumes `--card` differs
+      // from `--background` in the host theme. Emara's stock palette has both
+      // as white in light mode, so `defaultVariants.variant` (below) is set
+      // to `outline` — a bare `<Card>` should still look like a card.
+      variant: {
+        default: "bg-card text-card-foreground",
+        outline: "bg-card text-card-foreground border border-border",
+        elevated: "bg-card text-card-foreground shadow-md",
+        filled: "bg-muted text-foreground",
+        ghost: "bg-transparent text-foreground",
+      },
+      padding: {
+        none: "p-0",
+        sm: "p-3",
+        md: "p-4",
+        lg: "p-6",
+      },
+      interactive: {
+        true: [
+          "cursor-pointer",
+          // Subtle hover — only the surface tone shifts, text stays put.
+          // For the default/outline variants the border also gets slightly
+          // stronger so the lift reads even without a background change.
+          "hover:bg-accent/40 hover:border-foreground/20",
+          "active:bg-accent/60",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        ].join(" "),
+        false: "",
+      },
+      selected: {
+        true: "ring-2 ring-primary ring-offset-2 ring-offset-background",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      variant: "outline",
+      padding: "md",
+      interactive: false,
+      selected: false,
+    },
+  },
+);
+
+type CardVariants = VariantProps<typeof cardVariants>;
+
+type CardProps = React.HTMLAttributes<HTMLDivElement> &
+  CardVariants & {
+    asChild?: boolean;
+    loading?: boolean;
+  };
+
+const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
+  {
+    className,
+    variant,
+    padding,
+    interactive,
+    selected,
+    asChild = false,
+    loading = false,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+
+  // Loading state mirrors a typical Card: header (title + description), body
+  // (3 lines), and a footer action. The container carries `aria-busy` /
+  // `aria-live` so assistive tech announces the loading region.
+  const loadingContent = (
+    <div className="space-y-4" aria-busy="true" aria-live="polite">
+      <div className="space-y-2">
+        <Skeleton className="h-5 w-2/5" />
+        <Skeleton className="h-4 w-3/5" />
+      </div>
+      <div className="space-y-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-10/12" />
+        <Skeleton className="h-4 w-3/5" />
+      </div>
+      <div className="flex justify-end">
+        <Skeleton className="h-9 w-24" />
+      </div>
+    </div>
+  );
+
+  return (
+    <Comp
+      ref={ref}
+      data-selected={selected ? "true" : undefined}
+      className={cn(cardVariants({ variant, padding, interactive, selected }), className)}
+      {...props}
+    >
+      {loading ? loadingContent : children}
+    </Comp>
+  );
+});
+Card.displayName = "Card";
+
+// ----------------------------------------------------------------------------
+// CardHeader
+// ----------------------------------------------------------------------------
+
+type CardHeaderProps = React.HTMLAttributes<HTMLDivElement> & {
+  asChild?: boolean;
+};
+
+const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(function CardHeader(
+  { className, asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+  // Block layout with vertical rhythm. `space-y-1` is 4px — tight, but the
+  // CardTitle now carries its own `leading-snug` so visually there's already
+  // breathing room between title and description.
+  return <Comp ref={ref} className={cn("space-y-1", className)} {...props} />;
+});
+CardHeader.displayName = "CardHeader";
+
+// ----------------------------------------------------------------------------
+// CardTitle — polymorphic via `as` prop (h2..h6, default h3).
+// ----------------------------------------------------------------------------
+
+type CardTitleAs = "h2" | "h3" | "h4" | "h5" | "h6";
+
+type CardTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+  as?: CardTitleAs;
+  asChild?: boolean;
+};
+
+const CardTitle = forwardRef<HTMLHeadingElement, CardTitleProps>(function CardTitle(
+  { className, as = "h3", asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : as;
+  // 18px / leading-snug / tight letter-spacing — establishes a clear visual
+  // step above the 14px CardDescription and 16px body text.
+  return (
+    <Comp
+      ref={ref}
+      className={cn("text-lg font-semibold leading-snug tracking-tight", className)}
+      {...props}
+    />
+  );
+});
+CardTitle.displayName = "CardTitle";
+
+// ----------------------------------------------------------------------------
+// CardDescription
+// ----------------------------------------------------------------------------
+
+type CardDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
+  asChild?: boolean;
+};
+
+const CardDescription = forwardRef<HTMLParagraphElement, CardDescriptionProps>(function CardDescription(
+  { className, asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : "p";
+  return (
+    <Comp
+      ref={ref}
+      className={cn("text-sm leading-snug text-muted-foreground", className)}
+      {...props}
+    />
+  );
+});
+CardDescription.displayName = "CardDescription";
+
+// ----------------------------------------------------------------------------
+// CardContent — `first:pt-0` so a Card with content-only renders flush.
+// ----------------------------------------------------------------------------
+
+type CardContentProps = React.HTMLAttributes<HTMLDivElement> & {
+  asChild?: boolean;
+};
+
+const CardContent = forwardRef<HTMLDivElement, CardContentProps>(function CardContent(
+  { className, asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+  return <Comp ref={ref} className={cn("pt-4 first:pt-0", className)} {...props} />;
+});
+CardContent.displayName = "CardContent";
+
+// ----------------------------------------------------------------------------
+// CardFooter — same `first:pt-0` guard so a footer-only Card doesn't get a
+// stray top gap.
+// ----------------------------------------------------------------------------
+
+type CardFooterProps = React.HTMLAttributes<HTMLDivElement> & {
+  asChild?: boolean;
+};
+
+const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(function CardFooter(
+  { className, asChild = false, ...props },
+  ref,
+) {
+  const Comp = asChild ? Slot : "div";
+  return (
+    <Comp
+      ref={ref}
+      className={cn("flex items-center pt-4 first:pt-0", className)}
+      {...props}
+    />
+  );
+});
+CardFooter.displayName = "CardFooter";
+
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  cardVariants,
+};
+export type {
+  CardProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+};

package/components/ui/checkbox.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Checkbox } from "./checkbox";
+
+const meta: Meta<typeof Checkbox> = {
+  title: "Forms/Checkbox",
+  component: Checkbox,
+  parameters: { layout: "centered" },
+  argTypes: {
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    invalid: { control: "boolean" },
+    disabled: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Checkbox>;
+
+export const Default: Story = {};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Checkbox size="sm" defaultChecked label="Small" />
+      <Checkbox size="md" defaultChecked label="Medium" />
+      <Checkbox size="lg" defaultChecked label="Large" />
+    </div>
+  ),
+};
+
+export const WithLabel: Story = {
+  args: { label: "Accept the terms and conditions" },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: "Email notifications",
+    description: "Receive weekly digest emails about your account activity.",
+  },
+};
+
+export const Checked: Story = {
+  args: { defaultChecked: true, label: "Default checked" },
+};
+
+export const Indeterminate: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [state, setState] = useState<"indeterminate" | boolean>("indeterminate");
+      return (
+        <Checkbox
+          checked={state}
+          onCheckedChange={(v) => setState(v)}
+          label="Select all"
+          description={`Current state: ${String(state)}`}
+        />
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    invalid: true,
+    label: "You must accept to continue",
+    description: "This field is required.",
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="space-y-2">
+      <Checkbox disabled label="Disabled unchecked" />
+      <Checkbox disabled defaultChecked label="Disabled checked" />
+    </div>
+  ),
+};
+
+export const ListGroup: Story = {
+  render: () => (
+    <div className="w-72 space-y-3">
+      <Checkbox label="Marketing emails" description="Product updates and offers." />
+      <Checkbox
+        label="Security alerts"
+        description="Sign-in attempts and password changes."
+        defaultChecked
+      />
+      <Checkbox label="Newsletter" description="Monthly company updates." />
+    </div>
+  ),
+};