@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/handlers/HandlerRegistry.d.ts

@@ -0,0 +1,225 @@
+/**
+ * HandlerRegistry - Advanced handler registration and management system
+ *
+ * Provides sophisticated handler registration with priority management,
+ * conflict detection, dependency resolution, and dynamic loading capabilities.
+ *
+ * Related Issue: #56 - Handler Registration and Priority System
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+import BaseSyntaxHandler from './BaseSyntaxHandler.js';
+import type { DependencySpec } from './BaseSyntaxHandler.js';
+export type { DependencySpec };
+/**
+ * Handler registry configuration
+ */
+export interface RegistryConfig {
+    maxHandlers: number;
+    allowDuplicatePriorities: boolean;
+    enableDependencyResolution: boolean;
+    enableConflictDetection: boolean;
+    defaultTimeout: number;
+}
+/**
+ * Handler registry statistics
+ */
+export interface RegistryStats {
+    registeredHandlers: number;
+    activeHandlers: number;
+    totalExecutions: number;
+    totalErrors: number;
+    lastRegistration: Date | null;
+    lastUnregistration: Date | null;
+}
+/**
+ * Handler registration options
+ */
+export interface RegistrationOptions {
+    forceRegister?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Initialization context for handlers
+ */
+export interface HandlerInitContext {
+    engine: WikiEngine | undefined;
+    handlerRegistry: HandlerRegistry;
+    registrationOptions: RegistrationOptions;
+}
+/**
+ * WikiEngine minimal interface (until fully typed)
+ */
+export interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * Dependency validation error
+ */
+export interface DependencyValidationError {
+    handlerId: string;
+    dependencyType: 'handler' | 'manager';
+    dependencyName: string;
+    error: string;
+}
+/**
+ * Exported registry state
+ */
+export interface ExportedRegistryState {
+    config: RegistryConfig;
+    stats: RegistryStats;
+    handlers: unknown[];
+    dependencies: Record<string, string[]>;
+}
+/**
+ * Registry information summary
+ */
+export interface RegistryInfo {
+    handlerCount: number;
+    activeHandlerCount: number;
+    config: RegistryConfig;
+    stats: RegistryStats;
+}
+/**
+ * Extended registry statistics with handler details
+ */
+export interface ExtendedRegistryStats {
+    registry: RegistryStats & {
+        enabledHandlers: number;
+        disabledHandlers: number;
+        totalHandlers: number;
+    };
+    handlers: Record<string, unknown>;
+    config: RegistryConfig;
+}
+/**
+ * HandlerRegistry - Advanced handler registration and management system
+ */
+declare class HandlerRegistry {
+    private engine;
+    private handlers;
+    private handlersByPriority;
+    private handlersByPattern;
+    private dependencyGraph;
+    private config;
+    private stats;
+    constructor(engine?: WikiEngine | null);
+    /**
+     * Register a syntax handler with full validation and conflict detection
+     * @param handler - Handler to register
+     * @param options - Registration options
+     * @returns True if registration successful
+     */
+    registerHandler(handler: BaseSyntaxHandler, options?: RegistrationOptions): Promise<boolean>;
+    /**
+     * Unregister a syntax handler
+     * @param handlerId - ID of handler to unregister
+     * @returns True if unregistration successful
+     */
+    unregisterHandler(handlerId: string): Promise<boolean>;
+    /**
+     * Validate handler before registration
+     * @param handler - Handler to validate
+     */
+    private validateHandler;
+    /**
+     * Detect conflicts with existing handlers
+     * @param newHandler - New handler to check
+     * @returns Array of conflicting handlers
+     */
+    private detectConflicts;
+    /**
+     * Check if two handlers conflict
+     * @param handler1 - First handler
+     * @param handler2 - Second handler
+     * @returns True if handlers conflict
+     */
+    private handlersConflict;
+    /**
+     * Rebuild the priority-sorted handler list
+     */
+    private rebuildPriorityList;
+    /**
+     * Update dependency graph when handler is registered
+     * @param handler - Handler being registered
+     */
+    private updateDependencyGraph;
+    /**
+     * Get handlers that depend on the specified handler
+     * @param handlerId - Handler ID
+     * @returns Dependent handlers
+     */
+    private getDependentHandlers;
+    /**
+     * Get handler by ID
+     * @param handlerId - Handler ID
+     * @returns Handler or null if not found
+     */
+    getHandler(handlerId: string): BaseSyntaxHandler | null;
+    /**
+     * Get all handlers sorted by priority
+     * @param enabledOnly - Only return enabled handlers
+     * @returns Handlers sorted by priority
+     */
+    getHandlersByPriority(enabledOnly?: boolean): BaseSyntaxHandler[];
+    /**
+     * Get handlers by pattern
+     * @param pattern - Pattern to match
+     * @returns Matching handlers
+     */
+    getHandlersByPattern(pattern: string | RegExp): BaseSyntaxHandler[];
+    /**
+     * Enable handler by ID
+     * @param handlerId - Handler ID
+     * @returns True if successful
+     */
+    enableHandler(handlerId: string): boolean;
+    /**
+     * Disable handler by ID
+     * @param handlerId - Handler ID
+     * @returns True if successful
+     */
+    disableHandler(handlerId: string): boolean;
+    /**
+     * Get registry statistics
+     * @returns Registry statistics
+     */
+    getStats(): ExtendedRegistryStats;
+    /**
+     * Reset all handler statistics
+     */
+    resetStats(): void;
+    /**
+     * Resolve handler execution order considering dependencies
+     * @returns Handlers in dependency-resolved order
+     */
+    resolveExecutionOrder(): BaseSyntaxHandler[];
+    /**
+     * Validate all handler dependencies
+     * @returns Array of dependency validation errors
+     */
+    validateDependencies(): DependencyValidationError[];
+    /**
+     * Clear all handlers
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Export registry state for persistence
+     * @returns Serializable registry state
+     */
+    exportState(): ExportedRegistryState;
+    /**
+     * Get registry information
+     * @returns Registry information
+     */
+    getInfo(): RegistryInfo;
+}
+/**
+ * Custom error class for handler registration errors
+ */
+export declare class HandlerRegistrationError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+export { HandlerRegistry };
+export default HandlerRegistry;

package/lib/src/parsers/handlers/JSPWikiPreprocessor.d.ts

@@ -0,0 +1,89 @@
+import BaseSyntaxHandler, { ParseContext, HandlerMetadata } from './BaseSyntaxHandler.js';
+/**
+ * Wiki engine interface
+ */
+interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * JSPWikiPreprocessor - Processes JSPWiki syntax BEFORE markdown
+ *
+ * This handler runs in Phase 1 (Preprocessing) to:
+ * 1. Parse nested %%.../%% style blocks
+ * 2. Convert JSPWiki table syntax (|| header ||, | cell |) to HTML
+ * 3. Apply style classes to tables
+ *
+ * This matches JSPWiki's architecture where pre-blocking happens in the parser
+ * before any other transformations (like markdown).
+ *
+ * Related to: #41 - JSPWiki Table Styles Implementation
+ */
+declare class JSPWikiPreprocessor extends BaseSyntaxHandler {
+    handlerId: string;
+    private phase;
+    private tableClasses;
+    constructor(_engine?: WikiEngine | null);
+    /**
+     * Process content: find and parse all %%.../%% blocks with nested support
+     */
+    process(content: string, _context: ParseContext): Promise<string>;
+    /**
+     * Parse nested %%.../%% blocks
+     * JSPWiki syntax allows nesting like:
+     * %%zebra-table
+     * %%sortable
+     * || Header ||
+     * | Cell |
+     * /%
+     * /%
+     */
+    private parseStyleBlocks;
+    /**
+     * Extract a %%.../%% block starting at startIndex
+     * Returns { content, endIndex } or null if no matching /% found
+     */
+    private extractBlock;
+    /**
+     * Check if a class name is table-related
+     * Also handles custom color syntax: zebra-HEXCOLOR (e.g., zebra-ffe0e0)
+     */
+    private isTableClass;
+    /**
+     * Calculate contrast color (black or white) for a given background color
+     * Uses WCAG relative luminance formula
+     * @param hexColor - 6-digit hex color (without #)
+     * @returns '#000000' or '#ffffff'
+     */
+    private getContrastColor;
+    /**
+     * Extract custom styles from class names
+     * Returns { classes: string, styles: string }
+     */
+    private extractCustomStyles;
+    /**
+     * Parse JSPWiki table syntax and convert to HTML
+     * Handles both header rows (|| cell ||) and data rows (| cell |)
+     *
+     * @param content - Table markup
+     * @param className - CSS classes to apply (space-separated, can be empty)
+     */
+    private parseTable;
+    /**
+     * Escape HTML special characters, preserving placeholder spans
+     * that were inserted by extractJSPWikiSyntax (Phase 1).
+     *
+     * NOTE: intentionally NOT replaced with pluginFormatters.escapeHtml — the
+     * shared helper is a simple character mapper, but this method must first
+     * protect <span data-jspwiki-placeholder> tokens from being entity-encoded.
+     * The two implementations serve different contexts.
+     */
+    private escapeHtml;
+    /**
+     * Get handler metadata
+     */
+    getMetadata(): HandlerMetadata & {
+        name: string;
+        phase: number;
+    };
+}
+export default JSPWikiPreprocessor;

package/lib/src/parsers/handlers/LinkParserHandler.d.ts

@@ -0,0 +1,80 @@
+import BaseSyntaxHandler, { InitializationContext, ParseContext } from './BaseSyntaxHandler.js';
+/**
+ * Wiki engine interface
+ */
+interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * LinkParserHandler - Unified link processing handler using LinkParser
+ *
+ * This handler integrates the comprehensive LinkParser into the MarkupParser
+ * handler architecture, providing centralized processing for all link types:
+ * - Internal wiki links: [PageName], [Display|Target]
+ * - External links: [Display|http://example.com]
+ * - InterWiki links: [Display|Wikipedia:Article]
+ * - Email links: [Display|mailto:user@example.com]
+ * - Anchor links: [Display|#section]
+ * - Links with attributes: [Display|Target|class="custom" target="_blank"]
+ *
+ * Replaces the fragmented WikiLinkHandler and InterWikiLinkHandler approach
+ * with a unified, security-focused, and comprehensive solution.
+ *
+ * Related Issue: #75 - Create LinkParser.js for centralized link parsing
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+declare class LinkParserHandler extends BaseSyntaxHandler {
+    handlerId: string;
+    private engine;
+    private linkParser;
+    initialized: boolean;
+    private localStats;
+    private matchEnglishPlurals;
+    private matchCamelCase;
+    constructor(engine?: WikiEngine | null);
+    /**
+     * Initialize handler with LinkParser configuration
+     * @param context - Initialization context
+     */
+    protected onInitialize(context: InitializationContext): Promise<void>;
+    /**
+     * Initialize LinkParser with current page names and configuration
+     */
+    private initializeLinkParser;
+    /**
+     * Load InterWiki site configuration for LinkParser
+     */
+    private loadInterWikiConfiguration;
+    /**
+     * Load default InterWiki sites
+     */
+    private loadDefaultInterWikiSites;
+    /**
+     * Process content using LinkParser
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Content with links processed
+     */
+    process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Handle method - not used since we override process() entirely
+     * @param _match - Match information
+     * @param _context - Parse context
+     * @returns Processed match
+     */
+    handle(_match: RegExpMatchArray, _context: ParseContext): Promise<string>;
+    /**
+     * Refresh page names cache (called when pages are added/removed)
+     */
+    refreshPageNames(): Promise<void>;
+    /**
+     * Get handler information including LinkParser statistics
+     * @returns Handler information
+     */
+    getInfo(): Record<string, unknown>;
+    /**
+     * Handler-specific shutdown cleanup
+     */
+    protected onShutdown(): Promise<void>;
+}
+export default LinkParserHandler;

package/lib/src/parsers/handlers/PluginSyntaxHandler.d.ts

@@ -0,0 +1,78 @@
+import BaseSyntaxHandler, { InitializationContext, ParseContext } from './BaseSyntaxHandler.js';
+/**
+ * Wiki engine interface
+ */
+interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * PluginSyntaxHandler - Enhanced plugin syntax processing
+ *
+ * Handles JSPWiki-style plugin syntax: [{PluginName param=value}]
+ * with advanced parameter parsing and validation.
+ *
+ * Related Issue: #58 - Enhanced Plugin Syntax Handler
+ * Depends On: #56 - Handler Registration and Priority System
+ */
+declare class PluginSyntaxHandler extends BaseSyntaxHandler {
+    handlerId: string;
+    private engine;
+    private config;
+    constructor(engine?: WikiEngine | null);
+    /**
+     * Initialize handler with configuration
+     * @param context - Initialization context
+     */
+    protected onInitialize(context: InitializationContext): Promise<void>;
+    /**
+     * Process content by finding and executing all plugin instances
+     * Supports both simple [{Plugin}] and body syntax [{Plugin}]content[/{Plugin}]
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Content with plugins executed
+     */
+    process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Process body-style plugins: [{Plugin}]content[/{Plugin}]
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Content with body plugins processed
+     */
+    private processBodyPlugins;
+    /**
+     * Handle a specific plugin match
+     * @param matchInfo - Plugin match information
+     * @param context - Parse context
+     * @returns Plugin output HTML
+     */
+    private handlePlugin;
+    /**
+     * Validate plugin parameters
+     * @param pluginName - Plugin name
+     * @param parameters - Plugin parameters
+     * @returns Validation result
+     */
+    private validatePluginParameters;
+    /**
+     * Enhanced parameter parsing with support for complex formats
+     * @param paramString - Parameter string to parse
+     * @returns Parsed parameters
+     */
+    private parsePluginParameters;
+    /**
+     * Get supported plugin patterns for this handler
+     * @returns Array of supported patterns
+     */
+    getSupportedPatterns(): string[];
+    /**
+     * Get link graph from RenderingManager
+     * @returns Link graph object
+     */
+    private getLinkGraph;
+    /**
+     * Get handler information for debugging
+     * @returns Handler information
+     */
+    getInfo(): Record<string, unknown>;
+}
+export default PluginSyntaxHandler;

package/lib/src/parsers/handlers/WikiFormHandler.d.ts

@@ -0,0 +1,149 @@
+import BaseSyntaxHandler, { InitializationContext, ParseContext } from './BaseSyntaxHandler.js';
+/**
+ * Form validation result
+ */
+interface FormValidationResult {
+    isValid: boolean;
+    errors: string[];
+    sanitizedData: Record<string, unknown>;
+}
+/**
+ * Wiki engine interface
+ */
+interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * Extended parse context for the form handler. After #629 Pass 2, the
+ * setMetadata/getMetadata methods are available on the real ParseContext.
+ */
+type FormParseContext = ParseContext;
+/**
+ * WikiFormHandler - Interactive form generation within wiki pages
+ *
+ * Supports JSPWiki form syntax:
+ * - [{FormOpen action='SaveData' method='POST'}] - Form opening
+ * - [{FormInput name='field' type='text' value='default'}] - Input fields
+ * - [{FormSelect name='choice' options='A,B,C'}] - Select boxes
+ * - [{FormTextarea name='comment' rows='5'}] - Text areas
+ * - [{FormButton type='submit' value='Save'}] - Form buttons
+ * - [{FormClose}] - Form closing
+ *
+ * Related Issue: #60 - WikiForm Handler (FormOpen, FormInput, FormClose)
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+declare class WikiFormHandler extends BaseSyntaxHandler {
+    handlerId: string;
+    private config;
+    private activeForms;
+    private formCounter;
+    constructor(_engine?: WikiEngine | null);
+    /**
+     * Initialize handler with configuration
+     * @param context - Initialization context
+     */
+    protected onInitialize(context: InitializationContext): Promise<void>;
+    /**
+     * Process content by finding and executing all form elements
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Content with forms processed
+     */
+    process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Handle a specific form element
+     * @param matchInfo - Form element match information
+     * @param context - Parse context
+     * @returns Form element HTML
+     */
+    private handleElement;
+    /**
+     * Parse form parameters from string
+     */
+    private parseFormParameters;
+    /**
+     * Handle FormOpen element
+     * @param params - Form parameters
+     * @param context - Parse context
+     * @returns Form opening HTML
+     */
+    private handleFormOpen;
+    /**
+     * Handle FormInput element
+     * @param params - Input parameters
+     * @returns Input field HTML
+     */
+    private handleFormInput;
+    /**
+     * Handle FormSelect element
+     * @param params - Select parameters
+     * @returns Select field HTML
+     */
+    private handleFormSelect;
+    /**
+     * Handle FormTextarea element
+     * @param params - Textarea parameters
+     * @returns Textarea HTML
+     */
+    private handleFormTextarea;
+    /**
+     * Handle FormButton element
+     * @param params - Button parameters
+     * @returns Button HTML
+     */
+    private handleFormButton;
+    /**
+     * Handle FormClose element
+     * @param params - Close parameters (usually empty)
+     * @returns Form closing HTML
+     */
+    private handleFormClose;
+    /**
+     * Generate CSRF token for form security
+     * @param context - Parse context
+     * @returns CSRF token
+     */
+    private generateCSRFToken;
+    /**
+     * Validate form submission (for future form processing endpoint)
+     * @param formData - Submitted form data
+     * @param csrfToken - CSRF token from form
+     * @param context - Parse context
+     * @returns Validation result
+     */
+    validateFormSubmission(formData: Record<string, string>, csrfToken: string, context: FormParseContext): FormValidationResult;
+    /**
+     * Sanitize form data to prevent XSS
+     * @param formData - Raw form data
+     * @returns Sanitized form data
+     */
+    private sanitizeFormData;
+    /**
+     * Escape HTML characters to prevent XSS
+     * @param text - Text to escape
+     * @returns Escaped text
+     */
+    private escapeHtml;
+    /**
+     * Capitalize first letter of string
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     */
+    private capitalize;
+    /**
+     * Get supported form patterns
+     * @returns Array of supported patterns
+     */
+    getSupportedPatterns(): string[];
+    /**
+     * Get supported input types
+     * @returns Array of supported input types
+     */
+    getSupportedInputTypes(): string[];
+    /**
+     * Get handler information for debugging and documentation
+     * @returns Handler information
+     */
+    getInfo(): Record<string, unknown>;
+}
+export default WikiFormHandler;