@almadar/std 16.190.0 → 16.192.0

package/behaviors/lolo/ui/core/atoms/std-record-detail.lolo

@@ -20,7 +20,9 @@ orbital RecordItemOrbital {
     status : "active" | "inactive" | "pending" @description "The record's current state." @synonyms "state, condition, stage" = active
     slug : string @description "URL-friendly identifier, for records opened by address instead of id." @synonyms "permalink, url key, address" = ""
     content : string @description "The record's rich-text body as HTML, edited in place by the document look." @synonyms "body, text, document, article body" = ""
-    loadedRow : object @intrinsic @description "The full row exactly as last fetched (relations hydrated when config.include asks). The document look binds it as the panel's entity and hands it to header actions as ?row, so a settings modal seeds from the real record instead of the atom's four mapped columns." = {}
+    coverUrl : string @intrinsic @description "The document look's cover/hero image URL, stamped from the loaded row's coverField." = ""
+    iconName : string @intrinsic @description "The document look's icon name, stamped from the loaded row's iconField." = ""
+    loadedRow : object @intrinsic @description "The full row exactly as last fetched (relations hydrated when config.include asks). The details drawer binds it, and hosts that need it (e.g. a settings modal) stash it from RecordItemLoaded — the document panel itself takes only scalar props and emits scalar payloads ({ id, title })." = {}
     openDraft : string @intrinsic @description "Set from the navigate payload when the surface was opened on a record that was JUST minted blank; read once the row loads to decide whether the document body opens authoring (draft) or read-only. Absent on a refresh or a normal open, so the draft entry never repeats." @synonyms "new document, just created, draft open" = ""
     createdAt : string
   }
@@ -128,6 +130,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (render-ui main @config.documentEditingContent)
       RecordItemLoaded -> viewing when ["!=", (str/default (object/get @entity openDraft) ""), "1"]
         ;; (object/merge … {}) is a type adapter only: type_compat lacks "declared object accepts a named row type" (ledgered)
@@ -136,6 +140,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -149,6 +155,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (render-ui main @config.documentEditingContent)
       RecordItemSlugLoaded -> viewing when (and [">", (array/len ?data), 0] ["!=", (str/default (object/get @entity openDraft) ""), "1"])
         (set @entity.loadedRow (array/first ?data))
