feat: a11y improvements

* streamline ARIA roles, role descriptions and labels
* add localization for ARIA labels and role descriptions
* set empty string as the default image slide `alt` attribute

Author: igordanchenko

dev/App.tsx

@@ -12,7 +12,7 @@ export default function App() {
     <main className="centered">
       <Lightbox slides={slides} index={index} setIndex={setIndex} />
 
-      <button type="button" className="button" onClick={() => setIndex(0)}>
+      <button type="button" className="button" onClick={() => setIndex(0)} aria-haspopup="dialog">
         Open Lightbox
       </button>
     </main>

src/components/Carousel.tsx

@@ -3,28 +3,39 @@ import { useEffect, useRef } from "react";
 import ImageSlide from "./ImageSlide";
 import { useZoom, useZoomInternal } from "./Zoom";
 import { useLightboxContext } from "./LightboxContext";
-import { cssClass, isImageSlide, round } from "../utils";
+import { cssClass, isImageSlide, round, translateLabel, translateSlideCounter } from "../utils";
 import { RenderSlideProps, SlideImage } from "../types";
 
-function CarouselSlide({ slide, rect, current }: Pick<RenderSlideProps, "slide" | "rect" | "current">) {
+function CarouselSlide({
+  slide,
+  rect,
+  current,
+  slideIndex,
+}: Pick<RenderSlideProps, "slide" | "rect" | "current" | "slideIndex">) {
   const ref = useRef<HTMLDivElement | null>(null);
 
   const { zoom, offsetX, offsetY } = useZoom();
-  const { styles, render: { slide: renderSlide, slideHeader, slideFooter } = {} } = useLightboxContext();
+  const {
+    slides,
+    styles,
+    labels,
+    render: { slide: renderSlide, slideHeader, slideFooter } = {},
+  } = useLightboxContext();
 
   useEffect(() => {
     if (!current && ref.current?.contains(document.activeElement)) {
       ref.current.closest<HTMLElement>('[tabindex="-1"]')?.focus();
     }
   }, [current]);
 
-  const context = { slide, rect, current, zoom: round(current ? zoom : 1, 3) };
+  const context = { slide, rect, current, slideIndex, zoom: round(current ? zoom : 1, 3) };
 
   return (
     <div
       ref={ref}
       role="group"
-      aria-roledescription="slide"
+      aria-label={translateSlideCounter(labels, slideIndex + 1, slides.length)}
+      aria-roledescription={translateLabel(labels, "Slide")}
       className={cssClass("slide")}
       hidden={!current}
       style={{
@@ -44,12 +55,20 @@ function CarouselSlide({ slide, rect, current }: Pick<RenderSlideProps, "slide"
 }
 
 export default function Carousel() {
-  const { slides, index, styles, carousel: { preload = 2 } = {} } = useLightboxContext();
+  const { slides, index, styles, labels, carousel: { preload = 2 } = {} } = useLightboxContext();
   const { setCarouselRef } = useZoomInternal();
   const { rect } = useZoom();
 
   return (
-    <div ref={setCarouselRef} style={styles?.carousel} className={cssClass("carousel")}>
+    <div
+      ref={setCarouselRef}
+      style={styles?.carousel}
+      className={cssClass("carousel")}
+      role="region"
+      aria-live="polite"
+      aria-label={translateLabel(labels, "Photo gallery")}
+      aria-roledescription={translateLabel(labels, "Carousel")}
+    >
       {rect &&
         Array.from({ length: 2 * preload + 1 }).map((_, i) => {
           const slideIndex = index - preload + i;
@@ -63,6 +82,7 @@ export default function Carousel() {
               key={slide.key ?? [`${slideIndex}`, isImageSlide(slide) && slide.src].filter(Boolean).join("|")}
               rect={rect}
               slide={slide}
+              slideIndex={slideIndex}
               current={slideIndex === index}
             />
           );

src/components/ImageSlide.tsx

@@ -58,7 +58,7 @@ export default function ImageSlide({ slide, rect, zoom }: ImageSlideProps) {
       width={width}
       height={height}
       src={slide.src}
-      alt={slide.alt}
+      alt={slide.alt ?? ""}
       {...imageProps}
     />
   );

src/components/Portal.tsx

@@ -4,7 +4,7 @@ import { createPortal } from "react-dom";
 import useSensors from "./useSensors";
 import { useController } from "./Controller";
 import { useLightboxContext } from "./LightboxContext";
-import { clsx, cssClass, cssVar, getChildren } from "../utils";
+import { clsx, cssClass, cssVar, getChildren, translateLabel } from "../utils";
 import { Callback } from "../types";
 
 function setAttribute(element: Element, attribute: string, value: string) {
@@ -22,7 +22,7 @@ function setAttribute(element: Element, attribute: string, value: string) {
 }
 
 export default function Portal({ children }: PropsWithChildren) {
-  const { styles, className } = useLightboxContext();
+  const { labels, styles, className } = useLightboxContext();
 
   const cleanup = useRef<Callback[]>([]);
 
@@ -120,8 +120,7 @@ export default function Portal({ children }: PropsWithChildren) {
         <div
           aria-modal
           role="dialog"
-          aria-live="polite"
-          aria-roledescription="lightbox"
+          aria-label={translateLabel(labels, "Lightbox")}
           tabIndex={-1}
           ref={handleRef}
           style={styles?.portal}

src/types.ts

@@ -74,9 +74,28 @@ export interface ImageSource {
 
 /** Custom UI labels / translations */
 export interface Labels {
+  /** `Previous` button title */
   Previous?: string;
+  /** `Next` button title */
   Next?: string;
+  /** `Close` button title */
   Close?: string;
+  /** Lightbox ARIA label */
+  Lightbox?: string;
+  /** Carousel ARIA role description */
+  Carousel?: string;
+  /** Slide ARIA role description */
+  Slide?: string;
+  /** Carousel ARIA label */
+  "Photo gallery"?: string;
+  /**
+   * Slide ARIA label
+   *
+   * The value is a template string supporting the following placeholders:
+   * - {index} - current slide index
+   * - {total} - total number of slides
+   */
+  "{index} of {total}"?: string;
 }
 
 /** Label key */
@@ -110,6 +129,8 @@ export interface RenderSlideProps {
   zoom: number;
   /** if `true`, the slide is the current slide in the viewport */
   current: boolean;
+  /** slide index */
+  slideIndex: number;
 }
 
 /** Toolbar settings */

src/utils.ts

@@ -31,6 +31,12 @@ export function translateLabel(labels: Labels | undefined, label: Label) {
   return labels?.[label] ?? label;
 }
 
+export function translateSlideCounter(labels: Labels | undefined, index: number, total: number) {
+  return translateLabel(labels, "{index} of {total}")
+    .replace(/\{index}/g, `${index}`)
+    .replace(/\{total}/g, `${total}`);
+}
+
 export function makeUseContext<T>(context: Context<T | null>) {
   return () => {
     const ctx = useContext(context);