@conduction/docusaurus-preset 3.19.0 → 3.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.19.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/SetupSteps/SetupSteps.jsx

@@ -0,0 +1,81 @@
+/**
+ * <SetupSteps /> + <SetupStep />
+ *
+ * Vertical numbered-step list for docs setup/install/walkthrough
+ * sections and editorial action prompts. A small orange hex with a
+ * white number sits on the left of each row; bold title + one short
+ * body paragraph sit on the right.
+ *
+ * Distinct from <HowSteps />, which renders a 3-up card row for
+ * marketing surfaces (How install works, How to get help, …).
+ * SetupSteps lives in body prose where steps are sequential and
+ * detailed, and the list reads top to bottom.
+ *
+ * Numbers are auto-assigned in document order. Pass `start` to
+ * resume after a break (e.g. a continued procedure split across
+ * sections).
+ *
+ * Usage:
+ *
+ *   <SetupSteps title="Setup" lede="Numbered steps you read top to bottom.">
+ *     <SetupStep title="Add an xWiki source">
+ *       Open *Integrations → Sources → New source*, paste the base URL.
+ *     </SetupStep>
+ *     <SetupStep title="Pick the spaces to index">
+ *       Per source, choose one or more xWiki spaces.
+ *     </SetupStep>
+ *     <SetupStep title="Verify">
+ *       Open the app's chat sidebar and ask a matching question.
+ *     </SetupStep>
+ *   </SetupSteps>
+ *
+ *   // Editorial / action-prompt use, no h2 above the list:
+ *   <SetupSteps title={null}>
+ *     <SetupStep title="Call Nextcloud by its proper name.">
+ *       In tenders, in policy documents, in architecture diagrams.
+ *     </SetupStep>
+ *     ...
+ *   </SetupSteps>
+ *
+ * Mirrors preview/components/setup-steps.html.
+ */
+
+import React, {Children, cloneElement, isValidElement} from 'react';
+import styles from './SetupSteps.module.css';
+
+export function SetupStep({number, title, children, className}) {
+  const composed = [styles.row, className].filter(Boolean).join(' ');
+  return (
+    <div className={composed}>
+      {number != null && <div className={styles.num}>{number}</div>}
+      {/* div not p: MDX may wrap inline children in its own <p>,
+          which would be invalid nested inside another <p>. */}
+      <div className={styles.body}>
+        {title && <span className={styles.bodyTitle}>{title}</span>}
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export default function SetupSteps({
+  title,
+  lede,
+  start = 1,
+  children,
+  className,
+}) {
+  const numbered = Children.map(children, (child, i) => {
+    if (!isValidElement(child)) return child;
+    if (child.props.number != null) return child;
+    return cloneElement(child, {number: start + i});
+  });
+  const composed = [styles.wrap, className].filter(Boolean).join(' ');
+  return (
+    <section className={composed}>
+      {title && <h2 className={styles.title}>{title}</h2>}
+      {lede && <p className={styles.lede}>{lede}</p>}
+      {numbered}
+    </section>
+  );
+}

package/src/components/SetupSteps/SetupSteps.module.css

@@ -0,0 +1,82 @@
+/**
+ * <SetupSteps /> + <SetupStep /> styles. Vertical numbered-row
+ * pattern for docs setup/install/walkthrough sections and editorial
+ * action lists. Small orange hex with a white number on the left,
+ * bold title + one short body paragraph on the right.
+ *
+ * Distinct from <HowSteps /> which is a 3-up card row for marketing
+ * surfaces. SetupSteps lives inside body prose, so steps stack
+ * vertically and read like sentences in a list.
+ *
+ * Mirrors preview/components/setup-steps.html.
+ */
+
+.wrap {
+  margin: var(--space-7) 0;
+  font-family: var(--conduction-typography-font-family-body);
+}
+
+.title {
+  font-size: 28px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--c-cobalt-900);
+  margin: 0 0 var(--space-3);
+  line-height: 1.2;
+}
+
+.lede {
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--c-cobalt-700);
+  margin: 0 0 var(--space-5);
+  max-width: 60ch;
+}
+
+.row {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-4);
+  margin: var(--space-4) 0;
+}
+
+.num {
+  width: 36px;
+  height: 42px;
+  clip-path: var(--hex-pointy-top);
+  background: var(--c-orange-knvb);
+  color: white;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+.body {
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--c-cobalt-700);
+}
+
+.body strong,
+.bodyTitle {
+  display: block;
+  margin-bottom: 4px;
+  color: var(--c-cobalt-900);
+  font-size: 17px;
+  font-weight: 600;
+}
+
+.body p {
+  margin: 0;
+}
+
+.body code {
+  background: var(--c-cobalt-50);
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 13px;
+  color: var(--c-cobalt-900);
+}

package/src/components/index.js

@@ -48,6 +48,7 @@ export {default as ReferenceCard, ReferenceGrid} from './ReferenceCard/Reference
 export {default as PairCard, PairRow} from './PairCard/PairCard.jsx';
 export {default as FeatureList, FeatureItem} from './FeatureList/FeatureList.jsx';
 export {default as HowSteps, HowStep} from './HowSteps/HowSteps.jsx';
+export {default as SetupSteps, SetupStep} from './SetupSteps/SetupSteps.jsx';
 export {default as FAQ, FAQItem} from './FAQ/FAQ.jsx';
 export {default as EmployeeCard, TeamGrid} from './EmployeeCard/EmployeeCard.jsx';
 export {default as DetailHero} from './DetailHero/DetailHero.jsx';
@@ -88,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;