@@ -156,6 +164,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -245,6 +255,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get ?data @config.titleField))
         (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
         (set @entity.content (object/get ?data @config.contentField))
+        (set @entity.coverUrl (str/default (object/get ?data @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get ?data @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -258,6 +270,8 @@ orbital RecordItemOrbital {
         (set @entity.name (object/get (array/first ?data) @config.titleField))
         (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
         (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (set @entity.coverUrl (str/default (object/get (array/first ?data) @config.coverField) ""))
+        (set @entity.iconName (str/default (object/get (array/first ?data) @config.iconField) ""))
         (if ["=", @config.detailLook, document]
           (render-ui main @config.documentBodyContent)
           (if ["=", @config.detailLook, slide-over]
@@ -507,6 +521,16 @@ orbital RecordItemOrbital {
         @description "Name of the field on the loaded record that carries the rich-text HTML body the document look renders and edits (e.g. content, body, articleText)."
         @synonyms "body field, content field, document field"
         @tier "presentation"
+      coverField : string = ""
+        @label "Which field is the cover image?"
+        @description "Name of the image-typed field on the loaded record painted as the document look's full-bleed hero banner (e.g. coverImage, heroImage). Empty = no banner, the default."
+        @synonyms "cover field, hero image field, banner field"
+        @tier "presentation"
+      iconField : string = ""
+        @label "Which field is the document icon?"
+        @description "Name of the field on the loaded record whose icon name renders beside the document title (e.g. icon). Empty = no icon, the default."
+        @synonyms "icon field, glyph field"
+        @tier "presentation"
       editLabel : string = "Edit"
         @label "Edit button label"
         @description "Label of the quiet button above the document body that starts an editing session (the body itself is also clickable)."
@@ -587,9 +611,11 @@ orbital RecordItemOrbital {
         @tier "internal"
       documentBodyContent : render-ui = {
         actions: @config.actions
+        coverImage: @entity.coverUrl
+        icon: @entity.iconName
         editEvent: EDIT_CONTENT
         editLabel: @config.editLabel
-        entity: @entity.loadedRow
+        id: @entity.id
         maxInlineActions: @config.maxInlineActions
         placeholder: @config.placeholder
         subtitle: @entity.description
@@ -604,12 +630,14 @@ orbital RecordItemOrbital {
         @tier "internal"
       documentEditingContent : render-ui = {
         actions: @config.actions
+        coverImage: @entity.coverUrl
+        icon: @entity.iconName
         autosaveHint: @config.autosaveHint
         contentChangeEvent: CONTENT_CHANGE
         doneEvent: DONE_EDITING
         doneLabel: @config.doneLabel
         editing: true
-        entity: @entity.loadedRow
+        id: @entity.id
         maxInlineActions: @config.maxInlineActions
         placeholder: @config.placeholder
         subtitle: @entity.description
@@ -675,6 +703,14 @@ orbital RecordItemOrbital {
         @description "A property in the settings rail committed in place; patch carries the row id plus the one changed field, ready to hand straight to a persist update. Quiet contract: the host persists without refetching or repainting the open document."
         @synonyms "property saved, metadata changed, field committed, update property"
         @tier "domain"
+      RELATION_OPEN -> external {
+        field : string!
+        id : string!
+        name : string
+      }
+        @description "A relation chip in the details drawer was clicked (a tag, the author, the category); id is the linked row's id. Hosts route it to the linked record's own surface — a navigate, a scoped overlay, a filtered list."
+        @synonyms "open relation, linked record clicked, tag clicked, chip clicked"
+        @tier "domain"
     }
 
     listens {
@@ -718,6 +754,7 @@ orbital RecordItemOrbital {
       detailsContent : render-ui = {
         entity: @entity.loadedRow
         fields: @config.metaFields
+        relationEvent: RELATION_OPEN
         title: @config.detailsTitle
         type: document-details
       }

package/behaviors/lolo/ui/core/atoms/std-tag-taxonomy.lolo

@@ -7,6 +7,8 @@ orbital TagTaxonomyOrbital {
 
     type TagSelected = Event { tagId : string! } "Fired when a tag is selected to drill into its children"
 
+    type TagCommit = { name : string!, parentId : string }
+
   entity Tag [persistent: tags] {
     id : string!
     name : string! @description "The descriptive label for this item." @synonyms "label, title, description"
@@ -21,6 +23,11 @@ orbital TagTaxonomyOrbital {
     initial: loading
 
     state loading {
+      LEVEL_RELOAD -> loading
+        (fetch Tag {
+          filter: ["=", (object/get @entity parentId), (str/default ?tagId "")]
+          emit: { failure: TagLoadFailed, success: TagLoaded }
+        })
       INIT -> loading
         (set @entity.id "")
         (set @entity.parentId "")
@@ -55,7 +62,14 @@ orbital TagTaxonomyOrbital {
             content: @config.title
             type: typography
             variant: h3
-          }, {
+          }, (if @config.allowEdit {
+            action: NEW_TAG
+            icon: plus
+            label: "New category"
+            size: sm
+            type: button
+            variant: secondary
+          } null), {
             entity: ?data
             fields: []
             gap: sm
@@ -200,7 +214,14 @@ orbital TagTaxonomyOrbital {
             content: @config.title
             type: typography
             variant: h3
-          }, {
+          }, (if @config.allowEdit {
+            action: NEW_TAG
+            icon: plus
+            label: "New category"
+            size: sm
+            type: button
+            variant: secondary
+          } null), {
             entity: ?data
             fields: []
             gap: sm
@@ -261,6 +282,29 @@ orbital TagTaxonomyOrbital {
           gap: md
           type: stack
         })
+      NEW_TAG -> creating when @config.allowEdit
+        (render-ui modal {
+          children: [{
+            content: "New category"
+            type: typography
+            variant: h3
+          }, {
+            color: muted
+            content: (if (!= @entity.id "") "Created inside the open category." "Created at the top level.")
+            type: typography
+            variant: caption
+          }, { type: divider }, {
+            cancelEvent: CANCEL_TAG
+            entity: { parentId: @entity.id }
+            fields: (name)
+            mode: create
+            submitEvent: COMMIT_TAG
+            type: form-section
+          }]
+          direction: vertical
+          gap: md
+          type: stack
+        })
       TagLoadFailed -> error
         (render-ui main {
           message: ?error
@@ -269,6 +313,61 @@ orbital TagTaxonomyOrbital {
         })
     }
 
+    state creating {
+      COMMIT_TAG -> creating
+        (persist create Tag {
+          name: (object/get ?data name)
+          parentId: (str/default (object/get ?data parentId) "")
+        } {
+          emit: { failure: TagCreateFailed, success: TagCreated }
+        })
+      ;; A filter expression binds @entity to the candidate ROW, so the open
+      ;; level must travel by payload: the arm emits LEVEL_RELOAD carrying the
+      ;; trait's own level id, and loading refetches from it.
+      CANCEL_TAG -> loading
+        (render-ui modal null)
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading categories…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
+        (emit LEVEL_RELOAD { tagId: @entity.id })
+      ;; Refetch the level the new tag landed on — its own parentId names it.
+      TagCreated -> loading
+        (render-ui modal null)
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading categories…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
+        (fetch Tag {
+          filter: ["=", (object/get @entity parentId), (str/default (object/get ?row parentId) "")]
+          emit: { failure: TagLoadFailed, success: TagLoaded }
+        })
+      TagCreateFailed -> creating
+        (render-ui modal {
+          message: ?error
+          type: alert
+          variant: error
+        })
+    }
+
     state editing {
       INIT -> loading
         (set @entity.id "")
@@ -311,7 +410,14 @@ orbital TagTaxonomyOrbital {
             content: @config.title
             type: typography
             variant: h3
-          }, {
+          }, (if @config.allowEdit {
+            action: NEW_TAG
+            icon: plus
+            label: "New category"
+            size: sm
+            type: button
+            variant: secondary
+          } null), {
             entity: ?data
             fields: []
             gap: sm
@@ -429,6 +535,39 @@ orbital TagTaxonomyOrbital {
         @description "Signals a tag has been chosen for further exploration."
         @synonyms "chosen, picked, activated, highlighted"
         @tier "domain"
+      NEW_TAG
+        @description "Opens the new-category form (rendered only when allowEdit is on); the creation lands at the level currently open."
+        @synonyms "add tag, create category, new category"
+        @tier "domain"
+      COMMIT_TAG {
+        data : TagCommit
+      }
+        @description "The new-category form committed; data carries the name and the parent level."
+        @synonyms "save tag, create tag"
+        @tier "internal"
+      CANCEL_TAG
+        @description "The new-category form was dismissed without creating."
+        @synonyms "cancel, back"
+        @tier "internal"
+      LEVEL_RELOAD {
+        tagId : string
+      }
+        @description "Internal hop that refetches the open level after the new-category form closes (a fetch filter cannot read trait state, so the level travels by payload)."
+        @synonyms "reload level, refresh"
+        @tier "internal"
+      TagCreated {
+        row : Tag
+      }
+        @description "A new tag row persisted; the open level refetches to show it."
+        @synonyms "created, added"
+        @tier "internal"
+      TagCreateFailed {
+        error : string
+        code : string
+      }
+        @description "The tag create failed."
+        @synonyms "error, failure"
+        @tier "internal"
     }
 
     listens {
@@ -457,6 +596,39 @@ orbital TagTaxonomyOrbital {
         @description "A tag in the taxonomy has been chosen by the user."
         @synonyms "chosen, picked, activated, selected"
         @tier "domain"
+      NEW_TAG
+        @description "The New-category affordance was clicked."
+        @synonyms "add tag, create category"
+        @tier "domain"
+      COMMIT_TAG {
+        data : TagCommit
+      }
+        @description "The new-category form committed."
+        @synonyms "save tag, create tag"
+        @tier "internal"
+      CANCEL_TAG
+        @description "The new-category form was dismissed."
+        @synonyms "cancel, back"
+        @tier "internal"
+      LEVEL_RELOAD {
+        tagId : string
+      }
+        @description "Refetch the open level."
+        @synonyms "reload level, refresh"
+        @tier "internal"
+      TagCreated {
+        row : Tag
+      }
+        @description "A new tag row persisted."
+        @synonyms "created, added"
+        @tier "internal"
+      TagCreateFailed {
+        error : string
+        code : string
+      }
+        @description "The tag create failed."
+        @synonyms "error, failure"
+        @tier "internal"
     }
 
     config {
@@ -466,7 +638,7 @@ orbital TagTaxonomyOrbital {
         @tier "presentation"
       allowEdit : boolean = false
         @label "Allow editing"
-        @description "Show inline controls to create or rename tags"
+        @description "Render the New-category affordance: creations land at the level currently open (top level, or inside the drilled-into category). Rename is a follow-up (ledgered)."
         @tier "domain"
       tableLook : "dense" | "spacious" | "striped" | "borderless" | "card-rows" = dense
         @label "Table look"

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

@@ -245,7 +245,9 @@ orbital RevisionOrbital {
               label: Document
               look: @config.statLook
               type: stat-display
-              value: @entity.documentId
+              ;; The captured title, never the raw foreign id — also keeps this
+              ;; binding scalar when a consumer retypes documentId as a relation.
+              value: (str/default @entity.summary "")
             }, {
               icon: layers
               label: Type

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

@@ -15,7 +15,7 @@ orbital CalendarGridOrbital {
     initial: idle
 
     state idle {
-      INIT -> idle
+      INIT -> idle when @config.selfFetch
         (fetch CalendarGridItem { emit: { success: CalendarGridLoaded } })
         (render-ui main {
           weekStart: @config.weekStart
@@ -36,6 +36,26 @@ orbital CalendarGridOrbital {
           colorField: @config.colorField
           type: calendar-grid
         })
+      INIT -> idle when (not @config.selfFetch)
+        (render-ui main {
+          weekStart: @config.weekStart
+          timeSlots: @config.timeSlots
+          events: @entity
+          onSlotClick: @config.onSlotClick
+          onDayClick: @config.onDayClick
+          onEventClick: @config.onEventClick
+          className: @config.className
+          longPressEvent: @config.longPressEvent
+          longPressPayload: @config.longPressPayload
+          swipeLeftEvent: @config.swipeLeftEvent
+          swipeRightEvent: @config.swipeRightEvent
+          dayWindow: @config.dayWindow
+          titleField: @config.titleField
+          startField: @config.startField
+          endField: @config.endField
+          colorField: @config.colorField
+          type: calendar-grid
+        })
       CalendarGridLoaded -> idle
         (render-ui main {
           weekStart: @config.weekStart
@@ -158,6 +178,10 @@ orbital CalendarGridOrbital {
         @label "Color Field"
         @description "Row field holding the chip's Tailwind colour class. Defaults to `color`."
         @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."
+        @tier "internal"
     }
   }
 

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

@@ -41,7 +41,7 @@ orbital DataGridOrbital {
     initial: idle
 
     state idle {
-      INIT -> idle
+      INIT -> idle when @config.selfFetch
         (fetch DataGridItem { emit: { success: DataGridLoaded } })
         (render-ui main {
           dragGroup: @config.dragGroup
@@ -74,6 +74,38 @@ orbital DataGridOrbital {
           look: @config.look
           type: data-grid
         })
+      INIT -> idle when (not @config.selfFetch)
+        (render-ui main {
+          dragGroup: @config.dragGroup
+          accepts: @config.accepts
+          sortable: @config.sortable
+          dropEvent: @config.dropEvent
+          reorderEvent: @config.reorderEvent
+          positionEvent: @config.positionEvent
+          dndItemIdField: @config.dndItemIdField
+          dndRoot: @config.dndRoot
+          entity: @entity
+          fields: @config.fields
+          columns: @config.columns
+          itemActions: @config.itemActions
+          maxInlineActions: @config.maxInlineActions
+          scrollX: @config.scrollX
+          cols: @config.cols
+          gap: @config.gap
+          minCardWidth: @config.minCardWidth
+          className: @config.className
+          isLoading: @config.isLoading
+          error: @config.error
+          imageField: @config.imageField
+          selectable: @config.selectable
+          selectionEvent: @config.selectionEvent
+          infiniteScroll: @config.infiniteScroll
+          loadMoreEvent: @config.loadMoreEvent
+          hasMore: @config.hasMore
+          pageSize: @config.pageSize
+          look: @config.look
+          type: data-grid
+        })
       DataGridLoaded -> idle
         (render-ui main {
           dragGroup: @config.dragGroup
@@ -239,6 +271,10 @@ orbital DataGridOrbital {
         @label "Look"
         @description "Layer 2 visual treatment — mirrors the `entity-table` look enum so data-grid / data-list / entity-table share one knob name from authors."
         @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."
+        @tier "internal"
     }
   }
 

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

@@ -47,7 +47,7 @@ orbital DataListOrbital {
     initial: idle
 
     state idle {
-      INIT -> idle
+      INIT -> idle when @config.selfFetch
         (fetch DataListItem { emit: { success: DataListLoaded } })
         (render-ui main {
           dragGroup: @config.dragGroup
@@ -89,6 +89,47 @@ orbital DataListOrbital {
           look: @config.look
           type: data-list
         })
+      INIT -> idle when (not @config.selfFetch)
+        (render-ui main {
+          dragGroup: @config.dragGroup
+          accepts: @config.accepts
+          sortable: @config.sortable
+          dropEvent: @config.dropEvent
+          reorderEvent: @config.reorderEvent
+          positionEvent: @config.positionEvent
+          dndItemIdField: @config.dndItemIdField
+          dndRoot: @config.dndRoot
+          entity: @entity
+          fields: @config.fields
+          columns: @config.columns
+          itemActions: @config.itemActions
+          maxInlineActions: @config.maxInlineActions
+          itemClickEvent: @config.itemClickEvent
+          gap: @config.gap
+          variant: @config.variant
+          groupBy: @config.groupBy
+          senderField: @config.senderField
+          senderLabelField: @config.senderLabelField
+          currentUser: @config.currentUser
+          emptyMessage: @config.emptyMessage
+          className: @config.className
+          isLoading: @config.isLoading
+          error: @config.error
+          reorderable: @config.reorderable
+          swipeLeftEvent: @config.swipeLeftEvent
+          swipeLeftActions: @config.swipeLeftActions
+          swipeRightEvent: @config.swipeRightEvent
+          swipeRightActions: @config.swipeRightActions
+          longPressEvent: @config.longPressEvent
+          infiniteScroll: @config.infiniteScroll
+          loadMoreEvent: @config.loadMoreEvent
+          hasMore: @config.hasMore
+          pageSize: @config.pageSize
+          sortBy: @config.sortBy
+          sortDirection: @config.sortDirection
+          look: @config.look
+          type: data-list
+        })
       DataListLoaded -> idle
         (render-ui main {
           dragGroup: @config.dragGroup
@@ -319,6 +360,10 @@ orbital DataListOrbital {
         @label "Look"
         @description "Layer 2 visual treatment — mirrors the `entity-table` look enum so data-grid / data-list / entity-table share one knob name from authors."
         @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."
+        @tier "internal"
     }
   }
 

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

@@ -9,9 +9,10 @@ orbital DocumentDetailsOrbital {
     label : string
     header : string
     icon : icon
-    kind : "text" | "boolean" | "select" | "readonly"
+    kind : "text" | "boolean" | "select" | "readonly" | "image"
     options : [string]
     format : "date" | "currency" | "number" | "boolean" | "percent"
+    type : string
   }
 
   entity DocumentDetailsItem [runtime] {
@@ -22,12 +23,23 @@ orbital DocumentDetailsOrbital {
     initial: idle
 
     state idle {
-      INIT -> idle
+      INIT -> idle when @config.selfFetch
         (fetch DocumentDetailsItem { emit: { success: DocumentDetailsLoaded } })
         (render-ui main {
           entity: @entity
           fields: @config.fields
           metaCommitEvent: @config.metaCommitEvent
+          relationEvent: @config.relationEvent
+          title: @config.title
+          className: @config.className
+          type: document-details
+        })
+      INIT -> idle when (not @config.selfFetch)
+        (render-ui main {
+          entity: @entity
+          fields: @config.fields
+          metaCommitEvent: @config.metaCommitEvent
+          relationEvent: @config.relationEvent
           title: @config.title
           className: @config.className
           type: document-details
@@ -37,6 +49,7 @@ orbital DocumentDetailsOrbital {
           entity: @payload.data
           fields: @config.fields
           metaCommitEvent: @config.metaCommitEvent
+          relationEvent: @config.relationEvent
           title: @config.title
           className: @config.className
           type: document-details
@@ -50,6 +63,13 @@ orbital DocumentDetailsOrbital {
       }
         @description "Emitted when a property commits: { id, patch } — patch carries the id plus the one changed field, ready for a partial persist update."
         @tier "essential"
+      @config.relationEvent -> external {
+        field : string!
+        id : string!
+        name : string!
+      }
+        @description "Makes relation chips clickable: emitted with { field, id, name } when a hydrated relation value (or one row of a many-relation) is clicked — the host routes it to the linked record's own surface."
+        @tier "essential"
       DocumentDetailsLoaded
         @description "DocumentDetails rows finished loading; payload.data holds the collection."
         @synonyms "loaded, fetched, retrieved"
@@ -65,6 +85,10 @@ orbital DocumentDetailsOrbital {
         @label "Meta Commit Event"
         @description "Emitted when a property commits: { id, patch } — patch carries the id plus the one changed field, ready for a partial persist update."
         @tier "presentation"
+      relationEvent : string = "RELATION"
+        @label "Relation Event"
+        @description "Makes relation chips clickable: emitted with { field, id, name } when a hydrated relation value (or one row of a many-relation) is clicked — the host routes it to the linked record's own surface."
+        @tier "presentation"
       title : string
         @label "Title"
         @description "Card heading (defaults to the localized 'Details')"
@@ -73,6 +97,10 @@ orbital DocumentDetailsOrbital {
         @label "Class Name"
         @description "className prop"
         @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."
+        @tier "internal"
     }
   }