@adia-ai/web-modules 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -11,6 +11,32 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.3.6] - 2026-05-10
+
+### Added
+
+- **Editor cluster bespoke family** — third cluster decomposed per ADR-0023, confirming the pattern is canonical across 3 distinct shell archetypes.
+  - **`<editor-toolbar full-screen?>`** — JS-bearing (58 LOC + 8 unit tests). Replaces legacy `<header>` chrome bar inside `<editor-shell>`. Click-bubble for `[data-toolbar-action]` fires `toolbar-action` event. Slot vocabulary (title, status, action, action-leading).
+  - **`<editor-canvas empty? focused?>`** — JS-bearing (103 LOC + 11 unit tests). Replaces legacy `<div data-canvas>`. Owns scroll/zoom container, `[empty]` reflected, `[focused]` reflected. Public API: `.focus()` / `.blur()` / `.resetView()` / `.zoom` getter+setter.
+  - **`<editor-sidebar collapsible>`** — JS-bearing (170 LOC + 11 unit tests). **First bespoke child that DELEGATES rather than DUPLICATES a primitive's behavior** — wraps `<pane-ui resizable>` for drag, owns `[collapsed]` reflected via ResizeObserver, localStorage persistence (`adia-editor-sidebar-{name}` cluster-distinct).
+  - **2 CSS-only structural children** — `<editor-statusbar>`, `<editor-canvas-empty>` (visibility driven by parent `<editor-canvas>[empty]`).
+
+- **CSS bridge** `editor/editor-shell/css/editor-shell.bespoke.css` (172 LOC) — maps the 5 bespoke editor tags to a CSS Grid layout. Imported last in `editor-shell.css`.
+
+- **`editor/index.js` exports** all 4 JS-bearing editor children (EditorShell + EditorToolbar + EditorCanvas + EditorSidebar). Subpath import unchanged: `import '@adia-ai/web-modules/editor'`.
+
+### Changed
+
+- **`<editor-shell>` host** — refactored from 56 LOC (just select-options JSON parsing) to 115 LOC. Reads BOTH legacy + bespoke shapes via priority chain. Adds `[focus-mode]` reflected attribute that propagates to bespoke children's `[full-screen]` / `[focused]`. Listens for `toolbar-action` bubble events. Backwards compat preserved.
+
+### Fixed
+
+- **`<editor-sidebar>.collapse()` persist-before-snap bug** (commit `1d63f0d1`) — the implementation was setting `style.width = SNAP_THRESHOLD` THEN calling `#persistWidth()`, which overwrote storage with 96 (the snap value). On `expand()` the stored value would be ≤ threshold and fall through to default 240, losing the user's pre-collapse width. Fix: capture pre-collapse width by calling `#persistWidth()` BEFORE the snap, guarded by `if (!this.collapsed)`. Caught by the `expand() restores from stored width or defaults to 240` test on first run. Documented as Pitfall #12 in the `bespoke-shell-children` skill.
+
+### Backwards compatibility
+
+Legacy authoring shapes (`<header>`, `<div data-editor-body>`, `<pane-ui data-left|data-right>`, `<div data-canvas>`, `<footer>`) all still work identically. Mixed markup renders the same. Migration is opt-in.
+
 ## [0.3.5] - 2026-05-07
 
 ### Added

