@conduction/docusaurus-preset 3.20.0 → 3.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },

package/src/components/FeaturesPage/FeaturesPage.jsx

@@ -0,0 +1,57 @@
+/**
+ * <FeaturesPage />
+ *
+ * Route component used by the `conduction-features-page` plugin. Renders
+ * the list of implemented/reviewed capabilities extracted from
+ * `openspec/specs/` into `docs/features.json` (regenerated by the
+ * org-wide Features Extract workflow stage).
+ *
+ * Reuses the brand `<FeatureGrid>` for the actual list — every entry maps
+ * to a single `<FeatureItem>` with status `stable` (the extractor only
+ * emits specs whose frontmatter declares `implemented` or `reviewed`,
+ * both of which are stable by definition).
+ *
+ * Receives one prop module from the plugin via `addRoute({modules})`:
+ *
+ *   data: {
+ *     features: Array<{slug, title, summary, docsUrl}>,
+ *     title:    string,
+ *     intro:    string | null,
+ *   }
+ *
+ * Sites that want a different page chrome can swizzle the plugin route
+ * to register their own component; this default is intentionally minimal
+ * (one heading, one optional intro paragraph, the grid).
+ */
+
+import React from 'react';
+import Layout from '@theme/Layout';
+import FeatureGrid from '../FeatureGrid/FeatureGrid.jsx';
+
+export default function FeaturesPage({data}) {
+  const {features = [], title = 'Features', intro = null} = data || {};
+
+  const items = features.map((f) => ({
+    label: f.title || f.slug,
+    tip: f.summary || '',
+    status: 'stable',
+    href: f.docsUrl || undefined,
+  }));
+
+  return (
+    <Layout
+      title={title}
+      description={intro || `Capabilities shipped in this app, sourced from openspec/specs/.`}
+    >
+      <main className="container margin-vert--lg">
+        <h1>{title}</h1>
+        {intro && <p>{intro}</p>}
+        {items.length === 0 ? (
+          <p>No features documented yet.</p>
+        ) : (
+          <FeatureGrid items={items} legend />
+        )}
+      </main>
+    </Layout>
+  );
+}

package/src/components/index.js

@@ -89,6 +89,7 @@ export {default as McpToolShelf} from './McpToolShelf/McpToolShelf.jsx';
 export {default as ExternalAppShelf} from './ExternalAppShelf/ExternalAppShelf.jsx';
 export {default as WidgetShelf} from './WidgetShelf/WidgetShelf.jsx';
 export {default as FeatureGrid, FeatureGridGroup, FeatureItem as FeatureGridItem} from './FeatureGrid/FeatureGrid.jsx';
+export {default as FeaturesPage} from './FeaturesPage/FeaturesPage.jsx';
 
 /* Academy components (Batch 4). Card-and-chrome patterns for
    academy.conduction.nl: a single feed of blogs, guides, case studies,

package/src/index.js

@@ -683,6 +683,17 @@ function createConfig(opts) {
         require.resolve('./plugins/indexnow.js'),
         opts.indexnow || {},
       ],
+      /* The Features Page plugin registers a `/features` route backed by
+         the consuming app's `docs/features.json` (regenerated from
+         openspec/specs/ by the org-wide Features Extract workflow stage).
+         No-ops when features.json is absent, so it's safe to enable
+         across the fleet ahead of full adoption. Sites opt out via
+         opts.featuresPage = { disable: true } or override the page
+         title / intro / route path. */
+      [
+        require.resolve('./plugins/features-page.js'),
+        opts.featuresPage || {},
+      ],
       ...(opts.plugins || []),
     ],
   };

package/src/plugins/features-page.js

@@ -0,0 +1,89 @@
+/**
+ * @conduction/docusaurus-preset/plugins/features-page
+ *
+ * Adds a `/features` route to every Conduction docs site, backed by the
+ * `docs/features.json` artefact regenerated from `openspec/specs/` by the
+ * org-wide Features Extract workflow stage
+ * (https://github.com/ConductionNL/.github/blob/main/.github/workflows/quality.yml).
+ *
+ * The route renders the brand `<FeaturesPage />` component, which in turn
+ * maps each entry to a `<FeatureItem>` inside `<FeatureGrid>`. Every entry
+ * is rendered with status `stable` (the extractor only emits specs whose
+ * frontmatter declares `status: implemented` or `status: reviewed`, both
+ * of which map to the mint hex bullet).
+ *
+ * Options:
+ *   path         string  route path (default '/features')
+ *   featuresFile string  path to features.json (default 'features.json',
+ *                        resolved against `siteDir` — i.e. the directory
+ *                        holding `docusaurus.config.js`)
+ *   title        string  page title (default 'Features')
+ *   intro        string  optional intro paragraph rendered above the grid
+ *   disable      boolean skip the plugin entirely (the consuming site can
+ *                        keep the entry in `createConfig({featuresPage:
+ *                        {disable: true}})` instead of yanking the plugin)
+ *
+ * No-op when the resolved `featuresFile` doesn't exist on disk. This
+ * keeps the plugin safe to enable across the fleet before every app has
+ * adopted the workflow stage that produces the file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function loadFeatures(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    const raw = fs.readFileSync(absPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return null;
+    return parsed;
+  } catch (e) {
+    return null;
+  }
+}
+
+function featuresPagePlugin(context, options = {}) {
+  if (options.disable === true) return {name: 'conduction-features-page'};
+
+  const featuresFile = options.featuresFile || 'features.json';
+  const absPath = path.isAbsolute(featuresFile)
+    ? featuresFile
+    : path.resolve(context.siteDir, featuresFile);
+
+  const features = loadFeatures(absPath);
+  if (features === null) {
+    /* Plugin is enabled but the consuming site hasn't produced
+       features.json yet — most likely the Features Extract workflow
+       stage hasn't run, or the app has no openspec/specs/ entries with
+       a publishable status. Stay silent rather than build-fail. */
+    return {name: 'conduction-features-page'};
+  }
+
+  const routePath = options.path || '/features';
+  const title = options.title || 'Features';
+  const intro = options.intro || null;
+
+  return {
+    name: 'conduction-features-page',
+
+    async loadContent() {
+      return {features, title, intro};
+    },
+
+    async contentLoaded({content, actions}) {
+      const dataPath = await actions.createData(
+        'conduction-features-page.json',
+        JSON.stringify(content)
+      );
+      actions.addRoute({
+        path: routePath,
+        component: require.resolve('../components/FeaturesPage/FeaturesPage.jsx'),
+        exact: true,
+        modules: {data: dataPath},
+      });
+    },
+  };
+}
+
+module.exports = featuresPagePlugin;