Theme Config API

interface ThemeConfig {
  prefix: string;       // BEM prefix, e.g., 'rf' → .rf-hint
  tokenPrefix: string;  // CSS variable prefix, e.g., '--rf' → --rf-color-text
  icons: Record<string, Record<string, string>>;  // SVG icons by group and variant
  runes: Record<string, RuneConfig>;               // Per-rune configuration
}

Grid: { block: 'grid' }
// → class="rf-grid"

modifiers: {
  hintType: { source: 'meta', default: 'note' },
  align: { source: 'meta', default: 'center' },
}

<!-- Before transform — field data rides the data-rune-fields bag (camelCase keys) -->
<div data-rune="hint" data-rune-fields='{"hintType":"warning"}'>
  <p>Be careful!</p>
</div>

<!-- After transform -->
<div class="rf-hint rf-hint--warning" data-rune="hint" data-hint-type="warning">
  <!-- bag consumed, structural elements injected -->
  <p>Be careful!</p>
</div>

// Hint config
contextModifiers: { 'Hero': 'in-hero', 'Feature': 'in-feature' }

// When Hint is inside a Hero:
// class="rf-hint rf-hint--note rf-hint--in-hero"

// FeaturedTier shares the 'tier' block but always gets --featured
FeaturedTier: { block: 'tier', staticModifiers: ['featured'] }
// → class="rf-tier rf-tier--featured"

metaFields: {
  difficulty: {
    metaType: 'category',
    label: 'Difficulty',
    condition: 'difficulty',
    sentimentMap: { easy: 'positive', medium: 'neutral', hard: 'caution' },
  },
}

blocks: {
  metadata: { fields: ['prepTime', 'cookTime', 'servings', 'difficulty'], layout: 'definition-list' },
  eyebrow: { fields: ['plotType', { field: 'structure', align: 'end' }], layout: 'bar' },
}

layout: {
  root: ['media', 'content'],
  content: { tag: 'div', children: ['eyebrow', 'body', 'footer'] },
  preamble: { tag: 'header', children: ['eyebrow', 'headline', 'blurb'] },
}

variants: {
  'media-position': {
    cover: {
      layout: {
        root: ['cover-band', 'body'],
        'cover-band': { tag: 'div', children: ['media', 'preamble'] },
      },
    },
  },
}

structure: {
  header: {
    tag: 'div',
    before: true,
    children: [
      { tag: 'span', ref: 'icon', icon: { group: 'hint', variant: 'hintType' } },
      { tag: 'span', ref: 'title', metaText: 'hintType' },
    ],
  },
}

// Recipe config
contentWrapper: { tag: 'div', ref: 'content' }

// Output: recipe's structural header comes first, then content is wrapped
// <div class="rf-recipe">
//   <div class="rf-recipe__meta">...</div>       ← structure (before)
//   <div class="rf-recipe__content">              ← contentWrapper
//     <ul>ingredients...</ul>
//     <ol>steps...</ol>
//   </div>
// </div>

// AccordionItem config
autoLabel: { name: 'header' }

// A child with tag name "name" gets data-name="header"
// → class="rf-accordion-item__header"

// Details config
autoLabel: { summary: 'summary' }

// The <summary> child gets data-name="summary"
// → class="rf-details__summary"

styles: { columns: '--sb-columns' }
// With columns=3: style="--sb-columns: 3"

styles: {
  columns: {
    prop: 'grid-template-columns',
    template: 'repeat({}, 1fr)'
  }
}
// With columns=3: style="grid-template-columns: repeat(3, 1fr)"

Accordion: { block: 'accordion', defaultDensity: 'full' }
Details: { block: 'details', defaultDensity: 'compact' }
Breadcrumb: { block: 'breadcrumb', defaultDensity: 'minimal' }

Budget: {
  block: 'budget',
  sections: { header: 'header', title: 'title', footer: 'footer' },
}

Figure: { block: 'figure', mediaSlots: { media: 'cover' } }

Work: { block: 'work', checklist: true }

Steps: { block: 'steps', sequence: 'connected' }

Timeline: {
  block: 'timeline',
  sequence: 'connected',
  sequenceDirection: { fromModifier: 'direction', default: 'vertical' },
}

