@gtcx/accessibility 0.1.0

package/dist/index.js

@@ -0,0 +1,329 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LITERACY_UI_CONFIGS: () => LITERACY_UI_CONFIGS,
+  TechLiteracyDetector: () => TechLiteracyDetector,
+  contrastRatio: () => contrastRatio,
+  detectTechLiteracy: () => detectTechLiteracy,
+  meetsWCAG: () => meetsWCAG,
+  relativeLuminance: () => relativeLuminance,
+  useAnnounce: () => useAnnounce,
+  useFocusTrap: () => useFocusTrap,
+  useReducedMotion: () => useReducedMotion
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tech-literacy.ts
+async function detectTechLiteracy(interactions) {
+  if (interactions.length < 3) {
+    return {
+      level: "beginner",
+      confidence: 0.3,
+      signals: ["insufficient_data"]
+    };
+  }
+  const signals = [];
+  let score = 50;
+  const avgActionTime = average(interactions.map((i) => i.actionTime));
+  const totalErrors = sum(interactions.map((i) => i.errorCount));
+  const shortcutUsage = interactions.filter((i) => i.usedShortcuts).length;
+  const helpRequests = interactions.filter((i) => i.requestedHelp).length;
+  const voiceUsage = interactions.filter((i) => i.usedVoice).length;
+  if (avgActionTime < 2e3) {
+    score += 15;
+    signals.push("fast_completion");
+  } else if (avgActionTime > 8e3) {
+    score -= 15;
+    signals.push("slow_completion");
+  }
+  if (totalErrors > interactions.length * 2) {
+    score -= 20;
+    signals.push("high_error_rate");
+  } else if (totalErrors === 0) {
+    score += 10;
+    signals.push("no_errors");
+  }
+  if (shortcutUsage > interactions.length * 0.3) {
+    score += 25;
+    signals.push("keyboard_shortcuts");
+  }
+  if (helpRequests > interactions.length * 0.3) {
+    score -= 15;
+    signals.push("frequent_help_requests");
+  }
+  if (voiceUsage > 0) {
+    signals.push("voice_user");
+  }
+  let level;
+  if (score >= 70) {
+    level = "advanced";
+  } else if (score >= 40) {
+    level = "intermediate";
+  } else {
+    level = "beginner";
+  }
+  const confidence = Math.min(0.95, 0.5 + interactions.length * 0.05);
+  return { level, confidence, signals };
+}
+var TechLiteracyDetector = class {
+  interactions = [];
+  currentLevel = "beginner";
+  onLevelChange;
+  constructor(options) {
+    this.currentLevel = options?.initialLevel || "beginner";
+    this.onLevelChange = options?.onLevelChange;
+  }
+  /**
+   * Record an interaction for analysis
+   */
+  recordInteraction(pattern) {
+    this.interactions.push({
+      ...pattern,
+      timestamp: Date.now()
+    });
+    if (this.interactions.length > 50) {
+      this.interactions = this.interactions.slice(-50);
+    }
+    if (this.interactions.length % 5 === 0) {
+      this.evaluate();
+    }
+  }
+  /**
+   * Evaluate current literacy level
+   */
+  async evaluate() {
+    const result = await detectTechLiteracy(this.interactions);
+    if (result.level !== this.currentLevel && result.confidence > 0.7) {
+      this.currentLevel = result.level;
+      this.onLevelChange?.(result.level);
+    }
+    return result;
+  }
+  /**
+   * Get current assessed level
+   */
+  getLevel() {
+    return this.currentLevel;
+  }
+  /**
+   * Manually set level (user preference)
+   */
+  setLevel(level) {
+    this.currentLevel = level;
+    this.onLevelChange?.(level);
+  }
+};
+var LITERACY_UI_CONFIGS = {
+  beginner: {
+    buttonSize: "large",
+    // min 48px touch target
+    fontSize: "large",
+    // 18px+
+    navigation: "simple",
+    // Linear, no nested menus
+    icons: "labeled",
+    // Always show text with icons
+    animations: "minimal",
+    // Reduce motion
+    guidance: "proactive",
+    // Show help automatically
+    inputMode: "touch",
+    // Optimize for touch
+    errorHandling: "guided",
+    // Step-by-step error recovery
+    confirmations: "explicit",
+    // Confirm all actions
+    shortcuts: "hidden"
+    // Don't show keyboard shortcuts
+  },
+  intermediate: {
+    buttonSize: "medium",
+    fontSize: "medium",
+    // 16px
+    navigation: "standard",
+    // Some nesting allowed
+    icons: "tooltips",
+    // Show text on hover
+    animations: "standard",
+    guidance: "contextual",
+    // Show help when hovering
+    inputMode: "mixed",
+    // Touch + keyboard
+    errorHandling: "inline",
+    // Inline error messages
+    confirmations: "smart",
+    // Confirm destructive only
+    shortcuts: "discoverable"
+    // Show shortcuts in tooltips
+  },
+  advanced: {
+    buttonSize: "compact",
+    fontSize: "small",
+    // 14px
+    navigation: "full",
+    // All features accessible
+    icons: "minimal",
+    // Icons only, no labels
+    animations: "full",
+    guidance: "on-demand",
+    // Help only when requested
+    inputMode: "keyboard",
+    // Keyboard-first
+    errorHandling: "technical",
+    // Technical error details
+    confirmations: "minimal",
+    // Skip most confirmations
+    shortcuts: "prominent"
+    // Show all shortcuts
+  }
+};
+function average(arr) {
+  return arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+}
+function sum(arr) {
+  return arr.reduce((a, b) => a + b, 0);
+}
+
+// src/contrast.ts
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  const full = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
+  return [
+    parseInt(full.slice(0, 2), 16),
+    parseInt(full.slice(2, 4), 16),
+    parseInt(full.slice(4, 6), 16)
+  ];
+}
+function srgbToLinear(channel) {
+  const s = channel / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+}
+function contrastRatio(fg, bg) {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function meetsWCAG(fg, bg, level = "AA", large = false) {
+  const ratio = contrastRatio(fg, bg);
+  if (level === "AAA") return large ? ratio >= 4.5 : ratio >= 7;
+  return large ? ratio >= 3 : ratio >= 4.5;
+}
+
+// src/use-reduced-motion.ts
+var import_react = require("react");
+var QUERY = "(prefers-reduced-motion: reduce)";
+function useReducedMotion() {
+  const [reduced, setReduced] = (0, import_react.useState)(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(QUERY).matches;
+  });
+  (0, import_react.useEffect)(() => {
+    const mql = window.matchMedia(QUERY);
+    const handler = (e) => setReduced(e.matches);
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }, []);
+  return reduced;
+}
+
+// src/use-focus-trap.ts
+var import_react2 = require("react");
+var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+function useFocusTrap(active) {
+  const ref = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    if (!active || !ref.current) return;
+    const container = ref.current;
+    const previouslyFocused = document.activeElement;
+    const first = container.querySelector(FOCUSABLE);
+    first?.focus();
+    function handleKeyDown(e) {
+      if (e.key !== "Tab") return;
+      const focusable = container.querySelectorAll(FOCUSABLE);
+      if (focusable.length === 0) return;
+      const firstEl = focusable[0];
+      const lastEl = focusable[focusable.length - 1];
+      if (e.shiftKey && document.activeElement === firstEl) {
+        e.preventDefault();
+        lastEl.focus();
+      } else if (!e.shiftKey && document.activeElement === lastEl) {
+        e.preventDefault();
+        firstEl.focus();
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      previouslyFocused?.focus();
+    };
+  }, [active]);
+  return ref;
+}
+
+// src/use-announce.ts
+var import_react3 = require("react");
+function useAnnounce(politeness = "polite") {
+  const ref = (0, import_react3.useRef)(null);
+  const announce = (0, import_react3.useCallback)((message) => {
+    if (!ref.current) return;
+    ref.current.textContent = "";
+    requestAnimationFrame(() => {
+      if (ref.current) ref.current.textContent = message;
+    });
+  }, []);
+  const liveRegionProps = {
+    ref,
+    role: "status",
+    "aria-live": politeness,
+    "aria-atomic": true,
+    style: {
+      position: "absolute",
+      width: 1,
+      height: 1,
+      padding: 0,
+      margin: -1,
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: 0
+    }
+  };
+  return { announce, liveRegionProps };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LITERACY_UI_CONFIGS,
+  TechLiteracyDetector,
+  contrastRatio,
+  detectTechLiteracy,
+  meetsWCAG,
+  relativeLuminance,
+  useAnnounce,
+  useFocusTrap,
+  useReducedMotion
+});

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,iDAIyB;AAHvB,qHAAA,oBAAoB,OAAA;AACpB,mHAAA,kBAAkB,OAAA;AAClB,oHAAA,mBAAmB,OAAA;AAOrB,oCAAoC;AACpC,oDAAoD;AACpD,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,gDAAgD;AAChD,oDAAoD;AACpD,yDAAyD;AACzD,gEAAgE;AAChE,+CAA+C"}

