@vanduo-oss/vd3-cbun 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@vanduo-oss/vd3-cbun` are documented here. This file
 tracks the PACKAGE only — never docs-site content. Per-component VERSION
 constants are listed alongside each bundle release.
 
+## 1.1.0 — 2026-07-21
+
+Adds a fifth component, **`code-editor`** (`@vanduo-oss/vd3-cbun/code-editor` +
+`./code-editor/css`), exposing `VdCodeEditor` — a lightweight, first-party
+**textarea-overlay** code editor: a native `<textarea>` rendered transparently
+over a `<pre>` highlight layer painted by homegrown, ReDoS-safe tokenizers for
+JavaScript/TypeScript, HTML, CSS, JSON, Markdown, Shell, and Python. No
+third-party editor and no new runtime dependency — `vue` stays the only peer, and
+every input bundled for the entry lives under `src/code-editor/` (the metafile
+isolation guard passes). v1 features: line-number gutter + active-line highlight,
+auto-indent + Tab-to-spaces + bracket/quote auto-close, read-only mode +
+copy-to-clipboard, empty-state placeholder, and a large-input performance guard.
+Rendering is escaping-safe and `innerHTML`-free (DOM nodes via `replaceChildren`),
+and the component is SSR-safe (DOM touched only on mount). The four existing
+components are untouched (tree-shake contract). Additive minor: bundle
+`1.0.0 → 1.1.0`.
+
+Component versions in this release: **charts 1.0.0, code-editor 1.0.0, flowchart
+1.2.0, hex-grid 1.0.0, music-player 1.0.0** — the new `code-editor` enters the
+`component-versions.json` manifest at `1.0.0`; the bundle's own semver stays
+decoupled from the per-component `VERSION` constants.
+
 ## 1.0.0 — 2026-07-14
 
 First public release of `@vanduo-oss/vd3-cbun` — the Vanduo **components bundle**

package/README.md

@@ -2,16 +2,16 @@
 
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-The Vanduo **components bundle** for the vd3 line: Vue3-only charts, flowchart,
-hex-grid, and music-player consolidated into ONE package with tree-shakeable
-subpath exports. It replaces the four per-repo publishes (`@vanduo-oss/charts`,
-`@vanduo-oss/flowchart`, `@vanduo-oss/hex-grid`, `@vanduo-oss/music-player`)
-of the old line.
+The Vanduo **components bundle** for the vd3 line: Vue3-only charts, code-editor,
+flowchart, hex-grid, and music-player consolidated into ONE package with
+tree-shakeable subpath exports. It replaces the four per-repo publishes
+(`@vanduo-oss/charts`, `@vanduo-oss/flowchart`, `@vanduo-oss/hex-grid`,
+`@vanduo-oss/music-player`) of the old line.
 
-**Status: 1.0.0 — first public release.** All four component families are
-consolidated Vue3-only (vanilla auto-init/window-global layers excised), each on
-its own tree-shakeable subpath, with the esbuild metafile isolation guard in
-place.
+**Status: 1.1.0.** Five Vue3-only component families — charts, code-editor,
+flowchart, hex-grid, music-player — each on its own tree-shakeable subpath, with
+the esbuild metafile isolation guard in place. (1.1.0 adds the first-party
+`code-editor` component; see the [changelog](./CHANGELOG.md).)
 
 ## Install
 
@@ -32,6 +32,9 @@ Each component lives on its own subpath — importing one never pulls in another
 import { VdChart } from '@vanduo-oss/vd3-cbun/charts';
 import '@vanduo-oss/vd3-cbun/charts/css';
 
+import { VdCodeEditor } from '@vanduo-oss/vd3-cbun/code-editor';
+import '@vanduo-oss/vd3-cbun/code-editor/css';
+
 import { VdFlowchart } from '@vanduo-oss/vd3-cbun/flowchart';
 import '@vanduo-oss/vd3-cbun/flowchart/css';
 
@@ -50,7 +53,8 @@ import { VD3_CBUN_VERSIONS } from '@vanduo-oss/vd3-cbun';
 
 Each subpath entry (`dist/<component>/index.js`) re-exports **both** the Vue
 component and its framework-agnostic core (the core aliased with a `Core`
-suffix where the names collide — `VdFlowchartCore`, `VdHexGridCore`). Isolation
+suffix where the names collide — `VdCodeEditorCore`, `VdFlowchartCore`,
+`VdHexGridCore`). Isolation
 is not a convention but a build guard: `scripts/build.js` bundles every entry
 separately with `vue` external, emits an esbuild metafile (`dist/meta.json`),
 and **fails the build** if any component entry's inputs reach outside its own
@@ -74,16 +78,18 @@ Notes:
 The bundle's own semver (`package.json` version) is decoupled from the
 components inside it. Each component carries a VERSION constant tracked in
 `component-versions.json` at the repo root and asserted in tests against the
-exported `VD3_CBUN_VERSIONS` map. At bundle launch, charts, hex-grid, and
-music-player reset to `1.0.0`; **flowchart continues its old-line lineage at
+exported `VD3_CBUN_VERSIONS` map. charts, code-editor, hex-grid, and
+music-player sit at `1.0.0`; **flowchart continues its old-line lineage at
 `1.2.0`** because `VD_FLOWCHART_VERSION` is load-bearing — it is serialized
-into user documents via `toJSON().version`.
+into user documents via `toJSON().version`. A new component enters the manifest
+at `1.0.0` (`code-editor` did, in bundle 1.1.0).
 
 ## Theming
 
-All four components render against Vanduo's `--vd-*` design tokens — the same
-tokens `@vanduo-oss/vd3` defines. charts, flowchart, and hex-grid carry built-in
-fallbacks and degrade gracefully without them; **music-player expects the tokens**
+All five components render against Vanduo's `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines. charts, code-editor, flowchart, and hex-grid
+carry built-in fallbacks and degrade gracefully without them; **music-player
+expects the tokens**
 and renders with unset colors/backgrounds if none are provided. For correct
 theming, supply the tokens on an ancestor element — the simplest way is to ship
 the vd3 stylesheet:
