@kinetixui/ui 0.23.3 → 0.24.0

package/src/components/table.tsx

@@ -3,12 +3,103 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
 
+/**
+ * How `TableCaption` and `Table` agree on the id that names the scroll container.
+ *
+ * `fallbackId` is a `useId` rather than a counter: stable across server and client render, and unique
+ * when several tables share a page. A caption given an explicit `id` by the caller keeps it.
+ *
+ * `register` is what keeps the two in step. The caption tells `Table` the id it actually ended up with,
+ * on mount, whenever that id changes, and again with `undefined` when it unmounts. The alternative —
+ * reading the caption's id out of the DOM while measuring — was wrong in a way review caught: a caller
+ * can change an `id` without changing any dimension (one derived from state, with the caption's text
+ * unchanged), no `ResizeObserver` callback fires, and the wrapper is left pointing `aria-labelledby` at
+ * an element that no longer exists. A dangling reference names nothing, so the focus stop goes
+ * unannounced. Registration follows the render that changed it, which is the thing that actually
+ * happened.
+ */
+type TableCaptionRegistration = {
+  fallbackId: string;
+  register: (id: string | undefined) => void;
+};
+
+const TableCaptionContext = React.createContext<TableCaptionRegistration | undefined>(undefined);
+
+/**
+ * True only while the scroll container can actually scroll horizontally.
+ *
+ * Deliberately conditional. `overflow-auto` makes this wrapper a scrollable region, and a scrollable
+ * region no keyboard can reach is unreachable without a pointer — WCAG 2.1.1, which axe reports as
+ * `scrollable-region-focusable`. But most tables fit, and an unconditional `tabIndex` would add a focus
+ * stop to every table in every consumer's app that lands on nothing to scroll. So the tab stop exists
+ * exactly when there is something to scroll.
+ *
+ * This mirrors the `useScrollable` hook the docs site already uses for its preview frames, down to the
+ * 1px tolerance; it is re-stated here rather than imported because `packages/ui` cannot depend on the
+ * site, and it is kept module-private rather than exported so this fix adds no public API.
+ *
+ * The 1px tolerance is not superstition: sub-pixel layout rounding makes `scrollWidth` exceed
+ * `clientWidth` by a fraction on tables that are not actually scrollable, and that fraction would
+ * otherwise mint a useless focus stop.
+ */
+function useHorizontalScrollState(ref: React.RefObject<HTMLElement | null>) {
+  const [scrollable, setScrollable] = React.useState(false);
+
+  React.useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const measure = () => setScrollable(el.scrollWidth > el.clientWidth + 1);
+
+    measure();
+    // ResizeObserver, not polling: the wrapper changes size when the viewport does, and the table changes
+    // size when its content or the reader's text size does. Observing both covers a responsive layout, new
+    // rows arriving, and a font-size change, none of which fire a resize event on the window.
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    if (el.firstElementChild) observer.observe(el.firstElementChild);
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return scrollable;
+}
+
 const Table = React.forwardRef<HTMLTableElement, React.HTMLAttributes<HTMLTableElement>>(
-  ({ className, ...props }, ref) => (
-    <div className="relative w-full overflow-auto">
-      <table ref={ref} className={cn("w-full caption-bottom text-sm font-sans", className)} {...props} />
-    </div>
-  ),
+  ({ className, ...props }, ref) => {
+    const wrapper = React.useRef<HTMLDivElement>(null);
+    const fallbackId = React.useId();
+    const [labelledBy, setLabelledBy] = React.useState<string>();
+    const scrollable = useHorizontalScrollState(wrapper);
+    // `setLabelledBy` is stable, so this is created once per table and never re-provides needlessly.
+    const caption = React.useMemo<TableCaptionRegistration>(
+      () => ({ fallbackId, register: setLabelledBy }),
+      [fallbackId],
+    );
+
+    return (
+      <div
+        ref={wrapper}
+        // The focus ring is the existing one — `ring-ring` resolves to the same token every other control
+        // in this library focuses with. Left on unconditionally: a div with no `tabIndex` never matches
+        // `:focus-visible`, so this costs nothing while keeping the class string stable across a resize.
+        className="relative w-full overflow-auto focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        {...(scrollable
+          ? {
+              tabIndex: 0,
+              // Named only when the table actually has a caption to be named by. `role="group"` rather than
+              // `region`, which is a landmark and would put one entry per table into the landmark list; and
+              // no fabricated fallback name, because "Scrollable table" on every table in the catalogue
+              // tells a screen-reader user nothing they could not already hear from the table itself.
+              ...(labelledBy ? { role: "group", "aria-labelledby": labelledBy } : {}),
+            }
+          : {})}
+      >
+        <TableCaptionContext.Provider value={caption}>
+          <table ref={ref} className={cn("w-full caption-bottom text-sm font-sans", className)} {...props} />
+        </TableCaptionContext.Provider>
+      </div>
+    );
+  },
 );
 Table.displayName = "Table";
 
