Unify navigation tabs with displayMode and use built in pages for autofilled links

__tests__/server/headerUtils.server.test.ts

@@ -3,9 +3,13 @@ import {
   findNavigationItemBySlug,
   getCanonicalUrlsFromNavigation,
   getNavigationPathForSlug,
+  topLevelNavItem,
 } from '../../src/components/Header/utils-pure'
 
 import type { TopLevelNavItem } from '../../src/components/Header/utils'
+import type { Navigation } from '../../src/payload-types'
+
+type NavTab = Navigation['weather']
 
 describe('Header Utilities', () => {
   const mockNavItems: TopLevelNavItem[] = [
@@ -530,4 +534,203 @@ describe('Header Utilities', () => {
       expect(result.excludedSlugs).toEqual(['about', 'unique-page'])
     })
   })
+
+  describe('topLevelNavItem — displayMode branching', () => {
+    const internalLink: NonNullable<NonNullable<NavTab>['link']> = {
+      type: 'internal',
+      url: '/donate-membership',
+      label: 'Donate',
+    }
+
+    describe("displayMode: 'dropdown'", () => {
+      it('returns an entry with items (no top-level link)', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'dropdown' },
+          items: [
+            {
+              id: 'learn',
+              link: { type: 'internal', url: '/learn', label: 'Learn' },
+            },
+          ],
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Education' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual({
+          displayMode: 'dropdown',
+          label: 'Education',
+          items: [
+            {
+              id: 'learn',
+              link: { type: 'internal', url: '/education/learn', label: 'Learn' },
+            },
+          ],
+        })
+      })
+
+      it('returns empty array when dropdown has no items', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'dropdown' },
+          items: [],
+        }
+
+        expect(topLevelNavItem({ tab, label: 'Education' })).toEqual([])
+      })
+
+      it('defaults to dropdown when displayMode is not set', () => {
+        const tab: NavTab = {
+          items: [
+            {
+              id: 'learn',
+              link: { type: 'internal', url: '/learn', label: 'Learn' },
+            },
+          ],
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Education' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0].displayMode).toBe('dropdown')
+        expect(result[0].items).toBeDefined()
+      })
+    })
+
+    describe("displayMode: 'link'", () => {
+      it('returns a single entry with the top-level link and no items', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'link' },
+          link: { type: 'internal', url: '/blog', label: 'Blog' },
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Blog' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual({
+          displayMode: 'link',
+          link: { type: 'internal', url: '/blog', label: 'Blog' },
+          label: 'Blog',
+        })
+        expect(result[0].items).toBeUndefined()
+      })
+
+      it('returns empty array when link mode has no link', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'link' },
+        }
+
+        expect(topLevelNavItem({ tab, label: 'Blog' })).toEqual([])
+      })
+
+      it('ignores items when mode is link', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'link' },
+          link: { type: 'internal', url: '/blog', label: 'Blog' },
+          items: [
+            {
+              id: 'ignored',
+              link: { type: 'internal', url: '/ignored', label: 'Ignored' },
+            },
+          ],
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Blog' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0].items).toBeUndefined()
+      })
+    })
+
+    describe("displayMode: 'button'", () => {
+      it('returns a single entry flagged as a button with the link', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'button' },
+          link: internalLink,
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Donate' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual({
+          displayMode: 'button',
+          link: { type: 'internal', url: '/donate-membership', label: 'Donate' },
+          label: 'Donate',
+        })
+      })
+
+      it('returns empty array when button mode has no link', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'button' },
+        }
+
+        expect(topLevelNavItem({ tab, label: 'Donate' })).toEqual([])
+      })
+
+      it('preserves external link details (newTab) for button mode', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'button' },
+          link: {
+            type: 'external',
+            url: 'https://example.com/donate',
+            label: 'Donate',
+            newTab: true,
+          },
+        }
+
+        const result = topLevelNavItem({ tab, label: 'Donate' })
+
+        expect(result).toHaveLength(1)
+        expect(result[0]).toEqual({
+          displayMode: 'button',
+          link: {
+            type: 'external',
+            url: 'https://example.com/donate',
+            label: 'Donate',
+            newTab: true,
+          },
+          label: 'Donate',
+        })
+      })
+    })
+
+    describe('enabled toggle', () => {
+      it('returns empty array when the tab is disabled regardless of mode', () => {
+        const linkTab: NavTab = {
+          options: { displayMode: 'link', enabled: false },
+          link: { type: 'internal', url: '/blog', label: 'Blog' },
+        }
+        const buttonTab: NavTab = {
+          options: { displayMode: 'button', enabled: false },
+          link: internalLink,
+        }
+        const dropdownTab: NavTab = {
+          options: { displayMode: 'dropdown', enabled: false },
+          items: [
+            {
+              id: 'learn',
+              link: { type: 'internal', url: '/learn', label: 'Learn' },
+            },
+          ],
+        }
+
+        expect(topLevelNavItem({ tab: linkTab, label: 'Blog' })).toEqual([])
+        expect(topLevelNavItem({ tab: buttonTab, label: 'Donate' })).toEqual([])
+        expect(topLevelNavItem({ tab: dropdownTab, label: 'Education' })).toEqual([])
+      })
+
+      it('renders the tab when enabled is true', () => {
+        const tab: NavTab = {
+          options: { displayMode: 'link', enabled: true },
+          link: { type: 'internal', url: '/blog', label: 'Blog' },
+        }
+
+        expect(topLevelNavItem({ tab, label: 'Blog' })).toHaveLength(1)
+      })
+    })
+
+    it('returns empty array when the tab is missing', () => {
+      // NavTab is an optional field — confirm the function handles undefined gracefully
+      expect(topLevelNavItem({ tab: undefined, label: 'Weather' })).toEqual([])
+    })
+  })
 })

