@elabs-ai/components-ui 4.1.0 → 4.2.0

package/src/components/bounded-number/bounded-number.tsx

@@ -28,83 +28,86 @@ export interface BoundedNumberProps extends NumberInputProps {
  * `null` AND the field is not focused, so the underlying input stays fully
  * clickable/typable and still round-trips to `null` on an empty blur.
  */
-export const BoundedNumber = forwardRef<HTMLDivElement, BoundedNumberProps>(function BoundedNumber(
-  {
-    value: valueProp,
-    defaultValue,
-    onValueChange,
-    emptyLabel,
-    onFocus,
-    onBlur,
-    className,
-    ...props
-  },
-  ref,
-) {
-  const { t } = useLocale();
-  const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
-  const isControlled = valueProp !== undefined;
-  const [internalValue, setInternalValue] = useState<number | null>(
-    defaultValue !== undefined ? defaultValue : null,
-  );
-  const [focused, setFocused] = useState(false);
-  const currentValue = isControlled ? valueProp : internalValue;
-
-  const handleValueChange = useCallback(
-    (next: number | null) => {
-      if (!isControlled) setInternalValue(next);
-      onValueChange?.(next);
+export const BoundedNumber = forwardRef<HTMLInputElement, BoundedNumberProps>(
+  function BoundedNumber(
+    {
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      emptyLabel,
+      onFocus,
+      onBlur,
+      className,
+      ...props
     },
-    [isControlled, onValueChange],
-  );
+    ref,
+  ) {
+    const { t } = useLocale();
+    const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
+    const isControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = useState<number | null>(
+      defaultValue !== undefined ? defaultValue : null,
+    );
+    const [focused, setFocused] = useState(false);
+    const currentValue = isControlled ? valueProp : internalValue;
 
-  const handleFocus = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(true);
-      onFocus?.(event);
-    },
-    [onFocus],
-  );
+    const handleValueChange = useCallback(
+      (next: number | null) => {
+        if (!isControlled) setInternalValue(next);
+        onValueChange?.(next);
+      },
+      [isControlled, onValueChange],
+    );
 
-  const handleBlur = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(false);
-      onBlur?.(event);
-    },
-    [onBlur],
-  );
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
 
-  const showEmptyLabel = currentValue == null && !focused;
+    const showEmptyLabel = currentValue == null && !focused;
 
-  return (
-    // `className` lands on the ROOT (the positioning context), not on the
-    // inner `NumberInput`: a width utility on the inner control would resolve
-    // against a shrink-to-fit wrapper and silently do nothing, so
-    // `className="w-full"` could never widen the field. `w-36` here is
-    // `NumberInput`'s own default width, re-declared so `cn()` lets the caller
-    // override it; the input then simply fills the root.
-    <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
-      <NumberInput
-        ref={ref}
-        value={currentValue}
-        onValueChange={handleValueChange}
-        onFocus={handleFocus}
-        onBlur={handleBlur}
-        className="w-full"
-        {...props}
-      />
-      {showEmptyLabel && (
-        <span
-          aria-hidden="true"
-          data-slot="bounded-number-empty-label"
-          className={cn(
-            "pointer-events-none absolute inset-0 flex items-center justify-center",
-            "text-body text-muted-foreground",
-          )}
-        >
-          {resolvedEmptyLabel}
-        </span>
-      )}
-    </div>
-  );
-});
+    return (
+      // `className` lands on the ROOT (the positioning context), not on the
+      // inner `NumberInput`: a width utility on the inner control would resolve
+      // against a shrink-to-fit wrapper and silently do nothing, so
+      // `className="w-full"` could never widen the field. `w-36` is this
+      // preset's own default width (`NumberInput` itself is unconstrained and
+      // fills its container) — `cn()` lets the caller override it, and the
+      // inner `NumberInput` simply fills the root via `className="w-full"`.
+      <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
+        <NumberInput
+          ref={ref}
+          value={currentValue}
+          onValueChange={handleValueChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          className="w-full"
+          {...props}
+        />
+        {showEmptyLabel && (
+          <span
+            aria-hidden="true"
+            data-slot="bounded-number-empty-label"
+            className={cn(
+              "pointer-events-none absolute inset-0 flex items-center justify-center",
+              "text-body text-muted-foreground",
+            )}
+          >
+            {resolvedEmptyLabel}
+          </span>
+        )}
+      </div>
+    );
+  },
+);

package/src/components/breadcrumb/breadcrumb.tsx

