From 381b22e0394daa52835f10cbfaaae2ab693eb858 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Sun, 27 Jul 2025 16:17:13 -0400
Subject: [PATCH] feat(metabar): improve headings and add stability

---
 .../jsx-ast/utils/buildBarProps.mjs           | 27 ++++++++++++-------
 .../web/ui/components/MetaBar/index.jsx       | 23 ++++++++++++++--
 .../ui/components/MetaBar/index.module.css    |  5 ++++
 3 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/src/generators/jsx-ast/utils/buildBarProps.mjs b/src/generators/jsx-ast/utils/buildBarProps.mjs
index 8b08106e..cd42bfdd 100644
--- a/src/generators/jsx-ast/utils/buildBarProps.mjs
+++ b/src/generators/jsx-ast/utils/buildBarProps.mjs
@@ -41,15 +41,23 @@ const shouldIncludeEntryInToC = ({ heading }) =>
 const extractHeading = entry => {
   const data = entry.heading.data;
 
-  const rawName = data.name
-    // Remove any containing code blocks
-    .replace(/`/g, '')
-    // Remove any prefixes (i.e. 'Class:')
-    .replace(/^[^:]+:/, '')
-    // Trim the remaining whitespace
-    .trim();
-
-  let heading = getFullName(data, rawName);
+  const cliFlagOrEnv = [...data.text.matchAll(/`(-[\w-]+|[A-Z0-9_]+=)/g)];
+
+  let heading;
+
+  if (cliFlagOrEnv.length > 0) {
+    heading = cliFlagOrEnv.at(-1)[1];
+  } else {
+    const rawName = data.name
+      // Remove any containing code blocks
+      .replace(/`/g, '')
+      // Remove any prefixes (i.e. 'Class:')
+      .replace(/^[^:]+:/, '')
+      // Trim the remaining whitespace
+      .trim();
+
+    heading = getFullName(data, rawName);
+  }
 
   if (data.type === 'ctor') {
     heading += ' Constructor';
@@ -58,6 +66,7 @@ const extractHeading = entry => {
   return {
     depth: entry.heading.depth,
     value: heading,
+    stability: parseInt(entry.stability?.children[0]?.data.index ?? 2),
     slug: data.slug,
   };
 };
diff --git a/src/generators/web/ui/components/MetaBar/index.jsx b/src/generators/web/ui/components/MetaBar/index.jsx
index f069a99c..03682766 100644
--- a/src/generators/web/ui/components/MetaBar/index.jsx
+++ b/src/generators/web/ui/components/MetaBar/index.jsx
@@ -1,4 +1,5 @@
 import { CodeBracketIcon, DocumentIcon } from '@heroicons/react/24/outline';
+import Badge from '@node-core/ui-components/Common/Badge';
 import MetaBar from '@node-core/ui-components/Containers/MetaBar';
 import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
 
@@ -11,13 +12,16 @@ const iconMap = {
 
 /**
  * @typedef MetaBarProps
- * @property {Array<import('@vcarl/remark-headings').Heading>} headings - Array of page headings for table of contents
+ * @property {Array<import('@vcarl/remark-headings').Heading & { stability: string }>} headings - Array of page headings for table of contents
  * @property {string} addedIn - Version or date when feature was added
  * @property {string} readingTime - Estimated reading time for the page
  * @property {Array<[string, string]>} viewAs - Array of [title, path] tuples for view options
  * @property {string} editThisPage - URL for editing the current page
  */
 
+const STABILITY_KINDS = ['error', 'warning', null, 'default'];
+const STABILITY_LABELS = ['D', 'E', null, 'L'];
+
 /**
  * MetaBar component that displays table of contents and page metadata
  * @param {MetaBarProps} props - Component props
@@ -32,8 +36,23 @@ export default ({
   <MetaBar
     heading="Table of Contents"
     headings={{
-      items: headings.map(({ slug, ...heading }) => ({
+      items: headings.map(({ slug, value, stability, ...heading }) => ({
         ...heading,
+        value:
+          stability !== 2 ? (
+            <>
+              {value}
+              <Badge
+                size="small"
+                className={styles.badge}
+                kind={STABILITY_KINDS[stability]}
+              >
+                {STABILITY_LABELS[stability]}
+              </Badge>
+            </>
+          ) : (
+            value
+          ),
         data: { id: slug },
       })),
     }}
diff --git a/src/generators/web/ui/components/MetaBar/index.module.css b/src/generators/web/ui/components/MetaBar/index.module.css
index fa6de672..0f3163ee 100644
--- a/src/generators/web/ui/components/MetaBar/index.module.css
+++ b/src/generators/web/ui/components/MetaBar/index.module.css
@@ -4,3 +4,8 @@
   height: 1rem;
   margin-right: 0.25rem;
 }
+
+.badge {
+  display: inline-block;
+  margin-left: 0.25rem;
+}