@almadar/std 16.187.0 → 16.189.0

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

@@ -76,7 +76,7 @@ orbital RelatedItemOrbital {
             gap: sm
             type: stack
           }, { type: divider }, {
-            entity: ?data
+            entity: (array/map ?data (fn row { id: @row.id, name: (object/get @row @config.labelField) }))
             fields: []
             look: @config.tableLook
             renderItem: (fn item {
@@ -218,6 +218,10 @@ orbital RelatedItemOrbital {
         @label "Section title"
         @description "Heading shown above the related list."
         @tier "presentation"
+      labelField : string = name
+        @label "Which field labels each related row?"
+        @description "Name of the field on the (rebound) related row rendered as the row label and carried as SELECT_RELATED's name — set it to `title` (etc.) whenever the bound entity labels rows differently. The rows are mapped through this at render time, because a trait-level `fields {}` rename is declaration-only on the runtime path and every populated row used to render a blank label."
+        @tier "presentation"
       relationField : string = ""
         @label "Relation field"
         @description "RelatedItem field compared against SHOW_RELATED's key to scope the fetch to one parent document; empty renders the full unfiltered collection (default)."

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

@@ -1,5 +1,6 @@
 app std-selection "1.0.0"
 "std-selection as a Function"
+type FilterSpec = { field : string!, label : string, options : [string] }
 orbital SelectableItemOrbital {
     type SelectableItemLoaded = Event { data : [SelectableItem] } "Fired when SelectableItem finishes loading; payload.data holds the list"
 
@@ -46,7 +47,37 @@ orbital SelectableItemOrbital {
             direction: horizontal
             gap: sm
             type: stack
-          }, { type: divider }, {
+          }, (if @config.bodySearch {
+            children: [{
+              className: "w-full max-w-md"
+              clearable: true
+              event: REFETCH_QUERY
+              placeholder: @config.searchPlaceholder
+              type: search-input
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), (if [">", (array/len @config.filters), 0] {
+            children: [{
+              entity: SelectableItem
+              event: REFETCH_FILTER
+              filters: @config.filters
+              look: @config.filterBarLook
+              type: filter-group
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), { type: divider }, {
             color: muted
             content: "Choose a selectableitem to continue."
             type: typography
@@ -61,6 +92,7 @@ orbital SelectableItemOrbital {
               label: Select
             }]
             look: @config.tableLook
+            pageSize: @config.displayPageSize
             renderItem: (fn item {
               align: center
               children: [{ label: @item.name, type: checkbox }]
@@ -105,6 +137,106 @@ orbital SelectableItemOrbital {
     }
 
     state idle {
+      ;; REFETCH_* stays in `idle` and DOES NOT replace the pick-list with a
+      ;; spinner — same reasoning as std-browse's REFETCH_* arms: a skeleton
+      ;; on refetch unmounts the list and flickers every keystroke. The fetch
+      ;; fires in the background; the SelectableItemLoaded arm below
+      ;; re-renders in place once it lands.
+      REFETCH_QUERY -> idle
+        (fetch SelectableItem {
+          emit: { failure: SelectableItemLoadFailed, success: SelectableItemLoaded }
+          filter: (or ["=", ?searchTerm, ""] (str/includes (object/get @entity name) ?searchTerm))
+        })
+      REFETCH_FILTER -> idle
+        (fetch SelectableItem {
+          emit: { failure: SelectableItemLoadFailed, success: SelectableItemLoaded }
+          filter: (or ["=", ?value, ""] ["=", (object/get @entity ?field), ?value])
+        })
+      ;; No filter carried over on REFETCH_PAGE, mirroring std-browse exactly.
+      ;; Paging is safe here: this atom's selection is a single transient id
+      ;; carried only in the SELECT/CONFIRM_SELECTION payload (`?id`), never
+      ;; accumulated into a persisted @entity array, so turning a page cannot
+      ;; strand an "already selected" item — there is no multi-item selection
+      ;; state to strand. A future multi-select variant that DOES accumulate
+      ;; picks into an @entity field would need to carry that array across
+      ;; REFETCH_PAGE explicitly; this single-pick atom does not need to.
+      REFETCH_PAGE -> idle
+        (fetch SelectableItem {
+          emit: { failure: SelectableItemLoadFailed, success: SelectableItemLoaded }
+          limit: @config.pageSize
+          offset: ["*", ["-", ?page, 1], @config.pageSize]
+        })
+      SelectableItemLoaded -> idle
+        (render-ui main {
+          children: [{
+            align: center
+            children: [{ name: check-square, type: icon }, {
+              content: SelectableItems
+              type: typography
+              variant: h2
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          }, (if @config.bodySearch {
+            children: [{
+              className: "w-full max-w-md"
+              clearable: true
+              event: REFETCH_QUERY
+              placeholder: @config.searchPlaceholder
+              type: search-input
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), (if [">", (array/len @config.filters), 0] {
+            children: [{
+              entity: SelectableItem
+              event: REFETCH_FILTER
+              filters: @config.filters
+              look: @config.filterBarLook
+              type: filter-group
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), { type: divider }, {
+            color: muted
+            content: "Choose a selectableitem to continue."
+            type: typography
+            variant: caption
+          }, {
+            className: "transition-shadow hover:shadow-md cursor-pointer"
+            entity: ?data
+            fields: []
+            itemActions: [{
+              event: SELECT
+              icon: check
+              label: Select
+            }]
+            look: @config.tableLook
+            pageSize: @config.displayPageSize
+            renderItem: (fn item {
+              align: center
+              children: [{ label: @item.name, type: checkbox }]
+              direction: horizontal
+              gap: sm
+              type: stack
+            })
+            type: data-grid
+          }]
+          direction: vertical
+          gap: lg
+          type: stack
+        })
       SELECT -> selecting
         (render-ui main {
           children: [{
@@ -269,6 +401,25 @@ orbital SelectableItemOrbital {
         @description "Indicates a selectable item failed to load."
         @synonyms "error, failure, problem, load error"
         @tier "internal"
+      REFETCH_QUERY {
+        searchTerm : string!
+      }
+        @description "Triggers a pick-list refresh based on the current search term."
+        @synonyms "refresh, reload, update, re-query, search"
+        @tier "domain"
+      REFETCH_FILTER {
+        field : string!
+        value : string!
+      }
+        @description "Triggers a pick-list refresh based on current filter criteria."
+        @synonyms "refresh, filter, update, reload"
+        @tier "domain"
+      REFETCH_PAGE {
+        page : number!
+      }
+        @description "Triggers a pick-list page refresh."
+        @synonyms "reload, refresh, update, paginate"
+        @tier "domain"
     }
 
     config {
@@ -276,6 +427,36 @@ orbital SelectableItemOrbital {
         @label "Table look"
         @description "Layer 2 visual treatment for the data table rendered by this atom."
         @tier "presentation"
+      bodySearch : boolean = false
+        @label "Show the pick-list's own search box?"
+        @description "Embeds a search box above the pick-list. Set true only when the page has no other search affordance (e.g. no page-level std-search), so the surface shows one search box instead of two. False is the default — this atom has never had a search box (0 consumers today)."
+        @synonyms "inline search, list search, built-in search, show search"
+        @tier "presentation"
+      searchPlaceholder : string = "Search…"
+        @label "Search box placeholder text"
+        @description "Hint text inside the pick-list search box."
+        @synonyms "search hint, placeholder, search box text"
+        @tier "presentation"
+      filters : [FilterSpec] = []
+        @label "Which filters should appear above the pick-list?"
+        @description "Dropdown filter facets by field, rendered as an embedded filter bar above the rows; each selection fires REFETCH_FILTER on this trait. Empty (the default) = no filter bar, the right setting whenever the page already composes std-filter beside this list and routes XFilter.FILTER -> REFETCH_FILTER — that is the wired owner and remains the primary path. Use this knob only for a standalone pick-list with no page-level filter affordance."
+        @synonyms "filter bar, faceted filters, field filters, dropdowns"
+        @tier "presentation"
+      filterBarLook : "toolbar" | "chips" | "pills" | "popover-trigger" | "inline-column-header" = toolbar
+        @label "Filter bar look"
+        @description "Visual treatment for the embedded filter bar, mirroring std-filter's own enum. Only applies when `filters` is non-empty."
+        @synonyms "filter bar style, facet style, chips, pills"
+        @tier "presentation"
+      pageSize : number = 20
+        @label "How many candidates per page when paging?"
+        @description "Records fetched from the server per REFETCH_PAGE request. The initial load and search/filter refetches remain unpaginated (load every candidate) unless a consumer wires REFETCH_PAGE, so the default pick-list surface is unchanged. Safe to page: this atom's selection is a single transient id (never an accumulated array), so no already-picked item can be stranded on another page."
+        @synonyms "fetch limit, records per page, page limit"
+        @tier "presentation"
+      displayPageSize : number = 20
+        @label "How many candidates to show at once?"
+        @description "Rows visible per page before the data-grid's own pagination control appears — 20 matches the pick-list density sweet spot (Miller's law, 10-25 rows)."
+        @synonyms "visible rows, items per page, display limit, show per page"
+        @tier "presentation"
     }
   }
 

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

@@ -1,5 +1,6 @@
 app std-tree "1.0.0"
-"std-tree — generic hierarchical node browser. Fetches a flat TreeNode collection and renders it through file-tree's flat `items` mode (parentId-nested at render time by the component, not the .lolo); OPEN_NODE is the external handoff for a selected node's id. Rebindable: pass `fields` at the call site to retarget it at any parent-pointer entity (categories, org units, comment threads)."
+"std-tree — generic hierarchical node browser. Fetches a flat TreeNode collection and renders it through file-tree's flat `items` mode (parentId-nested at render time by the component, not the .lolo); OPEN_NODE is the external handoff for a selected node's id. Rebindable: pass `fields` at the call site to retarget it at any parent-pointer entity (categories, org units, comment threads). Search/filter are wired (REFETCH_QUERY/REFETCH_FILTER re-fetch the flat node set server-side); pagination is deliberately NOT offered — a hierarchy is not a paged list, and paging a flat node set would sever children from parents that fell on another page."
+type FilterSpec = { field : string!, label : string, options : [string] }
 orbital TreeNodeOrbital {
     type TreeNodeLoaded = Event { data : [TreeNode] } "Fired when the tree node collection finishes loading"
 
@@ -51,7 +52,37 @@ orbital TreeNodeOrbital {
             direction: horizontal
             gap: sm
             type: stack
-          }, { type: divider }, {
+          }, { type: divider }, (if @config.bodySearch {
+            children: [{
+              className: "w-full max-w-md"
+              clearable: true
+              event: REFETCH_QUERY
+              placeholder: @config.searchPlaceholder
+              type: search-input
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), (if [">", (array/len @config.filters), 0] {
+            children: [{
+              entity: TreeNode
+              event: REFETCH_FILTER
+              filters: @config.filters
+              look: @config.filterBarLook
+              type: filter-group
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), {
             items: (array/map ?data (fn row {
               icon: @row.icon
               id: @row.id
@@ -113,6 +144,22 @@ orbital TreeNodeOrbital {
           gap: md
           type: stack
         })
+      ;; REFETCH_* stays in `browsing` and DOES NOT replace the tree with a
+      ;; spinner — search-as-you-type would otherwise unmount file-tree every
+      ;; keystroke and flicker. The fetch fires in the background; when
+      ;; TreeNodeLoaded arrives (handler below) React reconciles the tree in
+      ;; place. No REFETCH_PAGE: a hierarchy is not a paged list — paging the
+      ;; flat node set would sever children from parents on another page.
+      REFETCH_QUERY -> browsing
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+          filter: (or ["=", ?searchTerm, ""] (str/includes (object/get @entity name) ?searchTerm))
+        })
+      REFETCH_FILTER -> browsing
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+          filter: (or ["=", ?value, ""] ["=", (object/get @entity ?field), ?value])
+        })
       OPEN_NODE -> browsing
         (set @entity.id ?id)
       TreeNodeLoaded -> browsing
@@ -132,7 +179,37 @@ orbital TreeNodeOrbital {
             direction: horizontal
             gap: sm
             type: stack
-          }, { type: divider }, {
+          }, { type: divider }, (if @config.bodySearch {
+            children: [{
+              className: "w-full max-w-md"
+              clearable: true
+              event: REFETCH_QUERY
+              placeholder: @config.searchPlaceholder
+              type: search-input
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), (if [">", (array/len @config.filters), 0] {
+            children: [{
+              entity: TreeNode
+              event: REFETCH_FILTER
+              filters: @config.filters
+              look: @config.filterBarLook
+              type: filter-group
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          } {
+            children: []
+            gap: none
+            type: stack
+          }), {
             items: (array/map ?data (fn row {
               icon: @row.icon
               id: @row.id
@@ -214,6 +291,19 @@ orbital TreeNodeOrbital {
     }
 
     listens {
+      REFETCH_QUERY {
+        searchTerm : string!
+      }
+        @description "Triggers a tree refresh based on the current search query."
+        @synonyms "refresh, reload, update, re-query"
+        @tier "domain"
+      REFETCH_FILTER {
+        field : string!
+        value : string!
+      }
+        @description "Triggers a tree refresh based on current filter criteria."
+        @synonyms "refresh, filter, update, reload"
+        @tier "domain"
       OPEN_NODE {
         id : string!
       }
@@ -240,6 +330,26 @@ orbital TreeNodeOrbital {
         @label "Section title"
         @description "Heading shown above the tree"
         @tier "presentation"
+      bodySearch : boolean = false
+        @label "Show the tree's own search box?"
+        @description "Embeds a search box above the tree that re-fetches the flat node set server-side. Set false (the default) when the page already provides a search affordance (a toolbar Search molecule), so the surface shows one search box instead of two."
+        @synonyms "inline search, list search, built-in search, show search, duplicate search"
+        @tier "presentation"
+      searchPlaceholder : string = "Search…"
+        @label "Search box placeholder text"
+        @description "Hint text inside the tree search box (e.g. 'Search nodes…')."
+        @synonyms "search hint, placeholder, search box text, search label"
+        @tier "presentation"
+      filters : [FilterSpec] = []
+        @label "Which filters should appear above the tree?"
+        @description "Dropdown filter facets by field, rendered as an embedded filter bar above the tree; each selection fires REFETCH_FILTER on this trait, re-fetching the flat node set. Empty (the default) = no filter bar, which is the right setting whenever the page already composes std-filter beside this tree and routes `XFilter.FILTER -> REFETCH_FILTER` — that is the wired owner and remains the primary path."
+        @synonyms "filter bar, faceted filters, field filters, dropdowns"
+        @tier "presentation"
+      filterBarLook : "toolbar" | "chips" | "pills" | "popover-trigger" | "inline-column-header" = toolbar
+        @label "Filter bar look"
+        @description "Visual treatment for the embedded filter bar, mirroring std-filter's own enum. Only applies when `filters` is non-empty."
+        @synonyms "filter bar style, facet style, chips, pills"
+        @tier "presentation"
     }
   }
 

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

@@ -16,7 +16,7 @@ orbital RevisionOrbital {
     versionNumber : number! @description "A sequential identifier representing the revision's order." @synonyms "sequence, order, iteration"
     authorId : string @description "Unique identifier for the user who made the change." @synonyms "user identifier, creator, contributor"
     authorName : string @description "The name of the user who made the change." @synonyms "user, contributor, owner"
-    content : string @description "The textual data of the revision." @synonyms "text, body, data, value"
+    content : string @description "The snapshotted body of the revision — plain text or the rich-text HTML a document-look record carries. Rollback hands the whole row back to the host, which restores content onto the source document." @synonyms "text, body, data, value"
     summary : string @description "A brief explanation of the revision's changes." @synonyms "description, note, comment, explanation"
     searchTerm : string @description "The current search query the user submitted." @synonyms "query, term, q" = ""
     createdAt : string

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

@@ -0,0 +1,80 @@
+app ui-document-details "1.0.0"
+"DocumentDetails — the document's metadata as a compact settings card for the rail beside a DocumentPanel, each property committing in place. — UI factory (1:1 with the @almadar/ui document-details pattern)."
+;; @capabilities "document settings, page details, post settings sidebar, metadata panel, document properties, publish settings"
+orbital DocumentDetailsOrbital {
+    type DocumentDetailsLoaded = Event { data : [DocumentDetailsItem] } "DocumentDetails rows finished loading; payload.data holds the collection"
+  type DocumentDetailsFieldsItem = {
+    name : string
+    key : string
+    label : string
+    header : string
+    icon : icon
+    kind : "text" | "boolean" | "select" | "readonly"
+    options : [string]
+    format : "date" | "currency" | "number" | "boolean" | "percent"
+  }
+
+  entity DocumentDetailsItem [runtime] {
+    id : string!
+  }
+
+  trait DocumentDetailsRender -> @rebindable DocumentDetailsItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (fetch DocumentDetailsItem { emit: { success: DocumentDetailsLoaded } })
+        (render-ui main {
+          entity: @entity
+          fields: @config.fields
+          metaCommitEvent: @config.metaCommitEvent
+          title: @config.title
+          className: @config.className
+          type: document-details
+        })
+      DocumentDetailsLoaded -> idle
+        (render-ui main {
+          entity: @payload.data
+          fields: @config.fields
+          metaCommitEvent: @config.metaCommitEvent
+          title: @config.title
+          className: @config.className
+          type: document-details
+        })
+    }
+
+    emits {
+      @config.metaCommitEvent -> external {
+        id : string!
+        patch : object!
+      }
+        @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"
+      DocumentDetailsLoaded
+        @description "DocumentDetails rows finished loading; payload.data holds the collection."
+        @synonyms "loaded, fetched, retrieved"
+        @tier "essential"
+    }
+
+    config {
+      fields : [DocumentDetailsFieldsItem] = []
+        @label "Fields"
+        @description "The properties shown; empty renders nothing."
+        @tier "presentation"
+      metaCommitEvent : string = "META_COMMIT"
+        @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"
+      title : string
+        @label "Title"
+        @description "Card heading (defaults to the localized 'Details')"
+        @tier "presentation"
+      className : string
+        @label "Class Name"
+        @description "className prop"
+        @tier "presentation"
+    }
+  }
+
+  page "/document-details" as DocumentDetailsPage -> DocumentDetailsRender
+}