@@ -6,7 +6,8 @@ import { useLocale } from "../locale-provider";
 
 export const Breadcrumb = forwardRef<HTMLElement, ComponentProps<"nav">>(
   function Breadcrumb(props, ref) {
-    return <nav ref={ref} aria-label="breadcrumb" {...props} />;
+    const { t } = useLocale();
+    return <nav ref={ref} aria-label={t("ui.breadcrumb.label")} {...props} />;
   },
 );
 export const BreadcrumbList = forwardRef<HTMLOListElement, ComponentProps<"ol">>(
@@ -15,7 +16,7 @@ export const BreadcrumbList = forwardRef<HTMLOListElement, ComponentProps<"ol">>
       <ol
         ref={ref}
         className={cn(
-          "flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground",
+          "flex flex-wrap items-center gap-1.5 break-words text-body text-muted-foreground",
           className,
         )}
         {...props}

package/src/components/button/button.tsx

@@ -4,15 +4,21 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
 export const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap touch-manipulation rounded-md text-body font-medium transition-[color,background-color,border-color,box-shadow,scale] duration-fast ease-standard active:scale-[0.98] motion-reduce:active:scale-100 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap touch-manipulation rounded-control text-body font-control transition-[color,background-color,border-color,box-shadow,scale] duration-fast ease-standard active:scale-[0.98] motion-reduce:active:scale-100 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
   {
     variants: {
       variant: {
+        // Disabled treatment is ONE rule for every variant, inherited from the
+        // base string above (`disabled:pointer-events-none disabled:opacity-50`)
+        // — no per-variant fill swap. A solid-fill variant fading via opacity
+        // still reads as "off" against `--muted`/`--background` in both themes;
+        // keeping one mechanism (vs. a bg-muted swap on some variants only) is
+        // what made Input's disabled state internally inconsistent (#286).
         default:
-          "bg-primary text-primary-foreground hover:bg-primary/90 disabled:bg-muted disabled:text-muted-foreground disabled:opacity-100",
+          "bg-primary text-primary-foreground hover:bg-primary-hover active:bg-primary-active",
         secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
         destructive:
-          "bg-destructive text-destructive-foreground hover:bg-destructive/90 disabled:bg-muted disabled:text-muted-foreground disabled:opacity-100",
+          "bg-destructive text-destructive-foreground hover:bg-destructive-hover active:bg-destructive-active",
         outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
         // The calm "outlined but quiet" rung (#194, research 02 §3a). `outline` uses
         // the form-field `border-input` token, `outline-subtle` uses `border-border`.
@@ -24,17 +30,17 @@ export const buttonVariants = cva(
         "outline-subtle":
           "border border-border bg-background hover:bg-accent hover:text-accent-foreground",
         ghost: "hover:bg-accent hover:text-accent-foreground",
-        // #399 — a link button is TEXT on the page, so it takes the on-surface
-        // `-text` rung; `bg-primary` above keeps the fill rung.
-        link: "text-primary-text underline-offset-4 hover:underline",
+        // #399 — a link button is TEXT on the page: `--link` defaults to the
+        // on-surface `--primary-text` rung; `bg-primary` above keeps the fill rung.
+        link: "text-link underline-offset-4 hover:underline",
       },
       size: {
-        sm: "h-8 rounded-md px-3 text-meta",
-        default: "h-9 px-4 py-2",
-        lg: "h-10 rounded-md px-6",
-        icon: "size-9",
-        "icon-sm": "size-8",
-        "icon-lg": "size-10",
+        sm: "h-control-sm px-3 text-meta",
+        default: "h-control px-4 py-2",
+        lg: "h-control-lg px-6",
+        icon: "size-control",
+        "icon-sm": "size-control-sm",
+        "icon-lg": "size-control-lg",
       },
     },
     defaultVariants: { variant: "default", size: "default" },

package/src/components/button-group/button-group.tsx

@@ -44,7 +44,7 @@ export const ButtonGroupText = forwardRef<
     <Comp
       ref={ref}
       className={cn(
-        "flex items-center gap-2 rounded-md border bg-muted px-4 text-sm font-medium shadow-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        "flex items-center gap-2 rounded-md border bg-muted px-4 text-body font-medium shadow-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}

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",

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

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { Card, CardDescription, CardTitle } from "./card";
 
 describe("Card", () => {
@@ -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">

package/src/components/card/card.tsx

@@ -2,6 +2,7 @@
 
 import {
   forwardRef,
+  useEffect,
   useRef,
   useState,
   useCallback,
@@ -110,12 +111,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 +153,7 @@ function CardWithHoverDetail({
   return (
     <div
       ref={containerRef}
+      data-slot="card"
       className={cn(
         cardVariants({ interactive }),
         cardDetailVariants({ detailPlacement, detailReveal: "hover" }),
@@ -161,6 +173,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}
@@ -189,6 +202,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
     return (
       <div
         ref={ref}
+        data-slot="card"
         className={cn(cardVariants({ interactive }), className)}
         style={style}
         {...props}
@@ -230,6 +244,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 +258,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 +269,14 @@ 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"
+        className={cn("flex flex-col gap-1.5 p-6", className)}
+        {...props}
+      />
+    );
   },
 );
 
@@ -276,7 +299,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-none", className)}
+      {...props}
+    />
+  );
 });
 
 export interface CardDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
@@ -293,11 +323,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 +343,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}
       />
@@ -321,12 +353,21 @@ export const CardAction = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivEleme
 
 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/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");
+  });
+});