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

package/dist/ai/BbSelect.md

@@ -1617,7 +1617,11 @@ const createLabel = (text: string) => {
 Set `group-by` to a field path (or a function) to bucket options under headers.
 The `#group` slot styles the header and receives
 `{ text, item, index, length, disabled }` — `length` is the number of options
-in the group, `index` the list index of its first option.
+in the group, `index` the list index of its first option. A row whose
+`group-by` gives `null` or `undefined` has no group: those rows are listed
+without a header, and `#group` is not called for them (a known row is listed
+the same way). Rows in the middle of the list with no header read as part of
+the group above, so give them a group of their own (`row.team ?? 'Other'`).
 
 A grouped list virtualizes **whole groups, not rows**: a group mounts only
 when it scrolls into range, but all of its rows mount together. Many
@@ -1895,6 +1899,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).
 
@@ -2344,7 +2350,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `description` — scope: `BbSelectDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `empty` — scope: `{ query: string; focus: () => void; error: unknown; }` — Content shown when no options match the query or the list is empty. `error` is what the latest failed load threw, untouched (`null` when none).
 - `footer` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
-- `group` — scope: `BbSelectGroupSlotProps<T>` `{ text: string; item: T; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above grouped options.
+- `group` — scope: `BbSelectGroupSlotProps<T>` `{ text: string; item: T; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above grouped options. Not called for rows with no group (`group-by` gives `null`/`undefined`, known rows): they are listed without a header.
 - `header` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
 - `label` — scope: `BbSelectLabelSlotProps` `{ showAsterisk?: boolean; text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered above the input.
 - `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.

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). |
@@ -1870,7 +1916,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `activator` — scope: `BbSelectPopoverActivatorSlotProps` `{ clear: () => void; close: () => Promise<void>; focus: () => void; disabled: boolean; loading: boolean; open: () => Promise<void>; props: { ref: (reference: unknown) => void; }; query: string; readonly: boolean; selectedOptions: BbSelectResolvedOption<any>[]; shown: boolean; text: string; toggle: () => Promise<void> }` — Replaces the default trigger element that opens the select popover.
 - `empty` — scope: `{ query: string; focus: () => void; error: unknown; }` — Content shown when no options match the query or the list is empty. `error` is what the latest failed load threw, untouched (`null` when none).
 - `footer` — scope: `BbSelectPopoverPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption<any>[] }` — Content pinned to the bottom of the panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
-- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` `{ disabled: boolean; index: number; item: Item; length: number; text: string }` — Replaces the default group header rendered above grouped options.
+- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` `{ disabled: boolean; index: number; item: Item; length: number; text: string }` — Replaces the default group header rendered above grouped options. Not called for rows with no group (`group-by` gives `null`/`undefined`, known rows): they are listed without a header.
 - `header` — scope: `BbSelectPopoverPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption<any>[] }` — Content pinned to the top of the panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
 - `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
 - `option` — scope: `BbSelectPopoverOptionSlotProps<Item>` `{ disabled: boolean; focused: boolean; index: number; item: Item; loading: boolean; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row in the dropdown.

package/dist/ai/GroupedListBox.md

@@ -53,7 +53,7 @@
 ## Slots
 
 - `empty` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
-- `group` — scope: `GroupedListBoxGroupSlotProps<Item>` `{ text: string; item: Item; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above each group of options.
+- `group` — scope: `GroupedListBoxGroupSlotProps<Item>` `{ text: string; item: Item; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above each group of options. A group whose `data` is `null`/`undefined` has no header, so no call.
 - `loading` — scope: `object` — Content shown while items are loading (replaces the default loading text).
 - `option` — scope: `GroupedListBoxOptionSlotProps<Item>` `{ disabled: boolean; focused: boolean; index: number; item: Item; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row within a group.
 - `options:append` — scope: `object` — Content appended inside the options list, after the last group.

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.61",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -69,7 +69,9 @@
 		"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",
+		"3.0.0-beta.61"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -103,7 +105,7 @@
 			"class": 138
 		},
 		"unreleased": 0,
-		"added": 408
+		"added": 409
 	},
 	"added": {
 		"3.0.0-alpha.1": [
@@ -2056,6 +2058,15 @@
 					"BbSelectPopover"
 				]
 			}
+		],
+		"3.0.0-beta.60": [
+			{
+				"text": "select-popover · known-items prop names the activator text at rest",
+				"components": [
+					"BbSelect",
+					"BbSelectPopover"
+				]
+			}
 		]
 	},
 	"breaking": [