@component-anatomy/astro

@component-anatomy/astro

Astro integration for component-anatomy — SSR-rendered Markdown descriptions, live hover sync, zero client-side Markdown bundle.

Installation

npm install @component-anatomy/astro

Usage

Import the <ComponentAnatomy> component and wrap any HTML you want to document:

---
import ComponentAnatomy from '@component-anatomy/astro/ComponentAnatomy.astro';

const parts = [
  {
    id: 'track',
    name: 'Track',
    description: 'The **rail** where the thumb slides. Takes full width of the container.',
  },
  {
    id: 'thumb',
    name: 'Thumb',
    description: 'The draggable handle. Constrained to the `Track`.',
  },
];
---

<ComponentAnatomy parts={parts}>
  <div class="slider">
    <div class="track" data-part="track"></div>
    <div class="thumb" data-part="thumb"></div>
  </div>
</ComponentAnatomy>

Props

Prop	Type	Required	Description
parts	AnatomyPartDefinition[]	No	Part definitions. If omitted, parts are auto-discovered from data-part attributes.
preset	'default' | 'minimal' | 'contrast' | 'blueprint'	No	Visual preset for overlays and panel accent.
theme	AnatomyTheme	No	Theme token overrides, e.g. { accent: '#0d9488', overlayRadius: 8 }.
overlayLabel	boolean	No	Show the floating name chip. Default true.
label	string	No	Accessible label of the block. Default "Component anatomy".
class	string	No	Extra class on the wrapper.

Theming

<ComponentAnatomy parts={parts} preset="blueprint">
  <Slider />
</ComponentAnatomy>

<ComponentAnatomy parts={parts} theme={{ accent: '#0d9488' }}>
  <Slider />
  <p slot="header">Hover a part below, or the component itself.</p>
</ComponentAnatomy>

The theme applies to both the canvas overlays and the panel accents. Layout variables (--ca-gap, --ca-preview-bg, --ca-preview-padding, --ca-panel-max-height) can be set on the wrapper via class. Full guide: customization docs.

AnatomyPartDefinition:

{
  id: string;           // Matches the data-part value on the DOM element
  name: string;         // Display name shown in the panel
  description?: string; // Raw Markdown — rendered server-side by marked
}

How it works

• The server renders the two-column layout (preview + panel) with Markdown descriptions converted to HTML by marked — no Markdown library is shipped to the browser
• The client script calls createAnatomy() from @component-anatomy/core to wire up hover sync and overlays
• Multiple <ComponentAnatomy> instances on the same page are isolated via a random instance ID

Requirements

• Astro ≥ 4.0
• Node ≥ 18

License

MIT