package/editor/editor-canvas/editor-canvas.a2ui.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/EditorCanvas.json",
+  "title": "EditorCanvas",
+  "description": "Module-tier editor canvas surface — replaces legacy <div data-canvas>\ninside <editor-shell> per ADR-0023. Owns scroll/zoom container\nsemantics, [empty] and [focused] reflected attributes, and a stable\ntarget for the host's content rendering pipeline.\n\nSits as the central content region inside <editor-shell>, between\nthe optional <editor-sidebar slot=\"leading\"> and <editor-sidebar\nslot=\"trailing\">. Authors compose <editor-canvas-empty> as an\noptional first child for the empty state; canvas content children\n(artboards, document body, etc.) are appended either statically or\ndynamically by the host.\n\nBackwards compat — <editor-shell> still recognizes the legacy\n<div data-canvas> shape via :is() selector. New code should prefer\n<editor-canvas>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "EditorCanvas"
+    },
+    "empty": {
+      "description": "Reflected — set when zero non-<editor-canvas-empty> children.\nDrives the <editor-canvas-empty> visibility via parent CSS —\nno JS toggling needed.\n",
+      "type": "boolean",
+      "default": true
+    },
+    "focused": {
+      "description": "Reflected — set when canvas claims focus ownership (programmatic\n.focus() call or toolbar full-screen toggle).\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "editor-canvas",
+      "canvas",
+      "workspace",
+      "artboard",
+      "editor-surface"
+    ],
+    "name": "EditorCanvas",
+    "related": [
+      "EditorShell",
+      "EditorCanvasEmpty",
+      "EditorToolbar",
+      "EditorSidebar"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default — canvas content (artboards, document body, blocks, etc.) plus an optional first <editor-canvas-empty> sibling for the empty state."
+      }
+    },
+    "states": [
+      {
+        "description": "Default canvas mode.",
+        "name": "idle"
+      },
+      {
+        "description": "Zero content children — empty state visible.",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "Canvas is the focus surface.",
+        "attribute": "focused",
+        "name": "focused"
+      }
+    ],
+    "synonyms": {
+      "editor-canvas": [
+        "canvas",
+        "workspace",
+        "artboard",
+        "design-surface"
+      ]
+    },
+    "tag": "editor-canvas",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/editor/editor-canvas/editor-canvas.js

