@rcarls/rc-textarea 0.3.1 → 0.4.0

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

@@ -1,4 +1,6 @@
 import { LitElement, CSSResultGroup } from 'lit';
+import { NativeChildController } from '@rcarls/rc-common';
+import { RCDocument } from './document.ts';
 import { SavedSelection } from './selection.ts';
 import { Decoration, DecorationInput, RCTextareaPlugin, RCTextareaPluginAPI, TextPattern } from './types.ts';
 declare global {
@@ -6,6 +8,11 @@ declare global {
         'rc-textarea': RCTextarea;
     }
 }
+interface UndoEntry {
+    value: string;
+    anchorOffset: number;
+    focusOffset: number;
+}
 /**
  * Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.
  *
@@ -36,6 +43,22 @@ declare global {
  * @fires rc-textarea-change - Fired when the field value changes
  * @fires rc-textarea-blur - Fired when the field loses focus
  *
+ * @csspart root - The outer flex container wrapping the gutter and editor area.
+ * @csspart gutter - The gutter column container.
+ * @csspart gutter-cells - The gutter's line-label list.
+ * @csspart editor-area - The container positioning the editor over the slotted textarea.
+ * @csspart editor - The contenteditable field surface.
+ *
+ * @attr line-numbers - Show sequential line numbers in the gutter. Enables the gutter implicitly.
+ * @attr list-numbers - Deprecated alias for sparse line numbering; removed before v1.0.
+ * @attr gutter - Enable the gutter column without any built-in content.
+ * @attr word-wrap - Wrap long lines within the field to prevent horizontal overflow.
+ * @attr auto-grow - Allow the field to grow vertically with content to prevent vertical overflow.
+ * @attr read-only - Disable editing. The field renders as a styled read-only display.
+ * @attr label - Deprecated accessible-name override; removed before v1.0.
+ * @attr value - Current field value.
+ * @attr default-value - Initial uncontrolled value.
+ *
  * @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
@@ -50,6 +73,8 @@ declare global {
  * @cssprop [--rc-textarea-gutter-bg=Canvas] - Gutter background color
  * @cssprop [--rc-textarea-gutter-color=GrayText] - Gutter text color
  * @cssprop [--rc-textarea-gutter-border=1px solid ButtonBorder] - Gutter right border
+ * @cssprop [--rc-textarea-gutter-font-family=var(--rc-textarea-font-family, monospace)] - Gutter font family
+ * @cssprop [--rc-textarea-gutter-padding-inline-end=0.75em] - Space between gutter labels and text
  */
 export declare class RCTextarea extends LitElement {
     static styles: CSSResultGroup;
@@ -64,6 +89,8 @@ export declare class RCTextarea extends LitElement {
     /** Show sequential line numbers in the gutter. Enables the gutter implicitly. */
     lineNumbers: boolean;
     /**
+     * Legacy alias for sparse (non-blank-line) list-style numbering.
+     *
      * @deprecated Use a plugin with `LineDecoration.gutterContent` to implement
      * sparse line numbering. This property will be removed before v1.0.
      */
@@ -84,6 +111,8 @@ export declare class RCTextarea extends LitElement {
     /** Disable editing. The field renders as a styled read-only display. */
     readOnly: boolean;
     /**
+     * Accessible-name override, applied to the editor's `aria-label`.
+     *
      * @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.
@@ -119,39 +148,39 @@ export declare class RCTextarea extends LitElement {
     private _defaultValue;
     private _initialValueResolved;
     private _valueSetByHost;
-    private _document;
-    private _$textareaRef;
-    private readonly _textareaController;
+    protected _document: RCDocument | null;
+    protected _$textareaRef: WeakRef<HTMLTextAreaElement> | null;
+    protected readonly _textareaController: NativeChildController<HTMLTextAreaElement>;
     /** Plugin-owned decorations */
     protected _pluginDecorations: Map<string, Decoration>;
     /** Pattern-generated decorations (rebuilt on each value change). */
-    private _patternDecorations;
+    protected _patternDecorations: Decoration[];
     /** Imperative decorations (set directly via the `decorations` property) */
     private _externalDecorations;
     /** Registered patterns. */
-    private _patterns;
+    protected _patterns: Map<string, TextPattern>;
     protected _plugin: RCTextareaPlugin | null;
     private _pluginProperty;
     protected _pluginApi: RCTextareaPluginAPI | null;
     /** Sequence counter for async plugin safety (discard stale results). */
-    private _pluginSeq;
+    protected _pluginSeq: number;
     /** Stylesheets adopted into the shadow root by the active plugin. */
-    private _pluginSheets;
+    protected _pluginSheets: Set<CSSStyleSheet>;
     protected _savedSelection: SavedSelection | null;
-    private _rafHandle;
-    private _composing;
-    private _isRendering;
+    protected _rafHandle: number | null;
+    protected _composing: boolean;
+    protected _isRendering: boolean;
     /** The currently highlighted `.line` element (active line). */
-    private _$activeLine;
+    protected _$activeLine: HTMLElement | null;
     /** Callbacks registered via PluginAPI.onCursorMove(). */
-    private _cursorCallbacks;
-    private _docSelectionChangeHandler;
+    protected _cursorCallbacks: Set<(start: number, end: number) => void>;
+    protected _docSelectionChangeHandler: () => void;
     /** Synthetic undo/redo stack (DOM rebuilds invalidate native undo) */
-    private _undoStack;
-    private _undoIndex;
-    private _resizeObserver;
+    protected _undoStack: UndoEntry[];
+    protected _undoIndex: number;
+    protected _resizeObserver: ResizeObserver | null;
     /** Cached per-line gutter labels from the last render — reused by ResizeObserver. */
-    private _gutterLabels;
+    protected _gutterLabels: (string | null)[];
     /**
      * The current field value.
      *
@@ -169,16 +198,17 @@ export declare class RCTextarea extends LitElement {
     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;
-    private _onSelectionChange;
-    private _updateActiveLine;
-    private _updateActiveGutterCell;
-    private _onKeyDown;
+    protected _onSlotChange(): void;
+    protected _setupTextarea($textarea: HTMLTextAreaElement | null, $previousTextarea?: HTMLTextAreaElement | null): void;
+    protected _onTextareaInvalid: () => void;
+    protected _bindEditorEvents($editor: HTMLElement): void;
+    protected _onInputEvent: () => void;
+    protected _onBeforeInput: (event: InputEvent) => void;
+    protected _onInput(): void;
+    protected _onSelectionChange: () => void;
+    protected _updateActiveLine(): void;
+    protected _updateActiveGutterCell(): void;
+    protected _onKeyDown: (e: KeyboardEvent) => void;
     protected _insertText(text: string): void;
     /**
      * Wrap the current selection with `prefix` and `suffix`.
@@ -195,13 +225,13 @@ export declare class RCTextarea extends LitElement {
      * When the selection is collapsed this is equivalent to `insertText`.
      */
     replaceSelection(text: string): void;
-    private _onPaste;
+    protected _onPaste: (e: ClipboardEvent) => void;
     /** 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;
+    protected _undo(): void;
+    protected _redo(): void;
+    protected _applyUndoEntry(entry: UndoEntry): void;
     /**
      * Register and mount a plugin imperatively.
      * Replaces any currently active plugin. Prefer the `plugin` property for
@@ -215,11 +245,16 @@ export declare class RCTextarea extends LitElement {
      * `mount()` call. Each getter delegates to the component's live state so the
      * API stays accurate across render frames without needing to be rebuilt.
      */
-    private _buildPluginApi;
-    private _clearPluginSheets;
+    protected _buildPluginApi(): RCTextareaPluginAPI;
+    protected _clearPluginSheets(): void;
     /**
      * Register a text pattern that generates decorations on every render pass.
      * Returns the pattern ID, which can be passed to `removePattern` to unregister it.
+     *
+     * @example
+     * const id = editor.addPattern({ pattern: /TODO/g, className: 'highlight-todo' });
+     * // Later:
+     * editor.removePattern(id);
      */
     addPattern(pattern: Omit<TextPattern, 'id'>): string;
     /** Remove a previously registered pattern by the ID returned from `addPattern`. */
@@ -227,7 +262,7 @@ export declare class RCTextarea extends LitElement {
     /** Remove all registered patterns and trigger a re-render. */
     clearPatterns(): void;
     protected _scheduleRender(): void;
-    private _performRender;
+    protected _performRender(): Promise<void>;
     /**
      * Compute the label string for each gutter cell based on the current gutter
      * mode (`lineNumbers`, `listNumbers` (deprecated), `gutter`) and any
@@ -237,7 +272,7 @@ export declare class RCTextarea extends LitElement {
      * - `string` — the label to display
      * - `null`   — render an empty cell
      */
-    private _computeGutterLabels;
+    protected _computeGutterLabels(allDecorations: Decoration[], value?: string): (string | null)[];
     /**
      * Synchronize the pixel height of each gutter cell to match the
      * corresponding `.line` element in the editor.
@@ -248,16 +283,17 @@ export declare class RCTextarea extends LitElement {
      * Also copies the editor's computed `paddingTop`/`paddingBottom` to the
      * gutter to compensate for browser UA overrides on contenteditable.
      */
-    private _syncGutterHeights;
+    protected _syncGutterHeights(): void;
     /**
      * Add, remove, or update `.gutter-cell` spans so their count and text
      * content match `labels`. When `labels` is provided the cached
      * `_gutterLabels` is updated first; otherwise the cached labels are reused
      * (called by the `ResizeObserver` without a new render pass).
      */
-    private _syncGutter;
-    private _syncLabel;
-    private _syncTypography;
+    protected _syncGutter(labels?: (string | null)[]): void;
+    protected _syncLabel(): void;
+    protected _syncTypography($textarea: HTMLTextAreaElement): void;
     protected _syncTextareaValue(fromUser?: boolean): void;
     protected _dispatchChange(value: string): void;
 }
+export {};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.",
   "repository": {
     "type": "git",