@c2n/code-editor 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nguyen Thai Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @c2n/code-editor
+
+Source-code field built with Lit on **CodeMirror 6**, which is an _optional_ peer dependency: nothing is imported until an editor mounts, and without it the element degrades to a plain `<textarea>` with the same value, events and form behaviour.
+
+```bash
+npm install @c2n/code-editor
+# the engine, installed alongside — only the grammars you need
+npm install @codemirror/state @codemirror/view @codemirror/commands @codemirror/language \
+  @codemirror/autocomplete @codemirror/search @lezer/highlight @codemirror/lang-javascript
+```
+
+```html
+<script type="module">
+  import '@c2n/code-editor'
+</script>
+
+<c2-code-editor label="Handler" language="javascript" line-numbers autocomplete value="export const answer = 42"></c2-code-editor>
+```
+
+- **Value**: `value` is the document; assigning it replaces the text without losing scroll position or undo history, and is silent — only a user edit fires `input`, with `change` on the blur that follows, as a native control does.
+- **Forms**: form-associated. `name` and `value` are submitted, `required` sets `valueMissing`, `checkValidity()` / `setCustomValidity()` work, and reset restores the `value` **attribute** — the same `defaultValue` contract a native control has.
+- **Languages**: `javascript`, `typescript`, `jsx`, `tsx`, `html`, `css` and `json` have built-in loaders, each its own dynamic import. Anything else comes from the `languageLoader` property, so adding Python or SQL costs this package no dependency. An empty `language` is a plain editor with no highlighting.
+- **Behaviour**: `line-numbers`, `wrap`, `autocomplete`, `tab-size`, `placeholder`, `readonly` and `disabled` are all live — each is its own CodeMirror `Compartment`, so toggling one never rebuilds the document.
+- **Engine**: `ready` resolves once the engine settles and `engine` reads `codemirror` or `basic`; the `ready` event carries the same. The fallback textarea is not a second editor — it has no highlighting, no gutter and no bracket matching.
+- **Events**: the editor's `contenteditable` fires native composed `input` / `beforeinput`, which are stopped at the component boundary so a consumer sees exactly one `input` per edit and none for an edit `readonly` rejected.
+- **Accessibility**: the editable element carries `role="textbox"` with the label as its accessible name, plus `aria-readonly` and `aria-disabled`. The default token palette meets WCAG AA on both the surface and the active-line tint.
+
+**Theming is plain CSS.** CodeMirror renders real DOM inside the shadow root, so there is no JavaScript theme: the frame, gutter, selection, cursor and the whole syntax palette are `--c2-code-editor__*` custom properties, and the token names (`--c2-code-editor__theme--token-keyword`, `…-string`, `…-comment`, …) match `@c2n/code-viewer`'s `css-variables` theme so one palette can drive the viewer and the editor. Dark mode is different variable values and nothing else:
+
+```css
+.midnight {
+  --c2-code-editor--background: #0d1117;
+  --c2-code-editor--color: #c9d1d9;
+  --c2-code-editor--border: 1px solid #30363d;
+  --c2-code-editor__theme--token-keyword: #ff7b72;
+  --c2-code-editor__theme--token-string: #a5d6ff;
+  --c2-code-editor__theme--token-comment: #8b949e;
+}
+```
+
+The full list is in `custom-elements.json` and on the docs site.

package/dist/code-editor.js

