@component-anatomy/core 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+export type AnatomyPartDefinition = {
+    /** Matches the value of data-part="..." on the DOM element */
+    id: string;
+    /** Display name shown in the documentation panel and overlay label */
+    name: string;
+    /** Raw Markdown string — rendered by the integration layer */
+    description?: string;
+};
+export type AnatomyEvent = 'part:enter' | 'part:leave';
+export type AnatomyEventHandler = (partId: string) => void;
+/** Names of the built-in visual presets. */
+export type AnatomyPresetName = 'default' | 'minimal' | 'contrast' | 'blueprint';
+/**
+ * Theme tokens. All optional — anything you don't set falls back to the
+ * preset, then to global `--ca-*` CSS variables, then to the default look.
+ */
+export type AnatomyTheme = {
+    /**
+     * Shorthand: a single brand color. Overlay border, overlay background
+     * (15% wash) and label background are derived from it automatically.
+     */
+    accent?: string;
+    /** Overlay fill. Any CSS color. */
+    overlayBg?: string;
+    /** Overlay border color. */
+    overlayBorder?: string;
+    /** Overlay border width — number (px) or CSS length. */
+    overlayBorderWidth?: string | number;
+    /** Overlay border style: 'solid' | 'dashed' | 'dotted'… */
+    overlayBorderStyle?: string;
+    /** Overlay corner radius — number (px) or CSS length. */
+    overlayRadius?: string | number;
+    /** Label chip background. */
+    labelBg?: string;
+    /** Label chip text color. */
+    labelFg?: string;
+    /** Label chip font-family. */
+    labelFont?: string;
+    /** Label chip font-size — number (px) or CSS length. */
+    labelFontSize?: string | number;
+    /** z-index of overlays and labels. */
+    zIndex?: number;
+    /** Show/hide transition duration — number (ms) or CSS time. */
+    transitionMs?: string | number;
+};
+export type OverlayRenderContext = {
+    /** The part being highlighted. */
+    part: AnatomyPartDefinition;
+    /** The DOM element this overlay box covers. */
+    element: HTMLElement;
+    /** Index of this element among all elements matching the part (0-based). */
+    index: number;
+};
+export type OverlayOptions = {
+    /** Show the floating name label chip. Default: true. */
+    label?: boolean;
+    /**
+     * Custom label content. Return a string (used as textContent) or a Node
+     * (appended). Return null/undefined to fall back to the part name.
+     */
+    renderLabel?: (ctx: OverlayRenderContext) => string | Node | null | undefined;
+    /**
+     * Called after each overlay box is created and positioned — mutate it,
+     * append children, add classes. The box is `position: fixed` and sized
+     * to the target element.
+     */
+    decorateOverlay?: (box: HTMLElement, ctx: OverlayRenderContext) => void;
+    /** Extra class name(s) added to every overlay box. */
+    className?: string;
+    /** Inflate the highlight box by N pixels on every side. Default: 0. */
+    padding?: number;
+};
+export type AnatomyOptions = {
+    /** The component preview container — where data-part elements live */
+    root: HTMLElement;
+    /** The documentation panel container — where data-anatomy-item elements live */
+    panel?: HTMLElement;
+    /** Part definitions. If omitted, auto-discovers from data-part values in the DOM */
+    parts?: AnatomyPartDefinition[];
+    /** Named visual preset. Default: 'default'. */
+    preset?: AnatomyPresetName;
+    /** Per-instance theme token overrides (applied on top of the preset). */
+    theme?: AnatomyTheme;
+    /** Overlay rendering options and hooks. */
+    overlay?: OverlayOptions;
+};
+export type AnatomyController = {
+    /** Programmatically activate a part (overlay + panel highlight) */
+    highlight(partId: string): void;
+    /** Deactivate all parts */
+    unhighlight(): void;
+    /** Re-query the DOM — call after dynamic updates */
+    refresh(): void;
+    /** Tear down all listeners and overlays */
+    destroy(): void;
+    /** Subscribe to part activation events. Returns an unsubscribe function. */
+    on(event: AnatomyEvent, handler: AnatomyEventHandler): () => void;
+    /** The resolved part definitions (explicit or auto-discovered). */
+    getParts(): AnatomyPartDefinition[];
+    /** Swap theme tokens at runtime. Pass a preset name, tokens, or both. */
+    setTheme(theme: AnatomyTheme, preset?: AnatomyPresetName): void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@component-anatomy/core",
+  "version": "0.0.1",
+  "description": "Framework-agnostic runtime for interactive component anatomy documentation",
+  "license": "MIT",
+  "author": "Julien Déramond",
+  "homepage": "https://github.com/julien-deramond/component-anatomy#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/julien-deramond/component-anatomy",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/julien-deramond/component-anatomy/issues"
+  },
+  "keywords": [
+    "component-anatomy",
+    "design-system",
+    "documentation",
+    "dom",
+    "overlay",
+    "anatomy",
+    "interactive",
+    "framework-agnostic"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "esbuild": "^0.21.0",
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.0",
+    "jsdom": "^24.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/controller.ts

@@ -0,0 +1,200 @@
+import { AnatomyRegistry } from './registry.js';
+import { AnatomyOverlay } from './overlay.js';
+import { resolveThemeVars } from './theme.js';
+import type {
+  AnatomyOptions,
+  AnatomyController,
+  AnatomyEvent,
+  AnatomyEventHandler,
+  AnatomyPartDefinition,
+} from './types.js';
+
+/** Capitalizes an ID like "slider-thumb" → "Slider Thumb" */
+function idToName(id: string): string {
+  return id
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function createController(options: AnatomyOptions): AnatomyController {
+  const { root, panel } = options;
+
+  const registry = new AnatomyRegistry(root);
+  const overlay = new AnatomyOverlay(
+    resolveThemeVars(options.preset, options.theme),
+    options.overlay ?? {}
+  );
+
+  // Resolve part definitions: explicit or auto-discovered
+  let parts: AnatomyPartDefinition[] = options.parts ??
+    registry.partIds().map((id) => ({ id, name: idToName(id) }));
+
+  function findPart(partId: string): AnatomyPartDefinition {
+    return parts.find((p) => p.id === partId) ?? { id: partId, name: idToName(partId) };
+  }
+
+  // Event emitter
+  const listeners = new Map<AnatomyEvent, Set<AnatomyEventHandler>>();
+
+  function emit(event: AnatomyEvent, partId: string) {
+    listeners.get(event)?.forEach((fn) => fn(partId));
+  }
+
+  // Cleanup registry
+  const cleanupFns: Array<() => void> = [];
+
+  function highlight(partId: string, source: 'preview' | 'panel' = 'panel') {
+    const elements = registry.query().get(partId) ?? [];
+    overlay.show(elements, findPart(partId));
+
+    // Mark matching panel items active + scroll into view when triggered from preview
+    if (panel) {
+      panel.querySelectorAll<HTMLElement>('[data-anatomy-item]').forEach((el) => {
+        if (el.dataset.anatomyItem === partId) {
+          el.setAttribute('data-active', '');
+          // Only auto-scroll when hover comes from the component, not the panel itself
+          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<HTMLElement>('[data-anatomy-item]').forEach((el) => {
+        el.removeAttribute('data-active');
+      });
+    }
+
+    // emit part:leave with empty string as signal (last active unknown at this point)
+    emit('part:leave', '');
+  }
+
+  function attachElementListeners() {
+    const map = registry.query();
+
+    map.forEach((elements, partId) => {
+      elements.forEach((el) => {
+        // Mouse only — no focus/blur here.
+        // Preview elements are a live component; adding tabstops breaks
+        // their natural tab order and confuses assistive technology.
+        // Keyboard navigation is handled via the panel entries only.
+        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<HTMLElement>('[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);
+      });
+    });
+  }
+
+  // Scroll + resize → reposition active overlays
+  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);
+
+    // Watch for dynamic DOM changes
+    const stopObserving = registry.observe(() => {
+      teardownListeners();
+      // Re-resolve auto-discovered parts if none were explicitly provided
+      if (!options.parts) {
+        parts = registry.partIds().map((id) => ({ id, name: idToName(id) }));
+      }
+      attachElementListeners();
+      attachPanelListeners();
+    });
+    cleanupFns.push(stopObserving);
+  }
+
+  function teardownListeners() {
+    // Run all registered cleanup functions except the MutationObserver (last one)
+    // We rebuild element/panel listeners on refresh but keep the observer running
+    const observerCleanup = cleanupFns.pop(); // MutationObserver cleanup is last
+    cleanupFns.forEach((fn) => fn());
+    cleanupFns.length = 0;
+    if (observerCleanup) cleanupFns.push(observerCleanup); // put it back
+  }
+
+  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, 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));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export type {
+  AnatomyPartDefinition,
+  AnatomyOptions,
+  AnatomyController,
+  AnatomyEvent,
+  AnatomyEventHandler,
+  AnatomyTheme,
+  AnatomyPresetName,
+  OverlayOptions,
+  OverlayRenderContext,
+} from './types.js';
+
+export { createController as createAnatomy } from './controller.js';
+export { presets, resolveThemeVars } from './theme.js';

package/src/overlay.ts

@@ -0,0 +1,231 @@
+import type {
+  AnatomyPartDefinition,
+  OverlayOptions,
+  OverlayRenderContext,
+} from './types.js';
+
+/**
+ * AnatomyOverlay — renders position:fixed highlight boxes + name label chips
+ * over target elements. Injected into document.body to escape ancestor
+ * stacking contexts and CSS transforms.
+ *
+ * Theming: the injected stylesheet reads `--ca-*` custom properties with
+ * built-in fallbacks (the "default" look). Per-instance themes are applied
+ * as inline custom properties on each overlay/label element, so multiple
+ * controllers with different themes can coexist on one page while global
+ * `--ca-*` variables keep working as a page-wide default.
+ */
+
+const OVERLAY_CLASS = 'ca-overlay';
+const LABEL_CLASS = 'ca-overlay-label';
+const 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 — 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: HTMLElement, vars: Record<string, string>) {
+  for (const [prop, value] of Object.entries(vars)) {
+    el.style.setProperty(prop, value);
+  }
+}
+
+export class AnatomyOverlay {
+  private overlays: HTMLDivElement[] = [];
+  private labels: HTMLDivElement[] = [];
+  private activeElements: HTMLElement[] = [];
+  private activePart: AnatomyPartDefinition | null = null;
+  private rafId: number | null = null;
+
+  private vars: Record<string, string>;
+  private options: OverlayOptions;
+
+  constructor(vars: Record<string, string> = {}, options: OverlayOptions = {}) {
+    this.vars = vars;
+    this.options = options;
+    injectStyles();
+  }
+
+  /**
+   * Replace the per-instance theme variables. Re-applies to any overlays
+   * currently on screen.
+   */
+  setVars(vars: Record<string, string>): void {
+    this.vars = vars;
+    if (this.overlays.length > 0 || this.labels.length > 0) {
+      [...this.overlays, ...this.labels].forEach((el) => {
+        el.removeAttribute('style'); // clear stale vars (positioning restored below)
+        applyVars(el, vars);
+      });
+      this._position();
+    }
+  }
+
+  /**
+   * Show highlight overlays + label chip over each of the given elements.
+   */
+  show(elements: HTMLElement[], part: AnatomyPartDefinition): void {
+    this.hide();
+    this.activeElements = elements;
+    this.activePart = part;
+
+    const showLabel = this.options.label !== false;
+
+    elements.forEach((element, index) => {
+      const ctx: OverlayRenderContext = { 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);
+      }
+    });
+
+    // Position after paint so getBoundingClientRect is accurate
+    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(): void {
+    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(): void {
+    if (this.overlays.length === 0) return;
+    if (this.rafId !== null) cancelAnimationFrame(this.rafId);
+    this.rafId = requestAnimationFrame(() => {
+      this._position();
+      this.rafId = null;
+    });
+  }
+
+  destroy(): void {
+    this.hide();
+  }
+
+  private _position(): void {
+    const LABEL_OFFSET = 6; // px gap between label and overlay top edge
+    const LABEL_HEIGHT = 22; // approximate label height
+    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;
+
+      // Position the highlight box
+      overlay.style.top = `${top}px`;
+      overlay.style.left = `${left}px`;
+      overlay.style.width = `${width}px`;
+      overlay.style.height = `${height}px`;
+
+      if (!label) return;
+
+      // Place label chip above the overlay; flip below if too close to top
+      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`;
+    });
+  }
+}

package/src/registry.ts

@@ -0,0 +1,77 @@
+/**
+ * AnatomyRegistry — discovers and tracks [data-part] elements within a root.
+ * Intentionally stateless between calls: query() always reads the live DOM.
+ */
+export class AnatomyRegistry {
+  private root: HTMLElement;
+  private observer: MutationObserver | null = null;
+
+  constructor(root: HTMLElement) {
+    this.root = root;
+  }
+
+  /**
+   * Returns a Map of partId → matching HTMLElements.
+   * Always queries the live DOM — never returns a stale cache.
+   */
+  query(): Map<string, HTMLElement[]> {
+    const map = new Map<string, HTMLElement[]>();
+    const nodes = this.root.querySelectorAll<HTMLElement>('[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(): string[] {
+    const seen = new Set<string>();
+    const result: string[] = [];
+    this.root.querySelectorAll<HTMLElement>('[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: () => void): () => void {
+    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;
+  }
+}