@profpowell/vb-project-planning 0.1.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@profpowell/vb-project-planning",
+  "version": "0.1.0",
+  "description": "Project- and UX-planning Web Components for Vanilla Breeze: personas, stories, journeys, empathy maps, impact/effort and quadrant grids, risk and traceability matrices, burndown, roadmap, kanban, story map, gantt, review surface, work items, ADRs, iron triangle, capacity plans, quality targets, and requirement cards.",
+  "license": "MIT",
+  "author": "Patrick Powell",
+  "type": "module",
+  "homepage": "https://github.com/ProfPowell/vb-project-planning#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProfPowell/vb-project-planning.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ProfPowell/vb-project-planning/issues"
+  },
+  "keywords": [
+    "vanilla-breeze",
+    "web-components",
+    "project-planning",
+    "ux",
+    "agile",
+    "kanban",
+    "roadmap"
+  ],
+  "files": [
+    "src",
+    "dist"
+  ],
+  "main": "./dist/vb-project-planning.js",
+  "module": "./src/index.js",
+  "style": "./dist/vb-project-planning.css",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./dist/vb-project-planning.js"
+    },
+    "./css": "./src/index.css",
+    "./dist/css": "./dist/vb-project-planning.css",
+    "./user-persona": "./src/web-components/user-persona/logic.js",
+    "./user-story": "./src/web-components/user-story/logic.js",
+    "./user-journey": "./src/web-components/user-journey/logic.js",
+    "./empathy-map": "./src/web-components/empathy-map/logic.js",
+    "./impact-effort": "./src/web-components/impact-effort/logic.js",
+    "./quadrant-grid": "./src/web-components/quadrant-grid/logic.js",
+    "./risk-register": "./src/web-components/risk-register/logic.js",
+    "./traceability-matrix": "./src/web-components/traceability-matrix/logic.js",
+    "./burndown-chart": "./src/web-components/burndown-chart/logic.js",
+    "./product-roadmap": "./src/web-components/product-roadmap/logic.js",
+    "./kanban-board": "./src/web-components/kanban-board/logic.js",
+    "./story-map": "./src/web-components/story-map/logic.js",
+    "./review-surface": "./src/web-components/review-surface/logic.js",
+    "./gantt-chart": "./src/web-components/gantt-chart/logic.js",
+    "./work-item": "./src/web-components/work-item/logic.js",
+    "./adr-wc": "./src/web-components/adr-wc/logic.js",
+    "./iron-triangle": "./src/web-components/iron-triangle/logic.js",
+    "./capacity-plan": "./src/web-components/capacity-plan/logic.js",
+    "./quality-target": "./src/web-components/quality-target/logic.js",
+    "./requirement-card": "./src/web-components/requirement-card/logic.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "npm run build:js && npm run build:css",
+    "build:js": "esbuild src/index.js --bundle --format=esm --outfile=dist/vb-project-planning.js && esbuild src/index.js --bundle --format=esm --minify --outfile=dist/vb-project-planning.min.js",
+    "build:css": "esbuild src/index.css --bundle --outfile=dist/vb-project-planning.css && esbuild src/index.css --bundle --minify --outfile=dist/vb-project-planning.min.css",
+    "prepublishOnly": "npm run build",
+    "test:components": "playwright test"
+  },
+  "peerDependencies": {
+    "vanilla-breeze": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vanilla-breeze": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "esbuild": "^0.27.0"
+  }
+}

package/src/index.css

