@almadar/std 16.235.0 → 16.237.0

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

@@ -10,23 +10,33 @@ 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
     navigatesTo : string
     placement : string
     variant : string
+    when : SExpr
+    roles : [string]
   }
 
   entity EntityCardsItem [runtime] {
@@ -60,7 +70,8 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
-          itemActions: @config.itemActions
+          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
           variant: @config.variant
@@ -89,7 +100,8 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
-          itemActions: @config.itemActions
+          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
           variant: @config.variant
@@ -118,7 +130,8 @@ orbital EntityCardsOrbital {
           fields: @config.fields
           fieldNames: @config.fieldNames
           columns: @config.columns
-          itemActions: @config.itemActions
+          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
           variant: @config.variant
@@ -128,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!
@@ -206,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"
@@ -218,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)"
@@ -238,6 +261,10 @@ orbital EntityCardsOrbital {
         @label "Image Field"
         @description "Entity field name containing an image URL to display as card thumbnail"
         @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/organisms/ui-entity-list.lolo

@@ -10,17 +10,24 @@ orbital EntityListOrbital {
     stack : string
   }
   type EntityListFieldsItem = {
-    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 EntityListFieldsItemColorMapValue
+    labels : Map string string
   }
+  type EntityListFieldsItemColorMapValue = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral" | "destructive"
   type EntityListItemActionsItem = {
     label : string!
     event : event
     navigatesTo : string
     placement : string
     variant : "primary" | "secondary" | "ghost" | "danger" | "default"
+    icon : icon
+    when : SExpr
+    roles : [string]
   }
 
   entity EntityListItem [runtime] {
@@ -48,13 +55,16 @@ orbital EntityListOrbital {
           entity: @entity
           entityType: @config.entityType
           selectable: @config.selectable
-          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))))
           showDividers: @config.showDividers
           variant: @config.variant
           emptyMessage: @config.emptyMessage
           children: @config.children
           fields: @config.fields
           fieldNames: @config.fieldNames
+          itemClickEvent: @config.itemClickEvent
+          completedField: @config.completedField
+          disabledField: @config.disabledField
           type: entity-list
         })
       INIT -> idle when (not @config.selfFetch)
@@ -73,13 +83,16 @@ orbital EntityListOrbital {
           entity: @entity
           entityType: @config.entityType
           selectable: @config.selectable
-          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))))
           showDividers: @config.showDividers
           variant: @config.variant
           emptyMessage: @config.emptyMessage
           children: @config.children
           fields: @config.fields
           fieldNames: @config.fieldNames
+          itemClickEvent: @config.itemClickEvent
+          completedField: @config.completedField
+          disabledField: @config.disabledField
           type: entity-list
         })
       EntityListLoaded -> idle
@@ -98,13 +111,16 @@ orbital EntityListOrbital {
           entity: @payload.data
           entityType: @config.entityType
           selectable: @config.selectable
-          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))))
           showDividers: @config.showDividers
           variant: @config.variant
           emptyMessage: @config.emptyMessage
           children: @config.children
           fields: @config.fields
           fieldNames: @config.fieldNames
+          itemClickEvent: @config.itemClickEvent
+          completedField: @config.completedField
+          disabledField: @config.disabledField
           type: entity-list
         })
     }
