pulse-js-framework 1.4.3 → 1.4.5

package/types/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Pulse Framework - Type Definitions
+ * @module pulse-js-framework
+ */
+
+// Core Reactivity
+export {
+  Pulse,
+  PulseOptions,
+  ComputedOptions,
+  MemoOptions,
+  MemoComputedOptions,
+  EqualsFn,
+  ReactiveState,
+  PromiseState,
+  pulse,
+  computed,
+  effect,
+  batch,
+  watch,
+  createState,
+  memo,
+  memoComputed,
+  fromPromise,
+  untrack,
+  onCleanup
+} from './pulse';
+
+// DOM Helpers
+export {
+  MaybeGetter,
+  Reactive,
+  Child,
+  ParsedSelector,
+  EventOptions,
+  KeyFn,
+  ListTemplate,
+  ConditionTemplate,
+  MatchCases,
+  ComponentContext,
+  ComponentSetup,
+  ComponentFactory,
+  ErrorFallback,
+  TransitionOptions,
+  TransitionElement,
+  WhenTransitionOptions,
+  parseSelector,
+  el,
+  text,
+  bind,
+  prop,
+  cls,
+  style,
+  on,
+  list,
+  when,
+  match,
+  model,
+  mount,
+  component,
+  onMount,
+  onUnmount,
+  show,
+  portal,
+  errorBoundary,
+  transition,
+  whenTransition
+} from './dom';
+
+// Router
+export {
+  RouteParams,
+  QueryParams,
+  RouteMeta,
+  NavigationTarget,
+  NavigationGuardReturn,
+  NavigationGuard,
+  AfterNavigationHook,
+  ScrollPosition,
+  ScrollBehaviorFn,
+  RouteHandler,
+  RouteDefinition,
+  Routes,
+  RouterOptions,
+  NavigateOptions,
+  LinkOptions,
+  MatchedRoute,
+  Router,
+  createRouter,
+  simpleRouter
+} from './router';
+
+// Store
+export {
+  StoreOptions,
+  StoreState,
+  StoreMethods,
+  Store,
+  ActionFn,
+  ActionsDef,
+  BoundActions,
+  GetterFn,
+  GettersDef,
+  ComputedGetters,
+  CombinedStores,
+  ModuleDef,
+  ModulesDef,
+  ModuleStore,
+  RootModuleStore,
+  StorePlugin,
+  HistoryStore,
+  createStore,
+  createActions,
+  createGetters,
+  combineStores,
+  createModuleStore,
+  usePlugin,
+  loggerPlugin,
+  historyPlugin
+} from './store';
+
+// Logger
+export {
+  LogLevel,
+  LogLevelValue,
+  LogFormatter,
+  LoggerOptions,
+  Logger,
+  setLogLevel,
+  getLogLevel,
+  setFormatter,
+  createLogger,
+  logger,
+  loggers
+} from './logger';

package/types/logger.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Pulse Logger - Type Definitions
+ * @module pulse-js-framework/runtime/logger
+ */
+
+/**
+ * Log level constants
+ */
+export declare const LogLevel: {
+  readonly SILENT: 0;
+  readonly ERROR: 1;
+  readonly WARN: 2;
+  readonly INFO: 3;
+  readonly DEBUG: 4;
+};
+
+export type LogLevelValue = 0 | 1 | 2 | 3 | 4;
+
+/**
+ * Custom formatter function type
+ */
+export type LogFormatter = (
+  level: 'error' | 'warn' | 'info' | 'debug',
+  namespace: string | null,
+  args: unknown[]
+) => string;
+
+/**
+ * Logger options
+ */
+export interface LoggerOptions {
+  /** Override global level for this logger */
+  level?: LogLevelValue;
+}
+
+/**
+ * Logger instance interface
+ */
+export interface Logger {
+  /**
+   * Log error message (always shown unless SILENT)
+   */
+  error(...args: unknown[]): void;
+
+  /**
+   * Log warning message
+   */
+  warn(...args: unknown[]): void;
+
+  /**
+   * Log info message (general output)
+   */
+  info(...args: unknown[]): void;
+
+  /**
+   * Log debug message (verbose output)
+   */
+  debug(...args: unknown[]): void;
+
+  /**
+   * Create a log group (for debug mode)
+   */
+  group(label: string): void;
+
+  /**
+   * End a log group
+   */
+  groupEnd(): void;
+
+  /**
+   * Log with custom level
+   */
+  log(level: LogLevelValue, ...args: unknown[]): void;
+
+  /**
+   * Create a child logger with additional namespace
+   */
+  child(childNamespace: string): Logger;
+}
+
+/**
+ * Set global log level
+ */
+export declare function setLogLevel(level: LogLevelValue): void;
+
+/**
+ * Get current global log level
+ */
+export declare function getLogLevel(): LogLevelValue;
+
+/**
+ * Set custom formatter for all loggers
+ */
+export declare function setFormatter(formatter: LogFormatter | null): void;
+
+/**
+ * Create a logger instance with optional namespace
+ */
+export declare function createLogger(
+  namespace?: string | null,
+  options?: LoggerOptions
+): Logger;
+
+/**
+ * Default logger instance (no namespace)
+ */
+export declare const logger: Logger;
+
+/**
+ * Pre-configured loggers for common subsystems
+ */
+export declare const loggers: {
+  readonly pulse: Logger;
+  readonly dom: Logger;
+  readonly router: Logger;
+  readonly store: Logger;
+  readonly native: Logger;
+  readonly hmr: Logger;
+  readonly cli: Logger;
+};
+
+export default logger;