@@ -119,6 +125,8 @@ tokens works — but it is the canonical source.)
 | `@vanduo-oss/vd3-cbun`                    | Root — the `VD3_CBUN_VERSIONS` per-component version map      |
 | `@vanduo-oss/vd3-cbun/charts`             | `VdChart` + typed chart wrappers, factories, scales, `resolveTheme` |
 | `@vanduo-oss/vd3-cbun/charts/css`         | Charts stylesheet (`dist/charts/vd3-charts.css`)             |
+| `@vanduo-oss/vd3-cbun/code-editor`        | `VdCodeEditor` + `VdCodeEditorCore`, `tokenize`, `highlight`, `LANGUAGES` |
+| `@vanduo-oss/vd3-cbun/code-editor/css`    | Code-editor stylesheet (`dist/code-editor/vd3-code-editor.css`) |
 | `@vanduo-oss/vd3-cbun/flowchart`          | `VdFlowchart` + `VdFlowchartCore`, `computeLayout`, `FLOWCHART_*` |
 | `@vanduo-oss/vd3-cbun/flowchart/css`      | Flowchart stylesheet (`dist/flowchart/vd3-flowchart.css`)    |
 | `@vanduo-oss/vd3-cbun/hex-grid`           | `VdHexGrid` + `VdHexGridCore`, `VD_HEX_VERSION`              |

package/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: vanduo-vd3-cbun
-description: Use when adding Vanduo vd3 components with @vanduo-oss/vd3-cbun — the Vue 3 components bundle (charts, flowchart, hex-grid, music-player) with tree-shakeable subpath exports. Covers install, per-subpath imports, CSS, theming, and per-component versioning.
+description: Use when adding Vanduo vd3 components with @vanduo-oss/vd3-cbun — the Vue 3 components bundle (charts, code-editor, flowchart, hex-grid, music-player) with tree-shakeable subpath exports. Covers install, per-subpath imports, CSS, theming, and per-component versioning.
 ---
 
 # @vanduo-oss/vd3-cbun
 
-One bundle, four Vue 3 components, each on its own tree-shakeable subpath
-(`./charts`, `./flowchart`, `./hex-grid`, `./music-player`). `vue >=3.3.0` is a
-required peer. The root import exposes only `VD3_CBUN_VERSIONS` — the per-
+One bundle, five Vue 3 components, each on its own tree-shakeable subpath
+(`./charts`, `./code-editor`, `./flowchart`, `./hex-grid`, `./music-player`).
+`vue >=3.3.0` is a required peer. The root import exposes only `VD3_CBUN_VERSIONS` — the per-
 component VERSION map. Every subpath re-exports the Vue wrapper AND the
 framework-agnostic core alongside it (the core aliased with a `Core` suffix
 where the names collide).
