@component-anatomy/core 0.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,142 @@
+# @component-anatomy/core
+
+> Framework-agnostic runtime for interactive component anatomy documentation.
+
+This is the core package. It runs in any browser DOM — no build tools, no framework required.
+
+## Installation
+
+```bash
+npm install @component-anatomy/core
+```
+
+Or via CDN (IIFE build):
+
+```html
+<script src="https://unpkg.com/@component-anatomy/core/dist/index.iife.js"></script>
+<!-- ComponentAnatomy is now available as a global -->
+```
+
+## Usage
+
+Annotate DOM elements with `data-part`:
+
+```html
+<div class="slider">
+  <div class="track" data-part="track"></div>
+  <div class="thumb" data-part="thumb"></div>
+</div>
+```
+
+Initialize the controller:
+
+```js
+import { createAnatomy } from '@component-anatomy/core';
+
+const anatomy = createAnatomy({
+  root: document.querySelector('.slider'),
+  panel: document.querySelector('#anatomy-panel'),
+  parts: [
+    {
+      id: 'track',
+      name: 'Track',
+      description: 'The rail where the thumb slides.',
+    },
+    {
+      id: 'thumb',
+      name: 'Thumb',
+      description: 'The draggable control handle.',
+    },
+  ],
+});
+```
+
+## API
+
+### `createAnatomy(options): AnatomyController`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `root` | `HTMLElement` | Yes | The component preview container |
+| `panel` | `HTMLElement` | No | The documentation panel container |
+| `parts` | `AnatomyPartDefinition[]` | No | Part definitions (auto-discovered from DOM if omitted) |
+| `preset` | `'default' \| 'minimal' \| 'contrast' \| 'blueprint'` | No | Named visual preset |
+| `theme` | `AnatomyTheme` | No | Theme token overrides, e.g. `{ accent: '#0d9488' }` |
+| `overlay` | `OverlayOptions` | No | Overlay hooks: `label`, `padding`, `className`, `renderLabel`, `decorateOverlay` |
+
+### `AnatomyController`
+
+```ts
+interface AnatomyController {
+  highlight(partId: string): void;   // Programmatically highlight a part
+  unhighlight(): void;               // Clear active highlight
+  refresh(): void;                   // Re-discover DOM parts after dynamic updates
+  destroy(): void;                   // Remove all listeners and overlays
+  on(event: AnatomyEvent, handler: AnatomyEventHandler): () => void;
+  getParts(): AnatomyPartDefinition[]; // Resolved (explicit or auto-discovered) parts
+  setTheme(theme: AnatomyTheme, preset?: AnatomyPresetName): void; // Runtime theme switch
+}
+```
+
+### Theming
+
+```js
+// One-line brand match — border, background wash and label derive from accent
+createAnatomy({ root, panel, theme: { accent: '#0d9488' } });
+
+// Named presets
+createAnatomy({ root, panel, preset: 'blueprint' });
+
+// Overlay hooks
+createAnatomy({
+  root,
+  overlay: {
+    padding: 4,
+    renderLabel: ({ part, index }) => `${part.name} #${index + 1}`,
+    decorateOverlay: (box, ctx) => box.classList.add('glow'),
+  },
+});
+```
+
+Full token table: [customization guide](https://julien-deramond.github.io/component-anatomy/docs/customization).
+
+### `AnatomyPartDefinition`
+
+```ts
+type AnatomyPartDefinition = {
+  id: string;           // Stable machine ID, matches data-part value
+  name: string;         // Human-readable display name
+  description?: string; // Markdown supported
+};
+```
+
+### Events
+
+```ts
+anatomy.on('part:enter', (partId) => console.log('hovered:', partId));
+anatomy.on('part:leave', (partId) => console.log('left:', partId));
+```
+
+## CSS custom properties
+
+Instances without a `preset`/`theme` pick up global variables — theme a whole site in CSS only:
+
+```css
+:root {
+  --ca-overlay-bg: rgba(99, 102, 241, 0.18);
+  --ca-overlay-border: rgba(99, 102, 241, 0.75);
+  --ca-overlay-border-width: 2px;
+  --ca-overlay-border-style: solid;
+  --ca-overlay-radius: 4px;
+  --ca-label-bg: rgba(79, 70, 229, 1);
+  --ca-label-fg: #fff;
+  --ca-label-font: ui-monospace, monospace;
+  --ca-label-font-size: 11px;
+  --ca-overlay-z: 9998;
+  --ca-transition: 150ms;
+}
+```
+
+## License
+
+MIT

package/dist/controller.d.ts

@@ -0,0 +1,3 @@
+import type { AnatomyOptions, AnatomyController } from './types.js';
+export declare function createController(options: AnatomyOptions): AnatomyController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AASpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAqL3E"}

package/dist/index.cjs

@@ -0,0 +1,486 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createAnatomy: () => createController,
+  presets: () => presets,
+  resolveThemeVars: () => resolveThemeVars
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/registry.ts
+var AnatomyRegistry = class {
+  constructor(root) {
+    this.observer = null;
+    this.root = root;
+  }
+  /**
+   * Returns a Map of partId → matching HTMLElements.
+   * Always queries the live DOM — never returns a stale cache.
+   */
+  query() {
+    const map = /* @__PURE__ */ new Map();
+    const nodes = this.root.querySelectorAll("[data-part]");
+    nodes.forEach((el) => {
+      const id = el.dataset.part;
+      if (!id) return;
+      const existing = map.get(id) ?? [];
+      existing.push(el);
+      map.set(id, existing);
+    });
+    return map;
+  }
+  /**
+   * Returns all unique part IDs present in the DOM, in document order.
+   */
+  partIds() {
+    const seen = /* @__PURE__ */ new Set();
+    const result = [];
+    this.root.querySelectorAll("[data-part]").forEach((el) => {
+      const id = el.dataset.part;
+      if (id && !seen.has(id)) {
+        seen.add(id);
+        result.push(id);
+      }
+    });
+    return result;
+  }
+  /**
+   * Watches the root for DOM mutations and calls the callback when [data-part]
+   * elements are added or removed. Returns a cleanup function.
+   */
+  observe(callback) {
+    this.observer = new MutationObserver((mutations) => {
+      const relevant = mutations.some(
+        (m) => Array.from(m.addedNodes).concat(Array.from(m.removedNodes)).some(
+          (n) => n instanceof HTMLElement && (n.hasAttribute("data-part") || n.querySelector("[data-part]") !== null)
+        )
+      );
+      if (relevant) callback();
+    });
+    this.observer.observe(this.root, { childList: true, subtree: true });
+    return () => {
+      this.observer?.disconnect();
+      this.observer = null;
+    };
+  }
+  destroy() {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+};
+
+// src/overlay.ts
+var OVERLAY_CLASS = "ca-overlay";
+var LABEL_CLASS = "ca-overlay-label";
+var STYLE_ID = "ca-overlay-styles";
+function injectStyles() {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+    .${OVERLAY_CLASS} {
+      position: fixed;
+      pointer-events: none;
+      box-sizing: border-box;
+      border-radius: var(--ca-overlay-radius, 4px);
+      background: var(--ca-overlay-bg, rgba(99, 102, 241, 0.18));
+      outline: var(--ca-overlay-border-width, 2px)
+               var(--ca-overlay-border-style, solid)
+               var(--ca-overlay-border, rgba(99, 102, 241, 0.75));
+      outline-offset: 1px;
+      z-index: var(--ca-overlay-z, 9998);
+      transition: opacity var(--ca-transition, 150ms) ease;
+    }
+    .${OVERLAY_CLASS}.ca-overlay--hidden {
+      opacity: 0;
+    }
+
+    /* Name label chip \u2014 floats above the overlay */
+    .${LABEL_CLASS} {
+      position: fixed;
+      pointer-events: none;
+      z-index: var(--ca-overlay-z, 9999);
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      padding: 2px 7px 2px 5px;
+      border-radius: 4px;
+      background: var(--ca-label-bg, rgba(79, 70, 229, 1));
+      color: var(--ca-label-fg, #fff);
+      font-family: var(--ca-label-font, ui-monospace, 'Cascadia Code', 'Fira Mono', monospace);
+      font-size: var(--ca-label-font-size, 11px);
+      font-weight: 500;
+      letter-spacing: 0.02em;
+      white-space: nowrap;
+      line-height: 1.6;
+      box-shadow: 0 1px 4px rgba(0,0,0,0.25);
+      transition: opacity var(--ca-transition, 150ms) ease;
+    }
+    .${LABEL_CLASS}.ca-overlay--hidden {
+      opacity: 0;
+    }
+    .${LABEL_CLASS}::before {
+      content: '';
+      display: inline-block;
+      width: 5px;
+      height: 5px;
+      border-radius: 50%;
+      background: color-mix(in srgb, var(--ca-label-fg, #fff) 60%, transparent);
+      flex-shrink: 0;
+    }
+  `;
+  document.head.appendChild(style);
+}
+function applyVars(el, vars) {
+  for (const [prop, value] of Object.entries(vars)) {
+    el.style.setProperty(prop, value);
+  }
+}
+var AnatomyOverlay = class {
+  constructor(vars = {}, options = {}) {
+    this.overlays = [];
+    this.labels = [];
+    this.activeElements = [];
+    this.activePart = null;
+    this.rafId = null;
+    this.vars = vars;
+    this.options = options;
+    injectStyles();
+  }
+  /**
+   * Replace the per-instance theme variables. Re-applies to any overlays
+   * currently on screen.
+   */
+  setVars(vars) {
+    this.vars = vars;
+    if (this.overlays.length > 0 || this.labels.length > 0) {
+      [...this.overlays, ...this.labels].forEach((el) => {
+        el.removeAttribute("style");
+        applyVars(el, vars);
+      });
+      this._position();
+    }
+  }
+  /**
+   * Show highlight overlays + label chip over each of the given elements.
+   */
+  show(elements, part) {
+    this.hide();
+    this.activeElements = elements;
+    this.activePart = part;
+    const showLabel = this.options.label !== false;
+    elements.forEach((element, index) => {
+      const ctx = { part, element, index };
+      const div = document.createElement("div");
+      div.className = `${OVERLAY_CLASS} ca-overlay--hidden`;
+      if (this.options.className) div.className += ` ${this.options.className}`;
+      div.setAttribute("aria-hidden", "true");
+      applyVars(div, this.vars);
+      document.body.appendChild(div);
+      this.overlays.push(div);
+      if (this.options.decorateOverlay) {
+        this.options.decorateOverlay(div, ctx);
+      }
+      if (showLabel) {
+        const label = document.createElement("div");
+        label.className = `${LABEL_CLASS} ca-overlay--hidden`;
+        label.setAttribute("aria-hidden", "true");
+        applyVars(label, this.vars);
+        const custom = this.options.renderLabel?.(ctx);
+        if (typeof custom === "string") label.textContent = custom;
+        else if (custom instanceof Node) label.appendChild(custom);
+        else label.textContent = part.name;
+        document.body.appendChild(label);
+        this.labels.push(label);
+      }
+    });
+    requestAnimationFrame(() => {
+      this._position();
+      this.overlays.forEach((o) => o.classList.remove("ca-overlay--hidden"));
+      this.labels.forEach((l) => l.classList.remove("ca-overlay--hidden"));
+    });
+  }
+  /**
+   * Remove all overlays and labels from the DOM.
+   */
+  hide() {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.overlays.forEach((o) => o.remove());
+    this.labels.forEach((l) => l.remove());
+    this.overlays = [];
+    this.labels = [];
+    this.activeElements = [];
+    this.activePart = null;
+  }
+  /**
+   * Recompute overlay positions. Call on scroll or resize.
+   */
+  reposition() {
+    if (this.overlays.length === 0) return;
+    if (this.rafId !== null) cancelAnimationFrame(this.rafId);
+    this.rafId = requestAnimationFrame(() => {
+      this._position();
+      this.rafId = null;
+    });
+  }
+  destroy() {
+    this.hide();
+  }
+  _position() {
+    const LABEL_OFFSET = 6;
+    const LABEL_HEIGHT = 22;
+    const pad = this.options.padding ?? 0;
+    this.activeElements.forEach((el, i) => {
+      const overlay = this.overlays[i];
+      const label = this.labels[i];
+      if (!overlay) return;
+      const rect = el.getBoundingClientRect();
+      const top = rect.top - pad;
+      const left = rect.left - pad;
+      const width = rect.width + pad * 2;
+      const height = rect.height + pad * 2;
+      overlay.style.top = `${top}px`;
+      overlay.style.left = `${left}px`;
+      overlay.style.width = `${width}px`;
+      overlay.style.height = `${height}px`;
+      if (!label) return;
+      const labelTop = top - LABEL_HEIGHT - LABEL_OFFSET;
+      const finalTop = labelTop < 4 ? top + height + LABEL_OFFSET : labelTop;
+      label.style.top = `${finalTop}px`;
+      label.style.left = `${left}px`;
+    });
+  }
+};
+
+// src/theme.ts
+var TOKEN_TO_VAR = {
+  overlayBg: "--ca-overlay-bg",
+  overlayBorder: "--ca-overlay-border",
+  overlayBorderWidth: "--ca-overlay-border-width",
+  overlayRadius: "--ca-overlay-radius",
+  labelBg: "--ca-label-bg",
+  labelFg: "--ca-label-fg",
+  labelFont: "--ca-label-font",
+  labelFontSize: "--ca-label-font-size",
+  zIndex: "--ca-overlay-z",
+  transitionMs: "--ca-transition"
+};
+var presets = {
+  /** The built-in indigo look. Empty on purpose: it lives in the stylesheet defaults. */
+  default: {},
+  /** Quiet: no fill, thin neutral border, subdued label. */
+  minimal: {
+    overlayBg: "transparent",
+    overlayBorder: "rgba(107, 114, 128, 0.9)",
+    overlayBorderWidth: "1px",
+    overlayRadius: "2px",
+    labelBg: "#374151",
+    labelFg: "#f9fafb"
+  },
+  /** High-visibility: strong yellow/black, thick border. WCAG-friendly. */
+  contrast: {
+    overlayBg: "rgba(250, 204, 21, 0.25)",
+    overlayBorder: "#000000",
+    overlayBorderWidth: "3px",
+    overlayRadius: "0px",
+    labelBg: "#000000",
+    labelFg: "#facc15"
+  },
+  /** Technical drawing look: blue dashed outline on a light wash. */
+  blueprint: {
+    overlayBg: "rgba(37, 99, 235, 0.08)",
+    overlayBorder: "#2563eb",
+    overlayBorderWidth: "1.5px",
+    overlayRadius: "0px",
+    overlayBorderStyle: "dashed",
+    labelBg: "#1d4ed8",
+    labelFg: "#ffffff"
+  }
+};
+function resolveThemeVars(preset, theme) {
+  const merged = {
+    ...preset ? presets[preset] : void 0,
+    ...theme
+  };
+  const vars = {};
+  if (merged.accent) {
+    vars["--ca-overlay-border"] = merged.accent;
+    vars["--ca-overlay-bg"] = `color-mix(in srgb, ${merged.accent} 15%, transparent)`;
+    vars["--ca-label-bg"] = merged.accent;
+  }
+  for (const [token, cssVar] of Object.entries(TOKEN_TO_VAR)) {
+    const value = merged[token];
+    if (value !== void 0) {
+      vars[cssVar] = typeof value === "number" ? token === "zIndex" ? String(value) : token === "transitionMs" ? `${value}ms` : `${value}px` : String(value);
+    }
+  }
+  if (merged.overlayBorderStyle) {
+    vars["--ca-overlay-border-style"] = merged.overlayBorderStyle;
+  }
+  return vars;
+}
+
+// src/controller.ts
+function idToName(id) {
+  return id.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function createController(options) {
+  const { root, panel } = options;
+  const registry = new AnatomyRegistry(root);
+  const overlay = new AnatomyOverlay(
+    resolveThemeVars(options.preset, options.theme),
+    options.overlay ?? {}
+  );
+  let parts = options.parts ?? registry.partIds().map((id) => ({ id, name: idToName(id) }));
+  function findPart(partId) {
+    return parts.find((p) => p.id === partId) ?? { id: partId, name: idToName(partId) };
+  }
+  const listeners = /* @__PURE__ */ new Map();
+  function emit(event, partId) {
+    listeners.get(event)?.forEach((fn) => fn(partId));
+  }
+  const cleanupFns = [];
+  function highlight(partId, source = "panel") {
+    const elements = registry.query().get(partId) ?? [];
+    overlay.show(elements, findPart(partId));
+    if (panel) {
+      panel.querySelectorAll("[data-anatomy-item]").forEach((el) => {
+        if (el.dataset.anatomyItem === partId) {
+          el.setAttribute("data-active", "");
+          if (source === "preview") {
+            el.scrollIntoView({ behavior: "smooth", block: "nearest" });
+          }
+        } else {
+          el.removeAttribute("data-active");
+        }
+      });
+    }
+    emit("part:enter", partId);
+  }
+  function unhighlight() {
+    overlay.hide();
+    if (panel) {
+      panel.querySelectorAll("[data-anatomy-item]").forEach((el) => {
+        el.removeAttribute("data-active");
+      });
+    }
+    emit("part:leave", "");
+  }
+  function attachElementListeners() {
+    const map = registry.query();
+    map.forEach((elements, partId) => {
+      elements.forEach((el) => {
+        const enter = () => highlight(partId, "preview");
+        const leave = () => unhighlight();
+        el.addEventListener("mouseenter", enter);
+        el.addEventListener("mouseleave", leave);
+        cleanupFns.push(() => {
+          el.removeEventListener("mouseenter", enter);
+          el.removeEventListener("mouseleave", leave);
+        });
+      });
+    });
+  }
+  function attachPanelListeners() {
+    if (!panel) return;
+    panel.querySelectorAll("[data-anatomy-item]").forEach((el) => {
+      const partId = el.dataset.anatomyItem ?? "";
+      const enter = () => highlight(partId, "panel");
+      const leave = () => unhighlight();
+      el.addEventListener("mouseenter", enter);
+      el.addEventListener("mouseleave", leave);
+      el.addEventListener("focus", enter);
+      el.addEventListener("blur", leave);
+      cleanupFns.push(() => {
+        el.removeEventListener("mouseenter", enter);
+        el.removeEventListener("mouseleave", leave);
+        el.removeEventListener("focus", enter);
+        el.removeEventListener("blur", leave);
+      });
+    });
+  }
+  const onScroll = () => overlay.reposition();
+  const onResize = () => overlay.reposition();
+  const resizeObserver = new ResizeObserver(() => overlay.reposition());
+  function setup() {
+    attachElementListeners();
+    attachPanelListeners();
+    window.addEventListener("scroll", onScroll, { passive: true, capture: true });
+    window.addEventListener("resize", onResize, { passive: true });
+    resizeObserver.observe(root);
+    const stopObserving = registry.observe(() => {
+      teardownListeners();
+      if (!options.parts) {
+        parts = registry.partIds().map((id) => ({ id, name: idToName(id) }));
+      }
+      attachElementListeners();
+      attachPanelListeners();
+    });
+    cleanupFns.push(stopObserving);
+  }
+  function teardownListeners() {
+    const observerCleanup = cleanupFns.pop();
+    cleanupFns.forEach((fn) => fn());
+    cleanupFns.length = 0;
+    if (observerCleanup) cleanupFns.push(observerCleanup);
+  }
+  setup();
+  return {
+    highlight,
+    unhighlight,
+    refresh() {
+      unhighlight();
+      teardownListeners();
+      if (!options.parts) {
+        parts = registry.partIds().map((id) => ({ id, name: idToName(id) }));
+      }
+      attachElementListeners();
+      attachPanelListeners();
+    },
+    destroy() {
+      unhighlight();
+      cleanupFns.forEach((fn) => fn());
+      cleanupFns.length = 0;
+      window.removeEventListener("scroll", onScroll, { capture: true });
+      window.removeEventListener("resize", onResize);
+      resizeObserver.disconnect();
+      overlay.destroy();
+      registry.destroy();
+      listeners.clear();
+    },
+    on(event, handler) {
+      if (!listeners.has(event)) listeners.set(event, /* @__PURE__ */ new Set());
+      listeners.get(event).add(handler);
+      return () => listeners.get(event)?.delete(handler);
+    },
+    getParts() {
+      return parts.slice();
+    },
+    setTheme(theme, preset) {
+      overlay.setVars(resolveThemeVars(preset, theme));
+    }
+  };
+}
+//# sourceMappingURL=index.cjs.map