@elabs-ai/components-ui 4.1.0 → 4.2.0

package/src/components/carousel/carousel.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createContext,
   forwardRef,
@@ -6,13 +8,29 @@ import {
   useEffect,
   useState,
   type ComponentProps,
+  type ElementRef,
   type HTMLAttributes,
   type KeyboardEvent,
 } from "react";
+import { useDirection } from "@radix-ui/react-direction";
 import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
 import { ArrowLeft, ArrowRight } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { Button } from "../button";
+import { useLocale } from "../locale-provider";
+
+/**
+ * True when the keyboard event's target already owns arrow-key semantics of
+ * its own (a text field's caret, a contenteditable's selection) — the
+ * carousel must not steal ArrowLeft/ArrowRight from a form control that
+ * happens to live inside the active slide.
+ */
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+}
 
 type CarouselApi = UseEmblaCarouselType[1];
 type CarouselOptions = NonNullable<Parameters<typeof useEmblaCarousel>[0]>;
@@ -62,17 +80,20 @@ export const Carousel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement
       // aria-roledescription changes the announcement, it does not name the
       // landmark. Default is overridable; pass a specific label ("Product
       // photos") when the carousel's purpose isn't generic. Issue #279.
-      "aria-label": ariaLabel = "Carousel",
+      "aria-label": ariaLabel,
       ...props
     },
     ref,
   ) {
+    const { t } = useLocale();
+    const resolvedAriaLabel = ariaLabel ?? t("ui.carousel.label");
     const [carouselRef, api] = useEmblaCarousel(
       { ...opts, axis: orientation === "horizontal" ? "x" : "y" },
       plugins,
     );
     const [canScrollPrev, setCanScrollPrev] = useState(false);
     const [canScrollNext, setCanScrollNext] = useState(false);
+    const dir = useDirection();
 
     const onSelect = useCallback((a: CarouselApi) => {
       if (!a) return;
@@ -85,15 +106,42 @@ export const Carousel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement
 
     const onKeyDown = useCallback(
       (e: KeyboardEvent<HTMLDivElement>) => {
+        // Don't steal ArrowLeft/ArrowRight from a text field's caret or a
+        // contenteditable's selection inside the active slide.
+        if (isEditableTarget(e.target)) return;
+
+        if (orientation === "vertical") {
+          if (e.key === "ArrowUp") {
+            e.preventDefault();
+            scrollPrev();
+          } else if (e.key === "ArrowDown") {
+            e.preventDefault();
+            scrollNext();
+          }
+          return;
+        }
+
+        // Horizontal: the PHYSICAL key maps to the visually-adjacent slide,
+        // which flips with writing direction — in RTL, ArrowLeft moves toward
+        // the next slide (visually to the left of the current one), not prev.
+        const isRtl = dir === "rtl";
         if (e.key === "ArrowLeft") {
           e.preventDefault();
-          scrollPrev();
+          if (isRtl) {
+            scrollNext();
+          } else {
+            scrollPrev();
+          }
         } else if (e.key === "ArrowRight") {
           e.preventDefault();
-          scrollNext();
+          if (isRtl) {
+            scrollPrev();
+          } else {
+            scrollNext();
+          }
         }
       },
-      [scrollPrev, scrollNext],
+      [orientation, dir, scrollPrev, scrollNext],
     );
 
     useEffect(() => {
@@ -105,6 +153,7 @@ export const Carousel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement
       api.on("reInit", onSelect);
       api.on("select", onSelect);
       return () => {
+        api.off("reInit", onSelect);
         api.off("select", onSelect);
       };
     }, [api, onSelect]);
@@ -128,7 +177,7 @@ export const Carousel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement
           className={cn("relative", className)}
           role="region"
           aria-roledescription="carousel"
-          aria-label={ariaLabel}
+          aria-label={resolvedAriaLabel}
           {...props}
         >
           {children}
@@ -176,20 +225,28 @@ export const CarouselItem = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivEle
   },
 );
 
-export function CarouselPrevious({ className, ...props }: ComponentProps<typeof Button>) {
+export const CarouselPrevious = forwardRef<
+  ElementRef<typeof Button>,
+  ComponentProps<typeof Button>
+>(function CarouselPrevious({ className, ...props }, ref) {
   const { scrollPrev, canScrollPrev, orientation } = useCarousel();
+  const { t } = useLocale();
   return (
     <Button
+      ref={ref}
       variant="outline"
       size="icon"
       disabled={!canScrollPrev}
       onClick={scrollPrev}
-      aria-label="Previous slide"
+      aria-label={t("previousSlide")}
       className={cn(
         "absolute size-8 rounded-full",
+        // Inset on narrow screens (no room for the button to sit outside
+        // the carousel box without overflowing horizontally); pushed
+        // outside the box only from `sm` up, where there's margin for it.
         orientation === "horizontal"
-          ? "-start-12 top-1/2 -translate-y-1/2"
-          : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
+          ? "start-2 top-1/2 -translate-y-1/2 sm:-start-12"
+          : "top-2 left-1/2 -translate-x-1/2 rotate-90 sm:-top-12",
         className,
       )}
       {...props}
@@ -197,29 +254,33 @@ export function CarouselPrevious({ className, ...props }: ComponentProps<typeof
       <ArrowLeft className="size-4" data-rtl-flip />
     </Button>
   );
-}
+});
 
-export function CarouselNext({ className, ...props }: ComponentProps<typeof Button>) {
-  const { scrollNext, canScrollNext, orientation } = useCarousel();
-  return (
-    <Button
-      variant="outline"
-      size="icon"
-      disabled={!canScrollNext}
-      onClick={scrollNext}
-      aria-label="Next slide"
-      className={cn(
-        "absolute size-8 rounded-full",
-        orientation === "horizontal"
-          ? "-end-12 top-1/2 -translate-y-1/2"
-          : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
-        className,
-      )}
-      {...props}
-    >
-      <ArrowRight className="size-4" data-rtl-flip />
-    </Button>
-  );
-}
+export const CarouselNext = forwardRef<ElementRef<typeof Button>, ComponentProps<typeof Button>>(
+  function CarouselNext({ className, ...props }, ref) {
+    const { scrollNext, canScrollNext, orientation } = useCarousel();
+    const { t } = useLocale();
+    return (
+      <Button
+        ref={ref}
+        variant="outline"
+        size="icon"
+        disabled={!canScrollNext}
+        onClick={scrollNext}
+        aria-label={t("nextSlide")}
+        className={cn(
+          "absolute size-8 rounded-full",
+          orientation === "horizontal"
+            ? "end-2 top-1/2 -translate-y-1/2 sm:-end-12"
+            : "bottom-2 left-1/2 -translate-x-1/2 rotate-90 sm:-bottom-12",
+          className,
+        )}
+        {...props}
+      >
+        <ArrowRight className="size-4" data-rtl-flip />
+      </Button>
+    );
+  },
+);
 
 export type { CarouselApi };

package/src/components/change-review/change-review.tsx

@@ -67,6 +67,7 @@ import { Badge } from "../badge/badge";
 import { StatePanel } from "../state-panel/state-panel";
 import { StatusIcon } from "../status-badge/status-badge";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../collapsible/collapsible";
+import { useLocale } from "../locale-provider";
 
 // ─── Public types ─────────────────────────────────────────────────────────────
 
@@ -283,6 +284,7 @@ export type ChangeReviewHeaderProps = HTMLAttributes<HTMLDivElement>;
  */
 export const ChangeReviewHeader = forwardRef<HTMLDivElement, ChangeReviewHeaderProps>(
   function ChangeReviewHeader({ className, ...props }, ref) {
+    const { t } = useLocale();
     const { state, actions, headingId } = useChangeReview();
     const { approvedCount, totalCount, allApproved, noneApproved } = state;
 
@@ -294,10 +296,10 @@ export const ChangeReviewHeader = forwardRef<HTMLDivElement, ChangeReviewHeaderP
       >
         <div className="flex items-center gap-2 min-w-0">
           <span id={headingId} className="text-subtitle font-semibold text-foreground truncate">
-            Review changes
+            {t("ui.changeReview.heading")}
           </span>
           <Badge variant={allApproved ? "success" : approvedCount > 0 ? "info" : "secondary"}>
-            {approvedCount} of {totalCount} approved
+            {t("ui.changeReview.approvedCount", { approved: approvedCount, total: totalCount })}
           </Badge>
         </div>
 
@@ -308,20 +310,20 @@ export const ChangeReviewHeader = forwardRef<HTMLDivElement, ChangeReviewHeaderP
               variant="outline-subtle"
               disabled={noneApproved}
               onClick={actions.rejectAll}
-              aria-label="Reject all changes"
+              aria-label={t("ui.changeReview.rejectAllLabel")}
             >
               <X aria-hidden="true" />
-              Reject all
+              {t("ui.changeReview.rejectAll")}
             </Button>
             <Button
               size="sm"
               variant={allApproved ? "secondary" : "default"}
               disabled={allApproved}
               onClick={actions.approveAll}
-              aria-label="Approve all changes"
+              aria-label={t("ui.changeReview.approveAllLabel")}
             >
               <CheckCheck aria-hidden="true" />
-              Approve all
+              {t("ui.changeReview.approveAll")}
             </Button>
           </div>
         )}
@@ -357,6 +359,7 @@ function isChangeProvenance(v: unknown): v is ChangeProvenance {
  */
 export const ChangeReviewProvenance = forwardRef<HTMLDivElement, ChangeReviewProvenanceProps>(
   function ChangeReviewProvenance({ provenance, className, ...props }, ref) {
+    const { t } = useLocale();
     if (isChangeProvenance(provenance)) {
       const { author, model, timestamp, note } = provenance;
       return (
@@ -367,7 +370,7 @@ export const ChangeReviewProvenance = forwardRef<HTMLDivElement, ChangeReviewPro
             className,
           )}
           role="group"
-          aria-label="Change provenance"
+          aria-label={t("ui.changeReview.provenanceLabel")}
           {...props}
         >
           {author && (
@@ -399,7 +402,7 @@ export const ChangeReviewProvenance = forwardRef<HTMLDivElement, ChangeReviewPro
         ref={ref}
         className={cn("pb-3 text-caption text-muted-foreground", className)}
         role="group"
-        aria-label="Change provenance"
+        aria-label={t("ui.changeReview.provenanceLabel")}
         {...props}
       >
         {provenance as ReactNode}
@@ -418,14 +421,15 @@ export type ChangeReviewListProps = HTMLAttributes<HTMLOListElement>;
  */
 export const ChangeReviewList = forwardRef<HTMLOListElement, ChangeReviewListProps>(
   function ChangeReviewList({ className, children, ...props }, ref) {
+    const { t } = useLocale();
     const { hunks, headingId } = useChangeReview();
 
     if (hunks.length === 0) {
       return (
         <StatePanel
           kind="empty"
-          title="No changes to review"
-          description="When an agent proposes edits, they'll appear here for your approval."
+          title={t("ui.changeReview.emptyTitle")}
+          description={t("ui.changeReview.emptyDescription")}
           className="my-2"
         />
       );
@@ -468,10 +472,10 @@ const HUNK_STATUS_ICONS: Record<ChangeHunkStatus, ReactNode> = {
   ),
 };
 
-const HUNK_STATUS_LABELS: Record<ChangeHunkStatus, string> = {
-  added: "added",
-  removed: "removed",
-  modified: "modified",
+const HUNK_STATUS_LABEL_KEYS: Record<ChangeHunkStatus, string> = {
+  added: "ui.changeReview.statusAdded",
+  removed: "ui.changeReview.statusRemoved",
+  modified: "ui.changeReview.statusModified",
 };
 
 // ─── Checks (verification evidence) ────────────────────────────────────────────
@@ -487,9 +491,9 @@ function isLongCheckDetail(detail: string): boolean {
   return detail.length > CHECK_DETAIL_COLLAPSE_THRESHOLD || detail.includes("\n");
 }
 
-const CHECK_PHASE_LABELS: Record<"before" | "after", string> = {
-  before: "Before",
-  after: "After",
+const CHECK_PHASE_LABEL_KEYS: Record<"before" | "after", string> = {
+  before: "ui.changeReview.phaseBefore",
+  after: "ui.changeReview.phaseAfter",
 };
 
 /**
@@ -526,9 +530,10 @@ function groupChecksByPhase(
  * decorative (`aria-hidden`); the status word is what reaches assistive tech.
  */
 function ChangeCheckRow({ check }: { check: CheckResult }) {
+  const { t } = useLocale();
   const [detailOpen, setDetailOpen] = useState(false);
   const { label, ok, detail, durationMs } = check;
-  const statusWord = ok ? "Passed" : "Failed";
+  const statusWord = ok ? t("ui.changeReview.checkPassed") : t("ui.changeReview.checkFailed");
   const hasDetail = detail !== undefined && detail !== "";
   const longDetail = hasDetail && isLongCheckDetail(detail);
 
@@ -552,7 +557,7 @@ function ChangeCheckRow({ check }: { check: CheckResult }) {
           <Collapsible open={detailOpen} onOpenChange={setDetailOpen}>
             <CollapsibleTrigger
               className={cn(
-                "flex items-center gap-1 self-start rounded-sm pl-5 text-caption text-muted-foreground",
+                "flex items-center gap-1 self-start rounded-sm ps-5 text-caption text-muted-foreground",
                 "hover:text-foreground focus-ring",
               )}
             >
@@ -563,16 +568,16 @@ function ChangeCheckRow({ check }: { check: CheckResult }) {
                   detailOpen ? "rotate-180" : "rotate-0",
                 )}
               />
-              {detailOpen ? "Hide detail" : "Show detail"}
+              {detailOpen ? t("ui.changeReview.hideDetail") : t("ui.changeReview.showDetail")}
             </CollapsibleTrigger>
             <CollapsibleContent data-slot="change-review-hunk-check-detail">
-              <p className="pl-5 pt-1 text-caption text-muted-foreground break-words">{detail}</p>
+              <p className="ps-5 pt-1 text-caption text-muted-foreground break-words">{detail}</p>
             </CollapsibleContent>
           </Collapsible>
         ) : (
           <p
             data-slot="change-review-hunk-check-detail"
-            className="pl-5 text-caption text-muted-foreground break-words"
+            className="ps-5 text-caption text-muted-foreground break-words"
           >
             {detail}
           </p>
@@ -583,6 +588,7 @@ function ChangeCheckRow({ check }: { check: CheckResult }) {
 
 /** The full checks section for one hunk — grouped by phase when applicable. */
 function ChangeReviewChecks({ checks }: { checks: CheckResult[] }) {
+  const { t } = useLocale();
   const groups = groupChecksByPhase(checks);
   const showPhaseLabels = groups.some((g) => g.phase !== undefined);
 
@@ -599,7 +605,7 @@ function ChangeReviewChecks({ checks }: { checks: CheckResult[] }) {
         >
           {showPhaseLabels && group.phase && (
             <span className="text-meta font-medium text-muted-foreground">
-              {CHECK_PHASE_LABELS[group.phase]}
+              {t(CHECK_PHASE_LABEL_KEYS[group.phase])}
             </span>
           )}
           <div className="flex flex-col gap-1.5">
@@ -636,12 +642,15 @@ export interface ChangeReviewHunkProps
  */
 export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>(
   function ChangeReviewHunk({ hunk, renderHunk, className, ...props }, ref) {
+    const { t } = useLocale();
     const { state, actions } = useChangeReview();
     const { id, title, before, after, status = "modified", provenance, checks } = hunk;
     const approved = state.approved.has(id);
 
-    const statusLabel = HUNK_STATUS_LABELS[status];
-    const toggleLabel = approved ? `Reject hunk: ${title ?? id}` : `Approve hunk: ${title ?? id}`;
+    const statusLabel = t(HUNK_STATUS_LABEL_KEYS[status]);
+    const toggleLabel = t(approved ? "ui.changeReview.rejectHunk" : "ui.changeReview.approveHunk", {
+      title: title ?? id,
+    });
 
     // Quiet, no-fill diff: before = struck muted text with a "−" marker, after =
     // foreground text with a "+" marker — separated by space, NOT colored
@@ -659,7 +668,7 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
                 >
                   −
                 </span>
-                <span className="sr-only">Before: </span>
+                <span className="sr-only">{t("ui.changeReview.beforePrefix")}</span>
                 <div className="min-w-0 break-words text-muted-foreground line-through decoration-muted-foreground/30">
                   {before}
                 </div>
@@ -670,7 +679,7 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
                 <span aria-hidden="true" className="shrink-0 select-none font-mono text-foreground">
                   +
                 </span>
-                <span className="sr-only">After: </span>
+                <span className="sr-only">{t("ui.changeReview.afterPrefix")}</span>
                 <div className="min-w-0 break-words text-foreground">{after}</div>
               </div>
             )}
@@ -691,7 +700,7 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
             {/* Status indicator: NON-color cue via symbol + color together */}
             <span
               role="img"
-              aria-label={`Change type: ${statusLabel}`}
+              aria-label={t("ui.changeReview.changeType", { status: statusLabel })}
               className="shrink-0 inline-flex items-center justify-center size-5"
             >
               {HUNK_STATUS_ICONS[status]}
@@ -732,7 +741,7 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
           <div className="flex items-center gap-1.5">
             <Badge variant="success" className="animate-in fade-in-0 duration-fast ease-entrance">
               <Check aria-hidden="true" className="size-3" />
-              Approved
+              {t("ui.changeReview.approvedBadge")}
             </Badge>
           </div>
         )}

package/src/components/checkbox/checkbox.tsx

@@ -10,6 +10,7 @@ export const Checkbox = forwardRef<
   return (
     <CheckboxPrimitive.Root
       ref={ref}
+      data-slot="checkbox"
       className={cn(
         "peer size-4 shrink-0 rounded-sm border border-input shadow-sm transition-colors duration-fast ease-standard",
         "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",

package/src/components/collapsible-panel/use-collapsible-panel.ts

@@ -25,9 +25,6 @@
  * state-keyed defaults for a generic panel. Sidebar passes its
  * `--sidebar-width` + `group-data-[collapsible=offcanvas]` literals and gets
  * back its exact original fragments (the byte-identical re-point).
- *
- * Fork-prevention: a second gap-spacer + fixed-slide width tween outside this
- * folder fails `pnpm collapse-fork:check` (scripts/check-collapse-fork.mjs).
  */
 import { useCallback, useMemo, useState } from "react";
 import { cn } from "../../lib/cn";

package/src/components/color-picker/color-picker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 // a2ui.exposed: yes
 import {
   forwardRef,
@@ -10,6 +12,7 @@ import {
 } from "react";
 import { cn } from "../../lib/cn";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { useLocale } from "../locale-provider";
 
 // ---------------------------------------------------------------------------
 // Token vocabulary
@@ -194,12 +197,14 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
     onValueChange,
     swatches = COLOR_TOKENS,
     allowCustom = false,
-    "aria-label": ariaLabel = "Pick color",
+    "aria-label": ariaLabel,
     className,
     ...props
   },
   ref,
 ) {
+  const { t } = useLocale();
+  const resolvedAriaLabel = ariaLabel ?? t("ui.colorPicker.pickColor");
   const isControlled = valueProp !== undefined;
   const [internalValue, setInternalValue] = useState<ColorToken | string>(
     defaultValue ?? "chart-1",
@@ -259,11 +264,11 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
         <PopoverTrigger asChild>
           <button
             type="button"
-            aria-label={ariaLabel}
+            aria-label={resolvedAriaLabel}
             aria-haspopup="dialog"
             aria-expanded={open}
             className={cn(
-              "inline-flex items-center gap-2 rounded-md border border-input bg-background px-3 py-1.5 text-sm shadow-sm",
+              "inline-flex items-center gap-2 rounded-md border border-input bg-background px-3 py-1.5 text-body shadow-sm",
               "transition-[color,box-shadow] duration-fast",
               "hover:bg-accent hover:text-accent-foreground",
               "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
@@ -271,7 +276,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
             )}
           >
             <TriggerSwatch value={current} />
-            <span className="text-muted-foreground">{current || "None"}</span>
+            <span className="text-muted-foreground">{current || t("ui.colorPicker.none")}</span>
           </button>
         </PopoverTrigger>
 
@@ -279,7 +284,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
           <div
             ref={groupRef}
             role="radiogroup"
-            aria-label="Color swatches"
+            aria-label={t("ui.colorPicker.swatches")}
             className="flex flex-wrap gap-1.5"
             onKeyDown={handleGroupKeyDown}
           >
@@ -296,18 +301,19 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
           {allowCustom && (
             <div className="mt-3 border-t border-border pt-3">
               {/* Custom hex is NOT theme-aware — it will not adapt to theme changes. */}
-              <p className="mb-1.5 text-xs text-muted-foreground">
+              <p className="mb-1.5 text-meta text-muted-foreground">
                 {/* #124: inline running text — ink rung, not the 3:1 mark rung. */}
-                Custom hex <span className="text-warning-text">(not theme-aware)</span>
+                {t("ui.colorPicker.customHexLabel")}{" "}
+                <span className="text-warning-text">{t("ui.colorPicker.notThemeAware")}</span>
               </p>
               <div className="flex gap-2">
                 <input
                   type="text"
                   value={customHex}
-                  placeholder="#3b82f6"
+                  placeholder="#3b82f6" // i18n-exempt: example hex value, not prose
                   maxLength={7}
                   spellCheck={false}
-                  aria-label="Custom hex color"
+                  aria-label={t("ui.colorPicker.customHex")}
                   onChange={(e) => setCustomHex(e.target.value)}
                   onKeyDown={(e) => {
                     if (e.key === "Enter") {
@@ -316,7 +322,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
                     }
                   }}
                   className={cn(
-                    "h-8 w-28 rounded-md border border-input bg-background px-2 text-sm",
+                    "h-8 w-28 rounded-md border border-input bg-background px-2 text-body",
                     "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                     "placeholder:text-muted-foreground",
                   )}
@@ -325,7 +331,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
                   type="button"
                   onClick={handleCustomSubmit}
                   className={cn(
-                    "h-8 rounded-md border border-input bg-background px-2 text-sm",
+                    "h-8 rounded-md border border-input bg-background px-2 text-body",
                     "hover:bg-accent hover:text-accent-foreground",
                     "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                   )}

package/src/components/combobox/combobox.stories.tsx

@@ -5,6 +5,16 @@ const meta = {
   title: "Forms/Combobox",
   component: Combobox,
   tags: ["autodocs"],
+  // The trigger fills its container by default (no hard-fixed width) — cap
+  // the docs canvas to a realistic form-field width instead of letting it
+  // stretch the full autodocs page.
+  decorators: [
+    (Story) => (
+      <div className="w-full max-w-md">
+        <Story />
+      </div>
+    ),
+  ],
   argTypes: {
     options: {
       description: "Array of `{ label, value }` options.",

package/src/components/combobox/combobox.test.tsx

@@ -66,6 +66,60 @@ describe("Combobox", () => {
     );
     expect(screen.getByRole("combobox")).toHaveTextContent("Custom Value");
   });
+
+  it("does not hard-fix the trigger width — fills its container by default", () => {
+    render(<Combobox options={[{ label: "A", value: "a" }]} />);
+    expect(screen.getByRole("combobox").className).not.toMatch(/\bw-56\b/);
+  });
+});
+
+// jsdom doesn't implement Element.scrollIntoView, which cmdk calls internally
+// to keep the auto-highlighted item visible — see the comment on the
+// `allowCustomValue` describe below for the full explanation.
+describe("Combobox (options interaction)", () => {
+  let originalScrollIntoView: typeof Element.prototype.scrollIntoView;
+
+  beforeEach(() => {
+    originalScrollIntoView = Element.prototype.scrollIntoView;
+    Element.prototype.scrollIntoView = vi.fn();
+  });
+
+  afterEach(() => {
+    Element.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  // #reviewed 1.7 — a hand-rolled `onValueChange ? onValueChange(v) : setInternal(v)`
+  // never updates internal state once a listener is attached, so an
+  // uncontrolled Combobox with an onValueChange handler never shows its own
+  // selection on the trigger.
+  it("updates the trigger's own displayed value when uncontrolled even with an onValueChange listener", async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={[{ label: "Alpha", value: "a" }]} onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("combobox"));
+    await userEvent.click(await screen.findByRole("option", { name: "Alpha" }));
+    expect(onValueChange).toHaveBeenCalledWith("a");
+    expect(screen.getByRole("combobox")).toHaveTextContent("Alpha");
+  });
+
+  // Duplicate labels used to collide because CommandItem's `value` (cmdk's
+  // identity/scoring key) was the LABEL, not the unique option value.
+  it("distinguishes options that share the same label", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={[
+          { label: "Production", value: "prod-us" },
+          { label: "Production", value: "prod-eu" },
+        ]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const options = await screen.findAllByRole("option", { name: "Production" });
+    expect(options).toHaveLength(2);
+    await userEvent.click(options[1]!);
+    expect(onValueChange).toHaveBeenCalledWith("prod-eu");
+  });
 });
 
 // #359 — allowCustomValue. A nested describe because these tests TYPE into the