@rcarls/rc-textarea 0.1.0 → 0.3.0

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

@@ -1,7 +1,7 @@
 import { Registry, ScrollBlot, BlockBlot, InlineBlot, EmbedBlot } from 'parchment';
 import { MarkDecoration } from './types.ts';
 export { Registry };
-export declare class V2ScrollBlot extends ScrollBlot {
+export declare class RCScrollBlot extends ScrollBlot {
     static blotName: string;
     constructor(registry: Registry, domNode: HTMLDivElement);
     update(_mutations: MutationRecord[], _context: Record<string, unknown>): void;
@@ -12,25 +12,25 @@ export declare class V2ScrollBlot extends ScrollBlot {
         [key: string]: unknown;
     }): void;
 }
-export declare class V2BlockBlot extends BlockBlot {
+export declare class RCBlockBlot extends BlockBlot {
     static blotName: string;
     static tagName: string;
     static className: string;
 }
 type InlineFormats = Pick<MarkDecoration, 'className' | 'bold' | 'italic' | 'color' | 'background' | 'underline' | 'underlineColor'>;
-export declare class V2InlineBlot extends InlineBlot {
+export declare class RCInlineBlot extends InlineBlot {
     static blotName: string;
     static tagName: string;
     static className: string;
     static create(formats?: InlineFormats): HTMLElement;
 }
 /**
- * Apply `MarkDecoration` style properties to a `.v2-mark` span element as
- * inline styles and extra CSS classes. Called by `V2InlineBlot.create()` and
+ * Apply `MarkDecoration` style properties to a `.mark` span element as
+ * inline styles and extra CSS classes. Called by `RCInlineBlot.create()` and
  * by external code that needs to style a span to match a decoration.
  */
-export declare function applyInlineFormats(el: HTMLSpanElement, formats: InlineFormats): void;
-export declare class V2WidgetBlot extends EmbedBlot {
+export declare function applyInlineFormats($el: HTMLSpanElement, formats: InlineFormats): void;
+export declare class RCWidgetBlot extends EmbedBlot {
     static blotName: string;
     static tagName: string;
     static className: string;

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

@@ -20,6 +20,8 @@ interface Edit {
  * This is a heuristic ("longest common prefix/suffix"), not a full LCS diff.
  * It assumes the browser makes one contiguous edit per input event, which holds
  * true for normal typing, deletion, and paste.
+ *
+ * @see {@link http://www.xmailserver.org/diff2.pdf Myers 1986 — An O(ND) Difference Algorithm and Its Variations}
  */
 export declare function findEdit(oldValue: string, newValue: string): Edit;
 /**
@@ -51,10 +53,11 @@ export declare function isLargeChange(oldValue: string, edit: Edit): boolean;
  *
  * This is the primary entry point used by the component on each input event.
  */
-export declare function mapOrClear(decorations: Decoration[], oldValue: string, newValue: string): Decoration[];
+export declare function remapDecorations(decorations: Decoration[], oldValue: string, newValue: string): Decoration[];
 /**
  * Add a single decoration to `map`, assigning it a fresh UUID as its `id`.
- * Returns the assigned ID.
+ *
+ * @returns the assigned `id`, used to remove or look up the decoration later
  */
 export declare function addDecoration(map: Map<string, Decoration>, input: DecorationInput): string;
 /**

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

@@ -1,19 +1,17 @@
 import { Decoration } from './types.ts';
-export declare class V2Document {
+export declare class RCDocument {
     private readonly scroll;
-    constructor(editorEl: HTMLDivElement);
+    constructor($documentRoot: HTMLDivElement);
     /**
-     * Rebuild the document tree from `value` + `decorations`.
-     * Reuses existing `.v2-line` elements in place to preserve DOM identity
+     * Rebuild the document tree.
+     *
+     * Reuses existing `.line` elements in place to preserve DOM identity
      * across renders (fixes DevTools node tracking and mouse gesture continuity).
-     * Only the children of each line are replaced; the line element itself survives.
      */
     build(value: string, decorations: Decoration[]): void;
     destroy(): void;
 }
 /**
- * Extracts plain text directly from the editor's contenteditable DOM.
- * Handles our structured .v2-line divs as well as browser-inserted markup
- * from edits that happen between render frames.
+ * Extracts plain text directly from the contenteditable DOM.
  */
-export declare function extractEditorText(editorEl: HTMLElement): string;
+export declare function getText($editorEl: HTMLElement): string;

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

@@ -1,24 +1,27 @@
 import { RCTextareaPluginAPI, DecorationInput } from './types.ts';
 export interface LineAction {
+    /** Stable identifier used for action-set change detection. */
     id: string;
+    /** Human-readable label; used as button text and accessible name. */
     label: string;
-    /** data-icon attribute — host renders via iconify or similar */
-    icon?: string;
+    /** Icon name passed to `LineActionsOptions.createIcon`, e.g. `'mdi-lock-outline'`. */
+    iconName?: string;
+    /** Called when the action button is activated. */
     onClick: () => void;
 }
 export interface LineActionsOptions {
-    /** Where to place the inline widget. Default: 'append'. */
+    /** Where to place the inline widget. Default: `'append'`. */
     position?: 'append';
     /**
-     * Create and return a DOM element for the given icon name (e.g. 'mdi-lock-outline').
-     * Called when `action.icon` is set. Return `null` to fall back to text label.
+     * Create and return a DOM element for the given icon name (e.g. `'mdi-lock-outline'`).
+     * Called when `action.iconName` is set. Return `null` to fall back to text label.
      *
-     * @example — iconify web component
+     * @example
      * ```ts
      * createIcon: (name) => {
-     *   const el = document.createElement('iconify-icon');
-     *   el.setAttribute('icon', name);
-     *   return el;
+     *   const $icon = document.createElement('iconify-icon');
+     *   $icon.setAttribute('icon', name);
+     *   return $icon;
      * }
      * ```
      */

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

@@ -1,13 +1,12 @@
 import { DecorationInput, LineDecoratorPlugin, RCTextareaPlugin } from './types.ts';
-/**
- * Options for `createLineDecoratorPlugin`.
- */
 export interface LineDecoratorPluginOptions {
     /**
-     * An array of subscriber setup functions. Each function receives a callback
-     * and should call it whenever an external value changes (e.g. a reactive
-     * signal). It may return an optional cleanup/unsubscribe function called on
-     * plugin destroy.
+     * An array of subscriber setup functions for (e.g., reactive
+     * signals).
+     *
+     * Each function receives a callback and should call it whenever an external
+     * value changes . It may return an optional cleanup/unsubscribe function
+     * called on plugin destroy.
      *
      * This is intentionally framework-agnostic. For Solid.js signals:
      * ```ts
@@ -19,8 +18,9 @@ export interface LineDecoratorPluginOptions {
     watch?: Array<(onChange: () => void) => (() => void) | void>;
     /**
      * Called once per update pass **after** all per-line decorations are built.
+     *
      * Use this to merge in decorations that require the full document value
-     * (e.g. diagnostics from a whole-document parser).
+     * (e.g., diagnostics from a whole-document parser).
      */
     extraDecorations?: (value: string) => DecorationInput[];
 }
@@ -28,6 +28,7 @@ export interface LineDecoratorPluginOptions {
  * Factory that wraps a `LineDecoratorPlugin` in a full `RCTextareaPlugin`.
  *
  * Handles the boilerplate that every per-line decorator needs:
+ *
  * - CSS injection via `api.adoptStyleSheet` on mount
  * - `lineStart` offset bookkeeping when converting line-relative offsets to
  *   absolute document offsets

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

@@ -4,8 +4,9 @@ export type { TextPattern };
  * Run all `patterns` against `value` and collect every match as decorations.
  *
  * For each pattern:
- * - If `captureGroups` is set, one `MarkDecoration` is emitted **per named
- *   capture group** instead of one for the whole match. Unmatched optional
+ *
+ * - If `captureGroups` is set, one `MarkDecoration` is emitted per named
+ *   capture group instead of one for the whole match. Unmatched optional
  *   groups are silently skipped. The `d` flag (match indices) is added to
  *   the regex automatically.
  * - Otherwise, one `MarkDecoration` covering the entire match is emitted,
@@ -15,6 +16,7 @@ export type { TextPattern };
  *
  * The global flag is added automatically if missing to ensure all occurrences
  * are found and to avoid stateful `lastIndex` bugs on the caller's regex.
+ *
  * Zero-length matches are skipped to prevent infinite loops.
  */
 export declare function matchPatternResults(value: string, patterns: TextPattern[]): {

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

@@ -1,20 +1,49 @@
 import { LitElement, CSSResultGroup } from 'lit';
 import { SavedSelection } from './selection.ts';
 import { Decoration, DecorationInput, RCTextareaPlugin, RCTextareaPluginAPI, TextPattern } from './types.ts';
+declare global {
+    interface HTMLElementTagNameMap {
+        'rc-textarea': RCTextarea;
+    }
+}
 /**
- * Enhanced textarea with line decorations, gutter, and plugin API.
+ * Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.
+ *
+ * Provide a native `<textarea>` as the direct child when the component is
+ * editable. Read-only displays may be driven from `value` or `defaultValue`.
+ *
+ * @see {@link https://richardcarls.github.io/rc-webcomponents/components/rc-textarea rc-textarea docs}
+ *
+ * @example Basic usage
+ * ```html
+ * <label for="editor">Source</label>
+ * <rc-textarea>
+ *   <textarea id="editor" name="source"></textarea>
+ * </rc-textarea>
+ * ```
  *
- * @slot - Accepts a native `<textarea>` element for form wiring and progressive enhancement.
- * @fires rc-textarea-change - Fired when the editor value changes
- * @fires rc-textarea-blur - Fired when the editor loses focus
- * @cssprop [--rc-textarea-border=1px solid ButtonBorder] - Border around the editor
- * @cssprop [--rc-textarea-border-radius=2px] - Border radius of the editor
- * @cssprop [--rc-textarea-background=Field] - Background color of the editor
+ * @example Controlled value (JavaScript)
+ * ```js
+ * const editor = document.querySelector('rc-textarea');
+ * editor.value = 'hello world';
+ * editor.addEventListener('rc-textarea-change', (e) => {
+ *   console.log(e.target.value);
+ * });
+ * ```
+ *
+ * @slot - Accepts a native `<textarea>` element for form wiring.
+ *
+ * @fires rc-textarea-change - Fired when the field value changes
+ * @fires rc-textarea-blur - Fired when the field loses focus
+ *
+ * @cssprop [--rc-textarea-border=1px solid ButtonBorder] - Border around the field
+ * @cssprop [--rc-textarea-border-radius=2px] - Border radius of the field
+ * @cssprop [--rc-textarea-background=Field] - Background color of the field
  * @cssprop [--rc-textarea-color=FieldText] - Text color; falls back through --rc-text
  * @cssprop [--rc-textarea-font-family=monospace] - Font family
  * @cssprop [--rc-textarea-font-size=1em] - Font size
  * @cssprop [--rc-textarea-line-height=1.5] - Line height
- * @cssprop [--rc-textarea-padding=0.5em] - Padding inside the editor area
+ * @cssprop [--rc-textarea-padding=0.5em] - Padding inside the field area
  * @cssprop [--rc-textarea-focus-outline=2px solid Highlight] - Focus ring outline
  * @cssprop [--rc-textarea-caret-color=FieldText] - Caret color
  * @cssprop [--rc-textarea-active-line-bg=transparent] - Active line highlight color
@@ -32,21 +61,42 @@ export declare class RCTextarea extends LitElement {
         serializable?: boolean;
         slotAssignment?: SlotAssignmentMode;
     };
+    /** Show sequential line numbers in the gutter. Enables the gutter implicitly. */
     lineNumbers: boolean;
-    listNumbers: boolean;
+    /**
+     * @deprecated Use a plugin with `LineDecoration.gutterContent` to implement
+     * sparse line numbering. This property will be removed before v1.0.
+     */
+    get listNumbers(): boolean;
+    set listNumbers(value: boolean);
+    private _listNumbers;
+    /**
+     * Enable the gutter column without any built-in content.
+     *
+     * Plugins can populate individual cells via `LineDecoration.gutterContent`.
+     * For sequential line numbers use `lineNumbers` / `line-numbers` instead.
+     */
     gutter: boolean;
+    /** Wrap long lines within the field to prevent horizontal overflow. */
     wordWrap: boolean;
+    /** Allow the field to grow vertically with content to prevent vertical overflow. */
     autoGrow: boolean;
+    /** Disable editing. The field renders as a styled read-only display. */
     readOnly: boolean;
-    label: string | null;
+    /**
+     * @deprecated Set `aria-label` on the slotted `<textarea>` instead, or
+     * associate a `<label>` element via its `for`/`id` pair. This property
+     * will be removed before v1.0.
+     */
+    get label(): string | null;
+    set label(value: string | null);
+    private _label;
     /** Declarative plugin hook for framework integrations. */
     get plugin(): RCTextareaPlugin | null;
     /** Declarative plugin hook for framework integrations. */
     set plugin(plugin: RCTextareaPlugin | null);
     /**
-     * Reactive decorations — set from outside the component without registering a plugin.
-     * Ideal for reactive frameworks (Solid, React 19+, Vue 3) where decorations are
-     * computed as reactive state and passed directly as a property:
+     * Imperatively set an external layer of decorations. Ideal for reactive frameworks.
      *
      * ```tsx
      * // Solid
@@ -62,17 +112,21 @@ export declare class RCTextarea extends LitElement {
      */
     get decorations(): DecorationInput[];
     set decorations(value: DecorationInput[] | undefined);
+    protected _$editor: HTMLElement;
+    protected _$gutterCells: HTMLElement;
+    protected _$slot: HTMLSlotElement;
     private _value;
     private _defaultValue;
     private _initialValueResolved;
     private _valueSetByHost;
     private _document;
-    private _textareaRef;
-    /** Plugin-owned decorations (set via PluginAPI.setDecorations / addDecoration). */
+    private _$textareaRef;
+    private readonly _textareaController;
+    /** Plugin-owned decorations */
     protected _pluginDecorations: Map<string, Decoration>;
     /** Pattern-generated decorations (rebuilt on each value change). */
     private _patternDecorations;
-    /** Decorations set directly via the `decorations` property (reactive-framework-friendly). */
+    /** Imperative decorations (set directly via the `decorations` property) */
     private _externalDecorations;
     /** Registered patterns. */
     private _patterns;
@@ -87,29 +141,37 @@ export declare class RCTextarea extends LitElement {
     private _rafHandle;
     private _composing;
     private _isRendering;
-    /** The currently highlighted `.v2-line` element (active line). */
-    private _activeLine;
+    /** The currently highlighted `.line` element (active line). */
+    private _$activeLine;
     /** Callbacks registered via PluginAPI.onCursorMove(). */
     private _cursorCallbacks;
     private _docSelectionChangeHandler;
-    /** Undo/redo stack — necessary because DOM rebuilds invalidate browser's native undo. */
+    /** Synthetic undo/redo stack (DOM rebuilds invalidate native undo) */
     private _undoStack;
     private _undoIndex;
     private _resizeObserver;
     /** Cached per-line gutter labels from the last render — reused by ResizeObserver. */
     private _gutterLabels;
+    /**
+     * The current field value.
+     *
+     * Setting this property puts the component into
+     * controlled mode (host owns the value, changes are reflected
+     * immediately, no change events dispatched)
+     */
     get value(): string;
-    set value(v: string);
-    /** Initial uncontrolled editor value. */
+    set value(val: string);
+    /** Initial uncontrolled value. */
     get defaultValue(): string | undefined;
-    /** Initial uncontrolled editor value. */
-    set defaultValue(v: string | undefined);
+    set defaultValue(val: string | undefined);
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
     updated(changed: Map<string, unknown>): void;
     render(): import('lit').TemplateResult<1>;
     private _onSlotChange;
+    private _setupTextarea;
+    private _onTextareaInvalid;
     private _bindEditorEvents;
     private _onInputEvent;
     private _onInput;
@@ -134,13 +196,19 @@ export declare class RCTextarea extends LitElement {
      */
     replaceSelection(text: string): void;
     private _onPaste;
-    /** Reset the undo/redo history. Call when the editor receives entirely new content. */
+    /** Reset the undo/redo history. Call when the field receives entirely new content. */
     clearHistory(): void;
     protected _pushUndo(sel: SavedSelection | null): void;
     private _undo;
     private _redo;
     private _applyUndoEntry;
+    /**
+     * Register and mount a plugin imperatively.
+     * Replaces any currently active plugin. Prefer the `plugin` property for
+     * reactive-framework integrations.
+     */
     usePlugin(plugin: RCTextareaPlugin): void;
+    /** Unmount the active plugin, clear its decorations, and release its stylesheets. */
     removePlugin(): void;
     /**
      * Build the `RCTextareaPluginAPI` object passed to the active plugin's
@@ -149,14 +217,20 @@ export declare class RCTextarea extends LitElement {
      */
     private _buildPluginApi;
     private _clearPluginSheets;
+    /**
+     * Register a text pattern that generates decorations on every render pass.
+     * Returns the pattern ID, which can be passed to `removePattern` to unregister it.
+     */
     addPattern(pattern: Omit<TextPattern, 'id'>): string;
+    /** Remove a previously registered pattern by the ID returned from `addPattern`. */
     removePattern(id: string): void;
+    /** Remove all registered patterns and trigger a re-render. */
     clearPatterns(): void;
     protected _scheduleRender(): void;
     private _performRender;
     /**
      * Compute the label string for each gutter cell based on the current gutter
-     * mode (`lineNumbers`, `listNumbers`, `gutter`) and any
+     * mode (`lineNumbers`, `listNumbers` (deprecated), `gutter`) and any
      * `LineDecoration.gutterContent` overrides in `allDecorations`.
      *
      * Returns one entry per line (same length as `value.split('\n')`):
@@ -166,7 +240,7 @@ export declare class RCTextarea extends LitElement {
     private _computeGutterLabels;
     /**
      * Synchronize the pixel height of each gutter cell to match the
-     * corresponding `.v2-line` element in the editor.
+     * corresponding `.line` element in the editor.
      *
      * In non-word-wrap mode the gutter uses a uniform `line-height` mirrored
      * from the editor's first line. In word-wrap mode each cell gets an explicit
@@ -182,13 +256,8 @@ export declare class RCTextarea extends LitElement {
      * (called by the `ResizeObserver` without a new render pass).
      */
     private _syncGutter;
+    private _syncLabel;
     private _syncTypography;
     protected _syncTextareaValue(fromUser?: boolean): void;
     protected _dispatchChange(value: string): void;
-    private _getEditorEl;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        'rc-textarea': RCTextarea;
-    }
 }

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

@@ -2,9 +2,10 @@
  * Cursor save/restore for rc-textarea's contenteditable editor.
  *
  * The text model is a plain string with \n line separators.
- * WidgetDecoration spans (.v2-widget) are skipped — they are zero-width in
- * the text model (not part of the value string).
- * <br> elements (used to make empty lines editable) count as 0 characters.
+ *
+ * WidgetDecoration spans (.widget) are zero-width in the text model (not part
+ * of the value string). <br> elements (used to make empty lines editable) count
+ * as 0 characters.
  */
 export interface SavedSelection {
     /** Anchor position as a character offset into the plain text value. */
@@ -13,27 +14,30 @@ export interface SavedSelection {
     focusOffset: number;
 }
 /**
- * Converts a DOM (node, nodeOffset) pair inside `root` to a plain-text offset.
- * Returns -1 if the target was not found inside root.
+ * Converts a DOM (node, nodeOffset) pair inside `$root` to a plain-text offset.
+ * Returns the end-of-content offset if the target was not found inside `$root`.
  */
-export declare function domToTextOffset(root: Element, targetNode: Node, targetNodeOffset: number): number;
+export declare function domToTextOffset($root: Element, $targetNode: Node, targetNodeOffset: number): number;
 interface DomPosition {
     node: Node;
     offset: number;
 }
 /**
- * Converts a plain-text offset to a (node, nodeOffset) DOM position inside `root`.
+ * Converts a plain-text offset to a (node, nodeOffset) DOM position inside `$root`.
+ *
  * Returns null if offset is out of range.
  */
-export declare function textOffsetToDom(root: Element, targetOffset: number): DomPosition | null;
+export declare function textOffsetToDom($root: Element, targetOffset: number): DomPosition | null;
 /**
- * Captures the current browser selection as plain-text offsets relative to `root`.
- * Returns null if there is no selection or the selection is outside `root`.
+ * Captures the current browser selection as plain-text offsets relative to `$root`.
+ *
+ * Returns null if there is no selection or the selection is outside `$root`.
  */
-export declare function saveSelection(root: Element): SavedSelection | null;
+export declare function saveSelection($root: Element): SavedSelection | null;
 /**
- * Restores a previously saved selection inside `root`.
+ * Restores a previously saved selection inside `$root`.
+ *
  * Silently does nothing if the saved offsets are out of range.
  */
-export declare function restoreSelection(root: Element, saved: SavedSelection): void;
+export declare function restoreSelection($root: Element, saved: SavedSelection): void;
 export {};

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

@@ -8,11 +8,13 @@ export declare function getSlottedTextarea(host: RCTextarea): HTMLTextAreaElemen
  */
 export declare function waitRender(): Promise<void>;
 /**
- * Dispatches a synthetic paste event carrying plain text onto `editor`.
+ * Dispatches a synthetic paste event carrying plain text onto `$editor`.
  *
  * Using a plain Event + manual clipboardData override because `new ClipboardEvent`
  * with a DataTransfer in the init dict is not reliable across browsers (Firefox
- * ignores the init's clipboardData). The paste handler only calls
- * `e.clipboardData?.getData('text/plain')`, so a minimal duck-typed mock is enough.
+ * ignores the init's clipboardData).
+ *
+ * The paste handler only calls `e.clipboardData?.getData('text/plain')`, so
+ * a minimal duck-typed mock is enough.
  */
-export declare function simulatePaste(editor: HTMLElement, text: string): void;
+export declare function simulatePaste($editor: HTMLElement, text: string): void;