bitboss-ui 3.0.0-beta.59 → 3.0.0-beta.60

package/dist/ai/BbSelect.md

@@ -1895,6 +1895,8 @@ Shipped behavior — never reimplement it:
 - Picking in single mode closes the panel and refocuses the control; in
   multiple mode the panel stays open and focus returns to the search field.
 - Clicks or focus outside the control and panel close it.
+- The list opens scrolled to its first selected option, else to the top, and
+  every new query scrolls it back to its first match.
 - `disabled`, `readonly` and `loading` suppress the open/navigate bindings
   (`Esc` still closes an open panel).
 

package/dist/ai/BbSelectPopover.md

@@ -201,16 +201,19 @@ open/close handlers. The full slot scope:
 - `text` — display text of the current selection — **popover state** (see below).
 - `disabled` / `readonly` / `loading` — state mirrors for styling the trigger.
 
-**The trigger must not depend on the popover's state — label it from your own
-data.** The popover is an _optional_ editing affordance: it may never be opened,
-and whether it has been opened must never change how the trigger reads. `text`
-and `selectedOptions` resolve the model against **loaded options**, so with a
-provider they stay empty until that provider first runs — by default, the first
-open. A trigger fed from them renders blank and then flickers into truth; a
-trigger fed from your own data is correct on first paint and stays that way.
-
-The robust pattern — used in the example — is a `computed` that resolves the
-label from the model against your own data:
+**The trigger must not depend on whether the popover was opened — pass known
+rows, or label it yourself.** The popover is an _optional_ editing affordance:
+it may never be opened, and whether it has been opened must never change how
+the trigger reads. `text` and `selectedOptions` resolve the model against
+**loaded options**, so with a provider they stay empty until that provider
+first runs — by default, the first open — unless `known-items` name the value
+(see [Rows you already hold](#rows-you-already-hold-known-items)). A trigger
+fed from loaded options alone renders blank and then flickers into truth; a
+trigger fed from known rows or from your own data is correct on first paint and
+stays that way.
+
+The other robust pattern — used in the example — is a `computed` that resolves
+the label from the model against your own data:
 
 ```ts
 const assigneeLabel = computed(
@@ -527,6 +530,43 @@ const destinationLabel = computed(
 </script>
 ```
 
+#### Rows you already hold: `known-items`
+
+When you already hold the selected record (`task.assignee` is
+`{ id, name }`), pass it as a `{ value, label }` row in `known-items`, whatever
+shape the options have. The activator's `text` and `selectedOptions` name the
+value from the first paint, with **no request** until the first open
+(`prefill: true` still loads on mount). A `null` entry names nothing, so an
+unassigned task falls back to your own text. With `multiple`, rows that name
+only some of the picks name none of them until the first open:
+
+```vue
+<BbSelectPopover
+	v-model="assigneeId"
+	item-text="name"
+	item-value="id"
+	:items="searchPeople"
+	:known-items="[
+		task.assignee && { value: task.assignee.id, label: task.assignee.name },
+	]"
+	:filter-by="false"
+>
+	<template #activator="{ props, text }">
+		<BbButton v-bind="props" :text="text || 'Unassigned'" />
+	</template>
+</BbSelectPopover>
+```
+
+It is the same prop as `BbSelect`'s, with the same rules: the provider does
+not change (the first open still asks for the picks by id), a value no row
+names loads as it would without the prop, the options' accessors never run on
+a known row (slots get it as `item` until the list brings its own), the rows
+are never listed unless selected, they vouch for their values under
+`enforce-coherence` until a parent change, and a selected row the list lacks is
+listed first. The details are in the BbSelect guide (_Rows the form already
+holds_). A row per table cell is the inline-edit case below: there a label
+from data you already hold is just as good.
+
 ### Laziness, prefill and the trigger label
 
 `prefill` controls **when the first load happens**: `'interaction'` (default) on
@@ -536,6 +576,10 @@ but only on a host that can transfer the result — see
 Opening the panel is not a search, so it loads nothing; until the first query the
 list shows a _"search to begin"_ hint instead of "no data".
 
+Opening never waits for the first load: the panel shows its loading state and the
+search field (or, with writing disabled, the focus proxy) takes focus at once, so
+keys typed while the first load runs land in the search.
+
 Reach for `false` when the result set is too large or too expensive to browse and
 the query is the only sensible entry point — a user picker over thousands of
 rows. Note the panel is deliberately empty on open: that is the mode telling the
@@ -567,9 +611,10 @@ a seeded model to an eager prefill the way in-field `BbSelect` does. That
 laziness is deliberate: a fetch per instance must be something you ask for (see
 _One popover per table row_).
 
-**Do not reach for `prefill: true` to fix a trigger label.** Resolve the label
-from your own state instead (above) — a trigger that needs a fetch to render is
-a trigger that renders wrong until the fetch lands.
+**Do not reach for `prefill: true` to fix a trigger label.** Pass
+`known-items`, or resolve the label from your own state (above) — a trigger
+that needs a fetch to render is a trigger that renders wrong until the fetch
+lands.
 
 ### Dependent fields and coherence
 
@@ -1659,8 +1704,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 - `multiple` with a non-array model **throws at setup** — seed `ref([])`.
 - A seeded model shows **no trigger `text`** until the first load (no eager
-  prefill upgrade, by design) — resolve the label from your own state. Array
-  `items` resolve on mount, so this only bites providers.
+  prefill upgrade, by design) — pass `known-items`, or resolve the label from
+  your own state. Array `items` resolve on mount, so this only bites providers.
 - The local substring filter also applies to provider results — server matches
   whose text doesn't contain the query are hidden — unless you set
   `:filter-by="false"`, which a provider that searches on the server needs.
@@ -1700,9 +1745,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 ### Anti-patterns
 
-- Reading `text` (or `selectedOptions`) for the trigger label instead of
-  computing it from your own state — with a provider they are empty until the
-  first load, so the trigger's appearance ends up depending on whether the panel
+- Reading `text` (or `selectedOptions`) for the trigger label with neither
+  `known-items` nor a label from your own state — with a provider they are
+  empty until the first load, so the trigger's appearance ends up depending on whether the panel
   was ever opened.
 - Binding many instances to **one shared ref**: each judges the same value against
   its own options and every instance that disagrees emits `null`, so the user's
@@ -1803,6 +1848,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `items` | `Item[] \| ((context: BbSelectPopoverItemsContext) => Item[] \| Promise<Item[]>)` | `[]` | yes | The options: an array, or a sync or async provider given a `BbSelectPopoverItemsContext` (`query`, `reason`, `modelValue`, `signal`). Branch on `reason !== 'search'` to resolve the selection by id. A provider fails by THROWING, never by returning `[]`. |
 | `itemText` | `ItemAccessor<Item, string> \| undefined` | `own `label`, else `text`, else `JSON.stringify(item)`` |  | Path to item property for display text or function to extract it. Unset: own `label`, else `text` (`{ label, value }` needs no accessor). |
 | `itemValue` | `ItemAccessor<Item> \| undefined` | `own `value`, else the whole item` |  | Path to item property for value or function to extract it. Unset: own `value`, even `null`. |
+| `knownItems` | `(BbSelectKnownItem \| null \| undefined)[] \| undefined` |  |  | `{ value, label }` rows naming the value the app already holds, whatever the options' shape: the activator's `text` with no request until the first open (`prefill: true` still loads). Not options; the options' accessors never run on them; slots get the row as `item` until the list brings its own. |
 | `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `loadingText` | `string \| undefined` |  |  | Message shown while items are being loaded. |
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items (limits selection when `multiple` is true). |

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 3,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.59",
+	"version": "3.0.0-beta.60",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -69,7 +69,8 @@
 		"3.0.0-beta.56",
 		"3.0.0-beta.57",
 		"3.0.0-beta.58",
-		"3.0.0-beta.59"
+		"3.0.0-beta.59",
+		"3.0.0-beta.60"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -103,7 +104,7 @@
 			"class": 138
 		},
 		"unreleased": 0,
-		"added": 408
+		"added": 409
 	},
 	"added": {
 		"3.0.0-alpha.1": [
@@ -2056,6 +2057,15 @@
 					"BbSelectPopover"
 				]
 			}
+		],
+		"3.0.0-beta.60": [
+			{
+				"text": "select-popover · known-items prop names the activator text at rest",
+				"components": [
+					"BbSelect",
+					"BbSelectPopover"
+				]
+			}
 		]
 	},
 	"breaking": [