feat(site): feature and preset reference UI + docs integration (#1258)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

site/src/utils/featureReferenceModel.js

@@ -0,0 +1,59 @@
+/**
+ * Centralized feature API reference subsection definitions.
+ *
+ * Mirrors componentReferenceModel.js for feature APIs. Produces heading/id data
+ * consumed by both FeatureReference.astro and remarkConditionalHeadings.
+ *
+ * Structure:
+ *   ## API Reference (H2)
+ *   ### State (H3) — if feature has state properties
+ *   ### Actions (H3) — if feature has action methods
+ */
+
+function hasEntries(value) {
+  return Object.keys(value ?? {}).length > 0;
+}
+
+export function createFeatureReferenceModel(name, ref) {
+  if (!ref) return null;
+
+  const sections = [];
+
+  if (hasEntries(ref.state)) {
+    sections.push({ key: 'state', title: 'State', id: 'state', depth: 3 });
+  }
+
+  if (hasEntries(ref.actions)) {
+    sections.push({ key: 'actions', title: 'Actions', id: 'actions', depth: 3 });
+  }
+
+  return {
+    name,
+    description: ref.description,
+    heading: { id: 'api-reference', depth: 2, text: 'API Reference' },
+    sections,
+    data: ref,
+  };
+}
+
+export function buildFeatureReferenceTocHeadings(model) {
+  if (!model) return [];
+
+  const headings = [
+    {
+      depth: model.heading.depth,
+      text: model.heading.text,
+      slug: model.heading.id,
+    },
+  ];
+
+  for (const section of model.sections) {
+    headings.push({
+      depth: section.depth,
+      text: section.title,
+      slug: section.id,
+    });
+  }
+
+  return headings;
+}

site/src/utils/remarkConditionalHeadings.js

@@ -4,10 +4,12 @@ import { fileURLToPath } from 'node:url';
 import { kebabCase } from 'es-toolkit/string';
 import GithubSlugger from 'github-slugger';
 import { buildComponentReferenceTocHeadings, createComponentReferenceModel } from './componentReferenceModel';
+import { buildFeatureReferenceTocHeadings, createFeatureReferenceModel } from './featureReferenceModel';
 import { buildUtilReferenceTocHeadings, createUtilReferenceModel } from './utilReferenceModel';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const COMPONENT_REF_DIR = path.resolve(__dirname, '../content/generated-component-reference');
+const FEATURE_REF_DIR = path.resolve(__dirname, '../content/generated-feature-reference');
 const UTIL_REF_DIR = path.resolve(__dirname, '../content/generated-util-reference');
 
 function readComponentRefJson(componentName) {
@@ -65,6 +67,8 @@ export default function remarkConditionalHeadings() {
           return;
         } else if (node.name === 'ComponentReference') {
           injectComponentReferenceHeadings(node, headingsWithMetadata, reservedSlugs);
+        } else if (node.name === 'FeatureReference') {
+          injectFeatureReferenceHeadings(node, headingsWithMetadata, reservedSlugs);
         } else if (node.name === 'UtilReference') {
           injectUtilReferenceHeadings(node, headingsWithMetadata, reservedSlugs);
           return;
@@ -148,6 +152,32 @@ function injectComponentReferenceHeadings(node, headingsWithMetadata, reservedSl
   }
 }
 
+function readFeatureRefJson(featureName) {
+  const filePath = path.join(FEATURE_REF_DIR, `${featureName}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function injectFeatureReferenceHeadings(node, headingsWithMetadata, reservedSlugs) {
+  const featureAttr = node.attributes?.find((a) => a.name === 'feature');
+  const featureName = typeof featureAttr?.value === 'string' ? featureAttr.value : null;
+  if (!featureName) return;
+
+  const json = readFeatureRefJson(featureName);
+  if (!json) return;
+
+  const featureModel = createFeatureReferenceModel(featureName, json);
+  const featureHeadings = buildFeatureReferenceTocHeadings(featureModel);
+
+  headingsWithMetadata.push(...featureHeadings);
+  for (const heading of featureHeadings) {
+    reservedSlugs.add(heading.slug);
+  }
+}
+
 function readUtilRefJson(slug) {
   const filePath = path.join(UTIL_REF_DIR, `${slug}.json`);
   try {