pulse-js-framework 1.10.0 → 1.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.10.0",
+  "version": "1.10.3",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "sideEffects": false,
@@ -149,6 +149,7 @@
   "scripts": {
     "test": "node scripts/run-all-tests.js",
     "test:compiler": "node test/compiler.test.js",
+    "test:parser-coverage": "node test/parser-coverage.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:css-parsing": "node test/css-parsing.test.js",
     "test:preprocessor": "node test/preprocessor.test.js",

package/runtime/a11y/announcements.js

@@ -0,0 +1,213 @@
+/**
+ * Pulse A11y - Screen Reader Announcements
+ *
+ * Live region announcements for screen readers
+ *
+ * @module pulse-js-framework/runtime/a11y/announcements
+ */
+
+import { pulse, effect } from '../pulse.js';
+
+// =============================================================================
+// LIVE REGIONS - Screen Reader Announcements
+// =============================================================================
+
+let liveRegionPolite = null;
+let liveRegionAssertive = null;
+
+/**
+ * Initialize live regions for screen reader announcements
+ * Called automatically on first announce
+ */
+function ensureLiveRegions() {
+  if (typeof document === 'undefined') return;
+
+  if (!liveRegionPolite) {
+    liveRegionPolite = document.createElement('div');
+    liveRegionPolite.setAttribute('role', 'status');
+    liveRegionPolite.setAttribute('aria-live', 'polite');
+    liveRegionPolite.setAttribute('aria-atomic', 'true');
+    Object.assign(liveRegionPolite.style, {
+      position: 'absolute',
+      width: '1px',
+      height: '1px',
+      padding: '0',
+      margin: '-1px',
+      overflow: 'hidden',
+      clip: 'rect(0, 0, 0, 0)',
+      whiteSpace: 'nowrap',
+      border: '0'
+    });
+    liveRegionPolite.id = 'pulse-a11y-polite';
+    document.body.appendChild(liveRegionPolite);
+  }
+
+  if (!liveRegionAssertive) {
+    liveRegionAssertive = document.createElement('div');
+    liveRegionAssertive.setAttribute('role', 'alert');
+    liveRegionAssertive.setAttribute('aria-live', 'assertive');
+    liveRegionAssertive.setAttribute('aria-atomic', 'true');
+    Object.assign(liveRegionAssertive.style, {
+      position: 'absolute',
+      width: '1px',
+      height: '1px',
+      padding: '0',
+      margin: '-1px',
+      overflow: 'hidden',
+      clip: 'rect(0, 0, 0, 0)',
+      whiteSpace: 'nowrap',
+      border: '0'
+    });
+    liveRegionAssertive.id = 'pulse-a11y-assertive';
+    document.body.appendChild(liveRegionAssertive);
+  }
+}
+
+/**
+ * Announce a message to screen readers
+ * @param {string} message - Message to announce
+ * @param {object} options - Options
+ * @param {'polite'|'assertive'} options.priority - Announcement priority (default: 'polite')
+ * @param {number} options.clearAfter - Clear message after ms (default: 1000)
+ */
+export function announce(message, options = {}) {
+  const { priority = 'polite', clearAfter = 1000 } = options;
+
+  ensureLiveRegions();
+
+  const region = priority === 'assertive' ? liveRegionAssertive : liveRegionPolite;
+  if (!region) return;
+
+  // Clear and set new message (needed for repeated announcements)
+  region.textContent = '';
+
+  // Use requestAnimationFrame to ensure the clear is processed
+  requestAnimationFrame(() => {
+    region.textContent = message;
+
+    if (clearAfter > 0) {
+      setTimeout(() => {
+        region.textContent = '';
+      }, clearAfter);
+    }
+  });
+}
+
+/**
+ * Announce politely (waits for user to finish current task)
+ * @param {string} message - Message to announce
+ */
+export function announcePolite(message) {
+  announce(message, { priority: 'polite' });
+}
+
+/**
+ * Announce assertively (interrupts current announcement)
+ * Use sparingly - only for critical updates
+ * @param {string} message - Message to announce
+ */
+export function announceAssertive(message) {
+  announce(message, { priority: 'assertive' });
+}
+
+/**
+ * Create a reactive live region that announces when value changes
+ * @param {Function} getter - Function that returns the message
+ * @param {object} options - Announce options
+ * @returns {Function} Cleanup function
+ */
+export function createLiveAnnouncer(getter, options = {}) {
+  let lastValue = null;
+
+  return effect(() => {
+    const value = getter();
+    if (value !== lastValue && value) {
+      announce(value, options);
+      lastValue = value;
+    }
+  });
+}
+// =============================================================================
+// ANNOUNCEMENT QUEUE
+// =============================================================================
+
+/**
+ * Create an announcement queue that handles multiple messages in sequence
+ * @param {object} options - Options
+ * @param {number} options.minDelay - Minimum delay between announcements (ms, default: 500)
+ * @returns {object} Queue control object
+ */
+export function createAnnouncementQueue(options = {}) {
+  const { minDelay = 500 } = options;
+
+  const queue = [];
+  let isProcessing = false;
+  let currentTimerId = null;
+  let aborted = false;
+  const queueLength = pulse(0);
+
+  const processQueue = async () => {
+    if (isProcessing || queue.length === 0 || aborted) return;
+
+    isProcessing = true;
+
+    while (queue.length > 0 && !aborted) {
+      const { message, priority, clearAfter } = queue.shift();
+      queueLength.set(queue.length);
+
+      announce(message, { priority, clearAfter });
+
+      // Wait for announcement to be read
+      await new Promise(resolve => {
+        currentTimerId = setTimeout(resolve,
+          Math.max(minDelay, clearAfter || 1000));
+      });
+      currentTimerId = null;
+    }
+
+    isProcessing = false;
+  };
+
+  const dispose = () => {
+    aborted = true;
+    if (currentTimerId !== null) {
+      clearTimeout(currentTimerId);
+      currentTimerId = null;
+    }
+    queue.length = 0;
+    queueLength.set(0);
+    isProcessing = false;
+  };
+
+  return {
+    queueLength,
+    /**
+     * Add a message to the queue
+     * @param {string} message - Message to announce
+     * @param {object} options - Announcement options (priority, clearAfter)
+     */
+    add: (message, opts = {}) => {
+      if (aborted) return;
+      queue.push({ message, ...opts });
+      queueLength.set(queue.length);
+      processQueue();
+    },
+    /**
+     * Clear the queue
+     */
+    clear: () => {
+      queue.length = 0;
+      queueLength.set(0);
+    },
+    /**
+     * Check if queue is being processed
+     * @returns {boolean}
+     */
+    isProcessing: () => isProcessing,
+    /**
+     * Dispose the queue, cancelling any pending timers
+     */
+    dispose
+  };
+}
+

package/runtime/a11y/contrast.js

@@ -0,0 +1,125 @@
+/**
+ * Pulse A11y - Color Contrast
+ *
+ * Color contrast calculation and WCAG compliance checking
+ *
+ * @module pulse-js-framework/runtime/a11y/contrast
+ */
+
+// =============================================================================
+// COLOR CONTRAST
+// =============================================================================
+
+/**
+ * Parse a color string to RGB values using canvas
+ * @param {string} color - CSS color string
+ * @returns {{r: number, g: number, b: number}|null}
+ */
+function parseColor(color) {
+  if (typeof document === 'undefined') return null;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = canvas.height = 1;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return null;
+
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+  return { r, g, b };
+}
+
+/**
+ * Calculate relative luminance of a color
+ * @param {{r: number, g: number, b: number}} color - RGB color
+ * @returns {number} Luminance between 0 and 1
+ */
+function relativeLuminance({ r, g, b }) {
+  const [rs, gs, bs] = [r, g, b].map(c => {
+    c = c / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+/**
+ * Calculate contrast ratio between two colors
+ * @param {string} foreground - Foreground color (any CSS color format)
+ * @param {string} background - Background color (any CSS color format)
+ * @returns {number} Contrast ratio (1 to 21)
+ */
+export function getContrastRatio(foreground, background) {
+  const fg = parseColor(foreground);
+  const bg = parseColor(background);
+
+  if (!fg || !bg) return 1;
+
+  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);
+}
+
+/**
+ * Check if contrast meets WCAG requirements
+ * @param {number} ratio - Contrast ratio
+ * @param {'AA'|'AAA'} level - WCAG level (default: 'AA')
+ * @param {'normal'|'large'} textSize - Text size category (default: 'normal')
+ * @returns {boolean}
+ */
+export function meetsContrastRequirement(ratio, level = 'AA', textSize = 'normal') {
+  const requirements = {
+    AA: { normal: 4.5, large: 3 },
+    AAA: { normal: 7, large: 4.5 }
+  };
+  return ratio >= (requirements[level]?.[textSize] ?? 4.5);
+}
+
+/**
+ * Get the effective background color of an element (handles transparency)
+ * @param {HTMLElement} element - Element to check
+ * @returns {string} Computed background color
+ */
+export function getEffectiveBackgroundColor(element) {
+  if (!element || typeof getComputedStyle === 'undefined') return 'rgb(255, 255, 255)';
+
+  let el = element;
+  while (el) {
+    const bg = getComputedStyle(el).backgroundColor;
+    // Check if background is not transparent
+    if (bg && bg !== 'transparent' && bg !== 'rgba(0, 0, 0, 0)') {
+      return bg;
+    }
+    el = el.parentElement;
+  }
+  return 'rgb(255, 255, 255)'; // Default to white
+}
+
+/**
+ * Check color contrast of text in an element
+ * @param {HTMLElement} element - Element to check
+ * @param {'AA'|'AAA'} level - WCAG level
+ * @returns {{ ratio: number, passes: boolean, foreground: string, background: string }}
+ */
+export function checkElementContrast(element, level = 'AA') {
+  if (!element || typeof getComputedStyle === 'undefined') {
+    return { ratio: 1, passes: false, foreground: '', background: '' };
+  }
+
+  const style = getComputedStyle(element);
+  const foreground = style.color;
+  const background = getEffectiveBackgroundColor(element);
+  const ratio = getContrastRatio(foreground, background);
+
+  // Determine if text is "large" (14pt bold or 18pt+)
+  const fontSize = parseFloat(style.fontSize);
+  const fontWeight = parseInt(style.fontWeight, 10) || 400;
+  const isLarge = fontSize >= 24 || (fontSize >= 18.66 && fontWeight >= 700);
+
+  const passes = meetsContrastRequirement(ratio, level, isLarge ? 'large' : 'normal');
+
+  return { ratio, passes, foreground, background };
+}