@@ -0,0 +1,14 @@
+/* @profpowell/vb-project-planning — light-DOM component styles.
+   (Shadow-DOM components bundle their own CSS via logic.js.) */
+@import "./web-components/impact-effort/styles.css";
+@import "./web-components/quadrant-grid/styles.css";
+@import "./web-components/risk-register/styles.css";
+@import "./web-components/traceability-matrix/styles.css";
+@import "./web-components/burndown-chart/styles.css";
+@import "./web-components/product-roadmap/styles.css";
+@import "./web-components/kanban-board/styles.css";
+@import "./web-components/story-map/styles.css";
+@import "./web-components/gantt-chart/styles.css";
+@import "./web-components/iron-triangle/styles.css";
+@import "./web-components/capacity-plan/styles.css";
+@import "./web-components/quality-target/styles.css";

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * @profpowell/vb-project-planning — barrel.
+ * Side-effect imports register every project-planning component.
+ * Consumes Vanilla Breeze tokens/themes via CSS custom properties.
+ * Drag-to-reorder components require <drag-surface> (Vanilla Breeze peer).
+ */
+import './web-components/user-persona/logic.js';
+import './web-components/user-story/logic.js';
+import './web-components/user-journey/logic.js';
+import './web-components/empathy-map/logic.js';
+import './web-components/impact-effort/logic.js';
+import './web-components/quadrant-grid/logic.js';
+import './web-components/risk-register/logic.js';
+import './web-components/traceability-matrix/logic.js';
+import './web-components/burndown-chart/logic.js';
+import './web-components/product-roadmap/logic.js';
+import './web-components/kanban-board/logic.js';
+import './web-components/story-map/logic.js';
+import './web-components/review-surface/logic.js';
+import './web-components/gantt-chart/logic.js';
+import './web-components/work-item/logic.js';
+import './web-components/adr-wc/logic.js';
+import './web-components/iron-triangle/logic.js';
+import './web-components/capacity-plan/logic.js';
+import './web-components/quality-target/logic.js';
+import './web-components/requirement-card/logic.js';

package/src/lib/bundle-registry.js

