pulse-js-framework 1.4.7 → 1.4.9

package/types/router.d.ts

@@ -69,12 +69,57 @@ export interface Routes {
   [path: string]: RouteHandler | RouteDefinition;
 }
 
+// =============================================================================
+// Middleware Types
+// =============================================================================
+
+/** Middleware context passed to each middleware function */
+export interface MiddlewareContext {
+  /** Target route */
+  to: NavigationTarget;
+  /** Source route */
+  from: NavigationTarget;
+  /** Shared metadata between middlewares */
+  meta: Record<string, unknown>;
+  /** Redirect to another path */
+  redirect(path: string): void;
+  /** Abort navigation */
+  abort(): void;
+}
+
+/** Middleware function */
+export type MiddlewareFn = (
+  ctx: MiddlewareContext,
+  next: () => Promise<void>
+) => void | Promise<void>;
+
+// =============================================================================
+// Lazy Loading Types
+// =============================================================================
+
+/** Lazy loading options */
+export interface LazyOptions {
+  /** Loading component shown while loading */
+  loading?: () => Node;
+  /** Error component shown on failure */
+  error?: (err: Error) => Node;
+  /** Timeout in milliseconds (default: 10000) */
+  timeout?: number;
+  /** Delay before showing loading component (default: 200) */
+  delay?: number;
+}
+
+/** Lazy route handler */
+export type LazyRouteHandler = (ctx: RouteContext) => Node;
+
 /** Router options */
 export interface RouterOptions {
   routes?: Routes;
   mode?: 'history' | 'hash';
   base?: string;
   scrollBehavior?: ScrollBehaviorFn;
+  /** Middleware functions */
+  middleware?: MiddlewareFn[];
 }
 
 /** Navigation options */
@@ -84,6 +129,15 @@ export interface NavigateOptions {
   state?: unknown;
 }
 
+/** Route context passed to route handlers */
+export interface RouteContext {
+  params: RouteParams;
+  query: QueryParams;
+  path: string;
+  navigate: Router['navigate'];
+  router: Router;
+}
+
 /** Link options */
 export interface LinkOptions {
   exact?: boolean;
@@ -141,6 +195,12 @@ export interface Router {
   /** Go to specific history entry */
   go(delta: number): void;
 
+  /**
+   * Add middleware dynamically
+   * @returns Unregister function
+   */
+  use(middleware: MiddlewareFn): () => void;
+
   /**
    * Add global before-navigation guard
    * @returns Unregister function
@@ -195,3 +255,32 @@ export declare function createRouter(options?: RouterOptions): Router;
  * Quick router setup (creates, starts, and mounts)
  */
 export declare function simpleRouter(routes: Routes, target?: string): Router;
+
+/**
+ * Create a lazy-loaded route handler
+ * Wraps a dynamic import with loading states and error handling
+ *
+ * @example
+ * const routes = {
+ *   '/dashboard': lazy(() => import('./Dashboard.js')),
+ *   '/settings': lazy(() => import('./Settings.js'), {
+ *     loading: () => el('div.spinner', 'Loading...'),
+ *     error: (err) => el('div.error', `Failed: ${err.message}`),
+ *     timeout: 5000
+ *   })
+ * };
+ */
+export declare function lazy(
+  importFn: () => Promise<{ default: RouteHandler | (() => Node) }>,
+  options?: LazyOptions
+): LazyRouteHandler;
+
+/**
+ * Preload a lazy component without rendering
+ * Useful for prefetching on hover or when likely to navigate
+ *
+ * @example
+ * const DashboardLazy = lazy(() => import('./Dashboard.js'));
+ * link.addEventListener('mouseenter', () => preload(DashboardLazy));
+ */
+export declare function preload(lazyHandler: LazyRouteHandler): Promise<void>;

package/types/sourcemap.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pulse Framework - Source Map Type Definitions
+ * @module pulse-js-framework/compiler/sourcemap
+ */
+
+/** Source map position */
+export interface Position {
+  line: number;
+  column: number;
+}
+
+/** Source map mapping */
+export interface Mapping {
+  generated: Position;
+  original?: Position;
+  source?: string;
+  name?: string;
+}
+
+/** V3 Source Map format */
+export interface SourceMapV3 {
+  version: 3;
+  file: string;
+  sourceRoot: string;
+  sources: string[];
+  sourcesContent: (string | null)[];
+  names: string[];
+  mappings: string;
+}
+
+/** Original position result from consumer */
+export interface OriginalPosition {
+  source: string;
+  line: number;
+  column: number;
+  name: string | null;
+}
+
+/**
+ * Source Map Generator
+ * Generates V3 source maps for compiled .pulse files
+ */
+export declare class SourceMapGenerator {
+  /**
+   * Create a new source map generator
+   * @param options - Generator options
+   */
+  constructor(options?: {
+    file?: string;
+    sourceRoot?: string;
+  });
+
+  /**
+   * Add a source file
+   * @param source - Source file path
+   * @param content - Source file content (optional, for inline sources)
+   * @returns Source index
+   */
+  addSource(source: string, content?: string | null): number;
+
+  /**
+   * Add a name (identifier) to the names array
+   * @param name - Identifier name
+   * @returns Name index
+   */
+  addName(name: string): number;
+
+  /**
+   * Add a mapping between generated and original positions
+   * @param mapping - Mapping information
+   */
+  addMapping(mapping: Mapping): void;
+
+  /**
+   * Generate the source map object
+   * @returns V3 source map object
+   */
+  toJSON(): SourceMapV3;
+
+  /**
+   * Generate source map as JSON string
+   */
+  toString(): string;
+
+  /**
+   * Generate inline source map comment
+   * @returns Comment with base64 encoded source map
+   */
+  toComment(): string;
+
+  /**
+   * Generate external source map URL comment
+   * @param url - URL to source map file
+   */
+  static toURLComment(url: string): string;
+}
+
+/**
+ * Source Map Consumer
+ * Parse and query source maps for error stack trace translation
+ */
+export declare class SourceMapConsumer {
+  /**
+   * Create a new source map consumer
+   * @param sourceMap - Source map object or JSON string
+   */
+  constructor(sourceMap: SourceMapV3 | string);
+
+  /**
+   * Decode VLQ string to numbers
+   * @param str - VLQ encoded string
+   */
+  static decodeVLQ(str: string): number[];
+
+  /**
+   * Get original position for a generated position
+   * @param position - Generated position
+   * @returns Original position or null if not found
+   */
+  originalPositionFor(position: Position): OriginalPosition | null;
+}
+
+/**
+ * Encode a number as VLQ base64
+ */
+export declare function encodeVLQ(value: number): string;