pulse-js-framework 1.7.33 → 1.7.38

package/types/a11y.d.ts

@@ -91,6 +91,24 @@ export function restoreFocus(): void;
  */
 export function clearFocusStack(): void;
 
+/**
+ * Handle escape key press within a container
+ * @returns Cleanup function to remove listener
+ */
+export function onEscapeKey(
+  container: HTMLElement,
+  onEscape: () => void,
+  options?: { stopPropagation?: boolean }
+): () => void;
+
+/**
+ * Track keyboard vs mouse focus for :focus-visible styling
+ */
+export function createFocusVisibleTracker(): {
+  isKeyboardUser: Pulse<boolean>;
+  cleanup: () => void;
+};
+
 // =============================================================================
 // SKIP LINKS
 // =============================================================================
@@ -138,10 +156,28 @@ export function prefersColorScheme(): 'light' | 'dark' | 'no-preference';
  */
 export function prefersHighContrast(): boolean;
 
+/**
+ * Check if user prefers reduced transparency
+ */
+export function prefersReducedTransparency(): boolean;
+
+/**
+ * Check if forced colors mode is active (Windows High Contrast Mode)
+ */
+export function forcedColorsMode(): 'active' | 'none';
+
+/**
+ * Check user's preferred contrast level
+ */
+export function prefersContrast(): 'no-preference' | 'more' | 'less' | 'custom';
+
 export interface UserPreferences {
   reducedMotion: Pulse<boolean>;
   colorScheme: Pulse<'light' | 'dark' | 'no-preference'>;
   highContrast: Pulse<boolean>;
+  reducedTransparency?: Pulse<boolean>;
+  forcedColors?: Pulse<'active' | 'none'>;
+  contrast?: Pulse<'no-preference' | 'more' | 'less' | 'custom'>;
 }
 
 /**
@@ -209,6 +245,96 @@ export function createTabs(
   options?: TabsOptions
 ): TabsControl;
 
+// =============================================================================
+// ARIA WIDGETS
+// =============================================================================
+
+export interface ModalOptions {
+  labelledBy?: string;
+  describedBy?: string;
+  closeOnBackdropClick?: boolean;
+  onClose?: () => void;
+}
+
+export interface ModalControl {
+  open: () => void;
+  close: () => void;
+  isOpen: Pulse<boolean>;
+}
+
+/**
+ * Create an ARIA-compliant modal dialog
+ */
+export function createModal(
+  dialog: HTMLElement,
+  options?: ModalOptions
+): ModalControl;
+
+export interface TooltipOptions {
+  showDelay?: number;
+  hideDelay?: number;
+}
+
+export interface TooltipControl {
+  isVisible: Pulse<boolean>;
+  cleanup: () => void;
+}
+
+/**
+ * Create an ARIA-compliant tooltip
+ */
+export function createTooltip(
+  trigger: HTMLElement,
+  tooltip: HTMLElement,
+  options?: TooltipOptions
+): TooltipControl;
+
+export interface AccordionOptions {
+  triggerSelector?: string;
+  panelSelector?: string;
+  allowMultiple?: boolean;
+  defaultOpen?: number;
+}
+
+export interface AccordionControl {
+  open: (index: number) => void;
+  close: (index: number) => void;
+  toggle: (index: number) => void;
+  closeAll: () => void;
+  openIndices: Pulse<number[]>;
+  cleanup: () => void;
+}
+
+/**
+ * Create an ARIA-compliant accordion
+ */
+export function createAccordion(
+  container: HTMLElement,
+  options?: AccordionOptions
+): AccordionControl;
+
+export interface MenuOptions {
+  itemSelector?: string;
+  closeOnSelect?: boolean;
+  onSelect?: (element: HTMLElement, index: number) => void;
+}
+
+export interface MenuControl {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  cleanup: () => void;
+}
+
+/**
+ * Create an ARIA-compliant dropdown menu
+ */
+export function createMenu(
+  button: HTMLElement,
+  menu: HTMLElement,
+  options?: MenuOptions
+): MenuControl;
+
 // =============================================================================
 // KEYBOARD NAVIGATION
 // =============================================================================
@@ -260,6 +386,61 @@ export function logA11yIssues(issues: A11yIssue[]): void;
  */
 export function highlightA11yIssues(issues: A11yIssue[]): () => void;
 