@@ -0,0 +1,156 @@
+/**
+ * Bundle Registry — Vanilla Breeze
+ *
+ * Provides infrastructure for modular bundles to register effects,
+ * components, and activate full bundles at runtime.
+ */
+
+// ─── Effect registry ─────────────────────────────────────────────────────────
+
+const effects = new Map()
+let observer = null
+const reducedMotionMq = window.matchMedia('(prefers-reduced-motion: reduce)')
+
+function startObserver() {
+  if (observer) return
+  observer = new MutationObserver(mutations => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue
+        const el = /** @type {Element} */ (node)
+        matchEffects(el)
+        el.querySelectorAll('*').forEach(matchEffects)
+      }
+      for (const node of mutation.removedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue
+        const el = /** @type {Element} */ (node)
+        unmatchEffects(el)
+        el.querySelectorAll('*').forEach(unmatchEffects)
+      }
+    }
+  })
+  observer.observe(document.body, { childList: true, subtree: true })
+}
+
+function matchEffects(el) {
+  for (const [, def] of effects) {
+    if (el.matches?.(def.selector)) {
+      if (reducedMotionMq.matches && def.reducedMotionFallback) {
+        def.reducedMotionFallback(el)
+      } else {
+        def.init(el)
+      }
+    }
+  }
+}
+
+function unmatchEffects(el) {
+  for (const [, def] of effects) {
+    if (el.matches?.(def.selector) && def.destroy) {
+      def.destroy(el)
+    }
+  }
+}
+
+/**
+ * Register a DOM effect that auto-initializes on matching elements.
+ *
+ * @param {string} name - Unique effect name
+ * @param {{ selector: string, init: (el: Element) => void, destroy?: (el: Element) => void, reducedMotionFallback?: (el: Element) => void }} def
+ */
+export function registerEffect(name, def) {
+  effects.set(name, def)
+
+  // Initialize on existing matching elements
+  document.querySelectorAll(def.selector).forEach(el => {
+    if (reducedMotionMq.matches && def.reducedMotionFallback) {
+      def.reducedMotionFallback(el)
+    } else {
+      def.init(el)
+    }
+  })
+
+  // Start shared observer lazily
+  if (document.body) {
+    startObserver()
+  } else {
+    document.addEventListener('DOMContentLoaded', startObserver, { once: true })
+  }
+}
+
+// ─── Component registry ──────────────────────────────────────────────────────
+
+const components = new Map()
+
+/**
+ * Register a custom element with priority-based conflict resolution.
+ * First-wins at equal priority. Higher priority wins over lower.
+ *
+ * @param {string} tag - Custom element tag name
+ * @param {typeof HTMLElement} impl - The element class
+ * @param {{ bundle?: string, contract?: string, priority?: number }} [opts]
+ */
+export function registerComponent(tag, impl, opts = {}) {
+  const priority = opts.priority ?? 10
+  const meta = { impl, bundle: opts.bundle, contract: opts.contract, priority }
+
+  const existing = components.get(tag)
+
+  if (customElements.get(tag)) {
+    // Already defined in the browser — cannot redefine
+    if (!existing || existing.priority >= priority) {
+      if (existing && existing.priority === priority && existing.impl !== impl) {
+        console.warn(
+          `[VB Bundle] Tag <${tag}> already registered by "${existing.bundle}" (priority ${existing.priority}). Skipping "${opts.bundle}".`
+        )
+      }
+      return
+    }
+    // Higher priority but can't redefine — warn
+    console.warn(
+      `[VB Bundle] Tag <${tag}> defined by "${existing.bundle}" cannot be replaced (customElements.define is permanent). "${opts.bundle}" has higher priority but arrived late.`
+    )
+    return
+  }
+
+  if (existing && existing.priority >= priority) {
+    if (existing.priority === priority) {
+      console.warn(
+        `[VB Bundle] Tag <${tag}> already registered by "${existing.bundle}". Skipping "${opts.bundle}" (first wins at equal priority).`
+      )
+    }
+    return
+  }
+
+  components.set(tag, meta)
+  customElements.define(tag, impl)
+}
+
+/**
+ * Activate a full pack by loading its CSS and JS from the CDN path.
+ * Convention: cdn/packs/{name}.full.css and cdn/packs/{name}.full.js
+ *
+ * @param {string} bundleName
+ * @param {{ basePath?: string }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function activateBundle(bundleName, opts = {}) {
+  const base = opts.basePath ?? '/cdn/packs'
+
+  // Load CSS
+  const cssHref = `${base}/${bundleName}.full.css`
+  if (!document.querySelector(`link[href="${cssHref}"]`)) {
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href = cssHref
+    await new Promise((resolve, reject) => {
+      link.onload = resolve
+      link.onerror = () => reject(new Error(`Failed to load bundle CSS: ${cssHref}`))
+      document.head.appendChild(link)
+    })
+  }
+
+  // Load JS
+  const jsSrc = `${base}/${bundleName}.full.js`
+  await import(jsSrc)
+}

package/src/lib/diff-by-key.js

@@ -0,0 +1,86 @@
+/**
+ * Keyed list diff with move-not-recreate semantics.
+ *
+ * Reconciles a `nodes` map (key → Element) against `newItems` so that
+ * each key in `newItems` ends up rendered in its target container at
+ * its target index. Existing nodes are moved rather than recreated;
+ * only new keys cause renderItem() to fire.
+ *
+ * Formal guarantee: a node whose key appears in both the current map
+ * and `newItems` is never removed. It may be moved (different parent
+ * or different position within the same parent), but the underlying
+ * DOM node identity is preserved — so in-flight drag state, focus,
+ * and CSS animations survive.
+ *
+ * The DOM operations used are minimal: `Node.insertBefore`, `Element.remove`,
+ * and reads of `parentElement` / `children`. Subclasses are responsible for
+ * removing non-managed children (placeholders, etc.) before the diff if
+ * they want clean indexing.
+ *
+ * @template T
+ * @param {object} opts
+ * @param {T[]} opts.newItems
+ * @param {Map<unknown, Element>} opts.nodes  Mutated in place.
+ * @param {(item: T) => unknown} opts.keyOf
+ * @param {(item: T) => Element} opts.renderItem  Called only for new keys.
+ * @param {(item: T, existingEl: Element | null) => Element} opts.containerFor
+ * @returns {{ added: unknown[], moved: unknown[], removed: unknown[] }}
+ */
+export function diffByKey({ newItems, nodes, keyOf, renderItem, containerFor }) {
+  const added = [];
+  const moved = [];
+  const removed = [];
+
+  // 1. Compute new key set for membership checks.
+  const newKeys = new Set();
+  for (const item of newItems) newKeys.add(keyOf(item));
+
+  // 2. Remove nodes whose keys are gone. (No node with a still-live key is
+  //    ever removed — that's the formal preservation guarantee.)
+  for (const [key, el] of [...nodes]) {
+    if (!newKeys.has(key)) {
+      el.remove();
+      nodes.delete(key);
+      removed.push(key);
+    }
+  }
+
+  // 3. Resolve each item's target container. Group entries per container
+  //    so we can reconcile each container's order in one pass.
+  /** @type {Map<Element, Array<{ item: T, key: unknown, existing: Element | null }>>} */
+  const byContainer = new Map();
+  for (const item of newItems) {
+    const key = keyOf(item);
+    const existing = nodes.get(key) || null;
+    const container = containerFor(item, existing);
+    if (!byContainer.has(container)) byContainer.set(container, []);
+    byContainer.get(container)?.push({ item, key, existing });
+  }
+
+  // 4. For each container, place each entry at its target index.
+  //    insertBefore is a no-op when the node is already at that position,
+  //    and a move (preserving identity) when it isn't.
+  for (const [container, entries] of byContainer) {
+    for (let i = 0; i < entries.length; i++) {
+      const { item, key, existing } = entries[i];
+      let el = existing;
+      if (!el) {
+        el = renderItem(item);
+        nodes.set(key, el);
+        added.push(key);
+      } else if (el.parentElement !== container) {
+        moved.push(key);
+      } else {
+        // Same container: detect intra-container reorder.
+        if (container.children[i] !== el) moved.push(key);
+      }
+
+      const target = container.children[i];
+      if (target !== el) {
+        container.insertBefore(el, target || null);
+      }
+    }
+  }
+
+  return { added, moved, removed };
+}