@@ -0,0 +1,314 @@
+import { BUILT_IN_LANGUAGES, createEditor } from "./engine.js";
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { isServer } from "lit-html/is-server.js";
+import { property, query, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { live } from "lit/directives/live.js";
+import { customElement } from "@c2n/core/element-helper.js";
+//#region src/code-editor.scss?inline
+var code_editor_default = "@charset \"UTF-8\";\n/* ex : var((width: 24px), width, c2-checkbox)  returns var(--c2-checkbox-width, 24px) */\n:host {\n  display: block;\n}\n\n:host([hidden]) {\n  display: none;\n}\n\n.c2-code-editor {\n  display: flex;\n  flex-direction: column;\n  gap: var(--c2-code-editor--gap,6px);\n}\n\n.c2-code-editor__label {\n  color: var(--c2-code-editor__label--color,#18181b);\n  font-size: var(--c2-code-editor__label--font-size,12px);\n  font-weight: var(--c2-code-editor__label--font-weight,500);\n}\n.c2-code-editor__label[hidden] {\n  display: none;\n}\n\n.c2-code-editor__surface,\n.c2-code-editor__fallback,\n.c2-code-editor__pending {\n  box-sizing: border-box;\n  width: 100%;\n  min-height: var(--c2-code-editor--min-height,120px);\n  max-height: var(--c2-code-editor--max-height,420px);\n  margin: 0;\n  overflow: auto;\n  background: var(--c2-code-editor--background,#ffffff);\n  color: var(--c2-code-editor--color,#24292e);\n  border: var(--c2-code-editor--border,1px solid #bcbcc6);\n  border-radius: var(--c2-code-editor--border-radius,6px);\n  box-shadow: var(--c2-code-editor--box-shadow);\n  font-family: var(--c2-code-editor--font-family,ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);\n  font-size: var(--c2-code-editor--font-size,13px);\n  line-height: var(--c2-code-editor--line-height,1.6);\n}\n.c2-code-editor__surface[hidden],\n.c2-code-editor__fallback[hidden],\n.c2-code-editor__pending[hidden] {\n  display: none;\n}\n\n.c2-code-editor__fallback,\n.c2-code-editor__pending {\n  padding: var(--c2-code-editor--padding-block,10px) var(--c2-code-editor--padding-inline,12px);\n  white-space: pre;\n  tab-size: 2;\n}\n\n.c2-code-editor__fallback {\n  display: block;\n  resize: vertical;\n}\n.c2-code-editor__fallback:focus {\n  border: var(--c2-code-editor__focus--border,var(--c2-code-editor--border,1px solid rgb(2, 101, 220)));\n  outline: var(--c2-code-editor__focus--outline,2px solid rgba(2, 101, 220, 0.4));\n  outline-offset: -1px;\n}\n.c2-code-editor__fallback::placeholder {\n  color: var(--c2-code-editor__placeholder--color,#71717a);\n}\n\n.c2-code-editor__pending {\n  color: var(--c2-code-editor__placeholder--color,#71717a);\n}\n\n.c2-code-editor.is-focused .c2-code-editor__surface {\n  border: var(--c2-code-editor__focus--border,var(--c2-code-editor--border,1px solid rgb(2, 101, 220)));\n  outline: var(--c2-code-editor__focus--outline,2px solid rgba(2, 101, 220, 0.4));\n  outline-offset: -1px;\n}\n\n.c2-code-editor.is-invalid .c2-code-editor__surface,\n.c2-code-editor.is-invalid .c2-code-editor__fallback {\n  border: var(--c2-code-editor__error--border,var(--c2-code-editor--border,1px solid #dc2626));\n}\n\n.c2-code-editor.is-disabled {\n  opacity: var(--c2-code-editor__disabled--opacity,0.38);\n}\n.c2-code-editor.is-disabled .c2-code-editor__surface {\n  cursor: default;\n}\n\n/**\n * CodeMirror's own DOM.\n *\n * Its base styles are injected as a `<style>` element into this shadow root, and Lit's `static styles` are an\n * adopted stylesheet — adopted sheets come last in the shadow root's cascade, so these rules win on equal\n * specificity without `!important`, and the extra `.c2-code-editor__surface` ancestor settles the rest. Only the\n * class names CodeMirror documents as stable are used.\n */\n.c2-code-editor__surface .cm-editor {\n  height: 100%;\n  background: transparent;\n  color: inherit;\n  font-family: inherit;\n  font-size: inherit;\n}\n.c2-code-editor__surface .cm-editor.cm-focused {\n  outline: none;\n}\n.c2-code-editor__surface .cm-scroller {\n  font-family: inherit;\n  line-height: inherit;\n  overflow: auto;\n}\n.c2-code-editor__surface .cm-content {\n  padding: var(--c2-code-editor--padding-block,10px) 0;\n  caret-color: var(--c2-code-editor__cursor--color,#18181b);\n}\n.c2-code-editor__surface .cm-line {\n  padding: 0 var(--c2-code-editor--padding-inline,12px);\n}\n.c2-code-editor__surface .cm-gutters {\n  min-width: var(--c2-code-editor__gutter--min-width,32px);\n  background: var(--c2-code-editor__gutter--background,transparent);\n  color: var(--c2-code-editor__gutter--color,#71717a);\n  border-right: var(--c2-code-editor__gutter--border-right,1px solid #e4e4e7);\n}\n.c2-code-editor__surface .cm-activeLineGutter {\n  background: transparent;\n  color: var(--c2-code-editor__gutter__active--color,#18181b);\n}\n.c2-code-editor__surface .cm-activeLine {\n  background: var(--c2-code-editor__active-line--background,rgba(2, 101, 220, 0.04));\n}\n.c2-code-editor__surface .cm-selectionBackground,\n.c2-code-editor__surface .cm-content ::selection,\n.c2-code-editor__surface .cm-editor.cm-focused .cm-selectionBackground {\n  background: var(--c2-code-editor__selection--background,rgba(2, 101, 220, 0.18));\n}\n.c2-code-editor__surface .cm-cursor,\n.c2-code-editor__surface .cm-dropCursor {\n  border-left-color: var(--c2-code-editor__cursor--color,#18181b);\n}\n.c2-code-editor__surface .cm-matchingBracket,\n.c2-code-editor__surface .cm-editor.cm-focused .cm-matchingBracket {\n  background: var(--c2-code-editor__matching-bracket--background,rgba(2, 101, 220, 0.16));\n  outline: none;\n}\n.c2-code-editor__surface .cm-nonmatchingBracket {\n  color: var(--c2-code-editor__error--color,#dc2626);\n}\n.c2-code-editor__surface .cm-placeholder {\n  color: var(--c2-code-editor__placeholder--color,#71717a);\n}\n.c2-code-editor__surface .cm-tooltip {\n  background: var(--c2-code-editor--background,#ffffff);\n  color: var(--c2-code-editor--color,#24292e);\n  border: var(--c2-code-editor--border,1px solid #bcbcc6);\n  border-radius: var(--c2-code-editor--border-radius,6px);\n}\n.c2-code-editor__surface .cm-tooltip-autocomplete ul li[aria-selected] {\n  background: var(--c2-code-editor__selection--background,rgba(2, 101, 220, 0.18));\n  color: var(--c2-code-editor--color,#24292e);\n}\n\n/**\n * The syntax palette. `engine.ts` maps Lezer tags to these classes instead of to inline styles, which is what keeps\n * the whole theme in CSS: dark mode is different variable values and no JavaScript. The names match\n * `--c2-code-viewer__theme--token-*` so one palette can drive the viewer and the editor.\n */\n.c2-code-editor__surface .c2tok-keyword {\n  color: var(--c2-code-editor__theme--token-keyword,#cf222e);\n}\n.c2-code-editor__surface .c2tok-string {\n  color: var(--c2-code-editor__theme--token-string,#032f62);\n}\n.c2-code-editor__surface .c2tok-comment {\n  color: var(--c2-code-editor__theme--token-comment,#636c76);\n  font-style: italic;\n}\n.c2-code-editor__surface .c2tok-constant {\n  color: var(--c2-code-editor__theme--token-constant,#0550ae);\n}\n.c2-code-editor__surface .c2tok-function {\n  color: var(--c2-code-editor__theme--token-function,#6f42c1);\n}\n.c2-code-editor__surface .c2tok-type {\n  color: var(--c2-code-editor__theme--token-type,#953800);\n}\n.c2-code-editor__surface .c2tok-property {\n  color: var(--c2-code-editor__theme--token-property,#0550ae);\n}\n.c2-code-editor__surface .c2tok-variable {\n  color: var(--c2-code-editor__theme--token-variable,#24292e);\n}\n.c2-code-editor__surface .c2tok-tag {\n  color: var(--c2-code-editor__theme--token-tag,#116329);\n}\n.c2-code-editor__surface .c2tok-punctuation {\n  color: var(--c2-code-editor__theme--token-punctuation,#24292e);\n}\n.c2-code-editor__surface .c2tok-link {\n  color: var(--c2-code-editor__theme--token-link,#032f62);\n  text-decoration: underline;\n}\n.c2-code-editor__surface .c2tok-invalid {\n  color: var(--c2-code-editor__theme--token-invalid,#cf222e);\n}\n.c2-code-editor__surface .c2tok-strong {\n  font-weight: 600;\n}\n.c2-code-editor__surface .c2tok-emphasis {\n  font-style: italic;\n}\n\n.c2-code-editor__supporting-text {\n  color: var(--c2-code-editor__supporting-text--color,#71717a);\n  font-size: var(--c2-code-editor__supporting-text--font-size,12px);\n}\n.c2-code-editor__supporting-text[hidden] {\n  display: none;\n}\n\n.c2-code-editor.is-invalid .c2-code-editor__supporting-text {\n  color: var(--c2-code-editor__error--color,#dc2626);\n}";
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/code-editor.ts
+var CodeEditor = class CodeEditor extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.internals = this.attachInternals();
+		this.value = "";
+		this.language = "";
+		this.languageLoader = void 0;
+		this.name = "";
+		this.label = "";
+		this.ariaLabel = null;
+		this.placeholder = "";
+		this.readOnly = false;
+		this.disabled = false;
+		this.required = false;
+		this.lineNumbers = false;
+		this.wrap = false;
+		this.autocomplete = false;
+		this.tabSize = 2;
+		this.error = false;
+		this.errorText = "";
+		this.help = "";
+		this.engineState = "pending";
+		this.focused = false;
+		this.customValidityMessage = "";
+		this.disabledByForm = false;
+		this.dirty = false;
+		this.hasLabelSlot = false;
+	}
+	static {
+		this.formAssociated = true;
+	}
+	static {
+		this.styles = unsafeCSS(code_editor_default);
+	}
+	/** Resolves once the engine has settled, so a host (or a test) can await the editor being live. */
+	get ready() {
+		return (this.mounting ?? Promise.resolve()).then(() => this.engineState);
+	}
+	/** The engine in use, or `undefined` while it is still loading. */
+	get engine() {
+		return this.engineState === "pending" ? void 0 : this.engineState === "ready" ? "codemirror" : "basic";
+	}
+	get form() {
+		return this.internals.form;
+	}
+	get labels() {
+		return this.internals.labels;
+	}
+	get validity() {
+		return this.internals.validity;
+	}
+	get validationMessage() {
+		return this.internals.validationMessage;
+	}
+	get willValidate() {
+		return this.internals.willValidate;
+	}
+	get effectiveDisabled() {
+		return this.disabled || this.disabledByForm;
+	}
+	/** What labels the editable element. CodeMirror's content node is the `textbox`, so the name has to land there. */
+	get accessibleName() {
+		return this.label || this.ariaLabel || "Code editor";
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.editor?.destroy();
+		this.editor = void 0;
+		if (this.engineState === "ready") this.engineState = "pending";
+	}
+	/** The `value` *attribute* is the default, exactly as `defaultValue` is on a native control. */
+	formResetCallback() {
+		this.value = this.getAttribute("value") ?? "";
+	}
+	formDisabledCallback(disabled) {
+		this.disabledByForm = disabled && !this.hasAttribute("disabled");
+	}
+	formStateRestoreCallback(state) {
+		if (typeof state === "string") this.value = state;
+	}
+	checkValidity() {
+		return this.internals.checkValidity();
+	}
+	reportValidity() {
+		return this.internals.reportValidity();
+	}
+	setCustomValidity(message) {
+		this.customValidityMessage = message;
+		this.requestUpdate();
+	}
+	focus(options) {
+		if (this.editor) this.editor.focus();
+		else this.fallback?.focus(options);
+	}
+	firstUpdated() {
+		if (isServer) return;
+		this.mounting = this.mount();
+	}
+	async mount() {
+		const editor = await createEditor({
+			parent: this.surface,
+			root: this.renderRoot,
+			value: this.value,
+			language: this.language,
+			languageLoader: this.languageLoader,
+			readOnly: this.readOnly,
+			editable: !this.effectiveDisabled,
+			lineNumbers: this.lineNumbers,
+			lineWrapping: this.wrap,
+			autocomplete: this.autocomplete,
+			tabSize: this.tabSize,
+			placeholder: this.placeholder,
+			label: this.accessibleName,
+			onInput: (value) => this.handleEditorInput(value),
+			onBlur: () => this.handleBlur(),
+			onFocus: () => this.focused = true
+		});
+		if (!this.isConnected) {
+			editor?.destroy();
+			return;
+		}
+		this.editor = editor;
+		this.engineState = editor ? "ready" : "basic";
+		this.dispatchEvent(new CustomEvent("ready", { detail: { engine: this.engineState === "ready" ? "codemirror" : "basic" } }));
+	}
+	updated(changed) {
+		const editor = this.editor;
+		if (editor) {
+			if (changed.has("value")) editor.setValue(this.value);
+			if (changed.has("language") || changed.has("languageLoader")) editor.setLanguage(this.language, this.languageLoader);
+			if (changed.has("readOnly") || changed.has("disabled") || changed.has("disabledByForm")) editor.setEditing(this.readOnly, !this.effectiveDisabled);
+			if (changed.has("lineNumbers")) editor.setLineNumbers(this.lineNumbers);
+			if (changed.has("wrap")) editor.setLineWrapping(this.wrap);
+			if (changed.has("autocomplete")) editor.setAutocomplete(this.autocomplete);
+			if (changed.has("tabSize")) editor.setTabSize(this.tabSize);
+			if (changed.has("placeholder")) editor.setPlaceholder(this.placeholder);
+			if (changed.has("label") || changed.has("ariaLabel")) editor.setLabel(this.accessibleName);
+		}
+		this.internals.setFormValue(this.value, this.value);
+		const missing = this.required && !this.value;
+		const flags = this.customValidityMessage ? { customError: true } : missing ? { valueMissing: true } : {};
+		const message = this.customValidityMessage || (missing ? "Please enter some code." : "");
+		this.internals.setValidity(flags, message, this.surface);
+	}
+	/**
+	* CodeMirror edits a `contenteditable`, whose native `input` / `beforeinput` are composed and would escape the
+	* shadow root — a consumer would see one of those *and* the component's own `input` for the same keystroke, and
+	* would see one even for an edit `readonly` rejected. The component owns its event surface, so they stop here.
+	*/
+	stopNativeEditing(event) {
+		event.stopPropagation();
+	}
+	handleEditorInput(value) {
+		if (value === this.value) return;
+		this.value = value;
+		this.dirty = true;
+		this.dispatchEvent(new Event("input", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	handleBlur() {
+		this.focused = false;
+		if (!this.dirty) return;
+		this.dirty = false;
+		this.dispatchEvent(new Event("change", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	/** The fallback textarea fires native `input` / `change`; only the value has to be mirrored. */
+	handleFallbackInput(event) {
+		this.value = event.target.value;
+		this.dispatchEvent(new Event("input", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	handleFallbackChange() {
+		this.dispatchEvent(new Event("change", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	renderFallback() {
+		return html`<textarea
+      class="c2-code-editor__fallback"
+      part="editor"
+      name=${ifDefined(this.name || void 0)}
+      aria-label=${this.accessibleName}
+      placeholder=${ifDefined(this.placeholder || void 0)}
+      spellcheck="false"
+      autocapitalize="off"
+      autocorrect="off"
+      ?disabled=${this.effectiveDisabled}
+      ?readonly=${this.readOnly}
+      .value=${live(this.value)}
+      @input=${this.handleFallbackInput}
+      @change=${this.handleFallbackChange}
+      @focus=${() => this.focused = true}
+      @blur=${() => this.focused = false}
+    ></textarea>`;
+	}
+	render() {
+		const invalid = this.error && !this.effectiveDisabled;
+		const showError = invalid && !!this.errorText;
+		const supporting = !!this.help || showError;
+		return html`
+      <div
+        class=${classMap({
+			"c2-code-editor": true,
+			"is-focused": this.focused,
+			"is-invalid": invalid,
+			"is-disabled": this.effectiveDisabled,
+			[`is-${this.engineState}`]: true
+		})}
+        part="container"
+      >
+        <label class="c2-code-editor__label" part="label" ?hidden=${!this.label && !this.hasLabelSlot}>
+          <slot name="label" @slotchange=${this.handleLabelSlotChange}>${this.label}</slot>
+        </label>
+        <!-- Always in the template, so switching engine state never recreates the node CodeMirror owns. -->
+        <div
+          class="c2-code-editor__surface"
+          part=${this.engineState === "ready" ? "editor" : nothing}
+          ?hidden=${this.engineState !== "ready"}
+          @beforeinput=${this.stopNativeEditing}
+          @input=${this.stopNativeEditing}
+        ></div>
+        ${this.engineState === "basic" ? this.renderFallback() : nothing}
+        ${this.engineState === "pending" ? html`<pre class="c2-code-editor__pending" aria-hidden="true">${this.value}</pre>` : nothing}
+        <div class="c2-code-editor__supporting-text" part="supporting-text" ?hidden=${!supporting}>
+          ${showError ? html`<span role="alert">${this.errorText}</span>` : html`<slot name="supporting-text">${this.help}</slot>`}
+        </div>
+      </div>
+    `;
+	}
+	handleLabelSlotChange(event) {
+		const slot = event.target;
+		this.hasLabelSlot = slot.assignedNodes({ flatten: true }).some((node) => node.nodeType === Node.ELEMENT_NODE || (node.textContent ?? "").trim() !== "");
+	}
+};
+__decorate([property()], CodeEditor.prototype, "value", void 0);
+__decorate([property({ reflect: true })], CodeEditor.prototype, "language", void 0);
+__decorate([property({ attribute: false })], CodeEditor.prototype, "languageLoader", void 0);
+__decorate([property()], CodeEditor.prototype, "name", void 0);
+__decorate([property()], CodeEditor.prototype, "label", void 0);
+__decorate([property({ attribute: "aria-label" })], CodeEditor.prototype, "ariaLabel", void 0);
+__decorate([property()], CodeEditor.prototype, "placeholder", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true,
+	attribute: "readonly"
+})], CodeEditor.prototype, "readOnly", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CodeEditor.prototype, "disabled", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CodeEditor.prototype, "required", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true,
+	attribute: "line-numbers"
+})], CodeEditor.prototype, "lineNumbers", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CodeEditor.prototype, "wrap", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CodeEditor.prototype, "autocomplete", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "tab-size"
+})], CodeEditor.prototype, "tabSize", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CodeEditor.prototype, "error", void 0);
+__decorate([property({ attribute: "error-text" })], CodeEditor.prototype, "errorText", void 0);
+__decorate([property()], CodeEditor.prototype, "help", void 0);
+__decorate([state()], CodeEditor.prototype, "engineState", void 0);
+__decorate([state()], CodeEditor.prototype, "focused", void 0);
+__decorate([query(".c2-code-editor__surface")], CodeEditor.prototype, "surface", void 0);
+__decorate([query("textarea")], CodeEditor.prototype, "fallback", void 0);
+__decorate([state()], CodeEditor.prototype, "disabledByForm", void 0);
+__decorate([state()], CodeEditor.prototype, "hasLabelSlot", void 0);
+CodeEditor = __decorate([customElement("c2-code-editor")], CodeEditor);
+//#endregion
+export { BUILT_IN_LANGUAGES, CodeEditor };

package/dist/engine.js

@@ -0,0 +1,296 @@
+//#region src/engine.ts
+/** Language ids with a built-in loader. Anything else needs `languageLoader`. */
+var BUILT_IN_LANGUAGES = [
+	"javascript",
+	"typescript",
+	"jsx",
+	"tsx",
+	"html",
+	"css",
+	"json"
+];
+async function importModules() {
+	const [state, view, commands, language, autocomplete, search, highlight] = await Promise.all([
+		import("@codemirror/state"),
+		import("@codemirror/view"),
+		import("@codemirror/commands"),
+		import("@codemirror/language"),
+		import("@codemirror/autocomplete"),
+		import("@codemirror/search"),
+		import("@lezer/highlight")
+	]);
+	return {
+		state,
+		view,
+		commands,
+		language,
+		autocomplete,
+		search,
+		highlight
+	};
+}
+var pending;
+/**
+* Loads CodeMirror once per page; ten editors mounting together share one request and one module evaluation.
+* Resolves to `undefined` when the peer is not installed, which is a supported state, not an error.
+*/
+function loadCodeMirror() {
+	return pending ??= importModules().catch(() => void 0);
+}
+/**
+* Token classes instead of inline colours, so the palette lives in `code-editor.scss` as
+* `--c2-code-editor__theme--token-*` — the same names `@c2n/code-viewer` uses for its `css-variables` theme, so the
+* two components can be given one palette.
+*/
+function buildHighlightStyle({ language, highlight }) {
+	const { tags } = highlight;
+	return language.HighlightStyle.define([
+		{
+			tag: [
+				tags.keyword,
+				tags.modifier,
+				tags.controlKeyword,
+				tags.operatorKeyword
+			],
+			class: "c2tok-keyword"
+		},
+		{
+			tag: [
+				tags.string,
+				tags.special(tags.string),
+				tags.regexp
+			],
+			class: "c2tok-string"
+		},
+		{
+			tag: [
+				tags.comment,
+				tags.lineComment,
+				tags.blockComment,
+				tags.docComment
+			],
+			class: "c2tok-comment"
+		},
+		{
+			tag: [
+				tags.number,
+				tags.bool,
+				tags.null,
+				tags.atom,
+				tags.constant(tags.name)
+			],
+			class: "c2tok-constant"
+		},
+		{
+			tag: [
+				tags.function(tags.variableName),
+				tags.function(tags.propertyName),
+				tags.macroName
+			],
+			class: "c2tok-function"
+		},
+		{
+			tag: [
+				tags.typeName,
+				tags.className,
+				tags.namespace,
+				tags.standard(tags.typeName)
+			],
+			class: "c2tok-type"
+		},
+		{
+			tag: [tags.propertyName, tags.attributeName],
+			class: "c2tok-property"
+		},
+		{
+			tag: [
+				tags.variableName,
+				tags.definition(tags.variableName),
+				tags.local(tags.variableName)
+			],
+			class: "c2tok-variable"
+		},
+		{
+			tag: [tags.tagName, tags.angleBracket],
+			class: "c2tok-tag"
+		},
+		{
+			tag: [
+				tags.operator,
+				tags.punctuation,
+				tags.separator,
+				tags.bracket,
+				tags.derefOperator
+			],
+			class: "c2tok-punctuation"
+		},
+		{
+			tag: [tags.link, tags.url],
+			class: "c2tok-link"
+		},
+		{
+			tag: tags.invalid,
+			class: "c2tok-invalid"
+		},
+		{
+			tag: [tags.heading, tags.strong],
+			class: "c2tok-strong"
+		},
+		{
+			tag: tags.emphasis,
+			class: "c2tok-emphasis"
+		}
+	]);
+}
+/** The built-in language loaders. Each grammar is its own dynamic import, so only what is used is fetched. */
+async function loadBuiltInLanguage(id) {
+	switch (id) {
+		case "javascript": return import("@codemirror/lang-javascript").then((module) => module.javascript());
+		case "jsx": return import("@codemirror/lang-javascript").then((module) => module.javascript({ jsx: true }));
+		case "typescript": return import("@codemirror/lang-javascript").then((module) => module.javascript({ typescript: true }));
+		case "tsx": return import("@codemirror/lang-javascript").then((module) => module.javascript({
+			typescript: true,
+			jsx: true
+		}));
+		case "html": return import("@codemirror/lang-html").then((module) => module.html());
+		case "css": return import("@codemirror/lang-css").then((module) => module.css());
+		case "json": return import("@codemirror/lang-json").then((module) => module.json());
+		default: return;
+	}
+}
+async function resolveLanguage(id, loader) {
+	const normalized = id.trim().toLowerCase();
+	if (!normalized || normalized === "plaintext" || normalized === "text") return void 0;
+	if (loader) {
+		const custom = await loader(normalized);
+		if (custom) return custom;
+	}
+	return loadBuiltInLanguage(normalized).catch(() => void 0);
+}
+/**
+* Mounts an editor, or resolves to `undefined` when CodeMirror is not installed. Each reconfigurable concern gets its
+* own `Compartment`, so toggling line numbers or swapping the language never rebuilds the document or loses history.
+*/
+async function createEditor(options) {
+	const modules = await loadCodeMirror();
+	if (!modules) return void 0;
+	const { state, view: viewModule, commands, language, autocomplete, search } = modules;
+	const { Compartment, EditorState } = state;
+	const { EditorView, keymap, lineNumbers, highlightActiveLine, highlightActiveLineGutter, drawSelection, rectangularSelection, placeholder } = viewModule;
+	let contentState = {
+		label: options.label,
+		readOnly: options.readOnly,
+		editable: options.editable
+	};
+	const contentAttributes = () => ({
+		"aria-label": contentState.label,
+		"aria-readonly": contentState.readOnly ? "true" : "false",
+		...contentState.editable ? {} : { "aria-disabled": "true" },
+		spellcheck: "false",
+		autocapitalize: "off",
+		autocorrect: "off"
+	});
+	const compartments = {
+		language: new Compartment(),
+		readOnly: new Compartment(),
+		editable: new Compartment(),
+		lineNumbers: new Compartment(),
+		lineWrapping: new Compartment(),
+		autocomplete: new Compartment(),
+		tabSize: new Compartment(),
+		placeholder: new Compartment(),
+		label: new Compartment()
+	};
+	let applying = false;
+	const view = new EditorView({
+		parent: options.parent,
+		root: options.root,
+		state: EditorState.create({
+			doc: options.value,
+			extensions: [
+				lineNumbers && compartments.lineNumbers.of(options.lineNumbers ? lineNumbers() : []),
+				highlightActiveLine(),
+				highlightActiveLineGutter(),
+				drawSelection(),
+				rectangularSelection(),
+				commands.history(),
+				language.bracketMatching(),
+				language.indentOnInput(),
+				language.foldGutter(),
+				autocomplete.closeBrackets(),
+				language.syntaxHighlighting(buildHighlightStyle(modules), { fallback: true }),
+				keymap.of([
+					...commands.defaultKeymap,
+					...commands.historyKeymap,
+					...search.searchKeymap,
+					...autocomplete.completionKeymap,
+					commands.indentWithTab
+				]),
+				compartments.language.of([]),
+				compartments.autocomplete.of(options.autocomplete ? autocomplete.autocompletion() : []),
+				compartments.lineWrapping.of(options.lineWrapping ? EditorView.lineWrapping : []),
+				compartments.tabSize.of(EditorState.tabSize.of(options.tabSize)),
+				compartments.readOnly.of(EditorState.readOnly.of(options.readOnly)),
+				compartments.editable.of(EditorView.editable.of(options.editable)),
+				compartments.placeholder.of(options.placeholder ? placeholder(options.placeholder) : []),
+				compartments.label.of(EditorView.contentAttributes.of(contentAttributes())),
+				EditorView.updateListener.of((update) => {
+					if (update.docChanged && !applying) options.onInput(update.state.doc.toString());
+					if (update.focusChanged) (update.view.hasFocus ? options.onFocus : options.onBlur)();
+				})
+			].filter(Boolean)
+		})
+	});
+	const reconfigure = (compartment, extension) => {
+		view.dispatch({ effects: compartment.reconfigure(extension) });
+	};
+	const handle = {
+		view,
+		getValue: () => view.state.doc.toString(),
+		setValue(value) {
+			if (value === view.state.doc.toString()) return;
+			applying = true;
+			try {
+				view.dispatch({ changes: {
+					from: 0,
+					to: view.state.doc.length,
+					insert: value
+				} });
+			} finally {
+				applying = false;
+			}
+		},
+		async setLanguage(id, loader) {
+			const extension = await resolveLanguage(id, loader);
+			reconfigure(compartments.language, extension ?? []);
+		},
+		setEditing(readOnly, editable) {
+			contentState = {
+				...contentState,
+				readOnly,
+				editable
+			};
+			reconfigure(compartments.readOnly, EditorState.readOnly.of(readOnly));
+			reconfigure(compartments.editable, EditorView.editable.of(editable));
+			reconfigure(compartments.label, EditorView.contentAttributes.of(contentAttributes()));
+		},
+		setLineNumbers: (on) => reconfigure(compartments.lineNumbers, on ? lineNumbers() : []),
+		setLineWrapping: (on) => reconfigure(compartments.lineWrapping, on ? EditorView.lineWrapping : []),
+		setAutocomplete: (on) => reconfigure(compartments.autocomplete, on ? autocomplete.autocompletion() : []),
+		setTabSize: (size) => reconfigure(compartments.tabSize, EditorState.tabSize.of(size)),
+		setPlaceholder: (text) => reconfigure(compartments.placeholder, text ? placeholder(text) : []),
+		setLabel(label) {
+			contentState = {
+				...contentState,
+				label
+			};
+			reconfigure(compartments.label, EditorView.contentAttributes.of(contentAttributes()));
+		},
+		focus: () => view.focus(),
+		destroy: () => view.destroy()
+	};
+	await handle.setLanguage(options.language, options.languageLoader);
+	return handle;
+}
+//#endregion
+export { BUILT_IN_LANGUAGES, createEditor, loadCodeMirror };

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@c2n/code-editor",
+  "version": "0.0.10",
+  "type": "module",
+  "main": "dist/code-editor.js",
+  "exports": {
+    ".": {
+      "types": "./types/src/code-editor.d.ts",
+      "default": "./dist/code-editor.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./vue": {
+      "types": "./vue.d.ts",
+      "default": "./vue.js"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "files": [
+    "dist",
+    "types",
+    "react.d.ts",
+    "react.js",
+    "vue.d.ts",
+    "vue.js"
+  ],
+  "keywords": [
+    "code-editor",
+    "codemirror",
+    "web component",
+    "lit"
+  ],
+  "license": "MIT",
+  "author": "code2nguyen@gmail.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code2nguyen/web-components.git"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "wireit",
+    "build:only": "vite build",
+    "type-check": "wireit"
+  },
+  "wireit": {
+    "type-check": {
+      "dependencies": [
+        "../../core:build"
+      ],
+      "command": "tsc -p tsconfig.lib.json --composite false"
+    },
+    "build": {
+      "dependencies": [
+        "type-check"
+      ],
+      "command": "vite build"
+    }
+  },
+  "dependencies": {
+    "@c2n/core": "0.0.10",
+    "lit": "3.3.3"
+  },
+  "devDependencies": {
+    "@c2n/config": "*",
+    "@codemirror/autocomplete": "^6.0.0",
+    "@codemirror/commands": "^6.0.0",
+    "@codemirror/lang-css": "^6.0.0",
+    "@codemirror/lang-html": "^6.0.0",
+    "@codemirror/lang-javascript": "^6.0.0",
+    "@codemirror/lang-json": "^6.0.0",
+    "@codemirror/language": "^6.0.0",
+    "@codemirror/search": "^6.0.0",
+    "@codemirror/state": "^6.0.0",
+    "@codemirror/view": "^6.0.0",
+    "@lezer/highlight": "^1.0.0"
+  },
+  "customElements": "custom-elements.json",
+  "peerDependencies": {
+    "@codemirror/autocomplete": "^6.0.0",
+    "@codemirror/commands": "^6.0.0",
+    "@codemirror/lang-css": "^6.0.0",
+    "@codemirror/lang-html": "^6.0.0",
+    "@codemirror/lang-javascript": "^6.0.0",
+    "@codemirror/lang-json": "^6.0.0",
+    "@codemirror/language": "^6.0.0",
+    "@codemirror/search": "^6.0.0",
+    "@codemirror/state": "^6.0.0",
+    "@codemirror/view": "^6.0.0",
+    "@lezer/highlight": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@codemirror/autocomplete": {
+      "optional": true
+    },
+    "@codemirror/commands": {
+      "optional": true
+    },
+    "@codemirror/lang-css": {
+      "optional": true
+    },
+    "@codemirror/lang-html": {
+      "optional": true
+    },
+    "@codemirror/lang-javascript": {
+      "optional": true
+    },
+    "@codemirror/lang-json": {
+      "optional": true
+    },
+    "@codemirror/language": {
+      "optional": true
+    },
+    "@codemirror/search": {
+      "optional": true
+    },
+    "@codemirror/state": {
+      "optional": true
+    },
+    "@codemirror/view": {
+      "optional": true
+    },
+    "@lezer/highlight": {
+      "optional": true
+    }
+  },
+  "gitHead": "8d57710b3345fcb01cdb4cb15d2d43ba8bf21642"
+}

package/react.d.ts

@@ -0,0 +1,24 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// JSX types for the custom elements of @c2n/code-editor. Import once, anywhere in the program:
+//
+//     import '@c2n/code-editor/react'
+//
+// Register the elements at module scope before React renders, or React writes an object prop as an
+// attribute and it stringifies.
+
+import type { DetailedHTMLProps, HTMLAttributes } from 'react'
+import type { CodeEditor } from '@c2n/code-editor'
+
+/** Standard React host-element attributes plus the element's own public properties. */
+type C2Props<T> = DetailedHTMLProps<HTMLAttributes<T>, T> & Partial<Omit<T, keyof HTMLElement>>
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'c2-code-editor': C2Props<CodeEditor>
+    }
+  }
+}
+
+export {}

