@rcarls/rc-textarea 0.5.0 → 0.7.0

package/dist/rc-textarea-define.js

@@ -1,5 +1,5 @@
-import { R as e } from "./line-actions-controller-CB8U0WvH.js";
-import { L as o, c as s, m as c } from "./line-actions-controller-CB8U0WvH.js";
+import { R as e } from "./line-actions-controller-DUdXQxMA.js";
+import { L as o, c as s, m as c } from "./line-actions-controller-DUdXQxMA.js";
 customElements.get("rc-textarea") || customElements.define("rc-textarea", e);
 export {
   o as LineActionsController,

package/dist/rc-textarea-folding.js

@@ -0,0 +1,5 @@
+import { F as l } from "./folding-action-controller-sxM3IomW.js";
+export {
+  l as FoldingActionController
+};
+//# sourceMappingURL=rc-textarea-folding.js.map

package/dist/rc-textarea-folding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rc-textarea-folding.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/rc-textarea.js

@@ -1,4 +1,4 @@
-import { L as t, R as r, c as o, m as s } from "./line-actions-controller-CB8U0WvH.js";
+import { L as t, R as r, c as o, m as s } from "./line-actions-controller-DUdXQxMA.js";
 export {
   t as LineActionsController,
   r as RCTextarea,

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

@@ -1,5 +1,5 @@
 import { Registry, ScrollBlot, BlockBlot, InlineBlot, EmbedBlot } from 'parchment';
-import { MarkDecoration } from './types.ts';
+import { MarkDecoration } from './types.js';
 export { Registry };
 export declare class RCScrollBlot extends ScrollBlot {
     static blotName: string;

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

@@ -1,5 +1,5 @@
-import { Decoration, MarkDecoration, LineDecoration, DecorationInput } from './types.ts';
-export { generateId } from './types.ts';
+import { Decoration, MarkDecoration, LineDecoration, DecorationInput } from './types.js';
+export { generateId } from './types.js';
 /**
  * The minimal description of a single contiguous edit:
  * a deletion of `removed` characters at `start`, followed by an insertion of
@@ -32,6 +32,7 @@ export declare function findEdit(oldValue: string, newValue: string): Edit;
  * - `LineDecoration`: dropped if its line falls within the deleted region;
  *   otherwise shifted by the line delta.
  * - `WidgetDecoration`: treated like a zero-width mark at its offset.
+ * - `FoldDecoration`: dropped; the owning plugin recalculates source ranges.
  *
  * Returns a new array. The input array and its elements are not mutated.
  */

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

@@ -1,6 +1,7 @@
-import { Decoration } from './types.ts';
+import { Decoration } from './types.js';
 export declare class RCDocument {
     private readonly scroll;
+    private readonly lineSignatures;
     constructor($documentRoot: HTMLDivElement);
     /**
      * Rebuild the document tree.

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

@@ -0,0 +1,46 @@
+import { DecorationInput, RCTextareaPluginAPI } from './types.js';
+export interface SourceFoldRange {
+    /** First source line hidden by the fold (one-based, inclusive). */
+    fromLine: number;
+    /** Last source line hidden by the fold (one-based, inclusive). */
+    toLine: number;
+}
+export interface FoldingAction {
+    /** Stable identity for the expansion state across plugin updates. */
+    key: string;
+    /** Name the region and its context; aria-expanded supplies its current state. */
+    label: string;
+    /** Source lines or a caller-owned panel. The caller renders panel widgets separately. */
+    target: SourceFoldRange | HTMLElement;
+    /** One-based gutter line. Omit to place the button in the trailing lane. */
+    gutterLine?: number;
+    /** Source offset for a trailing-lane button; required without gutterLine. */
+    offset?: number;
+    /** Initial state for a newly seen key. Defaults to true. */
+    initiallyExpanded?: boolean;
+    /** Add decorative content beside the gutter button. */
+    createGutterContent?: ($button: HTMLButtonElement) => HTMLElement;
+    /** Refresh the cached gutter content without replacing its focused button. */
+    updateGutterContent?: ($content: HTMLElement) => void;
+}
+export interface FoldingActionControllerOptions {
+    /** Render a decorative icon for the current expansion state. */
+    createTriggerIcon?: (expanded: boolean) => Element | null;
+}
+/** Reconcile independent, accessible folding actions without owning their content. */
+export declare class FoldingActionController {
+    private readonly entries;
+    private readonly gutterGroupElements;
+    private readonly api;
+    private readonly options;
+    constructor(api: RCTextareaPluginAPI, options?: FoldingActionControllerOptions);
+    private updateIcon;
+    private applyState;
+    /** Return trigger and collapsed-range decorations; callers provide any panel widget. */
+    getDecorations(actions: readonly FoldingAction[]): DecorationInput[];
+    /** Get expansion state for an existing key. */
+    isExpanded(key: string): boolean | undefined;
+    /** Discard expansion state and return focus before removing a focused control. */
+    clear(): void;
+    private release;
+}

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

@@ -0,0 +1,2 @@
+export { FoldingActionController } from './folding-action-controller.js';
+export type { FoldingAction, FoldingActionControllerOptions, SourceFoldRange, } from './folding-action-controller.js';

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

@@ -1,7 +1,7 @@
-export { RCTextarea } from './rc-textarea.ts';
-export type { Decoration, DecorationInput, MarkDecoration, MarkDecorationStyle, LineDecoration, WidgetDecoration, RCTextareaPlugin, RCTextareaPluginAPI, TextPattern, LineDecoratorPlugin, Token, } from './types.ts';
-export { matchPatternResults } from './pattern-matcher.ts';
-export { createLineDecoratorPlugin } from './line-decorator.ts';
-export type { LineDecoratorPluginOptions } from './line-decorator.ts';
-export { LineActionsController } from './line-actions-controller.ts';
-export type { LineAction, LineActionsOptions } from './line-actions-controller.ts';
+export { RCTextarea } from './rc-textarea.js';
+export type { Decoration, DecorationInput, MarkDecoration, MarkDecorationStyle, LineDecoration, WidgetDecoration, FoldDecoration, RCTextareaPlugin, RCTextareaPluginAPI, TextPattern, LineDecoratorPlugin, Token, } from './types.js';
+export { matchPatternResults } from './pattern-matcher.js';
+export { createLineDecoratorPlugin } from './line-decorator.js';
+export type { LineDecoratorPluginOptions } from './line-decorator.js';
+export { LineActionsController } from './line-actions-controller.js';
+export type { LineAction, LineActionsOptions } from './line-actions-controller.js';

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

@@ -1,4 +1,4 @@
-import { RCTextareaPluginAPI, DecorationInput } from './types.ts';
+import { RCTextareaPluginAPI, DecorationInput } from './types.js';
 export interface LineAction {
     /** Stable identifier used for action-set change detection. */
     id: string;
@@ -13,8 +13,9 @@ export interface LineActionsOptions {
     /** 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.iconName` 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'`),
+     * such as an `<svg>` or an icon custom element. Called when `action.iconName` is set.
+     * Return `null` to fall back to text label.
      *
      * @example
      * ```ts
@@ -25,7 +26,7 @@ export interface LineActionsOptions {
      * }
      * ```
      */
-    createIcon?: (iconName: string) => HTMLElement | null;
+    createIcon?: (iconName: string) => Element | null;
     /**
      * Full control over button content. Called instead of the default icon/label
      * logic. Use `createIcon` when you only need to swap the icon renderer —

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

@@ -1,4 +1,4 @@
-import { DecorationInput, LineDecoratorPlugin, RCTextareaPlugin } from './types.ts';
+import { DecorationInput, LineDecoratorPlugin, RCTextareaPlugin } from './types.js';
 export interface LineDecoratorPluginOptions {
     /**
      * An array of subscriber setup functions for (e.g., reactive

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

@@ -1,4 +1,4 @@
-import { TextPattern, MarkDecoration, LineDecoration } from './types.ts';
+import { TextPattern, MarkDecoration, LineDecoration } from './types.js';
 export type { TextPattern };
 /**
  * Run all `patterns` against `value` and collect every match as decorations.

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

@@ -1,8 +1,8 @@
 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';
+import { FlowController, LocaleController, NativeChildController } from '@rcarls/rc-common';
+import { RCDocument } from './document.js';
+import { SavedSelection } from './selection.js';
+import { Decoration, DecorationInput, RCTextareaPlugin, RCTextareaPluginAPI, TextPattern, FoldDecoration } from './types.js';
 declare global {
     interface HTMLElementTagNameMap {
         'rc-textarea': RCTextarea;
@@ -13,8 +13,14 @@ interface UndoEntry {
     anchorOffset: number;
     focusOffset: number;
 }
+interface FoldBounds {
+    from: number;
+    to: number;
+    anchorEnd: number;
+    reveal: () => void;
+}
 /**
- * Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.
+ * Textarea wrapper with line decorations, gutter rendering, folding actions, 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`.
@@ -38,14 +44,23 @@ interface UndoEntry {
  * });
  * ```
  *
+ * The slotted `<textarea>` describes the content: its `lang` and `spellcheck` are
+ * mirrored onto the editor, and its `dir` sets the editor's base direction (`auto`
+ * resolves from the first strong character of the value, else the host's direction).
+ * The host's own `lang` stays the interface language, which formats line numbers.
+ *
  * @slot - Accepts a native `<textarea>` element for form wiring.
  *
  * @fires rc-textarea-change - Fired when the field value changes
+ * @fires rc-textarea-focus - Fired when the field gains focus
  * @fires rc-textarea-blur - Fired when the field loses focus
+ * @fires rc-textarea-select - Fired when the selection changes while the editor is focused
  *
  * @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 fold-trigger - Native button created by a folding action; style its visual appearance without changing its target or keyboard behavior.
+ * @csspart fold-icon - Consumer-supplied icon inside a folding action button, when provided.
  * @csspart editor-area - The container positioning the editor over the slotted textarea.
  * @csspart editor - The contenteditable field surface.
  *
@@ -53,26 +68,46 @@ interface UndoEntry {
  * @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 line-direction - `base` (default) gives every line the editor's base direction; `auto` gives
+ *   each line the direction of its first strong character, holding lines without one to the base.
+ * @attr [data-readonly] - Reflected while the slotted `<textarea>` is `readonly`. The editor stays
+ *   focusable and selectable, announces `aria-readonly`, and blocks edits.
  * @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
- * @cssprop [--rc-textarea-color=FieldText] - Text color; falls back through --rc-text
+ * @cssprop [--rc-textarea-color=var(--rc-field-text, FieldText)] - Text color
  * @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 field area
+ * @cssprop [--rc-textarea-padding-block=0.5em] - Block padding of the editor and gutter; any `padding-block` value
+ * @cssprop [--rc-textarea-padding-inline=0.5em] - Inline padding on both sides of the editor and before the gutter; one length, which the active line highlight bleeds through
+ * @cssprop [--rc-textarea-gutter-min-inline-size=24px] - Minimum width of the gutter, including its padding
+ * @cssprop [--rc-textarea-trailing-size=2.5em] - Reserved inline space and minimum block size for trailing controls
  * @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
+ * @cssprop [--rc-textarea-active-line-bg=transparent] - Active line highlight color, including editor and gutter padding
  * @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-content-gap=0.25em] - Gap between a retained line number and custom gutter content
  * @cssprop [--rc-textarea-gutter-padding-inline-end=0.75em] - Space between gutter labels and text
+ * @cssprop [--rc-line-actions-gap=2px] - Gap between inline line actions; popover actions default to 4px
+ * @cssprop [--rc-line-actions-margin-start=6px] - Inline-start margin before line actions
+ * @cssprop [--rc-line-action-padding=1px] - Inline line-action padding; popover actions default to 4px 6px
+ * @cssprop [--rc-line-action-border=none] - Line-action border; the popover surface defaults to 1px solid ButtonBorder
+ * @cssprop [--rc-line-action-border-radius=3px] - Line-action border radius; the popover surface defaults to 4px
+ * @cssprop [--rc-line-action-bg=transparent] - Line-action background; the popover surface defaults to Canvas
+ * @cssprop [--rc-line-action-color=inherit] - Line-action color; popover actions default to ButtonText
+ * @cssprop [--rc-line-action-font-size=1em] - Inline line-action font size; popover actions default to 0.85em
+ * @cssprop [--rc-line-action-opacity=0.4] - Resting opacity of inline line actions
+ * @cssprop [--rc-line-action-hover-opacity=1] - Hover and focus opacity of inline line actions
+ * @cssprop [--rc-line-action-hover-bg=transparent] - Hover and focus background; popover actions default to ButtonFace
+ * @cssprop [--rc-line-action-hover-color=inherit] - Hover and focus text color
+ * @cssprop [--rc-line-action-shadow=0 2px 8px color-mix(in srgb, CanvasText 15%, transparent)] - Line-action popover shadow
  */
 export declare class RCTextarea extends LitElement {
     static styles: CSSResultGroup;
@@ -97,8 +132,20 @@ export declare class RCTextarea extends LitElement {
     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;
+    /**
+     * How each line's direction is chosen. `base` gives every line the editor's
+     * base direction, which suits code. `auto` gives a line with a letter the
+     * direction of its first strong character, for prose that mixes scripts, and
+     * holds lines without one (empty, digits, punctuation) to the base direction.
+     */
+    lineDirection: 'auto' | 'base';
+    /**
+     * Whether the slotted `<textarea>` is `readonly`. The native control is the
+     * source of truth; set `readonly` on it to change this state.
+     */
+    get readOnly(): boolean;
+    private _readOnly;
+    private _textareaAttributeObserver;
     /** Declarative plugin hook for framework integrations. */
     get plugin(): RCTextareaPlugin | null;
     /** Declarative plugin hook for framework integrations. */
@@ -130,6 +177,9 @@ export declare class RCTextarea extends LitElement {
     protected _document: RCDocument | null;
     protected _$textareaRef: WeakRef<HTMLTextAreaElement> | null;
     protected readonly _textareaController: NativeChildController<HTMLTextAreaElement>;
+    protected readonly _flowController: FlowController;
+    /** The interface locale, which formats line numbers. */
+    protected readonly _localeController: LocaleController;
     /** Plugin-owned decorations */
     protected _pluginDecorations: Map<string, Decoration>;
     /** Pattern-generated decorations (rebuilt on each value change). */
@@ -148,6 +198,9 @@ export declare class RCTextarea extends LitElement {
     protected _savedSelection: SavedSelection | null;
     protected _rafHandle: number | null;
     protected _composing: boolean;
+    private _contentAttributesPendingRender;
+    /** Set by Escape: the next Tab moves focus instead of inserting `\t`. */
+    private _tabMovesFocus;
     protected _isRendering: boolean;
     /** The currently highlighted `.line` element (active line). */
     protected _$activeLine: HTMLElement | null;
@@ -158,8 +211,18 @@ export declare class RCTextarea extends LitElement {
     protected _undoStack: UndoEntry[];
     protected _undoIndex: number;
     protected _resizeObserver: ResizeObserver | null;
+    protected _gutterBlockAxis: 'x' | 'y' | null;
     /** Cached per-line gutter labels from the last render — reused by ResizeObserver. */
-    protected _gutterLabels: (string | null)[];
+    protected _gutterLabels: (string | HTMLElement | null | {
+        number: string;
+        content: string | HTMLElement;
+    })[];
+    /** Gutter cells with explicitly accessible plugin controls. */
+    protected _accessibleGutterLines: Set<number>;
+    /** Collapsed source ranges from the most recent render. */
+    protected _foldedRanges: FoldDecoration[];
+    protected _foldBounds: FoldBounds[];
+    protected _hiddenGutterLines: Set<number>;
     /**
      * The current field value.
      *
@@ -176,18 +239,52 @@ export declare class RCTextarea extends LitElement {
     disconnectedCallback(): void;
     firstUpdated(): void;
     updated(changed: Map<string, unknown>): void;
-    render(): import('lit').TemplateResult<1>;
+    private _observeTextarea;
+    /**
+     * Mirror the native textarea's content attributes onto the editor. `lang`
+     * picks glyphs, the spelling dictionary and word boundaries; `spellcheck`
+     * stays off unless the textarea sets it. The host's own `lang` is the
+     * interface language and is never copied.
+     */
+    protected _syncContentAttributes(): void;
+    /**
+     * Set the editor's base direction from the textarea's `dir`. `auto` reads
+     * the native control's directionality, including its LTR neutral fallback;
+     * without `dir` the editor inherits. Composition keeps the current direction
+     * so the IME session isn't disturbed.
+     */
+    protected _syncContentDirection(): void;
+    /** The textarea's `lang`, or `''` when it sets none. */
+    protected _contentLang(): string;
+    /** The editor's resolved base direction. */
+    protected _contentDirection(): 'ltr' | 'rtl';
+    /**
+     * Mark lines with no strong character so `line-direction="auto"` holds them
+     * to the base direction. Reads the model value, which composition text
+     * doesn't reach until `compositionend`, so a composing line keeps its mark.
+     */
+    protected _syncLineDirections(value: string): void;
+    /**
+     * Mirror the native textarea's `readonly` attribute: the editor stays a
+     * focusable, selectable textbox that announces `aria-readonly`, and edits
+     * are blocked by the existing input guards.
+     */
+    protected _syncReadOnly(): void;
+    render(): import('lit-html').TemplateResult<1>;
     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 _revealFoldAtOffset(offset: number): boolean;
+    protected _revealFoldForEdit(inputType: string): boolean;
     protected _onInput(): void;
     protected _onSelectionChange: () => void;
     protected _updateActiveLine(): void;
     protected _updateActiveGutterCell(): void;
     protected _onKeyDown: (e: KeyboardEvent) => void;
+    protected _isWidgetEvent(event: Event): boolean;
     protected _insertText(text: string): void;
     /**
      * Wrap the current selection with `prefix` and `suffix`.
@@ -204,6 +301,7 @@ export declare class RCTextarea extends LitElement {
      * When the selection is collapsed this is equivalent to `insertText`.
      */
     replaceSelection(text: string): void;
+    protected _onCopy: (event: ClipboardEvent) => void;
     protected _onPaste: (e: ClipboardEvent) => void;
     /** Reset the undo/redo history. Call when the field receives entirely new content. */
     clearHistory(): void;
@@ -251,15 +349,17 @@ export declare class RCTextarea extends LitElement {
      * - `string` — the label to display
      * - `null`   — render an empty cell
      */
-    protected _computeGutterLabels(allDecorations: Decoration[], value?: string): (string | null)[];
+    protected _computeGutterLabels(allDecorations: Decoration[], value?: string): (string | HTMLElement | null | {
+        number: string;
+        content: string | HTMLElement;
+    })[];
     /**
-     * Synchronize the pixel height of each gutter cell to match the
+     * Synchronize the block size of each gutter cell to match the
      * 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
-     * `height` so wrapped lines stay vertically aligned with their gutter label.
-     * Also copies the editor's computed `paddingTop`/`paddingBottom` to the
+     * In non-word-wrap mode without block widgets the gutter uses a uniform
+     * line height. Wrapped lines and block widgets use per-line heights instead.
+     * Also copies the editor's computed block padding to the
      * gutter to compensate for browser UA overrides on contenteditable.
      */
     protected _syncGutterHeights(): void;
@@ -269,7 +369,10 @@ export declare class RCTextarea extends LitElement {
      * `_gutterLabels` is updated first; otherwise the cached labels are reused
      * (called by the `ResizeObserver` without a new render pass).
      */
-    protected _syncGutter(labels?: (string | null)[]): void;
+    protected _syncGutter(labels?: (string | HTMLElement | null | {
+        number: string;
+        content: string | HTMLElement;
+    })[]): void;
     protected _syncLabel(): void;
     protected _syncTypography($textarea: HTMLTextAreaElement): void;
     protected _syncTextareaValue(fromUser?: boolean): void;

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

@@ -28,6 +28,8 @@ interface DomPosition {
  * Returns null if offset is out of range.
  */
 export declare function textOffsetToDom($root: Element, targetOffset: number): DomPosition | null;
+/** Returns the current selection focus node when it belongs to `$root`. */
+export declare function getSelectionFocusNode($root: Element): Node | null;
 /**
  * Captures the current browser selection as plain-text offsets relative to `$root`.
  *

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

@@ -61,13 +61,19 @@ export interface LineDecoration {
     /** Additional HTML attributes set directly on the line element. */
     attributes?: Record<string, string>;
     /**
-     * Override the built-in gutter cell text for this line.
+     * Override the built-in gutter cell content for this line.
      *
      * - `string`    — custom label (e.g. `"!"`, `"▶"`)
+     * - `HTMLElement` — plugin-owned marker or control; reuse its node between updates.
+     *   Set `gutterAccessible` when it contains an interactive control.
      * - `null`      — force empty cell (suppress built-in content)
      * - `undefined` — use the built-in mode default (`line-numbers`, `gutter`, etc.)
      */
-    gutterContent?: string | null;
+    gutterContent?: string | HTMLElement | null;
+    /** Keep the built-in line number before custom gutter content when `line-numbers` is enabled. */
+    gutterLineNumber?: boolean;
+    /** Expose this gutter cell to assistive technology when it contains a control. */
+    gutterAccessible?: boolean;
 }
 /**
  * A non-editable DOM element inserted at a character offset.
@@ -81,17 +87,36 @@ export interface WidgetDecoration {
     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 widget content when its line rebuilds. With a stable key, content may be reused. */
     create(): HTMLElement;
     /** Whether to place the widget before or after the character at `offset`. Default: 'before'. */
     side?: 'before' | 'after';
+    /** Preserve this widget's line DOM while its key and decorations remain unchanged.
+     * Change the key when its content changes. Scope keys to the owning plugin.
+     */
+    key?: string;
+    /** Place the widget inline, below its logical line, or in a reserved trailing lane. */
+    layout?: 'inline' | 'block' | 'trailing';
+    /** Expose interactive or meaningful widget content to assistive technology. Default: false. */
+    accessible?: boolean;
+}
+/** Hide complete source lines while retaining their text and model offsets. */
+export interface FoldDecoration {
+    id: string;
+    type: 'fold';
+    /** First hidden line, one-based and inclusive. */
+    fromLine: number;
+    /** Last hidden line, one-based and inclusive. */
+    toLine: number;
+    /** Reveal this range before a user edit or caret move enters its hidden lines. */
+    reveal(): void;
 }
 /** Decorations are visual formatting applied to the field content without affecting
  *  the underlying plain text value.
  */
-export type Decoration = MarkDecoration | LineDecoration | WidgetDecoration;
+export type Decoration = MarkDecoration | LineDecoration | WidgetDecoration | FoldDecoration;
 /** 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'>;
+export type DecorationInput = Omit<MarkDecoration, 'id'> | Omit<LineDecoration, 'id'> | Omit<WidgetDecoration, 'id'> | Omit<FoldDecoration, 'id'>;
 /**
  * A semantic token produced by an external tokenizer (lezer, tree-sitter, shiki, etc.).
  *
@@ -138,6 +163,19 @@ export interface RCTextareaPluginAPI {
     readonly selectionStart: number;
     /** Normalized selection end offset (always ≥ `selectionStart`). Equals `selectionStart` when the cursor is collapsed. */
     readonly selectionEnd: number;
+    /**
+     * The editor's resolved base direction, from the textarea's `dir` or the
+     * host's. Anchor caret-relative popups with this, not the host's flow.
+     */
+    readonly contentDirection: 'ltr' | 'rtl';
+    /** The content language: the textarea's `lang`, or `''` when it sets none. */
+    readonly contentLang: string;
+    /**
+     * The resolved direction of a 1-based line. Under `line-direction="auto"`
+     * that is the direction of the line's first strong character; otherwise,
+     * and for lines without one, it is `contentDirection`.
+     */
+    lineDirection(line: number): 'ltr' | 'rtl';
     /**
      * Returns the bounding rect of the cursor (caret) in viewport coordinates.
      *
@@ -150,8 +188,13 @@ export interface RCTextareaPluginAPI {
     /**
      * 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)
+     * Words come from `Intl.Segmenter` for `contentLang` (UAX #29, with
+     * dictionary segmentation for Japanese and Thai), so `crème`, `don't` and
+     * `snake_case` are each one word. The word starting at the cursor wins over
+     * the one ending there.
+     *
+     * @returns the word and its `[from, to)` offsets, or `null` if the cursor
+     *   touches no letter or digit
      */
     getWordAtCursor(): {
         word: string;
@@ -341,8 +384,8 @@ export interface RCTextareaPlugin {
     /** Called when the plugin is replaced or the element disconnects. */
     destroy?(): void;
     /**
-     * Display-layer value transform — called before `update`/`highlight` in
-     * read-only mode.
+     * Display-layer value transform — called before `update`/`highlight`
+     * while the slotted textarea is `readonly`.
      *
      * Return a non-null string to substitute it as the rendered
      * text passed to all subsequent hooks and to the document builder.

package/package.json

@@ -3,8 +3,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.5.0",
-  "description": "Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.",
+  "version": "0.7.0",
+  "description": "Textarea wrapper with line decorations, gutter rendering, folding actions, and plugin hooks.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
@@ -29,6 +29,12 @@
         "types": "./dist/types/packages/rc-textarea/src/define.d.ts",
         "default": "./dist/rc-textarea-define.js"
       }
+    },
+    "./folding": {
+      "import": {
+        "types": "./dist/types/packages/rc-textarea/src/folding.d.ts",
+        "default": "./dist/rc-textarea-folding.js"
+      }
     }
   },
   "types": "./dist/types/packages/rc-textarea/src/index.d.ts",
@@ -45,7 +51,7 @@
     "test:browser:firefox": "vitest --run --project=firefox"
   },
   "dependencies": {
-    "@rcarls/rc-common": "0.5.0",
+    "@rcarls/rc-common": "0.7.0",
     "parchment": "^3.0.0"
   },
   "devDependencies": {