@rcarls/rc-textarea 0.1.0 → 0.3.0

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

@@ -1,39 +1,52 @@
 /**
  * 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 {
+    /** Unique identifier assigned at creation time. */
     id: string;
+    /** Decoration type discriminant. */
     type: 'mark';
     /** Inclusive start offset (0-based character index into plain text). */
     from: number;
     /** Exclusive end offset. */
     to: number;
+    /** Space-separated CSS class name(s) added to the blot span. */
     className?: string;
+    /** Renders the range bold (`font-weight: bold`). */
     bold?: boolean;
+    /** Renders the range italic (`font-style: italic`). */
     italic?: boolean;
+    /** Text color (`color` CSS property). Accepts any CSS color value. */
     color?: string;
+    /** Background color (`background` CSS property). Accepts any CSS color value. */
     background?: string;
+    /** Underline style (`text-decoration-style`). */
     underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';
+    /** Underline color (`text-decoration-color`). Defaults to the text `color` when omitted. */
     underlineColor?: string;
+    /** Additional HTML attributes set directly on the blot span element. */
     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.
+ * appends a diagnostic message at the end of the line.
  */
 export interface LineDecoration {
+    /** Unique identifier assigned at creation time. */
     id: string;
+    /** Decoration type discriminant. */
     type: 'line';
     /** 1-based logical line number. */
     line: number;
+    /** Space-separated CSS class name(s) added to the line div. */
     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.
+     * Error-lens style diagnostic text shown at the end of the line.
      */
     message?: string;
     /**
@@ -41,25 +54,30 @@ export interface LineDecoration {
      * 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; }
+     * .line[data-message-class~="error"][data-message]::after { color: red; }
      * ```
      */
     messageClassName?: string;
+    /** Additional HTML attributes set directly on the line element. */
     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.)