package/types/pulse.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Pulse Framework - Core Reactivity Type Definitions
+ * @module pulse-js-framework/runtime
+ */
+
+/** Equality function for comparing values */
+export type EqualsFn<T> = (a: T, b: T) => boolean;
+
+/** Pulse options */
+export interface PulseOptions<T> {
+  equals?: EqualsFn<T>;
+}
+
+/** Computed options */
+export interface ComputedOptions {
+  lazy?: boolean;
+}
+
+/** Memo options */
+export interface MemoOptions<T> {
+  equals?: EqualsFn<T>;
+}
+
+/** MemoComputed options */
+export interface MemoComputedOptions<T> {
+  deps?: unknown[];
+  equals?: EqualsFn<T>;
+}
+
+/**
+ * Reactive value container (signal)
+ */
+export declare class Pulse<T = unknown> {
+  constructor(value: T, options?: PulseOptions<T>);
+
+  /** Read value and track dependency */
+  get(): T;
+
+  /** Read value without tracking dependency */
+  peek(): T;
+
+  /** Set new value and notify subscribers */
+  set(newValue: T): void;
+
+  /** Update value using function */
+  update(fn: (value: T) => T): void;
+
+  /** Subscribe to changes, returns unsubscribe function */
+  subscribe(fn: (value: T) => void): () => void;
+
+  /** Create derived pulse */
+  derive<U>(fn: (value: T) => U): Pulse<U>;
+
+  /** Cleanup (for computed pulses) */
+  dispose(): void;
+}
+
+/**
+ * Create a reactive value
+ */
+export declare function pulse<T>(value: T, options?: PulseOptions<T>): Pulse<T>;
+
+/**
+ * Create a computed (derived) reactive value
+ */
+export declare function computed<T>(fn: () => T, options?: ComputedOptions): Pulse<T>;
+
+/**
+ * Create a side effect that runs when dependencies change
+ * @returns Cleanup function
+ */
+export declare function effect(fn: () => void | (() => void)): () => void;
+
+/**
+ * Batch multiple updates into a single effect run
+ */
+export declare function batch(fn: () => void): void;
+
+/**
+ * Watch specific pulses and run callback on change
+ * @returns Cleanup function
+ */
+export declare function watch<T>(
+  source: Pulse<T>,
+  callback: (newValue: T, oldValue: T) => void
+): () => void;
+export declare function watch<T extends readonly Pulse<unknown>[]>(
+  sources: T,
+  callback: (
+    newValues: { [K in keyof T]: T[K] extends Pulse<infer U> ? U : never },
+    oldValues: { [K in keyof T]: T[K] extends Pulse<infer U> ? U : never }
+  ) => void
+): () => void;
+
+/** State object with reactive properties */
+export interface ReactiveState<T extends Record<string, unknown>> {
+  /** Access raw pulses */
+  $pulses: { [K in keyof T]: Pulse<T[K]> };
+  /** Get pulse by key */
+  $pulse<K extends keyof T>(key: K): Pulse<T[K]>;
+}
+
+/**
+ * Create reactive state object from plain object
+ */
+export declare function createState<T extends Record<string, unknown>>(
+  obj: T
+): T & ReactiveState<T>;
+
+/**
+ * Memoize a function based on arguments
+ */
+export declare function memo<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  options?: MemoOptions<ReturnType<T>>
+): T;
+
+/**
+ * Create memoized computed value
+ */
+export declare function memoComputed<T>(
+  fn: () => T,
+  options?: MemoComputedOptions<T>
+): Pulse<T>;
+
+/** Promise result state */
+export interface PromiseState<T> {
+  value: Pulse<T | undefined>;
+  loading: Pulse<boolean>;
+  error: Pulse<Error | null>;
+}
+
+/**
+ * Create reactive values from a promise
+ */
+export declare function fromPromise<T>(
+  promise: Promise<T>,
+  initialValue?: T
+): PromiseState<T>;
+
+/**
+ * Read pulses without creating dependencies
+ */
+export declare function untrack<T>(fn: () => T): T;
+
+/**
+ * Register cleanup function for current effect
+ */
+export declare function onCleanup(fn: () => void): void;

