@tapestrylab/template

@tapestrylab/template

Template engine for generating structured component documentation with full integration with @tapestrylab/extract and @tapestrylab/resolve.

Features

• Full Pipeline Integration: Seamlessly integrates with @tapestrylab/extract for component metadata and @tapestrylab/resolve for relationship data
• Direct Type Usage: Uses ComponentMetadata from @tapestrylab/extract as its data model
• Zero-Config Defaults: Works beautifully out of the box with built-in templates and themes
• Progressive Enhancement: Start simple, customize as needed
• Multiple Output Formats: Markdown, MDX, and HTML support
• Theming System: Complete design control with theme support
• Programmatic API: Build and modify templates programmatically

Installation

pnpm add @tapestrylab/template

Quick Start

Generate Documentation from Component Source

import { generateAll } from '@tapestrylab/template';
import { TemplateBuilder } from '@tapestrylab/template';

// Option 1: Use built-in template
await generateAll({
  source: './src/components',
  outputDir: './docs',
  template: './node_modules/@tapestrylab/template/templates/component-docs.taptpl.json',
  outputFormat: 'mdx',
});

// Option 2: Create custom template programmatically
const template = new TemplateBuilder()
  .setMetadata({ name: 'My Template', outputFormat: 'mdx' })
  .addHeading(1, '{{name}}')
  .addParagraph('{{description}}', { if: 'description' })
  .addPropsTable('props')
  .addCodeBlocks('examples', { language: 'tsx', if: 'examples.length > 0' });

await template.save('./templates/my-template.taptpl.json');

Core Concepts

Data Model: ComponentMetadata

Templates use ComponentMetadata from @tapestrylab/extract directly:

interface ComponentMetadata {
  name: string;
  filePath: string;
  exportType: 'default' | 'named';
  props: PropMetadata[];
  description?: string;
  deprecated?: string | boolean;
  since?: string;
  examples?: string[];
  links?: string[];
  // ... and more
}

Template Structure

Templates are JSON files with blocks:

{
  "name": "Component Documentation",
  "outputFormat": "mdx",
  "blocks": [
    { "type": "heading", "level": 1, "text": "{{name}}" },
    { "type": "paragraph", "text": "{{description}}", "if": "description" },
    { "type": "propsTable", "dataSource": "props" }
  ]
}

Variables

Use {{variable}} syntax to access ComponentMetadata fields:

• {{name}} - Component name
• {{description}} - Component description
• {{props[0].name}} - First prop name
• {{props.length}} - Number of props

Conditionals

Control visibility with if expressions:

{
  "type": "paragraph",
  "text": "{{description}}",
  "if": "description"
}

{
  "type": "propsTable",
  "dataSource": "props",
  "if": "props.length > 0"
}

API Reference

Generate Documentation

import { generate, generateAll } from '@tapestrylab/template';

// Generate single component
const result = await generate({
  source: './src/components/Button.tsx',
  template: templateObject,
  output: './docs/Button.mdx',
  outputFormat: 'mdx',
});

// Generate all components
const results = await generateAll({
  source: './src/components',
  outputDir: './docs',
  template: templateObject,
  outputFormat: 'mdx',
  includeRelationships: true, // Include usage sites, dependencies, etc.
});

Template Builder

import { TemplateBuilder, createTemplate } from '@tapestrylab/template';

const template = createTemplate('My Template')
  .addHeading(1, '{{name}}')
  .addParagraph('{{description}}')
  .addPropsTable('props')
  .addCallout('warning', '{{deprecated}}', { if: 'deprecated' });

await template.save('./templates/my-template.taptpl.json');

Extract Components

import { extractComponents } from '@tapestrylab/template';

const components = await extractComponents({
  root: './src/components',
  include: ['**/*.tsx'],
});

Theming

The template package includes a flexible theming system that allows you to customize the appearance of generated documentation.

Using Built-in Themes

Three preset themes are included:

import { generateAll } from '@tapestrylab/template';

await generateAll({
  source: './src/components',
  outputDir: './docs',
  template: myTemplate,
  theme: './node_modules/@tapestrylab/template/themes/default.theme.js',
  // or 'minimal.theme.js', 'documentation.theme.js'
});

Built-in themes:

• default.theme.js - Balanced styling with borders and backgrounds
• minimal.theme.js - Minimal styling, mostly unstyled
• documentation.theme.js - Documentation-focused with enhanced spacing and colors

Creating a Custom Theme

Create a theme file that exports a theme object:

