pulse-js-framework 1.7.32 → 1.7.37

package/loader/webpack-loader.js

@@ -0,0 +1,228 @@
+/**
+ * Pulse Webpack Loader
+ *
+ * Enables .pulse file support in Webpack projects
+ * Extracts CSS and compiles to JavaScript with source maps
+ *
+ * CSS Preprocessor Support:
+ * - If `sass`, `less`, or `stylus` is installed in the user's project,
+ *   preprocessor syntax in style blocks is automatically compiled
+ * - No configuration needed - just install the preprocessor package
+ *
+ * Usage in webpack.config.js:
+ * ```js
+ * module.exports = {
+ *   module: {
+ *     rules: [
+ *       {
+ *         test: /\.pulse$/,
+ *         use: [
+ *           'style-loader',  // or mini-css-extract-plugin
+ *           'css-loader',
+ *           'pulse-js-framework/loader/webpack-loader'
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * };
+ * ```
+ */
+
+import { compile } from '../compiler/index.js';
+import {
+  preprocessStylesSync,
+  isSassAvailable,
+  isLessAvailable,
+  isStylusAvailable,
+  getSassVersion,
+  getLessVersion,
+  getStylusVersion,
+  detectPreprocessor
+} from '../compiler/preprocessor.js';
+import { dirname } from 'path';
+
+// Cache for preprocessor availability checks
+let preprocessorCache = null;
+
+/**
+ * Check available preprocessors once
+ */
+function checkPreprocessors() {
+  if (preprocessorCache) return preprocessorCache;
+
+  preprocessorCache = {
+    sass: isSassAvailable(),
+    less: isLessAvailable(),
+    stylus: isStylusAvailable()
+  };
+
+  return preprocessorCache;
+}
+
+/**
+ * Webpack loader for .pulse files
+ * @this {import('webpack').LoaderContext}
+ */
+export default function pulseLoader(source) {
+  const callback = this.async();
+  const options = this.getOptions() || {};
+
+  const {
+    sourceMap = true,
+    sass: sassOptions = {},
+    less: lessOptions = {},
+    stylus: stylusOptions = {}
+  } = options;
+
+  // Mark as cacheable
+  this.cacheable?.();
+
+  try {
+    // Compile .pulse to JavaScript
+    const result = compile(source, {
+      runtime: 'pulse-js-framework/runtime',
+      sourceMap,
+      filename: this.resourcePath
+    });
+
+    if (!result.success) {
+      const errors = result.errors.map(e =>
+        `${e.message}${e.line ? ` at line ${e.line}` : ''}`
+      ).join('\n');
+
+      callback(new Error(`Pulse compilation failed:\n${errors}`));
+      return;
+    }
+
+    let outputCode = result.code;
+    let outputMap = result.map;
+
+    // Extract CSS from compiled output
+    const stylesMatch = outputCode.match(/const styles = `([\s\S]*?)`;/);
+
+    if (stylesMatch) {
+      let css = stylesMatch[1];
+
+      // Check available preprocessors
+      const available = checkPreprocessors();
+      const preprocessor = detectPreprocessor(css);
+
+      // Preprocess if preprocessor detected and available
+      if (preprocessor !== 'none' && available[preprocessor]) {
+        try {
+          const preprocessorOptions = {
+            sass: sassOptions,
+            less: lessOptions,
+            stylus: stylusOptions
+          }[preprocessor];
+
+          const preprocessed = preprocessStylesSync(css, {
+            filename: this.resourcePath,
+            loadPaths: [dirname(this.resourcePath), ...(preprocessorOptions.loadPaths || [])],
+            compressed: preprocessorOptions.compressed || false,
+            preprocessor // Force detected preprocessor
+          });
+
+          css = preprocessed.css;
+
+          // Log preprocessor usage in verbose mode
+          if (preprocessorOptions.verbose) {
+            console.log(`[Pulse] Compiled ${preprocessor.toUpperCase()} in ${this.resourcePath}`);
+          }
+        } catch (preprocessorError) {
+          // Emit warning but continue with original CSS
+          this.emitWarning(
+            new Error(`${preprocessor.toUpperCase()} compilation warning: ${preprocessorError.message}`)
+          );
+        }
+      }
+
+      // Emit CSS as separate file or inline
+      if (options.extractCss !== false) {
+        // Default: emit CSS for css-loader to process
+        // This allows Webpack's CSS pipeline to handle it
+        this.emitFile?.(
+          this.resourcePath.replace(/\.pulse$/, '.pulse.css'),
+          css
+        );
+
+        // Replace inline CSS injection with import statement
+        // css-loader will process the CSS and style-loader will inject it
+        outputCode = outputCode.replace(
+          /\/\/ Styles\nconst styles = `[\s\S]*?`;\n\/\/ Inject styles\nconst styleEl = document\.createElement\("style"\);\nstyleEl\.textContent = styles;\ndocument\.head\.appendChild\(styleEl\);/,
+          `// Styles extracted - handled by css-loader\nimport "./${this.resourcePath.split('/').pop().replace(/\.pulse$/, '.pulse.css')}";`
+        );
+      }
+      // else: keep inline CSS injection (useful for development)
+    }
+
+    // Add HMR support if Webpack HMR is enabled
+    if (this.hot && options.hmr !== false) {
+      outputCode += `\n${generateHMRCode(this.resourcePath)}`;
+    }
+
+    // Only pass source map if enabled in options
+    callback(null, outputCode, sourceMap ? outputMap : null);
+  } catch (error) {
+    callback(new Error(`Pulse loader error: ${error.message}`));
+  }
+}
+
+/**
+ * Generate HMR (Hot Module Replacement) code for Webpack
+ */
+function generateHMRCode(resourcePath) {
+  return `
+// Webpack HMR
+if (module.hot) {
+  module.hot.accept();
+
+  // Cleanup on module replacement
+  module.hot.dispose((data) => {
+    // Store state for preservation
+    if (typeof __PULSE_HMR_STATE__ !== 'undefined') {
+      data.pulseState = __PULSE_HMR_STATE__;
+    }
+  });
+
+  // Restore state after replacement
+  if (module.hot.data && module.hot.data.pulseState) {
+    if (typeof __PULSE_HMR_RESTORE__ !== 'undefined') {
+      __PULSE_HMR_RESTORE__(module.hot.data.pulseState);
+    }
+  }
+}
+`;
+}
+
+/**
+ * Pitch loader - runs before other loaders
+ * Used to log preprocessor availability
+ */
+export function pitch() {
+  const available = checkPreprocessors();
+  const options = this.getOptions() || {};
+
+  // Log preprocessor availability once on first run
+  if (!pulseLoader._logged && options.verbose !== false) {
+    const preprocessors = [];
+    if (available.sass) {
+      preprocessors.push(`SASS ${getSassVersion() || 'unknown'}`);
+    }
+    if (available.less) {
+      preprocessors.push(`LESS ${getLessVersion() || 'unknown'}`);
+    }
+    if (available.stylus) {
+      preprocessors.push(`Stylus ${getStylusVersion() || 'unknown'}`);
+    }
+
+    if (preprocessors.length > 0) {
+      console.log(`[Pulse Webpack] Preprocessor support: ${preprocessors.join(', ')}`);
+    }
+
+    pulseLoader._logged = true;
+  }
+}
+
+// Export for CommonJS compatibility
+export const raw = false; // Return code as string, not Buffer

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.32",
+  "version": "1.7.37",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
+  "sideEffects": false,
   "main": "index.js",
   "types": "types/index.d.ts",
   "bin": {
@@ -94,6 +95,11 @@
       "types": "./types/index.d.ts",
       "default": "./loader/vite-plugin.js"
     },
