@adia-ai/web-components 0.0.13 → 0.0.15

package/components/code/code-editor.js

@@ -31,6 +31,7 @@ import {
 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) ───────────
@@ -91,6 +92,62 @@ export function importWithTimeout(loader, label) {
   ]);
 }
 
+// ── 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 {
@@ -100,4 +157,5 @@ export {
   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();
 
@@ -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:

package/components/heatmap/heatmap.js

@@ -61,12 +61,16 @@ class AdiaHeatmap extends AdiaElement {
     if (!this.#bound) {
       this.#bound = true;
       this.addEventListener('pointerover', this.#onHover);
+      this.addEventListener('pointermove', this.#onMove);
+      this.addEventListener('pointerleave', this.#onLeave);
       this.addEventListener('click', this.#onClick);
     }
   }
 
   disconnected() {
     this.removeEventListener('pointerover', this.#onHover);
+    this.removeEventListener('pointermove', this.#onMove);
+    this.removeEventListener('pointerleave', this.#onLeave);
     this.removeEventListener('click', this.#onClick);
     this.#bound = false;
   }
@@ -217,28 +221,73 @@ class AdiaHeatmap extends AdiaElement {
     return target?.closest?.('[data-cell]');
   }
 
-  #onHover = (e) => {
-    const cell = this.#findCell(e.target);
-    if (!cell || !cell.dataset.v) return;
+  /* Compose the cell-level event with the canonical chart-* shape so that
+     tooltip-ui[follows=pointer][for=this-heatmap] can render without caring
+     whether the source is a chart or a heatmap. */
+  #chartDetail(cell, event) {
     const r = Number(cell.dataset.r);
     const c = Number(cell.dataset.c);
     const v = Number(cell.dataset.v);
     const label = cell.getAttribute('aria-label') || '';
-    this.dispatchEvent(new CustomEvent('cell-hover', {
-      detail: { r, c, v, label }, bubbles: true,
-    }));
+    return {
+      r, c,
+      label,
+      value: Number.isFinite(v) ? v : null,
+      pct: null,
+      series: null,
+      slot: 0,
+      pointerX: event?.clientX ?? null,
+      pointerY: event?.clientY ?? null,
+    };
+  }
+
+  #hoveredCell = null;
+
+  #onHover = (e) => {
+    const cell = this.#findCell(e.target);
+    if (!cell || !cell.dataset.v) return;
+    this.#hoveredCell = cell;
+    const detail = this.#chartDetail(cell, e);
+    /* Legacy cell-specific shape — kept for back-compat. */
+    this.dispatchEvent(new CustomEvent('cell-hover', { detail, bubbles: true }));
+    /* Canonical chart-hover shape for tooltip-ui[follows=pointer]. */
+    this.dispatchEvent(new CustomEvent('chart-hover', { detail, bubbles: true }));
+  };
+
+  #onMove = (e) => {
+    const cell = this.#findCell(e.target);
+    if (!cell || !cell.dataset.v) {
+      if (this.#hoveredCell) {
+        this.#hoveredCell = null;
+        this.dispatchEvent(new CustomEvent('chart-leave', { bubbles: true }));
+      }
+      return;
+    }
+    if (cell !== this.#hoveredCell) {
+      this.#hoveredCell = cell;
+      const detail = this.#chartDetail(cell, e);
+      this.dispatchEvent(new CustomEvent('cell-hover', { detail, bubbles: true }));
+      this.dispatchEvent(new CustomEvent('chart-hover', { detail, bubbles: true }));
+    } else {
+      /* Pointer still inside the same cell — re-fire chart-hover so the
+         pointer-follow tooltip can reposition without re-painting content. */
+      const detail = this.#chartDetail(cell, e);
+      this.dispatchEvent(new CustomEvent('chart-hover', { detail, bubbles: true }));
+    }
+  };
+
+  #onLeave = () => {
+    if (!this.#hoveredCell) return;
+    this.#hoveredCell = null;
+    this.dispatchEvent(new CustomEvent('chart-leave', { bubbles: true }));
   };
 
   #onClick = (e) => {
     const cell = this.#findCell(e.target);
     if (!cell || !cell.dataset.v) return;
-    const r = Number(cell.dataset.r);
-    const c = Number(cell.dataset.c);
-    const v = Number(cell.dataset.v);
-    const label = cell.getAttribute('aria-label') || '';
-    this.dispatchEvent(new CustomEvent('cell-click', {
-      detail: { r, c, v, label }, bubbles: true,
-    }));
+    const detail = this.#chartDetail(cell, e);
+    this.dispatchEvent(new CustomEvent('cell-click', { detail, bubbles: true }));
+    this.dispatchEvent(new CustomEvent('chart-select', { detail, bubbles: true }));
   };
 }