@adia-ai/web-components 0.0.12 → 0.0.14

package/components/code/code-editor.js

@@ -0,0 +1,161 @@
+/**
+ * code-editor — CodeMirror 6 runtime bundled for <code-ui>.
+ *
+ * Single file for the whole integration: CM core re-exports, the AdiaUI
+ * base theme + highlight style, the per-language lazy-load map, and the
+ * load-timeout helper. `code.js` does `import('./code-editor.js')` once
+ * per element mount.
+ *
+ * Styling contract: `EditorView.theme()` can't emit CSS custom properties
+ * (per CodeMirror docs), so the base theme below is structural-only.
+ * Every color, padding, border, and syntax-token style lives in
+ * `code.css` under `@scope (code-ui)`. See SPEC-CODE-EDITOR-001 §6.
+ *
+ * In Vite dev, the bare-specifier imports resolve through node_modules.
+ * In production, `scripts/build-site.mjs` runs esbuild with
+ * `splitting: true` on this file; each `languages[…]()` dynamic import
+ * becomes its own chunk, lazy-loaded on first use.
+ */
+
+import {
+  EditorState, EditorSelection, Compartment, StateEffect,
+} from '@codemirror/state';
+import {
+  EditorView,
+  lineNumbers, highlightActiveLine, highlightActiveLineGutter,
+  placeholder, drawSelection, keymap,
+} from '@codemirror/view';
+import {
+  defaultKeymap, history, historyKeymap, indentWithTab,
+} from '@codemirror/commands';
+import {
+  HighlightStyle, syntaxHighlighting, LanguageSupport, defaultHighlightStyle,
+} from '@codemirror/language';
+import { linter, lintGutter } from '@codemirror/lint';
+import { tags as t } from '@lezer/highlight';
+
+// ── Base theme (structural only — colors live in code.css) ───────────
+
+export const adiaBaseTheme = EditorView.theme({
+  '&':           { fontFamily: 'inherit', fontSize: 'inherit', color: 'inherit', backgroundColor: 'transparent' },
+  '.cm-content': { padding: '0', caretColor: 'inherit' },
+  '.cm-focused': { outline: 'none' },
+});
+
+// ── Syntax highlight (class-based so CSS owns the colors) ────────────
+
+export const adiaHighlightStyle = HighlightStyle.define([
+  { tag: [t.comment, t.lineComment, t.blockComment, t.docComment],                 class: 'tok-comment' },
+  { tag: [t.keyword, t.controlKeyword, t.modifier, t.operatorKeyword],             class: 'tok-keyword' },
+  { tag: [t.string, t.character, t.regexp, t.escape, t.special(t.string)],         class: 'tok-string' },
+  { tag: [t.number, t.integer, t.float],                                           class: 'tok-number' },
+  { tag: [t.bool, t.null, t.atom],                                                 class: 'tok-boolean' },
+  { tag: [t.operator, t.logicOperator, t.arithmeticOperator, t.compareOperator,
+          t.updateOperator, t.definitionOperator],                                 class: 'tok-operator' },
+  { tag: [t.punctuation, t.bracket, t.paren, t.brace, t.squareBracket,
+          t.angleBracket, t.separator],                                            class: 'tok-punctuation' },
+  { tag: [t.function(t.variableName), t.function(t.propertyName), t.macroName],    class: 'tok-function' },
+  { tag: [t.variableName, t.local(t.variableName), t.self],                        class: 'tok-variable' },
+  { tag: [t.typeName, t.className, t.namespace],                                   class: 'tok-type' },
+  { tag: [t.propertyName, t.labelName, t.definition(t.variableName)],              class: 'tok-property' },
+  { tag: [t.tagName, t.heading, t.contentSeparator],                               class: 'tok-tag' },
+  { tag: [t.attributeName, t.attributeValue],                                      class: 'tok-attribute' },
+  { tag: [t.url, t.link],                                                          class: 'tok-url' },
+  { tag: [t.invalid, t.deleted],                                                   class: 'tok-invalid' },
+]);
+
+// ── Per-language lazy loaders ────────────────────────────────────────
+
+export const languages = {
+  json:       () => import('@codemirror/lang-json').then((m) => ({ extension: m.json() })),
+  html:       () => import('@codemirror/lang-html').then((m) => ({ extension: m.html() })),
+  javascript: () => import('@codemirror/lang-javascript').then((m) => ({ extension: m.javascript({ jsx: false, typescript: false }) })),
+  css:        () => import('@codemirror/lang-css').then((m) => ({ extension: m.css() })),
+  markdown:   () => import('@codemirror/lang-markdown').then((m) => ({ extension: m.markdown() })),
+  yaml:       () => import('@codemirror/lang-yaml').then((m) => ({ extension: m.yaml() })),
+};
+
+// ── Load helper ──────────────────────────────────────────────────────
+
+/** 10s ceiling on any single dynamic import. Per SPEC-CODE-EDITOR-001 §7.4. */
+export const LOAD_TIMEOUT_MS = 10_000;
+
+export function importWithTimeout(loader, label) {
+  return Promise.race([
+    loader(),
+    new Promise((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`code-editor: ${label} load timed out after ${LOAD_TIMEOUT_MS}ms`)),
+        LOAD_TIMEOUT_MS,
+      ),
+    ),
+  ]);
+}
+
+// ── Language-specific linters ────────────────────────────────────────
+//
+// Kept here (not in code.js) so code.js doesn't depend on the lint
+// primitives directly. `code.js` picks the right linter by language
+// name when editable mode is on. Phase 3 of SPEC-CODE-EDITOR-001 —
+// JSON only for now; extend per-language as need arises.
+
+/** JSON linter. Parses the full document; emits one error Diagnostic
+ *  at the reported position on `SyntaxError`, else clean. The error
+ *  position is parsed from the engine's message (V8 / Node ≥20 /
+ *  Firefox / JavaScriptCore all shape these slightly differently) and
+ *  falls back to the last character so a marker is always visible. */
+export const jsonLinter = linter((view) => {
+  const text = view.state.doc.toString();
+  if (text.trim() === '') return [];
+  try {
+    JSON.parse(text);
+    return [];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const { from, to } = extractJsonErrorPos(msg, text);
+    return [{
+      from, to,
+      severity: 'error',
+      message: msg.replace(/^SyntaxError:\s*/, ''),
+      source: 'json',
+    }];
+  }
+});
+
+function extractJsonErrorPos(msg, text) {
+  const docLen = text.length;
+  // "at position N" — V8 / Chromium / pre-Node-20
+  const posMatch = msg.match(/at position (\d+)/);
+  if (posMatch) {
+    const from = Math.min(docLen, Number(posMatch[1]));
+    return { from, to: Math.min(docLen, from + 1) };
+  }
+  // "line N column M" — Firefox / Node ≥20
+  const lineColMatch = msg.match(/line (\d+) column (\d+)/);
+  if (lineColMatch) {
+    const line = Number(lineColMatch[1]);
+    const col = Number(lineColMatch[2]);
+    let lineStart = 0;
+    let currentLine = 1;
+    for (let i = 0; i < text.length && currentLine < line; i++) {
+      if (text[i] === '\n') { currentLine++; lineStart = i + 1; }
+    }
+    const from = Math.min(docLen, lineStart + Math.max(0, col - 1));
+    return { from, to: Math.min(docLen, from + 1) };
+  }
+  // Fallback: point at the last character so the marker is visible.
+  const end = Math.max(0, docLen);
+  return { from: Math.max(0, end - 1), to: end };
+}
+
+// ── Re-exports (so code.js gets everything from one import) ─────────
+
+export {
+  EditorState, EditorSelection, Compartment, StateEffect,
+  EditorView,
+  lineNumbers, highlightActiveLine, highlightActiveLineGutter,
+  placeholder, drawSelection, keymap,
+  defaultKeymap, history, historyKeymap, indentWithTab,
+  HighlightStyle, syntaxHighlighting, LanguageSupport, defaultHighlightStyle,
+  linter, lintGutter,
+};