@@ -61,9 +152,31 @@ const TableCell = React.forwardRef<HTMLTableCellElement, React.TdHTMLAttributes<
 TableCell.displayName = "TableCell";
 
 const TableCaption = React.forwardRef<HTMLTableCaptionElement, React.HTMLAttributes<HTMLTableCaptionElement>>(
-  ({ className, ...props }, ref) => (
-    <caption ref={ref} className={cn("mt-4 text-sm text-muted-foreground", className)} {...props} />
-  ),
+  ({ className, id, ...props }, ref) => {
+    // Falls back to the id `Table` generated, so the scroll container has something real to point
+    // `aria-labelledby` at. A caller-supplied `id` always wins, so nothing that already sets one changes.
+    const context = React.useContext(TableCaptionContext);
+    const effectiveId = id ?? context?.fallbackId;
+    const register = context?.register;
+
+    // Report the id upward after every render that changes it, and withdraw it on unmount so a table
+    // whose caption is removed stops claiming a name instead of pointing at a missing element. A
+    // `TableCaption` rendered outside a `Table` has nothing to register with and simply renders.
+    React.useEffect(() => {
+      if (!register) return;
+      register(effectiveId);
+      return () => register(undefined);
+    }, [register, effectiveId]);
+
+    return (
+      <caption
+        ref={ref}
+        id={effectiveId}
+        className={cn("mt-4 text-sm text-muted-foreground", className)}
+        {...props}
+      />
+    );
+  },
 );
 TableCaption.displayName = "TableCaption";
 

package/src/components/tabs.tsx

@@ -4,6 +4,26 @@ import * as React from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import { cn } from "../lib/utils";
 
+/**
+ * Tabs — one navigation group, following the navigation state contract (TOKENS.md, "Text entry and
+ * navigation") and the surface model:
+ *
+ *   list       an inset well, `--surface-grouped` — below a Card in both themes; at large text sizes the tabs
+ *              wrap inside it rather than running off the page
+ *   rest       unselected tabs in `--muted-foreground`
+ *   hover      an unselected tab gets the selection controls' `--foreground` state layer at 8% and
+ *              `--foreground` text
+ *   selected   a small raised surface on the well — `--card`, the Card's half-strength `--border` edge and
+ *              `sm` depth — and `--foreground` text, so it is surface + edge + depth, never colour alone. The
+ *              list used to be `--muted` with a `--background` tab, which in dark mode put the selected tab
+ *              BELOW its well (measured: tab L 0.0031, well L 0.0167) — the inversion SegmentedControl had
+ *   focus      the 2px `--ring`, `!important` so the selected tab's edge cannot cover it; the selected
+ *              surface stays under it
+ *   disabled   `--opacity-disabled`, inert
+ *
+ * There is no pressed state: Radix selects a tab on pointer-down, so pressing IS selecting.
+ * Motion: colour, background and box-shadow over `duration-fast` with `ease-standard`; nothing moves.
+ */
 const Tabs = TabsPrimitive.Root;
 
 const TabsList = React.forwardRef<
@@ -13,7 +33,10 @@ const TabsList = React.forwardRef<
   <TabsPrimitive.List
     ref={ref}
     className={cn(
-      "inline-flex h-9 items-center justify-center rounded-lg bg-muted p-1 text-muted-foreground font-sans",
+      // `min-h-9` and `flex-wrap`, not `h-9`: identical at the default text size, but at 200% text three
+      // tabs need 440px and a phone gives them 358 — the strip ran 82px off the page (large-text pass), and a
+      // fixed-height well would have clipped a second row. Now the tabs wrap inside the well and it grows.
+      "inline-flex min-h-9 max-w-full flex-wrap items-center justify-center rounded-lg bg-surface-grouped p-1 text-muted-foreground font-sans",
       className,
     )}
     {...props}