+    "./webpack": "./loader/webpack-loader.js",
+    "./rollup": "./loader/rollup-plugin.js",
+    "./esbuild": "./loader/esbuild-plugin.js",
+    "./parcel": "./loader/parcel-plugin.js",
+    "./swc": "./loader/swc-plugin.js",
     "./mobile": "./mobile/bridge/pulse-native.js",
     "./package.json": "./package.json"
   },
@@ -110,7 +116,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:css-parsing && npm run test:preprocessor && npm run test:pulse && npm run test:dom && npm run test:dom-element && npm run test:dom-list && npm run test:dom-conditional && npm run test:dom-lifecycle && npm run test:dom-selector && npm run test:dom-adapter && npm run test:dom-advanced && npm run test:enhanced-mock-adapter && npm run test:router && npm run test:store && npm run test:context && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze && npm run test:cli && npm run test:cli-ui && npm run test:cli-create && npm run test:lru-cache && npm run test:utils && npm run test:utils-coverage && npm run test:docs && npm run test:docs-nav && npm run test:async && npm run test:async-coverage && npm run test:form && npm run test:http && npm run test:devtools && npm run test:native && npm run test:a11y && npm run test:a11y-enhanced && npm run test:logger && npm run test:logger-prod && npm run test:errors && npm run test:security && npm run test:websocket && npm run test:graphql && npm run test:graphql-coverage && npm run test:doctor && npm run test:scaffold && npm run test:test-runner && npm run test:build && npm run test:integration && npm run test:context-stress && npm run test:form-edge-cases && npm run test:graphql-subscriptions && npm run test:http-edge-cases && npm run test:integration-advanced && npm run test:websocket-stress && npm run test:ssr && npm run test:ssr-hydrator",
+    "test": "node scripts/run-all-tests.js",
     "test:compiler": "node test/compiler.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:css-parsing": "node test/css-parsing.test.js",
