@almadar/std 16.235.0 → 16.237.0

package/behaviors/lolo/ui/core/atoms/std-version-history.lolo

@@ -1,5 +1,6 @@
 app std-version-history "1.0.0"
 "std-version-history — wiki/CMS revision history with diff + rollback. Browses revisions; opens detail in `viewing_single`; compares the opened revision with the newest in `comparing`; Rollback emits RevisionRolledBack { row } for the consumer to restore onto its source document. `RevisionManage` is a rebindable single-entity trait: a consumer rebinds it to its own entity via `linkedEntity`. `config.scopeField` names the Revision field holding the parent document id; a page-mounted `{id}` route param scopes INIT's own fetch, and a consumer forwards SHOW_HISTORY { key } (via a `listens` override) to rescope the feed to one document — empty scopeField (default) or no id keeps today's unfiltered global feed. Rollback and retry refetches stay scoped."
+type ItemAction = { label : string!, event : event, variant : string, icon : string, roles : [string], when : SExpr }
 orbital RevisionOrbital {
     type RevisionLoaded = Event { data : [Revision] } "Fired when the revision collection finishes loading"
 
@@ -72,24 +73,16 @@ orbital RevisionOrbital {
             }, {
               label: Summary
               name: summary
-              variant: caption
+              variant: h4
             }, {
               label: Saved
+              format: date
               name: createdAt
               variant: caption
             }]
             gap: sm
-            itemActions: [{
-              event: OPEN_REVISION
-              icon: arrow-right
-              label: Open
-              variant: ghost
-            }, {
-              event: ROLLBACK
-              icon: rotate-ccw
-              label: Rollback
-              variant: danger
-            }]
+            itemClickEvent: @config.itemClickEvent
+            itemActions: (array/filter @config.itemActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
             look: @config.tableLook
             type: data-grid
           }]
@@ -600,6 +593,28 @@ orbital RevisionOrbital {
         @label "Scope field"
         @description "Revision entity field holding the parent document's id. When set, a page-mounted {id} route param scopes INIT's fetch, and a SHOW_HISTORY { key } event rescopes the feed, to rows whose scopeField equals the id/key; rollback and retry refetches stay scoped too. Empty (default) or no id = unfiltered global feed, unchanged from prior behavior."
         @tier "domain"
+      itemClickEvent : event = OPEN_REVISION
+        @label "Row click"
+        @description "Event emitted when a row is clicked; opens the revision. Empty disables the row click."
+        @tier "presentation"
+      itemActions : [ItemAction] = [{
+        event: OPEN_REVISION
+        icon: arrow-right
+        label: Open
+        variant: ghost
+      }, {
+        event: ROLLBACK
+        icon: rotate-ccw
+        label: Rollback
+        variant: danger
+      }]
+        @label "Row actions"
+        @description "Actions offered on each row; give an item `roles` to show it only to those viewer roles."
+        @tier "presentation"
+      viewerRole : string = ""
+        @label "Viewer's role"
+        @description "The signed-in viewer's role that each action's `roles` is checked against. Bind it explicitly at the call site (e.g. `viewerRole: @user.role`) in an app whose identity carries a role; left empty, only actions with no `roles` show."
+        @tier "policy"
     }
   }
 

package/behaviors/lolo/ui/core/atoms/std-vote.lolo

@@ -235,10 +235,6 @@ orbital VoteOrbital {
     }
 
     config {
-      allowDown : boolean = true
-        @label "Allow downvotes"
-        @description "Show the downvote arrow alongside the upvote"
-        @tier "domain"
     }
   }
 

package/behaviors/lolo/ui/core/atoms/std-wizard.lolo