package/src/lib/portrait-url.js

@@ -0,0 +1,87 @@
+/**
+ * Portrait URL utility
+ *
+ * Generates deterministic portrait image URLs from the faker-js
+ * person-portrait CDN assets (CC0 licensed, AI-generated).
+ *
+ * 200 unique portraits (100 male, 100 female) at 5 sizes:
+ *   32, 64, 128, 256, 512 px (square).
+ *
+ * @example
+ * portraitUrl('Sarah Chen');
+ * // → 'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/female/128/37.jpg'
+ *
+ * portraitUrl('Marcus Johnson', 256);
+ * // → 'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait/male/256/82.jpg'
+ */
+
+const CDN = 'https://cdn.jsdelivr.net/gh/faker-js/assets-person-portrait';
+const SIZES = [32, 64, 128, 256, 512];
+
+/**
+ * Simple string hash (same algorithm as _ux-base.js hashColor).
+ * @param {string} str
+ * @returns {number}
+ */
+function hash(str) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = str.charCodeAt(i) + ((h << 5) - h);
+  }
+  return h;
+}
+
+/**
+ * Snap a pixel value to the nearest available portrait size.
+ * @param {number} px - Desired size in pixels
+ * @returns {number} Closest available size (32, 64, 128, 256, or 512)
+ */
+function snapSize(px) {
+  let best = SIZES[0];
+  let bestDist = Math.abs(px - best);
+  for (let i = 1; i < SIZES.length; i++) {
+    const dist = Math.abs(px - SIZES[i]);
+    if (dist < bestDist) {
+      best = SIZES[i];
+      bestDist = dist;
+    }
+  }
+  return best;
+}
+
+/**
+ * Generate a deterministic portrait URL from a seed string.
+ *
+ * The same seed always produces the same portrait. Sex and index are
+ * derived from the seed hash, so names cluster naturally — different
+ * names get different faces.
+ *
+ * @param {string} seed  - Any string (name, ID, index, etc.)
+ * @param {number} [size=128] - Desired image size in px (snapped to nearest available)
+ * @returns {string} CDN URL for the portrait JPEG
+ */
+export function portraitUrl(seed, size = 128) {
+  const h = hash(String(seed));
+  const index = ((h % 100) + 100) % 100;
+  const sex = ((h >>> 16) & 1) === 0 ? 'female' : 'male';
+  const snapped = snapSize(size);
+  return `${CDN}/${sex}/${snapped}/${index}.jpg`;
+}
+
+/**
+ * Get a portrait URL by explicit numeric index (0–199).
+ * 0–99 = female, 100–199 = male.
+ *
+ * @param {number} index - Portrait index (0–199)
+ * @param {number} [size=128] - Desired image size in px
+ * @returns {string} CDN URL
+ */
+export function portraitByIndex(index, size = 128) {
+  const i = ((index % 200) + 200) % 200;
+  const sex = i < 100 ? 'female' : 'male';
+  const fileIndex = i < 100 ? i : i - 100;
+  const snapped = snapSize(size);
+  return `${CDN}/${sex}/${snapped}/${fileIndex}.jpg`;
+}
+
+export { SIZES as PORTRAIT_SIZES, CDN as PORTRAIT_CDN };

