@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/dom/WikiDocument.d.ts

@@ -0,0 +1,272 @@
+/**
+ * WikiDocument - Internal DOM representation of a wiki page
+ *
+ * Similar to JSPWiki's WikiDocument (org.apache.wiki.parser.WikiDocument)
+ * which extends JDOM2 Document. This provides a DOM-based alternative to
+ * string-based parsing, eliminating order-dependency issues.
+ *
+ * Key Features:
+ * - DOM-based structure (using linkedom for performance)
+ * - Cacheable representation
+ * - Metadata storage
+ * - WeakRef context for garbage collection
+ * - Standard W3C DOM API
+ *
+ * JSPWiki Reference:
+ * https://jspwiki.apache.org/apidocs/2.12.1/org/apache/wiki/parser/WikiDocument.html
+ *
+ * Related: GitHub Issue #93 - Migrate to WikiDocument DOM-Based Parsing
+ */
+import type { LinkedomElement, LinkedomText, LinkedomComment, LinkedomNode, LinkedomNodeList, LinkedomHTMLCollection } from 'linkedom';
+export type { LinkedomElement, LinkedomText, LinkedomComment, LinkedomNode, LinkedomNodeList, LinkedomHTMLCollection };
+/**
+ * WikiDocument metadata
+ */
+export interface WikiDocumentMetadata {
+    createdAt: string;
+    version: string;
+    [key: string]: unknown;
+}
+/**
+ * JSON serialization format
+ */
+export interface WikiDocumentJSON {
+    pageData: string;
+    html: string;
+    metadata: WikiDocumentMetadata;
+    version: string;
+    timestamp: string;
+}
+/**
+ * Document statistics
+ */
+export interface WikiDocumentStatistics {
+    nodeCount: number;
+    pageDataLength: number;
+    htmlLength: number;
+    hasContext: boolean;
+    metadata: number;
+}
+/**
+ * Rendering context (minimal interface)
+ * TODO: Replace with proper WikiContext import once converted
+ */
+export interface WikiContext {
+    pageName?: string;
+    userName?: string;
+    [key: string]: unknown;
+}
+/**
+ * WikiDocument - DOM-based representation of a wiki page
+ */
+declare class WikiDocument {
+    private document;
+    private root;
+    private pageData;
+    private contextRef;
+    private metadata;
+    /**
+     * Creates a new WikiDocument
+     *
+     * @param pageData - Original wiki markup content
+     * @param context - Rendering context (stored as WeakRef)
+     */
+    constructor(pageData: string, context?: WikiContext);
+    /**
+     * Gets the root element of the document
+     *
+     * @returns Root element (body)
+     */
+    getRootElement(): LinkedomElement;
+    /**
+     * Gets the original wiki markup
+     *
+     * JSPWiki equivalent: getPageData()
+     *
+     * @returns Original page data
+     */
+    getPageData(): string;
+    /**
+     * Sets the original wiki markup
+     *
+     * JSPWiki equivalent: setPageData(String data)
+     *
+     * @param data - Wiki markup
+     */
+    setPageData(data: string): void;
+    /**
+     * Gets the rendering context (if still alive)
+     *
+     * JSPWiki equivalent: getContext()
+     *
+     * @returns Context object or null if garbage collected
+     */
+    getContext(): WikiContext | null;
+    /**
+     * Sets the rendering context
+     *
+     * JSPWiki equivalent: setContext(Context ctx)
+     *
+     * @param context - Rendering context
+     */
+    setContext(context: WikiContext | null): void;
+    /**
+     * Gets all metadata
+     *
+     * @returns Metadata object
+     */
+    getMetadata(): WikiDocumentMetadata;
+    /**
+     * Sets a metadata value
+     *
+     * @param key - Metadata key
+     * @param value - Metadata value
+     */
+    setMetadata(key: string, value: unknown): void;
+    /**
+     * Gets a metadata value
+     *
+     * @param key - Metadata key
+     * @param defaultValue - Default value if not found
+     * @returns Metadata value or default
+     */
+    getMetadataValue(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Creates a new element
+     *
+     * @param tag - Element tag name
+     * @param attributes - Element attributes
+     * @returns New element
+     */
+    createElement(tag: string, attributes?: Record<string, string>): LinkedomElement;
+    /**
+     * Creates a text node
+     *
+     * @param text - Text content
+     * @returns New text node
+     */
+    createTextNode(text: string): LinkedomText;
+    /**
+     * Creates a comment node
+     *
+     * @param text - Comment text
+     * @returns New comment node
+     */
+    createCommentNode(text: string): LinkedomComment;
+    /**
+     * Appends a child to the root element
+     *
+     * @param node - Node to append
+     * @returns Appended node
+     */
+    appendChild(node: LinkedomNode): LinkedomNode;
+    /**
+     * Inserts a node before a reference node in root
+     *
+     * @param newNode - Node to insert
+     * @param referenceNode - Reference node
+     * @returns Inserted node
+     */
+    insertBefore(newNode: LinkedomNode, referenceNode: LinkedomNode | null): LinkedomNode;
+    /**
+     * Removes a child from the root element
+     *
+     * @param node - Node to remove
+     * @returns Removed node
+     */
+    removeChild(node: LinkedomNode): LinkedomNode;
+    /**
+     * Replaces a child in the root element
+     *
+     * @param newNode - New node
+     * @param oldNode - Old node to replace
+     * @returns Replaced node
+     */
+    replaceChild(newNode: LinkedomNode, oldNode: LinkedomNode): LinkedomNode;
+    /**
+     * Queries for a single element
+     *
+     * @param selector - CSS selector
+     * @returns First matching element or null
+     */
+    querySelector(selector: string): LinkedomElement | null;
+    /**
+     * Queries for all matching elements
+     *
+     * @param selector - CSS selector
+     * @returns Matching elements
+     */
+    querySelectorAll(selector: string): LinkedomNodeList;
+    /**
+     * Gets element by ID
+     *
+     * @param id - Element ID
+     * @returns Element or null
+     */
+    getElementById(id: string): LinkedomElement | null;
+    /**
+     * Gets elements by class name
+     *
+     * @param className - Class name
+     * @returns Elements with class
+     */
+    getElementsByClassName(className: string): LinkedomHTMLCollection;
+    /**
+     * Gets elements by tag name
+     *
+     * @param tagName - Tag name
+     * @returns Elements with tag
+     */
+    getElementsByTagName(tagName: string): LinkedomHTMLCollection;
+    /**
+     * Serializes the document to HTML string
+     *
+     * JSPWiki equivalent: XHTMLRenderer.render()
+     *
+     * @returns HTML string
+     */
+    toHTML(): string;
+    /**
+     * Serializes to string (for debugging)
+     *
+     * @returns String representation
+     */
+    toString(): string;
+    /**
+     * Serializes to JSON (for caching)
+     *
+     * @returns JSON representation
+     */
+    toJSON(): WikiDocumentJSON;
+    /**
+     * Deserializes from JSON (for cache restore)
+     *
+     * @param json - JSON data
+     * @param context - Rendering context
+     * @returns Restored WikiDocument
+     */
+    static fromJSON(json: WikiDocumentJSON, context?: WikiContext | null): WikiDocument;
+    /**
+     * Clears all content from the document
+     */
+    clear(): void;
+    /**
+     * Gets the number of child nodes in root
+     *
+     * @returns Number of children
+     */
+    getChildCount(): number;
+    /**
+     * Checks if the document is empty
+     *
+     * @returns True if empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets document statistics
+     *
+     * @returns Statistics
+     */
+    getStatistics(): WikiDocumentStatistics;
+}
+export default WikiDocument;

package/lib/src/parsers/dom/handlers/DOMLinkHandler.d.ts

@@ -0,0 +1,260 @@
+/**
+ * DOMLinkHandler - DOM-based link processing handler
+ *
+ * Replaces string-based regex link processing with DOM queries.
+ * Processes wiki links by querying WikiDocument for .wiki-link elements
+ * and updating them with proper href, classes, and attributes based on link type.
+ *
+ * Part of Phase 5 of WikiDocument DOM Migration (GitHub Issue #108)
+ *
+ * Supports:
+ * - 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"]
+ *
+ * Usage:
+ *   In wiki markup: [Display|Target] becomes <a class="wiki-link" data-wiki-link="Target">
+ *   This handler processes those elements and sets proper href, class, etc.
+ */
+import type WikiDocument from '../WikiDocument.js';
+import type { LinkedomElement } from '../WikiDocument.js';
+/**
+ * Link type enumeration
+ */
+export type LinkType = 'internal' | 'external' | 'interwiki' | 'email' | 'anchor';
+/**
+ * Link information object
+ */
+export interface LinkInfo {
+    /** Display text for the link */
+    text: string;
+    /** Link target */
+    target: string;
+    /** Link attributes */
+    attributes: Record<string, string>;
+    /** Original wiki syntax */
+    originalText: string;
+}
+/**
+ * InterWiki site configuration
+ */
+export interface InterWikiSite {
+    /** URL template with %s placeholder */
+    url: string;
+    /** Site description */
+    description?: string;
+    /** Site icon */
+    icon?: string;
+    /** Whether site is enabled */
+    enabled?: boolean;
+    /** Whether to open links in new window */
+    openInNewWindow?: boolean;
+}
+/**
+ * WikiEngine interface (minimal)
+ */
+interface WikiEngine {
+    /** Get a manager by name */
+    getManager(name: string): unknown;
+    /** Additional engine properties */
+    [key: string]: unknown;
+}
+/**
+ * Extracted link element from JSPWiki syntax extraction
+ */
+export interface ExtractedLinkElement {
+    /** Element type */
+    type: string;
+    /** Link target (may include pipe syntax: "Display|Target") */
+    target: string;
+    /** Unique ID for tracking */
+    id: number;
+    /** Original syntax */
+    syntax?: string;
+    /** Original text */
+    originalText?: string;
+    /** Start index in content */
+    startIndex?: number;
+    /** End index in content */
+    endIndex?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Rendering context
+ */
+export interface RenderContext {
+    /** Page name */
+    pageName?: string;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Link statistics by type
+ */
+export interface LinkTypeStats {
+    /** Number of internal links */
+    internal: number;
+    /** Number of external links */
+    external: number;
+    /** Number of InterWiki links */
+    interwiki: number;
+    /** Number of email links */
+    email: number;
+    /** Number of anchor links */
+    anchor: number;
+    /** Number of error links */
+    error: number;
+}
+/**
+ * Link processing statistics
+ */
+export interface LinkStatistics {
+    /** Total number of links */
+    totalLinks: number;
+    /** Link counts by type */
+    linkTypes: LinkTypeStats;
+    /** Number of red links (non-existent pages) */
+    redLinks: number;
+}
+/**
+ * DOMLinkHandler class
+ */
+declare class DOMLinkHandler {
+    /** WikiEngine instance */
+    private engine;
+    /** LinkParser instance */
+    private linkParser;
+    /** PageManager instance */
+    private pageManager;
+    /** Set of available page names */
+    private pageNames;
+    /** Page name matcher for fuzzy matching */
+    private pageNameMatcher;
+    /**
+     * Creates a new DOMLinkHandler
+     *
+     * @param {WikiEngine} engine - WikiEngine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initializes the handler
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load page names from PageManager
+     */
+    loadPageNames(): Promise<void>;
+    /**
+     * Load InterWiki site configuration
+     */
+    loadInterWikiConfiguration(): void;
+    /**
+     * Processes links in a WikiDocument
+     *
+     * Queries for .wiki-link elements and updates them with proper href and attributes.
+     * This is the DOM-based equivalent of LinkParserHandler.process()
+     *
+     * @param {WikiDocument} wikiDocument - The WikiDocument to process
+     * @param {RenderContext} context - Rendering context
+     * @returns {Promise<WikiDocument>} Updated WikiDocument
+     */
+    processLinks(wikiDocument: WikiDocument, context: RenderContext): Promise<WikiDocument>;
+    /**
+     * Process a link element based on its type
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param linkType - Link type
+     * @param context - Rendering context
+     */
+    processLinkByType(linkElement: LinkedomElement, linkInfo: LinkInfo, linkType: LinkType, context: RenderContext): Promise<void>;
+    /**
+     * Process internal wiki link
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param _context - Rendering context (unused)
+     */
+    processInternalLink(linkElement: LinkedomElement, linkInfo: LinkInfo, _context: RenderContext): void;
+    /**
+     * Process external link
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param _context - Rendering context (unused)
+     */
+    processExternalLink(linkElement: LinkedomElement, linkInfo: LinkInfo, _context: RenderContext): void;
+    /**
+     * Process InterWiki link
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param _context - Rendering context (unused)
+     */
+    processInterWikiLink(linkElement: LinkedomElement, linkInfo: LinkInfo, _context: RenderContext): void;
+    /**
+     * Process email link
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param _context - Rendering context (unused)
+     */
+    processEmailLink(linkElement: LinkedomElement, linkInfo: LinkInfo, _context: RenderContext): void;
+    /**
+     * Process anchor link
+     *
+     * @param linkElement - The link DOM element
+     * @param linkInfo - Link information
+     * @param _context - Rendering context (unused)
+     */
+    processAnchorLink(linkElement: LinkedomElement, linkInfo: LinkInfo, _context: RenderContext): void;
+    /**
+     * Creates a DOM node from an extracted link element
+     *
+     * This method is part of the Phase 2 extraction-based parsing (Issue #114).
+     * It creates a link node from a pre-extracted element instead of parsing tokens.
+     *
+     * @param {ExtractedLinkElement} element - Extracted element from extractJSPWikiSyntax()
+     * @param {RenderContext} context - Rendering context; `pageOwner` selects the store a `[store/Title]` link resolves in (#1457)
+     * @param {WikiDocument} wikiDocument - WikiDocument to create node in
+     * @returns {Promise<Element>} DOM node for the link
+     *
+     * @example
+     * const element = { type: 'link', target: 'PageName', id: 0, ... };
+     * const node = await handler.createNodeFromExtract(element, context, wikiDoc);
+     * // Returns: <a class="wiki-link wikipage" href="/view/PageName" data-jspwiki-id="0">PageName</a>
+     *
+     * @example
+     * const element = { type: 'link', target: 'Click Here|PageName', id: 1, ... };
+     * const node = await handler.createNodeFromExtract(element, context, wikiDoc);
+     * // Returns: <a class="wiki-link wikipage" href="/view/PageName" data-jspwiki-id="1">Click Here</a>
+     */
+    createNodeFromExtract(element: ExtractedLinkElement, context: RenderContext, wikiDocument: WikiDocument): Promise<LinkedomElement>;
+    /**
+     * Gets statistics about link processing
+     *
+     * @param {WikiDocument} wikiDocument - Document to analyze
+     * @returns {LinkStatistics} Statistics
+     */
+    getStatistics(wikiDocument: WikiDocument): LinkStatistics;
+    /**
+     * Refresh page names cache (called when pages are added/removed)
+     */
+    refreshPageNames(): Promise<void>;
+    /**
+     * Add a single page name to the known pages set (incremental update on page create/rename).
+     * Avoids the full getAllPages() reload cost of refreshPageNames().
+     * @param {string} pageName - Page name to add
+     */
+    addPageName(pageName: string): void;
+    /**
+     * Remove a single page name from the known pages set (incremental update on page delete/rename).
+     * @param {string} pageName - Page name to remove
+     */
+    removePageName(pageName: string): void;
+}
+export default DOMLinkHandler;