@@ -109,7 +109,7 @@ orbital WizardOrbital {
               }, { type: divider }, {
                 cancelEvent: CANCEL
                 entity: @entity
-                fields: @entity.currentFields
+                fields: (array/map @entity.currentFields (fn f { name: @f }))
                 mode: edit
                 showCancel: false
                 showSubmit: false
@@ -232,7 +232,7 @@ orbital WizardOrbital {
               }, { type: divider }, {
                 cancelEvent: CANCEL
                 entity: @entity
-                fields: @entity.currentFields
+                fields: (array/map @entity.currentFields (fn f { name: @f }))
                 mode: edit
                 showCancel: false
                 showSubmit: false
@@ -368,7 +368,7 @@ orbital WizardOrbital {
               }, { type: divider }, {
                 cancelEvent: CANCEL
                 entity: @entity
-                fields: @entity.currentFields
+                fields: (array/map @entity.currentFields (fn f { name: @f }))
                 mode: edit
                 showCancel: false
                 showSubmit: false

package/behaviors/lolo/ui/core/atoms/ui-presence.lolo

@@ -12,6 +12,9 @@ orbital PresenceOrbital {
     state idle {
       INIT -> idle
         (render-ui main {
+          animation: @config.animation
+          animate: @config.animate
+          onExited: @config.onExited
           show: @config.show
           className: @config.className
           children: @config.children
@@ -19,7 +22,25 @@ orbital PresenceOrbital {
         })
     }
 
+    emits {
+      @config.onExited -> external { }
+        @description "Fired after the exit animation completes (before unmount)."
+        @tier "essential"
+    }
+
     config {
+      animation : "modal" | "overlay" | "slide-up" | "drawer" | "popover" | "toast" | "fade" | "page" = modal
+        @label "Animation"
+        @description "Which motion preset to use (maps to `animate-<name>-in/out`)."
+        @tier "presentation"
+      animate : boolean
+        @label "Animate"
+        @description "Per-instance opt-out. Global opt-out is `--motion-enable` / reduced-motion. @default true"
+        @tier "presentation"
+      onExited : event = "EXITED"
+        @label "On Exited"
+        @description "Fired after the exit animation completes (before unmount)."
+        @tier "presentation"
       show : boolean = false
         @label "Show"
         @description "When false, the exit animation runs, then children unmount."

package/behaviors/lolo/ui/core/atoms/ui-time-slot-cell.lolo

@@ -19,6 +19,10 @@ orbital TimeSlotCellOrbital {
           className: @config.className
           children: @config.children
           isOccupied: @config.isOccupied
+          onPointerDown: @config.onPointerDown
+          onPointerUp: @config.onPointerUp
+          onPointerCancel: @config.onPointerCancel
+          onPointerLeave: @config.onPointerLeave
           type: time-slot-cell
         })
       CLICK -> idle
@@ -29,6 +33,10 @@ orbital TimeSlotCellOrbital {
           className: @config.className
           children: @config.children
           isOccupied: @config.isOccupied
+          onPointerDown: @config.onPointerDown
+          onPointerUp: @config.onPointerUp
+          onPointerCancel: @config.onPointerCancel
+          onPointerLeave: @config.onPointerLeave
           type: time-slot-cell
         })
     }
@@ -39,6 +47,18 @@ orbital TimeSlotCellOrbital {
       }
         @description "Called when the slot is clicked"
         @tier "essential"
+      @config.onPointerDown -> external { }
+        @description "onPointerDown prop"
+        @tier "essential"
+      @config.onPointerUp -> external { }
+        @description "onPointerUp prop"
+        @tier "essential"
+      @config.onPointerCancel -> external { }
+        @description "onPointerCancel prop"
+        @tier "essential"
+      @config.onPointerLeave -> external { }
+        @description "onPointerLeave prop"
+        @tier "essential"
     }
 
     listens {
@@ -68,6 +88,22 @@ orbital TimeSlotCellOrbital {
         @label "Is Occupied"
         @description "Whether this slot contains an event"
         @tier "presentation"
+      onPointerDown : event = "POINTER_DOWN"
+        @label "On Pointer Down"
+        @description "onPointerDown prop"
+        @tier "presentation"
+      onPointerUp : event = "POINTER_UP"
+        @label "On Pointer Up"
+        @description "onPointerUp prop"
+        @tier "presentation"
+      onPointerCancel : event = "POINTER_CANCEL"
+        @label "On Pointer Cancel"
+        @description "onPointerCancel prop"
+        @tier "presentation"
+      onPointerLeave : event = "POINTER_LEAVE"
+        @label "On Pointer Leave"
+        @description "onPointerLeave prop"
+        @tier "presentation"
     }
   }
 

package/behaviors/lolo/ui/core/atoms/ui-typography.lolo

@@ -22,6 +22,7 @@ orbital TypographyOrbital {
           overflow: @config.overflow
           className: @config.className
           style: @config.style
+          role: @config.role
           format: @config.format
           content: @config.content
           children: @config.children
@@ -70,6 +71,10 @@ orbital TypographyOrbital {
         @label "Style"
         @description "Inline style"
         @tier "presentation"
+      role : string
+        @label "Role"
+        @description "Accessibility role"
+        @tier "presentation"
       format : "none" | "date" | "time" | "datetime" | "number" | "currency" | "percent" = none
         @label "Format"
         @description "Value formatting applied to string/number/Date content — `none` (the default) renders content as-is. Covers the raw-ISO-date class: a bound datetime renders human-readable via `format='date'|'time'|'datetime'`."

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

@@ -20,6 +20,7 @@ orbital AlertOrbital {
           onDismiss: @config.onDismiss
           onClose: @config.onClose
           actions: @config.actions
+          icon: @config.icon
           className: @config.className
           dismissEvent: @config.dismissEvent
           type: alert
@@ -68,6 +69,10 @@ orbital AlertOrbital {
         @label "Actions"
         @description "actions prop"
         @tier "presentation"
+      icon : icon
+        @label "Icon"
+        @description "Icon shown instead of the variant's default (Lucide name or component)"
+        @tier "presentation"
       className : string
         @label "Class Name"
         @description "className prop"

package/behaviors/lolo/ui/core/molecules/ui-animated-counter.lolo

@@ -46,7 +46,7 @@ orbital AnimatedCounterOrbital {
         @tier "presentation"
       format : string
         @label "Format"
-        @description "'number' (locale grouping), 'currency' ($x.xx), 'percent' (rounded %). Unset keeps the value's own decimals."
+        @description "'number' (locale grouping), 'currency' (locale currency), 'percent' (rounded %). Unset keeps the value's own decimals."
         @tier "presentation"
       className : string
         @label "Class Name"

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

@@ -9,6 +9,7 @@ orbital BreadcrumbOrbital {
     icon : icon
     isCurrent : boolean
     event : event
+    roles : [string]
   }
 
   entity BreadcrumbItem [runtime] {
@@ -21,7 +22,7 @@ orbital BreadcrumbOrbital {
     state idle {
       INIT -> idle
         (render-ui main {
-          items: @config.items
+          items: (array/filter @config.items (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           fromNavStack: @config.fromNavStack
           itemEvent: @config.itemEvent
           separator: @config.separator
@@ -66,6 +67,10 @@ orbital BreadcrumbOrbital {
         @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/molecules/ui-chart.lolo

@@ -30,6 +30,7 @@ orbital ChartOrbital {
     event : event
     navigatesTo : string
     variant : "primary" | "secondary" | "ghost"
+    roles : [string]
   }
   type ChartError = {
     message : string!
@@ -60,8 +61,9 @@ orbital ChartOrbital {
           showValues: @config.showValues
           stack: @config.stack
           timeAxis: @config.timeAxis
+          period: @config.period
           drillEvent: @config.drillEvent
-          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
           className: @config.className
@@ -120,6 +122,10 @@ orbital ChartOrbital {
         @label "Time Axis"
         @description "Format X-axis labels as time (ISO date in → 'Mar 2026'-style label out)"
         @tier "presentation"
+      period : "day" | "week" | "month" | "quarter" | "year" = day
+        @label "Period"
+        @description "Bucket granularity of a time axis — labels read 'Oct 2', 'Week of Sep 28', 'Oct 2026', 'Q4 2026' or '2026'"
+        @tier "presentation"
       drillEvent : string
         @label "Drill Event"
         @description "Event name emitted as `UI:{drillEvent}` with `{ label, value, seriesLabel? }` on data-point click"
@@ -140,6 +146,10 @@ orbital ChartOrbital {
         @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/molecules/ui-code-block.lolo

@@ -18,6 +18,7 @@ orbital CodeBlockOrbital {
     event : event
     navigatesTo : string
     variant : "primary" | "secondary" | "ghost"
+    roles : [string]
   }
   type CodeBlockError = {
     message : string!
@@ -66,7 +67,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -106,7 +107,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -146,7 +147,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -186,7 +187,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -226,7 +227,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -266,7 +267,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -306,7 +307,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -346,7 +347,7 @@ orbital CodeBlockOrbital {
           showLineNumbers: @config.showLineNumbers
           wordWrap: @config.wordWrap
           files: @config.files
-          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
           showCopy: @config.showCopy
@@ -564,6 +565,10 @@ orbital CodeBlockOrbital {
         @label "Line Numbers"
         @description "Editable only: number the lines in a gutter (lines with errors in red). Default on."
         @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-command-palette.lolo

@@ -13,6 +13,7 @@ orbital CommandPaletteOrbital {
     event : event
     action : event
     actionPayload : @payload action
+    roles : [string]
   }
   type CommandPaletteSELECTCommand = {
     id : string!
@@ -41,7 +42,7 @@ orbital CommandPaletteOrbital {
         (render-ui main {
           open: @entity.open
           onOpenChange: @config.onOpenChange
-          commands: @config.commands
+          commands: (array/filter @config.commands (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           onSelect: @config.onSelect
           placeholder: @config.placeholder
           emptyLabel: @config.emptyLabel
@@ -53,7 +54,7 @@ orbital CommandPaletteOrbital {
         (render-ui main {
           open: @entity.open
           onOpenChange: @config.onOpenChange
-          commands: @config.commands
+          commands: (array/filter @config.commands (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           onSelect: @config.onSelect
           placeholder: @config.placeholder
           emptyLabel: @config.emptyLabel
@@ -98,18 +99,22 @@ orbital CommandPaletteOrbital {
         @label "On Select"
         @description "Called with the selected command (click, or Enter on the highlighted row)"
         @tier "presentation"
-      placeholder : string = "Type a command..."
+      placeholder : string
         @label "Placeholder"
-        @description "Search field placeholder. Consumers own i18n — plain string prop, no package-internal translation (matches FloatingToolbar's convention)."
+        @description "Search field placeholder. Defaults to the translated 'Type a command...'."
         @tier "presentation"
-      emptyLabel : string = "No matching commands"
+      emptyLabel : string
         @label "Empty Label"
-        @description "Label shown when no command matches the query"
+        @description "Label shown when no command matches the query. Defaults to the translated message."
         @tier "presentation"
       className : string
         @label "Class Name"
         @description "Additional CSS classes on the overlay's dialog"
         @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-commit-row.lolo

@@ -104,9 +104,9 @@ orbital CommitRowOrbital {
         @label "Timestamp"
         @description "Display time (already formatted, e.g. '2 min ago')."
         @tier "presentation"
-      kind : "user" | "agent" | "restore" | "undo" | "redo" | "snapshot" = user
+      kind : "user" | "agent" | "restore" | "undo" | "redo" | "snapshot" | "merge" = user
         @label "Kind"
-        @description "What made this version (a user save, an agent turn, a restore, an undo/redo, a snapshot)."
+        @description "What made this version (a user save, an agent turn, a restore, an undo/redo, a snapshot, a merge of a teammate's work)."
         @tier "presentation"
       additions : number
         @label "Additions"

package/behaviors/lolo/ui/core/molecules/ui-confirm-dialog.lolo

@@ -27,6 +27,7 @@ orbital ConfirmDialogOrbital {
         (render-ui modal {
           isOpen: @config.isOpen
           onClose: @config.onClose
+          onExited: @config.onExited
           onConfirm: @config.onConfirm
           title: @config.title
           message: @config.message
@@ -58,6 +59,9 @@ orbital ConfirmDialogOrbital {
       @config.onClose -> external { }
         @description "Callback when dialog is closed (injected by slot wrapper)"
         @tier "essential"
+      @config.onExited -> external { }
+        @description "Fires after the exit animation completes (the dialog is about to unmount)."
+        @tier "essential"
       @config.onConfirm -> external { }
         @description "Callback when action is confirmed (injected by slot wrapper)"
         @tier "essential"
@@ -77,6 +81,10 @@ orbital ConfirmDialogOrbital {
         @label "On Close"
         @description "Callback when dialog is closed (injected by slot wrapper)"
         @tier "presentation"
+      onExited : event = "EXITED"
+        @label "On Exited"
+        @description "Fires after the exit animation completes (the dialog is about to unmount)."
+        @tier "presentation"
       onConfirm : event = "CONFIRM"
         @label "On Confirm"
         @description "Callback when action is confirmed (injected by slot wrapper)"

package/behaviors/lolo/ui/core/molecules/ui-data-grid.lolo

@@ -4,28 +4,38 @@ app ui-data-grid "1.0.0"
 ;; @pattern "data-grid"
 orbital DataGridOrbital {
     type DataGridLoaded = Event { data : [DataGridItem] } "DataGrid rows finished loading; payload.data holds the collection"
+  type DataGridEmptyAction = {
+    label : string!
+    event : event
+  }
   type DataGridFieldsItem = {
     name : string!
     label : string
     icon : icon
     variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
     format : "date" | "currency" | "number" | "boolean" | "percent"
-    colorMap : Map string string
+    colorMap : Map string DataGridFieldsItemColorMapValue
+    labels : Map string string
   }
+  type DataGridFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type DataGridColumnsItem = {
     name : string!
     label : string
     icon : icon
     variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
     format : "date" | "currency" | "number" | "boolean" | "percent"
-    colorMap : Map string string
+    colorMap : Map string DataGridColumnsItemColorMapValue
+    labels : Map string string
   }
+  type DataGridColumnsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type DataGridItemActionsItem = {
     label : string!
     event : event
     navigatesTo : string
     icon : icon
     variant : "primary" | "secondary" | "ghost" | "danger"
+    when : SExpr
+    roles : [string]
   }
   type DataGridError = {
     message : string!
@@ -59,10 +69,15 @@ orbital DataGridOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @entity
           fields: @config.fields
           columns: @config.columns
-          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))))
+          itemClickEvent: @config.itemClickEvent
           maxInlineActions: @config.maxInlineActions
           scrollX: @config.scrollX
           cols: @config.cols
@@ -92,10 +107,15 @@ orbital DataGridOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @entity
           fields: @config.fields
           columns: @config.columns
-          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))))
+          itemClickEvent: @config.itemClickEvent
           maxInlineActions: @config.maxInlineActions
           scrollX: @config.scrollX
           cols: @config.cols
@@ -125,10 +145,15 @@ orbital DataGridOrbital {
           positionEvent: @config.positionEvent
           dndItemIdField: @config.dndItemIdField
           dndRoot: @config.dndRoot
+          emptyIcon: @config.emptyIcon
+          emptyTitle: @config.emptyTitle
+          emptyDescription: @config.emptyDescription
+          emptyAction: @config.emptyAction
           entity: @payload.data
           fields: @config.fields
           columns: @config.columns
-          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))))
+          itemClickEvent: @config.itemClickEvent
           maxInlineActions: @config.maxInlineActions
           scrollX: @config.scrollX
           cols: @config.cols
@@ -151,6 +176,12 @@ orbital DataGridOrbital {
     }
 
     emits {
+      @config.itemClickEvent -> external {
+        id : string!
+        row : @entity!
+      }
+        @description "When set, clicking a card emits UI:{itemClickEvent} with { id, row }. Omit = cards are not clickable."
+        @tier "essential"
       @config.selectionEvent -> external {
         selectedIds : [string]!
       }
@@ -204,6 +235,22 @@ orbital DataGridOrbital {
         @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 : DataGridEmptyAction
+        @label "Empty Action"
+        @description "Create-the-first-item action."
+        @tier "presentation"
       fields : [DataGridFieldsItem] = []
         @label "Fields"
         @description "Field definitions for rendering each card. The pattern contract in `@almadar/core/patterns` documents `columns` as the wire-format alias the compiler emits — both names resolve to the same shape here. Pass either."
@@ -216,6 +263,10 @@ orbital DataGridOrbital {
         @label "Item Actions"
         @description "Per-item action buttons"
         @tier "presentation"
+      itemClickEvent : event = "ITEM_CLICK"
+        @label "Item Click Event"
+        @description "When set, clicking a card emits UI:{itemClickEvent} with { id, row }. Omit = cards are not clickable."
+        @tier "presentation"
       maxInlineActions : number
         @label "Max Inline Actions"
         @description "Max inline primary action buttons before the rest collapse into a '⋯' overflow menu. Omit = all inline."
@@ -284,6 +335,10 @@ orbital DataGridOrbital {
         @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 field whose type is relation. 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."