package/types/router.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Pulse Framework - Router Type Definitions
+ * @module pulse-js-framework/runtime/router
+ */
+
+import { Pulse } from './pulse';
+
+/** Route parameters object */
+export type RouteParams = Record<string, string>;
+
+/** Query parameters object */
+export type QueryParams = Record<string, string | string[]>;
+
+/** Route meta information */
+export type RouteMeta = Record<string, unknown>;
+
+/** Navigation target (to/from) */
+export interface NavigationTarget {
+  path: string;
+  params: RouteParams;
+  query: QueryParams;
+  meta: RouteMeta;
+  matched?: RouteDefinition[];
+}
+
+/** Navigation guard return type */
+export type NavigationGuardReturn = boolean | string | void | Promise<boolean | string | void>;
+
+/** Navigation guard function */
+export type NavigationGuard = (
+  to: NavigationTarget,
+  from: NavigationTarget
+) => NavigationGuardReturn;
+
+/** After navigation hook */
+export type AfterNavigationHook = (to: NavigationTarget) => void | Promise<void>;
+
+/** Scroll position */
+export interface ScrollPosition {
+  x?: number;
+  y?: number;
+  selector?: string;
+  behavior?: ScrollBehavior;
+}
+
+/** Scroll behavior function */
+export type ScrollBehaviorFn = (
+  to: NavigationTarget,
+  from: NavigationTarget,
+  savedPosition: ScrollPosition | null
+) => ScrollPosition | null | void;
+
+/** Route handler (component) */
+export type RouteHandler =
+  | (() => Node)
+  | (() => Promise<{ default: () => Node }>)
+  | { render: () => Node };
+
+/** Route definition */
+export interface RouteDefinition {
+  handler?: RouteHandler;
+  meta?: RouteMeta;
+  beforeEnter?: NavigationGuard;
+  children?: Routes;
+}
+
+/** Routes configuration object */
+export interface Routes {
+  [path: string]: RouteHandler | RouteDefinition;
+}
+
+/** Router options */
+export interface RouterOptions {
+  routes?: Routes;
+  mode?: 'history' | 'hash';
+  base?: string;
+  scrollBehavior?: ScrollBehaviorFn;
+}
+
+/** Navigation options */
+export interface NavigateOptions {
+  replace?: boolean;
+  query?: Record<string, string | number>;
+  state?: unknown;
+}
+
+/** Link options */
+export interface LinkOptions {
+  exact?: boolean;
+  activeClass?: string;
+}
+
+/** Matched route */
+export interface MatchedRoute {
+  route: RouteDefinition;
+  params: RouteParams;
+}
+
+/** Router instance */
+export interface Router {
+  /** Current path (reactive) */
+  path: Pulse<string>;
+
+  /** Current route object (reactive) */
+  route: Pulse<NavigationTarget | null>;
+
+  /** Current route parameters (reactive) */
+  params: Pulse<RouteParams>;
+
+  /** Current query parameters (reactive) */
+  query: Pulse<QueryParams>;
+
+  /** Current route meta (reactive) */
+  meta: Pulse<RouteMeta>;
+
+  /** Loading state for async components (reactive) */
+  loading: Pulse<boolean>;
+
+  /**
+   * Navigate to path
+   * @returns Promise resolving to navigation success
+   */
+  navigate(path: string, options?: NavigateOptions): Promise<boolean>;
+
+  /**
+   * Create router link element
+   */
+  link(path: string, content: Node | string, options?: LinkOptions): HTMLAnchorElement;
+
+  /**
+   * Render current route component
+   */
+  outlet(container: string | HTMLElement): HTMLElement;
+
+  /** Navigate back in history */
+  back(): void;
+
+  /** Navigate forward in history */
+  forward(): void;
+
+  /** Go to specific history entry */
+  go(delta: number): void;
+
+  /**
+   * Add global before-navigation guard
+   * @returns Unregister function
+   */
+  beforeEach(hook: NavigationGuard): () => void;
+
+  /**
+   * Add before-resolve hook (after per-route guards)
+   * @returns Unregister function
+   */
+  beforeResolve(hook: NavigationGuard): () => void;
+
+  /**
+   * Add after-navigation hook
+   * @returns Unregister function
+   */
+  afterEach(hook: AfterNavigationHook): () => void;
+
+  /**
+   * Check if route matches
+   */
+  isActive(path: string, exact?: boolean): boolean;
+
+  /**
+   * Get all matched routes (for nested routes)
+   */
+  getMatchedRoutes(path: string): MatchedRoute[];
+
+  /**
+   * Start listening to navigation events
+   * @returns Stop function
+   */
+  start(): () => void;
+
+  /**
+   * Match path against pattern
+   */
+  matchRoute(pattern: string, path: string): RouteParams | null;
+
+  /**
+   * Parse query string to object
+   */
+  parseQuery(search: string): QueryParams;
+}
+
+/**
+ * Create router instance
+ */
+export declare function createRouter(options?: RouterOptions): Router;
+
+/**
+ * Quick router setup (creates, starts, and mounts)
+ */
+export declare function simpleRouter(routes: Routes, target?: string): Router;