chore: improved index page (#1045)

* chore: improved index page

* chore: improved index page

* chore: improved index page

* fixup!

* fixup!

Author: avivkeller

.changeset/documentation-index-component.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+Add a `<DocumentationIndex />` MDX component that renders the stability overview of every module, backed by a new `documentationIndex` export on `#theme/config` (replaces the `<!-- DOCUMENTATION_INDEX -->` comment)

.changeset/mdx-degrades-in-string-pipelines.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/core': patch
+---
+
+MDX nodes in the HTML-string pipelines are now dropped, and do not crash.

packages/core/src/utils/__tests__/generators.test.mjs

@@ -2,12 +2,71 @@ import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
 import {
+  getEntryDescription,
   groupNodesByModule,
   getVersionFromSemVer,
   coerceSemVer,
   getCompatibleVersions,
 } from '../generators.mjs';
 
+describe('getEntryDescription', () => {
+  it('returns llm_description when available', () => {
+    const entry = {
+      llm_description: 'LLM generated description',
+      content: { children: [] },
+    };
+
+    const result = getEntryDescription(entry);
+    assert.equal(result, 'LLM generated description');
+  });
+
+  it('extracts first paragraph when no llm_description', () => {
+    const entry = {
+      content: {
+        children: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'text', value: 'First paragraph' }],
+          },
+        ],
+      },
+    };
+
+    const result = getEntryDescription(entry);
+    assert.ok(result.length > 0);
+  });
+
+  it('returns empty string when no paragraph found', () => {
+    const entry = {
+      content: {
+        children: [
+          { type: 'heading', children: [{ type: 'text', value: 'Title' }] },
+        ],
+      },
+    };
+
+    const result = getEntryDescription(entry);
+    assert.equal(result, '');
+  });
+
+  it('removes newlines from description', () => {
+    const entry = {
+      content: {
+        children: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'text', value: 'Line 1\nLine 2\r\nLine 3' }],
+          },
+        ],
+      },
+    };
+
+    const result = getEntryDescription(entry);
+    assert.equal(result.includes('\n'), false);
+    assert.equal(result.includes('\r'), false);
+  });
+});
+
 describe('groupNodesByModule', () => {
   it('groups nodes by api property', () => {
     const nodes = [

packages/core/src/utils/__tests__/remark.test.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { getRemarkRehype } from '../remark.mjs';
+
+describe('getRemarkRehype', () => {
+  it('degrades MDX nodes instead of crashing rehype-stringify', () => {
+    const processor = getRemarkRehype();
+
+    const tree = {
+      type: 'root',
+      children: [
+        {
+          type: 'paragraph',
+          children: [
+            { type: 'text', value: 'before ' },
+            {
+              type: 'mdxJsxTextElement',
+              name: 'Tooltip',
+              attributes: [],
+              children: [{ type: 'text', value: 'inner' }],
+            },
+            { type: 'mdxTextExpression', value: '1 + 1' },
+          ],
+        },
+        {
+          type: 'mdxJsxFlowElement',
+          name: 'DocumentationIndex',
+          attributes: [],
+          children: [],
+        },
+      ],
+    };
+
+    const output = processor.stringify(processor.runSync(tree));
+
+    // JSX elements degrade to their children; expressions are dropped.
+    assert.equal(output, '<p>before inner</p>');
+  });
+});

packages/core/src/utils/generators.mjs

@@ -2,6 +2,36 @@
 
 import { coerce, major } from 'semver';
 
+import { transformNodeToString } from './unist.mjs';
+
+/**
+ * Retrieves the description of a given API doc entry. It first checks whether
+ * the entry has a llm_description property. If not, it extracts the first
+ * paragraph from the entry's content.
+ *
+ * @param {import('../generators/metadata/types').MetadataEntry} entry
+ * @returns {string}
+ */
+export const getEntryDescription = entry => {
+  if (entry.llm_description) {
+    return entry.llm_description.trim();
+  }
+
+  const descriptionNode = entry.content.children.find(
+    child => child.type === 'paragraph'
+  );
+
+  if (!descriptionNode) {
+    return '';
+  }
+
+  return (
+    transformNodeToString(descriptionNode)
+      // Remove newlines and extra spaces
+      .replace(/[\r\n]+/g, '')
+  );
+};
+
 /**
  * Groups all the API metadata nodes by module (`api` property) so that we can process each different file
  * based on the module it belongs to.

packages/core/src/utils/remark.mjs

@@ -13,18 +13,33 @@ import { lazy } from './misc.mjs';
 import { typeAnnotationToHast } from './type-annotations/hast.mjs';
 import remarkTypeAnnotations from './type-annotations/remark.mjs';
 
-// MDX node types that may appear in trees parsed by `getRemarkMdx`; the
-// rehype pipelines pass them through untouched.
-const passThrough = [
-  'element',
-  'mdxJsxTextElement',
-  'mdxJsxFlowElement',
-  'mdxJsxAttribute',
-  'mdxJsxAttributeValueExpression',
-  'mdxFlowExpression',
-  'mdxTextExpression',
-  'mdxjsEsm',
-];
+// Nodes the rehype pipelines pass through untouched.
+const passThrough = ['element'];
+
+/**
+ * Renders an MDX JSX element as just its children, so the surrounding prose
+ * still renders in HTML-string output.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('unist').Parent} node
+ */
+const mdxElementToChildren = (state, node) => state.all(node);
+
+/**
+ * Drops a node from HTML-string output.
+ */
+const dropNode = () => undefined;
+
+// The HTML-string pipelines cannot render MDX nodes (rendering those is the
+// React generators' job): JSX elements degrade to their children so the
+// surrounding prose still renders, and expressions/ESM are dropped.
+const mdxToHastHandlers = {
+  mdxJsxTextElement: mdxElementToChildren,
+  mdxJsxFlowElement: mdxElementToChildren,
+  mdxFlowExpression: dropNode,
+  mdxTextExpression: dropNode,
+  mdxjsEsm: dropNode,
+};
 
 /**
  * Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown)
@@ -64,7 +79,7 @@ export const getRemarkRehype = lazy(() =>
     .use(remarkRehype, {
       allowDangerousHtml: true,
       passThrough,
-      handlers: { typeAnnotation: typeAnnotationToHast },
+      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
     })
     // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
     // and we trust the sources of the Markdown files
@@ -86,7 +101,7 @@ export const getRemarkRehypeWithShiki = lazy(() =>
       allowDangerousHtml: true,
       passThrough,
       // legacy-html gets the minimal (unhighlighted) type rendering
-      handlers: { typeAnnotation: typeAnnotationToHast },
+      handlers: { typeAnnotation: typeAnnotationToHast, ...mdxToHastHandlers },
     })
     // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
     // and transform them into HAST nodes

packages/react/src/html/README.md

@@ -358,6 +358,11 @@ title: Welcome
 There are {stats.length} APIs documented.
 ```
 
+The built-in components are available without registration. Notably,
+`<DocumentationIndex />` renders an index of every documented module with its
+stability badge and description, sourced from the `documentationIndex` export
+of [`#theme/config`](#themeconfig-virtual-module).
+
 ## `#theme/config` virtual module
 
 The `html` generator provides a `#theme/config` virtual module that exposes pre-computed configuration as named exports. Any component (including custom overrides) can import the values it needs, and tree-shaking removes the rest.
@@ -377,6 +382,9 @@ import { project, repository, editURL } from '#theme/config';
 - `editURL` {string} Partially populated "edit this page" URL template (only
   `{path}` remains).
 - `pages` {Array} Sorted `[name, path]` tuples for sidebar navigation.
+- `documentationIndex` {Array} Entries rendered by the built-in
+  `<DocumentationIndex />` component — every page with a stability index, each
+  `{ api, name, index, description }`.
 - `navigation` {Object} Mirrors the configured `navigation` (consumed by the
   built-in `SideBar` and `NavBar`).
 - `useAbsoluteURLs` {boolean} Whether internal links use absolute URLs (mirrors

packages/react/src/html/constants.mjs

@@ -26,6 +26,10 @@ export const JSX_IMPORTS = {
     name: 'CodeTabs',
     source: resolve(ROOT, './ui/components/CodeTabs'),
   },
+  DocumentationIndex: {
+    name: 'DocumentationIndex',
+    source: resolve(ROOT, './ui/components/DocumentationIndex'),
+  },
   MDXTooltip: {
     name: 'MDXTooltip',
     isDefaultExport: false,

packages/react/src/html/ui/components/DocumentationIndex/index.jsx

@@ -0,0 +1,48 @@
+import Badge from '@node-core/ui-components/Common/Badge';
+
+import styles from './index.module.css';
+import { STABILITY_KINDS, STABILITY_LABELS } from '../constants.mjs';
+
+import { documentationIndex } from '#theme/config';
+
+/**
+ * @typedef {Object} DocumentationIndexEntry
+ * @property {string} api - Basename of the document, linked as `${api}.html`
+ * @property {string} name - Human-readable name from the document's heading
+ * @property {string} index - Stability index (e.g. `'2'` or `'1.1'`)
+ * @property {string} [description] - The document's `llm_description`, or its first paragraph
+ */
+
+/**
+ * @param {DocumentationIndexEntry} props
+ */
+const IndexEntry = ({ api, name, index, description }) => {
+  const level = parseInt(index, 10);
+  const label = STABILITY_LABELS[level] ?? index;
+
+  return (
+    <a className={styles.entry} href={`${api}.html`}>
+      <span className={styles.title}>
+        <span className={styles.name}>{name}</span>
+
+        <Badge
+          size="small"
+          kind={STABILITY_KINDS[level] ?? 'neutral'}
+          aria-label={`Stability: ${index}`}
+        >
+          {label}
+        </Badge>
+      </span>
+
+      {description && <span className={styles.summary}>{description}</span>}
+    </a>
+  );
+};
+
+export default () => (
+  <nav className={styles.documentationIndex} aria-label="Documentation index">
+    {documentationIndex.map(entry => (
+      <IndexEntry key={entry.api} {...entry} />
+    ))}
+  </nav>
+);

packages/react/src/html/ui/components/DocumentationIndex/index.module.css

@@ -0,0 +1,61 @@
+.documentationIndex {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
+  gap: 1rem;
+  margin-block: 1.5rem;
+}
+
+.entry {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  padding: 1rem;
+  border: 1px solid var(--color-neutral-200);
+  border-radius: 0.75rem;
+  color: inherit;
+  text-decoration: none;
+  transition:
+    border-color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.entry:hover,
+.entry:focus-visible {
+  border-color: var(--color-neutral-400);
+  background-color: var(--color-neutral-100);
+}
+
+:where([data-theme='dark'], [data-theme='dark'] *) .entry {
+  border-color: var(--color-neutral-900);
+}
+
+:where([data-theme='dark'], [data-theme='dark'] *) .entry:hover,
+:where([data-theme='dark'], [data-theme='dark'] *) .entry:focus-visible {
+  border-color: var(--color-neutral-700);
+  background-color: var(--color-neutral-950);
+}
+
+.title {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.name {
+  font-weight: 600;
+  color: var(--color-neutral-900);
+}
+
+:where([data-theme='dark'], [data-theme='dark'] *) .name {
+  color: var(--color-white);
+}
+
+.summary {
+  font-size: 0.875rem;
+  color: var(--color-neutral-800);
+}
+
+:where([data-theme='dark'], [data-theme='dark'] *) .summary {
+  color: var(--color-neutral-600);
+}