@elevasis/core 0.35.1 → 0.37.0

package/src/organization-model/__tests__/domains/navigation-topbar.test.ts

@@ -0,0 +1,282 @@
+import { describe, expect, it } from 'vitest'
+import {
+  OrganizationModelNavigationSchema,
+  TopbarActionNodeSchema,
+  TopbarSectionSchema
+} from '../../domains/navigation'
+import { OrganizationModelSchema } from '../../schema'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeMinimalSystems() {
+  return {
+    dashboard: {
+      id: 'dashboard',
+      order: 10,
+      label: 'Dashboard',
+      enabled: true,
+      lifecycle: 'active' as const,
+      path: '/'
+    }
+  }
+}
+
+function makeMinimalModel(overrides: Record<string, unknown> = {}) {
+  return {
+    version: 1,
+    branding: { organizationName: 'Test', productName: 'Test OS', shortName: 'Test' },
+    systems: makeMinimalSystems(),
+    entities: {},
+    actions: {},
+    ...overrides
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TopbarActionNodeSchema
+// ---------------------------------------------------------------------------
+
+describe('TopbarActionNodeSchema — leaf node shape', () => {
+  it('accepts a minimal node (id + label + enabled default)', () => {
+    const result = TopbarActionNodeSchema.safeParse({
+      id: 'request',
+      label: 'Request a feature or report an issue'
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.enabled).toBe(true)
+    }
+  })
+
+  it('accepts a fully populated node', () => {
+    const result = TopbarActionNodeSchema.safeParse({
+      id: 'request',
+      label: 'Request a feature or report an issue',
+      tooltip: 'Request a feature or report an issue',
+      icon: 'message-plus',
+      order: 10,
+      enabled: true,
+      devOnly: false,
+      requiresAdmin: false,
+      targets: { systems: ['monitoring'], actions: [] }
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('defaults enabled to true when omitted', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'docs', label: 'Docs' })
+
+    expect(result.enabled).toBe(true)
+  })
+
+  it('accepts enabled: false to mark an item as hidden', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'docs', label: 'Docs', enabled: false })
+
+    expect(result.enabled).toBe(false)
+  })
+
+  it('accepts optional devOnly flag', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'devtools', label: 'Dev Tools', devOnly: true })
+
+    expect(result.devOnly).toBe(true)
+  })
+
+  it('accepts optional requiresAdmin flag', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'admin-panel', label: 'Admin Panel', requiresAdmin: true })
+
+    expect(result.requiresAdmin).toBe(true)
+  })
+
+  it('rejects a node missing id', () => {
+    const result = TopbarActionNodeSchema.safeParse({ label: 'No Id' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects a node missing label', () => {
+    const result = TopbarActionNodeSchema.safeParse({ id: 'no-label' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('does NOT have a path field (leaf, not a route)', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'request', label: 'Request' })
+
+    expect('path' in result).toBe(false)
+  })
+
+  it('does NOT have a surfaceType field (closed enum untouched)', () => {
+    const result = TopbarActionNodeSchema.parse({ id: 'request', label: 'Request' })
+
+    expect('surfaceType' in result).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TopbarSectionSchema
+// ---------------------------------------------------------------------------
+
+describe('TopbarSectionSchema — flat map of topbar action nodes', () => {
+  it('defaults to an empty record', () => {
+    const result = TopbarSectionSchema.parse(undefined)
+
+    expect(result).toEqual({})
+  })
+
+  it('accepts a populated map', () => {
+    const result = TopbarSectionSchema.safeParse({
+      request: { id: 'request', label: 'Request' },
+      docs: { id: 'docs', label: 'Docs', icon: 'knowledge' }
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(Object.keys(result.data)).toEqual(['request', 'docs'])
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// OrganizationModelNavigationSchema — topbar field added
+// ---------------------------------------------------------------------------
+
+describe('OrganizationModelNavigationSchema — topbar region', () => {
+  it('defaults topbar to an empty record', () => {
+    const result = OrganizationModelNavigationSchema.parse({})
+
+    expect(result.topbar).toEqual({})
+  })
+
+  it('retains existing sidebar defaults (regression: append only, sidebar untouched)', () => {
+    const result = OrganizationModelNavigationSchema.parse({})
+
+    expect(result.sidebar.primary).toEqual({})
+    expect(result.sidebar.bottom).toEqual({})
+  })
+
+  it('accepts topbar nodes alongside sidebar', () => {
+    const result = OrganizationModelNavigationSchema.safeParse({
+      sidebar: { primary: {}, bottom: {} },
+      topbar: {
+        request: {
+          id: 'request',
+          label: 'Request a feature or report an issue',
+          tooltip: 'Request a feature or report an issue',
+          icon: 'message-plus',
+          order: 10,
+          enabled: true
+        }
+      }
+    })
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.topbar['request']?.id).toBe('request')
+      expect(result.data.topbar['request']?.icon).toBe('message-plus')
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// OrganizationModelSchema — navigation.topbar propagates through full schema
+// ---------------------------------------------------------------------------
+
+describe('OrganizationModelSchema — navigation.topbar contract', () => {
+  it('accepts a model with topbar declared', () => {
+    const result = OrganizationModelSchema.safeParse(
+      makeMinimalModel({
+        navigation: {
+          topbar: {
+            request: {
+              id: 'request',
+              label: 'Request a feature or report an issue',
+              tooltip: 'Request a feature or report an issue',
+              icon: 'message-plus',
+              order: 10,
+              enabled: true
+            }
+          }
+        }
+      })
+    )
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.navigation.topbar['request']?.id).toBe('request')
+    }
+  })
+
+  it('defaults navigation.topbar to empty when navigation is omitted', () => {
+    const result = OrganizationModelSchema.safeParse(makeMinimalModel())
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.navigation.topbar).toEqual({})
+    }
+  })
+
+  it('defaults navigation.topbar to empty when only sidebar is provided', () => {
+    const result = OrganizationModelSchema.safeParse(
+      makeMinimalModel({
+        navigation: {
+          sidebar: {
+            primary: {
+              dashboard: {
+                type: 'surface',
+                label: 'Dashboard',
+                path: '/',
+                surfaceType: 'dashboard',
+                order: 10
+              }
+            },
+            bottom: {}
+          }
+        }
+      })
+    )
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.navigation.topbar).toEqual({})
+    }
+  })
+
+  it('coexists with sidebar — both sections independently populated', () => {
+    const result = OrganizationModelSchema.safeParse(
+      makeMinimalModel({
+        navigation: {
+          sidebar: {
+            primary: {
+              dashboard: {
+                type: 'surface',
+                label: 'Dashboard',
+                path: '/',
+                surfaceType: 'dashboard',
+                order: 10
+              }
+            },
+            bottom: {}
+          },
+          topbar: {
+            request: {
+              id: 'request',
+              label: 'Request',
+              order: 10,
+              enabled: true
+            }
+          }
+        }
+      })
+    )
+
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.navigation.sidebar.primary['dashboard']?.label).toBe('Dashboard')
+      expect(result.data.navigation.topbar['request']?.label).toBe('Request')
+    }
+  })
+})

package/src/organization-model/__tests__/migration-helpers.test.ts

@@ -114,17 +114,6 @@ function modelWithBuildTemplate(): OrganizationModel {
               kind: 'template-step',
               appliesTo: 'sales.lead-gen:object/list',
               entries: {
-                'source-companies': {
-                  label: 'Source Companies',
-                  order: 10,
-                  primaryEntity: 'company',
-                  outputs: ['company'],
-                  stageKey: 'populated',
-                  dependencyMode: 'per-record-eligibility',
-                  actionKey: 'lead-gen.company.source',
-                  defaultBatchSize: 100,
-                  maxBatchSize: 500
-                },
                 'qualify-companies': {
                   label: 'Qualify Companies',
                   order: 20,
@@ -136,6 +125,17 @@ function modelWithBuildTemplate(): OrganizationModel {
                   actionKey: 'lead-gen.company.qualify',
                   defaultBatchSize: 100,
                   maxBatchSize: 500
+                },
+                'source-companies': {
+                  label: 'Source Companies',
+                  order: 10,
+                  primaryEntity: 'company',
+                  outputs: ['company'],
+                  stageKey: 'populated',
+                  dependencyMode: 'per-record-eligibility',
+                  actionKey: 'lead-gen.company.source',
+                  defaultBatchSize: 100,
+                  maxBatchSize: 500
                 }
               }
             }

package/src/organization-model/defaults.ts

@@ -37,7 +37,8 @@ const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: OrganizationModelNavigation = {
   sidebar: {
     primary: {},
     bottom: {}
-  }
+  },
+  topbar: {}
 }
 
 export const DEFAULT_ORGANIZATION_MODEL: OrganizationModel = {

package/src/organization-model/domains/navigation.ts

@@ -1,139 +1,176 @@
-import { z, type ZodType } from 'zod'
-import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema } from './shared'
-
-export const SurfaceTypeSchema = z
-  .enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
-  .meta({ label: 'Surface type', color: 'blue' })
-
-export const SurfaceDefinitionSchema = z.object({
-  id: ModelIdSchema,
-  label: LabelSchema,
-  path: PathSchema,
-  surfaceType: SurfaceTypeSchema,
-  description: DescriptionSchema.optional(),
-  enabled: z.boolean().default(true),
-  devOnly: z.boolean().optional(),
-  icon: IconNameSchema.optional(),
-  systemIds: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]),
-  entityIds: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]),
-  resourceIds: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]),
-  actionIds: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]),
-  parentId: ModelIdSchema.meta({ ref: 'surface' }).optional()
-})
-
-export const SidebarSurfaceTargetsSchema = z
-  .object({
-    systems: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]).optional(),
-    entities: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]).optional(),
-    resources: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]).optional(),
-    actions: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]).optional()
-  })
-  .default({})
-
-export interface SidebarSurfaceNode {
-  type: 'surface'
-  label: string
-  path: string
-  surfaceType: z.infer<typeof SurfaceTypeSchema>
-  description?: string
-  icon?: string
-  order?: number
-  targets?: {
-    systems?: string[]
-    entities?: string[]
-    resources?: string[]
-    actions?: string[]
-  }
-  devOnly?: boolean
-  requiresAdmin?: boolean
-}
-
-export interface SidebarGroupNode {
-  type: 'group'
-  label: string
-  description?: string
-  icon?: string
-  order?: number
-  children: Record<string, SidebarNode>
-}
-
-export type SidebarNode = SidebarSurfaceNode | SidebarGroupNode
-
-export const SidebarNodeSchema: ZodType<SidebarNode> = z.lazy(() =>
-  z.discriminatedUnion('type', [
-    z.object({
-      type: z.literal('group'),
-      label: LabelSchema,
-      description: DescriptionSchema.optional(),
-      icon: IconNameSchema.optional(),
-      order: z.number().int().optional(),
-      children: z.record(z.string(), SidebarNodeSchema).default({})
-    }),
-    z.object({
-      type: z.literal('surface'),
-      label: LabelSchema,
-      path: PathSchema,
-      surfaceType: SurfaceTypeSchema,
-      description: DescriptionSchema.optional(),
-      icon: IconNameSchema.optional(),
-      order: z.number().int().optional(),
-      targets: SidebarSurfaceTargetsSchema.optional(),
-      devOnly: z.boolean().optional(),
-      requiresAdmin: z.boolean().optional()
-    })
-  ])
-)
-
-export const SidebarSectionSchema = z.record(z.string(), SidebarNodeSchema).default({})
-
-export const SidebarNavigationSchema = z
-  .object({
-    primary: SidebarSectionSchema,
-    bottom: SidebarSectionSchema
-  })
-  .default({ primary: {}, bottom: {} })
-
-export const OrganizationModelNavigationSchema = z
-  .object({
-    sidebar: SidebarNavigationSchema
-  })
-  .default({ sidebar: { primary: {}, bottom: {} } })
-
-export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationModelNavigationSchema> = {
-  sidebar: {
-    primary: {},
-    bottom: {}
-  }
-}
-
-export function getSortedSidebarEntries<TNode extends SidebarNode>(
-  nodes: Record<string, TNode>
-): Array<[string, TNode]> {
-  return Object.entries(nodes).sort(([leftId, left], [rightId, right]) => {
-    const orderDelta = (left.order ?? Number.MAX_SAFE_INTEGER) - (right.order ?? Number.MAX_SAFE_INTEGER)
-    return orderDelta === 0 ? leftId.localeCompare(rightId) : orderDelta
-  })
-}
-
-/**
- * Core placement values: 'primary' | 'secondary' | 'bottom'.
- *
- * `placement` is intentionally open (`z.string()`) so that per-project adapters can
- * introduce additional placement IDs (e.g. 'pinned', 'spotlight', 'contextual') without
- * forking core. Extension pattern: add the new string literal to the project's
- * `foundations/config/organization-model.ts` adapter — no changes to this file required.
- *
- * `surfaceType` and `resourceType` remain closed enums (UI/runtime invariants).
- */
-export const CORE_PLACEMENT_VALUES = ['primary', 'secondary', 'bottom'] as const
-export type CorePlacement = (typeof CORE_PLACEMENT_VALUES)[number]
-
-export const NavigationGroupSchema = z.object({
-  id: ModelIdSchema,
-  label: LabelSchema,
-  placement: z.string().trim().min(1).max(50),
-  surfaceIds: z.array(ModelIdSchema.meta({ ref: 'surface' })).default([])
-})
-
-// SurfaceDefinitionSchema and NavigationGroupSchema remain for derived DTOs and
-// transitional call sites. They are not authored top-level OrganizationModel fields.
+import { z, type ZodType } from 'zod'
+import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema } from './shared'
+
+export const SurfaceTypeSchema = z
+  .enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
+  .meta({ label: 'Surface type', color: 'blue' })
+
+export const SurfaceDefinitionSchema = z.object({
+  id: ModelIdSchema,
+  label: LabelSchema,
+  path: PathSchema,
+  surfaceType: SurfaceTypeSchema,
+  description: DescriptionSchema.optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  icon: IconNameSchema.optional(),
+  systemIds: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]),
+  entityIds: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]),
+  resourceIds: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]),
+  actionIds: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]),
+  parentId: ModelIdSchema.meta({ ref: 'surface' }).optional()
+})
+
+export const SidebarSurfaceTargetsSchema = z
+  .object({
+    systems: z
+      .array(ModelIdSchema.meta({ ref: 'system' }))
+      .default([])
+      .optional(),
+    entities: z
+      .array(ModelIdSchema.meta({ ref: 'entity' }))
+      .default([])
+      .optional(),
+    resources: z
+      .array(ModelIdSchema.meta({ ref: 'resource' }))
+      .default([])
+      .optional(),
+    actions: z
+      .array(ModelIdSchema.meta({ ref: 'action' }))
+      .default([])
+      .optional()
+  })
+  .default({})
+
+export interface SidebarSurfaceNode {
+  type: 'surface'
+  label: string
+  path: string
+  surfaceType: z.infer<typeof SurfaceTypeSchema>
+  description?: string
+  icon?: string
+  order?: number
+  targets?: {
+    systems?: string[]
+    entities?: string[]
+    resources?: string[]
+    actions?: string[]
+  }
+  devOnly?: boolean
+  requiresAdmin?: boolean
+}
+
+export interface SidebarGroupNode {
+  type: 'group'
+  label: string
+  description?: string
+  icon?: string
+  order?: number
+  children: Record<string, SidebarNode>
+}
+
+export type SidebarNode = SidebarSurfaceNode | SidebarGroupNode
+
+export const SidebarNodeSchema: ZodType<SidebarNode> = z.lazy(() =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('group'),
+      label: LabelSchema,
+      description: DescriptionSchema.optional(),
+      icon: IconNameSchema.optional(),
+      order: z.number().int().optional(),
+      children: z.record(z.string(), SidebarNodeSchema).default({})
+    }),
+    z.object({
+      type: z.literal('surface'),
+      label: LabelSchema,
+      path: PathSchema,
+      surfaceType: SurfaceTypeSchema,
+      description: DescriptionSchema.optional(),
+      icon: IconNameSchema.optional(),
+      order: z.number().int().optional(),
+      targets: SidebarSurfaceTargetsSchema.optional(),
+      devOnly: z.boolean().optional(),
+      requiresAdmin: z.boolean().optional()
+    })
+  ])
+)
+
+export const SidebarSectionSchema = z.record(z.string(), SidebarNodeSchema).default({})
+
+export const SidebarNavigationSchema = z
+  .object({
+    primary: SidebarSectionSchema,
+    bottom: SidebarSectionSchema
+  })
+  .default({ primary: {}, bottom: {} })
+
+/**
+ * A leaf node in `navigation.topbar`. Has no `path`, `surfaceType`, or nesting —
+ * topbar actions trigger behavior (open a modal, open docs, etc.) rather than navigate to a route.
+ * Behavior is bound by a UI registry (`TopbarActionModule`) that matches on `id`.
+ */
+export const TopbarActionNodeSchema = z.object({
+  id: ModelIdSchema,
+  label: LabelSchema,
+  tooltip: DescriptionSchema.optional(),
+  icon: IconNameSchema.optional(),
+  order: z.number().int().optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  requiresAdmin: z.boolean().optional(),
+  targets: SidebarSurfaceTargetsSchema.optional()
+})
+
+/**
+ * A flat map of topbar action nodes, keyed by action id.
+ * Defaults to an empty record (no topbar actions declared).
+ */
+export const TopbarSectionSchema = z.record(z.string(), TopbarActionNodeSchema).default({})
+
+export const OrganizationModelNavigationSchema = z
+  .object({
+    sidebar: SidebarNavigationSchema,
+    topbar: TopbarSectionSchema
+  })
+  .default({ sidebar: { primary: {}, bottom: {} }, topbar: {} })
+
+export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationModelNavigationSchema> = {
+  sidebar: {
+    primary: {},
+    bottom: {}
+  },
+  topbar: {}
+}
+
+export function getSortedSidebarEntries<TNode extends SidebarNode>(
+  nodes: Record<string, TNode>
+): Array<[string, TNode]> {
+  return Object.entries(nodes).sort(([leftId, left], [rightId, right]) => {
+    const orderDelta = (left.order ?? Number.MAX_SAFE_INTEGER) - (right.order ?? Number.MAX_SAFE_INTEGER)
+    return orderDelta === 0 ? leftId.localeCompare(rightId) : orderDelta
+  })
+}
+
+/**
+ * Core placement values: 'primary' | 'secondary' | 'bottom'.
+ *
+ * `placement` is intentionally open (`z.string()`) so that per-project adapters can
+ * introduce additional placement IDs (e.g. 'pinned', 'spotlight', 'contextual') without
+ * forking core. Extension pattern: add the new string literal to the project's
+ * `foundations/config/organization-model.ts` adapter — no changes to this file required.
+ *
+ * `surfaceType` and `resourceType` remain closed enums (UI/runtime invariants).
+ */
+export const CORE_PLACEMENT_VALUES = ['primary', 'secondary', 'bottom'] as const
+export type CorePlacement = (typeof CORE_PLACEMENT_VALUES)[number]
+
+export const NavigationGroupSchema = z.object({
+  id: ModelIdSchema,
+  label: LabelSchema,
+  placement: z.string().trim().min(1).max(50),
+  surfaceIds: z.array(ModelIdSchema.meta({ ref: 'surface' })).default([])
+})
+
+// SurfaceDefinitionSchema and NavigationGroupSchema remain for derived DTOs and
+// transitional call sites. They are not authored top-level OrganizationModel fields.

package/src/organization-model/icons.ts

@@ -54,6 +54,7 @@ export const ORGANIZATION_MODEL_ICON_TOKENS = [
   'view',
   'launch',
   'message',
+  'message-plus',
   'escalate',
   'promote',
   'submit',

package/src/organization-model/migration-helpers.ts

@@ -124,7 +124,14 @@ export function getAllBuildTemplates(model: OrganizationModel): BuildTemplate[]
       entriesOf(catalog).map(([templateId, templateEntry]) => {
         const stepCatalogId = stringValue(templateEntry.stepCatalog) as OntologyId | undefined
         const stepCatalog = stepCatalogId !== undefined ? stepCatalogs.get(stepCatalogId) : undefined
-        const steps = stepCatalog === undefined ? [] : entriesOf(stepCatalog)
+        const steps =
+          stepCatalog === undefined
+            ? []
+            : entriesOf(stepCatalog).sort(
+                ([leftId, left], [rightId, right]) =>
+                  numberValue(left.order, Number.MAX_SAFE_INTEGER) -
+                    numberValue(right.order, Number.MAX_SAFE_INTEGER) || leftId.localeCompare(rightId)
+              )
 
         return {
           order: numberValue(templateEntry.order, Number.MAX_SAFE_INTEGER),