@lessonkit/accessibility 0.2.1 → 0.3.0

package/README.md

@@ -12,9 +12,18 @@ Small accessibility utilities used by LessonKit packages and apps.
 npm install @lessonkit/accessibility
 ```
 
-## Included (0.2.1)
+## Included (0.3.0)
 
 - `prefersReducedMotion()`
+- `getReducedMotionPreference()`
+- `shouldAnimate({ default })`
 - `focusFirst(container)`
+- `getFocusableElements(container)`
+- `trapFocus(container, opts)`
+- `createRovingTabIndex(opts)`
 - `visuallyHiddenStyle` — inline styles for screen-reader-only content (used by `@lessonkit/react` `Quiz`)
 
+## Guidance
+
+- See [`docs/ACCESSIBILITY.md`](../../docs/ACCESSIBILITY.md) for keyboard and screen-reader guidance.
+

package/dist/index.cjs

@@ -20,8 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createRovingTabIndex: () => createRovingTabIndex,
   focusFirst: () => focusFirst,
+  getFocusableElements: () => getFocusableElements,
+  getReducedMotionPreference: () => getReducedMotionPreference,
   prefersReducedMotion: () => prefersReducedMotion,
+  shouldAnimate: () => shouldAnimate,
+  trapFocus: () => trapFocus,
   visuallyHiddenStyle: () => visuallyHiddenStyle
 });
 module.exports = __toCommonJS(index_exports);
@@ -36,9 +41,33 @@ var visuallyHiddenStyle = {
   whiteSpace: "nowrap",
   border: 0
 };
+var FOCUSABLE_SELECTORS = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  // Prefer explicit tabindex, but allow contenteditable too.
+  "[tabindex]:not([tabindex='-1'])",
+  "[contenteditable='true']"
+].join(",");
+function isHTMLElement(v) {
+  return typeof HTMLElement !== "undefined" && v instanceof HTMLElement;
+}
 function prefersReducedMotion() {
   return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
+function getReducedMotionPreference() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "unknown";
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "reduce" : "no-preference";
+}
+function shouldAnimate(opts) {
+  const pref = getReducedMotionPreference();
+  if (pref === "reduce") return false;
+  if (pref === "no-preference") return true;
+  return opts?.default ?? true;
+}
 function focusFirst(container) {
   if (!container) return false;
   const el = container.querySelector(
@@ -54,9 +83,168 @@ function focusFirst(container) {
   el?.focus();
   return Boolean(el);
 }
+function getFocusableElements(container) {
+  const candidates = Array.from(container.querySelectorAll(FOCUSABLE_SELECTORS));
+  return candidates.filter((n) => isHTMLElement(n) && !n.hasAttribute("disabled"));
+}
+function trapFocus(container, opts) {
+  const restoreFocus = opts?.restoreFocus ?? true;
+  const allowOutsideClick = opts?.allowOutsideClick ?? false;
+  let active = false;
+  let prevFocused = null;
+  let removeListeners = null;
+  const onKeyDown = (e) => {
+    if (!active) return;
+    if (e.key !== "Tab") return;
+    const focusables = getFocusableElements(container);
+    if (!focusables.length) {
+      e.preventDefault();
+      container.focus?.();
+      return;
+    }
+    const current = document.activeElement;
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    if (e.shiftKey) {
+      if (current === first || !container.contains(current)) {
+        e.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (current === last || !container.contains(current)) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  };
+  const onFocusIn = (e) => {
+    if (!active) return;
+    const target = e.target;
+    if (!isHTMLElement(target)) return;
+    if (container.contains(target)) return;
+    const focusables = getFocusableElements(container);
+    (focusables[0] ?? container).focus?.();
+  };
+  const onPointerDownCapture = (e) => {
+    if (!active) return;
+    if (allowOutsideClick) return;
+    const target = e.target;
+    if (!isHTMLElement(target)) return;
+    if (container.contains(target)) return;
+    e.preventDefault();
+    e.stopPropagation();
+  };
+  const activate = () => {
+    if (active) return;
+    active = true;
+    prevFocused = restoreFocus && isHTMLElement(document.activeElement) ? document.activeElement : null;
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("mousedown", onPointerDownCapture, true);
+    removeListeners = () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("focusin", onFocusIn);
+      document.removeEventListener("mousedown", onPointerDownCapture, true);
+    };
+    const focusables = getFocusableElements(container);
+    const requested = opts?.initialFocus;
+    if (requested === "first" || requested === void 0) {
+      (focusables[0] ?? container).focus?.();
+    } else if (isHTMLElement(requested)) {
+      requested.focus();
+    }
+  };
+  const deactivate = () => {
+    if (!active) return;
+    active = false;
+    removeListeners?.();
+    removeListeners = null;
+    const toRestore = prevFocused;
+    prevFocused = null;
+    if (restoreFocus) toRestore?.focus?.();
+  };
+  return { activate, deactivate };
+}
+function createRovingTabIndex(opts) {
+  const itemCount = Math.max(0, opts.itemCount);
+  const loop = opts.loop ?? true;
+  const orientation = opts.orientation ?? "both";
+  let activeIndex = clampIndex(opts.initialIndex ?? 0, itemCount);
+  const setActiveIndex = (next) => {
+    activeIndex = clampIndex(next, itemCount);
+  };
+  const move = (delta) => {
+    if (!itemCount) return;
+    const next = activeIndex + delta;
+    if (loop) {
+      activeIndex = (next % itemCount + itemCount) % itemCount;
+      return;
+    }
+    activeIndex = clampIndex(next, itemCount);
+  };
+  const onKeyDown = (e) => {
+    if (!itemCount) return;
+    switch (e.key) {
+      case "Home":
+        e.preventDefault();
+        activeIndex = 0;
+        return;
+      case "End":
+        e.preventDefault();
+        activeIndex = itemCount - 1;
+        return;
+      case "ArrowLeft":
+        if (orientation === "vertical") return;
+        e.preventDefault();
+        move(-1);
+        return;
+      case "ArrowRight":
+        if (orientation === "vertical") return;
+        e.preventDefault();
+        move(1);
+        return;
+      case "ArrowUp":
+        if (orientation === "horizontal") return;
+        e.preventDefault();
+        move(-1);
+        return;
+      case "ArrowDown":
+        if (orientation === "horizontal") return;
+        e.preventDefault();
+        move(1);
+        return;
+    }
+  };
+  const getItemProps = (index) => ({
+    tabIndex: index === activeIndex ? 0 : -1,
+    id: opts.getId ? opts.getId(index) : void 0,
+    onKeyDown,
+    onFocus: () => {
+      setActiveIndex(index);
+    }
+  });
+  return {
+    get activeIndex() {
+      return activeIndex;
+    },
+    setActiveIndex,
+    getItemProps
+  };
+}
+function clampIndex(index, itemCount) {
+  if (itemCount <= 0) return 0;
+  if (index < 0) return 0;
+  if (index >= itemCount) return itemCount - 1;
+  return index;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createRovingTabIndex,
   focusFirst,
+  getFocusableElements,
+  getReducedMotionPreference,
   prefersReducedMotion,
+  shouldAnimate,
+  trapFocus,
   visuallyHiddenStyle
 });

package/dist/index.d.cts

@@ -7,6 +7,38 @@ type FocusContainer = {
     querySelector<T>(selectors: string): T | null;
 };
 declare function prefersReducedMotion(): boolean;
+declare function getReducedMotionPreference(): "reduce" | "no-preference" | "unknown";
+declare function shouldAnimate(opts?: {
+    default?: boolean;
+}): boolean;
 declare function focusFirst(container: FocusContainer | null): boolean;
+declare function getFocusableElements(container: Element): HTMLElement[];
+declare function trapFocus(container: HTMLElement, opts?: {
+    initialFocus?: HTMLElement | "first";
+    restoreFocus?: boolean;
+    allowOutsideClick?: boolean;
+}): {
+    activate: () => void;
+    deactivate: () => void;
+};
+declare function createRovingTabIndex(opts: {
+    itemCount: number;
+    getId?: (index: number) => string;
+    orientation?: "horizontal" | "vertical" | "both";
+    loop?: boolean;
+    initialIndex?: number;
+}): {
+    get activeIndex(): number;
+    setActiveIndex: (next: number) => void;
+    getItemProps: (index: number) => {
+        tabIndex: 0 | -1;
+        onKeyDown: (e: KeyboardEvent | {
+            key: string;
+            preventDefault: () => void;
+        }) => void;
+        onFocus: () => void;
+        id?: string;
+    };
+};
 
-export { type FocusContainer, type Focusable, focusFirst, prefersReducedMotion, visuallyHiddenStyle };
+export { type FocusContainer, type Focusable, createRovingTabIndex, focusFirst, getFocusableElements, getReducedMotionPreference, prefersReducedMotion, shouldAnimate, trapFocus, visuallyHiddenStyle };

package/dist/index.d.ts

@@ -7,6 +7,38 @@ type FocusContainer = {
     querySelector<T>(selectors: string): T | null;
 };
 declare function prefersReducedMotion(): boolean;
+declare function getReducedMotionPreference(): "reduce" | "no-preference" | "unknown";
+declare function shouldAnimate(opts?: {
+    default?: boolean;
+}): boolean;
 declare function focusFirst(container: FocusContainer | null): boolean;
+declare function getFocusableElements(container: Element): HTMLElement[];
+declare function trapFocus(container: HTMLElement, opts?: {
+    initialFocus?: HTMLElement | "first";
+    restoreFocus?: boolean;
+    allowOutsideClick?: boolean;
+}): {
+    activate: () => void;
+    deactivate: () => void;
+};
+declare function createRovingTabIndex(opts: {
+    itemCount: number;
+    getId?: (index: number) => string;
+    orientation?: "horizontal" | "vertical" | "both";
+    loop?: boolean;
+    initialIndex?: number;
+}): {
+    get activeIndex(): number;
+    setActiveIndex: (next: number) => void;
+    getItemProps: (index: number) => {
+        tabIndex: 0 | -1;
+        onKeyDown: (e: KeyboardEvent | {
+            key: string;
+            preventDefault: () => void;
+        }) => void;
+        onFocus: () => void;
+        id?: string;
+    };
+};
 
-export { type FocusContainer, type Focusable, focusFirst, prefersReducedMotion, visuallyHiddenStyle };
+export { type FocusContainer, type Focusable, createRovingTabIndex, focusFirst, getFocusableElements, getReducedMotionPreference, prefersReducedMotion, shouldAnimate, trapFocus, visuallyHiddenStyle };

package/dist/index.js

@@ -10,9 +10,33 @@ var visuallyHiddenStyle = {
   whiteSpace: "nowrap",
   border: 0
 };
+var FOCUSABLE_SELECTORS = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  // Prefer explicit tabindex, but allow contenteditable too.
+  "[tabindex]:not([tabindex='-1'])",
+  "[contenteditable='true']"
+].join(",");
+function isHTMLElement(v) {
+  return typeof HTMLElement !== "undefined" && v instanceof HTMLElement;
+}
 function prefersReducedMotion() {
   return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
+function getReducedMotionPreference() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "unknown";
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "reduce" : "no-preference";
+}
+function shouldAnimate(opts) {
+  const pref = getReducedMotionPreference();
+  if (pref === "reduce") return false;
+  if (pref === "no-preference") return true;
+  return opts?.default ?? true;
+}
 function focusFirst(container) {
   if (!container) return false;
   const el = container.querySelector(
@@ -28,8 +52,167 @@ function focusFirst(container) {
   el?.focus();
   return Boolean(el);
 }
+function getFocusableElements(container) {
+  const candidates = Array.from(container.querySelectorAll(FOCUSABLE_SELECTORS));
+  return candidates.filter((n) => isHTMLElement(n) && !n.hasAttribute("disabled"));
+}
+function trapFocus(container, opts) {
+  const restoreFocus = opts?.restoreFocus ?? true;
+  const allowOutsideClick = opts?.allowOutsideClick ?? false;
+  let active = false;
+  let prevFocused = null;
+  let removeListeners = null;
+  const onKeyDown = (e) => {
+    if (!active) return;
+    if (e.key !== "Tab") return;
+    const focusables = getFocusableElements(container);
+    if (!focusables.length) {
+      e.preventDefault();
+      container.focus?.();
+      return;
+    }
+    const current = document.activeElement;
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    if (e.shiftKey) {
+      if (current === first || !container.contains(current)) {
+        e.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (current === last || !container.contains(current)) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  };
+  const onFocusIn = (e) => {
+    if (!active) return;
+    const target = e.target;
+    if (!isHTMLElement(target)) return;
+    if (container.contains(target)) return;
+    const focusables = getFocusableElements(container);
+    (focusables[0] ?? container).focus?.();
+  };
+  const onPointerDownCapture = (e) => {
+    if (!active) return;
+    if (allowOutsideClick) return;
+    const target = e.target;
+    if (!isHTMLElement(target)) return;
+    if (container.contains(target)) return;
+    e.preventDefault();
+    e.stopPropagation();
+  };
+  const activate = () => {
+    if (active) return;
+    active = true;
+    prevFocused = restoreFocus && isHTMLElement(document.activeElement) ? document.activeElement : null;
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("mousedown", onPointerDownCapture, true);
+    removeListeners = () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("focusin", onFocusIn);
+      document.removeEventListener("mousedown", onPointerDownCapture, true);
+    };
+    const focusables = getFocusableElements(container);
+    const requested = opts?.initialFocus;
+    if (requested === "first" || requested === void 0) {
+      (focusables[0] ?? container).focus?.();
+    } else if (isHTMLElement(requested)) {
+      requested.focus();
+    }
+  };
+  const deactivate = () => {
+    if (!active) return;
+    active = false;
+    removeListeners?.();
+    removeListeners = null;
+    const toRestore = prevFocused;
+    prevFocused = null;
+    if (restoreFocus) toRestore?.focus?.();
+  };
+  return { activate, deactivate };
+}
+function createRovingTabIndex(opts) {
+  const itemCount = Math.max(0, opts.itemCount);
+  const loop = opts.loop ?? true;
+  const orientation = opts.orientation ?? "both";
+  let activeIndex = clampIndex(opts.initialIndex ?? 0, itemCount);
+  const setActiveIndex = (next) => {
+    activeIndex = clampIndex(next, itemCount);
+  };
+  const move = (delta) => {
+    if (!itemCount) return;
+    const next = activeIndex + delta;
+    if (loop) {
+      activeIndex = (next % itemCount + itemCount) % itemCount;
+      return;
+    }
+    activeIndex = clampIndex(next, itemCount);
+  };
+  const onKeyDown = (e) => {
+    if (!itemCount) return;
+    switch (e.key) {
+      case "Home":
+        e.preventDefault();
+        activeIndex = 0;
+        return;
+      case "End":
+        e.preventDefault();
+        activeIndex = itemCount - 1;
+        return;
+      case "ArrowLeft":
+        if (orientation === "vertical") return;
+        e.preventDefault();
+        move(-1);
+        return;
+      case "ArrowRight":
+        if (orientation === "vertical") return;
+        e.preventDefault();
+        move(1);
+        return;
+      case "ArrowUp":
+        if (orientation === "horizontal") return;
+        e.preventDefault();
+        move(-1);
+        return;
+      case "ArrowDown":
+        if (orientation === "horizontal") return;
+        e.preventDefault();
+        move(1);
+        return;
+    }
+  };
+  const getItemProps = (index) => ({
+    tabIndex: index === activeIndex ? 0 : -1,
+    id: opts.getId ? opts.getId(index) : void 0,
+    onKeyDown,
+    onFocus: () => {
+      setActiveIndex(index);
+    }
+  });
+  return {
+    get activeIndex() {
+      return activeIndex;
+    },
+    setActiveIndex,
+    getItemProps
+  };
+}
+function clampIndex(index, itemCount) {
+  if (itemCount <= 0) return 0;
+  if (index < 0) return 0;
+  if (index >= itemCount) return itemCount - 1;
+  return index;
+}
 export {
+  createRovingTabIndex,
   focusFirst,
+  getFocusableElements,
+  getReducedMotionPreference,
   prefersReducedMotion,
+  shouldAnimate,
+  trapFocus,
   visuallyHiddenStyle
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/accessibility",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Accessibility utilities for LessonKit packages and apps.",
   "license": "Apache-2.0",