+// =============================================================================
+// COLOR CONTRAST
+// =============================================================================
+
+/**
+ * Calculate WCAG contrast ratio between two colors
+ */
+export function getContrastRatio(foreground: string, background: string): number;
+
+/**
+ * Check if a contrast ratio meets WCAG requirements
+ */
+export function meetsContrastRequirement(
+  ratio: number,
+  level?: 'AA' | 'AAA',
+  textSize?: 'normal' | 'large'
+): boolean;
+
+/**
+ * Get the effective background color of an element (handles transparency)
+ */
+export function getEffectiveBackgroundColor(element: HTMLElement): string;
+
+/**
+ * Check contrast of a specific element
+ */
+export function checkElementContrast(
+  element: HTMLElement,
+  level?: 'AA' | 'AAA'
+): {
+  ratio: number;
+  passes: boolean;
+  foreground: string;
+  background: string;
+};
+
+// =============================================================================
+// ANNOUNCEMENT QUEUE
+// =============================================================================
+
+export interface AnnouncementQueueOptions {
+  minDelay?: number;
+}
+
+export interface AnnouncementQueue {
+  add: (message: string, options?: { priority?: 'polite' | 'assertive' }) => void;
+  clear: () => void;
+  queueLength: Pulse<number>;
+}
+
+/**
+ * Create a queue for managing multiple announcements
+ */
+export function createAnnouncementQueue(options?: AnnouncementQueueOptions): AnnouncementQueue;
+
 // =============================================================================
 // UTILITIES
 // =============================================================================
@@ -285,6 +466,11 @@ export function makeInert(element: HTMLElement): () => void;
  */
 export function srOnly(text: string): HTMLSpanElement;
 
+/**
+ * Compute the accessible name of an element (aria-label, text content, etc.)
+ */
+export function getAccessibleName(element: HTMLElement): string;
+
 // =============================================================================
 // DEFAULT EXPORT
 // =============================================================================

package/types/devtools.d.ts