package/react.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}

package/types/src/code-editor.d.ts

@@ -0,0 +1,204 @@
+import { LitElement, type PropertyValues } from 'lit';
+import type { TypedAddEventListener, TypedRemoveEventListener } from '@c2n/core/event-helper.js';
+import { type LanguageLoader } from './engine.js';
+export { BUILT_IN_LANGUAGES } from './engine.js';
+export type { BuiltInLanguage, LanguageLoader } from './engine.js';
+/** How far the engine got. `basic` is the textarea fallback: CodeMirror is not installed. */
+export type CodeEditorEngineState = 'pending' | 'ready' | 'basic';
+/** Events fired by {@link CodeEditor}, keyed for `addEventListener`. */
+export interface CodeEditorEventMap {
+    input: Event;
+    change: Event;
+    /** The engine settled. `detail.engine` is `codemirror` or `basic`. */
+    ready: CustomEvent<{
+        engine: 'codemirror' | 'basic';
+    }>;
+}
+export interface CodeEditor {
+    addEventListener: TypedAddEventListener<CodeEditor, CodeEditorEventMap>;
+    removeEventListener: TypedRemoveEventListener<CodeEditor, CodeEditorEventMap>;
+}
+/**
+ * Source-code field built on CodeMirror 6, which is an **optional peer dependency**: nothing is imported until an
+ * editor mounts, and when the peer is absent the element degrades to a plain `<textarea>` carrying the same value,
+ * the same events and the same form behaviour — only without highlighting. Install what you need alongside it:
+ *
+ * ```sh
+ * npm install @codemirror/state @codemirror/view @codemirror/commands @codemirror/language \
+ *   @codemirror/autocomplete @codemirror/search @lezer/highlight @codemirror/lang-javascript
+ * ```
+ *
+ * It is form-associated: `name` and `value` take part in a `<form>`, it restores on reset, and it fires the plain
+ * `input` and `change` a `v-model`, a `ControlValueAccessor` or any generic two-way binding listens for.
+ *
+ * Colours are **not** a CodeMirror theme. The editor renders real DOM inside the shadow root, so every surface,
+ * gutter and token colour is an ordinary `--c2-code-editor__*` custom property — including the syntax palette, whose
+ * `--c2-code-editor__theme--token-*` names match `@c2n/code-viewer`'s `css-variables` theme so one palette can drive
+ * both. Dark mode is therefore just different variable values, with no JavaScript involved.
+ *
+ * Grammars for `javascript`, `typescript`, `jsx`, `tsx`, `html`, `css` and `json` are built in and loaded on demand.
+ * Any other language comes from `languageLoader`, so adding Python or SQL costs this package no dependency.
+ *
+ * @tag c2-code-editor
+ *
+ * @slot label - Label shown above the editor. Falls back to the `label` attribute.
+ * @slot supporting-text - Help text under the editor. Replaced by `error-text` while `error` is set.
+ *
+ * @event {Event} input - The document changed. Fires on every edit.
+ * @event {Event} change - The value was committed: the editor lost focus after an edit, as a native control does.
+ * @event {CustomEvent<{ engine: 'codemirror' | 'basic' }>} ready - The engine settled, so tests and hosts can wait for it. Does not bubble.
+ *
+ * @csspart container - The box around the label, editor and supporting text.
+ * @csspart label - The label above the editor.
+ * @csspart editor - The element CodeMirror renders into, or the fallback textarea.
+ * @csspart supporting-text - The help / error row under the editor.
+ *
+ * @cssproperty {color} [--c2-code-editor--background=#ffffff]
+ * @cssproperty {color} [--c2-code-editor--color=#24292e] - Foreground of text no token class matched.
+ * @cssproperty {border} [--c2-code-editor--border=1px solid #bcbcc6]
+ * @cssproperty {border} [--c2-code-editor__focus--border=1px solid rgb(2, 101, 220)]
+ * @cssproperty {outline} [--c2-code-editor__focus--outline=2px solid rgba(2, 101, 220, 0.4)]
+ * @cssproperty {border-radius} [--c2-code-editor--border-radius=6px]
+ * @cssproperty {box-shadow} --c2-code-editor--box-shadow
+ * @cssproperty {opacity} [--c2-code-editor__disabled--opacity=0.38]
+ *
+ * @cssproperty {font-family} [--c2-code-editor--font-family=ui-monospace, SFMono-Regular, Menlo, Consolas, monospace]
+ * @cssproperty {font-size} [--c2-code-editor--font-size=13px]
+ * @cssproperty {line-height} [--c2-code-editor--line-height=1.6]
+ * @cssproperty {pixel} [--c2-code-editor--min-height=120px]
+ * @cssproperty {pixel} [--c2-code-editor--max-height=420px] - The editor scrolls past this height.
+ * @cssproperty {padding} [--c2-code-editor--padding-block=10px]
+ * @cssproperty {padding} [--c2-code-editor--padding-inline=12px]
+ *
+ * @cssproperty {color} [--c2-code-editor__gutter--background=transparent]
+ * @cssproperty {color} [--c2-code-editor__gutter--color=#71717a]
+ * @cssproperty {color} [--c2-code-editor__gutter__active--color=#18181b]
+ * @cssproperty {border} [--c2-code-editor__gutter--border-right=1px solid #e4e4e7]
+ * @cssproperty {pixel} [--c2-code-editor__gutter--min-width=32px]
+ *
+ * @cssproperty {color} [--c2-code-editor__active-line--background=rgba(2, 101, 220, 0.04)]
+ * @cssproperty {color} [--c2-code-editor__selection--background=rgba(2, 101, 220, 0.18)]
+ * @cssproperty {color} [--c2-code-editor__cursor--color=#18181b]
+ * @cssproperty {color} [--c2-code-editor__matching-bracket--background=rgba(2, 101, 220, 0.16)]
+ * @cssproperty {color} [--c2-code-editor__placeholder--color=#71717a]
+ *
+ * @cssproperty {color} [--c2-code-editor__theme--token-keyword=#cf222e]
+ * @cssproperty {color} [--c2-code-editor__theme--token-string=#032f62]
+ * @cssproperty {color} [--c2-code-editor__theme--token-comment=#636c76]
+ * @cssproperty {color} [--c2-code-editor__theme--token-constant=#0550ae]
+ * @cssproperty {color} [--c2-code-editor__theme--token-function=#6f42c1]
+ * @cssproperty {color} [--c2-code-editor__theme--token-type=#953800]
+ * @cssproperty {color} [--c2-code-editor__theme--token-property=#0550ae]
+ * @cssproperty {color} [--c2-code-editor__theme--token-variable=#24292e]
+ * @cssproperty {color} [--c2-code-editor__theme--token-tag=#116329]
+ * @cssproperty {color} [--c2-code-editor__theme--token-punctuation=#24292e]
+ * @cssproperty {color} [--c2-code-editor__theme--token-link=#032f62]
+ * @cssproperty {color} [--c2-code-editor__theme--token-invalid=#cf222e]
+ *
+ * @cssproperty {color} [--c2-code-editor__label--color=#18181b]
+ * @cssproperty {font-size} [--c2-code-editor__label--font-size=12px]
+ * @cssproperty {font-weight} [--c2-code-editor__label--font-weight=500]
+ * @cssproperty {color} [--c2-code-editor__supporting-text--color=#71717a]
+ * @cssproperty {font-size} [--c2-code-editor__supporting-text--font-size=12px]
+ * @cssproperty {color} [--c2-code-editor__error--color=#dc2626]
+ * @cssproperty {border} [--c2-code-editor__error--border=1px solid #dc2626]
+ * @cssproperty {pixel} [--c2-code-editor--gap=6px] - Space between the label, the editor and the supporting text.
+ */
+export declare class CodeEditor extends LitElement {
+    static formAssociated: boolean;
+    static styles: import("lit").CSSResult;
+    private readonly internals;
+    /** The source code. Assigning it replaces the document without losing scroll position or undo history. */
+    value: string;
+    /** Language id: one of `BUILT_IN_LANGUAGES`, anything `languageLoader` resolves, or empty for no highlighting. */
+    language: string;
+    /**
+     * Resolves a language id this package has no grammar for, to a CodeMirror `Extension`. Property only — it takes a
+     * function, so there is no attribute for it.
+     */
+    languageLoader: LanguageLoader | undefined;
+    /** Form field name. */
+    name: string;
+    /** Label above the editor, when the `label` slot is empty. */
+    label: string;
+    /** Accessible name when nothing visible labels the editor. */
+    ariaLabel: string | null;
+    /** Text shown while the document is empty. */
+    placeholder: string;
+    /** The document cannot be edited, but is still selectable and focusable. */
+    readOnly: boolean;
+    /** Blocks interaction entirely and dims the editor. */
+    disabled: boolean;
+    /** The form is invalid while the value is empty. */
+    required: boolean;
+    /** Show the line-number gutter. */
+    lineNumbers: boolean;
+    /** Wrap long lines instead of scrolling horizontally. */
+    wrap: boolean;
+    /** Offer completions while typing (identifiers, and whatever the grammar contributes). */
+    autocomplete: boolean;
+    /** Width of a tab stop, in characters. */
+    tabSize: number;
+    /** Renders the error styling; `error-text` replaces the supporting text. */
+    error: boolean;
+    /** Message shown in place of the supporting text while `error` is set. */
+    errorText: string;
+    /** Help text under the editor, when the `supporting-text` slot is empty. */
+    help: string;
+    /** How far the engine got: `pending`, `ready` (CodeMirror mounted) or `basic` (textarea fallback). */
+    private engineState;
+    private focused;
+    private surface;
+    private fallback?;
+    private editor;
+    private mounting;
+    private customValidityMessage;
+    private disabledByForm;
+    /** Set by an edit, cleared by the `change` that follows the blur — the native commit-on-blur contract. */
+    private dirty;
+    /** Resolves once the engine has settled, so a host (or a test) can await the editor being live. */
+    get ready(): Promise<CodeEditorEngineState>;
+    /** The engine in use, or `undefined` while it is still loading. */
+    get engine(): 'codemirror' | 'basic' | undefined;
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    private get effectiveDisabled();
+    /** What labels the editable element. CodeMirror's content node is the `textbox`, so the name has to land there. */
+    private get accessibleName();
+    disconnectedCallback(): void;
+    /** The `value` *attribute* is the default, exactly as `defaultValue` is on a native control. */
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(message: string): void;
+    focus(options?: FocusOptions): void;
+    protected firstUpdated(): void;
+    private mount;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * CodeMirror edits a `contenteditable`, whose native `input` / `beforeinput` are composed and would escape the
+     * shadow root — a consumer would see one of those *and* the component's own `input` for the same keystroke, and
+     * would see one even for an edit `readonly` rejected. The component owns its event surface, so they stop here.
+     */
+    private stopNativeEditing;
+    private handleEditorInput;
+    private handleBlur;
+    /** The fallback textarea fires native `input` / `change`; only the value has to be mirrored. */
+    private handleFallbackInput;
+    private handleFallbackChange;
+    private renderFallback;
+    render(): import("lit-html").TemplateResult<1>;
+    private hasLabelSlot;
+    private handleLabelSlotChange;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-code-editor': CodeEditor;
+    }
+}
+//# sourceMappingURL=code-editor.d.ts.map