@@ -45,6 +45,29 @@ the scales (`scaleLinear`, `scaleTime`, `scaleBand`, `scalePoint`,
 `resolveTheme`. No name collision, so the core factories keep their own names.
 CSS ships at `@vanduo-oss/vd3-cbun/charts/css`. `VD_CHARTS_VERSION` is `1.0.0`.
 
+## Code-editor
+
+```js
+import { VdCodeEditor, VdCodeEditorCore } from '@vanduo-oss/vd3-cbun/code-editor';
+import '@vanduo-oss/vd3-cbun/code-editor/css';
+```
+
+`VdCodeEditor` is the Vue 3 wrapper (`v-model` binds the contents); the
+framework-agnostic editor core shares the class name, so it is re-exported as
+`VdCodeEditorCore`. It is a lightweight, first-party **textarea-overlay** editor
+— a native `<textarea>` over a `<pre>` highlight layer painted by homegrown,
+ReDoS-safe tokenizers (JavaScript/TypeScript, HTML, CSS, JSON, Markdown, Shell,
+Python) — with a line-number gutter + active-line highlight, auto-indent and
+bracket/quote auto-close, read-only mode, a copy button, a placeholder, and a
+large-input performance guard. No third-party editor and no runtime dependency
+beyond `vue`; rendering is escaping-safe and `innerHTML`-free, and the wrapper is
+SSR-safe (DOM touched only on mount). The subpath also re-exports the pure
+`tokenize`, `highlight`, and `LANGUAGES` helpers plus `VD_CODE_EDITOR_VERSION`.
+Key props: `language`, `readOnly`, `lineNumbers`, `tabSize`, `wrap`,
+`placeholder`, `maxLength`; events: `update:modelValue`, `change`, `focus`,
+`blur`, `ready`. CSS ships at `@vanduo-oss/vd3-cbun/code-editor/css`.
+`VD_CODE_EDITOR_VERSION` is `1.0.0`.
+
 ## Flowchart
 
 ```js

package/dist/code-editor/core.d.ts

@@ -0,0 +1,128 @@
+// Hand-written declarations for the framework-agnostic code-editor core.
+
+export const VD_CODE_EDITOR_VERSION: string;
+
+/** Canonical language ids the editor understands. */
+export type CodeEditorLanguage =
+  | 'plaintext'
+  | 'javascript'
+  | 'typescript'
+  | 'html'
+  | 'css'
+  | 'json'
+  | 'markdown'
+  | 'shell'
+  | 'python';
+
+/** Canonical language ids (aliases like `js`/`py` resolve to these). */
+export const LANGUAGES: readonly CodeEditorLanguage[];
+
+/** Token classes produced by the tokenizers. */
+export type TokenType =
+  | 'plain'
+  | 'keyword'
+  | 'string'
+  | 'comment'
+  | 'number'
+  | 'boolean'
+  | 'null'
+  | 'function'
+  | 'operator'
+  | 'punctuation'
+  | 'property'
+  | 'tag'
+  | 'attribute'
+  | 'regex'
+  | 'variable'
+  | 'builtin'
+  | 'meta';
+
+export interface Token {
+  type: TokenType;
+  value: string;
+}
+
+/**
+ * Tokenize `source` for `language`. Lossless: the token values always
+ * concatenate back to `source` exactly. Unknown languages yield one `plain`
+ * token and never throw.
+ */
+export function tokenize(source: string, language: string): Token[];
+
+/** Tokenize + render to an escaped HTML string (never routed to innerHTML). */
+export function highlight(source: string, language: string): string;
+
+export interface CodeEditorSelection {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export interface VdCodeEditorOptions {
+  /** Container element or a selector for it. */
+  element?: Element | string;
+  /** Initial contents. */
+  value?: string;
+  /** Language id or alias. */
+  language?: string;
+  /** Render as a non-editable viewer. */
+  readOnly?: boolean;
+  /** Show the line-number gutter (ignored in wrap mode). */
+  lineNumbers?: boolean;
+  /** Indent width, in spaces. */
+  tabSize?: number;
+  /** Empty-state placeholder. */
+  placeholder?: string;
+  /** Native `maxlength` cap. */
+  maxLength?: number;
+  /** Soft-wrap long lines (disables the gutter + active-line). */
+  wrap?: boolean;
+  /** Auto-close brackets/quotes and step over closers. */
+  autoClose?: boolean;
+  /** Highlight the caret's line (ignored in wrap mode). */
+  highlightActiveLine?: boolean;
+  /** Skip highlighting above this many characters. */
+  maxHighlightLength?: number;
+  /** Native spellcheck. */
+  spellcheck?: boolean;
+  /** Show the copy-to-clipboard button. */
+  copy?: boolean;
+  /** Accessible label for the textarea. */
+  ariaLabel?: string;
+}
+
+export interface CodeEditorChangeEvent {
+  value: string;
+}
+
+export interface CodeEditorEventMap {
+  change: CodeEditorChangeEvent;
+  focus: FocusEvent;
+  blur: FocusEvent;
+}
+
+export class VdCodeEditor {
+  constructor(options?: VdCodeEditorOptions);
+  readonly element: Element | null;
+  getValue(): string;
+  setValue(next: string, options?: { silent?: boolean }): this;
+  getSelection(): CodeEditorSelection;
+  setSelection(start: number, end?: number): this;
+  insertText(text: string): this;
+  setLanguage(language: string): this;
+  setReadOnly(readOnly: boolean): this;
+  setTabSize(tabSize: number): this;
+  setPlaceholder(text: string): this;
+  setAutoClose(autoClose: boolean): this;
+  focus(): this;
+  blur(): this;
+  on<K extends keyof CodeEditorEventMap>(
+    name: K,
+    handler: (payload: CodeEditorEventMap[K]) => void,
+  ): this;
+  off<K extends keyof CodeEditorEventMap>(
+    name: K,
+    handler: (payload: CodeEditorEventMap[K]) => void,
+  ): this;
+  destroy(): void;
+}