@@ -28,10 +51,12 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium transition-all",
-      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium",
+      "transition-[color,background-color,box-shadow] duration-fast ease-standard",
+      "[@media(hover:hover)]:enabled:hover:data-[state=inactive]:bg-foreground/[0.08] [@media(hover:hover)]:enabled:hover:data-[state=inactive]:text-foreground",
+      "data-[state=active]:bg-card data-[state=active]:text-foreground data-[state=active]:[box-shadow:inset_0_0_0_1px_hsl(var(--border)/0.5),var(--shadow-sm)]",
+      "focus-visible:outline-none focus-visible:!ring-2 focus-visible:ring-ring",
       "disabled:pointer-events-none disabled:opacity-disabled",
-      "data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow",
       className,
     )}
     {...props}

package/src/components/tag.tsx

@@ -56,7 +56,7 @@ const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
         type="button"
         onClick={onRemove}
         aria-label={name}
-        className="-mr-0.5 ml-0.5 rounded-[2px] opacity-muted outline-none transition-opacity hover:opacity-visible focus-visible:ring-1 focus-visible:ring-current"
+        className="-me-0.5 ms-0.5 rounded-[2px] opacity-muted outline-none transition-opacity hover:opacity-visible focus-visible:ring-1 focus-visible:ring-current"
       >
         <X className="size-3.5" />
       </button>

package/src/components/textarea.tsx

@@ -9,14 +9,31 @@ import { cn } from "../lib/utils";
  * 01. Form Inputs › Textarea (node 54855:13857).
  *
  * Identical to `Input` except the field is multi-line: `min-h-[100px]`