// my-theme.theme.js
export default {
  components: {
    propsTable: {
      styles: {
        table: 'border-collapse border border-gray-300',
        header: 'bg-blue-100 font-bold',
        row: 'hover:bg-gray-50',
        cell: 'px-4 py-2',
      },
    },
    callout: {
      styles: {
        container: 'p-4 rounded-lg border-l-4',
        warning: 'bg-yellow-50 border-yellow-400',
        info: 'bg-blue-50 border-blue-400',
      },
    },
    codeBlock: {
      styles: {
        pre: 'bg-gray-900 text-gray-100 rounded-lg p-4',
        code: 'font-mono text-sm',
      },
      props: {
        showLineNumbers: true,
      },
    },
  },
  global: {
    fontFamily: 'Inter, sans-serif',
    accentColor: '#3b82f6',
    borderRadius: '8px',
  },
};

import { loadTheme } from '@tapestrylab/template';

const theme = await loadTheme('./my-theme.theme.js');

Extending Built-in Themes

Themes use shallow merge at the component level. To extend a built-in theme, manually spread the properties you want to preserve:

// extended-theme.theme.js
import defaultTheme from '@tapestrylab/template/themes/default.theme.js';

export default {
  ...defaultTheme,
  components: {
    ...defaultTheme.components,
    // Replace entire propsTable config
    propsTable: {
      styles: {
        table: 'my-custom-table-class',
        header: 'my-custom-header-class',
      },
    },
    // Selectively override nested properties
    tabs: {
      ...defaultTheme.components.tabs,
      styles: {
        ...defaultTheme.components.tabs.styles,
        activeTab: 'border-b-2 border-brand-primary', // Override just activeTab
      },
    },
  },
  global: {
    ...defaultTheme.global,
    accentColor: '#ff6b6b', // Override just accent color
  },
};

Theme Merge Behavior

Important: Custom themes use shallow merge at the component level:

• Setting components.propsTable replaces the entire propsTable configuration
• To preserve nested properties, manually spread them (see example above)
• Precedence: custom theme > default theme

Why shallow merge?

• Predictable: You always know exactly what configuration is active
• Explicit: No hidden merging behavior
• Type-safe: Easier for TypeScript to validate
• Standard pattern: Same pattern used by React props, Tailwind, ESLint

When to use each pattern:

Pattern	Use Case
Built-in theme as-is	Quick start, standard styling
Custom theme from scratch	Complete control, brand new design
Extend with spreading	Tweak specific properties, preserve defaults
Deep merge utility	Prefer automatic merging over manual spreading

Deep Merge Utility (Optional)

If you prefer automatic deep merging over manual spreading, use the deepMergeThemes() helper:

import { deepMergeThemes } from '@tapestrylab/template';
import defaultTheme from '@tapestrylab/template/themes/default.theme.js';

const customTheme = deepMergeThemes(defaultTheme, {
  components: {
    propsTable: {
      styles: {
        header: 'bg-brand-primary', // Only overrides header, preserves other styles
      },
    },
  },
  global: {
    accentColor: '#ff6b6b', // Only overrides accentColor, preserves other global settings
  },
});

Trade-offs:

• ✅ Less verbose than manual spreading
• ✅ Automatically preserves nested properties
• ⚠️ Less explicit - harder to see exactly what's being merged
• ⚠️ May merge more than intended if you're not careful

Available Component Styles

Each component type supports different style keys:

propsTable: table, header, row, cell tabs: container, tabList, tab, activeTab, panel accordion: container, item, header, content callout: container, icon, content codeBlock: container, pre, code

Built-in Templates

• component-docs.taptpl.json - Full documentation with props, examples, and metadata
• minimal.taptpl.json - Minimal docs with just name and props
• api-reference.taptpl.json - API-focused documentation

Built-in Themes

• default.theme.js - Default styling
• minimal.theme.js - Minimal styling
• documentation.theme.js - Documentation-focused styling

Block Types

Text Blocks

• heading - H1-H6 headings
• paragraph - Text content
• divider - Horizontal rule

Code Blocks

• code - Single code block
• codeBlocks - Multiple code blocks from data source

Data Blocks

• propsTable - Component props table
• apiReference - API documentation

Interactive Blocks

• tabs - Tabbed content
• accordion - Collapsible sections
• callout - Info/warning/error boxes

Relationship Blocks

• usageSites - Where component is used
• dependencyList - Component dependencies
• dependents - Components that depend on this one
• linkList - Related links

License

MIT