@zentauri-ui/zentauri-components 1.4.51 → 1.4.62

package/src/ui/empty-state/types.ts

@@ -8,6 +8,7 @@ type EmptyStateVariantProps = VariantProps<typeof emptyStateVariants>;
 export type EmptyStateProps = EmptyStateVariantProps &
   (Omit<ComponentPropsWithRef<"section">, "children"> & {
     children?: ReactNode;
+    liveRegion?: false | true | "polite" | "assertive";
     as?: ElementType;
   });
 

package/src/ui/file-upload/file-upload.tsx

@@ -70,8 +70,6 @@ export function FileUpload({
         multiple={multiple}
         disabled={disabled}
         onChange={handleChange}
-        aria-hidden
-        tabIndex={-1}
       />
       <label
         htmlFor={inputId}

package/src/ui/inputs/input-base.tsx

@@ -7,6 +7,18 @@ import { cn } from "../../lib/utils";
 import type { InputProps } from "./types";
 import { inputVariants } from "./variants";
 
+function mergeDescribedByIds(
+  user: string | undefined,
+  ...generated: (string | undefined)[]
+): string | undefined {
+  const ids = [
+    ...(user ?? "").split(/\s+/).filter(Boolean),
+    ...generated.filter((id): id is string => Boolean(id)),
+  ];
+  const unique = [...new Set(ids)];
+  return unique.length > 0 ? unique.join(" ") : undefined;
+}
+
 export const InputBase = (props: InputProps) => {
   const generatedId = useId();
 
@@ -19,13 +31,17 @@ export const InputBase = (props: InputProps) => {
       ref,
       "aria-invalid": ariaInvalidProp,
       errorMessage,
+      hint,
+      label,
       id,
       as,
+      "aria-describedby": ariaDescribedByUser,
       ...rest
     } = props;
 
     const controlId = id ?? generatedId;
     const errorId = `${controlId}-error`;
+    const hintId = `${controlId}-hint`;
     const ariaInvalid =
       ariaInvalidProp !== undefined
         ? ariaInvalidProp
@@ -33,8 +49,27 @@ export const InputBase = (props: InputProps) => {
           ? true
           : undefined;
 
+    const describedBy = mergeDescribedByIds(
+      ariaDescribedByUser,
+      hint !== undefined ? hintId : undefined,
+      errorMessage && appearance === "error" ? errorId : undefined,
+    );
+
     return (
       <>
+        {label !== undefined && (
+          <label
+            htmlFor={controlId}
+            className="mb-1 block text-sm font-medium text-slate-200"
+          >
+            {label}
+          </label>
+        )}
+        {hint !== undefined && (
+          <p id={hintId} className="mb-1 text-xs text-slate-400">
+            {hint}
+          </p>
+        )}
         <textarea
           ref={ref}
           id={controlId}
@@ -44,9 +79,7 @@ export const InputBase = (props: InputProps) => {
             className,
           )}
           aria-invalid={ariaInvalid}
-          aria-describedby={
-            errorMessage && appearance === "error" ? errorId : undefined
-          }
+          aria-describedby={describedBy}
           {...rest}
         />
         {errorMessage && appearance === "error" && (
@@ -69,13 +102,17 @@ export const InputBase = (props: InputProps) => {
     ref,
     "aria-invalid": ariaInvalidProp,
     errorMessage,
+    hint,
+    label,
     id,
     as,
+    "aria-describedby": ariaDescribedByUser,
     ...rest
   } = props;
 
   const controlId = id ?? generatedId;
   const errorId = `${controlId}-error`;
+  const hintId = `${controlId}-hint`;
   const ariaInvalid =
     ariaInvalidProp !== undefined
       ? ariaInvalidProp
@@ -83,8 +120,27 @@ export const InputBase = (props: InputProps) => {
         ? true
         : undefined;
 
+  const describedBy = mergeDescribedByIds(
+    ariaDescribedByUser,
+    hint !== undefined ? hintId : undefined,
+    errorMessage && appearance === "error" ? errorId : undefined,
+  );
+
   return (
     <>
+      {label !== undefined && (
+        <label
+          htmlFor={controlId}
+          className="mb-1 block text-sm font-medium text-slate-200"
+        >
+          {label}
+        </label>
+      )}
+      {hint !== undefined && (
+        <p id={hintId} className="mb-1 text-xs text-slate-400">
+          {hint}
+        </p>
+      )}
       <input
         ref={ref}
         id={controlId}
@@ -94,9 +150,7 @@ export const InputBase = (props: InputProps) => {
           className,
         )}
         aria-invalid={ariaInvalid}
-        aria-describedby={
-          errorMessage && appearance === "error" ? errorId : undefined
-        }
+        aria-describedby={describedBy}
         {...rest}
       />
       {errorMessage && appearance === "error" && (

package/src/ui/inputs/types.ts

@@ -1,10 +1,12 @@
 import type { VariantProps } from "class-variance-authority";
-import type { ComponentPropsWithRef } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
 
 import type { inputVariants } from "./variants";
 
 export type InputSharedProps = Omit<VariantProps<typeof inputVariants>, "as"> & {
   errorMessage?: string;
+  hint?: ReactNode;
+  label?: ReactNode;
 };
 
 export type InputProps =

package/src/ui/modal/animated/modal-content-animated.tsx

@@ -22,7 +22,7 @@ export function ModalContentAnimated({
   id,
   style,
 }: ModalContentAnimatedProps) {
-  const { open, setOpen, titleId, descriptionId, contentRef } =
+  const { open, setOpen, titleId, descriptionId, contentRef, triggerRef } =
     useModalContext("ModalContent");
   const reduceMotion = useReducedMotion();
   const overlayMotion =
@@ -34,6 +34,7 @@ export function ModalContentAnimated({
     open,
     setOpen,
     contentRef,
+    triggerRef,
   });
 
   const portalTarget = typeof document !== "undefined" ? document.body : null;
@@ -46,10 +47,8 @@ export function ModalContentAnimated({
     <AnimatePresence>
       {open ? (
         <div className="fixed inset-0 z-50" data-slot="modal-portal">
-          <motion.button
-            type="button"
-            aria-hidden
-            tabIndex={-1}
+          <motion.div
+            role="presentation"
             data-slot="modal-overlay"
             className={modalOverlayVariants()}
             onClick={() => setOpen(false)}

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

@@ -8,6 +8,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type RefObject,
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -31,7 +32,8 @@ type ModalCtx = {
   setOpen: (next: boolean) => void;
   titleId: string;
   descriptionId: string;
-  contentRef: React.RefObject<HTMLDivElement | null>;
+  contentRef: RefObject<HTMLDivElement | null>;
+  triggerRef: RefObject<HTMLElement | null>;
 };
 
 const ModalContext = createContext<ModalCtx | null>(null);
@@ -68,6 +70,7 @@ export function Modal({
   const titleId = `${baseId}-title`;
   const descriptionId = `${baseId}-description`;
   const contentRef = useRef<HTMLDivElement | null>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
 
   const ctx = useMemo(
     () => ({
@@ -76,6 +79,7 @@ export function Modal({
       titleId,
       descriptionId,
       contentRef,
+      triggerRef,
     }),
     [descriptionId, resolvedOpen, setOpen, titleId],
   );
@@ -90,13 +94,20 @@ export function ModalTrigger({
   children,
   appearance,
   onClick,
-  ref,
+  ref: refProp,
   ...rest
 }: ModalTriggerProps) {
-  const { setOpen } = useModalContext("ModalTrigger");
+  const { setOpen, triggerRef } = useModalContext("ModalTrigger");
   return (
     <button
-      ref={ref}
+      ref={(node) => {
+        triggerRef.current = node;
+        if (typeof refProp === "function") {
+          refProp(node);
+        } else if (refProp) {
+          (refProp as RefObject<HTMLButtonElement | null>).current = node;
+        }
+      }}
       type="button"
       data-slot="modal-trigger"
       className={cn(modalTriggerVariants({ appearance }), className)}
@@ -126,13 +137,14 @@ export function ModalContent({
   id,
   style,
 }: ModalContentProps) {
-  const { open, setOpen, titleId, descriptionId, contentRef } =
+  const { open, setOpen, titleId, descriptionId, contentRef, triggerRef } =
     useModalContext("ModalContent");
 
   useFocusManagement({
     open,
     setOpen,
     contentRef,
+    triggerRef,
   });
 
   const portalTarget = typeof document !== "undefined" ? document.body : null;
@@ -144,10 +156,8 @@ export function ModalContent({
   return createPortal(
     open ? (
       <div className="fixed inset-0 z-50" data-slot="modal-portal">
-        <button
-          type="button"
-          aria-hidden
-          tabIndex={-1}
+        <div
+          role="presentation"
           data-slot="modal-overlay"
           className={modalOverlayVariants()}
           onClick={() => setOpen(false)}

package/src/ui/modal/modal.test.tsx

@@ -77,6 +77,21 @@ describe("Modal", () => {
     });
   });
 
+  it("should render overlay as non-focusable presentation surface", async () => {
+    render(
+      <Modal defaultOpen>
+        <ModalContent>
+          <ModalTitle>T</ModalTitle>
+        </ModalContent>
+      </Modal>,
+    );
+    await waitFor(() => expect(screen.getByRole("dialog")).toBeInTheDocument());
+    const overlay = document.querySelector('[data-slot="modal-overlay"]');
+    expect(overlay?.tagName.toLowerCase()).toBe("div");
+    expect(overlay).toHaveAttribute("role", "presentation");
+    expect((overlay as HTMLElement).tabIndex).toBe(-1);
+  });
+
   it("should close when Escape is pressed", async () => {
     const user = userEvent.setup();
     render(
@@ -126,4 +141,27 @@ describe("Modal", () => {
     await user.keyboard("{Escape}");
     await waitFor(() => expect(handleChange).toHaveBeenLastCalledWith(false));
   });
+
+  it("should restore focus to the trigger after the dialog closes", async () => {
+    const user = userEvent.setup();
+    render(
+      <Modal>
+        <ModalTrigger>Open</ModalTrigger>
+        <ModalContent>
+          <ModalTitle>T</ModalTitle>
+        </ModalContent>
+      </Modal>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    trigger.focus();
+    await user.click(trigger);
+    await waitFor(() =>
+      expect(screen.getByRole("dialog")).toBeInTheDocument(),
+    );
+    await user.keyboard("{Escape}");
+    await waitFor(() =>
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),
+    );
+    expect(trigger).toHaveFocus();
+  });
 });

package/src/ui/pagination/pagination.tsx

@@ -192,9 +192,9 @@ export const Pagination = forwardRef<HTMLElement, PaginationProps>(
                 {item.type === "ellipsis" ? (
                   <span
                     data-slot="pagination-ellipsis"
-                    aria-hidden="true"
-                    title={ellipsisLabel}
                     className={paginationEllipsisVariants({ size })}
+                    role="img"
+                    aria-label={ellipsisLabel}
                   >
                     …
                   </span>

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 import { motion } from "framer-motion";
 
 import { cn, clamp } from "../../../lib/utils";
@@ -39,6 +39,32 @@ export function ProgressAnimated({
 }: ProgressAnimatedProps) {
   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<ProgressCtx>(
     () => ({
@@ -50,8 +76,21 @@ export function ProgressAnimated({
       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,
+    ],
   );
 
   const motionProps = progressAnimationPresets[animation];
@@ -65,8 +104,8 @@ export function ProgressAnimated({
         aria-valuemin={min}
         aria-valuemax={max}
         aria-valuenow={clamped}
-        aria-label={label}
         aria-busy={busy ? true : undefined}
+        {...labelingProps}
         className={cn(
           progressVariants({ appearance, size, shape, striped, animated }),
           className,

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, useId } from "react";
+import { useId } from "react";
 
 import { cn } from "../../lib/utils";
 import { inputVariants } from "../inputs/variants";
@@ -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/search/search-suggestion-list.tsx

@@ -31,9 +31,21 @@ export function SearchSuggestionList({
     );
   }
 
-  let lastGroup: string | undefined;
   const useListbox = Boolean(listboxId);
 
+  const rows: Array<{
+    item: (typeof items)[number];
+    showGroup: boolean;
+  }> = [];
+  let lastGroupSeen: string | undefined;
+  for (const item of items) {
+    const showGroup = Boolean(item.group && item.group !== lastGroupSeen);
+    if (item.group) {
+      lastGroupSeen = item.group;
+    }
+    rows.push({ item, showGroup });
+  }
+
   return (
     <nav
       data-slot="search-suggestion-list"
@@ -49,11 +61,7 @@ export function SearchSuggestionList({
           : {})}
         className={cn("flex flex-col gap-0.5", listClassName)}
       >
-        {items.map((item) => {
-          const showGroup = item.group && item.group !== lastGroup;
-          if (item.group) {
-            lastGroup = item.group;
-          }
+        {rows.map(({ item, showGroup }) => {
           const isActive = activeId === item.id;
           const optionDomId =
             useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : undefined;