@@ -168,6 +174,13 @@
     "test:websocket-stress": "node test/websocket-stress.test.js",
     "test:ssr": "node test/ssr.test.js",
     "test:ssr-hydrator": "node test/ssr-hydrator.test.js",
+    "test:webpack-loader": "node test/webpack-loader.test.js",
+    "test:rollup-plugin": "node test/rollup-plugin.test.js",
+    "test:esbuild-plugin": "node test/esbuild-plugin.test.js",
+    "test:parcel-plugin": "node test/parcel-plugin.test.js",
+    "test:swc-plugin": "node test/swc-plugin.test.js",
+    "test:dom-binding": "node test/dom-binding.test.js",
+    "test:interceptor-manager": "node test/interceptor-manager.test.js",
     "build:netlify": "node scripts/build-netlify.js",
     "version": "node scripts/sync-version.js",
     "docs": "node cli/index.js dev docs"

package/runtime/security.js

@@ -321,6 +321,27 @@ export function sanitizeHtml(html, options = {}) {
         attrValue = sanitized;
       }
 
+      // Sanitize style attribute to prevent CSS injection
+      if (attrName === 'style') {
+        const parts = attrValue.split(';').filter(Boolean);
+        const safeParts = [];
+        for (const part of parts) {
+          const colonIndex = part.indexOf(':');
+          if (colonIndex === -1) continue;
+          const cssProp = part.slice(0, colonIndex).trim();
+          const cssVal = part.slice(colonIndex + 1).trim();
+          if (/url\s*\(/i.test(cssVal) || /expression\s*\(/i.test(cssVal) ||
+              /javascript:/i.test(cssVal) || /behavior\s*:/i.test(cssVal) ||
+              /-moz-binding/i.test(cssVal)) {
+            log.warn(`Blocked dangerous CSS in style attribute: ${cssProp}`);
+            continue;
+          }
+          safeParts.push(`${cssProp}: ${cssVal}`);
+        }
+        attrValue = safeParts.join('; ');
+        if (!attrValue) continue;
+      }
+
       result += ` ${attrName}="${escapeHtml(attrValue)}"`;
     }
 

package/runtime/ssr.js

@@ -408,12 +408,16 @@ export function deserializeState(data) {
  * // Default implementation just stores in global
  * restoreState(window.__PULSE_STATE__);
  */
+// Module-scoped state store (avoids globalThis collision between multiple SSR instances)
+let _ssrState = null;
+
 export function restoreState(state) {
   const deserialized = typeof state === 'string'
     ? deserializeState(state)
     : state;
 
-  // Store in global for access by components
+  // Store in module scope and global for backward compatibility
+  _ssrState = deserialized;
   if (typeof globalThis !== 'undefined') {
     globalThis.__PULSE_SSR_STATE__ = deserialized;
   }
@@ -430,10 +434,20 @@ export function restoreState(state) {
  * const userData = getSSRState('user');
  */
 export function getSSRState(key) {
-  const state = globalThis?.__PULSE_SSR_STATE__ || {};
+  const state = _ssrState || globalThis?.__PULSE_SSR_STATE__ || {};
   return key ? state[key] : state;
 }
 
+/**
+ * Clear the SSR state. Use in tests or when cleaning up SSR context.
+ */
+export function clearSSRState() {
+  _ssrState = null;
+  if (typeof globalThis !== 'undefined') {
+    delete globalThis.__PULSE_SSR_STATE__;
+  }
+}
+
 // ============================================================================
 // Re-exports for convenience
 // ============================================================================
@@ -456,6 +470,7 @@ export default {
   deserializeState,
   restoreState,
   getSSRState,
+  clearSSRState,
 
   // Mode checks
   isSSR,

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
 // =============================================================================