@@ -113,6 +129,12 @@ orbital EntityListOrbital {
       ITEM_ACTIONS -> external { }
         @description "Item actions - schema-driven or function-based"
         @tier "essential"
+      @config.itemClickEvent -> external {
+        id : string!
+        row : @entity!
+      }
+        @description "When set, clicking a row emits UI:{itemClickEvent} with { id, row }. Omit = rows are not clickable."
+        @tier "essential"
       VIEW -> external {
         id : string!
         row : @entity!
@@ -199,14 +221,30 @@ orbital EntityListOrbital {
         @label "Children"
         @description "children prop"
         @tier "presentation"
-      fields : [EntityListFieldsItem] = [{ key: "Key", header: "Header", name: "Name", label: "Label" }, { key: "Key 2", header: "Header 2", name: "Name 2", label: "Label 2" }]
+      fields : [EntityListFieldsItem] = [{ 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 - accepts string[] or {key, header}[] for unified interface"
+        @description "Fields to display: field names, or declared fields ({ name, label, variant, format, colorMap, labels })"
         @tier "presentation"
       fieldNames : [string] = []
         @label "Field Names"
         @description "Alias for fields - backwards compatibility"
         @tier "presentation"
+      itemClickEvent : event = "ITEM_CLICK"
+        @label "Item Click Event"
+        @description "When set, clicking a row emits UI:{itemClickEvent} with { id, row }. Omit = rows are not clickable."
+        @tier "presentation"
+      completedField : string
+        @label "Completed Field"
+        @description "Row field that marks an item completed (`true` strikes its title through)"
+        @tier "presentation"
+      disabledField : string
+        @label "Disabled Field"
+        @description "Row field that marks an item disabled (`true` dims the row and disables its click)"
+        @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/organisms/ui-entity-table.lolo

@@ -16,6 +16,8 @@ orbital EntityTableOrbital {
     label : string
     width : string
     sortable : boolean
+    align : "left" | "center" | "right"
+    format : "date" | "currency" | "number" | "boolean" | "percent"
   }
   type EntityTableColumnsItem = {
     key : string
@@ -24,6 +26,8 @@ orbital EntityTableOrbital {
     label : string
     width : string
     sortable : boolean
+    align : "left" | "center" | "right"
+    format : "date" | "currency" | "number" | "boolean" | "percent"
   }
   type EntityTableItemActionsItem = {
     label : string!
@@ -32,6 +36,8 @@ orbital EntityTableOrbital {
     placement : string
     icon : icon
     variant : string
+    when : SExpr
+    roles : [string]
   }
   type EntityTableEmptyAction = {
     label : string!
@@ -42,12 +48,15 @@ orbital EntityTableOrbital {
     icon : icon
     variant : "default" | "danger"
     event : event
+    when : SExpr
+    roles : [string]
   }
   type EntityTableBulkActionsItem = {
     label : string!
     icon : icon
     variant : "default" | "danger"
     event : event
+    roles : [string]
   }
   type EntityTableRelationsDataValueItem = {
     value : string!
@@ -81,7 +90,8 @@ orbital EntityTableOrbital {
           entity: @entity
           fields: @config.fields
           columns: @config.columns
-          itemActions: @config.itemActions
+          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))))
           emptyIcon: @config.emptyIcon
           emptyTitle: @config.emptyTitle
           emptyDescription: @config.emptyDescription
@@ -89,8 +99,8 @@ orbital EntityTableOrbital {
           selectable: @config.selectable
           searchable: @config.searchable
           searchPlaceholder: @config.searchPlaceholder
-          rowActions: @config.rowActions
-          bulkActions: @config.bulkActions
+          rowActions: (array/filter @config.rowActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          bulkActions: (array/filter @config.bulkActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           headerActions: @config.headerActions
           showTotal: @config.showTotal
           look: @config.look
@@ -113,7 +123,8 @@ orbital EntityTableOrbital {
           entity: @entity
           fields: @config.fields
           columns: @config.columns
-          itemActions: @config.itemActions
+          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))))
           emptyIcon: @config.emptyIcon
           emptyTitle: @config.emptyTitle
           emptyDescription: @config.emptyDescription
@@ -121,8 +132,8 @@ orbital EntityTableOrbital {
           selectable: @config.selectable
           searchable: @config.searchable
           searchPlaceholder: @config.searchPlaceholder
-          rowActions: @config.rowActions
-          bulkActions: @config.bulkActions
+          rowActions: (array/filter @config.rowActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          bulkActions: (array/filter @config.bulkActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           headerActions: @config.headerActions
           showTotal: @config.showTotal
           look: @config.look
@@ -145,7 +156,8 @@ orbital EntityTableOrbital {
           entity: @payload.data
           fields: @config.fields
           columns: @config.columns
-          itemActions: @config.itemActions
+          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))))
           emptyIcon: @config.emptyIcon
           emptyTitle: @config.emptyTitle
           emptyDescription: @config.emptyDescription
@@ -153,8 +165,8 @@ orbital EntityTableOrbital {
           selectable: @config.selectable
           searchable: @config.searchable
           searchPlaceholder: @config.searchPlaceholder
-          rowActions: @config.rowActions
-          bulkActions: @config.bulkActions
+          rowActions: (array/filter @config.rowActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
+          bulkActions: (array/filter @config.bulkActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
           headerActions: @config.headerActions
           showTotal: @config.showTotal
           look: @config.look
@@ -164,6 +176,12 @@ orbital EntityTableOrbital {
     }
 
     emits {
+      @config.itemClickEvent -> external {
+        id : string!
+        row : @entity!
+      }
+        @description "When set, rows are activatable and emit UI:{itemClickEvent} with { id, row }"
+        @tier "essential"
       VIEW -> external {
         id : string!
         row : @entity!
@@ -222,7 +240,7 @@ orbital EntityTableOrbital {
         @label "Selected Ids"
         @description "Currently selected item IDs"
         @tier "presentation"
-      fields : [EntityTableFieldsItem] = [{ key: "Key", header: "Header", name: "Name", label: "Label", width: "Width", sortable: false }, { key: "Key 2", header: "Header 2", name: "Name 2", label: "Label 2", width: "Width 2", sortable: true }]
+      fields : [EntityTableFieldsItem] = [{ key: "Key", header: "Header", name: "Name", label: "Label", width: "Width", sortable: false, align: left, format: date }, { key: "Key 2", header: "Header 2", name: "Name 2", label: "Label 2", width: "Width 2", sortable: true, align: center, format: currency }]
         @label "Fields"
         @description "Fields to display - accepts string[] or Column[] for unified interface. Alias for columns"
         @tier "presentation"
@@ -230,6 +248,10 @@ orbital EntityTableOrbital {
         @label "Columns"
         @description "Columns can be Column objects or simple string field names"
         @tier "presentation"
+      itemClickEvent : event = "ITEM_CLICK"
+        @label "Item Click Event"
+        @description "When set, rows are activatable and emit UI:{itemClickEvent} with { id, row }"
+        @tier "presentation"
       itemActions : [EntityTableItemActionsItem] = [{ event: VIEW, label: View, variant: ghost }]
         @label "Item Actions"
         @description "Item actions from generated code - maps to rowActions"
@@ -286,6 +308,10 @@ orbital EntityTableOrbital {
         @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/organisms/ui-form-section.lolo

@@ -2,7 +2,7 @@ app ui-form-section "1.0.0"
 "FormSection — UI factory (1:1 with the @almadar/ui form-section pattern)."
 ;; @pattern "form-section"
 orbital FormSectionOrbital {
-    type FormSectionLoaded = Event { data : [FormSectionItem] } "FormSection rows finished loading; payload.data holds the collection"
+    type FormSectionLoaded = Event { data : FormSectionItem } "FormSection row finished loading; payload.data holds the single row"
   type FormSectionFieldsItem = {
     name : string
     field : string
@@ -14,6 +14,7 @@ orbital FormSectionOrbital {
     defaultValue : ControlValue
     options : [FormSectionFieldsItemOptionsItem]
     values : [string]
+    labels : Map string string
     relation : FormSectionFieldsItemRelation
     min : number
     max : number
@@ -100,6 +101,7 @@ orbital FormSectionOrbital {
     defaultValue : ControlValue
     options : [FormSectionSectionsItemFieldsItemOptionsItem]
     values : [string]
+    labels : Map string string
     relation : FormSectionSectionsItemFieldsItemRelation
     min : number
     max : number
@@ -138,11 +140,45 @@ orbital FormSectionOrbital {
   }
 
   trait FormSectionRender -> @rebindable FormSectionItem [interaction, instance] {
-    initial: idle
+    initial: resolving
 
-    state idle {
-      INIT -> idle when @config.selfFetch
-        (fetch FormSectionItem { emit: { success: FormSectionLoaded } })
+    state resolving {
+      INIT -> idle when (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create"))
+        (fetch FormSectionItem { id: ?id, emit: { success: FormSectionLoaded } })
+        (render-ui main {
+          children: @config.children
+          onSubmit: @config.onSubmit
+          onCancel: @config.onCancel
+          layout: @config.layout
+          gap: @config.gap
+          className: @config.className
+          entity: @entity
+          mode: @config.mode
+          fields: @config.fields
+          initialData: @entity
+          isLoading: @config.isLoading
+          error: @config.error
+          submitLabel: @config.submitLabel
+          cancelLabel: @config.cancelLabel
+          showCancel: @config.showCancel
+          showSubmit: @config.showSubmit
+          title: @config.title
+          submitEvent: @config.submitEvent
+          cancelEvent: @config.cancelEvent
+          relationsData: @config.relationsData
+          relationsLoading: @config.relationsLoading
+          fieldOverrides: @config.fieldOverrides
+          conditionalFields: @config.conditionalFields
+          hiddenCalculations: @config.hiddenCalculations
+          violationTriggers: @config.violationTriggers
+          evaluationContext: @config.evaluationContext
+          sections: @config.sections
+          onFieldChange: @config.onFieldChange
+          configPath: @config.configPath
+          repeatable: @config.repeatable
+          type: form-section
+        })
+      INIT -> idle when (not (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create")))
         (render-ui main {
           children: @config.children
           onSubmit: @config.onSubmit
@@ -176,7 +212,10 @@ orbital FormSectionOrbital {
           repeatable: @config.repeatable
           type: form-section
         })
-      INIT -> idle when (not @config.selfFetch)
+    }
+
+    state idle {
+      INIT -> idle
         (render-ui main {
           children: @config.children
           onSubmit: @config.onSubmit
@@ -218,7 +257,7 @@ orbital FormSectionOrbital {
           layout: @config.layout
           gap: @config.gap
           className: @config.className
-          entity: @payload.data
+          entity: @entity
           mode: @config.mode
           fields: @config.fields
           initialData: @payload.data
@@ -261,11 +300,19 @@ orbital FormSectionOrbital {
         @description "Callback when any field value changes"
         @tier "essential"
       FormSectionLoaded
-        @description "FormSection rows finished loading; payload.data holds the collection."
+        @description "FormSection 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 {
       children : node
         @label "Children"
@@ -380,8 +427,8 @@ orbital FormSectionOrbital {
         @description "Whether the form supports repeatable entries"
         @tier "presentation"
       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/organisms/ui-form.lolo

@@ -2,7 +2,7 @@ app ui-form "1.0.0"
 "Form — UI factory (1:1 with the @almadar/ui form pattern)."
 ;; @pattern "form"
 orbital FormOrbital {
-    type FormLoaded = Event { data : [FormItem] } "Form rows finished loading; payload.data holds the collection"
+    type FormLoaded = Event { data : FormItem } "Form row finished loading; payload.data holds the single row"
   type FormFieldsItem = {
     name : string
     field : string
@@ -14,6 +14,7 @@ orbital FormOrbital {
     defaultValue : ControlValue
     options : [FormFieldsItemOptionsItem]
     values : [string]
+    labels : Map string string
     relation : FormFieldsItemRelation
     min : number
     max : number
@@ -100,6 +101,7 @@ orbital FormOrbital {
     defaultValue : ControlValue
     options : [FormSectionsItemFieldsItemOptionsItem]
     values : [string]
+    labels : Map string string
     relation : FormSectionsItemFieldsItemRelation
     min : number
     max : number
@@ -138,11 +140,45 @@ orbital FormOrbital {
   }
 
   trait FormRender -> @rebindable FormItem [interaction, instance] {
-    initial: idle
+    initial: resolving
 
-    state idle {
-      INIT -> idle when @config.selfFetch
-        (fetch FormItem { emit: { success: FormLoaded } })
+    state resolving {
+      INIT -> idle when (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create"))
+        (fetch FormItem { id: ?id, emit: { success: FormLoaded } })
+        (render-ui main {
+          children: @config.children
+          onSubmit: @config.onSubmit
+          onCancel: @config.onCancel
+          layout: @config.layout
+          gap: @config.gap
+          className: @config.className
+          entity: @entity
+          mode: @config.mode
+          fields: @config.fields
+          initialData: @entity
+          isLoading: @config.isLoading
+          error: @config.error
+          submitLabel: @config.submitLabel
+          cancelLabel: @config.cancelLabel
+          showCancel: @config.showCancel
+          showSubmit: @config.showSubmit
+          title: @config.title
+          submitEvent: @config.submitEvent
+          cancelEvent: @config.cancelEvent
+          relationsData: @config.relationsData
+          relationsLoading: @config.relationsLoading
+          fieldOverrides: @config.fieldOverrides
+          conditionalFields: @config.conditionalFields
+          hiddenCalculations: @config.hiddenCalculations
+          violationTriggers: @config.violationTriggers
+          evaluationContext: @config.evaluationContext
+          sections: @config.sections
+          onFieldChange: @config.onFieldChange
+          configPath: @config.configPath
+          repeatable: @config.repeatable
+          type: form
+        })
+      INIT -> idle when (not (and @config.selfFetch (!= (str/default ?id "") "") (!= @config.mode "create")))
         (render-ui main {
           children: @config.children
           onSubmit: @config.onSubmit
@@ -176,7 +212,10 @@ orbital FormOrbital {
           repeatable: @config.repeatable
           type: form
         })
-      INIT -> idle when (not @config.selfFetch)
+    }
+
+    state idle {
+      INIT -> idle
         (render-ui main {
           children: @config.children
           onSubmit: @config.onSubmit
@@ -218,7 +257,7 @@ orbital FormOrbital {
           layout: @config.layout
           gap: @config.gap
           className: @config.className
-          entity: @payload.data
+          entity: @entity
           mode: @config.mode
           fields: @config.fields
           initialData: @payload.data
@@ -261,11 +300,19 @@ orbital FormOrbital {
         @description "Callback when any field value changes"
         @tier "essential"
       FormLoaded
-        @description "Form rows finished loading; payload.data holds the collection."
+        @description "Form 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 {
       children : node
         @label "Children"
@@ -380,8 +427,8 @@ orbital FormOrbital {
         @description "Whether the form supports repeatable entries"
         @tier "presentation"
       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"
     }
   }