Use tabs for multi-page Sim docs

Author: Sg312

apps/sim/lib/workspace-files/artifact-stylesheet.test.ts

@@ -165,6 +165,18 @@ describe('docs fidelity', () => {
     expect(SIM_ARTIFACT_STYLESHEET).not.toContain('data-rail="nav"')
   })
 
+  // Set navigation is the docs' top tab row. A long set must scroll
+  // sideways — never wrap or truncate — with no scrollbar chrome; and the
+  // retired prev/next arrows must stay gone.
+  it('keeps the tab row one scrollable line and carries no arrow chrome', () => {
+    expect(SIM_ARTIFACT_STYLESHEET).toContain('overflow-x: auto; scrollbar-width: none;')
+    expect(SIM_ARTIFACT_STYLESHEET).toContain('.page-tabs::-webkit-scrollbar { display: none; }')
+    expect(SIM_ARTIFACT_STYLESHEET).toContain('.page-tab.is-active')
+    expect(SIM_ARTIFACT_STYLESHEET).not.toContain('.page-nav')
+    expect(SIM_ARTIFACT_STYLESHEET).not.toContain('.pa-nav')
+    expect(SIM_ARTIFACT_SHELL).not.toContain('page-actions')
+  })
+
   // Pages live inside the app: the PLATFORM stack, not the docs' webfont —
   // Inter next to emcn/sim chrome read as foreign.
   it('uses the platform font stack', () => {
@@ -178,7 +190,7 @@ describe('docs fidelity', () => {
     expect(SIM_ARTIFACT_STYLESHEET).toContain('text-decoration-thickness: 1.5px')
     expect(SIM_ARTIFACT_STYLESHEET).toContain('text-underline-offset: 3.5px')
     expect(SIM_ARTIFACT_STYLESHEET).toContain('a:hover { opacity: 0.8; }')
-    expect(SIM_ARTIFACT_STYLESHEET).toContain('.rail a, .page-nav-card { font-weight: 400')
+    expect(SIM_ARTIFACT_STYLESHEET).toContain('.rail a { font-weight: 400')
   })
 
   // The docs' figure.shiki shell and Code.Viewer metrics.

apps/sim/lib/workspace-files/artifact-stylesheet.ts

@@ -431,18 +431,27 @@ figcaption { font-size: 0.875em; line-height: 1.4285714; color: var(--text-prima
   border-bottom: 1px solid var(--border);
 }
 .art-bar-title { font-size: var(--text-sm); font-weight: 500; color: var(--text-primary); margin-right: auto; }
-/* Top-of-page controls: Copy page + prev/next chevrons on the title row. */
-.page-actions {
-  display: flex; justify-content: flex-end; align-items: center; gap: 2px;
-  margin-bottom: -2.4rem; position: relative; z-index: 2;
+
+/* Multi-page set tabs — the docs' top tab row: muted labels, the current
+   page in primary with a 2px underline riding the row's hairline. The row
+   scrolls horizontally (no scrollbar chrome) when the set outgrows the
+   column, so a long set never wraps or truncates. */
+.page-tabs {
+  display: flex; gap: 1.75rem;
+  margin: 0 0 2rem;
+  border-bottom: 1px solid var(--border);
+  overflow-x: auto; scrollbar-width: none;
 }
-.pa-nav {
-  display: inline-flex; align-items: center; justify-content: center;
-  width: 30px; height: 30px; border-radius: 0.5rem;
-  color: var(--text-icon); transition: background-color 0.15s;
+.page-tabs::-webkit-scrollbar { display: none; }
+.page-tab {
+  flex-shrink: 0; white-space: nowrap;
+  padding: 0 0 0.65rem;
+  font-size: var(--text-sm); color: var(--text-muted);
+  text-decoration: none;
+  border-bottom: 2px solid transparent; margin-bottom: -1px;
 }
-.pa-nav:hover { background: var(--surface-active); opacity: 1; }
-.pa-nav.is-disabled { opacity: 0.35; pointer-events: none; }
+a.page-tab:hover { color: var(--text-body); opacity: 1; }
+.page-tab.is-active { color: var(--text-primary); font-weight: 500; border-bottom-color: var(--text-primary); }
 
 /* The docs' theme toggle: 30px, rounded-lg, --text-icon, --surface-active hover. */
 .art-theme {
@@ -474,8 +483,8 @@ figcaption { font-size: 0.875em; line-height: 1.4285714; color: var(--text-prima
 .toc-track, .toc-thumb { display: block; }
 .rail ol, .rail ul { list-style: none; margin: 0; padding: 0; }
 /* Chrome links are navigation, not prose: no underline weight or hover fade. */
-.rail a, .page-nav-card { font-weight: 400; transition: none; }
-.rail a:hover, .page-nav-card:hover { opacity: 1; }
+.rail a { font-weight: 400; transition: none; }
+.rail a:hover { opacity: 1; }
 
 .rail[data-rail="toc"] { min-width: 150px; }
 
@@ -558,7 +567,11 @@ figcaption { font-size: 0.875em; line-height: 1.4285714; color: var(--text-prima
    moment step bodies vary in height; a full-height rail that the opaque
    circles paint over is what the docs render. */
 .steps { list-style: none; margin: 1.25rem 0; padding: 0; }
-.step { --step-marker: 28px; position: relative; display: flex; gap: 1rem; padding-bottom: 1.75rem; }
+/* Explicit margin/padding resets: the prose list rules (ol > li's inline-start
+   indent, li's vertical margins) otherwise leak in — the indent shifts the
+   circles off the absolutely-positioned rail, and inter-item margins cut gaps
+   into it. */
+.step { --step-marker: 28px; position: relative; display: flex; gap: 1rem; margin: 0; padding: 0 0 1.75rem; }
 .step:last-child { padding-bottom: 0.25rem; }
 /* The rail spans the whole step, dead-centered under the circle; the last
    step draws none, so the line ends AT the final circle. */
@@ -596,23 +609,6 @@ figcaption { font-size: 0.875em; line-height: 1.4285714; color: var(--text-prima
 .codetab.is-active { background: var(--surface-active); color: var(--text-primary); }
 .codetabs-head .codetabs-copy { position: static; margin-left: auto; }
 
-/* API method chips — sidebar entries only, the docs' reference nav. */
-
-/* Footer pagination — the docs' PageFooter verbatim: name + chevron on a
-   hover pill (mt-12 flex gap-2 py-3; cards flex-1 gap-1.5 rounded-lg px-3
-   py-3 text-sm --text-body, hover --surface-active; chevrons 14px
-   --text-icon; a missing side keeps its half as a spacer). */
-.page-nav { display: flex; gap: 0.5rem; margin-top: 3rem; padding: 0.75rem 0; }
-.page-nav-card {
-  flex: 1; display: flex; align-items: center; gap: 0.375rem; min-width: 0;
-  border-radius: 0.5rem; padding: 0.75rem;
-  font-size: var(--text-sm); font-weight: 400; color: var(--text-body);
-  text-decoration: none; transition: background-color 0.2s;
-}
-.page-nav-card:hover { background: var(--surface-active); opacity: 1; }
-.page-nav-card.next { justify-content: flex-end; }
-.page-nav-card svg { flex-shrink: 0; color: var(--text-icon); }
-.page-nav-spacer { flex: 1; }
 `.trim()
 
 /**
@@ -803,29 +799,6 @@ export const SIM_ARTIFACT_SHELL = `<script>
     }
     cols.append(mid, right)
 
-    // Top-of-page controls: prev/next chevrons on the title row, wired to
-    // the same targets as the footer cards.
-    const CHEV_L = '<svg ' + ICON_ATTRS + '><path d="M13.25 3L6.25 10.25L13.25 17.5"/></svg>'
-    const CHEV_R = '<svg ' + ICON_ATTRS + '><path d="M6.25 3L13.25 10.25L6.25 17.5"/></svg>'
-    const actions = document.createElement('div')
-    actions.className = 'page-actions'
-    const prevCard = page.querySelector('.page-nav-card.prev')
-    const nextCard = page.querySelector('.page-nav-card.next')
-    if (prevCard || nextCard) {
-      const mkNav = (card, svg, label) => {
-        const a = document.createElement('a')
-        a.className = 'pa-nav'
-        a.setAttribute('aria-label', label)
-        const href = card ? card.getAttribute('href') : null
-        if (href) a.href = href
-        else a.classList.add('is-disabled')
-        a.innerHTML = svg
-        return a
-      }
-      actions.append(mkNav(prevCard, CHEV_L, 'Previous page'), mkNav(nextCard, CHEV_R, 'Next page'))
-    }
-    if (actions.childElementCount > 0) mid.insertBefore(actions, mid.firstChild)
-
     // Clerk track geometry (fumadocs clerk.js): one path threading every item,
     // vertical through each and a cubic easing across depth changes.
     const lineOffset = (depth) => (depth === '2' ? 8 : 16)

apps/sim/lib/workspace-files/page-compile.test.ts

@@ -146,23 +146,33 @@ describe('compileSimPage', () => {
     expect(html).toContain('src="/api/files/view/img9"')
   })
 
-  it('keeps a lone next card right-aligned with a spacer', () => {
-    const html = compileSimPage('---\ntitle: T\nnext: "[API](sim:file/b)"\n---\nBody.')
-    expect(html).toContain('<div class="page-nav-spacer"></div><a class="page-nav-card next"')
+  it('renders the tabs frontmatter as the docs tab row above the title', () => {
+    const html = compileSimPage(
+      '---\ntitle: Overview\ntabs:\n  - "Overview"\n  - "[API Reference](sim:file/b)"\n  - "[CLI](sim:file/c)"\n---\nBody.',
+      { workspaceId: 'ws1' }
+    )
+    expect(html).toContain('<nav class="page-tabs" aria-label="Pages">')
+    // The bare-label entry IS this page: the active, unlinked tab.
+    expect(html).toContain('<span class="page-tab is-active">Overview</span>')
+    // Linked entries resolve through the normal sim: link pass.
+    expect(html).toContain(
+      '<a class="page-tab" href="/workspace/ws1/files/b" data-sim-link="">API Reference</a>'
+    )
+    // Tabs precede the title, the docs' top-row placement.
+    expect(html.indexOf('page-tabs')).toBeLessThan(html.indexOf('<h1>'))
+  })
+
+  it('renders no tab row for a single page', () => {
+    expect(compileSimPage('---\ntitle: T\n---\nBody.')).not.toContain('page-tabs')
   })
 
-  it('renders frontmatter prev/next as footer pagination cards', () => {
+  it('tolerates prev/next frontmatter without rendering pagination', () => {
     const html = compileSimPage(
       '---\ntitle: T\nprev: "[Getting Started](sim:file/a)"\nnext: "[API Reference](sim:file/b)"\n---\nBody.',
       { workspaceId: 'ws1' }
     )
-    expect(html).toContain('<footer class="page-nav">')
-    expect(html).toContain('class="page-nav-card prev"')
-    expect(html).toContain('Getting Started')
-    expect(html).toContain('href="/workspace/ws1/files/b"')
-    // The docs' PageFooter shape: chevron + name, no Previous/Next labels.
-    expect(html).toContain('M6.25 3L13.25 10.25L6.25 17.5')
-    expect(html).not.toContain('Previous')
+    expect(html).not.toContain('page-nav')
+    expect(html).toContain('Body.')
   })
 
   it('tolerates nav frontmatter without rendering a sidebar', () => {

apps/sim/lib/workspace-files/page-compile.ts

@@ -40,9 +40,17 @@ const frontmatterSchema = z.object({
   eyebrow: z.string().optional(),
   lede: z.string().optional(),
   layout: z.enum(['docs', 'report']).optional(),
-  /** Docs-style footer pagination: a markdown link — `[Title](sim:file/<id>)`. */
+  /** Tolerated for old sources; no longer rendered — sets navigate by tabs. */
   prev: z.string().optional(),
   next: z.string().optional(),
+  /**
+   * Multi-page set navigation, the docs' top tab row: every page of a set
+   * carries the SAME ordered list. Each entry is a markdown link
+   * (`"[API Reference](sim:file/<id>)"`) to a sibling page; the CURRENT
+   * page's entry is its bare label (`"Overview"`), rendered as the active
+   * tab. The row scrolls horizontally when the set outgrows the column.
+   */
+  tabs: z.array(z.string()).min(1).optional(),
   /**
    * The SET's sidebar, docs-style: groups of pages under muted labels. Each
    * page entry is a markdown link; every page of a set carries the same nav.
@@ -66,26 +74,23 @@ const frontmatterSchema = z.object({
 
 const MD_LINK = /^\s*\[([^\]]+)\]\(([^)]+)\)\s*$/
 
-const CHEVRON_ATTRS =
-  'viewBox="-1 -2 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.55" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"'
-const CHEVRON_LEFT = `<svg ${CHEVRON_ATTRS}><path d="M13.25 3L6.25 10.25L13.25 17.5"/></svg>`
-const CHEVRON_RIGHT = `<svg ${CHEVRON_ATTRS}><path d="M6.25 3L13.25 10.25L6.25 17.5"/></svg>`
-
 /**
- * One footer navigation card from a frontmatter `[Title](href)` link — the
- * docs' own PageFooter: the destination name with a direction chevron on a
- * hover pill, no border and no Previous/Next label (the chevron already says
- * which way you are going). A missing side renders a spacer so the other
- * card keeps its half.
+ * The set's tab row above the title — the docs' own top tabs: linked entries
+ * navigate to sibling pages, the bare-label entry IS this page and renders as
+ * the active tab. sim: hrefs resolve through the normal link pass.
  */
-function paginationCard(value: string | undefined, direction: 'prev' | 'next'): string {
-  const match = value?.match(MD_LINK)
-  if (!match) return '<div class="page-nav-spacer"></div>'
-  const [, title, href] = match
-  const name = escapeHtml(title)
-  return direction === 'prev'
-    ? `<a class="page-nav-card prev" href="${escapeHtml(href)}">${CHEVRON_LEFT}${name}</a>`
-    : `<a class="page-nav-card next" href="${escapeHtml(href)}">${name}${CHEVRON_RIGHT}</a>`
+function tabBar(tabs: string[] | undefined): string {
+  if (!tabs || tabs.length === 0) return ''
+  const items = tabs
+    .map((entry) => {
+      const match = entry.match(MD_LINK)
+      if (match) {
+        return `<a class="page-tab" href="${escapeHtml(match[2])}">${escapeHtml(match[1])}</a>`
+      }
+      return `<span class="page-tab is-active">${escapeHtml(entry.trim())}</span>`
+    })
+    .join('')
+  return `<nav class="page-tabs" aria-label="Pages">${items}</nav>`
 }
 
 /** YAML leaves unquoted scalars typed; reject null/objects rather than stringify them. */
@@ -426,14 +431,10 @@ function compileSimPageDocument(source: string, diagnostics?: string[]): string
     '</head>',
     '<body>',
     `<div class="page" data-layout="${meta.layout ?? 'docs'}">`,
+    ...(meta.tabs ? [tabBar(meta.tabs)] : []),
     `<h1>${escapeHtml(meta.title)}</h1>`,
     ...(meta.lede ? [`<p class="lede">${escapeHtml(meta.lede)}</p>`] : []),
     compileBody(rest, diagnostics),
-    ...(meta.prev || meta.next
-      ? [
-          `<footer class="page-nav">${paginationCard(meta.prev, 'prev')}${paginationCard(meta.next, 'next')}</footer>`,
-        ]
-      : []),
     '</div>',
     '</body>',
     '</html>',

apps/sim/lib/workspace-files/shell-layout.test.ts

@@ -30,13 +30,13 @@ describe('shell layout decisions', () => {
     expect(toc.map((a) => a.textContent)).toEqual(['A', 'B', 'C'])
   })
 
-  it('keeps prev/next arrows wired from frontmatter', () => {
-    runShell('---\ntitle: T\nnext: "[Reference](sim:file/b)"\n---\n## Only\n\nx')
-    const next = document.querySelector('.page-actions .pa-nav[aria-label="Next page"]')
-    expect(next?.getAttribute('href')).toBe('sim:file/b')
-    expect(
-      document.querySelector('.page-actions .pa-nav[aria-label="Previous page"]')?.classList
-    ).toContain('is-disabled')
+  it('keeps the set tabs in place and adds no arrow chrome', () => {
+    runShell('---\ntitle: T\ntabs:\n  - "T"\n  - "[Reference](sim:file/b)"\n---\n## Only\n\nx')
+    const tabs = [...document.querySelectorAll('.page-tabs .page-tab')]
+    expect(tabs.map((tab) => tab.textContent)).toEqual(['T', 'Reference'])
+    expect(document.querySelector('.page-tab.is-active')?.textContent).toBe('T')
+    expect(document.querySelector('.page-actions')).toBeNull()
+    expect(document.querySelector('.pa-nav')).toBeNull()
   })
 })