@zentauri-ui/zentauri-components 1.8.0 → 1.8.2

package/src/ui/marquee/marquee.test.tsx

@@ -1,9 +1,13 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { Marquee } from "./marquee";
 
 describe("Marquee", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it("exposes a display name", () => {
     expect(Marquee.displayName).toBe("Marquee");
   });
@@ -17,13 +21,14 @@ describe("Marquee", () => {
 
     expect(document.querySelector('[data-slot="marquee"]')).toBeTruthy();
     expect(document.querySelector('[data-slot="marquee-track"]')).toBeTruthy();
-    expect(screen.getAllByText("Acme")).toHaveLength(2);
-
     const groups = document.querySelectorAll(
       '[data-slot="marquee-item-group"]',
     );
+    expect(groups).toHaveLength(2);
+    expect(groups[0]?.textContent).toContain("Acme");
     expect(groups[1]).toHaveAttribute("aria-hidden", "true");
     expect(groups[1]).toHaveAttribute("inert");
+    expect(groups[1]?.textContent).toContain("Acme");
   });
 
   it("applies horizontal metadata by default", () => {
@@ -84,6 +89,42 @@ describe("Marquee", () => {
     });
   });
 
+  it("hides filler copies from assistive technology", async () => {
+    vi.spyOn(HTMLElement.prototype, "offsetWidth", "get").mockImplementation(
+      function (this: HTMLElement) {
+        return this.getAttribute("data-slot") === "marquee" ? 300 : 0;
+      },
+    );
+    vi.spyOn(HTMLElement.prototype, "scrollWidth", "get").mockImplementation(
+      function (this: HTMLElement) {
+        return this.getAttribute("data-slot") === "marquee-measure" ? 100 : 0;
+      },
+    );
+
+    render(
+      <Marquee>
+        <button type="button">Focusable item</button>
+      </Marquee>,
+    );
+
+    const firstGroup = document.querySelector(
+      '[data-slot="marquee-item-group"]',
+    );
+
+    await waitFor(() => {
+      expect(firstGroup?.textContent).toBe(
+        "Focusable itemFocusable itemFocusable item",
+      );
+    });
+
+    expect(
+      screen.getAllByRole("button", { name: "Focusable item" }),
+    ).toHaveLength(1);
+    expect(
+      firstGroup?.querySelectorAll('[aria-hidden="true"][inert]'),
+    ).toHaveLength(2);
+  });
+
   it("accepts string gap values", () => {
     render(
       <Marquee gap="2rem" data-testid="marquee">

package/src/ui/marquee/marquee.tsx

@@ -1,7 +1,9 @@
 "use client";
 
-import type { CSSProperties } from "react";
+import { Children, useCallback, useMemo, useRef, useState } from "react";
+import type { CSSProperties, Ref } from "react";
 
+import { useIsomorphicLayoutEffect } from "../../hooks/useIsomorphicLayoutEffect";
 import { cn } from "../../lib/utils";
 
 import type { MarqueeProps } from "./types";
@@ -16,6 +18,17 @@ function toCssLength(value: number | string | undefined) {
   return typeof value === "number" ? `${value}px` : value;
 }
 
+function assignRef<TElement>(
+  ref: Ref<TElement> | undefined,
+  value: TElement | null,
+) {
+  if (typeof ref === "function") {
+    ref(value);
+  } else if (ref) {
+    (ref as { current: TElement | null }).current = value;
+  }
+}
+
 export function Marquee(props: MarqueeProps) {
   const {
     appearance,
@@ -44,14 +57,81 @@ export function Marquee(props: MarqueeProps) {
     resolvedDirection === "right" || resolvedDirection === "down";
   const animationName =
     resolvedOrientation === "vertical" ? "zui-marquee-y" : "zui-marquee-x";
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const measureRef = useRef<HTMLDivElement | null>(null);
+  const [copyCount, setCopyCount] = useState(1);
+  const childArray = useMemo(() => Children.toArray(children), [children]);
+  const setRootRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      rootRef.current = node;
+      assignRef(ref, node);
+    },
+    [ref],
+  );
   const marqueeStyle = {
     ...(gap !== undefined ? { "--zui-marquee-gap": toCssLength(gap) } : null),
     ...style,
   } as CSSProperties;
+  const groupClassName = cn(
+    "flex shrink-0 items-center justify-around gap-(--zui-marquee-gap)",
+    resolvedOrientation === "vertical" ? "flex-col" : "flex-row",
+    itemClassName,
+  );
+  const fillerChildren = Array.from(
+    { length: Math.max(0, copyCount - 1) },
+    (_, index) => (
+      <div key={index} aria-hidden="true" inert className="contents">
+        {childArray}
+      </div>
+    ),
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    const updateCopyCount = () => {
+      const root = rootRef.current;
+      const measure = measureRef.current;
+
+      if (!root || !measure) {
+        return;
+      }
+
+      const rootSize =
+        resolvedOrientation === "vertical"
+          ? root.offsetHeight
+          : root.offsetWidth;
+      const contentSize =
+        resolvedOrientation === "vertical"
+          ? measure.scrollHeight
+          : measure.scrollWidth;
+
+      if (!rootSize || !contentSize) {
+        setCopyCount(1);
+        return;
+      }
+
+      setCopyCount(Math.max(1, Math.ceil(rootSize / contentSize)));
+    };
+
+    updateCopyCount();
+
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+
+    const observer = new ResizeObserver(updateCopyCount);
+    if (rootRef.current) {
+      observer.observe(rootRef.current);
+    }
+    if (measureRef.current) {
+      observer.observe(measureRef.current);
+    }
+
+    return () => observer.disconnect();
+  }, [childArray, gap, resolvedOrientation]);
 
   return (
     <div
-      ref={ref}
+      ref={setRootRef}
       data-direction={resolvedDirection}
       data-orientation={resolvedOrientation}
       data-slot="marquee"
@@ -68,10 +148,21 @@ export function Marquee(props: MarqueeProps) {
       {...rest}
     >
       <style>{marqueeKeyframes}</style>
+      <div
+        aria-hidden="true"
+        data-slot="marquee-measure"
+        ref={measureRef}
+        className={cn(
+          "pointer-events-none invisible absolute -z-10",
+          groupClassName,
+        )}
+      >
+        {childArray}
+      </div>
       <div
         data-slot="marquee-track"
         className={cn(
-          "flex shrink-0 gap-[var(--zui-marquee-gap)] will-change-transform [animation-iteration-count:infinite] [animation-timing-function:linear] motion-reduce:[animation-play-state:paused]",
+          "flex shrink-0 gap-(--zui-marquee-gap) will-change-transform [animation-iteration-count:infinite] [animation-timing-function:linear] motion-reduce:[animation-play-state:paused]",
           resolvedOrientation === "vertical" ? "flex-col" : "w-max flex-row",
           pauseOnHover && "group-hover/marquee:[animation-play-state:paused]",
           isReverse && "[animation-direction:reverse]",
@@ -84,27 +175,18 @@ export function Marquee(props: MarqueeProps) {
           } as CSSProperties
         }
       >
-        <div
-          data-slot="marquee-item-group"
-          className={cn(
-            "flex shrink-0 items-center justify-around gap-[var(--zui-marquee-gap)]",
-            resolvedOrientation === "vertical" ? "flex-col" : "flex-row",
-            itemClassName,
-          )}
-        >
-          {children}
+        <div data-slot="marquee-item-group" className={groupClassName}>
+          {childArray}
+          {fillerChildren}
         </div>
         <div
           aria-hidden="true"
           inert
           data-slot="marquee-item-group"
-          className={cn(
-            "flex shrink-0 items-center justify-around gap-[var(--zui-marquee-gap)]",
-            resolvedOrientation === "vertical" ? "flex-col" : "flex-row",
-            itemClassName,
-          )}
+          className={groupClassName}
         >
-          {children}
+          {childArray}
+          {fillerChildren}
         </div>
       </div>
     </div>

package/src/ui/skeleton/skeleton.test.tsx

@@ -0,0 +1,85 @@
+import { createRef } from "react";
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonButton,
+  SkeletonCard,
+  SkeletonText,
+} from "./skeleton";
+
+describe("Skeleton", () => {
+  it("should set displayName on skeleton primitives", () => {
+    expect(Skeleton.displayName).toBe("Skeleton");
+    expect(SkeletonText.displayName).toBe("SkeletonText");
+    expect(SkeletonAvatar.displayName).toBe("SkeletonAvatar");
+    expect(SkeletonCard.displayName).toBe("SkeletonCard");
+    expect(SkeletonButton.displayName).toBe("SkeletonButton");
+  });
+
+  it("should stamp data-slot and hide the placeholder from assistive tech", () => {
+    const { container } = render(<Skeleton busy />);
+    const root = container.querySelector('[data-slot="skeleton"]');
+    expect(root).toHaveAttribute("aria-hidden", "true");
+    expect(root).toHaveAttribute("aria-busy", "true");
+  });
+
+  it("should apply pulse motion when animation is not none", () => {
+    const { container } = render(<Skeleton animation="pulse" />);
+    expect(
+      container.querySelector('[data-slot="skeleton"]')?.className,
+    ).toMatch(/animate-pulse/);
+  });
+
+  it("should omit motion classes when animation is none", () => {
+    const { container } = render(<Skeleton animation="none" />);
+    expect(
+      container.querySelector('[data-slot="skeleton"]')?.className,
+    ).not.toMatch(/animate-pulse/);
+  });
+
+  it("should render the requested number of text lines", () => {
+    const { container } = render(<SkeletonText lines={4} />);
+    const root = container.querySelector('[data-slot="skeleton-text"]');
+    expect(root).toHaveAttribute("aria-hidden", "true");
+    expect(root?.children.length).toBe(4);
+    expect(root?.lastElementChild?.className).toMatch(/w-3\/5/);
+  });
+
+  it("should share parent animation with nested text placeholders", () => {
+    const { container } = render(
+      <Skeleton animation="none">
+        <SkeletonText lines={2} />
+      </Skeleton>,
+    );
+    const text = container.querySelector('[data-slot="skeleton-text"]');
+    expect(text?.firstElementChild?.className).not.toMatch(/animate-pulse/);
+  });
+
+  it("should render avatar, button, and card slots", () => {
+    const { container } = render(
+      <>
+        <SkeletonAvatar avatarSize="xl" />
+        <SkeletonButton buttonSize="lg" />
+        <SkeletonCard />
+      </>,
+    );
+
+    expect(
+      container.querySelector('[data-slot="skeleton-avatar"]'),
+    ).toHaveClass("size-14");
+    expect(
+      container.querySelector('[data-slot="skeleton-button"]'),
+    ).toHaveClass("h-12");
+    expect(container.querySelector('[data-slot="skeleton-card"]')).toBeTruthy();
+  });
+
+  it("should forward refs to the base skeleton element", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<Skeleton ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("skeleton");
+  });
+});

package/src/ui/table/index.ts

@@ -18,5 +18,8 @@ export type {
   TableHeadCellProps,
   TableProps,
   TableSectionProps,
+  TableSortChangeHandler,
+  TableSortDirection,
+  TableSortState,
 } from "./types";
 export { tableVariants, tableRowVariants, tableCellVariants } from "./variants";

package/src/ui/table/table-base.tsx

@@ -1,6 +1,12 @@
 "use client";
 
-import { createContext, useContext, useMemo } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  type KeyboardEvent,
+} from "react";
 
 import { cn } from "../../lib/utils";
 
@@ -10,6 +16,7 @@ import type {
   TableHeadCellProps,
   TableProps,
   TableSectionProps,
+  TableSortDirection,
 } from "./types";
 import { tableCellVariants, tableRowVariants, tableVariants } from "./variants";
 
@@ -122,19 +129,20 @@ export function TableRow({
   children,
   ref,
   as: Wrapper = "tr",
+  rowAnimation: _rowAnimation,
   ...rest
 }: TableSectionProps & { ref?: React.Ref<HTMLTableRowElement> }) {
   const { appearance } = useTableContext("TableRow");
 
   return (
-    <tr
+    <Wrapper
       ref={ref}
       data-slot="table-row"
       className={cn(tableRowVariants({ appearance }), className)}
       {...rest}
     >
       {children}
-    </tr>
+    </Wrapper>
   );
 }
 
@@ -144,21 +152,78 @@ export function TableHead({
   className,
   children,
   scope = "col",
+  sortKey,
   sortDirection,
+  onSortChange,
+  onClick,
+  onKeyDown,
+  tabIndex,
   ref,
   ...rest
 }: TableHeadCellProps) {
   const { appearance, size, textAlign } = useTableContext("TableHead");
+  const isSortable = Boolean(sortKey && onSortChange);
+  const sortableDirection: TableSortDirection = sortDirection ?? "none";
+
+  const handleSort = useCallback(() => {
+    if (!sortKey || !onSortChange) {
+      return;
+    }
+
+    const nextDirection: TableSortDirection =
+      sortableDirection === "ascending"
+        ? "descending"
+        : sortableDirection === "descending"
+          ? "none"
+          : "ascending";
+
+    onSortChange({
+      sortKey,
+      sortDirection: nextDirection,
+    });
+  }, [onSortChange, sortKey, sortableDirection]);
+
+  const handleClick = useCallback<NonNullable<TableHeadCellProps["onClick"]>>(
+    (event) => {
+      onClick?.(event);
+      if (!event.defaultPrevented) {
+        handleSort();
+      }
+    },
+    [handleSort, onClick],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTableCellElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented || !isSortable) {
+        return;
+      }
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        handleSort();
+      }
+    },
+    [handleSort, isSortable, onKeyDown],
+  );
+
   return (
     <th
       ref={ref}
       data-slot="table-head"
       scope={scope}
-      aria-sort={sortDirection}
+      aria-sort={isSortable ? sortableDirection : sortDirection}
+      data-sort-key={sortKey}
+      data-sort-direction={sortDirection}
+      tabIndex={isSortable ? (tabIndex ?? 0) : tabIndex}
       className={cn(
         tableCellVariants({ appearance, size, textAlign }),
+        isSortable &&
+          "cursor-pointer select-none outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-950",
         className,
       )}
+      onClick={isSortable ? handleClick : onClick}
+      onKeyDown={isSortable ? handleKeyDown : onKeyDown}
       {...rest}
     >
       {children}

package/src/ui/table/table.test.tsx

@@ -0,0 +1,207 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Table } from "./table";
+import {
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "./table-base";
+
+function renderBasicTable() {
+  return render(
+    <Table>
+      <TableCaption>Quarterly revenue</TableCaption>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Company</TableHead>
+          <TableHead>ARR</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow>
+          <TableCell scope="row">Zentauri</TableCell>
+          <TableCell>$42k</TableCell>
+        </TableRow>
+      </TableBody>
+      <TableFooter>
+        <TableRow>
+          <TableCell>Total</TableCell>
+          <TableCell>$42k</TableCell>
+        </TableRow>
+      </TableFooter>
+    </Table>,
+  );
+}
+
+describe("Table", () => {
+  it("should set displayName on compound parts", () => {
+    expect(Table.displayName).toBe("Table");
+    expect(TableHeader.displayName).toBe("TableHeader");
+    expect(TableBody.displayName).toBe("TableBody");
+    expect(TableFooter.displayName).toBe("TableFooter");
+    expect(TableRow.displayName).toBe("TableRow");
+    expect(TableHead.displayName).toBe("TableHead");
+    expect(TableCell.displayName).toBe("TableCell");
+    expect(TableCaption.displayName).toBe("TableCaption");
+  });
+
+  it("should render semantic table structure inside a focusable scroll region", () => {
+    const { container } = renderBasicTable();
+    expect(
+      screen.getByRole("region", { name: "Scrollable table" }),
+    ).toHaveAttribute("data-slot", "table-scroll");
+    expect(screen.getByRole("table")).toHaveAttribute("data-slot", "table");
+    expect(
+      container.querySelector('[data-slot="table-caption"]'),
+    ).toHaveTextContent("Quarterly revenue");
+  });
+
+  it("should support a custom scroll region label", () => {
+    render(<Table scrollAreaAriaLabel="Usage table" />);
+    expect(screen.getByRole("region", { name: "Usage table" })).toBeVisible();
+  });
+
+  it("should apply sticky header classes when stickyHeader is enabled", () => {
+    const { container } = render(
+      <Table stickyHeader>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Name</TableHead>
+          </TableRow>
+        </TableHeader>
+      </Table>,
+    );
+    expect(
+      container.querySelector('[data-slot="table-header"]')?.className,
+    ).toMatch(/sticky/);
+    expect(container.querySelector('[data-slot="table"]')?.className).toMatch(
+      /table-auto/,
+    );
+  });
+
+  it("should expose sort state on sortable header cells", () => {
+    render(
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead sortKey="name" sortDirection="ascending">
+              Name
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+      </Table>,
+    );
+    const header = screen.getByRole("columnheader", { name: "Name" });
+    expect(header).toHaveAttribute("aria-sort", "ascending");
+    expect(header).toHaveAttribute("data-sort-key", "name");
+    expect(header).toHaveAttribute("data-sort-direction", "ascending");
+  });
+
+  it("should mark sortable unsorted header cells with aria-sort none", () => {
+    render(
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead sortKey="name" onSortChange={vi.fn()}>
+              Name
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+      </Table>,
+    );
+    expect(screen.getByRole("columnheader", { name: "Name" })).toHaveAttribute(
+      "aria-sort",
+      "none",
+    );
+  });
+
+  it("should call onSortChange with the next direction on click", async () => {
+    const user = userEvent.setup();
+    const handleSortChange = vi.fn();
+    render(
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead
+              sortKey="name"
+              sortDirection="ascending"
+              onSortChange={handleSortChange}
+            >
+              Name
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+      </Table>,
+    );
+
+    await user.click(screen.getByRole("columnheader", { name: "Name" }));
+    expect(handleSortChange).toHaveBeenCalledWith({
+      sortKey: "name",
+      sortDirection: "descending",
+    });
+  });
+
+  it("should support keyboard sorting", async () => {
+    const user = userEvent.setup();
+    const handleSortChange = vi.fn();
+    render(
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead
+              sortKey="createdAt"
+              sortDirection="none"
+              onSortChange={handleSortChange}
+            >
+              Created
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+      </Table>,
+    );
+
+    screen.getByRole("columnheader", { name: "Created" }).focus();
+    await user.keyboard("{Enter}");
+    expect(handleSortChange).toHaveBeenCalledWith({
+      sortKey: "createdAt",
+      sortDirection: "ascending",
+    });
+  });
+
+  it("should render scoped body cells as row headers", () => {
+    renderBasicTable();
+    expect(screen.getByRole("rowheader", { name: "Zentauri" })).toHaveAttribute(
+      "data-slot",
+      "table-cell",
+    );
+  });
+
+  it("should not leak rowAnimation onto the rendered row", () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow rowAnimation="hover">
+            <TableCell>Animated elsewhere</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    expect(
+      container.querySelector('[data-slot="table-row"]'),
+    ).not.toHaveAttribute("rowAnimation");
+  });
+
+  it("should forward refs to the table element", () => {
+    const ref = createRef<HTMLTableElement>();
+    render(<Table ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLTableElement);
+    expect(ref.current?.getAttribute("data-slot")).toBe("table");
+  });
+});

package/src/ui/table/types.ts

@@ -11,6 +11,16 @@ import type {
 import type { tableVariants } from "./variants";
 
 export type TableAnimation = "none" | "hover";
+export type TableSortDirection = "ascending" | "descending" | "none";
+
+export type TableSortState<TKey extends string = string> = {
+  sortKey?: TKey;
+  sortDirection: TableSortDirection;
+};
+
+export type TableSortChangeHandler<TKey extends string = string> = (
+  nextSort: TableSortState<TKey>,
+) => void;
 
 type TableVariantProps = VariantProps<typeof tableVariants>;
 
@@ -31,7 +41,9 @@ export type TableSectionProps = {
 };
 
 export type TableHeadCellProps = ThHTMLAttributes<HTMLTableCellElement> & {
-  sortDirection?: "ascending" | "descending" | "none";
+  sortKey?: string;
+  sortDirection?: TableSortDirection;
+  onSortChange?: TableSortChangeHandler;
   ref?: Ref<HTMLTableCellElement>;
 };