package/components/code/code.a2ui.json

@@ -13,9 +13,29 @@
     }
   ],
   "properties": {
+    "required": {
+      "description": "Form constraint — submission blocks if the editor is empty",
+      "type": "boolean",
+      "default": false
+    },
+    "bare": {
+      "description": "Omit the header chrome (label + copy button); for embedded editor surfaces",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "Code"
     },
+    "disabled": {
+      "description": "Disables input and excludes from form submission",
+      "type": "boolean",
+      "default": false
+    },
+    "editable": {
+      "description": "Editable CodeMirror instance (vs read-only display)",
+      "type": "boolean",
+      "default": false
+    },
     "inline": {
       "description": "Inline code (vs block)",
       "type": "boolean",
@@ -31,6 +51,21 @@
       "type": "boolean",
       "default": false
     },
+    "name": {
+      "description": "Form-control name — submitted with the enclosing form when `editable` is set",
+      "type": "string",
+      "default": ""
+    },
+    "placeholder": {
+      "description": "Placeholder text shown when the editor is empty (editable mode only)",
+      "type": "string",
+      "default": ""
+    },
+    "readonly": {
+      "description": "Blocks input but still submits with the form",
+      "type": "boolean",
+      "default": false
+    },
     "text": {
       "description": "Code text content",
       "type": "string",
@@ -45,8 +80,20 @@
     "anti_patterns": [],
     "category": "display",
     "events": {
+      "change": {
+        "description": "Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer"
+      },
       "copy": {
         "description": "Fired when text is copied to clipboard"
+      },
+      "input": {
+        "description": "Fired on every doc change (editable mode); detail.value is the current buffer"
+      },
+      "language-load-error": {
+        "description": "Fired when the language pack or CodeMirror bundle fails to load; detail.phase is 'core' or 'language'"
+      },
+      "save": {
+        "description": "Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable."
       }
     },
     "examples": [
@@ -82,6 +129,18 @@
       {
         "description": "Default, ready for interaction.",
         "name": "idle"
+      },
+      {
+        "description": "Editor is disabled — blocks input and excludes from form submission.",
+        "name": "disabled"
+      },
+      {
+        "description": "Editor blocks input but still submits with the form.",
+        "name": "readonly"
+      },
+      {
+        "description": "Editor has a validation error (e.g. `required` and empty). Reflects as `aria-invalid=\"true\"`.",
+        "name": "invalid"
       }
     ],
     "synonyms": {

package/components/code/code.css

@@ -8,10 +8,10 @@
     --code-copy-px:     var(--a-space-1);
 
     /* ── Colors ── */
-    --code-bg:          var(--a-bg-muted);
+    --code-bg:          var(--a-bg);
     --code-fg:          var(--a-fg);
     --code-border:      var(--a-border-subtle);
-    --code-header-bg:   var(--a-bg-subtle);
+    --code-header-bg:   var(--a-bg-scrim);
     --code-header-fg:   var(--a-fg-muted);
     --code-copy-hover-bg: var(--a-bg-muted);
     --code-copy-hover-fg: var(--a-fg);
@@ -57,6 +57,18 @@
     --code-tok-attribute:    var(--a-warning-strong);
     --code-tok-url:          var(--a-info-strong);
     --code-tok-invalid:      var(--a-danger-strong);
+
+    /* ── Lint markers (Phase 3 — editable JSON) ──
+       `@codemirror/lint` paints gutter markers + diagnostic tooltips
+       + inline underlines. Only fires in editable mode with a linter
+       attached; read-only instances never see these selectors. */
+    --code-lint-gutter-bg:   var(--a-bg-subtle);
+    --code-lint-error:       var(--a-danger-strong);
+    --code-lint-warning:     var(--a-warning-strong);
+    --code-lint-info:        var(--a-info-strong);
+    --code-lint-tooltip-bg:  var(--a-surface-floating);
+    --code-lint-tooltip-fg:  var(--a-fg);
+    --code-lint-tooltip-border: var(--a-border-subtle);
   }
 
   /* ── Block (default) ── */
@@ -196,6 +208,30 @@
     background: transparent;
   }
 
+  /* ── Form states (editable-only surfaces) ──
+     `[disabled]` — visually muted, pointer-events disabled so the user
+     can't click into the editor. CM's readonly compartment handles the
+     actual edit-blocking; these rules are the visual cue.
+     `[readonly]` — muted but clickable (user can still select + copy).
+     `[aria-invalid="true"]` — error ring for form validation failures. */
+  :scope[disabled] {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+  :scope[disabled] .cm-editor {
+    pointer-events: none;
+  }
+  :scope[readonly] .cm-editor {
+    background: var(--a-bg-subtle);
+  }
+  :scope[aria-invalid="true"] {
+    border-color: var(--a-danger-strong);
+  }
+  :scope[aria-invalid="true"] .cm-focused {
+    outline: 2px solid var(--a-danger-strong);
+    outline-offset: -1px;
+  }
+
   /* ── CodeMirror mount ──
      `<code-ui>` inserts `<div data-cm-mount>` in place of `<pre><code>`
      when `[language]` triggers the CM lazy-load. Styles below apply to
@@ -278,4 +314,44 @@
   :scope .tok-attribute   { color: var(--code-tok-attribute); }
   :scope .tok-url         { color: var(--code-tok-url); text-decoration: underline; }
   :scope .tok-invalid     { color: var(--code-tok-invalid); text-decoration: wavy underline; }
+
+  /* ── Lint gutter + diagnostics ──
+     Styles the `@codemirror/lint` markers in the gutter, the inline
+     wavy underline on the diagnostic range, and the tooltip panel. */
+  :scope .cm-gutter-lint {
+    background: var(--code-lint-gutter-bg);
+    width: 1em;
+  }
+  :scope .cm-lint-marker {
+    width: 0.7em;
+    height: 0.7em;
+    margin: 0.15em 0.15em;
+  }
+  :scope .cm-lint-marker-error   { color: var(--code-lint-error); }
+  :scope .cm-lint-marker-warning { color: var(--code-lint-warning); }
+  :scope .cm-lint-marker-info    { color: var(--code-lint-info); }
+
+  :scope .cm-lintRange-error   { background: none; text-decoration: wavy underline var(--code-lint-error); }
+  :scope .cm-lintRange-warning { background: none; text-decoration: wavy underline var(--code-lint-warning); }
+  :scope .cm-lintRange-info    { background: none; text-decoration: wavy underline var(--code-lint-info); }
+
+  :scope .cm-tooltip.cm-tooltip-lint {
+    background: var(--code-lint-tooltip-bg);
+    color: var(--code-lint-tooltip-fg);
+    border: 1px solid var(--code-lint-tooltip-border);
+    border-radius: var(--code-radius-sm);
+    padding: var(--a-space-1) var(--a-space-2);
+    font-size: var(--a-ui-sm);
+    font-family: var(--a-font-family);
+    max-inline-size: 40ch;
+  }
+  :scope .cm-diagnostic {
+    padding: 0;
+    border-inline-start: 3px solid transparent;
+    padding-inline-start: var(--a-space-2);
+  }
+  :scope .cm-diagnostic-error   { border-inline-start-color: var(--code-lint-error); }
+  :scope .cm-diagnostic-warning { border-inline-start-color: var(--code-lint-warning); }
+  :scope .cm-diagnostic-info    { border-inline-start-color: var(--code-lint-info); }
+  :scope .cm-diagnosticText { white-space: pre-wrap; }
 }

package/components/code/code.js

@@ -2,6 +2,7 @@
  * <code-ui language="js">const x = 42;</code-ui>
  * <code-ui language="css" inline>color: red</code-ui>
  * <code-ui language="json" text='{ "hello": "world" }'></code-ui>
+ * <code-ui editable language="json" name="schema" required></code-ui>
  *
  * Inline or block code display with optional language label and copy
  * button. The body comes from (a) declarative children, or (b) the
@@ -10,8 +11,16 @@
  *
  * When `[language]` names a supported language (see SUPPORTED_LANGUAGES),
  * CodeMirror 6 is lazy-loaded and mounted in place of `<pre><code>` for
- * syntax-highlighted read-only rendering. Phase 1 ships read-only only;
- * `[editable]` lands in phase 2 (see docs/specs/code-editor.md §12).
+ * syntax-highlighted rendering. Phase 1 shipped read-only; Phase 2 added
+ * `[editable]`; Phase 3 added lint + form-association (see
+ * `docs/specs/code-editor.md §12`).
+ *
+ * Form participation — editable instances are Form-Associated Custom
+ * Elements (FACE). Set `name`, `required`, `disabled`, `readonly` to
+ * opt into standard form behavior; the editor's live document
+ * becomes the form value. Non-editable instances declare
+ * `formAssociated = true` at the class level (required for FACE) but
+ * contribute nothing to form submission when `[editable]` is absent.
  */
 
 import { AdiaElement } from '../../core/element.js';
@@ -34,6 +43,8 @@ function canonicalLanguage(name) {
 }
 
 class AdiaCode extends AdiaElement {
+  static formAssociated = true;
+
   static properties = {
     language:     { type: String,  default: '', reflect: true },
     inline:       { type: Boolean, default: false, reflect: true },
@@ -42,6 +53,14 @@ class AdiaCode extends AdiaElement {
     editable:     { type: Boolean, default: false, reflect: true },
     bare:         { type: Boolean, default: false, reflect: true },
     placeholder:  { type: String,  default: '', reflect: true },
+
+    // Form-association (active only when `editable` is set; non-editable
+    // instances are FACE-declared for class consistency but contribute
+    // nothing to form submission).
+    name:         { type: String,  default: '', reflect: true },
+    required:     { type: Boolean, default: false, reflect: true },
+    disabled:     { type: Boolean, default: false, reflect: true },
+    readonly:     { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -52,6 +71,8 @@ class AdiaCode extends AdiaElement {
   #mountGen = 0;                // bumps on every connect/disconnect — guards against stale mounts
   #pendingMount = false;        // true while bundle/lang pack is loading
   #focusSnapshot = null;        // doc text captured on focus; used to diff for `change` event
+  #initialDoc = '';             // captured at mount; used by formResetCallback
+  #editableCompartment = null;  // CM Compartment — reconfigures readonly on disabled/readonly change
 
   #onCopyClick = () => this.#copy();
 
@@ -137,7 +158,7 @@ class AdiaCode extends AdiaElement {
     this.#pendingMount = true;
 
     try {
-      const bundle = await import('../../core/code-editor-bundle.js');
+      const bundle = await import('./code-editor.js');
 
       // Load the language pack with a timeout. If it fails, continue with
       // core-only (editor still renders; no syntax highlight). Emit an
@@ -156,7 +177,7 @@ class AdiaCode extends AdiaElement {
       // we were loading. Discard.
       if (gen !== this.#mountGen || !this.isConnected) return;
 
-      this.#attachEditor(bundle, extension);
+      this.#attachEditor(bundle, extension, lang);
     } catch (err) {
       this.dispatchEvent(new CustomEvent('language-load-error', {
         bubbles: true, detail: { phase: 'core', error: err },
@@ -168,21 +189,24 @@ class AdiaCode extends AdiaElement {
     }
   }
 
-  #attachEditor(bundle, languageExtension) {
+  #attachEditor(bundle, languageExtension, lang) {
     const {
       EditorState, EditorView,
+      Compartment,
       lineNumbers,
       placeholder,
       syntaxHighlighting,
       history, historyKeymap, defaultKeymap, indentWithTab,
       keymap,
       adiaBaseTheme, adiaHighlightStyle,
+      lintGutter, jsonLinter,
     } = bundle;
 
     // Replace <pre><code> with a mount target. Keep <header> where it is.
     const pre = this.querySelector(':scope > pre');
     const prior = pre ? pre.querySelector('code')?.textContent ?? '' : '';
     const initial = this.text || prior || '';
+    this.#initialDoc = initial;
 
     const mount = document.createElement('div');
     mount.setAttribute('data-cm-mount', '');
@@ -205,9 +229,11 @@ class AdiaCode extends AdiaElement {
         ]),
         EditorView.updateListener.of((update) => {
           if (!update.docChanged) return;
+          const value = update.state.doc.toString();
+          this.#syncFormValue(value);
           this.dispatchEvent(new CustomEvent('input', {
             bubbles: true,
-            detail: { value: update.state.doc.toString() },
+            detail: { value },
           }));
         }),
         EditorView.domEventHandlers({
@@ -228,19 +254,126 @@ class AdiaCode extends AdiaElement {
           },
         }),
       );
-    } else {
-      extensions.push(EditorView.editable.of(false));
-      extensions.push(EditorState.readOnly.of(true));
     }
 
+    // Editable/readonly compartment — respects editable + disabled + readonly.
+    // Dynamic because `disabled` / `readonly` can change at runtime (e.g.
+    // `formDisabledCallback` from the owning form). Starts with the
+    // correct initial config; `#updateEditableState()` reconfigures on
+    // attribute change.
+    this.#editableCompartment = new Compartment();
+    extensions.push(
+      this.#editableCompartment.of(this.#editableExtensions(EditorView, EditorState)),
+    );
+
     if (languageExtension) extensions.push(languageExtension);
     if (this.lineNumbers) extensions.push(lineNumbers());
     if (this.placeholder) extensions.push(placeholder(this.placeholder));
 
+    // Lint: editable-only, language-specific. JSON for now; extend per
+    // language as need arises. The gutter shows the aggregate marker
+    // per line; the diagnostics themselves produce the tooltip + error
+    // underline on the offending range.
+    if (this.editable && lang === 'json') {
+      extensions.push(jsonLinter, lintGutter());
+    }
+
     this.#cmView = new EditorView({
       parent: mount,
       state: EditorState.create({ doc: initial, extensions }),
     });
+
+    // Seed form value + constraints now that the editor is live.
+    if (this.editable) this.#syncFormValue(initial);
+  }
+
+  /** Returns the CM extensions that enforce editable vs readonly state
+   *  as a function of (editable && !disabled && !readonly). Called at
+   *  mount time and on any runtime change via the compartment. */
+  #editableExtensions(EditorView, EditorState) {
+    const canEdit = this.editable && !this.disabled && !this.readonly;
+    if (canEdit) return [];
+    return [
+      EditorView.editable.of(false),
+      EditorState.readOnly.of(true),
+    ];
+  }
+
+  /** Re-evaluate the editable/readonly state against current attributes.
+   *  Called from `render()` on property change. No-op if the editor
+   *  hasn't mounted yet. */
+  async #updateEditableState() {
+    if (!this.#cmView || !this.#editableCompartment) return;
+    const bundle = await import('./code-editor.js');
+    this.#cmView.dispatch({
+      effects: this.#editableCompartment.reconfigure(
+        this.#editableExtensions(bundle.EditorView, bundle.EditorState),
+      ),
+    });
+  }
+
+  // ── Form-association (FACE) ───────────────────────────────────────
+
+  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; }
+
+  checkValidity() { return this.internals.checkValidity(); }
+  reportValidity() { return this.internals.reportValidity(); }
+
+  /** Push the current editor value to the form + re-run constraints.
+   *  No-op when `editable` is false. Called on every CM doc change and
+   *  from the initial mount + `render()` when `text` is driven externally. */
+  #syncFormValue(val) {
+    if (!this.editable) return;
+    val = val ?? this.value ?? '';
+    this.internals.setFormValue(val);
+    this.#runConstraints(val);
+  }
+
+  #runConstraints(val) {
+    val = val ?? '';
+    if (this.required && !val.trim()) {
+      this.internals.setValidity(
+        { valueMissing: true },
+        this.getAttribute('data-msg-required') || 'This field is required.',
+        this,
+      );
+      this.setAttribute('aria-invalid', 'true');
+      return false;
+    }
+    this.internals.setValidity({});
+    this.removeAttribute('aria-invalid');
+    return true;
+  }
+
+  formResetCallback() {
+    if (this.#cmView) {
+      this.#cmView.dispatch({
+        changes: { from: 0, to: this.#cmView.state.doc.length, insert: this.#initialDoc },
+      });
+    } else {
+      this.text = this.#initialDoc;
+    }
+  }
+
+  formDisabledCallback(disabled) {
+    this.disabled = disabled;
+    // `disabled` is reflected; the render() hook picks up the change
+    // and calls #updateEditableState().
+  }
+
+  formStateRestoreCallback(state, _reason) {
+    if (typeof state !== 'string') return;
+    if (this.#cmView) {
+      this.#cmView.dispatch({
+        changes: { from: 0, to: this.#cmView.state.doc.length, insert: state },
+      });
+    } else {
+      this.text = state;
+    }
   }
 
   #emitSave(view) {