AccordionItem: { block: 'accordion-item', parent: 'Accordion' }

Figure: { block: 'figure', frameTarget: 'self' }

BreadcrumbItem: { block: 'breadcrumb-item', parent: 'Breadcrumb', requiresParent: 'Breadcrumb' }

Hero: { block: 'hero', defaultWidth: 'full' }

Grid: { block: 'grid', childDensity: 'compact' }
Backlog: { block: 'backlog', childDensity: 'minimal' }

Hint: {
  block: 'hint',
  editHints: { icon: 'none', title: 'inline' },
}

Sandbox: { block: 'sandbox', rootAttributes: { 'data-interactive': 'true' } }

Comparison: {
  block: 'comparison',
  projection: {
    hide: ['meta'],   // drop elements by data-name (the only retained op)
  },
}

modifiers: {
  method: {
    source: 'meta',
    default: 'GET',
    valueMap: { GET: 'read', POST: 'write', PUT: 'write', DELETE: 'danger' },
    mapTarget: 'intent',
  },
}
// Emits: data-method="GET" data-intent="read"

postTransform(node, ctx) {
  return {
    ...node,
    attributes: {
      ...node.attributes,
      'data-custom': `cols-${ctx.modifiers.columns}`,
    },
  };
}

interface StructureEntry {
  tag: string;                // HTML tag name ('div', 'span', 'a', etc.)
  ref?: string;               // Sets data-name (overrides the structure key)
  before?: boolean;           // Insert before content children (default: after)
  children?: (string | StructureEntry)[];  // Nested entries or text

  // Content
  metaText?: string;          // Inject resolved modifier value as text
  icon?: { group: string; variant: string };  // Icon from config.icons

  // Conditional
  condition?: string;         // Only render if named modifier is truthy
  conditionAny?: string[];    // Only render if any named modifier is truthy

  // Text transforms
  transform?: 'duration' | 'uppercase' | 'capitalize';
  textPrefix?: string;        // Prepend to metaText value
  textSuffix?: string;        // Append to metaText value

  // Labels
  label?: string;             // Emits <span data-meta-label>Label</span> child
  labelHidden?: boolean;      // Label visually hidden but accessible (sr-only)

  // Metadata dimensions (see Dimensions page)
  metaType?: 'status' | 'category' | 'quantity' | 'temporal' | 'tag' | 'id';
  sentimentMap?: Record<string, 'positive' | 'negative' | 'caution' | 'neutral'>;

  // Repetition — generate copies of a template element
  repeat?: {
    count: string;            // Modifier name providing the total count
    max?: number;             // Cap to prevent runaway generation (default 10)
    filled?: string;          // Modifier name for how many are "filled"
    element: StructureEntry;  // Template for each generated element
    filledElement?: StructureEntry;  // Optional template for filled elements
  };

  // Attributes — literal strings, or references to a modifier / page data
  attrs?: Record<string, string | { fromModifier: string } | { fromPageData: string }>;
}

Api: {
  block: 'api',
  contentWrapper: { tag: 'div', ref: 'body' },
  modifiers: {
    method: { source: 'meta', default: 'GET' },
    path: { source: 'meta' },
    auth: { source: 'meta' },
  },
  structure: {
    header: {
      tag: 'div', before: true,
      children: [
        { tag: 'span', ref: 'method', metaText: 'method' },
        { tag: 'code', ref: 'path', metaText: 'path' },
        { tag: 'span', ref: 'auth', metaText: 'auth', condition: 'auth' },
      ],
    },
  },
}

<div class="rf-api rf-api--GET" data-method="GET" data-rune="api">
  <div data-name="header" class="rf-api__header">
    <span data-name="method" class="rf-api__method">GET</span>
    <code data-name="path" class="rf-api__path">/api/users</code>
    <!-- auth span only present if auth modifier has a value -->
  </div>
  <div data-name="body" class="rf-api__body">
    <!-- content children -->
  </div>
</div>

{ tag: 'span', ref: 'auth', metaText: 'auth', condition: 'auth' }
// Only renders if the 'auth' modifier is present

