@life-and-dev/mdsite 0.5.0 → 0.5.2

package/mdsite-nuxt/app/components/AppTableOfContents.vue

@@ -1,11 +1,20 @@
 <template>
-  <div class="toc-sidebar" ref="tocContainer">
+  <!--
+    Guard at the root: the consuming composable's `shouldShowTOC` already
+    requires `tocItems.length >= TOC_MIN_HEADINGS (3)`, so by the time we
+    reach this template a usable TOC is guaranteed. Render nothing otherwise.
+  -->
+  <div
+    v-if="tocItems.length >= 3"
+    class="toc-sidebar"
+    ref="tocContainer"
+  >
     <!-- Header -->
     <h3 v-if="showHeader" class="toc-header">On This Page</h3>
     <v-divider v-if="showHeader" class="mb-2" />
 
     <!-- TOC Items -->
-    <nav v-if="tocItems.length >= 3" class="toc-nav">
+    <nav class="toc-nav">
       <TocItem
         v-for="item in tocItems"
         :key="item.id"
@@ -15,11 +24,6 @@
       />
     </nav>
 
-    <!-- Empty state -->
-    <div v-else class="toc-empty">
-      <p class="text-caption text-center">No table of contents available</p>
-    </div>
-
     <!-- Fade gradient for overflow -->
     <div v-if="showFade" class="fade-gradient" />
   </div>
@@ -122,16 +126,6 @@ watch(() => props.tocItems, () => {
   scrollbar-width: none;
 }
 
-.toc-empty {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 32px 16px;
-  color: rgb(var(--v-theme-on-surface-rail));
-  opacity: 0.6;
-}
-
 .fade-gradient {
   position: absolute;
   bottom: 0;

package/mdsite-nuxt/app/composables/useSiteConfig.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for the pure `mapSiteConfig` helper extracted from
+ * `useSiteConfig`. The `sourceEdit` Edit-on-GitHub link in `AppBar` and
+ * `AppFooter` is only rendered when `getEditUrl()` produces a URL, which
+ * in turn requires `contentGitRepo` to be populated from `server.repo`.
+ * These tests pin that mapping down so a future refactor cannot regress
+ * it back to the empty-string default.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { mapSiteConfig } from './useSiteConfig'
+
+describe('mapSiteConfig', () => {
+  it('returns safe defaults when siteConfig is undefined', () => {
+    const result = mapSiteConfig(undefined, undefined)
+
+    expect(result).toEqual({
+      siteName: '',
+      siteCanonical: '',
+      contentGitRepo: '',
+      contentGitBranch: 'main',
+      contentGitPath: '.',
+      contentPath: '.',
+      features: {
+        bibleTooltips: false,
+        sourceEdit: false
+      },
+      themeColorLight: '#000000',
+      themeColorDark: '#ffffff'
+    })
+  })
+
+  it('reads site metadata from site.name and site.canonical', () => {
+    const result = mapSiteConfig({
+      site: { name: 'My Site', canonical: 'https://example.test' }
+    }, undefined)
+
+    expect(result.siteName).toBe('My Site')
+    expect(result.siteCanonical).toBe('https://example.test')
+  })
+
+  describe('contentGitRepo (Edit on GitHub source)', () => {
+    it('reads server.repo into contentGitRepo', () => {
+      const result = mapSiteConfig({
+        server: { repo: 'https://github.com/life-and-dev/mdsite' }
+      }, undefined)
+
+      expect(result.contentGitRepo).toBe('https://github.com/life-and-dev/mdsite')
+    })
+
+    it('defaults to empty string when server.repo is missing', () => {
+      const result = mapSiteConfig({ server: {} }, undefined)
+
+      expect(result.contentGitRepo).toBe('')
+    })
+
+    it('defaults to empty string when server is missing entirely', () => {
+      const result = mapSiteConfig({}, undefined)
+
+      expect(result.contentGitRepo).toBe('')
+    })
+  })
+
+  describe('features', () => {
+    it('defaults both feature flags to false when features is missing', () => {
+      const result = mapSiteConfig({}, undefined)
+
+      expect(result.features.bibleTooltips).toBe(false)
+      expect(result.features.sourceEdit).toBe(false)
+    })
+
+    it('reads sourceEdit from features.sourceEdit', () => {
+      const result = mapSiteConfig({
+        features: { sourceEdit: true, bibleTooltips: false }
+      }, undefined)
+
+      expect(result.features.sourceEdit).toBe(true)
+      expect(result.features.bibleTooltips).toBe(false)
+    })
+
+    it('reads bibleTooltips from features.bibleTooltips', () => {
+      const result = mapSiteConfig({
+        features: { sourceEdit: false, bibleTooltips: true }
+      }, undefined)
+
+      expect(result.features.sourceEdit).toBe(false)
+      expect(result.features.bibleTooltips).toBe(true)
+    })
+  })
+
+  describe('theme colors', () => {
+    it('uses the configured light/dark primary colors when present', () => {
+      const result = mapSiteConfig({
+        themes: {
+          light: { colors: { primary: '#111111' } },
+          dark: { colors: { primary: '#eeeeee' } }
+        }
+      }, undefined)
+
+      expect(result.themeColorLight).toBe('#111111')
+      expect(result.themeColorDark).toBe('#eeeeee')
+    })
+
+    it('falls back to defaults when theme colors are missing', () => {
+      const result = mapSiteConfig({ themes: { light: {}, dark: {} } }, undefined)
+
+      expect(result.themeColorLight).toBe('#000000')
+      expect(result.themeColorDark).toBe('#ffffff')
+    })
+  })
+
+  it('passes through the contentPath argument with a dot default', () => {
+    expect(mapSiteConfig({}, '/abs/docs').contentPath).toBe('/abs/docs')
+    expect(mapSiteConfig({}, undefined).contentPath).toBe('.')
+    expect(mapSiteConfig({}, '').contentPath).toBe('.')
+  })
+})

package/mdsite-nuxt/app/composables/useSiteConfig.ts

@@ -1,4 +1,28 @@
-interface SiteConfig {
+/**
+ * Subset of the runtime `mdsite.yml` config shape that `useSiteConfig`
+ * consumes. The runtime value is the full `MdsiteConfig`, but we type only
+ * the fields this composable reads so the pure mapper below can be unit
+ * tested without pulling in the entire config schema.
+ */
+export interface RawSiteConfig {
+  site?: {
+    name?: string
+    canonical?: string
+  }
+  server?: {
+    repo?: string
+  }
+  features?: {
+    bibleTooltips?: boolean
+    sourceEdit?: boolean
+  }
+  themes?: {
+    light?: { colors?: { primary?: string } }
+    dark?: { colors?: { primary?: string } }
+  }
+}
+
+export interface SiteConfig {
   siteName: string
   siteCanonical: string
   contentGitRepo: string
@@ -14,19 +38,23 @@ interface SiteConfig {
 }
 
 /**
- * Get site configuration based on runtime config
+ * Pure helper that maps the raw runtime `siteConfig` object into the shape
+ * the renderer actually consumes. Extracted from `useSiteConfig` so the
+ * field mapping (notably `contentGitRepo` ← `server.repo`, which is what
+ * powers the Edit on GitHub link in `AppBar` and `AppFooter`) can be unit
+ * tested independently of the Nuxt runtime.
  */
-export function useSiteConfig(): SiteConfig {
-  const config = useRuntimeConfig()
-  const siteConfig = config.public.siteConfig as any
-
+export function mapSiteConfig(
+  siteConfig: RawSiteConfig | undefined,
+  contentPath: string | undefined,
+): SiteConfig {
   return {
     siteName: siteConfig?.site?.name || '',
     siteCanonical: siteConfig?.site?.canonical || '',
-    contentGitRepo: '',
+    contentGitRepo: siteConfig?.server?.repo || '',
     contentGitBranch: 'main',
     contentGitPath: '.',
-    contentPath: config.public.contentPath || '.',
+    contentPath: contentPath || '.',
     features: {
       bibleTooltips: siteConfig?.features?.bibleTooltips ?? false,
       sourceEdit: siteConfig?.features?.sourceEdit ?? false
@@ -35,3 +63,13 @@ export function useSiteConfig(): SiteConfig {
     themeColorDark: siteConfig?.themes?.dark?.colors?.primary || '#ffffff'
   }
 }
+
+/**
+ * Get site configuration based on runtime config
+ */
+export function useSiteConfig(): SiteConfig {
+  const config = useRuntimeConfig()
+  const siteConfig = config.public.siteConfig as RawSiteConfig | undefined
+
+  return mapSiteConfig(siteConfig, config.public.contentPath)
+}

package/mdsite-nuxt/app/composables/useTableOfContents.test.ts

@@ -8,7 +8,7 @@ import { computeShouldShowTOC, TOC_MIN_HEADINGS, TOC_MIN_LINES } from './useTabl
 describe('useTableOfContents threshold', () => {
   it('exposes the expected minimum constants', () => {
     expect(TOC_MIN_HEADINGS).toBe(3)
-    expect(TOC_MIN_LINES).toBe(40)
+    expect(TOC_MIN_LINES).toBe(15)
   })
 
   describe('computeShouldShowTOC', () => {
@@ -18,13 +18,13 @@ describe('useTableOfContents threshold', () => {
       expect(computeShouldShowTOC(2, 100)).toBe(false)
     })
 
-    it('returns false when lines < 40 (and headings >= 3)', () => {
+    it('returns false when lines < 15 (and headings >= 3)', () => {
       expect(computeShouldShowTOC(3, 0)).toBe(false)
-      expect(computeShouldShowTOC(5, 39)).toBe(false)
+      expect(computeShouldShowTOC(5, 14)).toBe(false)
     })
 
-    it('returns true when headings >= 3 and lines >= 40', () => {
-      expect(computeShouldShowTOC(3, 40)).toBe(true)
+    it('returns true when headings >= 3 and lines >= 15', () => {
+      expect(computeShouldShowTOC(3, 15)).toBe(true)
       expect(computeShouldShowTOC(5, 100)).toBe(true)
     })
 

package/mdsite-nuxt/app/composables/useTableOfContents.ts

@@ -8,7 +8,7 @@ export interface TocItem {
 /** Minimum number of headings required to show the TOC. */
 export const TOC_MIN_HEADINGS = 3
 /** Minimum number of non-empty lines in the rendered content required to show the TOC. */
-export const TOC_MIN_LINES = 40
+export const TOC_MIN_LINES = 15
 
 /**
  * Pure helper that decides whether the TOC should be shown.

package/mdsite-nuxt/nuxt.config.ts

@@ -18,7 +18,25 @@ export default defineNuxtConfig({
     public: {
       contentDomain: path.basename(mdsite.contentDir),
       contentPath: mdsite.contentDir,
-      siteConfig
+      // `mdsite.config` is a valid `MdsiteConfig` at runtime, but
+      // Nuxt's runtime-config type generator collapses every complex
+      // field of `siteConfig` to a degenerate shape — `menu` becomes
+      // `Array<{}>` (regardless of whether the source type is recursive
+      // or contains `Array<any>`) and `footer` becomes `Array<any>`.
+      // We verified this by:
+      //   1. Tightening `MdsiteConfig.menu` to a proper recursive
+      //      `MdsiteMenuItem` (no `any`) and clearing `.nuxt` cache:
+      //      the generated `menu` was still `Array<{}>`.
+      //   2. Trying `declare module 'nuxt/schema'` augmentations of
+      //      `PublicRuntimeConfig.siteConfig`: the augmentation
+      //      *intersects* with the broken generated type rather than
+      //      overriding it, producing an even narrower target.
+      // Since the runtime value is unchanged, `as any` is the most
+      // honest pragmatic escape hatch. The recursive `MdsiteMenuItem`
+      // type is still useful: it gives the rest of the codebase
+      // (notably `scripts/generate-indices.ts`) a single source of
+      // truth and proper types.
+      siteConfig: siteConfig as any
     }
   },
 

package/mdsite-nuxt/scripts/generate-indices.ts

@@ -4,6 +4,7 @@ import fs from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { parse as parseYaml } from 'yaml'
+import type { MdsiteMenuItem } from '../utils/mdsite-config'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -108,8 +109,10 @@ export interface MinimalTreeNode {
     isPrimary?: boolean
 }
 
-type MenuItemType = string | { [key: string]: string | null | MenuItemType[] } | null
-
+// `MdsiteMenuItem` is imported from `~/utils/mdsite-config` (see top of file).
+// It is the same recursive shape that was previously defined locally as
+// `MdsiteMenuItem`. Single source of truth lives in `utils/mdsite-config.ts`
+// so the Nuxt runtime-config type generator can infer it correctly.
 /**
  * Normalize URL path so a trailing /index resolves to its parent.
  * Mirrors filePathToUrlPath behavior so menu paths match content routes.
@@ -161,7 +164,7 @@ function resolvePath(menuPath: string, contextPath: string): string {
  * Process menu items recursively and build minimal tree structure
  */
 async function processMenuItems(
-    items: MenuItemType[],
+    items: MdsiteMenuItem[],
     contextPath: string,
     order: number = 0
 ): Promise<{ nodes: MinimalTreeNode[], nextOrder: number }> {
@@ -371,14 +374,14 @@ async function buildFallbackNavigationTree(sourceDir: string): Promise<MinimalTr
  * Load the menu array from a candidate config file (legacy _menu.yml/yaml or mdsite.yml).
  * Returns null if the file is missing, unreadable, has no menu key, or has an empty menu.
  */
-async function tryReadMenuFromConfig(configPath: string): Promise<MenuItemType[] | null> {
+async function tryReadMenuFromConfig(configPath: string): Promise<MdsiteMenuItem[] | null> {
     if (!await fs.pathExists(configPath)) {
         return null
     }
 
     try {
         const content = await fs.readFile(configPath, 'utf-8')
-        const parsed = parseYaml(content) as { menu?: MenuItemType[] } | null
+        const parsed = parseYaml(content) as { menu?: MdsiteMenuItem[] } | null
         if (parsed && Array.isArray(parsed.menu) && parsed.menu.length > 0) {
             return parsed.menu
         }
@@ -393,14 +396,14 @@ async function tryReadMenuFromConfig(configPath: string): Promise<MenuItemType[]
  * Try to read menu items from a plain (non-wrapped) legacy _menu.yml/yaml file.
  * Returns null if the file is missing, unreadable, or doesn't contain a non-empty array.
  */
-async function tryReadLegacyMenuFile(menuPath: string): Promise<MenuItemType[] | null> {
+async function tryReadLegacyMenuFile(menuPath: string): Promise<MdsiteMenuItem[] | null> {
     if (!await fs.pathExists(menuPath)) {
         return null
     }
 
     try {
         const content = await fs.readFile(menuPath, 'utf-8')
-        const parsed = parseYaml(content) as MenuItemType[] | null
+        const parsed = parseYaml(content) as MdsiteMenuItem[] | null
         if (Array.isArray(parsed) && parsed.length > 0) {
             return parsed
         }
@@ -420,7 +423,7 @@ async function tryReadLegacyMenuFile(menuPath: string): Promise<MenuItemType[] |
  *   5. <sourceDir>/mdsite.yml
  * Returns the first non-empty menu array, or null if none resolve to a menu.
  */
-async function loadMenuConfig(sourceDir: string): Promise<MenuItemType[] | null> {
+async function loadMenuConfig(sourceDir: string): Promise<MdsiteMenuItem[] | null> {
     const candidates: { path: string, isLegacy: boolean }[] = [
         { path: path.join(sourceDir, '_menu.yml'), isLegacy: true },
         { path: path.join(sourceDir, '_menu.yaml'), isLegacy: true }

package/mdsite-nuxt/utils/mdsite-config.ts

@@ -2,6 +2,30 @@ import fs from 'fs';
 import path from 'path';
 import YAML from 'yaml';
 
+/**
+ * Recursive shape of a single `mdsite.yml` `menu:` entry.
+ *
+ * - `string`        → flat link to a markdown slug
+ *                     (e.g. `- genesis`, `- resurrections`)
+ * - `null`          → visual separator (`===` in YAML)
+ * - `Record<string, MdsiteMenuValue>` → group: object whose keys are group
+ *                     labels (e.g. `"Members of the Trinity":`) and whose
+ *                     values are `MdsiteMenuValue` items
+ * - `MdsiteMenuValue` (the value side of a group) can be:
+ *     - `string`         → alias link with custom title
+ *                          (e.g. `"Job": https://...`, `"Homepage": index`)
+ *     - `null`           → group label only (renders as a heading, no link)
+ *     - `MdsiteMenuItem[]` → nested submenu (recursive)
+ *
+ * Keeping this a `type` alias (not an `interface`) and avoiding `any` lets
+ * Nuxt's runtime-config type generator infer `runtimeConfig.public.siteConfig`
+ * without collapsing `menu` to `{}[]`. See `nuxt.config.ts` for the cast
+ * history this replaces.
+ */
+export type MdsiteMenuItem = string | null | MdsiteMenuGroup
+export type MdsiteMenuGroup = { [key: string]: MdsiteMenuValue }
+export type MdsiteMenuValue = string | null | MdsiteMenuItem[]
+
 export interface MdsiteConfig {
   content?: {
     path?: string
@@ -11,7 +35,7 @@ export interface MdsiteConfig {
     bibleTooltips: boolean
     sourceEdit: boolean
   }
-  menu: Array<string | null | Record<string, string | null | Array<any>>>
+  menu: MdsiteMenuItem[]
   footer: string[]
   server: {
     output: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@life-and-dev/mdsite",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "private": false,
   "description": "Local-first CLI that orchestrates mdsite-nuxt",