@uniweb/kit 0.9.33 → 0.9.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.33",
+  "version": "0.9.34",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.26",
+    "@uniweb/core": "0.7.27",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/hooks/index.js

@@ -9,6 +9,7 @@ export { useVersion } from './useVersion.js'
 export { useScrolled } from './useScrolled.js'
 export { useMobileMenu } from './useMobileMenu.js'
 export { useAccordion } from './useAccordion.js'
+export { useHeadings } from './useHeadings.js'
 export { useGridLayout, getGridClasses } from './useGridLayout.js'
 export { useTheme, getThemeClasses, THEMES, THEME_NAMES } from './useTheme.js'
 export { useInView, useIsInView } from './useInView.js'

package/src/hooks/useHeadings.js

@@ -0,0 +1,201 @@
+/**
+ * useHeadings Hook
+ *
+ * The headings of the page being read, plus which one the reader is level with.
+ * What a table of contents needs, without any opinion about how it looks.
+ *
+ * Every documentation shell on this framework has hand-written this, and each
+ * one wrote it the only way a foundation can: scan the DOM for `h2, h3` after
+ * the body renders. That works, but it costs a frame of timing guesswork and it
+ * cannot run during prerender, so the rail is missing from every served page
+ * until hydration.
+ *
+ * The framework can do better because it owns both ends. It renders the
+ * headings and stamps their ids (`headingId`), and it holds the page content
+ * that produced them — so the list can come from the content, before anything
+ * is painted, and be guaranteed to match the anchors. Only the highlight needs
+ * the DOM, because only scrolling does.
+ *
+ * @example
+ * function PageContents() {
+ *   const { headings, activeId, scrollTo } = useHeadings()
+ *   if (!headings.length) return null
+ *
+ *   return (
+ *     <nav aria-label="On this page">
+ *       {headings.map(h => (
+ *         <button key={h.id} onClick={() => scrollTo(h.id)}
+ *                 className={h.id === activeId ? 'text-primary' : 'text-subtle'}>
+ *           {h.text}
+ *         </button>
+ *       ))}
+ *     </nav>
+ *   )
+ * }
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { headingId, nodeText } from '../utils/index.js'
+import { useWebsite } from './useWebsite.js'
+import { useActiveRoute } from './useActiveRoute.js'
+
+/**
+ * Pull headings out of the page's own content — available during prerender.
+ */
+function headingsFromContent(page, levels) {
+  const blocks = page?.getBodyBlocks?.() ?? []
+  const found = []
+
+  for (const block of blocks) {
+    const nodes = block?.rawContent?.content
+    if (!Array.isArray(nodes)) continue
+
+    for (const node of nodes) {
+      if (node?.type !== 'heading') continue
+      const level = node.attrs?.level ?? 1
+      if (!levels.includes(level)) continue
+
+      const text = nodeText(node).trim()
+      if (text) found.push({ id: headingId(text), text, level })
+    }
+  }
+
+  return found
+}
+
+/**
+ * Fall back to the rendered document, for content this hook cannot see — a
+ * foundation rendering its own markup, or anything not built from page blocks.
+ */
+function headingsFromDom(root, levels) {
+  if (typeof document === 'undefined') return []
+
+  const scope = document.querySelector(root)
+  if (!scope) return []
+
+  const selector = levels.map(level => `h${level}`).join(', ')
+
+  return [...scope.querySelectorAll(selector)]
+    .map(el => {
+      const text = el.textContent?.trim() || ''
+      if (!text) return null
+      // Adopt the id that is there; stamp the shared one when it is missing, so
+      // scrollTo has something to find either way.
+      if (!el.id) el.id = headingId(text)
+      return { id: el.id, text, level: Number(el.tagName[1]) }
+    })
+    .filter(Boolean)
+}
+
+/**
+ * Nest a flat, ordered heading list by level. A heading deeper than the one
+ * before it becomes its child; anything at or above the top level starts a new
+ * branch. Headings that skip a level still land somewhere sensible.
+ */
+function nest(flat) {
+  if (!flat.length) return []
+
+  const topLevel = Math.min(...flat.map(h => h.level))
+  const tree = []
+  let current = null
+
+  for (const heading of flat) {
+    const node = { ...heading, children: [] }
+    if (heading.level === topLevel || !current) {
+      tree.push(node)
+      current = node
+    } else {
+      current.children.push(node)
+    }
+  }
+
+  return tree
+}
+
+/**
+ * Height of the fixed site header, so anchors are not scrolled under it.
+ */
+function headerOffset(explicit) {
+  if (typeof explicit === 'number') return explicit
+  if (typeof document === 'undefined') return 0
+
+  const declared = getComputedStyle(document.documentElement).getPropertyValue('--header-height')
+  return (parseInt(declared, 10) || 0) + 16
+}
+
+/**
+ * @param {Object} [options]
+ * @param {number[]} [options.levels=[2,3]] - Heading levels to collect
+ * @param {string} [options.root='main'] - Selector to scan, for the DOM fallback
+ * @param {number} [options.offset] - Scroll offset in px; defaults to the site
+ *   header's height read from `--header-height`, plus a little breathing room
+ * @returns {{ headings: Array, activeId: string, scrollTo: (id: string) => void }}
+ *   `headings` is nested — each entry carries `{ id, text, level, children }`
+ */
+export function useHeadings({ levels = [2, 3], root = 'main', offset } = {}) {
+  const { website } = useWebsite()
+  const { route } = useActiveRoute()
+  const [domHeadings, setDomHeadings] = useState(null)
+  const [activeId, setActiveId] = useState('')
+
+  // The content path runs during render, so it is available server-side.
+  const contentHeadings = useMemo(
+    () => headingsFromContent(website?.activePage, levels),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [website?.activePage, route, levels.join()]
+  )
+
+  // Only reached when the content path found nothing.
+  useEffect(() => {
+    setActiveId('')
+    if (contentHeadings.length) {
+      setDomHeadings(null)
+      return
+    }
+    const id = requestAnimationFrame(() => setDomHeadings(headingsFromDom(root, levels)))
+    return () => cancelAnimationFrame(id)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [route, contentHeadings.length, root, levels.join()])
+
+  const flat = contentHeadings.length ? contentHeadings : domHeadings ?? []
+  const headings = useMemo(() => nest(flat), [flat])
+
+  // Which heading the reader is level with. Scroll position is the one thing
+  // here that only the DOM knows.
+  useEffect(() => {
+    if (!flat.length || typeof window === 'undefined') return
+
+    const gap = headerOffset(offset)
+
+    function onScroll() {
+      const line = window.scrollY + gap + 4
+      let current = ''
+      for (const { id } of flat) {
+        const el = document.getElementById(id)
+        if (el && el.getBoundingClientRect().top + window.scrollY <= line) current = id
+      }
+      setActiveId(current || flat[0].id)
+    }
+
+    window.addEventListener('scroll', onScroll, { passive: true })
+    onScroll()
+    return () => window.removeEventListener('scroll', onScroll)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [flat.map(h => h.id).join(), offset])
+
+  const scrollTo = useCallback(
+    id => {
+      const el = typeof document !== 'undefined' && document.getElementById(id)
+      if (!el) return
+      window.scrollTo({
+        top: el.getBoundingClientRect().top + window.scrollY - headerOffset(offset),
+        behavior: 'smooth',
+      })
+    },
+    [offset]
+  )
+
+  return { headings, activeId, scrollTo }
+}
+
+export default useHeadings

package/src/index.js

@@ -62,6 +62,7 @@ export {
   useScrolled,
   useMobileMenu,
   useAccordion,
+  useHeadings,
   useGridLayout,
   getGridClasses,
   useTheme,
@@ -99,6 +100,10 @@ export {
   parseIconRef,
   // Content utilities
   splitContent,
+  // Heading anchors — one generator, shared by the renderers that stamp them
+  // and by anything that links to one (see useHeadings).
+  headingId,
+  nodeText,
   // Href resolution (for foundations rendering their own links or prose HTML)
   applyBasePath,
   resolveRoute,

package/src/styled/Prose/index.jsx

@@ -11,7 +11,7 @@
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer } from '../../utils/index.js'
+import { cn, getChildBlockRenderer, headingId } from '../../utils/index.js'
 import { SafeHtml } from '../../components/SafeHtml/index.js'
 import { Image } from '../../components/Image/index.js'
 import { Media } from '../../components/Media/index.js'
@@ -30,13 +30,6 @@ const SIZE_CLASSES = {
   '2xl': 'prose-2xl'
 }
 
-function generateId(text) {
-  return text
-    .replace(/<[^>]*>/g, '')
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-}
 
 const INLINE_INSET_RE = /<uniweb-inset data-ref-id="([^"]+)"><\/uniweb-inset>/g
 
@@ -92,7 +85,7 @@ function SequenceElement({ element, block }) {
     case 'heading': {
       const level = Math.min(element.level || 1, 6)
       const Tag = `h${level}`
-      const id = generateId(element.text || '')
+      const id = headingId(element.text || '')
       return <Tag id={id}><SafeHtml value={element.text} as="span" /></Tag>
     }
 

package/src/styled/Section/Render.jsx

@@ -8,7 +8,7 @@
  */
 
 import React from 'react'
-import { cn, getChildBlockRenderer } from '../../utils/index.js'
+import { cn, getChildBlockRenderer, headingId } from '../../utils/index.js'
 import { SafeHtml } from '../../components/SafeHtml/index.js'
 import { Image } from '../../components/Image/index.js'
 import { Media } from '../../components/Media/index.js'
@@ -33,15 +33,6 @@ function extractText(node) {
   return ''
 }
 
-/**
- * Generate ID from heading text
- */
-function generateId(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-|-$/g, '')
-}
 
 /**
  * Render a list (ordered or unordered)
@@ -81,7 +72,7 @@ function RenderNode({ node, block, ...props }) {
     case 'heading': {
       const level = attrs?.level || 1
       const text = extractText(node)
-      const id = generateId(text)
+      const id = headingId(text)
       const Tag = `h${Math.min(level, 6)}`
 
       return (

package/src/styled/Section/renderers/Code.jsx

@@ -1,9 +1,10 @@
 /**
  * Code Block Renderer
  *
- * Renders syntax-highlighted code blocks using Shiki.
- * Shiki is lazy-loaded only when code blocks are actually used,
- * and CSS variables are injected at runtime from theme.code.
+ * Renders syntax-highlighted code blocks using Shiki, lazy-loaded only when a
+ * page actually has one. A site's `theme.yml` `code:` block becomes a Shiki
+ * theme layered over the default, so the colours a site declares are the
+ * colours Shiki writes.
  *
  * @module @uniweb/kit/Section/renderers/Code
  */
@@ -16,37 +17,90 @@ import { getUniweb } from '@uniweb/core'
 let cssInjected = false
 let shikiInstance = null
 let shikiLoadPromise = null
+let siteThemeLoaded = false
+
+// What a site gets when it declares no `code:` block of its own, and the base
+// every declaration layers over.
+const DEFAULT_THEME = 'github-dark'
 
 /**
- * Map theme.code keys to Shiki CSS variable names
+ * Where each documented `theme.code` key lands in TextMate scope terms.
+ *
+ * Shiki colours by scope, so a declaration only reaches the output by becoming
+ * a scope rule. This used to map the same keys onto `--shiki-*` CSS variables,
+ * which could never take effect: Shiki writes its theme as an inline style on
+ * the <pre> and on every token span, and an inline style outranks any
+ * stylesheet. The `code:` block was documented, parsed, and inert.
+ *
+ * `lineNumber` and `selection` are deliberately absent. They are editor chrome,
+ * not token scopes, and Shiki's HTML has neither.
+ */
+const SCOPE_MAP = {
+  comment: ['comment', 'punctuation.definition.comment'],
+  string: ['string', 'string.quoted', 'constant.other.symbol'],
+  keyword: ['keyword', 'storage', 'storage.type', 'keyword.control'],
+  operator: ['keyword.operator'],
+  function: ['entity.name.function', 'support.function', 'meta.function-call'],
+  variable: ['variable', 'variable.other.readwrite'],
+  number: ['constant.numeric'],
+  constant: ['constant.language', 'constant.character', 'support.constant'],
+  type: ['entity.name.type', 'entity.name.class', 'support.type', 'support.class'],
+  property: ['variable.other.property', 'support.type.property-name', 'meta.object-literal.key'],
+  tag: ['entity.name.tag'],
+  attribute: ['entity.other.attribute-name'],
+  punctuation: ['punctuation'],
+}
+
+export const SITE_CODE_THEME = 'uniweb-site-code'
+
+/**
+ * Build a Shiki theme from a site's `theme.yml` `code:` block, layered over a
+ * base theme.
+ *
+ * Layering rather than replacing is the point. Most sites declare `background:`
+ * alone — "the same highlighting, on my surface" — and building a theme from
+ * only the declared keys would strip every syntax colour to answer that. So the
+ * base supplies everything, and each declared key overrides its own scopes.
+ *
+ * @param {Object} base - A resolved Shiki theme to layer over
+ * @param {Object} code - The site's `theme.code` declaration
+ * @returns {Object} A Shiki theme registration
  */
-const CSS_VAR_MAP = {
-  background: '--shiki-background',
-  foreground: '--shiki-foreground',
-  keyword: '--shiki-token-keyword',
-  string: '--shiki-token-string',
-  number: '--shiki-token-constant',
-  comment: '--shiki-token-comment',
-  function: '--shiki-token-function',
-  variable: '--shiki-token-variable',
-  operator: '--shiki-token-operator',
-  punctuation: '--shiki-token-punctuation',
-  type: '--shiki-token-type',
-  constant: '--shiki-token-constant',
-  property: '--shiki-token-property',
-  tag: '--shiki-token-tag',
-  attribute: '--shiki-token-attribute',
-  lineNumber: '--shiki-line-number',
-  selection: '--shiki-selection',
+export function buildCodeTheme(base, code) {
+  const theme = {
+    ...base,
+    name: SITE_CODE_THEME,
+    colors: { ...base?.colors },
+    // Declared scopes go last so they win over the base's own rules.
+    settings: [...(base?.settings ?? [])],
+  }
+
+  if (code?.background) {
+    theme.bg = code.background
+    theme.colors['editor.background'] = code.background
+  }
+  if (code?.foreground) {
+    theme.fg = code.foreground
+    theme.colors['editor.foreground'] = code.foreground
+  }
+
+  for (const [key, scope] of Object.entries(SCOPE_MAP)) {
+    if (code?.[key]) theme.settings.push({ scope, settings: { foreground: code[key] } })
+  }
+
+  return theme
 }
 
 /**
- * Inject CSS variables from theme.code into the document
+ * Layout for the highlighted block. Colour is not set here — Shiki writes the
+ * theme's own inline, and the theme is now the site's (see buildCodeTheme).
+ * What is left is spacing and the code face, so a listing is legible before a
+ * foundation styles it, without kit deciding what colour anything is.
  */
-function injectCodeThemeCSS(codeTheme) {
+function injectCodeLayoutCSS() {
   if (cssInjected || typeof document === 'undefined') return
 
-  const styleId = 'uniweb-code-theme'
+  const styleId = 'uniweb-code-layout'
 
   // Check if already injected (e.g., by another component instance)
   if (document.getElementById(styleId)) {
@@ -54,38 +108,15 @@ function injectCodeThemeCSS(codeTheme) {
     return
   }
 
-  // Build CSS variables
-  const cssVars = []
-  for (const [key, value] of Object.entries(codeTheme || {})) {
-    const varName = CSS_VAR_MAP[key]
-    if (varName && value) {
-      cssVars.push(`${varName}: ${value};`)
-    }
-  }
-
-  // Create and inject style element
   const style = document.createElement('style')
   style.id = styleId
   style.textContent = `
-:root {
-  ${cssVars.join('\n  ')}
-}
-
-/* Code block base styles */
 .shiki {
-  background-color: var(--shiki-background, #1e1e2e);
-  color: var(--shiki-foreground, #cdd6f4);
   padding: 1rem;
   border-radius: 0.5rem;
   overflow-x: auto;
 }
 
-/* Ensure proper token colors */
-.shiki span {
-  color: var(--shiki-token-foreground, inherit);
-}
-
-/* Code element inside shiki */
 .shiki code {
   display: block;
   font-family: var(--font-code, ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace);
@@ -138,13 +169,33 @@ async function loadShiki() {
   return shikiLoadPromise
 }
 
+/**
+ * Register the site's `code:` declaration as a theme, once, and answer with the
+ * theme name to highlight against. Sites that declare nothing get the default.
+ */
+async function resolveThemeName(highlighter, codeTheme) {
+  if (!codeTheme || Object.keys(codeTheme).length === 0) return DEFAULT_THEME
+  if (siteThemeLoaded) return SITE_CODE_THEME
+
+  try {
+    await highlighter.loadTheme(buildCodeTheme(highlighter.getTheme(DEFAULT_THEME), codeTheme))
+    siteThemeLoaded = true
+    return SITE_CODE_THEME
+  } catch (error) {
+    console.warn('[Code] Could not apply theme.code, using the default:', error)
+    return DEFAULT_THEME
+  }
+}
+
 /**
  * Highlight code using Shiki
  */
-async function highlightCode(code, language, highlighter) {
+async function highlightCode(code, language, highlighter, codeTheme) {
   if (!highlighter) return null
 
   try {
+    const theme = await resolveThemeName(highlighter, codeTheme)
+
     // Load language if not already loaded
     const loadedLangs = highlighter.getLoadedLanguages()
     const lang = language?.toLowerCase() || 'plaintext'
@@ -154,16 +205,13 @@ async function highlightCode(code, language, highlighter) {
         await highlighter.loadLanguage(lang)
       } catch {
         // Language not available, fall back to plaintext
-        return highlighter.codeToHtml(code, {
-          lang: 'plaintext',
-          theme: 'github-dark',
-        })
+        return highlighter.codeToHtml(code, { lang: 'plaintext', theme })
       }
     }
 
     return highlighter.codeToHtml(code, {
       lang: lang === 'plaintext' ? 'text' : lang,
-      theme: 'github-dark',
+      theme,
     })
   } catch (error) {
     console.warn('[Code] Highlighting failed:', error)
@@ -207,12 +255,11 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     return aliases[l] || l
   }, [language])
 
-  // Inject CSS on first render (if in browser)
+  // Inject layout CSS on first render (if in browser). Unlike the colours, this
+  // is wanted whether or not the site declared a `code:` block.
   useEffect(() => {
-    if (typeof document !== 'undefined' && codeTheme) {
-      injectCodeThemeCSS(codeTheme)
-    }
-  }, [codeTheme])
+    injectCodeLayoutCSS()
+  }, [])
 
   // Load Shiki and highlight code
   useEffect(() => {
@@ -223,7 +270,7 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
       if (cancelled) return
 
       if (highlighter && content) {
-        const html = await highlightCode(content, lang, highlighter)
+        const html = await highlightCode(content, lang, highlighter, codeTheme)
         if (!cancelled) {
           setHighlightedHtml(html)
         }
@@ -235,7 +282,7 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     return () => {
       cancelled = true
     }
-  }, [content, lang])
+  }, [content, lang, codeTheme])
 
   // Render highlighted code or fallback
   if (highlightedHtml) {
@@ -248,18 +295,19 @@ export function Code({ content, language = 'plaintext', className, ...props }) {
     )
   }
 
-  // Fallback: plain code block (shown before Shiki loads or if it fails)
-  // No loading indicator - the code content is already visible and readable.
-  // When Shiki loads, syntax colors will appear smoothly.
+  // Fallback: plain code block (shown before Shiki loads or if it fails).
+  // No loading indicator — the code is already readable, and the syntax colours
+  // arrive when Shiki does. Semantic tokens, so the wait looks like the site
+  // rather than like a fixed grey no theme asked for.
   return (
     <pre
       className={cn(
-        'overflow-x-auto rounded-lg bg-gray-900 p-4 text-sm',
+        'overflow-x-auto rounded-lg bg-muted p-4 text-sm text-body',
         className
       )}
       {...props}
     >
-      <code className={`language-${lang} text-gray-100`}>
+      <code className={`language-${lang}`}>
         {content}
       </code>
     </pre>

package/src/styled/SidebarLayout/SidebarLayout.jsx

@@ -76,14 +76,15 @@ function MobileDrawer({ isOpen, onClose, width, stickyHeader, children }) {
   }, [isOpen])
 
   // Position below header if sticky, otherwise from top
-  const topOffset = stickyHeader ? 'top-16' : 'top-0'
-  const height = stickyHeader ? 'h-[calc(100vh-4rem)]' : 'h-screen'
+  const topOffset = stickyHeader ? 'top-[var(--header-height,4rem)]' : 'top-0'
+  const height = stickyHeader ? 'h-[calc(100vh-var(--header-height,4rem))]' : 'h-screen'
 
   return (
     <>
       {/* Backdrop */}
       <div
         className={cn(
+          // kit-palette-ok: a modal scrim is the same black in either scheme
           'fixed inset-0 bg-black/50 z-40 transition-opacity duration-300',
           isOpen ? 'opacity-100' : 'opacity-0 pointer-events-none'
         )}
@@ -94,7 +95,7 @@ function MobileDrawer({ isOpen, onClose, width, stickyHeader, children }) {
       {/* Drawer (always from left) */}
       <div
         className={cn(
-          'fixed left-0 bg-white z-50 shadow-xl',
+          'fixed left-0 bg-section z-50 shadow-xl',
           topOffset,
           height,
           width,
@@ -108,10 +109,10 @@ function MobileDrawer({ isOpen, onClose, width, stickyHeader, children }) {
         {/* Close button */}
         <button
           onClick={onClose}
-          className="absolute top-4 right-4 p-1.5 rounded-md hover:bg-gray-100 transition-colors"
+          className="absolute top-4 right-4 p-1.5 rounded-md hover:bg-muted transition-colors"
           aria-label="Close sidebar"
         >
-          <CloseIcon className="w-5 h-5 text-gray-500" />
+          <CloseIcon className="w-5 h-5 text-subtle" />
         </button>
 
         {/* Drawer content */}
@@ -132,7 +133,7 @@ function FloatingMenuButton({ onClick }) {
       onClick={onClick}
       className={cn(
         'fixed bottom-4 left-4 z-30',
-        'p-3 bg-primary text-white rounded-full shadow-lg',
+        'p-3 bg-primary text-primary-foreground rounded-full shadow-lg',
         'hover:bg-primary/90 active:scale-95 transition-all',
         'focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2'
       )}
@@ -223,17 +224,17 @@ export function SidebarLayout({
     : ''
 
   const sidebarClasses = stickySidebar && stickyHeader
-    ? 'sticky top-16 h-[calc(100vh-4rem)]'
+    ? 'sticky top-[var(--header-height,4rem)] h-[calc(100vh-var(--header-height,4rem))]'
     : stickySidebar
       ? 'sticky top-0 h-screen'
       : ''
 
   return (
-    <div className={cn('min-h-screen flex flex-col bg-white', className)}>
+    <div className={cn('min-h-screen flex flex-col bg-section', className)}>
       {/* Header */}
       {header && (
         <header className={cn(
-          'w-full border-b border-gray-200 bg-white/95 backdrop-blur supports-[backdrop-filter]:bg-white/80',
+          'w-full border-b border-border bg-section/95 backdrop-blur supports-[backdrop-filter]:bg-section/80',
           headerClasses
         )}>
           {header}
@@ -260,7 +261,7 @@ export function SidebarLayout({
           {/* Left Sidebar (desktop) */}
           {leftContent && (
             <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-r border-gray-200',
+              'hidden flex-shrink-0 overflow-y-auto border-r border-border',
               leftClasses.showClass,
               leftWidth,
               sidebarClasses
@@ -279,7 +280,7 @@ export function SidebarLayout({
           {/* Right Sidebar (desktop only, hidden on mobile) */}
           {rightContent && (
             <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-l border-gray-200',
+              'hidden flex-shrink-0 overflow-y-auto border-l border-border',
               rightClasses.showClass,
               rightWidth,
               sidebarClasses
@@ -292,7 +293,7 @@ export function SidebarLayout({
 
       {/* Footer */}
       {footer && (
-        <footer className="w-full border-t border-gray-200">
+        <footer className="w-full border-t border-border">
           {footer}
         </footer>
       )}

package/src/utils/index.js

@@ -248,3 +248,37 @@ export function detectMediaType(url) {
 // ─────────────────────────────────────────────────────────────────
 
 export { submitForm, derivePreviewFromFormData } from './submitForm.js'
+
+/**
+ * The text of a ProseMirror node, flattened.
+ *
+ * @param {Object|string} node - A ProseMirror node
+ * @returns {string}
+ */
+export function nodeText(node) {
+  if (!node) return ''
+  if (typeof node === 'string') return node
+  if (node.text) return node.text
+  if (node.content) return node.content.map(nodeText).join('')
+  return ''
+}
+
+/**
+ * The anchor id for a heading.
+ *
+ * One generator, used by every renderer that stamps a heading and by anything
+ * that links to one. That agreement is the whole point: a table of contents
+ * scrolls to an id some other module produced, so a second implementation is a
+ * drift waiting to happen — and there were two, differing in whether they
+ * stripped markup first, which decided whether a heading containing a link got
+ * a usable anchor.
+ *
+ * @param {string} text - Heading text, plain or containing markup
+ * @returns {string}
+ */
+export function headingId(text) {
+  return stripTags(String(text ?? ''))
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}