@component-anatomy/core 0.0.1

package/src/theme.ts

@@ -0,0 +1,118 @@
+import type { AnatomyTheme, AnatomyPresetName } from './types.js';
+
+/**
+ * Theming — resolves { preset, theme } into a set of CSS custom properties
+ * applied per controller instance.
+ *
+ * Resolution order (lowest → highest priority):
+ *   1. Stylesheet defaults (the `var(--ca-*, fallback)` chain — the "default" look)
+ *   2. Global CSS variables set by the user on :root or an ancestor
+ *   3. A named preset passed to createAnatomy()
+ *   4. Individual `theme` tokens passed to createAnatomy()
+ *
+ * The `accent` token is a shorthand: when provided, overlay border, overlay
+ * background and label background are derived from it (via color-mix) unless
+ * they are explicitly set too.
+ */
+
+/** Maps theme token names → CSS custom property names used by the stylesheet. */
+export const TOKEN_TO_VAR: Record<
+  keyof Omit<AnatomyTheme, 'accent' | 'overlayBorderStyle'>,
+  string
+> = {
+  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',
+};
+
+/**
+ * Built-in presets. Each is a plain AnatomyTheme — you can also import these,
+ * spread them, and tweak individual tokens.
+ */
+export const presets: Record<AnatomyPresetName, AnatomyTheme> = {
+  /** 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',
+  },
+};
+
+/**
+ * Resolve a { preset, theme } pair into a flat CSS-variable map.
+ * Only *customized* tokens are returned — an empty result means
+ * "use the stylesheet defaults", which keeps global `--ca-*` variables
+ * set by users fully functional (backward compatible).
+ */
+export function resolveThemeVars(
+  preset?: AnatomyPresetName,
+  theme?: AnatomyTheme
+): Record<string, string> {
+  const merged: AnatomyTheme = {
+    ...(preset ? presets[preset] : undefined),
+    ...theme,
+  };
+
+  const vars: Record<string, string> = {};
+
+  // Accent shorthand — derive dependent tokens unless explicitly overridden.
+  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 as keyof AnatomyTheme];
+    if (value !== undefined) {
+      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;
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+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;
+
+/* ─────────────────────────── Theming ─────────────────────────── */
+
+/** 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;
+};
+
+/* ─────────────────────── Overlay customization ─────────────────────── */
+
+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;
+};
+
+/* ─────────────────────────── Options ─────────────────────────── */
+
+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;
+};