@@ -0,0 +1,418 @@
+/**
+ * Pulse Framework - DevTools Type Definitions
+ * @module pulse-js-framework/runtime/devtools
+ */
+
+import { Pulse } from './pulse';
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+/** DevTools configuration options */
+export interface DevToolsOptions {
+  /** Enable dev tools (default: false) */
+  enabled?: boolean;
+  /** Enable automatic timeline recording (default: false) */
+  autoTimeline?: boolean;
+  /** Debounce interval for auto-timeline in ms (default: 100) */
+  timelineDebounce?: number;
+  /** Maximum number of state snapshots to retain (default: 50) */
+  maxSnapshots?: number;
+  /** Log pulse updates to console (default: false) */
+  logUpdates?: boolean;
+  /** Warn when effects take longer than one frame (default: true) */
+  warnOnSlowEffects?: boolean;
+}
+
+// =============================================================================
+// DIAGNOSTICS
+// =============================================================================
+
+/** Diagnostics summary of the reactive system */
+export interface Diagnostics {
+  /** Number of tracked pulses */
+  pulseCount: number;
+  /** Number of tracked effects */
+  effectCount: number;
+  /** Average effect execution time in ms */
+  avgEffectTime: number;
+  /** Number of state snapshots in history */
+  snapshotCount: number;
+  /** Additional diagnostic properties */
+  [key: string]: unknown;
+}
+
+/** Performance statistics for a tracked effect */
+export interface EffectStat {
+  /** Unique identifier of the effect */
+  id: string;
+  /** Display name of the effect */
+  name: string;
+  /** Number of times the effect has run */
+  runCount: number;
+  /** Average execution time in ms */
+  avgTime: number;
+}
+
+/** Information about a tracked pulse */
+export interface PulseInfo {
+  /** Unique identifier of the pulse */
+  id: string;
+  /** Display name of the pulse */
+  name: string;
+  /** Current value of the pulse */
+  value: unknown;
+  /** Number of active subscribers */
+  subscriberCount: number;
+}
+
+/** Reactive dependency graph structure */
+export interface DependencyGraph {
+  /** Nodes representing pulses and effects */
+  nodes: Array<{ id: string; type: string; name?: string }>;
+  /** Edges representing dependencies between nodes */
+  edges: Array<{ from: string; to: string }>;
+}
+
+/**
+ * Get diagnostics summary of the reactive system
+ */
+export declare function getDiagnostics(): Diagnostics;
+
+/**
+ * Get performance statistics for all tracked effects
+ */
+export declare function getEffectStats(): EffectStat[];
+
+/**
+ * Get information about all tracked pulses
+ */
+export declare function getPulseList(): PulseInfo[];
+
+/**
+ * Get the reactive dependency graph
+ */
+export declare function getDependencyGraph(): DependencyGraph;
+
+/**
+ * Export the dependency graph as a Graphviz DOT string
+ */
+export declare function exportGraphAsDot(): string;
+
+/**
+ * Create a tracked pulse with automatic snapshot on change.
+ * Integrates with time-travel debugging.
+ *
+ * @param initialValue - Initial value for the pulse
+ * @param name - Display name for debugging
+ * @returns A tracked pulse instance
+ */
+export declare function trackedPulse<T>(initialValue: T, name?: string): Pulse<T>;
+
+/**
+ * Create a tracked effect with performance monitoring.
+ * Execution time and run count are recorded.
+ *
+ * @param fn - Effect function (may return a cleanup function)
+ * @param name - Display name for debugging
+ * @returns Dispose function to stop the effect
+ */
+export declare function trackedEffect(fn: () => void | (() => void), name?: string): () => void;
+
+// =============================================================================
+// PROFILING
+// =============================================================================
+
+/** Result of a profiled operation */
+export interface ProfileResult {
+  /** Name of the profiled operation */
+  name: string;
+  /** Duration in ms */
+  duration: number;
+  /** Return value of the profiled function */
+  result: unknown;
+}
+
+/** Handle returned by mark() to end a timing measurement */
+export interface MarkResult {
+  /** End the mark and return duration in ms */
+  end(): number;
+}
+
+/**
+ * Profile a synchronous function, logging its execution time
+ *
+ * @param name - Name for the profiling entry
+ * @param fn - Function to profile
+ * @returns Profile result with duration and return value
+ */
+export declare function profile<T>(name: string, fn: () => T): ProfileResult;
+
+/**
+ * Start a timing mark for manual profiling
+ *
+ * @param name - Name for the mark
+ * @returns A mark handle with an end() method
+ */
+export declare function mark(name: string): MarkResult;
+
+// =============================================================================
+// TIME-TRAVEL
+// =============================================================================
+
+/** A state snapshot for time-travel debugging */
+export interface Snapshot {
+  /** Description of the action that triggered this snapshot */
+  label: string;
+  /** Unix timestamp in ms when the snapshot was taken */
+  timestamp: number;
+  /** Serialized state of all tracked pulses */
+  state: Record<string, unknown>;
+}
+
+/**
+ * Take a snapshot of the current state of all tracked pulses
+ *
+ * @param label - Description of the action (default: 'manual')
+ */
+export declare function takeSnapshot(label?: string): void;
+
+/**
+ * Get all state snapshots in the history
+ */
+export declare function getHistory(): Snapshot[];
+
+/**
+ * Get the current position in history
+ */
+export declare function getHistoryIndex(): number;
+
+/**
+ * Restore state to a specific snapshot index
+ *
+ * @param index - History index to travel to
+ */
+export declare function travelTo(index: number): void;
+
+/**
+ * Go back one step in history
+ */
+export declare function back(): void;
+
+/**
+ * Go forward one step in history
+ */
+export declare function forward(): void;
+
+/**
+ * Clear all snapshots from history
+ */
+export declare function clearHistory(): void;
+
+// =============================================================================
+// AUTO-TIMELINE
+// =============================================================================
+
+/**
+ * Enable automatic timeline recording.
+ * Records all pulse changes to the timeline with debouncing.
+ *
+ * @param options - Configuration options
+ */
+export declare function enableAutoTimeline(options?: { debounce?: number }): void;
+
+/**
+ * Disable automatic timeline recording
+ */
+export declare function disableAutoTimeline(): void;
+
+/**
+ * Check if auto-timeline recording is enabled
+ */
+export declare function isAutoTimelineEnabled(): boolean;
+
+// =============================================================================
+// CONFIGURATION API
+// =============================================================================
+
+/**
+ * Enable dev tools and expose to window.__PULSE_DEVTOOLS__
+ *
+ * @param options - Configuration options
+ */
+export declare function enableDevTools(options?: DevToolsOptions): void;
+
+/**
+ * Disable dev tools and remove window.__PULSE_DEVTOOLS__
+ */
+export declare function disableDevTools(): void;
+
+/**
+ * Check if dev tools are enabled
+ */
+export declare function isDevToolsEnabled(): boolean;
+
+/**
+ * Update dev tools configuration
+ *
+ * @param options - Configuration options to merge
+ */
+export declare function configureDevTools(options: DevToolsOptions): void;
+
+/**
+ * Reset all dev tools data (diagnostics, history, and a11y audit)
+ */
+export declare function resetDevTools(): void;
+
+// =============================================================================
+// A11Y AUDIT
+// =============================================================================
+
+/** An accessibility issue found during audit */
+export interface A11yIssue {
+  /** Type/rule of the issue (e.g., 'missing-alt', 'no-label') */
+  type: string;
+  /** Human-readable description of the issue */
+  message: string;
+  /** The DOM element with the issue (if available) */
+  element?: Element;
+  /** Severity level */
+  severity: 'error' | 'warning' | 'info';
+}
+
+/** Summary statistics from an a11y audit */
+export interface A11yStats {
+  /** Total number of issues found */
+  totalIssues: number;
+  /** Number of error-level issues */
+  errorCount: number;
+  /** Number of warning-level issues */
+  warningCount: number;
+  /** Number of info-level issues */
+  infoCount: number;
+}
+
+/** Configuration options for continuous a11y auditing */
+export interface A11yAuditOptions {
+  /** Enable periodic audits (default: false) */
+  autoAudit?: boolean;
+  /** Interval between audits in ms (default: 5000) */
+  auditInterval?: number;
+  /** Show visual overlay on elements with issues (default: true) */
+  highlightIssues?: boolean;
+  /** Log issues to browser console (default: true) */
+  logToConsole?: boolean;
+  /** Trigger debugger breakpoint on errors (default: false) */
+  breakOnError?: boolean;
+  /** Re-audit when DOM changes via MutationObserver (default: false) */
+  watchMutations?: boolean;
+}
+
+/** Result returned by runA11yAudit() */
+export interface A11yAuditResult {
+  /** List of accessibility issues found */
+  issues: A11yIssue[];
+  /** Number of error-level issues */
+  errorCount: number;
+  /** Number of warning-level issues */
+  warningCount: number;
+}
+
+/**
+ * Run an accessibility audit on the document or specific element
+ */
+export declare function runA11yAudit(): A11yAuditResult;
+
+/**
+ * Get all current a11y issues from the last audit
+ */
+export declare function getA11yIssues(): A11yIssue[];
+
+/**
+ * Get summary statistics of a11y issues
+ */
+export declare function getA11yStats(): A11yStats;
+
+/**
+ * Enable continuous a11y auditing with optional configuration
+ *
+ * @param options - Audit configuration options
+ */
+export declare function enableA11yAudit(options?: A11yAuditOptions): void;
+
+/**
+ * Disable continuous a11y auditing and clean up resources
+ */
+export declare function disableA11yAudit(): void;
+
+/**
+ * Toggle visual highlighting of a11y issues in the DOM
+ *
+ * @param show - Force show/hide, or toggle if omitted
+ */
+export declare function toggleA11yHighlights(show?: boolean): void;
+
+/**
+ * Export the a11y audit report in the specified format
+ *
+ * @param format - Output format
+ * @returns Formatted report string
+ */
+export declare function exportA11yReport(format: 'json' | 'csv' | 'html'): string;
+
+/**
+ * Reset a11y audit state (clear issues, stop observers)
+ */
+export declare function resetA11yAudit(): void;
+
+// =============================================================================
+// DEFAULT EXPORT
+// =============================================================================
+
+export interface PulseDevTools {
+  // Diagnostics
+  getDiagnostics: typeof getDiagnostics;
+  getEffectStats: typeof getEffectStats;
+  getPulseList: typeof getPulseList;
+  getDependencyGraph: typeof getDependencyGraph;
+  exportGraphAsDot: typeof exportGraphAsDot;
+  trackedPulse: typeof trackedPulse;
+  trackedEffect: typeof trackedEffect;
+  profile: typeof profile;
+  mark: typeof mark;
+
+  // Time-travel
+  takeSnapshot: typeof takeSnapshot;
+  getHistory: typeof getHistory;
+  getHistoryIndex: typeof getHistoryIndex;
+  travelTo: typeof travelTo;
+  back: typeof back;
+  forward: typeof forward;
+  clearHistory: typeof clearHistory;
+
+  // Auto-timeline
+  enableAutoTimeline: typeof enableAutoTimeline;
+  disableAutoTimeline: typeof disableAutoTimeline;
+  isAutoTimelineEnabled: typeof isAutoTimelineEnabled;
+
+  // Configuration
+  enableDevTools: typeof enableDevTools;
+  disableDevTools: typeof disableDevTools;
+  isDevToolsEnabled: typeof isDevToolsEnabled;
+  configureDevTools: typeof configureDevTools;
+  resetDevTools: typeof resetDevTools;
+
+  // Accessibility Audit
+  runA11yAudit: typeof runA11yAudit;
+  getA11yIssues: typeof getA11yIssues;
+  getA11yStats: typeof getA11yStats;
+  enableA11yAudit: typeof enableA11yAudit;
+  disableA11yAudit: typeof disableA11yAudit;
+  toggleA11yHighlights: typeof toggleA11yHighlights;
+  exportA11yReport: typeof exportA11yReport;
+  resetA11yAudit: typeof resetA11yAudit;
+}
+
+declare const _default: PulseDevTools;
+export default _default;