@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/calendar/calendar.tsx

@@ -14,6 +14,7 @@ export function Calendar({
 }: CalendarProps) {
   return (
     <DayPicker
+      data-slot="calendar"
       showOutsideDays={showOutsideDays}
       className={cn("p-3", className)}
       classNames={{
@@ -26,7 +27,7 @@ export function Calendar({
         // for a taller caption (e.g. `captionLayout="dropdown"`), and `px-8` keeps
         // the label clear of the buttons overlaying either edge.
         month_caption: "flex min-h-7 items-center justify-center px-8",
-        caption_label: "text-sm font-medium",
+        caption_label: "text-body font-medium",
         // Overlays the caption row and pushes the buttons to either edge; the
         // buttons themselves stay in normal flow inside it.
         nav: "absolute inset-x-0 top-0 flex h-7 items-center justify-between",
@@ -42,7 +43,7 @@ export function Calendar({
         weekdays: "flex",
         weekday: "w-8 rounded-md text-[0.8rem] font-normal text-muted-foreground",
         week: "mt-2 flex w-full",
-        day: "relative size-8 p-0 text-center text-sm focus-within:relative focus-within:z-20 [&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-range-end)]:rounded-e-md first:[&:has([aria-selected])]:rounded-s-md last:[&:has([aria-selected])]:rounded-e-md",
+        day: "relative size-8 p-0 text-center text-body focus-within:relative focus-within:z-20 [&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-range-end)]:rounded-e-md first:[&:has([aria-selected])]:rounded-s-md last:[&:has([aria-selected])]:rounded-e-md",
         day_button: cn(
           buttonVariants({ variant: "ghost" }),
           "size-8 p-0 font-normal aria-selected:opacity-100",
@@ -50,8 +51,13 @@ export function Calendar({
         range_start: "day-range-start rounded-s-md",
         range_end: "day-range-end rounded-e-md",
         range_middle: "aria-selected:bg-accent aria-selected:text-accent-foreground",
+        // `focus:bg-primary focus:text-primary-foreground` was dead CSS: this
+        // class targets react-day-picker v9's `<td role="gridcell">` slot,
+        // which is never focusable — the actual focusable `DayButton`
+        // already inherits `focus-visible:ring-2 focus-visible:ring-ring`
+        // from `buttonVariants({ variant: "ghost" })` (#308).
         selected:
-          "bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground focus:bg-primary focus:text-primary-foreground",
+          "bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground",
         today: "bg-accent text-accent-foreground",
         outside: "day-outside text-muted-foreground aria-selected:text-muted-foreground",
         disabled: "text-muted-foreground opacity-50",

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

@@ -1,12 +1,26 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, userEvent } from "storybook/test";
-import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./card";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+} from "./card";
 
 const meta = {
   title: "Core/Card",
   component: Card,
   tags: ["autodocs"],
   argTypes: {
+    stacked: {
+      description:
+        "Opt-in hairline gesture: two sheet edges stacked behind the card's top edge. Plain cards only.",
+      control: "boolean",
+      table: { category: "Appearance" },
+    },
     interactive: {
       description:
         "Opt-in hover-lift for clickable cards (motion-tokened, respects reduced-motion).",
@@ -68,6 +82,64 @@ export const Default: Story = {
   ),
 };
 
+/**
+ * `CardMedia` — the media WELL. A faded hairline hatch sits behind whatever the
+ * card shows (`ground="dots"` for a dot field, `"none"` for a bare well; `fade`
+ * picks the direction it dissolves in). The texture is an inert layer: the media
+ * on top of it is never tinted or masked.
+ */
+export const Media: Story = {
+  render: () => (
+    <div className="grid max-w-3xl gap-4 sm:grid-cols-2">
+      <Card>
+        <CardMedia>
+          <div className="rounded-md border border-card-border bg-card px-4 py-3 text-body shadow-card">
+            <span className="font-medium">24,512</span>{" "}
+            <span className="text-muted-foreground">active users</span>
+          </div>
+        </CardMedia>
+        <CardHeader>
+          <CardTitle>Hatch (default)</CardTitle>
+          <CardDescription>Fades out toward every edge.</CardDescription>
+        </CardHeader>
+      </Card>
+      <Card>
+        <CardMedia ground="dots" fade="top">
+          <div className="rounded-md border border-card-border bg-card px-4 py-3 text-body shadow-card">
+            <span className="font-medium">+12.4%</span>{" "}
+            <span className="text-muted-foreground">vs last month</span>
+          </div>
+        </CardMedia>
+        <CardHeader>
+          <CardTitle>Dots, fading up</CardTitle>
+          <CardDescription>The ink settles at the foot of the well.</CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  ),
+};
+
+/**
+ * `stacked` — the edges of two sheets rise behind the card's top edge (the
+ * `hairline-stack` utility). It draws OUTSIDE the card: leave ~12px above it and
+ * keep it a plain card (a `detail` card clips its overflow).
+ */
+export const Stacked: Story = {
+  render: () => (
+    <div className="pt-4">
+      <Card stacked className="max-w-sm">
+        <CardHeader>
+          <CardTitle>Spending limit</CardTitle>
+          <CardDescription>One of several budgets in this workspace</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="text-display font-semibold">40% used</div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
 /** Opt-in hover-lift for clickable cards (gated by the motion system). */
 export const Interactive: Story = {
   // The suite runs under `prefers-reduced-motion: reduce`

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

@@ -1,6 +1,6 @@
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
-import { Card, CardDescription, CardTitle } from "./card";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Card, CardDescription, CardMedia, CardTitle } from "./card";
 
 describe("Card", () => {
   it("renders a nested title", () => {
@@ -23,7 +23,7 @@ describe("Card", () => {
     render(<CardTitle as="h2">Section title</CardTitle>);
     const heading = screen.getByRole("heading", { level: 2, name: "Section title" });
     expect(heading.tagName).toBe("H2");
-    expect(heading).toHaveClass("text-title", "leading-none");
+    expect(heading).toHaveClass("text-title", "leading-(--card-title-leading)");
   });
 
   // --- CardDescription `text-muted-foreground` drop (#336) ---
@@ -103,6 +103,28 @@ describe("Card", () => {
     expect(region).toHaveAttribute("aria-hidden", "true");
   });
 
+  it("with `detail` + hover, cancels its pending conceal rAF on unmount", () => {
+    const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(42);
+    const cafSpy = vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {});
+    const { unmount } = render(
+      <Card data-testid="card" detailReveal="hover" detail={<button>More</button>}>
+        main
+      </Card>,
+    );
+    const card = screen.getByTestId("card");
+    // focus-out schedules the conceal rAF this test is locking cleanup for.
+    fireEvent.focusOut(card);
+    expect(rafSpy).toHaveBeenCalled();
+
+    unmount();
+    // Without cancelling it, the scheduled frame is still pending after
+    // teardown and fires against a component that no longer exists.
+    expect(cafSpy).toHaveBeenCalledWith(42);
+
+    rafSpy.mockRestore();
+    cafSpy.mockRestore();
+  });
+
   it("with `detail` + hover, detail region is labelled (landmark navigation, #141)", () => {
     render(
       <Card detailReveal="hover" detail={<span>info</span>} detailLabel="Card details">
@@ -150,4 +172,31 @@ describe("Card", () => {
     );
     expect(screen.getByTestId("card").style.getPropertyValue("--card-detail-size")).toBe("20rem");
   });
+
+  // --- hairline seams: `stacked` + `CardMedia` ---
+  it("is not stacked by default; `stacked` adds the hairline-stack gesture", () => {
+    const { rerender } = render(<Card data-testid="c" />);
+    expect(screen.getByTestId("c")).not.toHaveClass("hairline-stack");
+    rerender(<Card data-testid="c" stacked />);
+    expect(screen.getByTestId("c")).toHaveClass("hairline-stack");
+    expect(screen.getByTestId("c")).not.toHaveAttribute("stacked");
+  });
+
+  it("CardMedia is a faded hairline-hatch well by default", () => {
+    render(<CardMedia data-testid="m">art</CardMedia>);
+    const well = screen.getByTestId("m");
+    expect(well).toHaveAttribute("data-slot", "card-media");
+    expect(well).toHaveClass("bg-hairline-hatch", "[--paper-fade:var(--deco-fade-edges)]");
+  });
+
+  it("CardMedia takes another ground, a fade direction, or no ground at all", () => {
+    const { rerender } = render(<CardMedia data-testid="m" ground="dots" fade="top" />);
+    expect(screen.getByTestId("m")).toHaveClass(
+      "bg-dot-grid",
+      "[--paper-fade:var(--deco-fade-top)]",
+    );
+    rerender(<CardMedia data-testid="m" ground="none" />);
+    expect(screen.getByTestId("m")).not.toHaveClass("bg-hairline-hatch");
+    expect(screen.getByTestId("m")).not.toHaveClass("bg-dot-grid");
+  });
 });

package/src/components/card/card.tsx

@@ -2,6 +2,7 @@
 
 import {
   forwardRef,
+  useEffect,
   useRef,
   useState,
   useCallback,
@@ -17,18 +18,21 @@ import { cn } from "../../lib/cn";
 // this one rung so the SAME logical block shows ONE radius across editor↔preview
 // (was rounded-xl = 8px, whose meaning silently changed with the --radius-xl override
 // — see #19). Overlays (Dialog/AlertDialog) deliberately use a larger rung.
-export const cardVariants = cva("rounded-lg border bg-card text-card-foreground shadow-sm", {
-  variants: {
-    // Opt-in hover-lift for clickable cards. Gated by --motion-factor via the
-    // duration-* utility; the transform is neutralized under OS reduced-motion
-    // (the shadow/border still respond — "reduced != none").
-    interactive: {
-      true: "cursor-pointer transition-[translate,box-shadow,border-color] duration-base ease-standard hover:-translate-y-1 hover:border-ring/40 hover:shadow-md focus-ring motion-reduce:hover:translate-y-0",
-      false: "",
+export const cardVariants = cva(
+  "rounded-lg border border-card-border bg-card text-card-foreground shadow-card",
+  {
+    variants: {
+      // Opt-in hover-lift for clickable cards. Gated by --motion-factor via the
+      // duration-* utility; the transform is neutralized under OS reduced-motion
+      // (the shadow/border still respond — "reduced != none").
+      interactive: {
+        true: "cursor-pointer transition-[translate,box-shadow,border-color] duration-base ease-standard hover:-translate-y-1 hover:border-ring/40 hover:shadow-md focus-ring motion-reduce:hover:translate-y-0",
+        false: "",
+      },
     },
+    defaultVariants: { interactive: false },
   },
-  defaultVariants: { interactive: false },
-});
+);
 
 // Grid container for the OPTIONAL detail panel — applied only when `detail` is set.
 // `fixed` keeps the panel track at its full size; `hover` collapses it to 0 at rest and
@@ -88,6 +92,13 @@ export interface CardProps
   detailSize?: string;
   /** Accessible label for the detail region. @default "Details" */
   detailLabel?: string;
+  /**
+   * Opt-in hairline gesture: the edges of two sheets stacked behind the card's
+   * top edge (the `hairline-stack` utility). It draws OUTSIDE the card, so it
+   * needs ~12px of room above and a card that does not clip — a plain card, not
+   * a `detail` one (whose grid is `overflow-hidden`). @default false
+   */
+  stacked?: boolean;
 }
 
 /**
@@ -110,12 +121,22 @@ function CardWithHoverDetail({
 }: CardProps) {
   const [isRevealed, setIsRevealed] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
+  const concealRafRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (concealRafRef.current !== null) cancelAnimationFrame(concealRafRef.current);
+    };
+  }, []);
 
   const reveal = useCallback(() => setIsRevealed(true), []);
   const conceal = useCallback(() => {
     // Only conceal if focus has truly left the card (not moved to detail).
     // Use requestAnimationFrame so the new focusIn event fires first.
-    requestAnimationFrame(() => {
+    // Tracked in a ref so it can be cancelled if the card unmounts before the
+    // frame fires (a focus-out right before navigation away, say).
+    concealRafRef.current = requestAnimationFrame(() => {
+      concealRafRef.current = null;
       if (containerRef.current && !containerRef.current.contains(document.activeElement)) {
         setIsRevealed(false);
       }
@@ -142,6 +163,7 @@ function CardWithHoverDetail({
   return (
     <div
       ref={containerRef}
+      data-slot="card"
       className={cn(
         cardVariants({ interactive }),
         cardDetailVariants({ detailPlacement, detailReveal: "hover" }),
@@ -161,6 +183,7 @@ function CardWithHoverDetail({
         role="region"
         aria-label={detailLabel}
         aria-hidden={!isRevealed}
+        data-slot="card-detail"
         className={cn("overflow-hidden bg-background p-6", dividerEdge, dividerColor)}
       >
         {detail}
@@ -173,6 +196,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
   {
     className,
     interactive,
+    stacked,
     detail,
     detailPlacement = "side",
     detailReveal = "fixed",
@@ -189,7 +213,8 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
     return (
       <div
         ref={ref}
-        className={cn(cardVariants({ interactive }), className)}
+        data-slot="card"
+        className={cn(cardVariants({ interactive }), stacked && "hairline-stack", className)}
         style={style}
         {...props}
       >
@@ -230,6 +255,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
   return (
     <div
       ref={ref}
+      data-slot="card"
       className={cn(
         cardVariants({ interactive }),
         cardDetailVariants({ detailPlacement, detailReveal }),
@@ -243,6 +269,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
       <div
         role="region"
         aria-label={detailLabel}
+        data-slot="card-detail"
         className={cn("overflow-hidden bg-background p-6", dividerEdge, dividerColor)}
       >
         {detail}
@@ -253,7 +280,21 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
 
 export const CardHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
   function CardHeader({ className, ...props }, ref) {
-    return <div ref={ref} className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />;
+    return (
+      <div
+        ref={ref}
+        data-slot="card-header"
+        // With a `CardAction` inside, the header becomes the two-column grid the
+        // action's `col-start-2 row-span-2` placement assumes (title + description
+        // stack on the left, the action top-right); without one, nothing changes.
+        className={cn(
+          "flex flex-col gap-1.5 p-6",
+          "has-data-[slot=card-action]:grid has-data-[slot=card-action]:auto-rows-min has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-action]:items-start",
+          className,
+        )}
+        {...props}
+      />
+    );
   },
 );
 
@@ -276,7 +317,14 @@ export const CardTitle = forwardRef<HTMLDivElement, CardTitleProps>(function Car
   { className, as: Tag = "div", ...props },
   ref,
 ) {
-  return <Tag ref={ref} className={cn("text-title leading-none", className)} {...props} />;
+  return (
+    <Tag
+      ref={ref}
+      data-slot="card-title"
+      className={cn("text-title leading-(--card-title-leading)", className)}
+      {...props}
+    />
+  );
 });
 
 export interface CardDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
@@ -293,11 +341,12 @@ export const CardDescription = forwardRef<HTMLParagraphElement, CardDescriptionP
     return (
       <p
         ref={ref}
+        data-slot="card-description"
         // `text-balance` sets `text-wrap: balance`. #336's real defect was an
         // invalid, misspelled utility name that emitted zero CSS (NOT a
         // tailwind-merge conflict) — this is the real, registered class.
         className={cn(
-          "text-sm text-balance text-muted-foreground",
+          "text-body text-balance text-muted-foreground",
           measure && "max-w-prose",
           className,
         )}
@@ -312,6 +361,7 @@ export const CardAction = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivEleme
     return (
       <div
         ref={ref}
+        data-slot="card-action"
         className={cn("col-start-2 row-span-2 row-start-1 self-start justify-self-end", className)}
         {...props}
       />
@@ -319,14 +369,69 @@ export const CardAction = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivEleme
   },
 );
 
+const cardMediaVariants = cva("flex min-h-40 items-center justify-center p-6", {
+  variants: {
+    ground: {
+      hatch: "bg-hairline-hatch",
+      dots: "bg-dot-grid",
+      none: "",
+    },
+    // The ground is never flat: it fades across the well. Literal classes (not
+    // an interpolated one) so Tailwind can see them.
+    fade: {
+      edges: "[--paper-fade:var(--deco-fade-edges)]",
+      top: "[--paper-fade:var(--deco-fade-top)]",
+      bottom: "[--paper-fade:var(--deco-fade-bottom)]",
+      center: "[--paper-fade:var(--deco-fade-center)]",
+    },
+  },
+  defaultVariants: { ground: "hatch", fade: "edges" },
+});
+
+export interface CardMediaProps
+  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof cardMediaVariants> {}
+
+/**
+ * The card's media WELL — the recessed region that holds an illustration, a
+ * mini chart, a product fragment or a logo grid. Its ground is a faded hairline
+ * hatch by default (`ground="dots"` for a dot field, `"none"` for a bare well),
+ * painted on an inert layer behind the media, so whatever you put in it sits ON
+ * the texture and is never tinted or masked by it.
+ *
+ * Place it above `CardHeader` (media first) or below `CardContent`. It centres
+ * its children; pass `className` to change that.
+ */
+export const CardMedia = forwardRef<HTMLDivElement, CardMediaProps>(function CardMedia(
+  { className, ground, fade, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-slot="card-media"
+      className={cn(cardMediaVariants({ ground, fade }), className)}
+      {...props}
+    />
+  );
+});
+
 export const CardContent = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
   function CardContent({ className, ...props }, ref) {
-    return <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />;
+    return (
+      <div ref={ref} data-slot="card-content" className={cn("p-6 pt-0", className)} {...props} />
+    );
   },
 );
 
 export const CardFooter = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
   function CardFooter({ className, ...props }, ref) {
-    return <div ref={ref} className={cn("flex items-center p-6 pt-0", className)} {...props} />;
+    return (
+      <div
+        ref={ref}
+        data-slot="card-footer"
+        className={cn("flex items-center p-6 pt-0", className)}
+        {...props}
+      />
+    );
   },
 );

package/src/components/card/index.ts

@@ -8,6 +8,8 @@ export {
   CardDescription,
   type CardDescriptionProps,
   CardAction,
+  CardMedia,
+  type CardMediaProps,
   CardContent,
   CardFooter,
 } from "./card";

package/src/components/carousel/carousel.test.tsx

@@ -0,0 +1,169 @@
+import { createRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { DirectionProvider } from "@radix-ui/react-direction";
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from "./carousel";
+
+function renderCarousel(props: Partial<React.ComponentProps<typeof Carousel>> = {}) {
+  return render(
+    <Carousel {...props}>
+      <CarouselContent>
+        <CarouselItem>
+          <input aria-label="slide input" defaultValue="abc" />
+        </CarouselItem>
+        <CarouselItem>Slide 2</CarouselItem>
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+    </Carousel>,
+  );
+}
+
+describe("Carousel keyboard handling", () => {
+  it("does not intercept ArrowLeft/ArrowRight when the target is a text input", () => {
+    renderCarousel();
+    const input = screen.getByLabelText("slide input") as HTMLInputElement;
+    input.focus();
+    const event = fireEvent.keyDown(input, { key: "ArrowRight", bubbles: true });
+    // `fireEvent` returns `false` from `dispatchEvent` only when
+    // `preventDefault()` was called — the carousel must leave the caret event
+    // alone so it reaches the input's own default behavior.
+    expect(event).toBe(true);
+  });
+
+  it("still intercepts ArrowLeft/ArrowRight outside of an editable target", () => {
+    renderCarousel();
+    const region = screen.getByRole("region");
+    const event = fireEvent.keyDown(region, { key: "ArrowRight", bubbles: true });
+    expect(event).toBe(false);
+  });
+});
+
+describe("Carousel RTL keyboard mapping", () => {
+  it("flips ArrowLeft/ArrowRight to the visually-adjacent slide under dir=rtl", () => {
+    let scrollPrevSpy: ReturnType<typeof vi.spyOn> | undefined;
+    let scrollNextSpy: ReturnType<typeof vi.spyOn> | undefined;
+    render(
+      <DirectionProvider dir="rtl">
+        <Carousel
+          setApi={(api) => {
+            if (!api) return;
+            scrollPrevSpy = vi.spyOn(api, "scrollPrev");
+            scrollNextSpy = vi.spyOn(api, "scrollNext");
+          }}
+        >
+          <CarouselContent>
+            <CarouselItem>Slide 1</CarouselItem>
+            <CarouselItem>Slide 2</CarouselItem>
+          </CarouselContent>
+        </Carousel>
+      </DirectionProvider>,
+    );
+    const region = screen.getByRole("region");
+    // In RTL, ArrowLeft is the visually-forward direction — it must trigger
+    // the SAME embla call the "Next slide" button does, not "Previous".
+    fireEvent.keyDown(region, { key: "ArrowLeft" });
+    expect(scrollNextSpy).toHaveBeenCalledTimes(1);
+    expect(scrollPrevSpy).not.toHaveBeenCalled();
+
+    fireEvent.keyDown(region, { key: "ArrowRight" });
+    expect(scrollPrevSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the physical mapping under dir=ltr (default)", () => {
+    let scrollPrevSpy: ReturnType<typeof vi.spyOn> | undefined;
+    let scrollNextSpy: ReturnType<typeof vi.spyOn> | undefined;
+    render(
+      <Carousel
+        setApi={(api) => {
+          if (!api) return;
+          scrollPrevSpy = vi.spyOn(api, "scrollPrev");
+          scrollNextSpy = vi.spyOn(api, "scrollNext");
+        }}
+      >
+        <CarouselContent>
+          <CarouselItem>Slide 1</CarouselItem>
+          <CarouselItem>Slide 2</CarouselItem>
+        </CarouselContent>
+      </Carousel>,
+    );
+    const region = screen.getByRole("region");
+    fireEvent.keyDown(region, { key: "ArrowRight" });
+    expect(scrollNextSpy).toHaveBeenCalledTimes(1);
+    fireEvent.keyDown(region, { key: "ArrowLeft" });
+    expect(scrollPrevSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses ArrowUp/ArrowDown instead of ArrowLeft/ArrowRight for a vertical carousel", () => {
+    let scrollPrevSpy: ReturnType<typeof vi.spyOn> | undefined;
+    let scrollNextSpy: ReturnType<typeof vi.spyOn> | undefined;
+    render(
+      <Carousel
+        orientation="vertical"
+        setApi={(api) => {
+          if (!api) return;
+          scrollPrevSpy = vi.spyOn(api, "scrollPrev");
+          scrollNextSpy = vi.spyOn(api, "scrollNext");
+        }}
+      >
+        <CarouselContent>
+          <CarouselItem>Slide 1</CarouselItem>
+          <CarouselItem>Slide 2</CarouselItem>
+        </CarouselContent>
+      </Carousel>,
+    );
+    const region = screen.getByRole("region");
+    fireEvent.keyDown(region, { key: "ArrowRight" });
+    expect(scrollNextSpy).not.toHaveBeenCalled();
+    fireEvent.keyDown(region, { key: "ArrowDown" });
+    expect(scrollNextSpy).toHaveBeenCalledTimes(1);
+    fireEvent.keyDown(region, { key: "ArrowUp" });
+    expect(scrollPrevSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("CarouselPrevious / CarouselNext", () => {
+  it("forward a ref to the underlying button", () => {
+    const prevRef = createRef<HTMLButtonElement>();
+    const nextRef = createRef<HTMLButtonElement>();
+    renderCarousel();
+    render(
+      <Carousel>
+        <CarouselContent>
+          <CarouselItem>1</CarouselItem>
+        </CarouselContent>
+        <CarouselPrevious ref={prevRef} />
+        <CarouselNext ref={nextRef} />
+      </Carousel>,
+    );
+    expect(prevRef.current).toBeInstanceOf(HTMLButtonElement);
+    expect(nextRef.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  it("keeps the buttons inset on narrow viewports (no unconditional negative offset)", () => {
+    render(
+      <Carousel>
+        <CarouselContent>
+          <CarouselItem>1</CarouselItem>
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+      </Carousel>,
+    );
+    const prev = screen.getByRole("button", { name: "Previous slide" });
+    const next = screen.getByRole("button", { name: "Next slide" });
+    // The negative offset that pushes the button outside the carousel box
+    // only applies from `sm:` up; unconditionally offsetting it caused
+    // horizontal overflow on narrow phone screens.
+    expect(prev.className).not.toMatch(/(?<!sm:)-start-12/);
+    expect(next.className).not.toMatch(/(?<!sm:)-end-12/);
+    expect(prev.className).toContain("sm:-start-12");
+    expect(next.className).toContain("sm:-end-12");
+  });
+});