@rtif-sdk/web 1.0.0

package/dist/shortcut-handler.js

@@ -0,0 +1,155 @@
+/**
+ * Keyboard shortcut handler for the RTIF web editor.
+ *
+ * Reads shortcut bindings from the engine and intercepts `keydown` events
+ * to dispatch the corresponding commands through the {@link CommandBus}.
+ * Uses platform-aware modifier key detection (Cmd on Mac, Ctrl on Win/Linux).
+ *
+ * The shortcut handler fires BEFORE the cursor-nav handler's keydown listener,
+ * so plugin-registered shortcuts take priority over built-in navigation.
+ *
+ * @module
+ */
+import { isMac } from './cursor-nav.js';
+// ---------------------------------------------------------------------------
+// ShortcutHandler
+// ---------------------------------------------------------------------------
+/**
+ * Intercepts `keydown` events and matches them against engine-registered
+ * keyboard shortcuts.
+ *
+ * When a match is found, the corresponding command is executed via the
+ * command bus and the event is prevented/stopped.
+ *
+ * @example
+ * ```ts
+ * const handler = new ShortcutHandler(root, {
+ *   getShortcuts: () => engine.getShortcuts(),
+ *   commandBus: bus,
+ *   isComposing: () => compositionHandler.isComposing(),
+ * });
+ * handler.attach();
+ * ```
+ */
+export class ShortcutHandler {
+    _root;
+    _deps;
+    _attached = false;
+    _boundHandler;
+    constructor(root, deps) {
+        this._root = root;
+        this._deps = deps;
+        this._boundHandler = (e) => this._handleKeyDown(e);
+    }
+    /**
+     * Attach the `keydown` event listener to the root element.
+     *
+     * Uses `capture: true` so shortcuts fire before other keydown handlers.
+     *
+     * @example
+     * ```ts
+     * handler.attach();
+     * ```
+     */
+    attach() {
+        if (this._attached)
+            return;
+        this._root.addEventListener('keydown', this._boundHandler, true);
+        this._attached = true;
+    }
+    /**
+     * Remove the `keydown` event listener.
+     *
+     * @example
+     * ```ts
+     * handler.detach();
+     * ```
+     */
+    detach() {
+        if (!this._attached)
+            return;
+        this._root.removeEventListener('keydown', this._boundHandler, true);
+        this._attached = false;
+    }
+    _handleKeyDown(e) {
+        // Suppress shortcuts during IME composition
+        if (this._deps.isComposing())
+            return;
+        const shortcuts = this._deps.getShortcuts();
+        if (shortcuts.length === 0)
+            return;
+        for (const binding of shortcuts) {
+            if (matchesShortcut(e, binding)) {
+                // Check canExecute before consuming the event — if the command
+                // cannot execute (e.g., Tab outside a list), let the event pass
+                // through to the browser.
+                let canExec = true;
+                try {
+                    canExec = this._deps.commandBus.canExecute(binding.command, binding.payload);
+                }
+                catch {
+                    /* default to allowing */
+                }
+                if (!canExec)
+                    continue;
+                e.preventDefault();
+                e.stopPropagation();
+                this._deps.commandBus.execute(binding.command, binding.payload);
+                return;
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a keyboard event matches a shortcut binding.
+ *
+ * Platform-aware: `mod` matches `metaKey` on Mac, `ctrlKey` on other platforms.
+ *
+ * @param e - The keyboard event
+ * @param binding - The shortcut binding to match against
+ * @returns Whether the event matches the binding
+ *
+ * @example
+ * ```ts
+ * const matches = matchesShortcut(event, {
+ *   descriptor: { key: 'b', mod: true },
+ *   command: 'toggleBold',
+ * });
+ * ```
+ */
+export function matchesShortcut(e, binding) {
+    const desc = binding.descriptor;
+    // Key comparison (case-insensitive for single characters)
+    if (e.key.toLowerCase() !== desc.key.toLowerCase())
+        return false;
+    // Platform modifier: Cmd on Mac, Ctrl on others
+    const mac = isMac();
+    const modRequired = desc.mod ?? false;
+    const modPressed = mac ? e.metaKey : e.ctrlKey;
+    if (modRequired !== modPressed)
+        return false;
+    // On Mac, if mod is required (metaKey), we don't also require ctrlKey to be false,
+    // but we do check the other modifiers
+    const shiftRequired = desc.shift ?? false;
+    if (shiftRequired !== e.shiftKey)
+        return false;
+    const altRequired = desc.alt ?? false;
+    if (altRequired !== e.altKey)
+        return false;
+    // Reject if extra modifier keys are held that aren't required
+    // On Mac: ctrl shouldn't be pressed (unless it's not a mod shortcut)
+    // On Win/Linux: meta shouldn't be pressed
+    if (mac && !modRequired && e.metaKey)
+        return false;
+    if (!mac && !modRequired && e.ctrlKey)
+        return false;
+    if (mac && e.ctrlKey && modRequired)
+        return false; // Ctrl+Cmd combo not expected
+    if (!mac && e.metaKey)
+        return false;
+    return true;
+}
+//# sourceMappingURL=shortcut-handler.js.map

package/dist/shortcut-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut-handler.js","sourceRoot":"","sources":["../src/shortcut-handler.ts"],"names":[],"mappings":"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"}

package/dist/toolbar.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Fixed toolbar primitive for the RTIF web editor.
+ *
+ * Renders a horizontal toolbar with buttons that execute editor commands.
+ * Button state (active, disabled) updates live via the {@link CommandBus}.
+ * Uses `mousedown` + `preventDefault()` to avoid stealing focus from the editor.
+ *
+ * @module
+ */
+import type { CommandBus } from './command-bus.js';
+/**
+ * Type-safe constants for common toolbar group names.
+ *
+ * Use these when building `ToolbarButtonConfig` arrays to ensure consistent
+ * grouping across your toolbar.
+ *
+ * @example
+ * ```ts
+ * const buttons: ToolbarButtonConfig[] = [
+ *   { command: 'undo', icon: '↩', label: 'Undo', group: ToolbarGroup.HISTORY },
+ *   { command: 'toggleMark:bold', icon: 'B', label: 'Bold', group: ToolbarGroup.MARKS },
+ * ];
+ * ```
+ */
+export declare const ToolbarGroup: {
+    readonly HISTORY: "history";
+    readonly MARKS: "marks";
+    readonly BLOCKS: "blocks";
+    readonly INSERT: "insert";
+    readonly ALIGN: "align";
+    readonly INDENT: "indent";
+    readonly STYLE: "style";
+};
+/**
+ * Configuration for a single toolbar button.
+ *
+ * @example
+ * ```ts
+ * const boldButton: ToolbarButtonConfig = {
+ *   command: 'toggleMark:bold',
+ *   icon: 'B',
+ *   label: 'Bold',
+ *   group: 'format',
+ * };
+ * ```
+ */
+export interface ToolbarButtonConfig {
+    /** The command to execute when the button is clicked */
+    readonly command: string;
+    /** Optional payload to pass to the command handler */
+    readonly payload?: unknown;
+    /** Icon text or HTML to display in the button (e.g., "B", "<svg>...") */
+    readonly icon: string;
+    /** Accessible label for the button */
+    readonly label: string;
+    /** Optional group name for visual grouping (rendered as a separator between groups) */
+    readonly group?: string;
+}
+/**
+ * Handle returned by `createToolbar()` for lifecycle management.
+ *
+ * @example
+ * ```ts
+ * const toolbar = createToolbar(container, bus, buttons);
+ * // ... later:
+ * toolbar.destroy();
+ * ```
+ */
+export interface ToolbarHandle {
+    /** The toolbar's root DOM element */
+    readonly element: HTMLElement;
+    /** Remove all event listeners and subscriptions. Idempotent. */
+    destroy(): void;
+}
+/**
+ * Create a fixed toolbar with command-driven buttons.
+ *
+ * Buttons reflect live command state:
+ * - `aria-pressed="true"` when the command's `isActive` returns true
+ * - `aria-disabled="true"` when the command's `canExecute` returns false
+ *
+ * The toolbar subscribes to the CommandBus for automatic state updates.
+ *
+ * @param container - The DOM element to render the toolbar into
+ * @param bus - The CommandBus to execute commands and query state
+ * @param buttons - Array of button configurations
+ * @returns A ToolbarHandle for lifecycle management
+ *
+ * @example
+ * ```ts
+ * const toolbar = createToolbar(
+ *   document.getElementById('toolbar')!,
+ *   bus,
+ *   [
+ *     { command: 'toggleMark:bold', icon: 'B', label: 'Bold', group: 'format' },
+ *     { command: 'toggleMark:italic', icon: 'I', label: 'Italic', group: 'format' },
+ *     { command: 'undo', icon: '↩', label: 'Undo', group: 'history' },
+ *   ],
+ * );
+ * ```
+ */
+export declare function createToolbar(container: HTMLElement, bus: CommandBus, buttons: ReadonlyArray<ToolbarButtonConfig>): ToolbarHandle;
+//# sourceMappingURL=toolbar.d.ts.map

package/dist/toolbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar.d.ts","sourceRoot":"","sources":["../src/toolbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC;AAMX;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,EACtB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC1C,aAAa,CA+Ef"}

package/dist/toolbar.js

@@ -0,0 +1,134 @@
+/**
+ * Fixed toolbar primitive for the RTIF web editor.
+ *
+ * Renders a horizontal toolbar with buttons that execute editor commands.
+ * Button state (active, disabled) updates live via the {@link CommandBus}.
+ * Uses `mousedown` + `preventDefault()` to avoid stealing focus from the editor.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Toolbar group constants
+// ---------------------------------------------------------------------------
+/**
+ * Type-safe constants for common toolbar group names.
+ *
+ * Use these when building `ToolbarButtonConfig` arrays to ensure consistent
+ * grouping across your toolbar.
+ *
+ * @example
+ * ```ts
+ * const buttons: ToolbarButtonConfig[] = [
+ *   { command: 'undo', icon: '↩', label: 'Undo', group: ToolbarGroup.HISTORY },
+ *   { command: 'toggleMark:bold', icon: 'B', label: 'Bold', group: ToolbarGroup.MARKS },
+ * ];
+ * ```
+ */
+export const ToolbarGroup = {
+    HISTORY: 'history',
+    MARKS: 'marks',
+    BLOCKS: 'blocks',
+    INSERT: 'insert',
+    ALIGN: 'align',
+    INDENT: 'indent',
+    STYLE: 'style',
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a fixed toolbar with command-driven buttons.
+ *
+ * Buttons reflect live command state:
+ * - `aria-pressed="true"` when the command's `isActive` returns true
+ * - `aria-disabled="true"` when the command's `canExecute` returns false
+ *
+ * The toolbar subscribes to the CommandBus for automatic state updates.
+ *
+ * @param container - The DOM element to render the toolbar into
+ * @param bus - The CommandBus to execute commands and query state
+ * @param buttons - Array of button configurations
+ * @returns A ToolbarHandle for lifecycle management
+ *
+ * @example
+ * ```ts
+ * const toolbar = createToolbar(
+ *   document.getElementById('toolbar')!,
+ *   bus,
+ *   [
+ *     { command: 'toggleMark:bold', icon: 'B', label: 'Bold', group: 'format' },
+ *     { command: 'toggleMark:italic', icon: 'I', label: 'Italic', group: 'format' },
+ *     { command: 'undo', icon: '↩', label: 'Undo', group: 'history' },
+ *   ],
+ * );
+ * ```
+ */
+export function createToolbar(container, bus, buttons) {
+    // Create the toolbar element
+    const toolbar = container.ownerDocument.createElement('div');
+    toolbar.setAttribute('role', 'toolbar');
+    toolbar.setAttribute('aria-label', 'Editor toolbar');
+    // Track button elements for state updates
+    const buttonElements = [];
+    let lastGroup;
+    for (const config of buttons) {
+        // Add separator between groups
+        if (config.group !== undefined && config.group !== lastGroup && lastGroup !== undefined) {
+            const separator = container.ownerDocument.createElement('span');
+            separator.setAttribute('role', 'separator');
+            separator.setAttribute('aria-orientation', 'vertical');
+            separator.className = 'rtif-toolbar-separator';
+            toolbar.appendChild(separator);
+        }
+        lastGroup = config.group;
+        const btn = container.ownerDocument.createElement('button');
+        btn.type = 'button';
+        btn.setAttribute('aria-label', config.label);
+        btn.setAttribute('data-command', config.command);
+        btn.className = 'rtif-toolbar-button';
+        btn.innerHTML = config.icon;
+        // Prevent focus steal on mousedown
+        btn.addEventListener('mousedown', (e) => {
+            e.preventDefault();
+        });
+        // Execute command on click
+        btn.addEventListener('click', () => {
+            bus.execute(config.command, config.payload);
+        });
+        toolbar.appendChild(btn);
+        buttonElements.push({ el: btn, config });
+    }
+    container.appendChild(toolbar);
+    // Update button states
+    function updateStates() {
+        for (const { el, config } of buttonElements) {
+            const active = bus.isActive(config.command, config.payload);
+            const canExec = bus.canExecute(config.command, config.payload);
+            el.setAttribute('aria-pressed', String(active));
+            el.setAttribute('aria-disabled', String(!canExec));
+            el.disabled = !canExec;
+            if (active) {
+                el.classList.add('rtif-toolbar-active');
+            }
+            else {
+                el.classList.remove('rtif-toolbar-active');
+            }
+        }
+    }
+    // Initial state update
+    updateStates();
+    // Subscribe to state changes for live updates
+    const unsubscribe = bus.subscribe(() => updateStates());
+    let destroyed = false;
+    return {
+        element: toolbar,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            unsubscribe();
+            toolbar.remove();
+        },
+    };
+}
+//# sourceMappingURL=toolbar.js.map

package/dist/toolbar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar.js","sourceRoot":"","sources":["../src/toolbar.ts"],"names":[],"mappings":"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"}

package/dist/trigger-manager.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Generic trigger infrastructure for character-triggered interactions.
+ *
+ * Detects trigger characters (e.g., `@`, `#`, `/`), manages TriggerSession
+ * lifecycle, handles keyboard routing and dismissal. Fully reusable for
+ * @mentions, #hashtags, /slash-commands, etc.
+ *
+ * @module
+ */
+import type { IEditorEngine } from '@rtif-sdk/engine';
+import type { CursorRectAPI } from './cursor-rect.js';
+import type { Disposable } from './types.js';
+/** Reason a trigger session was deactivated. */
+export type TriggerDeactivateReason = 'accepted' | 'dismissed' | 'cursor-moved' | 'deleted';
+/** Position constraint for trigger activation. */
+export type TriggerPosition = 'start' | 'after-whitespace' | 'anywhere';
+/**
+ * Configuration for registering a trigger character.
+ *
+ * @example
+ * ```ts
+ * const config: TriggerConfig = {
+ *   id: 'mention',
+ *   char: '@',
+ *   onActivate(session) { showDropdown(session.query); },
+ *   onChange(session) { filterDropdown(session.query); },
+ *   onDeactivate(reason) { hideDropdown(); },
+ * };
+ * ```
+ */
+export interface TriggerConfig {
+    /** Unique identifier for this trigger. */
+    readonly id: string;
+    /** The trigger character (e.g., "@", "#", "/"). */
+    readonly char: string;
+    /**
+     * Position constraint for when the trigger activates.
+     * - `'start'` — Only at the start of a block.
+     * - `'after-whitespace'` — After whitespace or at block start.
+     * - `'anywhere'` — At any position.
+     *
+     * Default: `'after-whitespace'`.
+     */
+    readonly position?: TriggerPosition;
+    /** Called when a trigger session activates. */
+    readonly onActivate: (session: TriggerSession) => void;
+    /** Called when a trigger session deactivates. */
+    readonly onDeactivate?: (reason: TriggerDeactivateReason) => void;
+    /** Called when the query text changes during an active session. */
+    readonly onChange?: (session: TriggerSession) => void;
+    /**
+     * Called on keydown during an active session.
+     * Return `true` to stop event propagation (e.g., ArrowDown in dropdown).
+     * Return `false` to let the event propagate to the editor.
+     */
+    readonly onKeyDown?: (session: TriggerSession, event: KeyboardEvent) => boolean;
+    /**
+     * If true, the session is deactivated when the query contains a space.
+     * Default: false.
+     */
+    readonly cancelOnSpace?: boolean;
+    /**
+     * Called when the trigger position may have changed due to scroll or resize.
+     * Consumers should re-query `getTriggerRect()` / `getCursorRect()` and
+     * reposition their UI.
+     *
+     * Only fires while a session for this trigger is active.
+     */
+    readonly onPositionChange?: (session: TriggerSession) => void;
+}
+/**
+ * Represents an active trigger session.
+ *
+ * @example
+ * ```ts
+ * function handleActivate(session: TriggerSession) {
+ *   console.log('Trigger:', session.trigger.char, 'Query:', session.query);
+ *   const rect = session.getTriggerRect();
+ *   if (rect) positionDropdown(rect);
+ * }
+ * ```
+ */
+export interface TriggerSession {
+    /** The trigger configuration that activated this session. */
+    readonly trigger: Readonly<TriggerConfig>;
+    /** Absolute offset of the trigger character in the document. */
+    readonly triggerOffset: number;
+    /** Text between the trigger character and the cursor. */
+    readonly query: string;
+    /** Get the screen rect of the trigger character. */
+    getTriggerRect(): DOMRect | null;
+    /** Get the screen rect of the current cursor position. */
+    getCursorRect(): DOMRect | null;
+    /**
+     * Accept a result — replaces trigger+query with the result text/marks.
+     *
+     * @param result - The text and optional marks to insert
+     */
+    accept(result: TriggerAcceptResult): void;
+    /** Dismiss the session — leaves text as-is, closes session. */
+    dismiss(): void;
+    /** Returns true if this session is still active. */
+    isActive(): boolean;
+}
+/**
+ * The result passed to `session.accept()`.
+ *
+ * @example
+ * ```ts
+ * session.accept({
+ *   text: '@Alice Johnson',
+ *   marks: { mention: { id: 'user-123', displayName: 'Alice Johnson' } },
+ *   appendSpace: true,
+ * });
+ * ```
+ */
+export interface TriggerAcceptResult {
+    /** The text to insert in place of trigger+query. */
+    readonly text: string;
+    /** Optional marks to apply to the inserted text. */
+    readonly marks?: Record<string, unknown>;
+    /**
+     * Whether to append a space after the inserted text.
+     * Default: true.
+     */
+    readonly appendSpace?: boolean;
+}
+/**
+ * The TriggerManager interface.
+ *
+ * @example
+ * ```ts
+ * const manager = createTriggerManager(deps);
+ * const disposable = manager.register(mentionTriggerConfig);
+ * // later:
+ * disposable.dispose();
+ * manager.destroy();
+ * ```
+ */
+export interface TriggerManager {
+    /**
+     * Register a trigger character configuration.
+     *
+     * @param config - The trigger configuration
+     * @returns A disposable to unregister the trigger
+     */
+    register(config: TriggerConfig): Disposable;
+    /**
+     * Get the currently active trigger session, or null if none.
+     *
+     * @returns The active session, or null
+     */
+    getActiveSession(): TriggerSession | null;
+    /**
+     * Returns true if any trigger session is currently active.
+     *
+     * @returns Whether a session is active
+     */
+    isActive(): boolean;
+    /** Tear down the TriggerManager — removes all listeners. */
+    destroy(): void;
+}
+/**
+ * Dependencies injected into the TriggerManager.
+ *
+ * @example
+ * ```ts
+ * const deps: TriggerManagerDeps = {
+ *   root,
+ *   engine,
+ *   cursorRect,
+ *   isComposing: () => compositionHandler.isComposing(),
+ * };
+ * ```
+ */
+export interface TriggerManagerDeps {
+    /** The editor root element. */
+    readonly root: HTMLElement;
+    /** The RTIF engine instance. */
+    readonly engine: IEditorEngine;
+    /** The cursor rect API for positioning. */
+    readonly cursorRect: CursorRectAPI;
+    /** Whether an IME composition is in progress. */
+    readonly isComposing: () => boolean;
+}
+/**
+ * Create a TriggerManager instance.
+ *
+ * The trigger manager detects trigger characters, manages sessions,
+ * and handles keyboard routing. Attach its keydown listener BEFORE
+ * the shortcut handler for correct priority.
+ *
+ * @param deps - Dependencies for the trigger manager
+ * @returns A TriggerManager instance
+ *
+ * @example
+ * ```ts
+ * const triggerManager = createTriggerManager({
+ *   root, engine, cursorRect,
+ *   isComposing: () => compositionHandler.isComposing(),
+ * });
+ * ```
+ */
+export declare function createTriggerManager(deps: TriggerManagerDeps): TriggerManager;
+//# sourceMappingURL=trigger-manager.d.ts.map

package/dist/trigger-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-manager.d.ts","sourceRoot":"","sources":["../src/trigger-manager.ts"],"names":[],"mappings":"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"}