@rcarls/rc-textarea 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,157 @@
+# @rcarls/rc-textarea
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 079e025: Standardize component styling contracts for the breaking 0.7 release.
+
+  BREAKING CHANGE: Rename the Markdown editor's `--rme-*` properties to
+  `--rc-markdown-editor-*`, `--rc-app-bar-background` to `--rc-app-bar-bg`,
+  `--rc-textarea-radius` to `--rc-textarea-border-radius`, the transfer-list
+  `--rc-transfer-list-panel-*` properties to `--rc-transfer-list-listbox-*`,
+  `--rc-chip-group-webkit-scrollbar-display` to
+  `--rc-chip-group-scrollbar-display`, and `--rc-text` to `--rc-field-text`.
+  Compatibility aliases are intentionally not provided.
+
+  BREAKING CHANGE: Replace `--rc-select-chip-padding-inline` and
+  `--rc-combobox-chip-padding-inline` with explicit `*-padding-inline-start` and
+  `*-padding-inline-end` tokens. Generated removable chips now reserve the full
+  remove target and its edge offset, so their indicator cannot overlap label text.
+
+  Add canonical app-bar elevation, transfer-list listbox radius, and textarea
+  line-action tokens. Add logical `rc-chip` inline-padding properties so themes
+  can implement Material's icon-aware spacing without overriding authored child
+  styles. Make `rc-field` consume the shared semantic token layer,
+  and place the `rc-chip` and `rc-search-bar` light-DOM structural styles in the
+  `rc-base` cascade layer so normal consumer rules override them.
+
+  Prevent decorative, `aria-hidden` trailing list content from intercepting a
+  whole-row action target, and keep segmented-list item geometry from leaking
+  into nested standard lists.
+
+  Remove unused Material navigation-rail toggle tokens and obsolete list-item
+  theme tokens. Register the segmented-button private theme seam and enforce
+  token ownership, documentation, removed-name, selector-budget, and cascade
+  layer contracts through the component architecture audit.
+
+### Patch Changes
+
+- 4617b45: Keep active-line and cursor tracking consistent when browsers expose a shadow-DOM selection
+  through different selection APIs.
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Patch Changes
+
+- 985067e: Allow `rc-textarea` to shrink below its intrinsic content width so `word-wrap`
+  wraps long, unbroken lines inside narrow grid and flex layouts instead of
+  forcing the consumer layout to overflow.
+- 57370e4: Align component metadata, aggregate framework typings, development-time native-child
+  validation, controlled menu state, package declarations, and public documentation before the
+  next release.
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- 689340c: Remove pre-1.0 deprecated APIs: the boolean `keyNavigation` option, `rc-disclosure.fragment`,
+  `rc-textarea.listNumbers`, `rc-textarea.label`, and `decorationsFromHtml`.
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 46810f7: Render line breaks immediately when Enter is pressed at the end of an editable line, including virtual-keyboard `beforeinput` events.
+- 32b1dc4: Allow gutter typography to be themed independently with `--rc-textarea-gutter-font-family`.
+- c50d9e2: Document the `root`, `gutter`, `gutter-cells`, `editor-area`, and `editor` CSS
+  parts, all public attributes, and the `--rc-textarea-gutter-padding-inline-end`
+  custom property in the generated API reference.
+- be4f0ae: Fix `defaultValue` so its HTML attribute is `default-value`, matching every
+  other `default-*` attribute in the library. It previously had no kebab-case
+  mapping, so `<rc-textarea default-value="...">` was silently ignored.
+- c40a1be: Add theme-neutral fast, default, and slow effects and spatial motion token
+  pairs. Expose bottom-sheet settle easing through
+  `--rc-bottom-sheet-snap-easing` and map sheet settling to the Material spatial
+  motion scheme.
+
+  Give direct-child bottom-sheet handles a full-width 48px interaction target
+  while preserving the 32 by 4 pixel visual indicator. Replace rectangular
+  mobile browser tap highlights on chips with themeable, shape-clipped state
+  layers. Keep bottom-sheet snap targets docked to the block-end edge when CSS
+  minimum or maximum sizing constrains their requested heights.
+
+  Mount declaratively assigned textarea plugins at connection time and remount
+  them after reconnection, preserving plugin effects and adopted styles in
+  framework render lifecycles.
+
+- aecba33: Fix cursor position tracking in WebKit, where a plain Range from `getRangeAt()` does not
+  resolve inside `rc-textarea`'s open shadow root. This made every Enter press and
+  virtual-keyboard paragraph insert land at the start of the value instead of the cursor. Fall
+  back to `Selection.getComposedRanges()` when Chrome's non-standard `shadowRoot.getSelection()`
+  isn't available.
+- Updated dependencies [e57277f]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+  - @rcarls/rc-common@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- 808afe4: ### Fixed
+
+  - Fix regression where the visible editor did not reflect `value` and `defaultValue` on first mount.
+  - @rcarls/rc-common@0.3.1
+
+## 0.3.0
+
+### Added
+
+- Add `parseDecorationsFromHtml` as the canonical HTML decoration helper.
+- Add `rc-textarea` to `HTMLElementTagNameMap`.
+
+### Changed
+
+- Deprecate `decorationsFromHtml` in favor of `parseDecorationsFromHtml`.
+- Rename internal Parchment blot classes and document helpers from `V2` to `RC`.
+- Expand public JSDoc across the component and plugin APIs.
+- Update package metadata, README intro, and docs links.
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0