package/types/src/code-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-editor.d.ts","sourceRoot":"","sources":["../../src/code-editor.ts"],"names":[],"mappings":"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"}

package/types/src/engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Lazy access to CodeMirror 6.
+ *
+ * Nothing here is imported by the element file at module scope: `c2-code-editor` pulls in no engine until an
+ * instance actually mounts, so importing the package costs nothing, the module is safe to evaluate during SSR, and
+ * the whole of CodeMirror stays an *optional* peer dependency — the element degrades to a plain textarea when it is
+ * not installed, the same contract `@c2n/chart` has with uPlot and ECharts.
+ *
+ * Every visible colour comes from the component's CSS custom properties, not from a CodeMirror theme: the editor
+ * renders real DOM inside the shadow root, so `code-editor.scss` can style `.cm-*` directly, and the syntax
+ * highlighter maps Lezer tags to `c2tok-*` classes rather than to inline styles.
+ */
+import type { Extension } from '@codemirror/state';
+import type { EditorView } from '@codemirror/view';
+/** Language ids with a built-in loader. Anything else needs `languageLoader`. */
+export declare const BUILT_IN_LANGUAGES: readonly ["javascript", "typescript", "jsx", "tsx", "html", "css", "json"];
+export type BuiltInLanguage = (typeof BUILT_IN_LANGUAGES)[number];
+/** Resolves a language id to CodeMirror extensions. Return nothing for "no highlighting". */
+export type LanguageLoader = (id: string) => Promise<Extension | undefined> | Extension | undefined;
+export interface EditorOptions {
+    parent: HTMLElement;
+    /** The shadow root the editor lives in. CodeMirror needs it for selection and focus tracking. */
+    root: ShadowRoot | Document;
+    value: string;
+    language: string;
+    languageLoader?: LanguageLoader;
+    readOnly: boolean;
+    editable: boolean;
+    lineNumbers: boolean;
+    lineWrapping: boolean;
+    autocomplete: boolean;
+    tabSize: number;
+    placeholder: string;
+    /** Accessible name put on the editable element itself, which is what carries `role=textbox`. */
+    label: string;
+    onInput: (value: string) => void;
+    onBlur: () => void;
+    onFocus: () => void;
+}
+/** What the element drives. Every setter is a live reconfiguration, never a teardown. */
+export interface EditorHandle {
+    readonly view: EditorView;
+    getValue(): string;
+    setValue(value: string): void;
+    setLanguage(language: string, loader?: LanguageLoader): Promise<void>;
+    setEditing(readOnly: boolean, editable: boolean): void;
+    setLineNumbers(on: boolean): void;
+    setLineWrapping(on: boolean): void;
+    setAutocomplete(on: boolean): void;
+    setTabSize(size: number): void;
+    setPlaceholder(text: string): void;
+    setLabel(label: string): void;
+    focus(): void;
+    destroy(): void;
+}
+/** Thrown by nothing: a missing peer resolves to `undefined` so the element can fall back instead of failing. */
+type Modules = Awaited<ReturnType<typeof importModules>>;
+declare function importModules(): Promise<{
+    state: typeof import("@codemirror/state");
+    view: typeof import("@codemirror/view");
+    commands: typeof import("@codemirror/commands");
+    language: typeof import("@codemirror/language");
+    autocomplete: typeof import("@codemirror/autocomplete");
+    search: typeof import("@codemirror/search");
+    highlight: typeof import("@lezer/highlight");
+}>;
+/**
+ * Loads CodeMirror once per page; ten editors mounting together share one request and one module evaluation.
+ * Resolves to `undefined` when the peer is not installed, which is a supported state, not an error.
+ */
+export declare function loadCodeMirror(): Promise<Modules | undefined>;
+/**
+ * Mounts an editor, or resolves to `undefined` when CodeMirror is not installed. Each reconfigurable concern gets its
+ * own `Compartment`, so toggling line numbers or swapping the language never rebuilds the document or loses history.
+ */
+export declare function createEditor(options: EditorOptions): Promise<EditorHandle | undefined>;
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/types/src/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,4EAA6E,CAAA;AAE5G,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,SAAS,GAAG,SAAS,CAAA;AAEnG,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,CAAA;IACnB,iGAAiG;IACjG,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,OAAO,CAAA;IACpB,YAAY,EAAE,OAAO,CAAA;IACrB,YAAY,EAAE,OAAO,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,IAAI,MAAM,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrE,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IACtD,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IACjC,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAClC,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAClC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,IAAI,IAAI,CAAA;IACb,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,iHAAiH;AACjH,KAAK,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAA;AAExD,iBAAe,aAAa;;;;;;;;GAW3B;AAID;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAE7D;AA4DD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAiH5F"}