- * (Figma `h: 100`) and vertical resize. Same state matrix and tokens.
+ * (Figma `h: 100`) and vertical resize. Same state matrix and tokens as Input:
+ *
+ * It follows the text-entry state contract (TOKENS.md, "Text entry and navigation"):
+ *
+ *   rest       edge `--muted-foreground` at 80% — 3.4:1 light / 5.4:1 dark on a card, where `--input` was
+ *              2.2:1 / 2.4:1 and was the only thing marking where the field is (SC 1.4.11)
+ *   hover      a pointer that can hover: the edge steps to full `--muted-foreground`. Not on a focused,
+ *              invalid, read-only or disabled field — hover never takes over a stronger state
+ *   focus      `--action` edge + the `--shadow-focus` ring, the strongest signal, unchanged by the pointer
+ *   invalid    `aria-invalid="true"` → `--destructive` edge and ring, which hover does not replace; the
+ *              field's error text is the non-colour cue (SC 1.4.1)
+ *   read-only  an inset `--muted` fill, full-strength text, no hover: readable and selectable, not editable
+ *   disabled   `--opacity-disabled`, inert
+ *
+ * Motion: border-color, box-shadow and background-color over `duration-instant` with `ease-standard`.
+ * Reduced motion collapses it (the library floor) and lands on the same end state.
  */
 const textareaVariants = cva(
   [
-    "flex w-full min-h-[100px] resize-y rounded-sm border border-input bg-background px-3 py-3",
+    "flex w-full min-h-[100px] resize-y rounded-sm border border-muted-foreground/80 bg-background px-3 py-3",
     "font-sans text-body-md text-foreground",
     "placeholder:text-muted-foreground",
-    "outline-none transition-colors",
+    "outline-none transition-[border-color,box-shadow,background-color] duration-instant ease-standard",
+    "[@media(hover:hover)]:enabled:hover:[&:not(:focus):not([aria-invalid=true]):not([readonly]):not([data-state=focus])]:border-muted-foreground",
+    "[&[readonly]]:bg-muted",
     "focus-visible:border-action focus-visible:shadow-focus",
     "disabled:cursor-not-allowed disabled:opacity-disabled",
     "aria-[invalid=true]:border-destructive aria-[invalid=true]:focus-visible:border-destructive aria-[invalid=true]:focus-visible:shadow-focus-destructive",

package/src/components/tooltip.tsx

@@ -3,7 +3,9 @@
 import * as React from "react";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import { cn } from "../lib/utils";
+import { withDirectionalPortal } from "./direction-provider";
 
+const TooltipPortal = withDirectionalPortal(TooltipPrimitive.Portal);
 const TooltipProvider = TooltipPrimitive.Provider;
 const Tooltip = TooltipPrimitive.Root;
 const TooltipTrigger = TooltipPrimitive.Trigger;
@@ -12,19 +14,27 @@ const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
 >(({ className, sideOffset = 4, ...props }, ref) => (
-  <TooltipPrimitive.Portal>
+  <TooltipPortal>
     <TooltipPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
       className={cn(
-        "z-overlay overflow-hidden rounded-md bg-action px-3 py-1.5 text-xs text-action-foreground font-sans",
-        "animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+    // Capped to the room Radix reports it has, so large text cannot push the surface past the window —
+    // see the note in popover.tsx for the measurement that prompted it.
+        "z-overlay max-w-[var(--radix-popper-available-width)] overflow-hidden rounded-md bg-action px-3 py-1.5 text-xs text-action-foreground font-sans",
+        // Timing stays in the same string as the animation it times, so a reader (and the motion
+        // contract test) can see both at once.
+        "animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 duration-instant ease-enter data-[state=closed]:ease-exit",
+        // `data-side` is the side Radix RESOLVED the surface onto — it is already physical, having been
+        // flipped for direction and collisions before it reaches the DOM. The slide must therefore stay
+        // physical to travel away from the trigger; a logical class here would invert the animation under
+        // RTL and make the surface fly the wrong way. // rtl-ok
         "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className,
       )}
       {...props}
     />
-  </TooltipPrimitive.Portal>
+  </TooltipPortal>
 ));
 TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 

package/src/components/tour.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 import { createPortal } from "react-dom";
 import { Button } from "./button";
+import { useKinetixPortalContainer } from "./direction-provider";
 
 /**
  * Tour — sequenced spotlight popovers over real elements (onboarding
@@ -38,6 +39,13 @@ export interface TourProps {
 
 const SPOTLIGHT_PADDING = 8;
 
+/** `true` when the user asked for less motion. Safe on the server and anywhere `matchMedia` is absent. */
+function prefersReducedMotion(): boolean {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    : false;
+}
+
 const Tour: React.FC<TourProps> = ({
   steps,
   open,
@@ -50,6 +58,9 @@ const Tour: React.FC<TourProps> = ({
   doneLabel = "Done",
 }) => {
   const [mounted, setMounted] = React.useState(false);
+  // Portaled like every other overlay here: into the nearest direction provider's host, else <body>. `null`
+  // is a provider whose host is not attached yet: render nothing until it is.
+  const portalHost = useKinetixPortalContainer();
   const [rect, setRect] = React.useState<DOMRect | null>(null);
   const step = steps[stepIndex];
 
@@ -98,7 +109,11 @@ const Tour: React.FC<TourProps> = ({
       const el = document.querySelector(step.target);
       if (el) {
         setRect(el.getBoundingClientRect());
-        el.scrollIntoView({ behavior: "smooth", block: "center" });
+        // An explicit `behavior: "smooth"` overrides the CSS `scroll-behavior: auto` that the
+        // reduced-motion base layer sets, so the option has to be chosen rather than inherited:
+        // otherwise the one motion a reduced-motion user cannot look away from — the viewport
+        // itself travelling — is the one that still plays.
+        el.scrollIntoView({ behavior: prefersReducedMotion() ? "auto" : "smooth", block: "center" });
       } else {
         setRect(null);
       }
@@ -121,7 +136,7 @@ const Tour: React.FC<TourProps> = ({
     return () => document.removeEventListener("keydown", onKeyDown);
   }, [open, onOpenChange]);
 
-  if (!mounted || !open || !step) return null;
+  if (!mounted || !open || !step || portalHost === null) return null;
 
   const isFirst = stepIndex === 0;
   const isLast = stepIndex === steps.length - 1;
@@ -132,9 +147,9 @@ const Tour: React.FC<TourProps> = ({
         left: rect.left - SPOTLIGHT_PADDING,
         width: rect.width + SPOTLIGHT_PADDING * 2,
         height: rect.height + SPOTLIGHT_PADDING * 2,
-        boxShadow: "0 0 0 9999px rgb(0 0 0 / 0.6)",
+        boxShadow: "0 0 0 9999px hsl(var(--scrim))",
       }
-    : { inset: 0, background: "rgb(0 0 0 / 0.6)" };
+    : { inset: 0, background: "hsl(var(--scrim))" };
 
   const cardStyle: React.CSSProperties = rect
     ? {
@@ -147,7 +162,7 @@ const Tour: React.FC<TourProps> = ({
     <>
       <div
         aria-hidden
-        className="pointer-events-none fixed z-overlay rounded-lg transition-all duration-fast"
+        className="pointer-events-none fixed z-overlay rounded-lg transition-[top,left,width,height,opacity] duration-fast ease-standard"
         style={spotlightStyle}
       />
       <div
@@ -157,7 +172,7 @@ const Tour: React.FC<TourProps> = ({
         aria-labelledby={titleId}
         tabIndex={-1}
         onKeyDown={trapTab}
-        className="fixed z-overlay w-80 rounded-lg border border-border bg-popover p-4 font-sans text-popover-foreground shadow-lg outline-none transition-all duration-fast"
+        className="fixed z-overlay w-80 rounded-lg border border-border bg-popover p-4 font-sans text-popover-foreground shadow-lg outline-none transition-[top,left,opacity] duration-fast ease-standard"
         style={cardStyle}
       >
         <p id={titleId} className="text-title-sm font-medium text-foreground">
@@ -192,7 +207,7 @@ const Tour: React.FC<TourProps> = ({
         </div>
       </div>
     </>,
-    document.body,
+    portalHost ?? document.body,
   );
 };
 

package/src/components/tree-view.tsx

@@ -262,7 +262,7 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
         >
           {hasChildren ? (
             <ChevronRight
-              className={cn("size-4 shrink-0 text-muted-foreground transition-transform", expanded && "rotate-90")}
+              className={cn("size-4 shrink-0 text-muted-foreground transition-transform", expanded ? "rotate-90" : "rtl:-scale-x-100")}
               onClick={(e) => {
                 e.stopPropagation();
                 ctx.toggleExpanded(value);

package/src/components-behavior.test.tsx

@@ -12,6 +12,7 @@ import {
   AccordionItem,
   AccordionTrigger,
 } from "./components/accordion";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./components/collapsible";
 
 // kx-verify: interaction
 
@@ -137,3 +138,76 @@ describe("Accordion", () => {
     expect(screen.getByText("Answer text")).toBeVisible();
   });
 });
+
+/**
+ * Collapsible's disclosure contract.
+ *
+ * These assert the behaviour and the structural prerequisites for the transition — that the content
+ * is clipped while its height animates, and that it carries the state attribute the animation is
+ * selected on. They deliberately do NOT assert that it moved: jsdom has no layout and no compositor,
+ * so a test here cannot tell a 200ms height animation from an instant one. That claim is made by
+ * `scripts/motion.mjs`, in a browser, by reading a rendered midpoint.
+ *
+ * The split matters because the component shipped with no tests at all and no motion, and a test
+ * asserting a class name would have gone on passing if the keyframes were deleted.
+ */
+describe("Collapsible", () => {
+  const Example = () => (
+    <Collapsible>
+      <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+      <CollapsibleContent>Hidden detail</CollapsibleContent>
+    </Collapsible>
+  );
+
+  it("reveals and hides its content from the trigger", async () => {
+    render(<Example />);
+    expect(screen.queryByText("Hidden detail")).not.toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: "Toggle" }));
+    expect(screen.getByText("Hidden detail")).toBeVisible();
+    await userEvent.click(screen.getByRole("button", { name: "Toggle" }));
+    expect(screen.queryByText("Hidden detail")).not.toBeInTheDocument();
+  });
+
+  it("opens from the keyboard, because the trigger is a real button", async () => {
+    render(<Example />);
+    await userEvent.tab();
+    expect(screen.getByRole("button", { name: "Toggle" })).toHaveFocus();
+    await userEvent.keyboard("{Enter}");
+    expect(screen.getByText("Hidden detail")).toBeVisible();
+    await userEvent.keyboard(" ");
+    expect(screen.queryByText("Hidden detail")).not.toBeInTheDocument();
+  });
+
+  it("clips its content while the height animates", async () => {
+    render(<Example />);
+    await userEvent.click(screen.getByRole("button", { name: "Toggle" }));
+    // Without overflow-hidden the text is laid out at full height from the first frame and spills
+    // out of the box the animation is still collapsing.
+    //
+    // `getByText` returns the content element itself: unlike AccordionContent, this component wraps
+    // its children in nothing, so the animated element and the text's element are the same node.
+    expect(screen.getByText("Hidden detail")).toHaveClass("overflow-hidden");
+  });
+
+  it("carries the state attribute the disclosure animation is selected on", async () => {
+    render(<Example />);
+    const trigger = screen.getByRole("button", { name: "Toggle" });
+    await userEvent.click(trigger);
+    const content = screen.getByText("Hidden detail");
+    expect(content).toHaveAttribute("data-state", "open");
+    expect(content?.className).toContain("data-[state=open]:animate-collapsible-down");
+    expect(content?.className).toContain("data-[state=closed]:animate-collapsible-up");
+  });
+
+  it("merges a caller's className instead of dropping it", async () => {
+    render(
+      <Collapsible defaultOpen>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent className="mt-4">Hidden detail</CollapsibleContent>
+      </Collapsible>,
+    );
+    const content = screen.getByText("Hidden detail");
+    expect(content).toHaveClass("mt-4");
+    expect(content).toHaveClass("overflow-hidden");
+  });
+});