@zentauri-ui/zentauri-components 1.4.51 → 1.4.62

package/src/ui/select/select.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useState, useEffect, useCallback, useRef, useId } from "react";
 import {
   SelectProps,
   SelectOption,
@@ -32,6 +32,7 @@ export const Select = ({
   onChange,
   multiple = true,
 }: SelectProps) => {
+  const listboxId = `${useId()}-listbox`;
   const [internal, setInternal] = useState<string[]>(defaultValue);
   const [open, setOpen] = useState(false);
   const [options, setOptions] = useState<SelectOption[]>([]);
@@ -97,6 +98,7 @@ export const Select = ({
         registerOption,
         options,
         multiple,
+        listboxId,
       }}
     >
       <div ref={rootRef} className="relative w-full">
@@ -110,16 +112,25 @@ export const SelectTrigger = ({
   className,
   variant,
   size,
+  onClick,
   ...props
 }: SelectTriggerProps) => {
-  const { open, setOpen } = useSelect();
+  const { open, setOpen, listboxId } = useSelect();
 
   return (
     <button
       type="button"
-      onClick={() => setOpen(!open)}
+      aria-expanded={open}
+      aria-haspopup="listbox"
+      aria-controls={listboxId}
       className={cn(selectTriggerVariants({ variant, size }), className)}
       {...props}
+      onClick={(event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) {
+          setOpen(!open);
+        }
+      }}
     />
   );
 };
@@ -161,12 +172,85 @@ export const SelectContent = ({
   spacing = "default",
   ...props
 }: SelectContentProps) => {
-  const { open } = useSelect();
+  const { open, listboxId, multiple } = useSelect();
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+    const opts = Array.from(
+      panel.querySelectorAll<HTMLElement>('[role="option"]'),
+    ).filter((el) => el.getAttribute("aria-disabled") !== "true");
+    requestAnimationFrame(() => opts[0]?.focus());
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const panel = panelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    const enabledOptions = () =>
+      Array.from(panel.querySelectorAll<HTMLElement>('[role="option"]')).filter(
+        (el) => el.getAttribute("aria-disabled") !== "true",
+      );
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const options = enabledOptions();
+      if (options.length === 0) {
+        return;
+      }
+
+      const idx = options.findIndex((el) => el === document.activeElement);
+
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        const next = idx < 0 ? 0 : Math.min(idx + 1, options.length - 1);
+        options[next]?.focus();
+        return;
+      }
+
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        const prev =
+          idx <= 0 ? options.length - 1 : Math.max(idx - 1, 0);
+        options[prev]?.focus();
+        return;
+      }
+
+      if (event.key === "Home") {
+        event.preventDefault();
+        options[0]?.focus();
+        return;
+      }
+
+      if (event.key === "End") {
+        event.preventDefault();
+        options[options.length - 1]?.focus();
+      }
+    };
+
+    panel.addEventListener("keydown", handleKeyDown);
+    return () => panel.removeEventListener("keydown", handleKeyDown);
+  }, [open]);
 
   if (!open) return null;
 
   return (
     <div
+      ref={panelRef}
+      id={listboxId}
+      role="listbox"
+      aria-multiselectable={multiple}
+      tabIndex={-1}
       className={cn(
         selectContentVariants({ appearance, size, spacing }),
         className,
@@ -198,10 +282,17 @@ export const SelectItem = ({
     <div
       role="option"
       aria-selected={isActive}
-      tabIndex={0}
+      aria-disabled={disabled ? true : undefined}
+      tabIndex={-1}
       onClick={() => !disabled && toggleValue(value)}
       onKeyDown={(e) => {
-        if (e.key === "Enter") toggleValue(value);
+        if (disabled) {
+          return;
+        }
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          toggleValue(value);
+        }
       }}
       data-selected={isActive ? "true" : "false"}
       className={cn(

package/src/ui/select/types.ts

@@ -40,6 +40,7 @@ export type SelectContextType = {
   registerOption: (option: SelectOption) => void;
   options: SelectOption[];
   multiple: boolean;
+  listboxId: string;
 };
 
 export type SelectProps = {

package/src/ui/select/variants.ts

@@ -1,7 +1,7 @@
 import { cva } from "class-variance-authority";
 
 export const selectTriggerVariants = cva(
-  "flex items-center justify-between rounded-md border transition-all focus:outline-none",
+  "flex items-center justify-between rounded-md border transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-400 focus-visible:ring-offset-2",
   {
     variants: {
       variant: {
@@ -50,8 +50,10 @@ export const selectTriggerVariants = cva(
   },
 );
 
-export const selectItemVariants = cva("cursor-pointer px-3 py-2 rounded-md", {
-  variants: {
+export const selectItemVariants = cva(
+  "cursor-pointer px-3 py-2 rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-400 focus-visible:ring-inset",
+  {
+    variants: {
     appearance: {
       default:
         "bg-white text-gray-900 data-[selected=true]:bg-gray-200 data-[selected=true]:text-gray-900",

package/src/ui/slider/slider.test.tsx

@@ -41,7 +41,9 @@ describe("Slider", () => {
         </SliderTrack>
       </Slider>,
     );
-    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "25");
+    const thumb = screen.getByRole("slider");
+    expect(thumb).toHaveAttribute("aria-valuenow", "25");
+    expect(thumb).toHaveAttribute("aria-label", "Level");
   });
 
   it("should adjust value with keyboard", async () => {
@@ -91,4 +93,26 @@ describe("RangeSlider", () => {
     );
     expect(screen.getAllByRole("slider")).toHaveLength(2);
   });
+
+  it("should give each thumb an accessible name when aria-label is set", () => {
+    render(<RangeSlider defaultValue={[10, 90]} aria-label="Budget" />);
+    const thumbs = screen.getAllByRole("slider");
+    expect(thumbs[0]).toHaveAttribute("aria-label", "Budget, minimum");
+    expect(thumbs[1]).toHaveAttribute("aria-label", "Budget, maximum");
+  });
+
+  it("should mirror aria-labelledby onto thumbs when aria-label is omitted", () => {
+    render(
+      <>
+        <span id="range-lbl">Volume band</span>
+        <RangeSlider
+          defaultValue={[10, 90]}
+          aria-labelledby="range-lbl"
+        />
+      </>,
+    );
+    const thumbs = screen.getAllByRole("slider");
+    expect(thumbs[0]).toHaveAttribute("aria-labelledby", "range-lbl");
+    expect(thumbs[1]).toHaveAttribute("aria-labelledby", "range-lbl");
+  });
 });

package/src/ui/slider/slider.tsx

@@ -208,8 +208,21 @@ export function Slider({
       size: size ?? "md",
       appearance: appearance ?? "default",
       trackRef,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
     }),
-    [appearance, disabled, max, min, setValue, size, step, value],
+    [
+      appearance,
+      ariaLabel,
+      ariaLabelledBy,
+      disabled,
+      max,
+      min,
+      setValue,
+      size,
+      step,
+      value,
+    ],
   );
 
   return (
@@ -303,8 +316,18 @@ export function SliderThumb({
   ref: refProp,
   ...rest
 }: SliderThumbProps & { ref?: Ref<HTMLDivElement> }) {
-  const { min, max, value, step, setValue, disabled, size, trackRef } =
-    useSliderContext("SliderThumb");
+  const {
+    min,
+    max,
+    value,
+    step,
+    setValue,
+    disabled,
+    size,
+    trackRef,
+    "aria-label": sliderAriaLabel,
+    "aria-labelledby": sliderAriaLabelledBy,
+  } = useSliderContext("SliderThumb");
   /** Horizontal thumb position; same mapping as `SliderRange` width uses. */
   const pct = max === min ? 0 : ((value - min) / (max - min)) * 100;
 
@@ -414,6 +437,8 @@ export function SliderThumb({
       role="slider"
       tabIndex={disabled ? -1 : 0}
       data-slot="slider-thumb"
+      aria-label={sliderAriaLabel}
+      aria-labelledby={sliderAriaLabelledBy}
       aria-valuemin={min}
       aria-valuemax={max}
       aria-valuenow={value}
@@ -561,6 +586,13 @@ export function RangeSlider({
 
   const resolvedSize = size ?? "md";
 
+  const lowThumbAriaLabel =
+    ariaLabel !== undefined ? `${ariaLabel}, minimum` : undefined;
+  const highThumbAriaLabel =
+    ariaLabel !== undefined ? `${ariaLabel}, maximum` : undefined;
+  const thumbAriaLabelledBy =
+    ariaLabel === undefined ? ariaLabelledBy : undefined;
+
   return (
     <div
       ref={ref}
@@ -568,7 +600,6 @@ export function RangeSlider({
       role="group"
       aria-label={ariaLabel}
       aria-labelledby={ariaLabelledBy}
-      aria-valuetext={`${lo} – ${hi}`}
       className={cn(sliderRootVariants({ size: resolvedSize }), className)}
       {...rest}
     >
@@ -596,6 +627,8 @@ export function RangeSlider({
           trackRef={trackRef}
           onMoveClientX={(x) => moveThumb(0, x)}
           onNudge={(delta) => setPair([lo + delta, hi])}
+          aria-label={lowThumbAriaLabel}
+          aria-labelledby={thumbAriaLabelledBy}
         />
         <RangeThumb
           disabled={disabled}
@@ -608,6 +641,8 @@ export function RangeSlider({
           trackRef={trackRef}
           onMoveClientX={(x) => moveThumb(1, x)}
           onNudge={(delta) => setPair([lo, hi + delta])}
+          aria-label={highThumbAriaLabel}
+          aria-labelledby={thumbAriaLabelledBy}
         />
       </div>
     </div>
@@ -629,6 +664,8 @@ type RangeThumbProps = {
   onMoveClientX: (clientX: number) => void;
   /** Relative keyboard adjustment in value units; parent merges into the pair. */
   onNudge: (delta: number) => void;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
 };
 
 /** Private thumb implementation shared by the low and high endpoints. */
@@ -643,6 +680,8 @@ function RangeThumb({
   trackRef,
   onMoveClientX,
   onNudge,
+  "aria-label": thumbAriaLabel,
+  "aria-labelledby": thumbAriaLabelledBy,
 }: RangeThumbProps) {
   const onPointerDown = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>) => {
@@ -712,6 +751,8 @@ function RangeThumb({
       role="slider"
       tabIndex={disabled ? -1 : 0}
       data-slot="range-slider-thumb"
+      aria-label={thumbAriaLabel}
+      aria-labelledby={thumbAriaLabelledBy}
       aria-valuemin={min}
       aria-valuemax={max}
       aria-valuenow={value}

package/src/ui/slider/types.ts

@@ -20,9 +20,9 @@ export type SliderProps = SliderRootVariantProps & {
   onValueChange?: (value: number) => void;
   disabled?: boolean;
   appearance?: VariantProps<typeof sliderRangeVariants>["appearance"];
-  /** Label for the slider group (accessibility). */
+  /** Accessible name for the slider (applied to the focusable thumb). */
   "aria-label"?: string;
-  /** Optional visible label id */
+  /** Visible label element id (`aria-labelledby` on the focusable thumb). */
   "aria-labelledby"?: string;
   children?: ReactNode;
 } & Omit<ComponentPropsWithoutRef<"div">, "children" | "defaultValue">;
@@ -45,7 +45,9 @@ export type RangeSliderProps = SliderRootVariantProps & {
   onValueChange?: (value: [number, number]) => void;
   disabled?: boolean;
   appearance?: VariantProps<typeof sliderRangeVariants>["appearance"];
+  /** Accessible name for the range control (each thumb gets a distinct suffix). */
   "aria-label"?: string;
+  /** Visible label element id for each thumb when `aria-label` is not used. */
   "aria-labelledby"?: string;
 } & Omit<ComponentPropsWithoutRef<"div">, "children" | "defaultValue">;
 
@@ -63,4 +65,8 @@ export type SliderCtx = {
   size: NonNullable<SliderProps["size"]>;
   appearance: SliderAppearance;
   trackRef: RefObject<HTMLDivElement | null>;
+  /** Mirrored from `<Slider>` so the focusable thumb exposes an accessible name. */
+  "aria-label"?: string;
+  /** Mirrored from `<Slider>` so the focusable thumb exposes an accessible name. */
+  "aria-labelledby"?: string;
 };

package/src/ui/spinner/animated/spinner.tsx

@@ -33,6 +33,7 @@ export function Spinner(props: SpinnerProps) {
         initial={false}
         {...rest}
       >
+        <span className="sr-only">{ariaLabel}</span>
         <motion.span
           className="block size-full rounded-full border-2 border-current border-t-transparent"
           animate={{ rotate: 360 }}
@@ -62,6 +63,7 @@ export function Spinner(props: SpinnerProps) {
         initial={false}
         {...rest}
       >
+        <span className="sr-only">{ariaLabel}</span>
         {[0, 1, 2].map((index) => (
           <motion.span
             key={index}
@@ -91,6 +93,7 @@ export function Spinner(props: SpinnerProps) {
         initial={false}
         {...rest}
       >
+        <span className="sr-only">{ariaLabel}</span>
         <motion.span
           className="block size-full rounded-full bg-current"
           animate={{ scale: [0.75, 1, 0.75], opacity: [0.45, 1, 0.45] }}
@@ -122,6 +125,7 @@ export function Spinner(props: SpinnerProps) {
       initial={false}
       {...rest}
     >
+      <span className="sr-only">{ariaLabel}</span>
       {[0, 1, 2, 3].map((index) => (
         <motion.span
           key={index}

package/src/ui/stepper/stepper.test.tsx

@@ -19,7 +19,7 @@ describe("Stepper", () => {
     expect(StepperDescription.displayName).toBe("StepperDescription");
   });
 
-  it("should stamp data-slot on stepper root and use list semantics", () => {
+  it("should stamp data-slot on stepper root and use ordered list markup", () => {
     render(
       <Stepper>
         <StepperItem>
@@ -30,11 +30,10 @@ describe("Stepper", () => {
     );
     const root = document.querySelector('[data-slot="stepper"]');
     expect(root).toBeTruthy();
-    expect(root).toHaveAttribute("role", "list");
-    expect(document.querySelector('[data-slot="stepper-item"]')).toHaveAttribute(
-      "role",
-      "listitem",
-    );
+    expect(root?.tagName).toBe("OL");
+    expect(
+      document.querySelector('[data-slot="stepper-item"]')?.tagName,
+    ).toBe("LI");
   });
 
   it("should apply default upcoming appearance to indicators", () => {
@@ -153,7 +152,7 @@ describe("Stepper", () => {
   });
 
   it("should forward ref on Stepper", () => {
-    const ref = createRef<HTMLDivElement>();
+    const ref = createRef<HTMLOListElement>();
     render(
       <Stepper ref={ref}>
         <StepperItem>

package/src/ui/stepper/stepper.tsx

@@ -6,7 +6,6 @@ import {
   isValidElement,
   useContext,
   useMemo,
-  type Ref,
 } from "react";
 
 import { cn } from "../../lib/utils";
@@ -54,7 +53,7 @@ export function Stepper({
   children,
   ref,
   ...rest
-}: StepperProps & { ref?: Ref<HTMLDivElement> }) {
+}: StepperProps) {
   const items = useMemo(
     () => Children.toArray(children).filter(isValidElement),
     [children],
@@ -70,11 +69,14 @@ export function Stepper({
 
   return (
     <StepperContext.Provider value={ctx}>
-      <div
+      <ol
         ref={ref}
         data-slot="stepper"
-        role="list"
-        className={cn(stepperVariants({ orientation }), className)}
+        className={cn(
+          stepperVariants({ orientation }),
+          "m-0 list-none p-0",
+          className,
+        )}
         {...rest}
       >
         {items.map((child, index) => (
@@ -82,7 +84,7 @@ export function Stepper({
             {child}
           </StepperIndexContext.Provider>
         ))}
-      </div>
+      </ol>
     </StepperContext.Provider>
   );
 }
@@ -94,18 +96,17 @@ export function StepperItem({
   ref,
   children,
   ...rest
-}: StepperItemProps & { ref?: React.Ref<HTMLDivElement> }) {
+}: StepperItemProps) {
   const { orientation } = useStepper("StepperItem");
   return (
-    <div
+    <li
       ref={ref}
       data-slot="stepper-item"
-      role="listitem"
       className={cn(stepperItemVariants({ orientation }), className)}
       {...rest}
     >
       {children}
-    </div>
+    </li>
   );
 }
 

package/src/ui/stepper/types.ts

@@ -1,5 +1,9 @@
 import type { VariantProps } from "class-variance-authority";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react";
 
 import type { stepperIndicatorVariants, stepperVariants } from "./variants";
 
@@ -8,9 +12,9 @@ type StepperVariantProps = VariantProps<typeof stepperVariants>;
 export type StepperProps = StepperVariantProps & {
   size?: VariantProps<typeof stepperIndicatorVariants>["size"];
   children?: ReactNode;
-} & Omit<ComponentPropsWithoutRef<"div">, "children">;
+} & Omit<ComponentPropsWithRef<"ol">, "children">;
 
-export type StepperItemProps = ComponentPropsWithoutRef<"div"> & {
+export type StepperItemProps = ComponentPropsWithRef<"li"> & {
   children?: ReactNode;
 };
 

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

@@ -30,6 +30,7 @@ export function TableBase(props: TableProps) {
     size = "md",
     textAlign = "left",
     stickyHeader = false,
+    scrollAreaAriaLabel,
     children,
     ref,
     ...rest
@@ -47,11 +48,19 @@ export function TableBase(props: TableProps) {
 
   return (
     <TableContext.Provider value={ctx}>
-      <div data-slot="table-scroll" className="relative w-full overflow-auto">
+      <div
+        data-slot="table-scroll"
+        tabIndex={0}
+        role="region"
+        aria-label={scrollAreaAriaLabel ?? "Scrollable table"}
+        className={cn(
+          "relative w-full overflow-auto",
+          "outline-none focus-visible:ring-2 focus-visible:ring-slate-300 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-950",
+        )}
+      >
         <table
           ref={ref}
           data-slot="table"
-          role="table"
           className={cn(
             tableVariants({ appearance, size, stickyHeader }),
             "w-full min-w-0 table",
@@ -163,17 +172,34 @@ export function TableCell({
   className,
   children,
   ref,
+  scope,
   ...rest
 }: TableCellProps) {
   const { appearance, size, textAlign } = useTableContext("TableCell");
+  const cellClassName = cn(
+    tableCellVariants({ appearance, size, textAlign }),
+    className,
+  );
+
+  if (scope !== undefined) {
+    return (
+      <th
+        ref={ref}
+        data-slot="table-cell"
+        scope={scope}
+        className={cellClassName}
+        {...rest}
+      >
+        {children}
+      </th>
+    );
+  }
+
   return (
     <td
       ref={ref}
       data-slot="table-cell"
-      className={cn(
-        tableCellVariants({ appearance, size, textAlign }),
-        className,
-      )}
+      className={cellClassName}
       {...rest}
     >
       {children}

package/src/ui/table/types.ts

@@ -19,6 +19,8 @@ export type TableProps = TableVariantProps &
     children?: ReactNode;
     ref?: Ref<HTMLTableElement>;
     textAlign?: "left" | "center" | "right";
+    /** Label for the overflow scroll wrapper (keyboard-focusable region). */
+    scrollAreaAriaLabel?: string;
   };
 
 export type TableSectionProps = {
@@ -33,9 +35,14 @@ export type TableHeadCellProps = ThHTMLAttributes<HTMLTableCellElement> & {
   ref?: Ref<HTMLTableCellElement>;
 };
 
-export type TableCellProps = TdHTMLAttributes<HTMLTableCellElement> & {
+export type TableCellProps = Omit<
+  TdHTMLAttributes<HTMLTableCellElement>,
+  "scope"
+> & {
   ref?: Ref<HTMLTableCellElement>;
   textAlign?: "left" | "center" | "right";
+  /** Row/column header scope; when set, the cell renders as `<th>` (required for valid `scope` usage). */
+  scope?: ThHTMLAttributes<HTMLTableCellElement>["scope"];
 };
 
 export type TableCtx = {