@rcarls/rc-textarea 0.1.0

package/dist/types/packages/rc-textarea/src/types.d.ts

@@ -0,0 +1,394 @@
+/**
+ * A styled inline range over characters [from, to).
+ * Rich formatting properties (bold, italic, color, etc.) are rendered as
+ * inline styles on the blot span; `className` adds an extra CSS class.
+ */
+export interface MarkDecoration {
+    id: string;
+    type: 'mark';
+    /** Inclusive start offset (0-based character index into plain text). */
+    from: number;
+    /** Exclusive end offset. */
+    to: number;
+    className?: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    background?: string;
+    underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';
+    underlineColor?: string;
+    attributes?: Record<string, string>;
+}
+/**
+ * A decoration applied to an entire logical line.
+ * Adds a CSS class and/or data attributes to the line div, and optionally
+ * appends an error-lens style annotation message at the end of the line.
+ */
+export interface LineDecoration {
+    id: string;
+    type: 'line';
+    /** 1-based logical line number. */
+    line: number;
+    className?: string;
+    /**
+     * Error-lens style annotation text shown at the end of the line.
+     * Rendered via `::after` pseudo-element on the line div (not a real DOM node),
+     * so it is completely excluded from selection and clipboard operations.
+     */
+    message?: string;
+    /**
+     * Space-separated CSS class name(s) applied to the `data-message-class` attribute
+     * on the line div. Use attribute selectors in CSS to style the message:
+     *
+     * ```css
+     * .v2-line[data-message-class~="error"][data-message]::after { color: red; }
+     * ```
+     */
+    messageClassName?: string;
+    attributes?: Record<string, string>;
+    /**
+     * Override the built-in gutter cell text for this line.
+     * - `string`    — custom label (e.g. `"!"`, `"▶"`)
+     * - `null`      — force empty cell (suppress built-in content)
+     * - `undefined` — use the built-in mode default (`line-numbers`, `list-numbers`, etc.)
+     */
+    gutterContent?: string | null;
+}
+/**
+ * A non-editable DOM element inserted at a character offset.
+ * Widgets are purely visual and do not appear in the plain text value.
+ */
+export interface WidgetDecoration {
+    id: string;
+    type: 'widget';
+    /** Character offset. Widget is placed before (or after) the character at this position. */
+    offset: number;
+    /** Factory called each render cycle. Must return a new element each time. */
+    create(): HTMLElement;
+    /** Whether to place the widget before or after the character at `offset`. Default: 'before'. */
+    side?: 'before' | 'after';
+}
+export type Decoration = MarkDecoration | LineDecoration | WidgetDecoration;
+export type DecorationInput = Omit<MarkDecoration, 'id'> | Omit<LineDecoration, 'id'> | Omit<WidgetDecoration, 'id'>;
+/**
+ * A semantic token produced by an external tokenizer (lezer, tree-sitter, shiki, etc.).
+ * Offsets are absolute character indices into the plain-text value — the same coordinate
+ * space as `MarkDecoration.from` / `MarkDecoration.to`.
+ *
+ * Use `RCTextareaPluginAPI.decorationsFromTokens()` to convert a token array into
+ * `DecorationInput[]` using a theme map.
+ */
+export interface Token {
+    /** Inclusive start offset (0-based character index into plain text). */
+    from: number;
+    /** Exclusive end offset. */
+    to: number;
+    /** Semantic token type, e.g. `"keyword"`, `"string"`, `"comment"`. */
+    type: string;
+    /** Optional TextMate / VS Code scope list (e.g. `["keyword.control", "source.js"]`). */
+    scopes?: string[];
+}
+/**
+ * Contextual API available inside plugin lifecycle callbacks.
+ *
+ * Plugins own the decoration state — keep a reference to `api` from `mount()`
+ * to set decorations from outside the plugin lifecycle:
+ *
+ * ```ts
+ * let api: RCTextareaPluginAPI;
+ * editor.usePlugin({
+ *   mount(a) { api = a; },
+ *   update() {},
+ * });
+ * // later:
+ * api.setDecorations([...]);
+ * api.scheduleUpdate();
+ * ```
+ */
+export interface RCTextareaPluginAPI {
+    /** The host rc-textarea element. */
+    readonly host: HTMLElement;
+    readonly value: string;
+    /** Normalized selection start offset (always ≤ selectionEnd). */
+    readonly selectionStart: number;
+    /** Normalized selection end offset (always ≥ selectionStart). Equals selectionStart when the cursor is collapsed. */
+    readonly selectionEnd: number;
+    /**
+     * Returns the bounding rect of the cursor (caret) in viewport coordinates,
+     * or `null` if the editor is not focused or the cursor is outside the editor.
+     * Useful for anchoring autocomplete popups or hover tooltips to the cursor.
+     */
+    getCursorRect(): DOMRect | null;
+    /**
+     * Returns the word at the current cursor position, or `null` if the cursor is
+     * not on a word character (`\w` — alphanumeric + underscore).
+     */
+    getWordAtCursor(): {
+        word: string;
+        from: number;
+        to: number;
+    } | null;
+    /**
+     * Subscribe to cursor/selection changes. The callback fires on every cursor
+     * move (arrow keys, mouse clicks, selection changes) while the editor is focused.
+     * Returns an unsubscribe function — call it in your plugin's `destroy()`.
+     *
+     * @example
+     * ```ts
+     * let unsub: () => void;
+     * editor.usePlugin({
+     *   mount(api) {
+     *     unsub = api.onCursorMove((start, end) => {
+     *       const word = api.getWordAtCursor();
+     *       if (word) showTooltip(word, api.getCursorRect());
+     *     });
+     *   },
+     *   destroy() { unsub?.(); },
+     * });
+     * ```
+     */
+    onCursorMove(callback: (selectionStart: number, selectionEnd: number) => void): () => void;
+    addDecoration(d: DecorationInput): string;
+    removeDecoration(id: string): void;
+    clearDecorations(): void;
+    setDecorations(decorations: DecorationInput[]): void;
+    /** Returns the decorations this plugin has currently set, in insertion order. */
+    getDecorations(): readonly Decoration[];
+    /** Trigger a render pass outside of normal text input events. */
+    scheduleUpdate(): void;
+    /**
+     * Inject a stylesheet into the component's shadow root via `adoptedStyleSheets`.
+     *
+     * Pass a `CSSStyleSheet` object to share an already-constructed sheet (zero
+     * extra parsing cost), or a raw CSS text string to compile and adopt a new one.
+     * Returns the adopted `CSSStyleSheet` so it can be passed to `removeStyleSheet`
+     * if explicit removal is needed before the plugin is unmounted.
+     *
+     * Adopted sheets are **automatically removed** when the plugin is unmounted
+     * (via `removePlugin()` or `usePlugin()` with a replacement).
+     *
+     * @example CSS text string
+     * ```ts
+     * editor.usePlugin({
+     *   mount(api) {
+     *     api.adoptStyleSheet(`
+     *       .hljs-keyword { color: #cba6f7; }
+     *       .hljs-string  { color: #a6e3a1; }
+     *     `);
+     *   },
+     * });
+     * ```
+     *
+     * @example Shared CSSStyleSheet (constructed once, adopted by many)
+     * ```ts
+     * const sharedSheet = new CSSStyleSheet();
+     * sharedSheet.replaceSync('.hljs-keyword { color: #cba6f7; }');
+     *
+     * editor.usePlugin({
+     *   mount(api) { api.adoptStyleSheet(sharedSheet); },
+     * });
+     * ```
+     */
+    adoptStyleSheet(sheetOrCssText: CSSStyleSheet | string): CSSStyleSheet;
+    /**
+     * Remove a previously adopted stylesheet from the shadow root.
+     * The sheet does not need to have been adopted via `adoptStyleSheet` —
+     * any sheet already present in `adoptedStyleSheets` may be removed.
+     */
+    removeStyleSheet(sheet: CSSStyleSheet): void;
+    /**
+     * Compatibility bridge for highlight.js / prism.js.
+     *
+     * Parses an HTML string of `<span class="...">text</span>` structures
+     * (as returned by `hljs.highlight()` or `Prism.highlight()`) and converts
+     * them into `MarkDecoration` objects covering the corresponding character
+     * ranges of the plain text value.
+     *
+     * ```ts
+     * editor.usePlugin({
+     *   highlight(value, api) {
+     *     const html = hljs.highlight(value, { language: 'js' }).value;
+     *     api.setDecorations(api.decorationsFromHtml(html));
+     *   },
+     * });
+     * ```
+     */
+    decorationsFromHtml(html: string): Omit<MarkDecoration, 'id'>[];
+    /**
+     * Convert a flat token array from an external tokenizer (lezer, tree-sitter, shiki, moo, etc.)
+     * into `DecorationInput` objects using a theme map keyed by `token.type`.
+     *
+     * Token offsets must be **absolute** character indices into the plain-text value
+     * (same coordinate space as `MarkDecoration.from` / `MarkDecoration.to`).
+     * Types not present in `themeMap` are silently ignored.
+     *
+     * ```ts
+     * editor.usePlugin({
+     *   update(value, api) {
+     *     const tokens = myTokenizer.tokenize(value);
+     *     api.setDecorations(api.decorationsFromTokens(tokens, {
+     *       keyword: { bold: true, color: 'var(--color-keyword)' },
+     *       string:  { color: 'var(--color-string)' },
+     *       comment: { italic: true, color: 'var(--color-comment)' },
+     *     }));
+     *   },
+     * });
+     * ```
+     */
+    decorationsFromTokens(tokens: Token[], themeMap: Record<string, Omit<MarkDecoration, 'id' | 'type' | 'from' | 'to'>>): Omit<MarkDecoration, 'id'>[];
+    /**
+     * Insert `text` at the current cursor position, replacing any active selection.
+     * Equivalent to typing the text with the keyboard.
+     */
+    insertText(text: string): void;
+    /**
+     * Wrap the current selection with `prefix` and `suffix`.
+     * No-op when the selection is collapsed (no text selected).
+     *
+     * ```ts
+     * api.wrapSelection('**', '**'); // bold
+     * api.wrapSelection('`', '`');   // inline code
+     * ```
+     */
+    wrapSelection(prefix: string, suffix: string): void;
+    /**
+     * Replace the current selection with `text`.
+     * When the selection is collapsed this is equivalent to `insertText`.
+     */
+    replaceSelection(text: string): void;
+}
+/**
+ * Plugin interface for rc-textarea.
+ *
+ * At least one of `update` or `highlight` must be provided.
+ *
+ * @example Syntax highlighting with highlight.js
+ * ```ts
+ * import hljs from 'highlight.js/lib/core';
+ * import javascript from 'highlight.js/lib/languages/javascript';
+ * hljs.registerLanguage('javascript', javascript);
+ *
+ * editor.usePlugin({
+ *   highlight(value, api) {
+ *     const html = hljs.highlight(value, { language: 'javascript' }).value;
+ *     api.setDecorations(api.decorationsFromHtml(html));
+ *   },
+ * });
+ * ```
+ *
+ * @example Async highlighter (WASM / web worker)
+ * ```ts
+ * editor.usePlugin({
+ *   async update(value, api) {
+ *     const decs = await myParser.decorate(value);
+ *     api.setDecorations(decs);
+ *   },
+ * });
+ * ```
+ */
+export interface RCTextareaPlugin {
+    /** Called when the plugin is registered. Store `api` here for external use. */
+    mount?(api: RCTextareaPluginAPI): void;
+    /** Called when the plugin is replaced or the element disconnects. */
+    destroy?(): void;
+    /**
+     * Display-layer value transform — called before `update`/`highlight` in
+     * read-only mode. Return a non-null string to substitute it as the rendered
+     * text passed to all subsequent hooks and to the document builder.
+     * The underlying `element.value` is **never** modified; only the display
+     * layer sees the transformed text.
+     * Return `null` or `void` to leave the value unchanged.
+     */
+    transform?(value: string, api: RCTextareaPluginAPI): string | null | void;
+    /**
+     * Imperative decoration API — called on each value change.
+     * Use `api.setDecorations()` to apply decorations.
+     */
+    update?(value: string, api: RCTextareaPluginAPI): void | Promise<void>;
+    /**
+     * HTML-based compat — called on each value change.
+     * Return an HTML string (e.g. from hljs/prism); it will be parsed via
+     * `api.decorationsFromHtml()` and applied as mark decorations.
+     * Return `null` or `void` to skip.
+     */
+    highlight?(value: string, api: RCTextareaPluginAPI): string | null | void | Promise<string | null | void>;
+}
+/**
+ * The subset of `MarkDecoration` properties used for styling.
+ * Used in `TextPattern.captureGroups` to assign a style to each named capture group.
+ */
+export type MarkDecorationStyle = Pick<MarkDecoration, 'className' | 'bold' | 'italic' | 'color' | 'background' | 'underline' | 'underlineColor' | 'attributes'>;
+export interface TextPattern {
+    id: string;
+    pattern: RegExp;
+    className?: string;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    background?: string;
+    underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';
+    underlineColor?: string;
+    attributes?: Record<string, string>;
+    /**
+     * Factory called for each regex match. Return a partial LineDecoration
+     * (message, messageClassName, className, attributes) to add an error-lens
+     * annotation on the matched line, or `null` to skip.
+     */
+    createLineDecoration?: (match: RegExpMatchArray) => Omit<LineDecoration, 'id' | 'type' | 'line'> | null;
+    /**
+     * Per-named-capture-group decoration styles. When provided, one
+     * `MarkDecoration` is emitted per captured group (unmatched optional groups
+     * are skipped) instead of one decoration for the whole match.
+     *
+     * The `pattern` must use named capture groups (`(?<name>...)`). The `d`
+     * flag (indices) is added automatically when `captureGroups` is set.
+     *
+     * @example
+     * ```ts
+     * {
+     *   id: 'kv',
+     *   pattern: /^(?<key>\w+):\s*(?<value>.+)$/gm,
+     *   captureGroups: {
+     *     key:   { bold: true, color: '#c792ea' },
+     *     value: { color: '#c3e88d' },
+     *   },
+     * }
+     * ```
+     */
+    captureGroups?: Record<string, MarkDecorationStyle>;
+}
+/**
+ * A simplified plugin variant for per-line decoration.
+ *
+ * Return mark/line decorations with offsets **relative to the start of the
+ * line** — `createLineDecoratorPlugin()` converts them to absolute document
+ * offsets automatically, so no `lineStart` bookkeeping is needed.
+ *
+ * @example
+ * ```ts
+ * const myDecorator: LineDecoratorPlugin = {
+ *   styles: '.kw { font-weight: bold; color: #cba6f7; }',
+ *   decorateLine(line) {
+ *     const results: Omit<MarkDecoration | LineDecoration, 'id'>[] = [];
+ *     const m = /\bfunction\b/.exec(line);
+ *     if (m) results.push({ type: 'mark', from: m.index, to: m.index + m[0].length, className: 'kw' });
+ *     return results;
+ *   },
+ * };
+ * editor.usePlugin(createLineDecoratorPlugin(myDecorator));
+ * ```
+ */
+export interface LineDecoratorPlugin {
+    /**
+     * Called for each line of text (including empty lines, which can be skipped
+     * by returning `[]`). `lineIndex` is 0-based.
+     *
+     * Offsets in returned `MarkDecoration` objects must be **line-relative**
+     * (0 = start of the line). `LineDecoration.line` should be 1-based as usual.
+     */
+    decorateLine(line: string, lineIndex: number): (Omit<MarkDecoration, 'id'> | Omit<LineDecoration, 'id'>)[];
+    /** CSS text to inject into the component's shadow root once on mount. */
+    styles?: string;
+}
+/** Generate a unique decoration ID (UUID v4). */
+export declare function generateId(): string;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@rcarls/rc-textarea",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "description": "Headless enhanced textarea web component built with Lit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
+    "directory": "packages/rc-textarea"
+  },
+  "homepage": "https://github.com/richardcarls/rc-webcomponents#readme",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/rc-textarea.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/packages/rc-textarea/src/index.d.ts",
+        "default": "./dist/rc-textarea.js"
+      }
+    },
+    "./define": {
+      "import": {
+        "types": "./dist/types/packages/rc-textarea/src/define.d.ts",
+        "default": "./dist/rc-textarea-define.js"
+      }
+    }
+  },
+  "types": "./dist/types/packages/rc-textarea/src/index.d.ts",
+  "sideEffects": [
+    "./dist/rc-textarea-define.js"
+  ],
+  "customElements": "dist/custom-elements.json",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build && cem analyze",
+    "cem:analyze": "cem analyze",
+    "preview": "vite preview",
+    "test:browser": "vitest",
+    "test:browser:chrome": "vitest --project=chromium",
+    "test:browser:firefox": "vitest --project=firefox"
+  },
+  "dependencies": {
+    "parchment": "^3.0.0"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@guanghechen/rollup-plugin-copy": "^6.0.9",
+    "@types/node": "^25.6.0",
+    "@vitest/browser-playwright": "4.1.5",
+    "lit": "^3.0.0",
+    "playwright": "^1.56.0",
+    "rollup": "^4.60.2",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6",
+    "vitest-browser-lit": "^1.0.1"
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0"
+  }
+}