@@ -0,0 +1,103 @@
+/**
+ * <editor-canvas focused?>
+ *   <editor-canvas-empty>...</editor-canvas-empty>  (optional empty state)
+ *   <!-- canvas content (children) -->
+ * </editor-canvas>
+ *
+ * Module-tier editor canvas surface — replaces legacy <div data-canvas>
+ * inside <editor-shell> per ADR-0023. Owns:
+ *
+ *   - [empty] reflected attribute (set when no non-stub children) —
+ *     drives <editor-canvas-empty> visibility via parent CSS
+ *   - [focused] reflected attribute (set when canvas claims focus
+ *     ownership; e.g., toolbar full-screen toggle, click-to-focus)
+ *   - Public API for zoom/pan refs (.zoom getter/setter, .resetView())
+ *   - .focus() / .blur() programmatic — sets [focused] reflected
+ *
+ * Reflected attributes:
+ *   [empty]    — true when zero non-<editor-canvas-empty> children
+ *   [focused]  — true when canvas is the focus surface
+ *
+ * Public methods:
+ *   .focus()      — claim focus + reflect [focused]
+ *   .blur()       — release focus + clear [focused]
+ *   .resetView()  — reset zoom/pan to defaults
+ *
+ * Properties:
+ *   .zoom         — getter/setter (default 1.0)
+ *
+ * The host (<editor-shell>) reads either <editor-canvas> or
+ * [data-canvas] / <div data-canvas> via :is() selector for backwards
+ * compat.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+class EditorCanvas extends UIElement {
+  static properties = {
+    empty: { type: Boolean, default: true, reflect: true },
+    focused: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #zoom = 1.0;
+  #childObserver = null;
+
+  connected() {
+    this.#syncEmptyFromChildren();
+    this.#setupChildObserver();
+  }
+
+  disconnected() {
+    this.#childObserver?.disconnect();
+    this.#childObserver = null;
+  }
+
+  // ── Public API ──
+
+  get zoom() {
+    return this.#zoom;
+  }
+
+  set zoom(value) {
+    const v = parseFloat(value);
+    if (!isFinite(v) || v <= 0) return;
+    this.#zoom = v;
+    this.style.setProperty('--editor-canvas-zoom', String(v));
+  }
+
+  resetView() {
+    this.zoom = 1.0;
+    // Future: also reset pan offsets when implemented
+  }
+
+  focus() {
+    super.focus?.();
+    this.focused = true;
+  }
+
+  blur() {
+    super.blur?.();
+    this.focused = false;
+  }
+
+  // ── Internal: empty state from children ──
+
+  #syncEmptyFromChildren() {
+    const contentChildren = Array.from(this.children).filter(
+      (c) => c.tagName.toLowerCase() !== 'editor-canvas-empty'
+    );
+    this.empty = contentChildren.length === 0;
+  }
+
+  #setupChildObserver() {
+    this.#childObserver = new MutationObserver(() => {
+      this.#syncEmptyFromChildren();
+    });
+    this.#childObserver.observe(this, { childList: true });
+  }
+}
+
+customElements.define('editor-canvas', EditorCanvas);
+export { EditorCanvas };

package/editor/editor-canvas/editor-canvas.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../../web-components/core/element.js';
+import './editor-canvas.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  globalThis.MutationObserver = class {
+    observe() {} disconnect() {}
+  };
+});
+
+describe('editor-canvas', () => {
+  it('registers editor-canvas as a custom element', () => {
+    expect(customElements.get('editor-canvas')).toBeDefined();
+  });
+
+  it('defaults to focused=false', () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    expect(c.focused).toBe(false);
+  });
+
+  it('defaults to empty=true with no children', async () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    await tick();
+    expect(c.empty).toBe(true);
+  });
+
+  it('reflects [empty] via property assignment', async () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    c.empty = false;
+    await tick();
+    expect(c.hasAttribute('empty')).toBe(false);
+    c.empty = true;
+    await tick();
+    expect(c.hasAttribute('empty')).toBe(true);
+  });
+
+  it('reflects [focused] via property assignment', async () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    c.focused = true;
+    await tick();
+    expect(c.hasAttribute('focused')).toBe(true);
+  });
+
+  it('does not count <editor-canvas-empty> stub as a content child', () => {
+    const c = mount('<editor-canvas><editor-canvas-empty></editor-canvas-empty></editor-canvas>');
+    expect(c.empty).toBe(true);
+  });
+
+  it('exposes .zoom getter/setter (default 1.0)', () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    expect(c.zoom).toBe(1.0);
+    c.zoom = 2.0;
+    expect(c.zoom).toBe(2.0);
+    expect(c.style.getPropertyValue('--editor-canvas-zoom')).toBe('2');
+  });
+
+  it('rejects invalid zoom values', () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    c.zoom = 1.5;
+    c.zoom = 'invalid';   // should not change
+    expect(c.zoom).toBe(1.5);
+    c.zoom = -1;          // should not change
+    expect(c.zoom).toBe(1.5);
+    c.zoom = 0;           // should not change
+    expect(c.zoom).toBe(1.5);
+  });
+
+  it('.resetView() restores zoom to 1.0', () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    c.zoom = 2.5;
+    c.resetView();
+    expect(c.zoom).toBe(1.0);
+  });
+
+  it('.focus() sets [focused] reflected', async () => {
+    const c = mount('<editor-canvas></editor-canvas>');
+    c.focus();
+    await tick();
+    expect(c.focused).toBe(true);
+    expect(c.hasAttribute('focused')).toBe(true);
+  });
+
+  it('.blur() clears [focused] reflected', async () => {
+    const c = mount('<editor-canvas focused></editor-canvas>');
+    c.blur();
+    await tick();
+    expect(c.focused).toBe(false);
+    expect(c.hasAttribute('focused')).toBe(false);
+  });
+});

package/editor/editor-canvas/editor-canvas.yaml

@@ -0,0 +1,88 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: EditorCanvas
+tag: editor-canvas
+component: EditorCanvas
+category: container
+version: 1
+description: |
+  Module-tier editor canvas surface — replaces legacy <div data-canvas>
+  inside <editor-shell> per ADR-0023. Owns scroll/zoom container
+  semantics, [empty] and [focused] reflected attributes, and a stable
+  target for the host's content rendering pipeline.
+
+  Sits as the central content region inside <editor-shell>, between
+  the optional <editor-sidebar slot="leading"> and <editor-sidebar
+  slot="trailing">. Authors compose <editor-canvas-empty> as an
+  optional first child for the empty state; canvas content children
+  (artboards, document body, etc.) are appended either statically or
+  dynamically by the host.
+
+  Backwards compat — <editor-shell> still recognizes the legacy
+  <div data-canvas> shape via :is() selector. New code should prefer
+  <editor-canvas>.
+
+props:
+  empty:
+    description: |
+      Reflected — set when zero non-<editor-canvas-empty> children.
+      Drives the <editor-canvas-empty> visibility via parent CSS —
+      no JS toggling needed.
+    type: boolean
+    default: true
+    reflect: true
+  focused:
+    description: |
+      Reflected — set when canvas claims focus ownership (programmatic
+      .focus() call or toolbar full-screen toggle).
+    type: boolean
+    default: false
+    reflect: true
+
+events: {}
+
+slots:
+  default:
+    description: >-
+      Default — canvas content (artboards, document body, blocks, etc.)
+      plus an optional first <editor-canvas-empty> sibling for the
+      empty state.
+
+states:
+  - name: idle
+    description: Default canvas mode.
+  - name: empty
+    attribute: empty
+    description: Zero content children — empty state visible.
+  - name: focused
+    attribute: focused
+    description: Canvas is the focus surface.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      editor-canvas is the bespoke replacement for legacy
+      <div data-canvas> inside <editor-shell>. Use it as the central
+      content region for editor work surfaces.
+    - >-
+      Place <editor-canvas-empty> as an optional first child for the
+      empty state; the [empty] reflected attribute drives its visibility
+      via CSS (no JS toggling).
+
+keywords:
+  - editor-canvas
+  - canvas
+  - workspace
+  - artboard
+  - editor-surface
+
+synonyms:
+  editor-canvas: [canvas, workspace, artboard, design-surface]
+
+related:
+  - EditorShell
+  - EditorCanvasEmpty
+  - EditorToolbar
+  - EditorSidebar

package/editor/editor-canvas-empty/editor-canvas-empty.a2ui.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/EditorCanvasEmpty.json",
+  "title": "EditorCanvasEmpty",
+  "description": "Module-tier editor canvas empty state. CSS-only — no behavior, no\nJS. Sits as the first child of <editor-canvas> as the empty state\nplaceholder. Visibility is driven by <editor-canvas>'s [empty]\nreflected attribute via CSS (no JS toggling) — when content arrives,\nthe parent canvas loses [empty] and CSS hides this stub.\n\nReplaces ad-hoc empty-state placement inside the legacy\n<div data-canvas> per ADR-0023.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "EditorCanvasEmpty"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "editor-canvas-empty",
+      "empty-state",
+      "placeholder",
+      "no-content",
+      "canvas-empty"
+    ],
+    "name": "EditorCanvasEmpty",
+    "related": [
+      "EditorShell",
+      "EditorCanvas",
+      "EmptyState"
+    ],
+    "slots": {
+      "default": {
+        "description": "Empty state content — typically <empty-state-ui> with a \"Create new...\" prompt or onboarding affordance."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, visible.",
+        "name": "idle"
+      },
+      {
+        "description": "Hidden via parent <editor-canvas>:not([empty]) selector.",
+        "name": "hidden"
+      }
+    ],
+    "synonyms": {
+      "editor-canvas-empty": [
+        "empty-state",
+        "placeholder",
+        "no-document"
+      ]
+    },
+    "tag": "editor-canvas-empty",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/editor/editor-canvas-empty/editor-canvas-empty.yaml

@@ -0,0 +1,56 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: EditorCanvasEmpty
+tag: editor-canvas-empty
+component: EditorCanvasEmpty
+category: feedback
+version: 1
+description: |
+  Module-tier editor canvas empty state. CSS-only — no behavior, no
+  JS. Sits as the first child of <editor-canvas> as the empty state
+  placeholder. Visibility is driven by <editor-canvas>'s [empty]
+  reflected attribute via CSS (no JS toggling) — when content arrives,
+  the parent canvas loses [empty] and CSS hides this stub.
+
+  Replaces ad-hoc empty-state placement inside the legacy
+  <div data-canvas> per ADR-0023.
+
+props: {}
+
+events: {}
+
+slots:
+  default:
+    description: >-
+      Empty state content — typically <empty-state-ui> with a
+      "Create new..." prompt or onboarding affordance.
+
+states:
+  - name: idle
+    description: Default, visible.
+  - name: hidden
+    description: Hidden via parent <editor-canvas>:not([empty]) selector.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      editor-canvas-empty is the bespoke empty-state slot for
+      <editor-canvas>. Place as the first child of <editor-canvas>;
+      visibility is automatic via the [empty] reflected attribute.
+
+keywords:
+  - editor-canvas-empty
+  - empty-state
+  - placeholder
+  - no-content
+  - canvas-empty
+
+synonyms:
+  editor-canvas-empty: [empty-state, placeholder, no-document]
+
+related:
+  - EditorShell
+  - EditorCanvas
+  - EmptyState