package/README.md

@@ -0,0 +1,317 @@
+# rc-textarea
+
+Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-textarea](https://richardcarls.github.io/rc-webcomponents/components/rc-textarea).
+
+Made with [Lit](https://lit.dev) and [Parchment](https://github.com/quilljs/parchment).
+
+---
+
+## Feature Highlights
+
+- **Mixed inline formatting** - bold, italic, color, background, and underline
+- **Imperative APIs** that behave well with reactive frameworks
+- **Error-lens style line annotations** that stay separate from text content
+- **Inline widgets** - color swatches, icons, tooltips or quick action buttons are possible
+- **Simple Pattern API** that auto-decorates text matching regular expressions
+- **Plugin API** - imperative decoration control + highlight.js / prism.js HTML compatibility bridge
+- **Line numbers, word wrap, auto-grow** - declarative features for common use cases
+- **Progressive enhancement** - wraps a native `<textarea>` for form submission, label association
+- **Undo/redo** - durable internally tracked undo stack
+
+---
+
+## Installation
+
+```bash
+npm install @rcarls/rc-textarea
+```
+
+```bash
+yarn add @rcarls/rc-textarea
+```
+
+Import the define entry to register `<rc-textarea>`:
+
+```ts
+import '@rcarls/rc-textarea/define';
+```
+
+Import public types when you need typed access:
+
+```ts
+import type { RCTextarea, RCTextareaPlugin } from '@rcarls/rc-textarea';
+```
+
+## Basic Usage
+
+Slot a native `<textarea>` as the direct child. It is hidden from view and used
+only for form wiring.
+
+```html
+<label for="message">Message</label>
+
+<rc-textarea line-numbers word-wrap auto-grow>
+  <textarea id="message" name="message" rows="10" placeholder="Start typing..."></textarea>
+</rc-textarea>
+```
+
+Use the `value` property for controlled updates, `defaultValue` for an initial uncontrolled
+value, and `rc-textarea-change` for user-originated changes.
+
+```ts
+const editor = document.querySelector('rc-textarea');
+
+editor.value = 'Programmatic updates are silent.';
+
+editor.addEventListener('rc-textarea-change', (event) => {
+  console.log(event.detail.value);
+});
+```
+
+When the user edits, the slotted textarea is kept in sync and dispatches a native bubbling
+`input` event. Submitting a form reads the textarea's plain-text value normally.
+
+```html
+<form>
+  <rc-textarea>
+    <textarea name="body" required maxlength="5000"></textarea>
+  </rc-textarea>
+
+  <button type="submit">Send</button>
+</form>
+```
+
+## Common Options
+
+| Attribute      | Property      | Description                                                                         |
+| -------------- | ------------- | ----------------------------------------------------------------------------------- |
+| `line-numbers` | `lineNumbers` | Show sequential line numbers in the gutter.                                         |
+| `gutter`       | `gutter`      | Show an empty gutter that plugins can populate with `LineDecoration.gutterContent`. |
+| `word-wrap`    | `wordWrap`    | Wrap long lines instead of scrolling horizontally.                                  |
+| `auto-grow`    | `autoGrow`    | Let the field grow vertically with content.                                         |
+| `read-only`    | `readOnly`    | Render selectable, non-editable content.                                            |
+
+Use a plugin with `LineDecoration.gutterContent` for sparse numbering. Put accessible names on
+the slotted textarea with `aria-label` or a real `<label for="...">`.
+
+The main JavaScript-only properties are:
+
+| Property                          | Type                       | Description                                                               |
+| --------------------------------- | -------------------------- | ------------------------------------------------------------------------- |
+| `value`                           | `string`                   | Current plain-text value. Host writes are silent.                         |
+| `defaultValue`                    | `string \| undefined`      | Initial uncontrolled value, used before `value` or textarea content wins. |
+| `plugin`                          | `RCTextareaPlugin \| null` | Declarative plugin hook for reactive frameworks.                          |
+| `decorations`                     | `DecorationInput[]`        | External decoration layer merged with plugin and pattern decorations.     |
+| `selectionStart` / `selectionEnd` | `number`                   | Current plain-text selection offsets.                                     |
+
+## Events
+
+All public events bubble and are composed.
+
+| Event                | Detail                                             | Fires when                                         |
+| -------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| `rc-textarea-change` | `{ value: string }`                                | User editing changes the plain-text value.         |
+| `rc-textarea-focus`  | none                                               | The editor receives focus.                         |
+| `rc-textarea-blur`   | none                                               | The editor loses focus.                            |
+| `rc-textarea-select` | `{ selectionStart: number, selectionEnd: number }` | The selection changes while the editor is focused. |
+
+## Pattern Highlights
+
+Use `addPattern()` for lightweight regex decoration without writing a plugin.
+
+```ts
+const todoPatternId = editor.addPattern({
+  pattern: /\bTODO\b/g,
+  bold: true,
+  color: 'var(--editor-todo-color)',
+});
+
+editor.removePattern(todoPatternId);
+editor.clearPatterns();
+```
+
+Patterns can also style named capture groups and add line diagnostics.
+
+```ts
+editor.addPattern({
+  pattern: /^(?<key>\w[\w-]*):\s*(?<value>.+)$/gm,
+  captureGroups: {
+    key: { bold: true, color: 'var(--editor-key-color)' },
+    value: { color: 'var(--editor-value-color)' },
+  },
+  createLineDecoration: () => ({ className: 'config-line' }),
+});
+```
+
+See [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) for the complete decoration and plugin model.
+
+## Markdown Plugin Package
+
+Install the Markdown plugin package when you want Markdown-oriented decorations and preview
+HTML without writing your own parser bridge.
+
+```bash
+npm install @rcarls/rc-textarea @rcarls/rc-textarea-plugin-markdown \
+  mdast-util-from-markdown micromark unist-util-visit
+```
+
+```bash
+yarn add @rcarls/rc-textarea @rcarls/rc-textarea-plugin-markdown \
+  mdast-util-from-markdown micromark unist-util-visit
+```
+
+```ts
+import '@rcarls/rc-textarea/define';
+import { createMarkdownPlugin } from '@rcarls/rc-textarea-plugin-markdown';
+
+const editor = document.querySelector('rc-textarea');
+const markdown = createMarkdownPlugin();
+
+editor.usePlugin(markdown);
+
+preview.innerHTML = markdown.getPreviewHtml(editor.value);
+```
+
+The package decorates common Markdown syntax using `mdast-util-from-markdown` and exposes
+`getMarkdownPreviewHtml()` / `plugin.getPreviewHtml()` for preview rendering.
+
+## highlight.js And Prism Bridge
+
+`rc-textarea` can consume the HTML strings produced by highlighters that wrap token text in
+`<span class="...">...</span>` nodes. Return that HTML from `highlight()` or call
+`api.parseDecorationsFromHtml()` yourself inside `update()`.
+
+```ts
+import hljs from 'highlight.js/lib/core';
+import javascript from 'highlight.js/lib/languages/javascript';
+
+hljs.registerLanguage('javascript', javascript);
+
+editor.usePlugin({
+  mount(api) {
+    api.adoptStyleSheet(`
+      .hljs-keyword { color: var(--editor-syntax-keyword); font-weight: 600; }
+      .hljs-string { color: var(--editor-syntax-string); }
+      .hljs-comment { color: var(--editor-syntax-comment); font-style: italic; }
+    `);
+  },
+
+  highlight(value) {
+    return hljs.highlight(value, { language: 'javascript' }).value;
+  },
+});
+```
+
+```ts
+import Prism from 'prismjs';
+import 'prismjs/components/prism-python';
+
+editor.usePlugin({
+  mount(api) {
+    api.adoptStyleSheet(`
+      .token.keyword { color: var(--editor-syntax-keyword); font-weight: 600; }
+      .token.string { color: var(--editor-syntax-string); }
+      .token.comment { color: var(--editor-syntax-comment); font-style: italic; }
+    `);
+  },
+
+  highlight(value) {
+    return Prism.highlight(value, Prism.languages.python, 'python');
+  },
+});
+```
+
+For Lezer, Unified, and Shiki integrations, see `@rcarls/rc-textarea-adapters`.
+
+## Theming
+
+`rc-textarea` is design-system neutral and uses CSS system colors by default. Theme it with broad tokens
+for the field, then add component tokens for editor-specific surfaces.
+
+### Broad Theme Tokens
+
+The component reads inherited tokens where possible:
+
+| Token             | Use                                                          |
+| ----------------- | ------------------------------------------------------------ |
+| `--rc-field-text` | Fallback text color before `--rc-textarea-color`.            |
+| `color-scheme`    | Inherited by the host so system colors match the page theme. |
+
+### Component Tokens
+
+| Token                                     | Default                                     | Use                                   |
+| ----------------------------------------- | ------------------------------------------- | ------------------------------------- |
+| `--rc-textarea-font-family`               | `monospace`                                 | Editor font family.                   |
+| `--rc-textarea-font-size`                 | `1em`                                       | Editor and gutter font size.          |
+| `--rc-textarea-line-height`               | `1.5`                                       | Editor and gutter line height.        |
+| `--rc-textarea-padding`                   | `0.5em`                                     | Editor and gutter padding.            |
+| `--rc-textarea-background`                | `Field`                                     | Field background.                     |
+| `--rc-textarea-color`                     | `var(--rc-field-text, FieldText)`           | Field text color.                     |
+| `--rc-textarea-caret-color`               | `var(--rc-textarea-color, FieldText)`       | Caret color.                          |
+| `--rc-textarea-border`                    | `1px solid ButtonBorder`                    | Field border.                         |
+| `--rc-textarea-border-radius`             | `2px`                                       | Field corner radius.                  |
+| `--rc-textarea-focus-outline`             | `2px solid Highlight`                       | Focus ring.                           |
+| `--rc-textarea-active-line-bg`            | `transparent`                               | Active line background.               |
+| `--rc-textarea-gutter-bg`                 | `Canvas`                                    | Gutter background.                    |
+| `--rc-textarea-gutter-color`              | `GrayText`                                  | Gutter text color.                    |
+| `--rc-textarea-gutter-border`             | `1px solid ButtonBorder`                    | Gutter separator.                     |
+| `--rc-textarea-gutter-font-family`        | `var(--rc-textarea-font-family, monospace)` | Gutter font family.                   |
+| `--rc-textarea-gutter-padding-inline-end` | `0.75em`                                    | Space between gutter labels and text. |
+
+Line actions added by plugins use the `--rc-line-action-*` family. Inline actions default to
+compact, inherited styling; popover actions use `Canvas`, `ButtonText`, and `ButtonFace` system
+colors where their surface needs an independent default. The public hooks are
+`--rc-line-actions-gap`, `--rc-line-actions-margin-start`, `--rc-line-action-padding`,
+`--rc-line-action-border`, `--rc-line-action-border-radius`, `--rc-line-action-bg`,
+`--rc-line-action-color`, `--rc-line-action-font-size`, `--rc-line-action-opacity`,
+`--rc-line-action-hover-opacity`, `--rc-line-action-hover-bg`,
+`--rc-line-action-hover-color`, and `--rc-line-action-shadow`.
+
+```css
+rc-textarea {
+  color-scheme: dark;
+  --rc-textarea-font-family: 'Fira Code', monospace;
+  --rc-textarea-font-size: 13px;
+  --rc-textarea-background: #1e1e2e;
+  --rc-textarea-color: #cdd6f4;
+  --rc-textarea-border: 1px solid #313244;
+  --rc-textarea-active-line-bg: rgb(255 255 255 / 0.06);
+}
+```
+
+### Parts And Decoration Styles
+
+The exposed CSS parts are `root`, `gutter`, `gutter-cells`, `editor-area`, and `editor`.
+
+```css
+rc-textarea::part(editor) {
+  tab-size: 2;
+}
+```
+
+Decoration elements are inside the shadow root. Use `api.adoptStyleSheet()` from a plugin to
+style custom classes such as `.my-highlight`, `.line[data-message]`, or token classes from a
+syntax highlighter.
+
+## Keyboard Behavior
+
+| Key                               | Behavior                                                     |
+| --------------------------------- | ------------------------------------------------------------ |
+| `Tab`                             | Inserts `\t`.                                                |
+| `Ctrl/Cmd+Z`                      | Undo.                                                        |
+| `Ctrl/Cmd+Y` / `Ctrl/Cmd+Shift+Z` | Redo.                                                        |
+| `Paste`                           | Inserts plain text only and normalizes line endings to `\n`. |
+| `Enter`                           | Inserts a line break.                                        |
+
+## More Detail
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) covers custom plugins, decoration types,
+  selection APIs, stylesheet injection, and parser/highlighter recipes.
+- [ARCHITECTURE.md](ARCHITECTURE.md) is an internal contributor reference for the rendering
+  loop, Parchment integration, selection mapping, and gutter synchronization.
+
+## License
+
+[MIT](../../LICENSE)