@elevasis/core 0.36.0 → 0.37.0

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/published.ts

@@ -29,11 +29,7 @@ export {
   OrganizationModelDomainMetadataSchema,
   OrganizationModelSchema
 } from './schema'
-export {
-  NodeIdPathSchema,
-  NodeIdStringSchema,
-  UiPositionSchema
-} from './domains/systems'
+export { NodeIdPathSchema, NodeIdStringSchema, UiPositionSchema } from './domains/systems'
 export { LinkSchema } from './graph/link'
 export { IconNameSchema, TechStackEntrySchema } from './domains/shared'
 export {
@@ -221,7 +217,9 @@ export {
   SidebarSectionSchema,
   SidebarSurfaceTargetsSchema,
   SurfaceDefinitionSchema,
-  SurfaceTypeSchema
+  SurfaceTypeSchema,
+  TopbarActionNodeSchema,
+  TopbarSectionSchema
 } from './domains/navigation'
 export {
   defineKnowledgeNode,
@@ -299,6 +297,8 @@ export type {
   OrganizationModelSidebarSection,
   OrganizationModelSidebarSurfaceNode,
   OrganizationModelSidebarSurfaceTargets,
+  OrganizationModelTopbarActionNode,
+  OrganizationModelTopbarSection,
   OrganizationModelKeyResult,
   OrganizationModelObjective,
   OrganizationModelSystemEntry,

package/src/organization-model/types.ts

@@ -11,7 +11,9 @@ import {
   SidebarNodeSchema,
   SidebarSectionSchema,
   SidebarSurfaceTargetsSchema,
-  SurfaceDefinitionSchema
+  SurfaceDefinitionSchema,
+  TopbarActionNodeSchema,
+  TopbarSectionSchema
 } from './domains/navigation'
 import { TechStackEntrySchema } from './domains/shared'
 import { StatusesDomainSchema, StatusEntrySchema, StatusSemanticClassSchema } from './domains/statuses'
@@ -135,6 +137,8 @@ export type OrganizationModelSidebarNode = z.infer<typeof SidebarNodeSchema>
 export type OrganizationModelSidebarSurfaceTargets = z.infer<typeof SidebarSurfaceTargetsSchema>
 export type OrganizationModelSidebarSurfaceNode = Extract<OrganizationModelSidebarNode, { type: 'surface' }>
 export type OrganizationModelSidebarGroupNode = Extract<OrganizationModelSidebarNode, { type: 'group' }>
+export type OrganizationModelTopbarActionNode = z.infer<typeof TopbarActionNodeSchema>
+export type OrganizationModelTopbarSection = z.infer<typeof TopbarSectionSchema>
 export type OrganizationModelTechStackEntry = z.infer<typeof TechStackEntrySchema>
 export type OrganizationModelStatuses = z.infer<typeof StatusesDomainSchema>
 export type OrganizationModelStatusEntry = z.infer<typeof StatusEntrySchema>

package/src/platform/constants/versions.ts

@@ -1,3 +1,3 @@
 export const VERSION = {
-  CURRENT: '1.12.12'
+  CURRENT: '1.12.13'
 }

package/src/reference/_generated/contracts.md

@@ -135,6 +135,18 @@ export type OrganizationModelSidebarSurfaceNode = Extract<OrganizationModelSideb
 export type OrganizationModelSidebarGroupNode = Extract<OrganizationModelSidebarNode, { type: 'group' }>
 ```
 
+### `OrganizationModelTopbarActionNode`
+
+```typescript
+export type OrganizationModelTopbarActionNode = z.infer<typeof TopbarActionNodeSchema>
+```
+
+### `OrganizationModelTopbarSection`
+
+```typescript
+export type OrganizationModelTopbarSection = z.infer<typeof TopbarSectionSchema>
+```
+
 ### `OrganizationModelTechStackEntry`
 
 ```typescript
@@ -845,6 +857,57 @@ export interface ShellRuntime {
 }
 ```
 
+### `ResolvedTopbarAction`
+
+```typescript
+/**
+ * A resolved topbar action — the OM node after gating/filtering, with icon resolved
+ * from the semantic icon registry. Passed to `TopbarActionModule.render`.
+ */
+export interface ResolvedTopbarAction {
+  id: string
+  label: string
+  tooltip?: string
+  icon: TablerIconComponent
+  order: number
+}
+```
+
+### `TopbarActionModule`
+
+```typescript
+/**
+ * A topbar action module — binds a registry key to UI behavior (a render callback).
+ * The key must match `navigation.topbar[id]`. The OM supplies data + visibility;
+ * the module supplies behavior.
+ */
+export interface TopbarActionModule {
+  /** Stable key that matches the `id` of a `navigation.topbar` node. */
+  key: string
+  /** Render the topbar action. Receives the resolved OM node (icon pre-resolved). */
+  render: (ctx: { node: ResolvedTopbarAction }) => ReactNode
+}
+```
+
+### `ResolvedTopbarActionEntry`
+
+```typescript
+/** A joined entry emitted by `getTopbarActions`: resolved OM node + module behavior. */
+export interface ResolvedTopbarActionEntry {
+  node: ResolvedTopbarAction
+  render: TopbarActionModule['render']
+}
+```
+
+### `TopbarActionsProjectionOptions`
+
+```typescript
+export interface TopbarActionsProjectionOptions {
+  isPlatformAdmin?: boolean
+  isDev?: boolean
+}
+```
+
 ### `OrganizationGraphSystemBridge`
 
 ```typescript
@@ -868,6 +931,8 @@ export interface OrganizationGraphContextValue {
 ```typescript
 export interface ElevasisSystemsProviderProps {
   systems?: SystemModule[]
+  /** Registered topbar action modules. OM node presence controls visibility; module supplies behavior. */
+  topbarActions?: TopbarActionModule[]
   organizationModel?: ElevasisOrganizationModel
   timeRange?: TimeRange
   operationsApiUrl?: string
@@ -886,6 +951,8 @@ export interface ElevasisSystemsContextValue {
   shellModel: ResolvedShellModel
   shellRuntime: ShellRuntime
   getSidebarLinks: (options?: ShellSidebarProjectionOptions) => ShellSidebarLinkGroup[]
+  /** Returns the list of topbar actions visible to the current user, in order. */
+  getTopbarActions: (options?: TopbarActionsProjectionOptions) => ResolvedTopbarActionEntry[]
   enabledResolvedSystems: ResolvedSystemModule[]
   resolvedSystems: ResolvedSystemModule[]
   organizationGraph: OrganizationGraphContextValue