@almadar/std 16.235.0 → 16.237.0

package/behaviors/lolo/ui/core/molecules/ui-page-header.lolo

@@ -18,6 +18,7 @@ orbital PageHeaderOrbital {
     icon : icon
     loading : boolean
     disabled : boolean
+    roles : [string]
   }
   type PageHeaderError = {
     message : string!
@@ -42,12 +43,13 @@ orbital PageHeaderOrbital {
       INIT -> idle
         (render-ui main {
           title: @config.title
+          icon: @config.icon
           subtitle: @config.subtitle
           showBack: @config.showBack
           backEvent: @config.backEvent
           breadcrumbs: @config.breadcrumbs
           status: @config.status
-          actions: @config.actions
+          actions: (array/filter @config.actions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           isLoading: @config.isLoading
           error: @config.error
           tabs: @config.tabs
@@ -75,6 +77,10 @@ orbital PageHeaderOrbital {
         @label "Title"
         @description "Page title - accepts string or number from generated code accessing dynamic entity data"
         @tier "presentation"
+      icon : icon
+        @label "Icon"
+        @description "Icon shown before the title."
+        @tier "presentation"
       subtitle : scalar
         @label "Subtitle"
         @description "Optional subtitle/description"
@@ -127,6 +133,10 @@ orbital PageHeaderOrbital {
         @label "Class Name"
         @description "className prop"
         @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The viewer's role that each action's `roles` is checked against; bind it at the call site (e.g. `viewerRole: @user.role`). Empty = only actions with no `roles` show."
+        @tier "policy"
     }
   }
 

package/behaviors/lolo/ui/core/molecules/ui-page-transition.lolo

@@ -22,7 +22,7 @@ orbital PageTransitionOrbital {
     config {
       locationKey : string = ""
         @label "Location Key"
-        @description "Value that changes on navigation (e.g. `location.pathname`)."
+        @description "Value that changes on navigation (a page path)."
         @tier "presentation"
       children : node
         @label "Children"

package/behaviors/lolo/ui/core/molecules/ui-swipeable-row.lolo

@@ -2,13 +2,15 @@ app ui-swipeable-row "1.0.0"
 "SwipeableRow — UI factory (1:1 with the @almadar/ui swipeable-row pattern)."
 ;; @pattern "swipeable-row"
 orbital SwipeableRowOrbital {
-    type SwipeableRowLoaded = Event { data : [SwipeableRowItem] } "SwipeableRow rows finished loading; payload.data holds the collection"
+    type SwipeableRowLoaded = Event { data : SwipeableRowItem } "SwipeableRow row finished loading; payload.data holds the single row"
   type SwipeableRowLeftActionsItem = {
     label : string!
     icon : icon
     variant : "primary" | "secondary" | "danger" | "ghost"
     event : event!
     eventPayload : @payload event
+    when : SExpr
+    roles : [string]
   }
   type SwipeableRowRightActionsItem = {
     label : string!
@@ -16,6 +18,8 @@ orbital SwipeableRowOrbital {
     variant : "primary" | "secondary" | "danger" | "ghost"
     event : event!
     eventPayload : @payload event
+    when : SExpr
+    roles : [string]
   }
 
   entity SwipeableRowItem [runtime] {
@@ -23,24 +27,37 @@ orbital SwipeableRowOrbital {
   }
 
   trait SwipeableRowRender -> @rebindable SwipeableRowItem [interaction, instance] {
-    initial: idle
+    initial: resolving
 
-    state idle {
-      INIT -> idle when @config.selfFetch
-        (fetch SwipeableRowItem { emit: { success: SwipeableRowLoaded } })
+    state resolving {
+      INIT -> idle when (and @config.selfFetch (!= (str/default ?id "") ""))
+        (fetch SwipeableRowItem { id: ?id, emit: { success: SwipeableRowLoaded } })
+        (render-ui main {
+          leftActions: (array/filter @config.leftActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          rightActions: (array/filter @config.rightActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          threshold: @config.threshold
+          children: @config.children
+          itemData: @entity
+          className: @config.className
+          type: swipeable-row
+        })
+      INIT -> idle when (not (and @config.selfFetch (!= (str/default ?id "") "")))
         (render-ui main {
-          leftActions: @config.leftActions
-          rightActions: @config.rightActions
+          leftActions: (array/filter @config.leftActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          rightActions: (array/filter @config.rightActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           threshold: @config.threshold
           children: @config.children
           itemData: @entity
           className: @config.className
           type: swipeable-row
         })
-      INIT -> idle when (not @config.selfFetch)
+    }
+
+    state idle {
+      INIT -> idle
         (render-ui main {
-          leftActions: @config.leftActions
-          rightActions: @config.rightActions
+          leftActions: (array/filter @config.leftActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          rightActions: (array/filter @config.rightActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           threshold: @config.threshold
           children: @config.children
           itemData: @entity
@@ -49,8 +66,8 @@ orbital SwipeableRowOrbital {
         })
       SwipeableRowLoaded -> idle
         (render-ui main {
-          leftActions: @config.leftActions
-          rightActions: @config.rightActions
+          leftActions: (array/filter @config.leftActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          rightActions: (array/filter @config.rightActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           threshold: @config.threshold
           children: @config.children
           itemData: @payload.data
@@ -61,11 +78,19 @@ orbital SwipeableRowOrbital {
 
     emits {
       SwipeableRowLoaded
-        @description "SwipeableRow rows finished loading; payload.data holds the collection."
+        @description "SwipeableRow row finished loading; payload.data holds the single row."
         @synonyms "loaded, fetched, retrieved"
         @tier "essential"
     }
 
+    listens {
+      INIT {
+        id : string
+      }
+        @description "Mount payload; a host that routes to this panel by id (a :id page param) passes it here."
+        @tier "internal"
+    }
+
     config {
       leftActions : [SwipeableRowLeftActionsItem] = []
         @label "Left Actions"
@@ -87,9 +112,13 @@ orbital SwipeableRowOrbital {
         @label "Class Name"
         @description "className prop"
         @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The viewer's role that each action's `roles` is checked against; bind it at the call site (e.g. `viewerRole: @user.role`). Empty = only actions with no `roles` show."
+        @tier "policy"
       selfFetch : boolean = true
-        @label "Fetch its own rows on mount?"
-        @description "true (default) = standalone mount self-populates on INIT. false = a composing atom owns the fetch and routes its loaded event here — suppresses the wrapper's own un-hydrated fetch so it cannot race the composer's."
+        @label "Fetch its own row on mount?"
+        @description "true (default) = a mount that carries an id loads that one row (never the collection); a create-mode mount skips the load. false = a composing atom owns the load."
         @tier "internal"
     }
   }

package/behaviors/lolo/ui/core/molecules/ui-table-view.lolo

@@ -4,6 +4,10 @@ app ui-table-view "1.0.0"
 ;; @pattern "table-view"
 orbital TableViewOrbital {
     type TableViewLoaded = Event { data : [TableViewItem] } "TableView rows finished loading; payload.data holds the collection"
+  type TableViewEmptyAction = {
+    label : string!
+    event : event
+  }
   type TableViewColumnsItem = {
     key : string!
     field : string
@@ -14,9 +18,13 @@ orbital TableViewOrbital {
     className : string
     weight : "normal" | "medium" | "semibold"
     format : "badge" | "date" | "currency" | "number" | "percent" | "boolean"
+    colorMap : Map string TableViewColumnsItemColorMapValue
+    labels : Map string string
+    variant : "h3" | "h4"
     icon : icon
     sortable : boolean
   }
+  type TableViewColumnsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type TableViewFieldsItem = {
     key : string!
     field : string
@@ -27,14 +35,20 @@ orbital TableViewOrbital {
     className : string
     weight : "normal" | "medium" | "semibold"
     format : "badge" | "date" | "currency" | "number" | "percent" | "boolean"
+    colorMap : Map string TableViewFieldsItemColorMapValue
+    labels : Map string string
+    variant : "h3" | "h4"
     icon : icon
     sortable : boolean
   }
+  type TableViewFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type TableViewItemActionsItem = {
     label : string!
     event : event!
     icon : icon
     variant : "primary" | "secondary" | "ghost" | "danger"
+    when : SExpr
+    roles : [string]
   }
   type TableViewError = {
     message : string!
@@ -68,10 +82,14 @@ orbital TableViewOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @entity
           columns: @config.columns
           fields: @config.fields
-          itemActions: @config.itemActions
+          itemActions: (array/filter @config.itemActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           itemClickEvent: @config.itemClickEvent
           selectable: @config.selectable
@@ -100,10 +118,14 @@ orbital TableViewOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @entity
           columns: @config.columns
           fields: @config.fields
-          itemActions: @config.itemActions
+          itemActions: (array/filter @config.itemActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           itemClickEvent: @config.itemClickEvent
           selectable: @config.selectable
@@ -132,10 +154,14 @@ orbital TableViewOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @payload.data
           columns: @config.columns
           fields: @config.fields
-          itemActions: @config.itemActions
+          itemActions: (array/filter @config.itemActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           itemClickEvent: @config.itemClickEvent
           selectable: @config.selectable
@@ -157,6 +183,12 @@ orbital TableViewOrbital {
     }
 
     emits {
+      @config.itemClickEvent -> external {
+        id : string!
+        row : @entity!
+      }
+        @description "When set, the whole row is clickable and emits UI:{itemClickEvent} with { id, row } (action-button clicks stopPropagation so they still win). Mirrors DataList's contract. Omit = rows are not clickable."
+        @tier "essential"
       @config.selectEvent -> external {
         selectedIds : [string]!
       }
@@ -213,6 +245,22 @@ orbital TableViewOrbital {
         @label "Dnd Root"
         @description "Mark this container as the DnD root for its subtree — descendant zones share one DndContext (cross-container drag). Use on an outer container whose own items are not draggable."
         @tier "presentation"
+      emptyIcon : icon
+        @label "Empty Icon"
+        @description "Domain icon for the empty state."
+        @tier "presentation"
+      emptyTitle : string
+        @label "Empty Title"
+        @description "Specific title ('No orders yet')."
+        @tier "presentation"
+      emptyDescription : string
+        @label "Empty Description"
+        @description "What will appear here once rows exist."
+        @tier "presentation"
+      emptyAction : TableViewEmptyAction
+        @label "Empty Action"
+        @description "Create-the-first-item action."
+        @tier "presentation"
       columns : [TableViewColumnsItem] = []
         @label "Columns"
         @description "Column definitions. The compiler emits `columns`; `fields` is the alias."
@@ -229,9 +277,9 @@ orbital TableViewOrbital {
         @label "Max Inline Actions"
         @description "maxInlineActions prop"
         @tier "presentation"
-      itemClickEvent : event = ""
+      itemClickEvent : event = "ITEM_CLICK"
         @label "Item Click Event"
-        @description "When set, the whole row is clickable and emits UI:{itemClickEvent} with { id, row } (action-button clicks stopPropagation so they still win). Mirrors DataList's contract. When OMITTED and `itemActions` exist, the row click defaults to the first non-danger item action (the view/open action by authoring convention) — a danger action never becomes the row default (destructive actions require intentional reach)."
+        @description "When set, the whole row is clickable and emits UI:{itemClickEvent} with { id, row } (action-button clicks stopPropagation so they still win). Mirrors DataList's contract. Omit = rows are not clickable."
         @tier "presentation"
       selectable : boolean = false
         @label "Selectable"
@@ -289,6 +337,10 @@ orbital TableViewOrbital {
         @label "Relations Data"
         @description "Relation display data: { fieldName: [{value, label}] } — injected server-side by the runtime (relation-option injection) or bound by compiled codegen; resolves stored foreign ids to display names for a column whose field is relation-typed. Same contract DetailPanel takes."
         @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The viewer's role that each action's `roles` is checked against; bind it at the call site (e.g. `viewerRole: @user.role`). Empty = only actions with no `roles` show."
+        @tier "policy"
       selfFetch : boolean = true
         @label "Fetch its own rows on mount?"
         @description "true (default) = standalone mount self-populates on INIT. false = a composing atom owns the fetch and routes its loaded event here — suppresses the wrapper's own un-hydrated fetch so it cannot race the composer's."

package/behaviors/lolo/ui/core/molecules/ui-tabs.lolo

@@ -13,6 +13,7 @@ orbital TabsOrbital {
     disabled : boolean
     event : event
     active : boolean
+    roles : [string]
   }
   type TabsItemsItemIconAsset = {
     url : asset!
@@ -39,6 +40,7 @@ orbital TabsOrbital {
     disabled : boolean
     event : event
     active : boolean
+    roles : [string]
   }
   type TabsTabsItemIconAsset = {
     url : asset!
@@ -65,8 +67,8 @@ orbital TabsOrbital {
     state idle {
       INIT -> idle
         (render-ui main {
-          items: @config.items
-          tabs: @config.tabs
+          items: (array/filter @config.items (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          tabs: (array/filter @config.tabs (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           defaultActiveTab: @config.defaultActiveTab
           activeTab: @config.activeTab
           onTabChange: @config.onTabChange
@@ -123,6 +125,10 @@ orbital TabsOrbital {
         @label "Class Name"
         @description "Additional CSS classes"
         @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The viewer's role that each action's `roles` is checked against; bind it at the call site (e.g. `viewerRole: @user.role`). Empty = only actions with no `roles` show."
+        @tier "policy"
     }
   }
 

package/behaviors/lolo/ui/core/organisms/ui-detail-panel.lolo

@@ -2,7 +2,7 @@ app ui-detail-panel "1.0.0"
 "DetailPanel — UI factory (1:1 with the @almadar/ui detail-panel pattern)."
 ;; @pattern "detail-panel"
 orbital DetailPanelOrbital {
-    type DetailPanelLoaded = Event { data : [DetailPanelItem] } "DetailPanel rows finished loading; payload.data holds the collection"
+    type DetailPanelLoaded = Event { data : DetailPanelItem } "DetailPanel row finished loading; payload.data holds the single row"
   type DetailPanelError = {
     message : string!
     name : string
@@ -29,6 +29,8 @@ orbital DetailPanelOrbital {
     event : event
     navigatesTo : string
     variant : "primary" | "secondary" | "ghost" | "danger"
+    when : SExpr
+    roles : [string]
   }
   type DetailPanelBackAction = {
     label : string!
@@ -36,14 +38,21 @@ orbital DetailPanelOrbital {
     event : event
     navigatesTo : string
     variant : "primary" | "secondary" | "ghost" | "danger"
+    when : SExpr
   }
   type DetailPanelFieldsItem = {
-    key : string!
-    header : string
+    name : string!
+    label : string
+    icon : icon
+    variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
+    format : "date" | "currency" | "number" | "boolean" | "percent"
+    colorMap : Map string DetailPanelFieldsItemColorMapValue
+    labels : Map string string
     type : string
     values : [string]
     relation : DetailPanelFieldsItemRelation
   }
+  type DetailPanelFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type DetailPanelFieldsItemRelation = {
     entity : string!
     cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
@@ -60,11 +69,48 @@ orbital DetailPanelOrbital {
   }
 
   trait DetailPanelRender -> @rebindable DetailPanelItem [interaction, instance] {
-    initial: idle
+    initial: resolving
 
-    state idle {
-      INIT -> idle when @config.selfFetch
-        (fetch DetailPanelItem { emit: { success: DetailPanelLoaded } })
+    state resolving {
+      INIT -> idle when (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create"))
+        (fetch DetailPanelItem { id: ?id, emit: { success: DetailPanelLoaded } })
+        (render-ui main {
+          className: @config.className
+          isLoading: @config.isLoading
+          error: @config.error
+          sortBy: @config.sortBy
+          sortDirection: @config.sortDirection
+          searchValue: @config.searchValue
+          page: @config.pageProp
+          pageSize: @config.pageSize
+          totalCount: @config.totalCount
+          activeFilters: @config.activeFilters
+          selectedIds: @config.selectedIds
+          entity: @entity
+          title: @config.title
+          onTitleCommit: @config.onTitleCommit
+          subtitle: @config.subtitle
+          status: @config.status
+          avatar: @config.avatar
+          sections: @config.sections
+          actions: (array/filter @config.actions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          maxInlineActions: @config.maxInlineActions
+          backAction: @config.backAction
+          closeEvent: @config.closeEvent
+          footer: @config.footer
+          slideOver: @config.slideOver
+          fields: @config.fields
+          fieldNames: @config.fieldNames
+          initialData: @entity
+          mode: @config.mode
+          position: @config.position
+          width: @config.width
+          displayFields: @config.displayFields
+          showActions: @config.showActions
+          relationsData: @config.relationsData
+          type: detail-panel
+        })
+      INIT -> idle when (not (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create")))
         (render-ui main {
           className: @config.className
           isLoading: @config.isLoading
@@ -84,9 +130,10 @@ orbital DetailPanelOrbital {
           status: @config.status
           avatar: @config.avatar
           sections: @config.sections
-          actions: @config.actions
+          actions: (array/filter @config.actions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           backAction: @config.backAction
+          closeEvent: @config.closeEvent
           footer: @config.footer
           slideOver: @config.slideOver
           fields: @config.fields
@@ -100,7 +147,10 @@ orbital DetailPanelOrbital {
           relationsData: @config.relationsData
           type: detail-panel
         })
-      INIT -> idle when (not @config.selfFetch)
+    }
+
+    state idle {
+      INIT -> idle
         (render-ui main {
           className: @config.className
           isLoading: @config.isLoading
@@ -120,9 +170,10 @@ orbital DetailPanelOrbital {
           status: @config.status
           avatar: @config.avatar
           sections: @config.sections
-          actions: @config.actions
+          actions: (array/filter @config.actions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           backAction: @config.backAction
+          closeEvent: @config.closeEvent
           footer: @config.footer
           slideOver: @config.slideOver
           fields: @config.fields
@@ -156,9 +207,10 @@ orbital DetailPanelOrbital {
           status: @config.status
           avatar: @config.avatar
           sections: @config.sections
-          actions: @config.actions
+          actions: (array/filter @config.actions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           maxInlineActions: @config.maxInlineActions
           backAction: @config.backAction
+          closeEvent: @config.closeEvent
           footer: @config.footer
           slideOver: @config.slideOver
           fields: @config.fields
@@ -175,12 +227,23 @@ orbital DetailPanelOrbital {
     }
 
     emits {
+      @config.closeEvent -> external { }
+        @description "The event of the declared action that dismisses the panel. The matching action renders as the header close ×; omitted, no × is drawn."
+        @tier "essential"
       DetailPanelLoaded
-        @description "DetailPanel rows finished loading; payload.data holds the collection."
+        @description "DetailPanel row finished loading; payload.data holds the single row."
         @synonyms "loaded, fetched, retrieved"
         @tier "essential"
     }
 
+    listens {
+      INIT {
+        id : string
+      }
+        @description "Mount payload; a host that routes to this panel by id (a :id page param) passes it here."
+        @tier "internal"
+    }
+
     config {
       className : string
         @label "Class Name"
@@ -263,6 +326,10 @@ orbital DetailPanelOrbital {
         @label "Back Action"
         @description "Navigation-back affordance. Renders top-LEFT before the title (OS/back convention — Almadar_UX §8.4), spatially separated from the right-aligned action buttons + close X. Never inferred from actions[] labels."
         @tier "presentation"
+      closeEvent : event = "CLOSE"
+        @label "Close Event"
+        @description "The event of the declared action that dismisses the panel. The matching action renders as the header close ×; omitted, no × is drawn."
+        @tier "presentation"
       footer : node
         @label "Footer"
         @description "footer prop"
@@ -271,9 +338,9 @@ orbital DetailPanelOrbital {
         @label "Slide Over"
         @description "slideOver prop"
         @tier "presentation"
-      fields : [DetailPanelFieldsItem] = [{ key: "Key", header: "Header", type: "Type", values: ["Item", "Item 2"], relation: { entity: "Entity", cardinality: one } }, { key: "Key 2", header: "Header 2", type: "Type 2", values: ["Item", "Item 2"], relation: { entity: "Entity 2", cardinality: many } }]
+      fields : [DetailPanelFieldsItem] = [{ name: "Name", label: "Label", icon: "circle", variant: h3, format: date, type: "Type", values: ["Item", "Item 2"], relation: { entity: "Entity", cardinality: one } }, { name: "Name 2", label: "Label 2", icon: "circle", variant: h4, format: currency, type: "Type 2", values: ["Item", "Item 2"], relation: { entity: "Entity 2", cardinality: many } }]
         @label "Fields"
-        @description "Fields to display - accepts string[], {key, header}[], or DetailField[]"
+        @description "Fields to display: field names, or declared fields ({ name, label, variant, format, colorMap, labels })"
         @tier "presentation"
       fieldNames : [string] = []
         @label "Field Names"
@@ -303,9 +370,13 @@ orbital DetailPanelOrbital {
         @label "Relations Data"
         @description "Relation display data: { fieldName: [{value, label}] } — injected server-side by the runtime (relation-option injection) or bound by compiled codegen; resolves stored foreign ids to display names."
         @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The viewer's role that each action's `roles` is checked against; bind it at the call site (e.g. `viewerRole: @user.role`). Empty = only actions with no `roles` show."
+        @tier "policy"
       selfFetch : boolean = true
-        @label "Fetch its own rows on mount?"
-        @description "true (default) = standalone mount self-populates on INIT. false = a composing atom owns the fetch and routes its loaded event here — suppresses the wrapper's own un-hydrated fetch so it cannot race the composer's."
+        @label "Fetch its own row on mount?"
+        @description "true (default) = a mount that carries an id loads that one row (never the collection); a create-mode mount skips the load. false = a composing atom owns the load."
         @tier "internal"
     }
   }