package/vue.d.ts

@@ -0,0 +1,40 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+//
+// Vue template types for the custom elements of @c2n/code-editor. Import once, anywhere in the program:
+//
+//     import '@c2n/code-editor/vue'
+//
+// Tell the compiler about the tags as well, or every c2-* tag is resolved as a Vue component and renders
+// nothing: template.compilerOptions.isCustomElement = (tag) => tag.startsWith('c2-') in vite.config.ts.
+
+import type { DefineComponent, HTMLAttributes } from 'vue'
+import type { CodeEditor, CodeEditorEventMap } from '@c2n/code-editor'
+
+/** The element's own public properties, plus every attribute Vue understands on a host element. */
+type C2Props<T> = Partial<Omit<T, keyof HTMLElement>> & HTMLAttributes
+
+declare module 'vue' {
+  interface GlobalComponents {
+    'c2-code-editor': DefineComponent<
+      C2Props<CodeEditor> & {
+        'aria-label'?: unknown
+        readonly?: unknown
+        'line-numbers'?: unknown
+        'tab-size'?: unknown
+        'error-text'?: unknown
+        onReady?: (event: CodeEditorEventMap['ready']) => void
+        onInput?: (event: CodeEditorEventMap['input']) => void
+        onChange?: (event: CodeEditorEventMap['change']) => void
+      }
+    >
+  }
+}
+
+declare module '@vue/runtime-dom' {
+  interface HTMLAttributes {
+    /** Vue's own definition omits it, and slotting a plain element into a component needs it. */
+    slot?: string
+  }
+}
+
+export {}

package/vue.js

@@ -0,0 +1,3 @@
+// GENERATED by @c2n/framework-types. Do not edit by hand.
+// Types only — see the matching .d.ts.
+export {}