@zentauri-ui/zentauri-components 1.4.61 → 1.4.62

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

@@ -1,6 +1,15 @@
 "use client";
 
-import { createContext, useContext, useMemo } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useId,
+  useRef,
+  useState,
+} from "react";
 
 import { cn, clamp } from "../../lib/utils";
 
@@ -40,6 +49,32 @@ export function ProgressBase(props: ProgressProps) {
   } = props;
   const clamped = clamp(value, min, max);
   const percent = max === min ? 0 : ((clamped - min) / (max - min)) * 100;
+  const labelSlotId = `${useId()}-progress-label`;
+  const labelSlotCountRef = useRef(0);
+  const [labelSlotMounted, setLabelSlotMounted] = useState(false);
+  const registerProgressLabel = useCallback(() => {
+    labelSlotCountRef.current += 1;
+    if (labelSlotCountRef.current === 1) {
+      setLabelSlotMounted(true);
+    }
+    return () => {
+      labelSlotCountRef.current -= 1;
+      if (labelSlotCountRef.current === 0) {
+        setLabelSlotMounted(false);
+      }
+    };
+  }, []);
+  const hasInlineLabelProp = Boolean(label?.trim().length);
+
+  const labelingProps = useMemo(() => {
+    if (hasInlineLabelProp) {
+      return { "aria-label": label?.trim() ?? "Progress" };
+    }
+    if (labelSlotMounted) {
+      return { "aria-labelledby": labelSlotId };
+    }
+    return { "aria-label": "Progress" };
+  }, [hasInlineLabelProp, label, labelSlotId, labelSlotMounted]);
 
   const ctx = useMemo(
     () => ({
@@ -51,8 +86,21 @@ export function ProgressBase(props: ProgressProps) {
       striped: Boolean(striped),
       animated: Boolean(animated),
       appearance: appearance ?? "default",
+      labelSlotId,
+      registerProgressLabel,
     }),
-    [animated, appearance, clamped, max, min, shape, size, striped],
+    [
+      animated,
+      appearance,
+      clamped,
+      labelSlotId,
+      max,
+      min,
+      registerProgressLabel,
+      shape,
+      size,
+      striped,
+    ],
   );
 
   return (
@@ -64,7 +112,7 @@ export function ProgressBase(props: ProgressProps) {
         aria-valuemin={min}
         aria-valuemax={max}
         aria-valuenow={clamped}
-        aria-label={label}
+        {...labelingProps}
         className={cn(
           progressVariants({ appearance, size, shape, striped, animated }),
           className,
@@ -121,8 +169,16 @@ export function ProgressBar({
 ProgressBar.displayName = "ProgressBar";
 
 export function ProgressLabel({ className, children }: ProgressSectionProps) {
+  const { labelSlotId, registerProgressLabel } =
+    useProgressContext("ProgressLabel");
+
+  useEffect(() => {
+    return registerProgressLabel();
+  }, [registerProgressLabel]);
+
   return (
     <div
+      id={labelSlotId}
       data-slot="progress-label"
       className={cn("mb-2 font-medium text-slate-200", className)}
     >

package/src/ui/progress/types.ts

@@ -30,4 +30,7 @@ export type ProgressCtx = {
   striped: boolean;
   animated: boolean;
   appearance: NonNullable<ProgressProps["appearance"]>;
+  labelSlotId: string;
+  /** Increments the label mount count; returned cleanup decrements. Multiple labels are supported. */
+  registerProgressLabel: () => () => void;
 };

package/src/ui/search/search-bar.tsx

@@ -24,6 +24,7 @@ export const SearchBar = function SearchBar(
     comboboxListboxId,
     comboboxActiveOptionId,
     comboboxExpanded,
+    "aria-label": ariaLabel,
     ref,
     ...rest
   }: SearchBarProps,
@@ -53,6 +54,10 @@ export const SearchBar = function SearchBar(
         spellCheck={false}
         disabled={disabled}
         value={value}
+        aria-label={
+          ariaLabel ??
+          (combobox ? undefined : "Search")
+        }
         data-slot="search-bar-input"
         className={cn(
           inputVariants({ appearance, size: inputSize, ring, as: "input" }),

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;
 };