ribbit/src/ts/ribbit.ts

/*
 * ribbit.ts — core editor classes for the ribbit WYSIWYG markdown editor.
 */

import { HopDown } from './hopdown';
import { defaultTheme } from './default-theme';
import { ThemeManager } from './theme-manager';
import { RibbitEmitter, type RibbitEventMap } from './events';
import type { RibbitTheme } from './types';

export interface RibbitSettings {
    api?: unknown;
    editorId?: string;
    plugins?: Array<{ new(settings: { name: string; wiki: Ribbit }): RibbitPlugin; name: string }>;
    currentTheme?: string;
    themes?: RibbitTheme[];
    themesPath?: string;
    on?: Partial<RibbitEventMap>;
}

/**
 * Base class for editor plugins. Subclass and override toHTML/toMarkdown
 * to add custom processing hooks.
 */
export class RibbitPlugin {
    name: string;
    wiki: Ribbit;
    precedence: number;

    constructor(settings: { name: string; wiki: Ribbit }) {
        this.name = settings.name;
        this.wiki = settings.wiki;
        this.precedence = 50;
    }

    setEditable(): void {
    }

    toMarkdown(html: string): string {
        return html;
    }

    toHTML(md: string): string {
        return md;
    }
}

/**
 * Read-only markdown viewer. Renders markdown content into an HTML element.
 *
 * Usage:
 *   const viewer = new Ribbit({
 *       editorId: 'my-element',
 *       on: {
 *           ready: ({ mode, theme }) => console.log(`Ready in ${mode}`),
 *       },
 *   });
 *   viewer.run();
 */
export class Ribbit {
    api: unknown;
    element: HTMLElement;
    states: Record<string, string>;
    cachedHTML: string | null;
    cachedMarkdown: string | null;
    state: string | null;
    changed: boolean;
    enabledPlugins: Record<string, RibbitPlugin>;
    theme: RibbitTheme;
    themes: ThemeManager;
    converter: HopDown;
    themesPath: string;
    private emitter: RibbitEmitter;

    constructor(settings: RibbitSettings) {
        this.api = settings.api || null;
        this.element = document.getElementById(settings.editorId || 'ribbit')!;
        this.themesPath = settings.themesPath || './themes';
        this.emitter = new RibbitEmitter();
        this.states = {
            VIEW: 'view',
        };
        this.cachedHTML = null;
        this.cachedMarkdown = null;
        this.state = null;
        this.changed = false;
        this.enabledPlugins = {};

        this.themes = new ThemeManager(defaultTheme, this.themesPath, (theme, previous) => {
            this.theme = theme;
            this.converter = theme.tags
                ? new HopDown({ tags: theme.tags })
                : new HopDown();
            this.cachedHTML = null;
            this.emitter.emit('themeChange', {
                current: theme,
                previous,
            });
            if (this.getState() === this.states.VIEW) {
                this.state = null;
                this.view();
            }
        });

        (settings.themes || []).forEach(theme => {
            this.themes.add(theme);
        });

        const activeName = settings.currentTheme || defaultTheme.name;
        this.themes.set(activeName);
        this.theme = this.themes.current();
        this.converter = this.theme.tags
            ? new HopDown({ tags: this.theme.tags })
            : new HopDown();

        (settings.plugins || []).forEach(plugin => {
            this.enabledPlugins[plugin.name] = new plugin({
                name: plugin.name,
                wiki: this,
            });
        });

        if (settings.on) {
            for (const [event, handler] of Object.entries(settings.on)) {
                if (handler) {
                    this.on(event as keyof RibbitEventMap, handler as any);
                }
            }
        }
    }

    /**
     * Register a callback for an event.
     *
     *   editor.on('save', ({ markdown }) => {
     *       fetch('/api/save', { method: 'POST', body: markdown });
     *   });
     */
    on<K extends keyof RibbitEventMap>(event: K, callback: RibbitEventMap[K]): void {
        this.emitter.on(event, callback);
    }

    /**
     * Remove a previously registered callback.
     *
     *   editor.off('change', myHandler);
     */
    off<K extends keyof RibbitEventMap>(event: K, callback: RibbitEventMap[K]): void {
        this.emitter.off(event, callback);
    }

    run(): void {
        this.element.classList.add('loaded');
        this.view();
        this.emitter.emit('ready', {
            markdown: this.getMarkdown(),
            html: this.getHTML(),
            mode: this.state || 'view',
            theme: this.theme,
        });
    }

    plugins(): RibbitPlugin[] {
        return Object.values(this.enabledPlugins).sort((a, b) => a.precedence - b.precedence);
    }

    getState(): string | null {
        return this.state;
    }

    setState(newState: string): void {
        const previous = this.state;
        this.state = newState;
        Object.values(this.states).forEach(state => {
            if (state === newState) {
                this.element.classList.add(state);
            } else {
                this.element.classList.remove(state);
            }
        });
        this.emitter.emit('modeChange', {
            current: newState,
            previous,
        });
    }

    markdownToHTML(md: string): string {
        return this.converter.toHTML(md);
    }

    getHTML(): string {
        if (this.changed || !this.cachedHTML) {
            this.cachedHTML = this.markdownToHTML(this.getMarkdown());
        }
        return this.cachedHTML;
    }

    getMarkdown(): string {
        if (!this.cachedMarkdown) {
            this.cachedMarkdown = this.element.textContent || '';
        }
        return this.cachedMarkdown;
    }

    /**
     * Request a save. Fires the 'save' event with the current content.
     * The consumer's callback handles persistence.
     *
     *   editor.save();  // triggers on.save({ markdown, html })
     */
    save(): void {
        this.emitter.emit('save', {
            markdown: this.getMarkdown(),
            html: this.getHTML(),
        });
    }

    view(): void {
        if (this.getState() === this.states.VIEW) return;
        this.element.innerHTML = this.getHTML();
        this.setState(this.states.VIEW);
        this.element.contentEditable = 'false';
    }

    /**
     * Notify that content has changed. Called internally by the editor
     * on input events. Fires the 'change' event with current content.
     */
    notifyChange(): void {
        this.changed = true;
        this.emitter.emit('change', {
            markdown: this.getMarkdown(),
            html: this.getHTML(),
        });
    }
}

/**
 * Convert a string to title case, splitting on whitespace.
 * Returns an array of capitalized words.
 */
export function camelCase(words: string): string[] {
    return words.trim().split(/\s+/g).map(word => {
        const lc = word.toLowerCase();
        return lc.charAt(0).toUpperCase() + lc.slice(1);
    });
}

/**
 * Decode HTML entities in a string using a textarea element.
 */
export function decodeHtmlEntities(html: string): string {
    const txt = document.createElement('textarea');
    txt.innerHTML = html;
    return txt.value;
}

/**
 * Encode HTML-significant characters as numeric entities.
 */
export function encodeHtmlEntities(str: string): string {
    return str.replace(/[\u00A0-\u9999<>&]/g, i => '&#' + i.charCodeAt(0) + ';');
}