consistent-type-assertions.txt

@@ -10,7 +10,6 @@ src/collections/Users/components/InviteUser.tsx
 src/collections/Users/components/InviteUserDrawer.tsx
 src/collections/Users/components/inviteUserAction.ts
 src/collections/Users/components/resendInviteActions.ts
-src/components/Header/utils.ts
 src/endpoints/seed/upsert.ts
 src/globals/Diagnostics/actions/revalidateCache.ts
 src/utilities/removeNonDeterministicKeys.ts

src/collections/BuiltInPages/index.ts

@@ -28,6 +28,7 @@ export const BuiltInPages: CollectionConfig<'pages'> = {
     group: 'Content',
     useAsTitle: 'title',
     baseListFilter: filterByTenant,
+    defaultColumns: ['title', 'url', 'tenant'],
   },
   fields: [
     titleField(),

src/collections/Navigations/fields/itemsField.ts

@@ -1,9 +1,9 @@
 import { navLink } from '@/fields/navLink'
 import { merge } from 'lodash-es'
-import { ArrayField, FieldHook } from 'payload'
+import { ArrayField, Condition, FieldHook } from 'payload'
 
 // Condition: show field only when item has sub-items (accordion/section mode)
-const hasSubItems = (_data: unknown, siblingData: Record<string, unknown>) =>
+const hasSubItems: Condition = (_, siblingData) =>
   Array.isArray(siblingData?.items) && siblingData.items.length > 0
 
 // Copy link.label to standalone label when sub-items are added,
@@ -66,8 +66,7 @@ export const itemsField = ({
           ...navLink,
           admin: {
             ...navLink.admin,
-            condition: (data: unknown, siblingData: Record<string, unknown>) =>
-              !hasSubItems(data, siblingData),
+            condition: (...args: Parameters<Condition>) => !hasSubItems(...args),
           },
           hooks: {
             // navLink.hooks contains clearIrrelevantLinkValues; we add our cleanup hook

src/collections/Navigations/fields/navTab.ts

@@ -0,0 +1,107 @@
+import { navLink } from '@/fields/navLink'
+import { Field, Tab, toWords } from 'payload'
+import { itemsField } from './itemsField'
+
+export type DisplayMode = 'dropdown' | 'link' | 'button'
+
+const isDisplayMode = (value: unknown): value is DisplayMode =>
+  value === 'dropdown' || value === 'link' || value === 'button'
+
+const MODE_OPTIONS: { label: string; value: DisplayMode }[] = [
+  { label: 'Dropdown — a menu of sub-items', value: 'dropdown' },
+  { label: 'Link — a single clickable link to one page', value: 'link' },
+  { label: 'Button — a styled call-to-action button', value: 'button' },
+]
+
+const getMode = (siblingData: unknown): DisplayMode | null => {
+  if (typeof siblingData !== 'object' || siblingData === null) return null
+  if (!('options' in siblingData)) return null
+  const options = siblingData.options
+  if (typeof options !== 'object' || options === null) return null
+  if (!('displayMode' in options)) return null
+  return isDisplayMode(options.displayMode) ? options.displayMode : null
+}
+
+/**
+ * Unified helper for navigation tabs. Every tab has the same shape; its rendering
+ * (dropdown, single link, or button) is controlled by the `options.displayMode` field.
+ */
+export const navTab = ({
+  name,
+  description,
+  defaultMode = 'dropdown',
+  hasEnabledToggle = true,
+  enabledToggleDescription = 'If hidden, pages with links in this nav item will not be accessible at their navigation-nested URLs.',
+}: {
+  name: string
+  description?: string
+  defaultMode?: DisplayMode
+  hasEnabledToggle?: boolean
+  enabledToggleDescription?: string
+}): Tab => {
+  const displayModeField: Field = {
+    name: 'displayMode',
+    type: 'radio',
+    defaultValue: defaultMode,
+    options: MODE_OPTIONS,
+    admin: {
+      layout: 'vertical',
+    },
+  }
+
+  const enabledField: Field = {
+    type: 'checkbox',
+    defaultValue: true,
+    name: 'enabled',
+    label: 'Show in navigation',
+    admin: { description: enabledToggleDescription },
+  }
+
+  const optionsGroup: Field = {
+    type: 'group',
+    name: 'options',
+    fields: hasEnabledToggle ? [displayModeField, enabledField] : [displayModeField],
+  }
+
+  const linkField: Field = {
+    ...navLink,
+    label: '',
+    admin: {
+      ...navLink.admin,
+      condition: (_, siblingData) => {
+        const mode = getMode(siblingData)
+        return mode === 'link' || mode === 'button'
+      },
+    },
+  }
+
+  const items: Field = itemsField({
+    label: `${toWords(name)} Nav Items`,
+    description: `Dropdown items under ${toWords(name)}`,
+    overrides: {
+      admin: {
+        condition: (_, siblingData) => getMode(siblingData) === 'dropdown',
+      },
+    },
+  })
+
+  let fields: Field[] = [optionsGroup, linkField, items]
+
+  if (description) {
+    const descriptionField: Field = {
+      type: 'ui',
+      name: `${name}Description`,
+      admin: {
+        components: {
+          Field: {
+            path: '@/components/BannerDescription#BannerDescription',
+            clientProps: { message: description, type: 'info' },
+          },
+        },
+      },
+    }
+    fields = [descriptionField, ...fields]
+  }
+
+  return { name, fields }
+}