package/src/lib/vb-collection.js

@@ -0,0 +1,122 @@
+/**
+ * VBCollection — Mixin for "keyed list of children" components.
+ *
+ * Subclass implements:
+ *   _renderItem(item) → Element       Build a fresh element for a new key.
+ *   _containerFor(item, existingEl)   (Optional) the parent each item lives in.
+ *   _postRender({ added, moved, removed, items })  (Optional) refresh placeholders / counts.
+ *
+ * Subclass declares (optional):
+ *   static keyOf = (item) => item.id   Diff key. Default: item.id.
+ *
+ * Provides:
+ *   .items   getter/setter — assignment runs a keyed diff.
+ *   _emit(name, detail, source)  — tags events with source for loop avoidance.
+ *
+ * Formal guarantee: any element whose key is present in both the previous
+ * and the next items list is preserved (never removed and recreated). The
+ * same DOM node may be moved across containers or reordered, but its
+ * identity — and any in-flight drag, focus, or animation state — survives.
+ */
+
+import { diffByKey } from './diff-by-key.js';
+
+/**
+ * @template {new (...args: any[]) => HTMLElement} TBase
+ * @param {TBase} Base
+ */
+export function VBCollection(Base) {
+  const BaseAny = /** @type {any} */ (Base);
+  return class extends BaseAny {
+    static keyOf(item) { return item.id; }
+
+    /** @type {any[]} */
+    #items = [];
+    /** @type {Map<unknown, Element>} */
+    #nodes = new Map();
+
+    get items() { return this.#items; }
+    set items(value) {
+      const next = value || [];
+      const result = diffByKey({
+        newItems: next,
+        nodes: this.#nodes,
+        keyOf: /** @type {any} */ (this.constructor).keyOf,
+        renderItem: (item) => /** @type {any} */ (this._renderItem(item)),
+        containerFor: (item, existing) => /** @type {any} */ (this._containerFor(item, existing)),
+      });
+      this.#items = next;
+      this._postRender({ ...result, items: next });
+      this._emit('items-changed', { items: next }, 'api');
+    }
+
+    /**
+     * Subclass hook. Build a fresh element for a new item.
+     * Must return Element. Strings/templates are not accepted (see VB-XG5X).
+     */
+    _renderItem(_item) {
+      throw new Error(`${this.constructor.name}: must implement _renderItem(item)`);
+    }
+
+    /**
+     * Subclass hook. Where this item lives. Default: the element itself.
+     * Override to route items into specific child containers (e.g. kanban columns).
+     */
+    _containerFor(_item, _existingEl) {
+      return this;
+    }
+
+    /**
+     * Subclass hook. Called after every diff. Use to refresh placeholders,
+     * counts, WIP markers, empty-state UI.
+     */
+    _postRender(_diff) {}
+
+    /**
+     * Dispatch a tagged event so consumers can avoid feedback loops.
+     * @param {string} name  Event suffix (e.g. 'items-changed').
+     * @param {object} detail  Custom payload.
+     * @param {'api' | 'attribute' | 'drag' | 'internal' | string} [source='api']
+     */
+    _emit(name, detail, source = 'api') {
+      this.dispatchEvent(new CustomEvent(`${this.localName}:${name}`, {
+        detail: { ...detail, source },
+        bubbles: true,
+      }));
+    }
+
+    /**
+     * Read-only access to the rendered node for a given key.
+     * Useful for subclass hooks that want to update an item in place.
+     */
+    _nodeFor(key) {
+      return this.#nodes.get(key) || null;
+    }
+
+    /**
+     * Seed the collection from existing DOM (HTML-first upgrade path).
+     * Subclass calls this once after parsing initial children so the next
+     * `.items = ...` assignment diffs against existing rendered nodes
+     * instead of recreating them.
+     *
+     * @param {any[]} items
+     * @param {Map<unknown, Element>} nodeMap  key → existing element
+     */
+    _seedCollection(items, nodeMap) {
+      this.#items = items;
+      this.#nodes.clear();
+      for (const [key, el] of nodeMap) this.#nodes.set(key, el);
+    }
+
+    /**
+     * Update the in-memory items array without running a diff (e.g. after
+     * a drag mutates the DOM). Subclass is expected to keep the DOM and
+     * the items array in sync; this method just records the new model.
+     *
+     * @param {any[]} items
+     */
+    _setItemsSilently(items) {
+      this.#items = items;
+    }
+  };
+}

package/src/lib/vb-element.js

@@ -0,0 +1,96 @@
+/**
+ * VBElement — Minimal base class for Vanilla Breeze web components
+ *
+ * Provides:
+ * - data-upgraded guard (prevents double initialization on reconnect)
+ * - listen() method with automatic cleanup on disconnect
+ * - setup()/teardown() lifecycle hooks
+ *
+ * Does NOT provide: props reflection, template rendering, reactivity.
+ * Components that need observedAttributes/attributeChangedCallback
+ * declare them normally alongside setup()/teardown().
+ */
+class VBElement extends HTMLElement {
+  #cleanups = [];
+  /** @type {ElementInternals | undefined} */
+  #internals;
+
+  connectedCallback() {
+    if (this.hasAttribute('data-upgraded')) return;
+    if (this.setup() === false) return;
+    this.setAttribute('data-upgraded', '');
+    // Dispatch :upgraded in a microtask so any sibling component definitions
+    // queued in the same synchronous script (e.g. a pack's registerComponent
+    // calls) complete before consumers react. Without this, listeners that
+    // immediately assign .items can hit a race where downstream components
+    // (work-item, etc.) aren't defined yet and the default renderer falls
+    // back to a plain element.
+    queueMicrotask(() => {
+      this.dispatchEvent(new CustomEvent(`${this.localName}:upgraded`, { bubbles: true }));
+    });
+  }
+
+  disconnectedCallback() {
+    for (const fn of this.#cleanups) fn();
+    this.#cleanups = [];
+    this.removeAttribute('data-upgraded');
+    this.teardown();
+  }
+
+  /**
+   * Track an event listener for automatic cleanup on disconnect.
+   * @param {EventTarget} target
+   * @param {string} event
+   * @param {EventListenerOrEventListenerObject} handler
+   * @param {AddEventListenerOptions} [opts]
+   */
+  listen(target, event, handler, opts) {
+    target.addEventListener(event, handler, opts);
+    this.#cleanups.push(() => target.removeEventListener(event, handler, opts));
+  }
+
+  /**
+   * Override in subclass. Return false to abort upgrade.
+   * @returns {boolean | void}
+   */
+  setup() {}
+
+  /** Override in subclass for cleanup beyond event listeners. */
+  teardown() {}
+
+  /**
+   * Toggle a CustomStateSet entry targetable via the `:state(name)` CSS selector.
+   * Use for component-private flags. For author-facing state, keep using
+   * data-* / aria-* attributes — see admin/specs/custom-state-set-research.md.
+   *
+   * Lazily attaches ElementInternals on first call; subclasses that already
+   * attached internals (form-associated components) must hand them over via
+   * `_adoptInternals(this.attachInternals())` in their constructor to avoid
+   * the double-attach throw.
+   *
+   * @param {string} name
+   * @param {boolean} on
+   */
+  setState(name, on) {
+    if (!this.#internals) this.#internals = this.attachInternals();
+    const states = this.#internals.states;
+    try {
+      if (on) states.add(name); else states.delete(name);
+    } catch {
+      // Legacy --name syntax for older Chromium/WebKit releases
+      const legacy = `--${name}`;
+      if (on) states.add(legacy); else states.delete(legacy);
+    }
+  }
+
+  /**
+   * Hand pre-attached ElementInternals to the base class. Form-associated
+   * subclasses call this in their constructor right after attachInternals().
+   * @param {ElementInternals} internals
+   */
+  _adoptInternals(internals) {
+    if (!this.#internals) this.#internals = internals;
+  }
+}
+
+export { VBElement };