@conduction/docusaurus-preset 1.5.1 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },
@@ -10,6 +10,7 @@
     ".": "./src/index.js",
     "./components": "./src/components/index.js",
     "./data": "./src/data/app-downloads.js",
+    "./data/apps-registry": "./src/data/apps-registry.js",
     "./css/brand.css": "./src/css/brand.css",
     "./css/tokens.css": "./src/css/tokens.css",
     "./theme": "./src/theme.js",

package/src/components/AppCrossLinks/AppCrossLinks.jsx

@@ -0,0 +1,148 @@
+/**
+ * <AppCrossLinks />
+ *
+ * Cross-links between the three surfaces a visitor lands on while
+ * learning about a Conduction app:
+ *
+ *   1. /apps/<slug>                              product page
+ *   2. https://docs.conduction.nl/<slug>         documentation
+ *   3. /academy?app=<slug>                       academy filtered
+ *
+ * URLs come from the shared apps-registry so all three surfaces stay
+ * in lockstep without per-page constants.
+ *
+ * Two variants:
+ *   - rail   sticky right-rail card. Used on /apps/<slug>.mdx, paired
+ *            with a 2-col grid (see partners/<slug>.mdx for the same
+ *            layout pattern).
+ *   - inline page-bottom block, three link tiles in a row. Used at
+ *            the bottom of an academy post and on each app's docs
+ *            overview page (or auto-injected via the DocItemFooter
+ *            swizzle when the docs site sets themeConfig.conduction
+ *            .appId in docusaurus.config.js).
+ *
+ * `surface` tells the component which row to omit, so we never link
+ * the user to the page they're already on:
+ *   - surface="product"  hides the "Open product page" row
+ *   - surface="academy"  hides the "Read in the academy" row
+ *   - surface="docs"     hides the "Read the documentation" row
+ *   - surface omitted    all three rows render
+ *
+ * Usage:
+ *
+ *   import {AppCrossLinks} from '@conduction/docusaurus-preset/components';
+ *
+ *   <AppCrossLinks
+ *     variant="rail"
+ *     apps={['opencatalogi']}
+ *     surface="product"
+ *   />
+ *
+ *   <AppCrossLinks
+ *     variant="inline"
+ *     apps={frontMatter.apps}
+ *     surface="academy"
+ *   />
+ */
+
+import React from 'react';
+import {APPS_REGISTRY} from '../../data/apps-registry';
+import styles from './AppCrossLinks.module.css';
+
+const ROWS = [
+  {key: 'product', surfaceKey: 'product', hrefKey: 'productHref', label: 'Open product page',   hint: 'Capabilities, pricing, install link'},
+  {key: 'docs',    surfaceKey: 'docs',    hrefKey: 'docsHref',    label: 'Read the documentation', hint: 'Reference, guides, API'},
+  {key: 'academy', surfaceKey: 'academy', hrefKey: 'academyHref', label: 'Read in the academy',    hint: 'Tutorials, case studies, blog'},
+];
+
+const ICONS = {
+  product: (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M3 7l9-4 9 4-9 4-9-4z" />
+      <path d="M3 12l9 4 9-4" />
+      <path d="M3 17l9 4 9-4" />
+    </svg>
+  ),
+  docs: (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+      <path d="M14 2v6h6" />
+      <path d="M9 13h6M9 17h6M9 9h2" />
+    </svg>
+  ),
+  academy: (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M3 7l9-4 9 4-9 4-9-4z" />
+      <path d="M5 11v5a7 7 0 0 0 14 0v-5" />
+      <path d="M21 7v5" />
+    </svg>
+  ),
+};
+
+function AppCard({app, surface, variant}) {
+  const reg = APPS_REGISTRY[app];
+  if (!reg) return null;
+
+  const rows = ROWS.filter((row) => row.surfaceKey !== surface);
+  const tagId = `app-cross-links-${reg.slug}`;
+
+  return (
+    <div className={styles.card} aria-labelledby={tagId}>
+      <div className={styles.head}>
+        <span className={styles.hex} aria-hidden="true" />
+        <div>
+          <p className={styles.eyebrow}>About this app</p>
+          <h4 className={styles.title} id={tagId}>{reg.name}</h4>
+        </div>
+      </div>
+
+      <ul className={styles.rows}>
+        {rows.map((row) => (
+          <li key={row.key} className={styles.row}>
+            <a
+              href={reg[row.hrefKey]}
+              className={styles.rowLink}
+              target={row.key === 'docs' ? '_blank' : undefined}
+              rel={row.key === 'docs' ? 'noopener noreferrer' : undefined}
+            >
+              <span className={styles.rowIcon} aria-hidden="true">{ICONS[row.key]}</span>
+              <span className={styles.rowText}>
+                <span className={styles.rowLabel}>{row.label}</span>
+                <span className={styles.rowHint}>{row.hint}</span>
+              </span>
+              <span className={styles.rowArrow} aria-hidden="true">→</span>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export default function AppCrossLinks({
+  apps = [],
+  variant = 'inline',
+  surface,
+  className,
+  heading,
+}) {
+  const known = apps.filter((slug) => APPS_REGISTRY[slug]);
+  if (known.length === 0) return null;
+
+  const composed = [
+    styles.root,
+    styles[`variant-${variant}`],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <aside className={composed} aria-label="Related app links">
+      {heading && <h3 className={styles.heading}>{heading}</h3>}
+      <div className={styles.list}>
+        {known.map((slug) => (
+          <AppCard key={slug} app={slug} surface={surface} variant={variant} />
+        ))}
+      </div>
+    </aside>
+  );
+}

package/src/components/AppCrossLinks/AppCrossLinks.module.css

@@ -0,0 +1,178 @@
+/**
+ * <AppCrossLinks /> styles. Rail variant mirrors PartnerSidecard's
+ * card chrome (white card, cobalt-100 hairline, 1-shadow). Inline
+ * variant lays the same cards out horizontally as a page-bottom
+ * cross-link block on academy posts and docs overview pages.
+ */
+
+.root {
+  font-family: var(--conduction-typography-font-family-body);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+
+.heading {
+  font-size: 22px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--c-cobalt-900);
+  margin: 0;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+
+.variant-rail {
+  width: 100%;
+  max-width: 320px;
+  position: sticky;
+  top: var(--space-8);
+}
+
+.variant-inline .list {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: var(--space-4);
+}
+
+.card {
+  background: white;
+  border: 1px solid var(--c-cobalt-100);
+  border-radius: var(--radius-lg);
+  padding: var(--space-5);
+  box-shadow: var(--shadow-1);
+}
+
+/* ---------- Card head ---------- */
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  margin-bottom: var(--space-4);
+}
+
+.hex {
+  width: 28px;
+  height: 32px;
+  clip-path: var(--hex-pointy-top);
+  background: var(--c-blue-cobalt);
+  flex-shrink: 0;
+}
+
+.eyebrow {
+  font-family: var(--conduction-typography-font-family-code);
+  font-size: 10px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--c-cobalt-400);
+  margin: 0 0 2px;
+  font-weight: 600;
+}
+
+.title {
+  font-size: 17px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--c-cobalt-900);
+  margin: 0;
+  line-height: 1.2;
+}
+
+/* ---------- Rows ---------- */
+
+.rows {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.row {
+  margin: 0;
+}
+
+.rowLink {
+  display: grid;
+  grid-template-columns: 24px 1fr auto;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3);
+  border-radius: var(--radius-md);
+  background: var(--c-cobalt-50);
+  color: var(--c-cobalt-900);
+  text-decoration: none;
+  transition: background 160ms ease, color 160ms ease, transform 160ms ease;
+}
+.rowLink:hover {
+  background: var(--c-blue-cobalt);
+  color: white;
+  text-decoration: none;
+  transform: translateX(2px);
+}
+.rowLink:hover .rowHint,
+.rowLink:hover .rowArrow {
+  color: rgba(255, 255, 255, 0.85);
+}
+.rowLink:hover .rowIcon {
+  color: white;
+}
+
+.rowIcon {
+  width: 22px;
+  height: 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--c-blue-cobalt);
+}
+.rowIcon svg {
+  width: 22px;
+  height: 22px;
+  stroke: currentColor;
+  stroke-width: 1.6;
+  fill: none;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.rowText {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
+.rowLabel {
+  font-size: 14px;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.rowHint {
+  font-size: 12px;
+  color: var(--c-cobalt-400);
+  line-height: 1.3;
+}
+
+.rowArrow {
+  font-size: 16px;
+  color: var(--c-cobalt-400);
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+/* ---------- Responsive ---------- */
+
+@media (max-width: 900px) {
+  .variant-rail {
+    max-width: 100%;
+    position: static;
+  }
+}

package/src/components/ContentTypeFilter/ContentTypeFilter.jsx

@@ -1,9 +1,15 @@
 /**
  * <ContentTypeFilter />
  *
- * Top-of-page chip row that filters academy content by type. "All" is
- * the default chip and is always present. Driven by a `?type=` query
- * parameter so the filter survives reload and copy-paste.
+ * Top-of-page chip row that filters a feed by a single key. Defaults
+ * to academy content types ("Blogs", "Guides", "Case studies", …) but
+ * is reused on the academy landing as the product filter row by
+ * passing a different `types` + `labels` map (see APP_LABELS in
+ * @conduction/docusaurus-preset/data/apps-registry).
+ *
+ * "All" is the default chip and is always present. Driven by a query
+ * parameter (`?type=` for content types, `?app=` for products) so the
+ * filter survives reload and copy-paste.
  *
  * Mirrors the chip row in preview/components/academy.html.
  *
@@ -29,6 +35,19 @@
  *
  *   const [type, setType] = useState(null);
  *   <ContentTypeFilter value={type} onChange={setType} />
+ *
+ * Usage as a product filter (reuses the same component):
+ *
+ *   import {APP_LABELS, APP_SLUGS} from '@conduction/docusaurus-preset/data/apps-registry';
+ *   <ContentTypeFilter
+ *     value={app}
+ *     onChange={setApp}
+ *     types={APP_SLUGS}
+ *     labels={APP_LABELS}
+ *     counts={appCounts}
+ *     allLabel="All apps"
+ *     allCount={totalCount}
+ *   />
  */
 
 import React from 'react';
@@ -48,9 +67,14 @@ export default function ContentTypeFilter({
   allLabel = 'Everything',
   allCount,
   types = CONTENT_TYPES,
+  labels,
   className,
 }) {
   const isLinkMode = typeof hrefForType === 'function';
+  const labelFor = (key) => {
+    if (labels && labels[key]) return labels[key];
+    return CONTENT_TYPE_PLURAL_LABELS[key] || key;
+  };
 
   const renderChip = (key, label, count) => {
     const active = (key === ALL && value == null) || key === value;
@@ -94,7 +118,7 @@ export default function ContentTypeFilter({
     <div className={[styles.row, className].filter(Boolean).join(' ')}>
       {renderChip(ALL, allLabel, allCount)}
       {types.map((t) =>
-        renderChip(t, CONTENT_TYPE_PLURAL_LABELS[t] || t, counts && counts[t])
+        renderChip(t, labelFor(t), counts && counts[t])
       )}
     </div>
   );

package/src/components/index.js

@@ -94,6 +94,8 @@ export {
 export {default as NewsletterCta} from './NewsletterCta/NewsletterCta.jsx';
 export {default as RelatedPosts} from './RelatedPosts/RelatedPosts.jsx';
 export {default as ContentDetailHero} from './ContentDetailHero/ContentDetailHero.jsx';
+export {default as AppCrossLinks} from './AppCrossLinks/AppCrossLinks.jsx';
+export {APPS_REGISTRY, APP_SLUGS, APP_LABELS, getApp, getApps} from '../data/apps-registry';
 
 /* Tutorial-body components. Drop-in replacements for the ad-hoc
    "What you need", "Troubleshooting", and "Next steps" h2 + bullet

package/src/data/apps-registry.js

@@ -0,0 +1,61 @@
+/**
+ * @conduction/docusaurus-preset/data/apps-registry
+ *
+ * URL-only registry of every public Conduction app. Single source of
+ * truth for cross-linking between the three surfaces a visitor lands
+ * on while learning about an app:
+ *
+ *   1. /apps/<slug>                  product detail page
+ *   2. https://docs.conduction.nl/<slug>     documentation site (lives
+ *      in the app's own repo, served from a per-app subfolder under
+ *      the central docs.conduction.nl Docusaurus install)
+ *   3. /academy?app=<slug>           academy posts filtered by app
+ *
+ * The registry is consumed by:
+ *   - <AppCrossLinks/>          renders the three links per app.
+ *   - <ProductFilter/>          renders the chip row on /academy.
+ *   - sites/www/src/data/apps-catalog.js   the live Conduction.nl
+ *     site adds icons, taglines, and category metadata on top of
+ *     this registry, so display data and URLs stay in lockstep.
+ *
+ * Adding a new app: add an entry here. The url shape is conventional:
+ *   - productHref:  /apps/<slug>
+ *   - docsHref:     https://docs.conduction.nl/<slug>
+ *   - academyHref:  /academy?app=<slug>
+ * Override any of the three when an app deviates from the convention
+ * (none today; the convention holds).
+ */
+
+export const APPS_REGISTRY = {
+  opencatalogi:    {slug: 'opencatalogi',    name: 'OpenCatalogi',     productHref: '/apps/opencatalogi',    docsHref: 'https://docs.conduction.nl/opencatalogi',    academyHref: '/academy?app=opencatalogi'},
+  openregister:    {slug: 'openregister',    name: 'OpenRegister',     productHref: '/apps/openregister',    docsHref: 'https://docs.conduction.nl/openregister',    academyHref: '/academy?app=openregister'},
+  openconnector:   {slug: 'openconnector',   name: 'OpenConnector',    productHref: '/apps/openconnector',   docsHref: 'https://docs.conduction.nl/openconnector',   academyHref: '/academy?app=openconnector'},
+  docudesk:        {slug: 'docudesk',        name: 'DocuDesk',         productHref: '/apps/docudesk',        docsHref: 'https://docs.conduction.nl/docudesk',        academyHref: '/academy?app=docudesk'},
+  mydash:          {slug: 'mydash',          name: 'MyDash',           productHref: '/apps/mydash',          docsHref: 'https://docs.conduction.nl/mydash',          academyHref: '/academy?app=mydash'},
+  openwoo:         {slug: 'openwoo',         name: 'OpenWoo',          productHref: '/apps/openwoo',         docsHref: 'https://docs.conduction.nl/openwoo',         academyHref: '/academy?app=openwoo'},
+  zaakafhandelapp: {slug: 'zaakafhandelapp', name: 'ZaakAfhandelApp',  productHref: '/apps/zaakafhandelapp', docsHref: 'https://docs.conduction.nl/zaakafhandelapp', academyHref: '/academy?app=zaakafhandelapp'},
+  pipelinq:        {slug: 'pipelinq',        name: 'PipelinQ',         productHref: '/apps/pipelinq',        docsHref: 'https://docs.conduction.nl/pipelinq',        academyHref: '/academy?app=pipelinq'},
+  procest:         {slug: 'procest',         name: 'Procest',          productHref: '/apps/procest',         docsHref: 'https://docs.conduction.nl/procest',         academyHref: '/academy?app=procest'},
+  decidesk:        {slug: 'decidesk',        name: 'DeciDesk',         productHref: '/apps/decidesk',        docsHref: 'https://docs.conduction.nl/decidesk',        academyHref: '/academy?app=decidesk'},
+  softwarecatalog: {slug: 'softwarecatalog', name: 'SoftwareCatalog',  productHref: '/apps/softwarecatalog', docsHref: 'https://docs.conduction.nl/softwarecatalog', academyHref: '/academy?app=softwarecatalog'},
+  larpingapp:      {slug: 'larpingapp',      name: 'LarpingApp',       productHref: '/apps/larpingapp',      docsHref: 'https://docs.conduction.nl/larpingapp',      academyHref: '/academy?app=larpingapp'},
+  nldesign:        {slug: 'nldesign',        name: 'NLDesign',         productHref: '/apps/nldesign',        docsHref: 'https://docs.conduction.nl/nldesign',        academyHref: '/academy?app=nldesign'},
+};
+
+export const APP_SLUGS = Object.keys(APPS_REGISTRY);
+
+/** Build a label map keyed by slug, suitable for <ContentTypeFilter labels=…/>. */
+export const APP_LABELS = APP_SLUGS.reduce((acc, slug) => {
+  acc[slug] = APPS_REGISTRY[slug].name;
+  return acc;
+}, {});
+
+/** Resolve a slug to its registry entry; returns undefined for unknown slugs. */
+export function getApp(slug) {
+  return APPS_REGISTRY[slug];
+}
+
+/** Resolve an array of slugs, dropping any that aren't in the registry. */
+export function getApps(slugs = []) {
+  return slugs.map(getApp).filter(Boolean);
+}

package/src/index.js

@@ -86,8 +86,8 @@ const baseFooterLinks = () => [
   {
     title: 'Documentatie',
     items: [
-      { label: 'Brand book', href: 'https://connext.conduction.nl/' },
-      { label: 'Diagram set', href: 'https://connext.conduction.nl/diagrams/' },
+      { label: 'Brand book', href: 'https://identity.conduction.nl/' },
+      { label: 'Diagram set', href: 'https://identity.conduction.nl/diagrams/' },
     ],
   },
 ];

package/src/theme/DocItem/Footer/index.jsx

@@ -0,0 +1,104 @@
+/**
+ * Brand DocItem/Footer swizzle.
+ *
+ * Wraps Docusaurus's default doc-item footer (tags row + edit-meta
+ * row) and appends a Conduction <AppCrossLinks/> block so every
+ * documentation page on docs.conduction.nl/<app> finishes with a
+ * cross-link to the product page and the academy filter.
+ *
+ * Activation is per-site, opt-in: a docs site enables the block by
+ * adding to its docusaurus.config.js:
+ *
+ *   themeConfig: {
+ *     conduction: {
+ *       appId: 'opencatalogi'
+ *     },
+ *     ...
+ *   }
+ *
+ * Apps that don't set `themeConfig.conduction.appId` keep the default
+ * Docusaurus footer behaviour, untouched.
+ *
+ * Per-page opt-out: a doc page can suppress the block via frontmatter
+ *
+ *   ---
+ *   hide_app_cross_links: true
+ *   ---
+ *
+ * which is useful for changelogs, license pages, or other docs that
+ * shouldn't end with a cross-link.
+ */
+
+import React from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import TagsListInline from '@theme/TagsListInline';
+import EditMetaRow from '@theme/EditMetaRow';
+import {AppCrossLinks} from '@conduction/docusaurus-preset/components';
+import {APPS_REGISTRY} from '@conduction/docusaurus-preset/data/apps-registry';
+
+export default function DocItemFooter() {
+  const {siteConfig} = useDocusaurusContext();
+  const {metadata, frontMatter} = useDoc();
+  const {editUrl, lastUpdatedAt, lastUpdatedBy, tags} = metadata;
+
+  /* Per-page opt-out and per-page override (`apps:` in frontmatter
+     wins over the site-wide appId). Lets a single doc page point at
+     a different app without touching siteConfig. */
+  const hide = !!frontMatter?.hide_app_cross_links;
+  const fmApps = Array.isArray(frontMatter?.apps) ? frontMatter.apps : null;
+  const siteAppId = siteConfig?.themeConfig?.conduction?.appId;
+  const apps = (fmApps && fmApps.length > 0)
+    ? fmApps
+    : (siteAppId ? [siteAppId] : []);
+  const knownApps = apps.filter((slug) => APPS_REGISTRY[slug]);
+
+  const canDisplayTagsRow = tags.length > 0;
+  const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+  const canDisplayCrossLinks = !hide && knownApps.length > 0;
+
+  const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow || canDisplayCrossLinks;
+  if (!canDisplayFooter) return null;
+
+  return (
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}>
+      {canDisplayTagsRow && (
+        <div
+          className={clsx(
+            'row margin-top--sm',
+            ThemeClassNames.docs.docFooterTagsRow,
+          )}>
+          <div className="col">
+            <TagsListInline tags={tags} />
+          </div>
+        </div>
+      )}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          className={clsx(
+            'margin-top--sm',
+            ThemeClassNames.docs.docFooterEditMetaRow,
+          )}
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+        />
+      )}
+      {canDisplayCrossLinks && (
+        <div className="margin-top--lg">
+          <AppCrossLinks
+            variant="inline"
+            apps={knownApps}
+            surface="docs"
+            heading={knownApps.length === 1
+              ? 'About this app'
+              : 'About these apps'}
+          />
+        </div>
+      )}
+    </footer>
+  );
+}