{
  tag: 'div', ref: 'meta', before: true,
  conditionAny: ['prepTime', 'cookTime', 'servings', 'difficulty'],
  children: [...]
}
// Only renders if any of those modifiers has a value

{
  tag: 'a', ref: 'register', condition: 'url',
  attrs: { href: { fromModifier: 'url' } },
  children: ['Register'],
}
// → <a href="https://example.com" class="rf-event__register">Register</a>

{
  tag: 'div', ref: 'rating',
  repeat: {
    count: 'maxRating',   // modifier holding the total
    filled: 'rating',     // modifier holding how many are filled
    element: { tag: 'span', ref: 'star' },
  },
}
// With maxRating=5, rating=3:
// Produces 5 <span> elements, first 3 with data-filled="true"

{ tag: 'span', ref: 'meta-item', metaText: 'prepTime',
  transform: 'duration', textPrefix: 'Prep: ' }
// With prepTime="PT45M": "Prep: 45m"

{ tag: 'span', ref: 'meta-item', metaText: 'prepTime',
  label: 'Prep:', metaType: 'temporal' }

{ tag: 'span', ref: 'badge', metaText: 'difficulty',
  metaType: 'category',
  sentimentMap: { easy: 'positive', medium: 'neutral', hard: 'caution' } }

<span data-meta-type="category"
      data-meta-sentiment="positive" data-difficulty="easy">
  easy
</span>

import { baseConfig } from '@refrakt-md/runes';
import { mergeThemeConfig } from '@refrakt-md/transform';

const myConfig = mergeThemeConfig(baseConfig, {
  // Override the BEM prefix (optional)
  prefix: 'my',

  // Add icon SVGs (merged by group)
  icons: {
    hint: {
      note: '<svg>...</svg>',
      warning: '<svg>...</svg>',
    },
  },

  // Override specific rune configs (shallow merge per rune)
  runes: {
    Hint: {
      // This replaces only the 'modifiers' field of the Hint config
      // All other fields (block, contextModifiers, structure) are preserved
      modifiers: {
        hintType: { source: 'meta', default: 'info' }, // different default
      },
    },
  },
});

Grid: { block: 'grid' }

Hint: {
  block: 'hint',
  modifiers: { hintType: { source: 'meta', default: 'note' } },
  contextModifiers: { 'Hero': 'in-hero', 'Feature': 'in-feature' },
  structure: {
    header: {
      tag: 'div', before: true,
      children: [
        { tag: 'span', ref: 'icon', icon: { group: 'hint', variant: 'hintType' } },
        { tag: 'span', ref: 'title', metaText: 'hintType' },
      ],
    },
  },
}

Recipe: {
  block: 'recipe',
  defaultDensity: 'full',
  sequence: 'numbered',
  sections: { preamble: 'preamble', headline: 'title', blurb: 'description', media: 'media' },
  mediaSlots: { media: 'cover' },
  modifiers: {
    'media-position': { source: 'meta', default: 'top', noBemClass: true },
    prepTime: { source: 'meta', noBemClass: true },
    cookTime: { source: 'meta', noBemClass: true },
    servings: { source: 'meta', noBemClass: true },
    difficulty: { source: 'meta', default: 'medium' },
  },
  metaFields: {
    prepTime: { metaType: 'temporal', label: 'Prep', condition: 'prepTime', transform: 'duration' },
    cookTime: { metaType: 'temporal', label: 'Cook', condition: 'cookTime', transform: 'duration' },
    servings: { metaType: 'quantity', label: 'Serves', condition: 'servings' },
    difficulty: {
      metaType: 'category', label: 'Difficulty', condition: 'difficulty',
      sentimentMap: { easy: 'positive', medium: 'neutral', hard: 'caution' },
    },
  },
  blocks: {
    metadata: { fields: ['prepTime', 'cookTime', 'servings', 'difficulty'], layout: 'definition-list' },
  },
  layout: {
    root: ['media', 'content'],
    content: { tag: 'div', children: ['preamble', 'metadata', 'ingredients', 'steps', 'tips'] },
    preamble: { tag: 'header', children: ['eyebrow', 'headline', 'blurb'] },
  },
}