jamdesk 1.1.34 → 1.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.34",
+  "version": "1.1.35",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/components/mdx/Steps.tsx

@@ -2,6 +2,7 @@
 
 import { ReactNode, Children, cloneElement, isValidElement, memo } from 'react';
 import { getIconClass } from '@/lib/icon-utils';
+import { generateSlug } from '@/lib/heading-extractor';
 
 type TitleSize = 'p' | 'h2' | 'h3';
 type IconType = 'regular' | 'solid' | 'light' | 'thin' | 'sharp-solid' | 'duotone' | 'brands';
@@ -129,9 +130,24 @@ function StepTitle({ title, titleSize }: { title: string; titleSize: TitleSize }
 
 export const Step = memo(function Step({ title, children, stepNumber, isLast, icon, iconType, titleSize = 'p' }: StepProps) {
   const containerClassName = isLast ? 'relative pb-0' : 'relative pb-8';
+  const slug = title ? generateSlug(title) || undefined : undefined;
+
+  // Emit both attrs together or neither — the DOM scanner keys off
+  // `data-step-number`, so a label without a number would be a dangling
+  // attribute, and a number without a label would produce a TOC entry with
+  // empty text.
+  const stepAttrs: { 'data-step-number'?: number; 'data-step-label'?: string } = {};
+  if (typeof stepNumber === 'number' && title) {
+    stepAttrs['data-step-number'] = stepNumber;
+    stepAttrs['data-step-label'] = title;
+  }
 
   return (
-    <div className={containerClassName}>
+    <div
+      className={containerClassName}
+      id={slug}
+      {...stepAttrs}
+    >
       {/* Vertical line connecting to next step - positioned absolutely */}
       {!isLast && (
         <div

package/vendored/components/navigation/TableOfContents.tsx

@@ -2,12 +2,13 @@
 
 import { useEffect, useState, useRef, useCallback } from 'react';
 import { getIconClass } from '@/lib/icon-utils';
-import { generateSlug } from '@/lib/heading-extractor';
+import { extractHeadings } from '@/lib/heading-extractor';
 
 interface TocItem {
   id: string;
   text: string;
   level: number;
+  stepNumber?: number;
 }
 
 interface TableOfContentsProps {
@@ -196,75 +197,128 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
     return () => observer.disconnect();
   }, [updateThumb]);
 
-  // Parse headings from content in source order, then scan DOM for dynamic components
+  // Source-order parse gives immediate headings; the MutationObserver below
+  // keeps the list in sync when dynamic components (Accordion, Tabs) reveal
+  // Steps after initial render.
   useEffect(() => {
-    // Line-by-line pass to preserve source order and skip fenced code blocks
-    const items: TocItem[] = [];
-    const lines = content.split('\n');
-    let inCodeBlock = false;
-    let fencePattern = '';
-
-    for (const line of lines) {
-      const fenceMatch = line.match(/^(`{3,}|~{3,})/);
-      if (fenceMatch) {
-        if (!inCodeBlock) {
-          inCodeBlock = true;
-          fencePattern = fenceMatch[1];
-          continue;
-        } else if (line.startsWith(fencePattern)) {
-          inCodeBlock = false;
-          fencePattern = '';
-          continue;
-        }
-      }
-      if (inCodeBlock) continue;
-
-      const headingMatch = line.match(/^(#{2,3})\s+(.+)$/);
-      if (headingMatch) {
-        const level = headingMatch[1].length;
-        const text = headingMatch[2].trim();
-        const id = generateSlug(text);
-        if (id) items.push({ id, text, level });
-      }
+    const sourceItems: TocItem[] = extractHeadings(content)
+      .filter(h => h.level === 2 || h.level === 3)
+      .map(h => ({
+        id: h.id,
+        text: h.text,
+        level: h.level,
+        stepNumber: h.stepNumber,
+      }));
 
-      const updateMatch = line.match(/<Update\s+label=["']([^"']+)["']/);
-      if (updateMatch) {
-        const text = updateMatch[1];
-        const id = generateSlug(text);
-        if (id) items.push({ id, text, level: 2 });
-      }
-    }
-
-    setHeadings(items);
+    setHeadings(sourceItems);
 
-    // DOM scan: single query to get all TOC elements in document order
     const scanDomHeadings = () => {
-      const tocElements = document.querySelectorAll('main h2[id], main h3[id], main [data-update-label]');
+      const tocElements = document.querySelectorAll<HTMLElement>(
+        'main h2[id], main h3[id], main [data-update-label], main [data-step-number]',
+      );
       const newItems: TocItem[] = [];
       const seenDomIds = new Set<string>();
+      const collisions: string[] = [];
 
       tocElements.forEach((element) => {
         const id = element.id;
-        if (!id || seenDomIds.has(id)) return;
+        if (!id) return;
+        if (seenDomIds.has(id)) {
+          collisions.push(id);
+          return;
+        }
+
+        const stepNumberAttr = element.getAttribute('data-step-number');
+        const isStep = stepNumberAttr !== null && stepNumberAttr !== '';
+        const isUpdate = !isStep && element.hasAttribute('data-update-label');
+
+        let text = '';
+        let level = 2;
+        let stepNumber: number | undefined;
+
+        if (isStep) {
+          text = element.getAttribute('data-step-label')?.trim() || '';
+          level = 3;
+          const parsed = parseInt(stepNumberAttr as string, 10);
+          stepNumber = Number.isFinite(parsed) ? parsed : undefined;
+        } else if (isUpdate) {
+          text = element.getAttribute('data-update-label')?.trim() || '';
+          level = 2;
+        } else {
+          text = element.textContent?.trim() || '';
+          level = element.tagName === 'H2' ? 2 : 3;
+        }
 
-        const isUpdate = element.hasAttribute('data-update-label');
-        const text = isUpdate
-          ? (element.getAttribute('data-update-label') || '')
-          : (element.textContent?.trim() || '');
         if (!text) return;
 
         seenDomIds.add(id);
-        const level = isUpdate ? 2 : (element.tagName === 'H2' ? 2 : 3);
-        newItems.push({ id, text, level });
+        newItems.push({ id, text, level, stepNumber });
       });
 
-      if (newItems.length > 0) {
-        setHeadings(newItems);
+      // Dev-mode warning for slug collisions. In production builds, stay
+      // silent — browsers still render correctly (first match wins).
+      if (collisions.length > 0 && process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `[TableOfContents] Duplicate anchor id(s) detected on this page: ${[...new Set(collisions)].join(', ')}. ` +
+          `This usually means a <Step title="X"> collides with a heading of the same text. ` +
+          `Only the first element will be targetable via fragment link or TOC click.`,
+        );
       }
+
+      if (newItems.length === 0) return;
+
+      // Dedupe re-renders: if the new item list matches the current one
+      // position-for-position on (id, stepNumber), skip setState. This keeps
+      // the MutationObserver cheap when it fires on unrelated DOM changes.
+      setHeadings(prev => {
+        if (prev.length !== newItems.length) return newItems;
+        for (let i = 0; i < newItems.length; i++) {
+          if (
+            prev[i].id !== newItems[i].id ||
+            prev[i].stepNumber !== newItems[i].stepNumber ||
+            prev[i].text !== newItems[i].text
+          ) {
+            return newItems;
+          }
+        }
+        return prev;
+      });
     };
 
-    const timer = setTimeout(scanDomHeadings, 500);
-    return () => clearTimeout(timer);
+    // Coalesce scans to one per animation frame. cancelAnimationFrame in the
+    // cleanup below is only effective while scheduledScan is non-null — once
+    // the rAF callback starts, the functional setHeadings is safe on an
+    // unmounted tree because it returns prev when items are unchanged.
+    let scheduledScan: number | null = null;
+    const scheduleScan = () => {
+      if (scheduledScan !== null) return;
+      scheduledScan = requestAnimationFrame(() => {
+        scheduledScan = null;
+        scanDomHeadings();
+      });
+    };
+
+    scheduleScan();
+
+    const mainEl = document.querySelector('main');
+    const observer = mainEl ? new MutationObserver(scheduleScan) : null;
+    if (mainEl && observer) {
+      observer.observe(mainEl, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['id', 'data-step-number', 'data-step-label', 'data-update-label'],
+      });
+    } else if (!mainEl && process.env.NODE_ENV !== 'production') {
+      console.warn(
+        '[TableOfContents] no <main> element found — late-mount TOC updates will not be observed.',
+      );
+    }
+
+    return () => {
+      if (scheduledScan !== null) cancelAnimationFrame(scheduledScan);
+      observer?.disconnect();
+    };
   }, [content]);
 
   // For API pages, hide TOC if there are code panels visible
@@ -415,6 +469,7 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
         <div ref={containerRef} className="relative flex flex-col">
           {headings.map((heading, index) => {
             const isActive = activeAnchors.includes(heading.id);
+            const hasStepNumber = typeof heading.stepNumber === 'number';
 
             const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
               e.preventDefault();
@@ -425,18 +480,45 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
               }
             };
 
+            // 30px leaves room for the absolute-positioned 18px step circle
+            // (insetInlineStart: 1) + a gap. Non-step H3s use the same value
+            // so mixed step/non-step groups align visually.
+            const startOffset = heading.level === 3
+              ? 30
+              : getItemOffset(heading.level);
+
             return (
               <a
                 key={`${heading.id}-${index}`}
                 href={`#${heading.id}`}
                 onClick={handleClick}
                 data-active={isActive}
+                data-step={hasStepNumber || undefined}
                 className={`
                   relative block py-1.5 text-sm transition-colors duration-200
                   ${getLinkClass(heading.level, isActive)}
                 `}
-                style={{ paddingInlineStart: getItemOffset(heading.level) }}
+                style={{ paddingInlineStart: startOffset }}
               >
+                {hasStepNumber && (
+                  <span
+                    aria-hidden="true"
+                    className="absolute flex items-center justify-center rounded-full text-[11px] font-medium"
+                    style={{
+                      insetInlineStart: 1,
+                      top: '50%',
+                      transform: 'translateY(-50%)',
+                      width: 18,
+                      height: 18,
+                      backgroundColor: isActive
+                        ? 'var(--color-primary)'
+                        : 'var(--color-bg-primary)',
+                      color: isActive ? '#fff' : 'var(--color-text-muted)',
+                    }}
+                  >
+                    {heading.stepNumber}
+                  </span>
+                )}
                 {heading.text}
               </a>
             );

package/vendored/lib/heading-extractor.ts

@@ -2,7 +2,8 @@
  * Heading extractor for link validation.
  * Extracts heading slugs from MDX content to validate #fragment links.
  *
- * Canonical source for generateSlug — imported by TableOfContents.tsx and Update.tsx.
+ * Canonical source for generateSlug — imported by TableOfContents.tsx, Update.tsx,
+ * and Steps.tsx.
  */
 
 export interface HeadingInfo {
@@ -10,6 +11,8 @@ export interface HeadingInfo {
   text: string;
   level: number;
   line: number; // 1-indexed
+  /** When the entry is a <Step> inside a <Steps> block, this is its 1-based index within the block. */
+  stepNumber?: number;
 }
 
 /**
@@ -26,10 +29,20 @@ export function generateSlug(text: string): string {
 const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
 const FENCE_REGEX = /^(`{3,}|~{3,})/;
 const UPDATE_LABEL_REGEX = /<Update\s+label=["']([^"']+)["']/;
+const STEPS_OPEN_REGEX = /<Steps(\s|>)/;
+const STEPS_CLOSE_REGEX = /<\/Steps>/;
+// Global flag — we iterate with matchAll so authors who inline multiple
+// <Step> tags on one line get every one numbered.
+// Alternation (not a character class) keeps the capture from terminating on
+// apostrophes inside double-quoted attribute values (e.g. `<Step title="You're Live">`).
+// MUST only be used with matchAll — direct `test`/`exec` would share
+// lastIndex across calls and miscount.
+const STEP_TITLE_REGEX = /<Step\s+[^>]*title=(?:"([^"]+)"|'([^']+)')/g;
 
 /**
  * Extract all heading slugs from MDX content.
- * Includes markdown headings and <Update label="..."> component anchors.
+ * Includes markdown headings, <Update label="..."> component anchors,
+ * and <Step title="..."> entries inside <Steps> blocks (with per-block numbering).
  * Skips content inside fenced code blocks.
  */
 export function extractHeadings(content: string): HeadingInfo[] {
@@ -37,6 +50,10 @@ export function extractHeadings(content: string): HeadingInfo[] {
   const lines = content.split('\n');
   let inCodeBlock = false;
   let fencePattern = '';
+  // Boolean (not depth counter) — resets on every <Steps> open so an unclosed
+  // block can't stick the counter across subsequent blocks.
+  let inStepsBlock = false;
+  let stepCounter = 0;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -56,6 +73,14 @@ export function extractHeadings(content: string): HeadingInfo[] {
 
     if (inCodeBlock) continue;
 
+    // <Steps> open resets the per-block counter unconditionally. Ordering
+    // matters: open-reset must run BEFORE step matching on the same line so
+    // `<Steps><Step title="A">...</Step>` numbers "A" as 1.
+    if (STEPS_OPEN_REGEX.test(line)) {
+      inStepsBlock = true;
+      stepCounter = 0;
+    }
+
     const headingMatch = line.match(HEADING_REGEX);
     if (headingMatch) {
       const level = headingMatch[1].length;
@@ -74,6 +99,28 @@ export function extractHeadings(content: string): HeadingInfo[] {
         headings.push({ id, text, level: 2, line: i + 1 });
       }
     }
+
+    if (inStepsBlock) {
+      for (const match of line.matchAll(STEP_TITLE_REGEX)) {
+        const text = match[1] ?? match[2];
+        const id = generateSlug(text);
+        if (!id) continue;
+        stepCounter += 1;
+        headings.push({
+          id,
+          text,
+          level: 3,
+          line: i + 1,
+          stepNumber: stepCounter,
+        });
+      }
+    }
+
+    // </Steps> close runs AFTER step matching so `</Steps>` on the same line
+    // as the last <Step> still picks up that step.
+    if (STEPS_CLOSE_REGEX.test(line)) {
+      inStepsBlock = false;
+    }
   }
 
   return headings;

package/vendored/scripts/validate-links.cjs

@@ -219,16 +219,26 @@ function generateSlug(text) {
 
 /**
  * Extract heading slugs from MDX content.
- * Includes markdown headings and <Update label="..."> component anchors.
+ * Includes markdown headings, <Update label="..."> anchors, and
+ * <Step title="..."> anchors inside a <Steps> block.
  * Skips content inside fenced code blocks.
  *
- * Uses single-pass fence tracking (matches heading-extractor.ts pattern).
+ * Must stay semantically compatible with extractHeadings() in lib/heading-extractor.ts
+ * for slug collection. stepNumber tracking is intentionally omitted here — this
+ * function returns a Set<string>, not HeadingInfo[].
  */
 function extractHeadingSlugs(content) {
   const slugs = new Set();
   const lines = content.split('\n');
   let inCodeBlock = false;
   let fencePattern = '';
+  let inStepsBlock = false;
+
+  const STEPS_OPEN_REGEX = /<Steps(\s|>)/;
+  const STEPS_CLOSE_REGEX = /<\/Steps>/;
+  // Alternation, not a character class — must not terminate at apostrophes
+  // inside double-quoted attribute values (e.g. <Step title="You're Live">).
+  const STEP_TITLE_REGEX = /<Step\s+[^>]*title=(?:"([^"]+)"|'([^']+)')/g;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -248,6 +258,10 @@ function extractHeadingSlugs(content) {
 
     if (inCodeBlock) continue;
 
+    if (STEPS_OPEN_REGEX.test(line)) {
+      inStepsBlock = true;
+    }
+
     const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
     if (headingMatch) {
       const slug = generateSlug(headingMatch[1].trim());
@@ -259,6 +273,17 @@ function extractHeadingSlugs(content) {
       const slug = generateSlug(updateMatch[1]);
       if (slug) slugs.add(slug);
     }
+
+    if (inStepsBlock) {
+      for (const match of line.matchAll(STEP_TITLE_REGEX)) {
+        const slug = generateSlug(match[1] ?? match[2]);
+        if (slug) slugs.add(slug);
+      }
+    }
+
+    if (STEPS_CLOSE_REGEX.test(line)) {
+      inStepsBlock = false;
+    }
   }
 
   return slugs;