@startsimpli/ui 0.4.31 → 0.4.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -33,8 +33,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "0.5.31",
-    "@startsimpli/auth": "0.4.26"
+    "@startsimpli/auth": "0.4.26",
+    "@startsimpli/api": "0.5.31"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/blog/BlogPost.tsx

@@ -20,7 +20,9 @@ export interface BlogPostProps {
   theme?: 'light' | 'dark'
   /** schema.org JSON-LD object(s) rendered into the page head. */
   structuredData?: object | object[]
-  /** Optional sidebar (TOC, share widgets, CTAs). Rendered right of the content on lg+. */
+  /** Left-rail outline, e.g. `<TableOfContents content={post.content} />`. Sticky on lg+. */
+  toc?: ReactNode
+  /** Optional sidebar (share widgets, CTAs). Rendered right of the content on lg+. */
   sidebar?: ReactNode
   className?: string
 }
@@ -38,6 +40,7 @@ export function BlogPost({
   byline,
   theme = 'light',
   structuredData,
+  toc,
   sidebar,
   className,
 }: BlogPostProps) {
@@ -46,6 +49,15 @@ export function BlogPost({
     ? new Date(post.publishedAt).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' })
     : null
 
+  const mainColClass =
+    toc && sidebar
+      ? 'lg:col-span-6'
+      : toc
+        ? 'lg:col-span-9'
+        : sidebar
+          ? 'lg:col-span-8'
+          : 'max-w-3xl mx-auto w-full'
+
   return (
     <article className={cn('py-12', className)}>
       {structuredData && <JsonLd data={structuredData} />}
@@ -68,8 +80,13 @@ export function BlogPost({
           </ol>
         </nav>
 
-        <div className={cn('grid grid-cols-1 gap-8', sidebar ? 'lg:grid-cols-12' : '')}>
-          <div className={sidebar ? 'lg:col-span-8' : 'max-w-3xl mx-auto w-full'}>
+        <div className={cn('grid grid-cols-1 gap-8 lg:gap-10', toc || sidebar ? 'lg:grid-cols-12' : '')}>
+          {toc && (
+            <aside className="hidden lg:block lg:col-span-3 order-first">
+              <div className="sticky top-8">{toc}</div>
+            </aside>
+          )}
+          <div className={mainColClass}>
             <h1 className="font-heading text-4xl md:text-5xl font-bold text-foreground mb-6">{post.title}</h1>
 
             <div className="flex items-center gap-4 mb-8 pb-8 border-b border-border text-sm text-muted-foreground">
@@ -106,7 +123,7 @@ export function BlogPost({
           </div>
 
           {sidebar && (
-            <aside className="lg:col-span-4">
+            <aside className={toc ? 'lg:col-span-3' : 'lg:col-span-4'}>
               <div className="sticky top-8 space-y-6">{sidebar}</div>
             </aside>
           )}

package/src/components/blog/TableOfContents.tsx

@@ -0,0 +1,96 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import { cn } from '../../utils/cn'
+
+/** Must match MarkdownRenderer's heading id slugify exactly so anchors line up. */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+}
+
+export interface TocItem {
+  id: string
+  text: string
+  level: number
+}
+
+/** Parse markdown headings (#, ##, ###) into a flat outline, skipping fenced code. */
+export function extractToc(content: string): TocItem[] {
+  const items: TocItem[] = []
+  let inCode = false
+  for (const raw of content.split('\n')) {
+    const line = raw.trimEnd()
+    if (/^\s*```/.test(line)) {
+      inCode = !inCode
+      continue
+    }
+    if (inCode) continue
+    const m = /^(#{1,3})\s+(.+?)\s*#*$/.exec(line)
+    if (!m) continue
+    const text = m[2].replace(/[*_`]/g, '').trim()
+    const id = slugify(text)
+    if (!id) continue
+    items.push({ id, text, level: m[1].length })
+  }
+  return items
+}
+
+export interface TableOfContentsProps {
+  content: string
+  title?: string
+  className?: string
+}
+
+/**
+ * Sticky left-rail outline for an article, with scroll-spy highlighting.
+ * Renders nothing for content with fewer than 2 headings.
+ */
+export function TableOfContents({ content, title = 'On this page', className }: TableOfContentsProps) {
+  const items = useMemo(() => extractToc(content), [content])
+  const [activeId, setActiveId] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (items.length < 2) return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) setActiveId(entry.target.id)
+        }
+      },
+      { rootMargin: '0px 0px -70% 0px', threshold: 0 },
+    )
+    items.forEach((it) => {
+      const el = document.getElementById(it.id)
+      if (el) observer.observe(el)
+    })
+    return () => observer.disconnect()
+  }, [items])
+
+  if (items.length < 2) return null
+
+  return (
+    <nav className={cn('text-sm', className)} aria-label="Table of contents">
+      <p className="font-heading text-xs font-semibold uppercase tracking-wide text-muted-foreground mb-3">{title}</p>
+      <ul className="border-l border-border">
+        {items.map((it) => (
+          <li key={it.id} style={{ paddingLeft: `${(Math.min(it.level, 3) - 1) * 12}px` }}>
+            <a
+              href={`#${it.id}`}
+              className={cn(
+                'block -ml-px border-l-2 pl-3 py-1 transition-colors',
+                activeId === it.id
+                  ? 'border-primary text-primary font-medium'
+                  : 'border-transparent text-muted-foreground hover:text-foreground',
+              )}
+            >
+              {it.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

package/src/components/blog/index.ts

@@ -11,3 +11,4 @@ export { MarkdownRenderer, type MarkdownRendererProps } from './MarkdownRenderer
 export { ArticleCard, type ArticleCardProps } from './ArticleCard'
 export { BlogIndex, type BlogIndexProps } from './BlogIndex'
 export { BlogPost, type BlogPostProps } from './BlogPost'
+export { TableOfContents, extractToc, type TableOfContentsProps, type TocItem } from './TableOfContents'