@@ -284,6 +417,9 @@ class AdiaCode extends AdiaElement {
     const label = this.querySelector(':scope > header [slot="label"]');
     if (label && this.language) label.textContent = this.language;
 
+    // React to disabled/readonly toggles on a live editor.
+    this.#updateEditableState();
+
     // Keep the rendered code in sync with the reactive `text` property so
     // callers can drive updates via setAttribute('text', ...).
     if (!this.inline && this.text !== '') {
@@ -296,6 +432,8 @@ class AdiaCode extends AdiaElement {
           this.#cmView.dispatch({
             changes: { from: 0, to: current.length, insert: this.text },
           });
+          // CM's updateListener catches the dispatch and re-syncs the
+          // form value; nothing extra to do here.
         }
       } else {
         const code = this.querySelector(':scope > pre > code');

package/components/code/code.yaml

@@ -25,15 +25,57 @@ props:
     description: Code text content
     type: string
     default: ""
+  editable:
+    description: Editable CodeMirror instance (vs read-only display)
+    type: boolean
+    default: false
+  bare:
+    description: Omit the header chrome (label + copy button); for embedded editor surfaces
+    type: boolean
+    default: false
+  placeholder:
+    description: Placeholder text shown when the editor is empty (editable mode only)
+    type: string
+    default: ""
+  name:
+    description: Form-control name — submitted with the enclosing form when `editable` is set
+    type: string
+    default: ""
+  required:
+    description: Form constraint — submission blocks if the editor is empty
+    type: boolean
+    default: false
+  disabled:
+    description: Disables input and excludes from form submission
+    type: boolean
+    default: false
+  readonly:
+    description: Blocks input but still submits with the form
+    type: boolean
+    default: false
 events:
   copy:
     description: Fired when text is copied to clipboard
+  input:
+    description: Fired on every doc change (editable mode); detail.value is the current buffer
+  change:
+    description: Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer
+  save:
+    description: Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable.
+  language-load-error:
+    description: Fired when the language pack or CodeMirror bundle fails to load; detail.phase is 'core' or 'language'
 slots:
   default:
     description: Raw text fallback when the text property is not set
 states:
   - name: idle
     description: Default, ready for interaction.
+  - name: disabled
+    description: Editor is disabled — blocks input and excludes from form submission.
+  - name: readonly
+    description: Editor blocks input but still submits with the form.
+  - name: invalid
+    description: Editor has a validation error (e.g. `required` and empty). Reflects as `aria-invalid="true"`.
 traits: []
 tokens: {}
 a2ui: