Configure nav-menu variant and class via site config.

Author: koculu

frontend/purestack.studio/components/site/nav-menu/nav-menu.mdx

@@ -376,6 +376,22 @@ createApp(
   </TabPane>
 </Tabs>
 
+## From site config
+
+The menu the doc layout docks in its sidebar takes its tone, variant and extra classes from the `navigation` section of `siteConfig.json`. A page can still override the tone with `nav.tone` in its frontmatter.
+
+```json
+{
+  "navigation": {
+    "tone": "accent",
+    "variant": "glass",
+    "class": "spotlight-from-top-right"
+  }
+}
+```
+
+Docked in the sidebar, the menu stays square and borderless whatever the variant, so the variant sets its fill and colors.
+
 ## Your own items
 
 Pass `items` to show a tree that is not the site navigation, and `currentUrl` to say which page is current. Without `currentUrl`, NavMenu uses the page being rendered, then the browser location. Groups are items with `children`; a group can have its own `url` too.

packages/ts-common/src/navMenu-types.ts

@@ -11,6 +11,10 @@ export interface NavigationConfig {
   sortBy?: NavigationSort
   roots?: string[]
   tone?: SemanticTone
+  /** Treatment of the navigation panel, such as flat, surfaceAlt or glass. */
+  variant?: string
+  /** Extra classes for the navigation panel. */
+  class?: string
 }
 
 export interface NavItem {

packages/ts-components/src/standard/navMenu/navMenu.test.ts

@@ -76,6 +76,29 @@ describe('NavMenu rendering', () => {
     expect(customHtml).not.toContain('tone-fill-flat')
   })
 
+  it('adds a given class to the navigation panel', () => {
+    const cleanup = ensureDomGlobals()
+    const html = renderApp(
+      `<NavMenu :items="[]" class="spotlight-from-top-right"></NavMenu>`,
+      {
+        components: {
+          ...defineButtonComponents(),
+          ...defineFlexComponents(),
+          ...defineIconComponents(getSvgIcon),
+          ...definePanelComponents(),
+          ...defineSignInComponents(),
+          ...defineNavigationComponents(),
+        },
+        context: createTestContext(),
+      },
+    )
+    cleanup()
+
+    const navClass = html.match(/<nav class="([^"]*)"/)?.[1].split(' ')
+    expect(navClass).toContain('spotlight-from-top-right')
+    expect(navClass).toContain('tone-fill-flat')
+  })
+
   it('marks the currentUrl item as the current page and opens its group', () => {
     const cleanup = ensureDomGlobals()
     const components = {

packages/ts-ssg/README.md

@@ -151,7 +151,10 @@ Config comes from:
     "navFileName": "_nav.json",
     "maxDepth": 3,
     "includeIndex": true,
-    "sortBy": "order"
+    "sortBy": "order",
+    "tone": "neutral",
+    "variant": "flat",
+    "class": ""
   },
   "sitemap": {
     "enabled": true,

packages/ts-ssg/schema/siteConfig.schema.json

@@ -383,6 +383,35 @@
           ],
           "description": "Navigation menu semantic tone.",
           "default": "neutral"
+        },
+        "variant": {
+          "type": "string",
+          "enum": [
+            "solid",
+            "surface",
+            "surfaceAlt",
+            "spotlight",
+            "glass",
+            "flat",
+            "flatAlt",
+            "flatSolid",
+            "outlineFill",
+            "outline",
+            "subtle",
+            "subtleBtn",
+            "link",
+            "sheen",
+            "underline",
+            "rail",
+            "bracket",
+            "none"
+          ],
+          "description": "Navigation menu treatment. Docked in the doc sidebar, the menu stays square and borderless whatever the variant.",
+          "default": "flat"
+        },
+        "class": {
+          "type": "string",
+          "description": "Extra classes for the navigation menu, such as spotlight-from-top-right."
         }
       }
     },

packages/ts-ssg/src/build/renderer.test.ts

@@ -317,6 +317,59 @@ describe('renderPage consent integration', () => {
     expect(html).not.toContain('page-toc')
   })
 
+  it('passes the configured navigation variant and class to the nav menu', async () => {
+    const site = resolveSiteConfig({
+      rootDir: process.cwd(),
+      navigation: {
+        tone: 'accent',
+        variant: ' glass ',
+        class: 'spotlight-from-top-right',
+      },
+    })
+    const html = await renderPage({
+      bodyHtml: '<p>Hello</p>',
+      pageInfo: {
+        relPath: 'index.md',
+        urlPath: '/',
+        frontmatter: normalizeFrontmatter({}),
+      },
+      navigation: {
+        mode: 'auto',
+        folder: '',
+        root: '',
+        items: [{ title: 'Home', url: '/' }],
+        global: [],
+        tone: 'accent',
+      },
+      site,
+    })
+    expect(html).toMatch(
+      /<nav-menu tone="accent" variant="glass" class="spotlight-from-top-right">/,
+    )
+  })
+
+  it('leaves the nav menu on its own variant when none is configured', async () => {
+    const site = resolveSiteConfig({ rootDir: process.cwd() })
+    const html = await renderPage({
+      bodyHtml: '<p>Hello</p>',
+      pageInfo: {
+        relPath: 'index.md',
+        urlPath: '/',
+        frontmatter: normalizeFrontmatter({}),
+      },
+      navigation: {
+        mode: 'auto',
+        folder: '',
+        root: '',
+        items: [{ title: 'Home', url: '/' }],
+        global: [],
+        tone: 'neutral',
+      },
+      site,
+    })
+    expect(html).toContain('<nav-menu tone="neutral">')
+  })
+
   it('does not render navigation shell when showNav is false', async () => {
     const site = resolveSiteConfig({ rootDir: process.cwd() })
     const html = await renderPage({

packages/ts-ssg/src/navigation/config.ts

@@ -40,7 +40,24 @@ export function resolveNavigationConfig(
   const sortBy = resolveSort(merged.sortBy)
   const roots = resolveNavigationRoots(merged.roots)
   const tone = pickSemanticTone(merged.tone) ?? DEFAULT_NAV_CONFIG.tone
-  return { mode, navFileName, maxDepth, includeIndex, sortBy, roots, tone }
+  const variant = resolveText(merged.variant)
+  const className = resolveText(merged.class)
+  return {
+    mode,
+    navFileName,
+    maxDepth,
+    includeIndex,
+    sortBy,
+    roots,
+    tone,
+    ...(variant ? { variant } : {}),
+    ...(className ? { class: className } : {}),
+  }
+}
+
+function resolveText(value: unknown) {
+  if (typeof value !== 'string') return undefined
+  return value.trim() || undefined
 }
 
 function resolveMode(mode: NavigationMode | undefined): NavigationMode {

packages/ts-ssg/src/navigation/model.ts

@@ -17,6 +17,8 @@ export interface ResolvedNavigationConfig {
   sortBy: NavigationSort
   roots: string[]
   tone: SemanticTone
+  variant?: string
+  class?: string
 }
 
 export interface NavigationTree {

packages/ts-ssg/src/templates/page-templates.ts

@@ -67,7 +67,17 @@ function renderDocTemplate({
                 ? [
                     h('aside')
                       .attr({ class: 'doc-sidebar', id: 'doc-sidebar' })
-                      .push(h('nav-menu').attr({ tone: navigation?.tone })),
+                      .push(
+                        h('nav-menu').attr({
+                          tone: navigation?.tone,
+                          ...(site.navigation.variant
+                            ? { variant: site.navigation.variant }
+                            : {}),
+                          ...(site.navigation.class
+                            ? { class: site.navigation.class }
+                            : {}),
+                        }),
+                      ),
                   ]
                 : []),
               h('main')