+     * - `undefined` — use the built-in mode default (`line-numbers`, `gutter`, 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 {
+    /** Unique identifier assigned at creation time. */
     id: string;
+    /** Decoration type discriminant. */
     type: 'widget';
     /** Character offset. Widget is placed before (or after) the character at this position. */
     offset: number;
@@ -68,10 +86,15 @@ export interface WidgetDecoration {
     /** Whether to place the widget before or after the character at `offset`. Default: 'before'. */
     side?: 'before' | 'after';
 }
+/** Decorations are visual formatting applied to the field content without affecting
+ *  the underlying plain text value.
+ */
 export type Decoration = MarkDecoration | LineDecoration | WidgetDecoration;
+/** Input shape for creating a decoration — id-less variant of each decoration type. */
 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`.
  *
@@ -83,9 +106,9 @@ export interface Token {
     from: number;
     /** Exclusive end offset. */
     to: number;
-    /** Semantic token type, e.g. `"keyword"`, `"string"`, `"comment"`. */
+    /** Semantic token type. */
     type: string;
-    /** Optional TextMate / VS Code scope list (e.g. `["keyword.control", "source.js"]`). */
+    /** Optional scope list. */
     scopes?: string[];
 }
 /**
@@ -100,28 +123,35 @@ export interface Token {
  *   mount(a) { api = a; },
  *   update() {},
  * });
+ *
  * // later:
  * api.setDecorations([...]);
  * api.scheduleUpdate();
  * ```
  */
 export interface RCTextareaPluginAPI {
-    /** The host rc-textarea element. */
+    /** The host `rc-textarea` element. */
     readonly host: HTMLElement;
+    /** The current plain-text field value at the time of the callback. */
     readonly value: string;
-    /** Normalized selection start offset (always ≤ selectionEnd). */
+    /** Normalized selection start offset (always ≤ `selectionEnd`). */
     readonly selectionStart: number;
-    /** Normalized selection end offset (always ≥ selectionStart). Equals selectionStart when the cursor is collapsed. */
+    /** 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.
+     * Returns the bounding rect of the cursor (caret) in viewport coordinates.
+     *
      * Useful for anchoring autocomplete popups or hover tooltips to the cursor.
+     *
+     * @returns the cursor bounding rect, or `null` if the editor is not focused
+     *   or the cursor is outside the editor
      */
     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).
+     * Returns the word boundaries at the current cursor position.
+     *
+     * @returns the word and its `[from, to)` offsets, or `null` if the cursor is
+     *   not on a word character (`\w` — alphanumeric + underscore)
      */
     getWordAtCursor(): {
         word: string;
@@ -131,7 +161,8 @@ export interface RCTextareaPluginAPI {
     /**
      * 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()`.
+     *
+     * @returns an unsubscribe function. Call this in `destroy()`
      *
      * @example
      * ```ts
@@ -148,24 +179,35 @@ export interface RCTextareaPluginAPI {
      * ```
      */
     onCursorMove(callback: (selectionStart: number, selectionEnd: number) => void): () => void;
+    /**
+     * Add a single decoration to the plugin's decoration set.
+     *
+     * Use the returned id with `removeDecoration` to remove it individually.
+     *
+     * @returns the assigned `id`, used to remove or look up the decoration later
+     */
     addDecoration(d: DecorationInput): string;
+    /** Remove a previously added decoration by its id. */
     removeDecoration(id: string): void;
+    /** Remove all decorations set by this plugin. */
     clearDecorations(): void;
+    /**
+     * Replace the full decoration set with `decorations`.
+     */
     setDecorations(decorations: DecorationInput[]): void;
-    /** Returns the decorations this plugin has currently set, in insertion order. */
+    /**
+     * @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.
      *
-     * Adopted sheets are **automatically removed** when the plugin is unmounted
-     * (via `removePlugin()` or `usePlugin()` with a replacement).
+     * @returns the adopted `CSSStyleSheet`, which can be passed to `removeStyleSheet`
+     *   if explicit removal is needed before unmount
      *
      * @example CSS text string
      * ```ts
@@ -192,8 +234,6 @@ export interface RCTextareaPluginAPI {
     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;
     /**
@@ -204,15 +244,20 @@ export interface RCTextareaPluginAPI {
      * them into `MarkDecoration` objects covering the corresponding character
      * ranges of the plain text value.
      *
+     * @example
      * ```ts
      * editor.usePlugin({
      *   highlight(value, api) {
      *     const html = hljs.highlight(value, { language: 'js' }).value;
-     *     api.setDecorations(api.decorationsFromHtml(html));
+     *     api.setDecorations(api.parseDecorationsFromHtml(html));
      *   },
      * });
      * ```
      */
+    parseDecorationsFromHtml(html: string): Omit<MarkDecoration, 'id'>[];
+    /**
+     * @deprecated Use `parseDecorationsFromHtml` instead.
+     */
     decorationsFromHtml(html: string): Omit<MarkDecoration, 'id'>[];
     /**
      * Convert a flat token array from an external tokenizer (lezer, tree-sitter, shiki, moo, etc.)
@@ -222,6 +267,7 @@ export interface RCTextareaPluginAPI {
      * (same coordinate space as `MarkDecoration.from` / `MarkDecoration.to`).
      * Types not present in `themeMap` are silently ignored.
      *
+     * @example
      * ```ts
      * editor.usePlugin({
      *   update(value, api) {
@@ -238,13 +284,16 @@ export interface RCTextareaPluginAPI {
     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).
      *
+     * @example
      * ```ts
      * api.wrapSelection('**', '**'); // bold
      * api.wrapSelection('`', '`');   // inline code
@@ -253,6 +302,7 @@ export interface RCTextareaPluginAPI {
     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;
@@ -266,12 +316,14 @@ export interface RCTextareaPluginAPI {
  * ```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));
+ *
+ *     api.setDecorations(api.parseDecorationsFromHtml(html));
  *   },
  * });
  * ```
@@ -281,6 +333,7 @@ export interface RCTextareaPluginAPI {
  * editor.usePlugin({
  *   async update(value, api) {
  *     const decs = await myParser.decorate(value);
+ *
  *     api.setDecorations(decs);
  *   },
  * });
@@ -293,50 +346,69 @@ export interface RCTextareaPlugin {
     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
+     * 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
+     * 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.
+     * Imperative decoration API
      */
     update?(value: string, api: RCTextareaPluginAPI): void | Promise<void>;
     /**
-     * HTML-based compat — called on each value change.
+     * HTML-based compat
+     *
      * Return an HTML string (e.g. from hljs/prism); it will be parsed via
-     * `api.decorationsFromHtml()` and applied as mark decorations.
+     * `api.parseDecorationsFromHtml()` 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 {
+    /** Unique identifier used to register and unregister the pattern. */
     id: string;
+    /** Regular expression matched against the full editor value. Use the `g` flag for multiple matches. */
     pattern: RegExp;
+    /** Space-separated CSS class name(s) applied to matched ranges. */
     className?: string;
+    /** Renders matched ranges bold (`font-weight: bold`). */
     bold?: boolean;
+    /** Renders matched ranges italic (`font-style: italic`). */
     italic?: boolean;
+    /** Text color for matched ranges. Accepts any CSS color value. */
     color?: string;
+    /** Background color for matched ranges. Accepts any CSS color value. */
     background?: string;
+    /** Underline style for matched ranges (`text-decoration-style`). */
     underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';
+    /** Underline color for matched ranges (`text-decoration-color`). Defaults to the text `color` when omitted. */
     underlineColor?: string;
+    /** Additional HTML attributes set directly on matched-range spans. */
     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.
+     * Factory called for each regex match.
+     *
+     * Return a partial LineDecoration
+     * (message, messageClassName, className, attributes) to add a diagnostic
+     * message 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
+     * Decoration styles for each named capture group in the pattern.
+     *
+     * When provided, one
      * `MarkDecoration` is emitted per captured group (unmatched optional groups
      * are skipped) instead of one decoration for the whole match.
      *
@@ -360,8 +432,10 @@ export interface TextPattern {
 /**
  * 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
+ * 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
@@ -371,10 +445,15 @@ export interface TextPattern {
  *   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' });
+ *
+ *     if (m) {
+ *       results.push({ type: 'mark', from: m.index, to: m.index + m[0].length, className: 'kw' });
+ *     }
+ *
  *     return results;
  *   },
  * };
+ *
  * editor.usePlugin(createLineDecoratorPlugin(myDecorator));
  * ```
  */

package/package.json

@@ -3,14 +3,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0",
-  "description": "Headless enhanced textarea web component built with Lit",
+  "version": "0.3.0",
+  "description": "Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
     "directory": "packages/rc-textarea"
   },
-  "homepage": "https://github.com/richardcarls/rc-webcomponents#readme",
+  "homepage": "https://richardcarls.github.io/rc-webcomponents/components/rc-textarea",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -37,20 +37,19 @@
   ],
   "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"
+    "test:browser": "vitest --run",
+    "test:browser:chrome": "vitest --run --project=chromium",
+    "test:browser:firefox": "vitest --run --project=firefox"
   },
   "dependencies": {
+    "@rcarls/rc-common": "workspace:*",
     "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",

package/dist/demo.css

@@ -1,85 +0,0 @@
-*, *::before, *::after {
-  box-sizing: border-box;
-}
-
-:root {
-  color-scheme: light dark;
-  --rc-accent: Highlight; /* Chrome doesn't support AccentColor on the open web */
-}
-
-@supports (color: AccentColor) {
-  :root {
-    --rc-accent: AccentColor;
-  }
-}
-
-[data-theme="light"] { color-scheme: light; }
-[data-theme="dark"]  { color-scheme: dark;  }
-
-[data-theme="solarized-light"] {
-  color-scheme: light;
-  --rc-surface: #fdf6e3;
-  --rc-text:    #657b83;
-  --rc-border:  1px solid #93a1a1;
-  --rc-shadow:  0 2px 8px rgba(0, 0, 0, .12);
-}
-
-[data-theme="solarized-dark"] {
-  color-scheme: dark;
-  --rc-surface: #002b36;
-  --rc-text:    #839496;
-  --rc-border:  1px solid #586e75;
-  --rc-shadow:  0 2px 8px rgba(0, 0, 0, .3);
-}
-
-body {
-  font-family: system-ui, sans-serif;
-  margin: 0;
-}
-
-.demo-page {
-  max-width: 60rem;
-  margin: 0 auto;
-  padding: 2rem 1.5rem;
-}
-
-.demo-controls {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-  margin-bottom: 2rem;
-  padding-bottom: 1rem;
-  border-bottom: 1px solid ButtonBorder;
-}
-
-.demo-controls .demo-title {
-  flex: 1;
-}
-
-.demo-controls h1 {
-  margin: 0 0 0.15rem;
-  font-size: 1.5rem;
-}
-
-.demo-controls a {
-  font-size: 0.8rem;
-}
-
-.demo-section {
-  margin-bottom: 2rem;
-}
-
-.demo-section h2 {
-  margin: 0 0 0.5rem;
-}
-
-.theme-picker {
-  padding: 0.35em 0.75em;
-  font-family: inherit;
-  font-size: 0.8rem;
-  cursor: pointer;
-  border: 1px solid ButtonBorder;
-  border-radius: 4px;
-  background: Canvas;
-  color: CanvasText;
-}

package/dist/demo.js

@@ -1,40 +0,0 @@
-const THEMES = ['', 'light', 'dark', 'solarized-light', 'solarized-dark'];
-const LABELS = ['Auto', 'Light', 'Dark', 'Solarized ☀', 'Solarized ☾'];
-
-const stored = localStorage.getItem('rc-demo-theme') ?? '';
-applyTheme(stored);
-
-function applyTheme(theme) {
-  if (theme) {
-    document.documentElement.dataset.theme = theme;
-  } else {
-    delete document.documentElement.dataset.theme;
-  }
-}
-
-function currentIndex() {
-  const current = document.documentElement.dataset.theme ?? '';
-  const idx = THEMES.indexOf(current);
-  return idx === -1 ? 0 : idx;
-}
-
-function updateButtons() {
-  const label = LABELS[currentIndex()];
-  document.querySelectorAll('.theme-picker').forEach((btn) => {
-    btn.textContent = label;
-  });
-}
-
-window.cycleTheme = function () {
-  const next = THEMES[(currentIndex() + 1) % THEMES.length];
-  applyTheme(next);
-  localStorage.setItem('rc-demo-theme', next);
-  updateButtons();
-};
-
-document.addEventListener('DOMContentLoaded', () => {
-  updateButtons();
-  document.querySelectorAll('.theme-picker').forEach((btn) => {
-    btn.addEventListener('click', window.cycleTheme);
-  });
-});