package/dist/index.mjs

@@ -0,0 +1,294 @@
+// src/tech-literacy.ts
+async function detectTechLiteracy(interactions) {
+  if (interactions.length < 3) {
+    return {
+      level: "beginner",
+      confidence: 0.3,
+      signals: ["insufficient_data"]
+    };
+  }
+  const signals = [];
+  let score = 50;
+  const avgActionTime = average(interactions.map((i) => i.actionTime));
+  const totalErrors = sum(interactions.map((i) => i.errorCount));
+  const shortcutUsage = interactions.filter((i) => i.usedShortcuts).length;
+  const helpRequests = interactions.filter((i) => i.requestedHelp).length;
+  const voiceUsage = interactions.filter((i) => i.usedVoice).length;
+  if (avgActionTime < 2e3) {
+    score += 15;
+    signals.push("fast_completion");
+  } else if (avgActionTime > 8e3) {
+    score -= 15;
+    signals.push("slow_completion");
+  }
+  if (totalErrors > interactions.length * 2) {
+    score -= 20;
+    signals.push("high_error_rate");
+  } else if (totalErrors === 0) {
+    score += 10;
+    signals.push("no_errors");
+  }
+  if (shortcutUsage > interactions.length * 0.3) {
+    score += 25;
+    signals.push("keyboard_shortcuts");
+  }
+  if (helpRequests > interactions.length * 0.3) {
+    score -= 15;
+    signals.push("frequent_help_requests");
+  }
+  if (voiceUsage > 0) {
+    signals.push("voice_user");
+  }
+  let level;
+  if (score >= 70) {
+    level = "advanced";
+  } else if (score >= 40) {
+    level = "intermediate";
+  } else {
+    level = "beginner";
+  }
+  const confidence = Math.min(0.95, 0.5 + interactions.length * 0.05);
+  return { level, confidence, signals };
+}
+var TechLiteracyDetector = class {
+  interactions = [];
+  currentLevel = "beginner";
+  onLevelChange;
+  constructor(options) {
+    this.currentLevel = options?.initialLevel || "beginner";
+    this.onLevelChange = options?.onLevelChange;
+  }
+  /**
+   * Record an interaction for analysis
+   */
+  recordInteraction(pattern) {
+    this.interactions.push({
+      ...pattern,
+      timestamp: Date.now()
+    });
+    if (this.interactions.length > 50) {
+      this.interactions = this.interactions.slice(-50);
+    }
+    if (this.interactions.length % 5 === 0) {
+      this.evaluate();
+    }
+  }
+  /**
+   * Evaluate current literacy level
+   */
+  async evaluate() {
+    const result = await detectTechLiteracy(this.interactions);
+    if (result.level !== this.currentLevel && result.confidence > 0.7) {
+      this.currentLevel = result.level;
+      this.onLevelChange?.(result.level);
+    }
+    return result;
+  }
+  /**
+   * Get current assessed level
+   */
+  getLevel() {
+    return this.currentLevel;
+  }
+  /**
+   * Manually set level (user preference)
+   */
+  setLevel(level) {
+    this.currentLevel = level;
+    this.onLevelChange?.(level);
+  }
+};
+var LITERACY_UI_CONFIGS = {
+  beginner: {
+    buttonSize: "large",
+    // min 48px touch target
+    fontSize: "large",
+    // 18px+
+    navigation: "simple",
+    // Linear, no nested menus
+    icons: "labeled",
+    // Always show text with icons
+    animations: "minimal",
+    // Reduce motion
+    guidance: "proactive",
+    // Show help automatically
+    inputMode: "touch",
+    // Optimize for touch
+    errorHandling: "guided",
+    // Step-by-step error recovery
+    confirmations: "explicit",
+    // Confirm all actions
+    shortcuts: "hidden"
+    // Don't show keyboard shortcuts
+  },
+  intermediate: {
+    buttonSize: "medium",
+    fontSize: "medium",
+    // 16px
+    navigation: "standard",
+    // Some nesting allowed
+    icons: "tooltips",
+    // Show text on hover
+    animations: "standard",
+    guidance: "contextual",
+    // Show help when hovering
+    inputMode: "mixed",
+    // Touch + keyboard
+    errorHandling: "inline",
+    // Inline error messages
+    confirmations: "smart",
+    // Confirm destructive only
+    shortcuts: "discoverable"
+    // Show shortcuts in tooltips
+  },
+  advanced: {
+    buttonSize: "compact",
+    fontSize: "small",
+    // 14px
+    navigation: "full",
+    // All features accessible
+    icons: "minimal",
+    // Icons only, no labels
+    animations: "full",
+    guidance: "on-demand",
+    // Help only when requested
+    inputMode: "keyboard",
+    // Keyboard-first
+    errorHandling: "technical",
+    // Technical error details
+    confirmations: "minimal",
+    // Skip most confirmations
+    shortcuts: "prominent"
+    // Show all shortcuts
+  }
+};
+function average(arr) {
+  return arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+}
+function sum(arr) {
+  return arr.reduce((a, b) => a + b, 0);
+}
+
+// src/contrast.ts
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  const full = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
+  return [
+    parseInt(full.slice(0, 2), 16),
+    parseInt(full.slice(2, 4), 16),
+    parseInt(full.slice(4, 6), 16)
+  ];
+}
+function srgbToLinear(channel) {
+  const s = channel / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+}
+function contrastRatio(fg, bg) {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function meetsWCAG(fg, bg, level = "AA", large = false) {
+  const ratio = contrastRatio(fg, bg);
+  if (level === "AAA") return large ? ratio >= 4.5 : ratio >= 7;
+  return large ? ratio >= 3 : ratio >= 4.5;
+}
+
+// src/use-reduced-motion.ts
+import { useState, useEffect } from "react";
+var QUERY = "(prefers-reduced-motion: reduce)";
+function useReducedMotion() {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(QUERY).matches;
+  });
+  useEffect(() => {
+    const mql = window.matchMedia(QUERY);
+    const handler = (e) => setReduced(e.matches);
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }, []);
+  return reduced;
+}
+
+// src/use-focus-trap.ts
+import { useRef, useEffect as useEffect2 } from "react";
+var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+function useFocusTrap(active) {
+  const ref = useRef(null);
+  useEffect2(() => {
+    if (!active || !ref.current) return;
+    const container = ref.current;
+    const previouslyFocused = document.activeElement;
+    const first = container.querySelector(FOCUSABLE);
+    first?.focus();
+    function handleKeyDown(e) {
+      if (e.key !== "Tab") return;
+      const focusable = container.querySelectorAll(FOCUSABLE);
+      if (focusable.length === 0) return;
+      const firstEl = focusable[0];
+      const lastEl = focusable[focusable.length - 1];
+      if (e.shiftKey && document.activeElement === firstEl) {
+        e.preventDefault();
+        lastEl.focus();
+      } else if (!e.shiftKey && document.activeElement === lastEl) {
+        e.preventDefault();
+        firstEl.focus();
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      previouslyFocused?.focus();
+    };
+  }, [active]);
+  return ref;
+}
+
+// src/use-announce.ts
+import { useRef as useRef2, useCallback } from "react";
+function useAnnounce(politeness = "polite") {
+  const ref = useRef2(null);
+  const announce = useCallback((message) => {
+    if (!ref.current) return;
+    ref.current.textContent = "";
+    requestAnimationFrame(() => {
+      if (ref.current) ref.current.textContent = message;
+    });
+  }, []);
+  const liveRegionProps = {
+    ref,
+    role: "status",
+    "aria-live": politeness,
+    "aria-atomic": true,
+    style: {
+      position: "absolute",
+      width: 1,
+      height: 1,
+      padding: 0,
+      margin: -1,
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: 0
+    }
+  };
+  return { announce, liveRegionProps };
+}
+export {
+  LITERACY_UI_CONFIGS,
+  TechLiteracyDetector,
+  contrastRatio,
+  detectTechLiteracy,
+  meetsWCAG,
+  relativeLuminance,
+  useAnnounce,
+  useFocusTrap,
+  useReducedMotion
+};