@almadar/std 16.236.0 → 16.237.0

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-command-palette.lolo

@@ -99,13 +99,13 @@ 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"

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

@@ -14,16 +14,20 @@ orbital DataGridOrbital {
     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
@@ -73,6 +77,7 @@ orbital DataGridOrbital {
           fields: @config.fields
           columns: @config.columns
           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
@@ -110,6 +115,7 @@ orbital DataGridOrbital {
           fields: @config.fields
           columns: @config.columns
           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
@@ -147,6 +153,7 @@ orbital DataGridOrbital {
           fields: @config.fields
           columns: @config.columns
           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
@@ -169,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]!
       }
@@ -250,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."

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

@@ -13,14 +13,20 @@ orbital DataListOrbital {
     icon : icon
     variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
     format : "date" | "currency" | "number" | "boolean" | "percent"
+    colorMap : Map string DataListFieldsItemColorMapValue
+    labels : Map string string
   }
+  type DataListFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type DataListColumnsItem = {
     name : string!
     label : string
     icon : icon
     variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
     format : "date" | "currency" | "number" | "boolean" | "percent"
+    colorMap : Map string DataListColumnsItemColorMapValue
+    labels : Map string string
   }
+  type DataListColumnsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type DataListItemActionsItem = {
     label : string!
     event : event!

package/behaviors/lolo/ui/core/molecules/ui-date-range-picker.lolo

@@ -93,13 +93,13 @@ orbital DateRangePickerOrbital {
         @tier "presentation"
       presets : [DateRangePickerPresetsItem] = []
         @label "Presets"
-        @description "Preset shortcuts. Defaults to the standard finance set (Last 7d / Last 30d / This Month / This Quarter / YTD). Pass an empty array to hide presets entirely."
+        @description "Preset shortcuts. Defaults to the translated standard finance set (Last 7d / Last 30d / This Month / This Quarter / YTD). Pass an empty array to hide presets entirely."
         @tier "presentation"
-      fromLabel : string = From
+      fromLabel : string
         @label "From Label"
         @description "From-input label."
         @tier "presentation"
-      toLabel : string = To
+      toLabel : string
         @label "To Label"
         @description "To-input label."
         @tier "presentation"

package/behaviors/lolo/ui/core/molecules/ui-document-details.lolo

@@ -12,6 +12,7 @@ orbital DocumentDetailsOrbital {
     icon : icon
     kind : "text" | "boolean" | "select" | "readonly" | "image"
     options : [string]
+    labels : Map string string
     format : "date" | "currency" | "number" | "boolean" | "percent"
     type : string
   }

package/behaviors/lolo/ui/core/molecules/ui-emoji-picker.lolo

@@ -42,7 +42,7 @@ orbital EmojiPickerOrbital {
         @label "Trigger Icon"
         @description "Icon shown on the trigger button"
         @tier "presentation"
-      triggerLabel : string = "Add emoji"
+      triggerLabel : string
         @label "Trigger Label"
         @description "Accessible label for the trigger button"
         @tier "presentation"

package/behaviors/lolo/ui/core/molecules/ui-feature-card.lolo

@@ -42,7 +42,7 @@ orbital FeatureCardOrbital {
         @label "Href"
         @description "Optional link URL"
         @tier "presentation"
-      linkLabel : string = "Learn more"
+      linkLabel : string
         @label "Link Label"
         @description "Label for the link button"
         @tier "presentation"

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

@@ -8,6 +8,7 @@ orbital GanttOrbital {
     from : string!
     to : string!
   }
+  type GanttStatusColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type GanttError = {
     message : string!
     name : string
@@ -33,6 +34,7 @@ orbital GanttOrbital {
           endField: @config.endField
           durationField: @config.durationField
           statusField: @config.statusField
+          statusColorMap: @config.statusColorMap
           groupField: @config.groupField
           rangeStart: @config.rangeStart
           rangeEnd: @config.rangeEnd
@@ -53,6 +55,7 @@ orbital GanttOrbital {
           endField: @config.endField
           durationField: @config.durationField
           statusField: @config.statusField
+          statusColorMap: @config.statusColorMap
           groupField: @config.groupField
           rangeStart: @config.rangeStart
           rangeEnd: @config.rangeEnd
@@ -73,6 +76,7 @@ orbital GanttOrbital {
           endField: @config.endField
           durationField: @config.durationField
           statusField: @config.statusField
+          statusColorMap: @config.statusColorMap
           groupField: @config.groupField
           rangeStart: @config.rangeStart
           rangeEnd: @config.rangeEnd
@@ -121,7 +125,11 @@ orbital GanttOrbital {
         @tier "presentation"
       statusField : string = status
         @label "Status Field"
-        @description "Row field holding the bar status (drives bar colour). Defaults to `status`."
+        @description "Row field holding the bar status. Defaults to `status`."
+        @tier "presentation"
+      statusColorMap : Map string GanttStatusColorMapValue = { item: default }
+        @label "Status Color Map"
+        @description "Bar colour per exact status value; unmapped statuses are primary bars."
         @tier "presentation"
       groupField : string
         @label "Group Field"

package/behaviors/lolo/ui/core/molecules/ui-import-preview-tree.lolo

@@ -5,6 +5,7 @@ orbital ImportPreviewTreeOrbital {
   type ImportPreviewTreeUnitsItem = {
     ref : string!
     targetEntity : string!
+    title : string
     fields : Map string ControlValue!
     parentRef : string
   }
@@ -77,11 +78,11 @@ orbital ImportPreviewTreeOrbital {
         @label "On Cancel"
         @description "Called when the user cancels the staged import"
         @tier "presentation"
-      confirmLabel : string = "Confirm import"
+      confirmLabel : string
         @label "Confirm Label"
         @description "Confirm button label"
         @tier "presentation"
-      cancelLabel : string = Cancel
+      cancelLabel : string
         @label "Cancel Label"
         @description "Cancel button label"
         @tier "presentation"

package/behaviors/lolo/ui/core/molecules/ui-likert-scale.lolo

@@ -45,7 +45,7 @@ orbital LikertScaleOrbital {
         @tier "presentation"
       options : [LikertScaleOptionsItem] = []
         @label "Options"
-        @description "Scale points (defaults to a 5-point agree/disagree set)"
+        @description "Scale points (defaults to a translated 5-point agree/disagree set)"
         @tier "presentation"
       value : scalar
         @label "Value"

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

@@ -3,6 +3,7 @@ app ui-menu "1.0.0"
 ;; @pattern "menu"
 orbital MenuOrbital {
   type MenuItemsItem = {
+    type : "item" | "divider"
     id : string
     label : string!
     icon : icon

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

@@ -18,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
@@ -31,9 +35,13 @@ 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!
@@ -175,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]!
       }
@@ -263,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"

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

@@ -41,12 +41,18 @@ orbital DetailPanelOrbital {
     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"
@@ -90,6 +96,7 @@ orbital DetailPanelOrbital {
           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
@@ -126,6 +133,7 @@ orbital DetailPanelOrbital {
           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
@@ -165,6 +173,7 @@ orbital DetailPanelOrbital {
           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
@@ -201,6 +210,7 @@ orbital DetailPanelOrbital {
           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
@@ -217,6 +227,9 @@ 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 row finished loading; payload.data holds the single row."
         @synonyms "loaded, fetched, retrieved"
@@ -313,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"
@@ -321,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"

package/behaviors/lolo/ui/core/organisms/ui-entity-cards.lolo

@@ -10,17 +10,25 @@ orbital EntityCardsOrbital {
     stack : string
   }
   type EntityCardsFieldsItem = {
-    key : string
-    header : string
-    name : string
+    name : string!
     label : string
+    icon : icon
+    variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
+    format : "date" | "currency" | "number" | "boolean" | "percent"
+    colorMap : Map string EntityCardsFieldsItemColorMapValue
+    labels : Map string string
   }
+  type EntityCardsFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type EntityCardsColumnsItem = {
-    key : string
-    header : string
-    name : string
+    name : string!
     label : string
+    icon : icon
+    variant : "h3" | "h4" | "body" | "caption" | "badge" | "small" | "progress"
+    format : "date" | "currency" | "number" | "boolean" | "percent"
+    colorMap : Map string EntityCardsColumnsItemColorMapValue
+    labels : Map string string
   }
+  type EntityCardsColumnsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type EntityCardsItemActionsItem = {
     label : string!
     event : event
@@ -62,6 +70,7 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
+          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))))
           showTotal: @config.showTotal
           showAvatar: @config.showAvatar
@@ -91,6 +100,7 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
+          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))))
           showTotal: @config.showTotal
           showAvatar: @config.showAvatar
@@ -120,6 +130,7 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
+          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))))
           showTotal: @config.showTotal
           showAvatar: @config.showAvatar
@@ -130,6 +141,12 @@ orbital EntityCardsOrbital {
     }
 
     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"
       VIEW -> external {
         id : string!
         row : @entity!
@@ -208,7 +225,7 @@ orbital EntityCardsOrbital {
         @label "Children"
         @description "Children elements (cards) - optional when using entity prop"
         @tier "presentation"
-      fields : [EntityCardsFieldsItem] = [{ key: "Key", header: "Header", name: "Name", label: "Label" }, { key: "Key 2", header: "Header 2", name: "Name 2", label: "Label 2" }]
+      fields : [EntityCardsFieldsItem] = [{ name: "Name", label: "Label", icon: "circle", variant: h3, format: date }, { name: "Name 2", label: "Label 2", icon: "circle", variant: h4, format: currency }]
         @label "Fields"
         @description "Fields to display - required for schema-driven rendering"
         @tier "presentation"
@@ -220,6 +237,10 @@ orbital EntityCardsOrbital {
         @label "Columns"
         @description "Alias for fields - backwards compatibility"
         @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"
       itemActions : [EntityCardsItemActionsItem] = [{ event: VIEW, label: View, variant: ghost }]
         @label "Item Actions"
         @description "Actions for each card item (schema-driven)"