bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/components/BbDropdown/types.d.ts

@@ -1,8 +1,10 @@
 import { BbBaseButtonProps } from '../BbBaseButton/types';
+import { PtItemCtx, PtItemMap, PtItemResult, PtValue } from '../../types/passthrough';
 import { Placement } from '../../types/Placement';
 import { IconType } from '../../types/Icon';
 import { DropdownItemVariantType } from '../../types/DropdownItemVariant';
 import { BbOffCanvasProps } from '../BbOffCanvas/types';
+import { ItemProps } from '../../types/ItemProps';
 export type { DropdownItemVariantType };
 export type DropdownTrigger = 'click' | 'contextMenu';
 /**
@@ -12,15 +14,33 @@ export type DropdownTrigger = 'click' | 'contextMenu';
  */
 type DropdownEntryBase = {
     /**
-     * Icon to be displayed after the text. Ignored when the item opens a
-     * submenu (a chevron is shown) or sits in a selectable group (a check is shown).
+     * Icon to be displayed after the text. Not shown when the item opens a
+     * submenu (the chevron is), when it is the selected row of a selectable
+     * group (the check is), or when an append slot fills the region.
      */
     'append:icon'?: IconType;
     /**
-     * Key used to identify the entry. Also acts as the selection token when the
-     * item lives in a selectable group.
+     * Key used to identify the entry. REQUIRED when anything outside the menu
+     * reads it: a row in a `selectable` group (the v-model holds it), a row or
+     * group with its own slot (`#<key>` is named by it), a group bound by a
+     * `<BbDropdownGroup id>` or selectable. Optional on a plain action row (it
+     * runs its `onClick`) and a layout-only group: the dropdown then derives an
+     * internal identity from the text that nothing outside ever sees. A keyless
+     * row in a selectable group renders but can't be selected. Load-bearing
+     * identifiers are written, never derived — `bitboss-ui check` flags a
+     * missing required key where the items are in the same file.
      */
-    key: string;
+    key?: string;
+    /** @internal Set by the dropdown on a row it derived a key for (Q53.17). */
+    keyless?: true;
+    /**
+     * Your own data for this entry, carried untouched to its slots (as
+     * `item.meta`) and to per-item `pt` functions. The dropdown never reads it
+     * and never puts it on the DOM. Typically the record the entry stands for,
+     * e.g. `{ key: clinic.id, text: clinic.name, meta: clinic }`; a fetched
+     * group sets it through `itemProps` (`(clinic) => ({ meta: clinic })`).
+     */
+    meta?: any;
     /** Click handler. */
     onClick?: (...args: any[]) => any;
     /** Icon to be displayed before the text. */
@@ -33,6 +53,22 @@ type DropdownEntryBase = {
      */
     variant?: DropdownItemVariantType;
 };
+/**
+ * The `itemProps` fields of a fetched (pipeline) dropdown group: everything a
+ * hand-written row accepts except its identity and structure (`key`, `text`,
+ * `items`, `group`) and `disabled`. See {@link InternalGroup.itemProps}.
+ */
+export type DropdownItemFields = Omit<BbBaseButtonProps, 'block' | 'tag' | 'type' | 'text' | 'disabled'> & Omit<DropdownEntryBase, 'key'> & {
+    /** Muted second line under the row text. */
+    description: string;
+};
+/**
+ * `itemProps` of a fetched (pipeline) dropdown group — the ADDITIONAL fields of
+ * each fetched row (never its text or value). Public: type a standalone mapper
+ * with it, e.g.
+ * `const memberProps: BbDropdownItemProps<Member> = { description: 'email' }`.
+ */
+export type BbDropdownItemProps<T = any> = ItemProps<T, DropdownItemFields>;
 /**
  * A single actionable menu entry. Extends BbBaseButton (minus layout props) and
  * can open a recursive submenu via `items`.
@@ -89,11 +125,18 @@ export type InternalItem = Omit<BbBaseButtonProps, 'block' | 'tag' | 'type'> & S
     multiple?: never;
     /**
      * Marks a synthetic placeholder row produced for a pipeline group while its
-     * async items load (`'loading'`) or when it resolved empty (`'no-data'`).
+     * async items load (`'loading'`) or when it resolved empty (`'empty'`).
      * Rendered as a non-interactive row that shows `text` or, when provided, the
-     * dropdown's `loading` / `no-data` slot. Internal — set by `BbDropdownGroup`.
+     * dropdown's `loading` / `empty` slot. Internal — set by `BbDropdownGroup`.
+     */
+    placeholder?: 'loading' | 'empty';
+    /**
+     * Marks a row built by the pipeline resolver from a fetched item. Its
+     * `selectable` predicate already ran against the RAW item there, so
+     * `normalizeGroups` must not run it again against this row object.
+     * Internal.
      */
-    placeholder?: 'loading' | 'no-data';
+    fetched?: true;
     /**
      * Optional slot token used to resolve per-item named slots. Primarily set
      * by the pipeline resolver so slot names can be derived from the resolved
@@ -167,12 +210,36 @@ export type InternalGroup = DropdownEntryBase & {
     /**
      * Pipeline groups only. Path/getter producing each item's display text.
      * Defaults to `JSON.stringify(item)` (or the string itself for strings).
+     *
+     * @defaultValue `JSON.stringify(item)`
      */
     itemText?: string | ((item: any) => string);
+    /**
+     * Pipeline groups only. The ADDITIONAL fields of each fetched row — never its
+     * text or value, which stay on `itemText` / `itemValue`. A fetched row takes
+     * every field a hand-written row accepts except its identity and structure
+     * (`key`, `text`, `items`, `group`) and `disabled`: `description`, the icons,
+     * `variant`, `onClick`, `href` / `to` and the rest of the link and Inertia
+     * options.
+     *
+     * Either an object with a path or getter per field
+     * (`{ description: 'email', href: 'url' }`) or one function returning the
+     * fields (`(user) => ({ description: user.email, href: user.url })`). In
+     * the object form a function is always a getter, so a handler field returns
+     * the handler: `onClick: (user) => () => open(user)`.
+     *
+     * Nothing is read off the raw item implicitly — without `itemProps` a row
+     * has only its text. An empty value means the field is absent. To disable
+     * individual rows use a `selectable` predicate on the group; fetched groups
+     * are for selection (see plans/ITEM-DESCRIPTION.md v2.4).
+     */
+    itemProps?: BbDropdownItemProps;
     /**
      * Pipeline groups only. Path/getter producing each item's value — what
      * `v-model` surfaces; its hash is the internal selection key. Defaults to the
      * whole item (so the key is the hash of the entire object).
+     *
+     * @defaultValue the whole item
      */
     itemValue?: string | ((item: any) => any);
     /** Pipeline groups only. Placeholder row text while async items load. */
@@ -187,11 +254,14 @@ export type InternalGroup = DropdownEntryBase & {
      * predictable size regardless of row content. A `number` is pixels; a `string`
      * is any CSS length (`'50vh'`, `'20rem'`). `'none'` (or `0`) removes the cap.
      *
-     * `searchable` groups default to `280` (≈ 10 rows of 28px), since a searched
-     * list is usually long; set your own value to tweak, or `'none'` to uncap.
-     * Non-searchable groups are uncapped unless you set this.
+     * `searchable` groups default to `280` (≈ 10 rows of 28px) **on the flyout**,
+     * since a searched list is usually long; set your own value to tweak, or
+     * `'none'` to uncap. The adaptive sheet ignores the cap so the OffCanvas
+     * body stays the only scroller (nested group overflow trapped swipes that
+     * started on a row). Non-searchable flyout groups are uncapped unless you
+     * set this.
      *
-     * @defaultValue `280` for `searchable` groups, otherwise unset
+     * @defaultValue `280` for `searchable` flyout groups, otherwise unset
      */
     maxHeight?: number | string;
     /**
@@ -200,8 +270,17 @@ export type InternalGroup = DropdownEntryBase & {
      * @defaultValue `false`
      */
     multiple?: boolean;
+    /**
+     * Single selectable groups only: re-clicking the selected row clears the
+     * group (`item:unselected`, `v-model` → `null`). Without it a single group
+     * behaves like a radio group, and a re-click keeps the pick. Means nothing
+     * on a `multiple` group, where a checkbox always unchecks.
+     *
+     * @defaultValue `false`
+     */
+    clearable?: boolean;
     /** Pipeline groups only. Placeholder row text when there are no items. */
-    noDataText?: string;
+    emptyText?: string;
     /**
      * Pipeline groups only. When the group's async items are fetched — same
      * three-state contract as `BbSelect`'s `prefill`:
@@ -228,10 +307,20 @@ export type InternalGroup = DropdownEntryBase & {
     /** Placeholder for this group's search field. Defaults to the localized label. */
     searchPlaceholder?: string;
     /**
-     * When `true`, items act as selectable options that render a check on the
-     * right and keep the menu open when toggled.
+     * When set, items act as selectable options that render a check on the right
+     * and keep the menu open when toggled.
+     *
+     * Pass a function `(item) => boolean` to gate individual rows — the same
+     * contract as `BbSelect` and the option groups. The group is still a
+     * selectable group; a row the function rejects renders disabled (clicks do
+     * nothing, keyboard navigation skips it), and the lock holds on a row that is
+     * already selected. `max` stays a soft cap on top. The function receives the
+     * raw fetched item in a fetched group, the row object in a hand-written one.
+     *
+     * This is how a fetched row is disabled: fetched groups are for selection, so
+     * their `itemProps` has no `disabled` (see the guide).
      */
-    selectable?: boolean;
+    selectable?: boolean | ((item: any) => boolean);
     /**
      * Searchable pipeline groups only. Accumulate the items behind *selected* keys
      * so they stay resolvable across searches. Without it, selecting an item in one
@@ -282,23 +371,43 @@ export type FlatItem<T> = T extends Array<infer U> ? U : T;
  * item's `items` is a submenu array). Without this last case such an entry would
  * be treated as a plain item and its function `items` iterated ("not iterable").
  */
+/**
+ * Whether a declared group is selectable: `selectable` set (a boolean, or a
+ * predicate — which counts as `true`), or `multiple` given an explicit value.
+ * Both unset ⇒ non-selectable. Value-based, not key presence: companion merges
+ * write `multiple: undefined` keys that must not read as selectable.
+ */
+export declare const isSelectableGroup: (entry: Pick<InternalGroup, "selectable" | "multiple">) => boolean;
+/** The group's per-row `selectable` predicate, when it passed one. */
+export declare const selectablePredicateOf: (entry: Pick<InternalGroup, "selectable">) => ((item: any) => boolean) | undefined;
 export declare const isGroup: (entry: Item) => entry is InternalGroup;
 /**
  * A group after normalization: anonymous arrays and loose items become
  * non-selectable groups; {@link InternalGroup} objects keep their metadata. Selection
  * defaults are resolved here. Produced by `normalizeGroups`.
  */
+/**
+ * A row after normalization: its `key` is always set — the consumer's, or one
+ * the dropdown derived for a keyless action row (`keyless`, Q53.17).
+ */
+export type KeyedItem = InternalItem & {
+    key: string;
+};
 export type NormalizedGroup = {
     'append:icon'?: IconType;
+    /** Single groups: a re-click on the selected row clears it. */
+    clearable?: boolean;
     /** Whether a divider is rendered before this group. */
     divider: boolean;
     /** Keys matched against each raw item when searching (empty ⇒ match text). */
     filterBy?: string[];
-    items: InternalItem[];
+    items: KeyedItem[];
     /** Group key (when it originated from a {@link InternalGroup} object). */
     key?: string;
     /** Fixed max-height (px number or CSS length) of this group's item region. */
     maxHeight?: number | string;
+    /** The group's own `meta`, untouched. */
+    meta?: any;
     multiple: boolean;
     onClick?: (...args: any[]) => any;
     'prepend:icon'?: IconType;
@@ -325,7 +434,68 @@ export type MappedItem = InternalItem & {
      */
     onKeydown: (event: KeyboardEvent) => void;
 };
+/**
+ * Passthrough parts of `BbDropdown` (plans/passthrough/BbDropdown.md). Groups,
+ * headings and dividers are not parts.
+ *
+ * Per-item functions: on the instance, an entry part (`item`, `itemText`, `itemIcon`, `itemDescription`) also accepts `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the menu entry (an `Item`: its `text`, `key`, `description`, whatever else you put on it), and every state a boolean beside it, on for it (`selected`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the entry as it was. See the passthrough guide, _Per-item functions_.
+ *
+ * @part root - The floating element — an invisible positioning wrapper; a
+ *   `class` on the component lands here. No node on the phone sheet: style
+ *   what you see with `panel`.
+ * @part panel - The menu surface you see — the bordered flyout box on
+ *   desktop, the sheet itself on a phone.
+ * @part sheet - The bottom sheet the menu becomes on a phone (the
+ *   `BbOffCanvas` root) — never the desktop surface. Applied after `panel`, so it wins a conflict there.
+ * @part header - The menu's header band.
+ * @part footer - The menu's footer band.
+ * @part input - A searchable group's search field — a broadcast: it lands on
+ *   every searchable group's field, desktop and phone alike. Its magnifier
+ *   glyph is chrome.
+ * @part list - The top-level items container between the bands — the node
+ *   that lays the entries out (a flex column with a 1px gap; on a phone, the
+ *   sheet's items container). A submenu's list is not reached. Groups,
+ *   headings and dividers are not parts.
+ * @part item - One menu entry, submenus included — a broadcast resolved per
+ *   entry. Also takes a per-item function, called with the entry.
+ * @part itemText - An entry's label (its `text`) — resolved with that
+ *   entry's states. A per-entry `#<key>` slot replaces it. Also takes a
+ *   per-item function.
+ * @part itemIcon - An entry's prepend / append icons — resolved with that
+ *   entry's states. Also takes a per-item function.
+ * @part itemDescription - An entry's muted second line (its `description`) —
+ *   resolved with that entry's states. A per-entry `#<key>` slot replaces it.
+ *   Also takes a per-item function.
+ */
+export type BbDropdownPtPart = 'root' | 'panel' | 'sheet' | 'header' | 'footer' | 'input' | 'list' | 'item' | 'itemText' | 'itemIcon' | 'itemDescription';
+/** The surface parts — they take a `PtValue` only. Spelled flat (T20). */
+export type BbDropdownSurfacePtPart = 'root' | 'panel' | 'sheet' | 'header' | 'footer' | 'input' | 'list';
+/** The entry parts — broadcasts resolved per entry; their base key also takes a per-item function. Spelled flat (T20). */
+export type BbDropdownItemPtPart = 'item' | 'itemText' | 'itemIcon' | 'itemDescription';
+/**
+ * Passthrough states of `BbDropdown`, true while the matching `--` modifier is on.
+ *
+ * @state selected - Per node, on the entry parts: a selectable group's
+ *   checked entry.
+ * @state disabled - Per node, on the entry parts: an entry that is disabled.
+ * @state open - Component-wide: the menu is open.
+ */
+export type BbDropdownPtState = 'open' | 'selected' | 'disabled';
+/** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
+export declare const BB_DROPDOWN_PT: {
+    readonly parts: readonly ["root", "panel", "sheet", "header", "footer", "input", "list", "item", "itemText", "itemIcon", "itemDescription"];
+    readonly states: readonly ["selected", "disabled", "open"];
+};
 export type BbDropdownProps = {
+    [K in `pt:${BbDropdownSurfacePtPart}` | `pt:${BbDropdownPtPart}:${BbDropdownPtState}`]?: PtValue;
+} & {
+    [K in `pt:${BbDropdownItemPtPart}`]?: PtValue | ((ctx: PtItemCtx<InternalItem, BbDropdownPtState>) => PtItemResult);
+} & {
+    /**
+     * Passthrough, object form: the same keys as the `pt:*` attributes
+     * without the prefix. See the `pt:<part>` row.
+     */
+    pt?: PtItemMap<BbDropdownPtPart, BbDropdownItemPtPart, BbDropdownPtState, InternalItem>;
     /**
      * External activator element or component ref.
      * When provided, the activator slot is not rendered and event listeners
@@ -345,6 +515,17 @@ export type BbDropdownProps = {
      * @defaultValue `config.adaptive` (`true`)
      */
     adaptive?: boolean;
+    /**
+     * Apply the compact density variant — the same ladder `BbSelect` uses, on
+     * both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The
+     * label size does not change; density here is height, as it is for a select.
+     *
+     * A menu row is a touch target in a way a select option is not quite — a
+     * mis-tap fires the neighbouring COMMAND rather than picking the wrong value
+     * — so the compact sheet stops at 36px and never follows the flyout down to
+     * 24px. That is the same floor the select's sheet holds.
+     */
+    compact?: boolean;
     /**
      * Element the panel positions itself against, when it should differ from the
      * activator — e.g. a wrapper that the activator is only a part of, so the menu
@@ -376,7 +557,9 @@ export type BbDropdownProps = {
      */
     enforceCoherence?: boolean;
     /**
-     * The identifier of the component.
+     * Names this dropdown: the activator's id (unless it already has one),
+     * the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a
+     * companion `BbDropdownGroup` pair by. Generated when omitted.
      */
     id?: string;
     /**
@@ -399,21 +582,31 @@ export type BbDropdownProps = {
     loadingText?: string;
     /**
      * Default placeholder text shown when a pipeline group resolves to no items.
-     * A group's own `noDataText` overrides this; both fall back to the localized
-     * `common.noDataText` (`'No data to display'`).
+     * A group's own `emptyText` overrides this; both fall back to the localized
+     * `common.emptyText` (`'No data to display'`).
      */
-    noDataText?: string;
+    emptyText?: string;
     /**
+     * Props for the phone sheet. A `pt` inside it, object or colon keys, styles
+     * only that sheet.
+     *
      * Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders
      * the sheet on mobile. Merged over the adaptive defaults
-     * (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when
+     * (`side: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when
      * `adaptive` is `false`.
+     *
+     * A `pt` inside it styles ONLY the sheet, in `BbOffCanvas`'s part words
+     * (`root`, `header`, `title`, `description`, `content`, `footer`, `close`;
+     * state `open`), object (`{ pt: { header: '…' } }`) or colon keys
+     * (`{ 'pt:header': '…' }`) alike. It merges after what this component
+     * forwards to its sheet, so it wins a conflict and drops nothing — see the
+     * passthrough guide § Inside the sheet.
      */
     offCanvasProps?: Partial<BbOffCanvasProps>;
     /**
      * Space the floating container will maintain from the activator.
      *
-     * @defaultValue `3`
+     * @defaultValue `4`
      */
     offset?: number;
     /**
@@ -424,7 +617,8 @@ export type BbDropdownProps = {
     padding?: number;
     /**
      * Position of the dropdown relative to the activator.
-     * Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow).
+     * Use `'cursor'` to anchor at the mouse/touch coordinates.
+     * (No arrow is drawn either way — arrows are tooltip-only in v3.)
      *
      * @defaultValue `'bottom'`
      */
@@ -438,7 +632,9 @@ export type BbDropdownProps = {
     queryDebounceTime?: number;
     /**
      * How long the transition has to last in milliseconds. Menus use the fast
-     * transition rather than the medium one the other popovers default to.
+     * transition (150) rather than the medium one (250) the other popovers
+     * default to: a menu is opened to pick one command and is gone again, so
+     * it answers faster than a panel the user reads or edits in.
      *
      * @defaultValue `150`
      */
@@ -460,6 +656,14 @@ export type BbDropdownProps = {
     width?: number | string;
 };
 export type BbDropdownEvents = {
+    /** Emitted as soon as the menu (the popover, or the sheet on a phone) starts to open. */
+    (e: 'show'): void;
+    /** Emitted once the menu is open and its open transition has finished. */
+    (e: 'shown'): void;
+    /** Emitted as soon as the menu starts to close. */
+    (e: 'hide'): void;
+    /** Emitted once the menu has finished closing. */
+    (e: 'hidden'): void;
     /**
      * Fired when an item in any selectable group becomes selected. The payload is
      * the item's resolved value (its `item-value` for pipeline groups, else its
@@ -502,12 +706,44 @@ export type BbDropdownEdgeSlotProps = {
     /** The current placement of the dropdown panel. */
     placement: BbDropdownProps['placement'];
 };
+/**
+ * The group a slot renders in, as item slots see it. Anonymous groups (loose
+ * items, plain arrays) have no `key` and no `label`.
+ */
+export type BbDropdownSlotGroup = {
+    /** The group's key, when it was declared as a group object. */
+    key?: string;
+    /** The group's label, when it has one (also when `hideLabel` hides it). */
+    label?: string;
+    /** The group's own `meta`. */
+    meta?: any;
+    /** Whether the group is multi-select. */
+    multiple: boolean;
+    /** Whether the group's rows are choices. */
+    selectable: boolean;
+};
 /** Props exposed by the `item:prepend` and `item:append` slots, and named item slots. */
 export type BbDropdownItemSlotProps = {
     /** The item's muted description line, when set. */
     description?: InternalItem['description'];
     /** Whether this item is disabled. */
     disabled?: InternalItem['disabled'];
+    /**
+     * The group this row sits in. On a group's title line (`groupTitle`), the
+     * group itself.
+     */
+    group: BbDropdownSlotGroup;
+    /**
+     * `true` when the slot is drawing a group's title line rather than a row.
+     * The shared `item:prepend` / `item:append` slots run for both, with the
+     * group passed as `item` on a title line.
+     */
+    groupTitle: boolean;
+    /**
+     * Nesting depth of the menu the slot renders in: `0` for the root menu,
+     * `1` for a submenu, and so on — the same on the flyout and the phone sheet.
+     */
+    level: number;
     /** The zero-based index of this item among the flattened items. */
     index: number;
     /** The raw item object from the `items` prop. */
@@ -526,13 +762,32 @@ export type BbDropdownItemSlotProps = {
     /** The resolved display text for this item. */
     text: InternalItem['text'];
 };
-/** Props exposed by the `loading` and `no-data` placeholder slots. */
+/** Props exposed by the `loading` and `empty` placeholder slots. */
 export type BbDropdownPlaceholderSlotProps = {
     /** Key of the group this placeholder belongs to. */
     groupKey?: string;
-    /** Resolved placeholder text (group `loadingText`/`noDataText` → dropdown default). */
+    /** Resolved placeholder text (group `loadingText`/`emptyText` → dropdown default). */
     text: string;
 };
+/**
+ * Besides the fixed slots, every entry gets named slots from its key run
+ * through `slotKey` (`'practice-switcher'` → `practice_switcher`). The most
+ * specific slot a row has wins: its own, then its group's, then the shared
+ * `item:prepend` / `item:append`. Each edge has ONE occupant: a slot replaces
+ * the `prepend:icon` / `append:icon`. On the trailing edge the selected row's
+ * check beats every slot, a row's own `#<key>:append` beats the submenu
+ * chevron, and the chevron beats the group-wide and shared slots.
+ *
+ * @dynamicSlot `<key>` {BbDropdownItemSlotProps} - One row's content (text and description), by its key; in a fetched group, by its resolved `itemValue`.
+ * @dynamicSlot `<key>:prepend` {BbDropdownItemSlotProps} - One row's leading region; replaces its `prepend:icon`.
+ * @dynamicSlot `<key>:append` {BbDropdownItemSlotProps} - One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
+ * @dynamicSlot `<groupKey>:item` {BbDropdownItemSlotProps} - The content of every row of that group, and no other; a row's own `#<key>` still wins.
+ * @dynamicSlot `<groupKey>:item:prepend` {BbDropdownItemSlotProps} - The leading region of every row of that group — e.g. an avatar per record, drawn from `item.meta`, while other rows keep their `prepend:icon`.
+ * @dynamicSlot `<groupKey>:item:append` {BbDropdownItemSlotProps} - The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
+ * @dynamicSlot `<groupKey>` {BbDropdownItemSlotProps} - That group's title line (the group is passed as `item`, `groupTitle` is `true`).
+ * @dynamicSlot `<groupKey>:prepend` {BbDropdownItemSlotProps} - The leading region of that group's title line.
+ * @dynamicSlot `<groupKey>:append` {BbDropdownItemSlotProps} - The trailing region of that group's title line.
+ */
 export type BbDropdownSlots = {
     /**
      * Hosts `<BbDropdownGroup>` companions. They register their group with the
@@ -548,7 +803,7 @@ export type BbDropdownSlots = {
      * Replaces the default "no data" placeholder row shown in a pipeline group
      * that resolved to no items. Rendered once per empty group.
      */
-    'no-data'?: (props: BbDropdownPlaceholderSlotProps) => any;
+    empty?: (props: BbDropdownPlaceholderSlotProps) => any;
     /**
      * The element that triggers the dropdown to open. Spread `props` onto your trigger element.
      */
@@ -560,11 +815,14 @@ export type BbDropdownSlots = {
      */
     header?: (props: BbDropdownEdgeSlotProps) => any;
     /**
-     * Content rendered before each dropdown item's default button content.
+     * The leading region of every row (and group title line), replacing its
+     * `prepend:icon`. A row's own or its group's named slot wins over it.
      */
     'item:prepend'?: (props: BbDropdownItemSlotProps) => any;
     /**
-     * Content rendered after each dropdown item's default button content.
+     * The trailing region of every row (and group title line), replacing its
+     * `append:icon`. A named slot wins over it; the submenu chevron and the
+     * check on a selected row take its place.
      */
     'item:append'?: (props: BbDropdownItemSlotProps) => any;
     /**

package/dist/components/BbDropdown/types.js

@@ -1,4 +1,23 @@
 //#region src/components/BbDropdown/types.ts
-var e = (e) => Array.isArray(e) ? e : [], t = (e) => !Array.isArray(e) && (e.group === !0 || "selectable" in e || "multiple" in e || typeof e.items == "function");
+var e = (e) => Array.isArray(e) ? e : [], t = (e) => e.selectable == null ? e.multiple != null : !!e.selectable, n = (e) => typeof e.selectable == "function" ? e.selectable : void 0, r = (e) => !Array.isArray(e) && (e.group === !0 || "selectable" in e || "multiple" in e || typeof e.items == "function"), i = {
+	parts: [
+		"root",
+		"panel",
+		"sheet",
+		"header",
+		"footer",
+		"input",
+		"list",
+		"item",
+		"itemText",
+		"itemIcon",
+		"itemDescription"
+	],
+	states: [
+		"selected",
+		"disabled",
+		"open"
+	]
+};
 //#endregion
-export { e as groupItemsAsArray, t as isGroup };
+export { i as BB_DROPDOWN_PT, e as groupItemsAsArray, r as isGroup, t as isSelectableGroup, n as selectablePredicateOf };

package/dist/components/BbDropdown/useDropdownContext.d.ts

@@ -1,11 +1,17 @@
 import { ComputedRef, Ref, Slots } from 'vue';
-import { BbDropdownProps, InternalItem, NormalizedGroup } from './types';
+import { BbDropdownProps, KeyedItem, NormalizedGroup, BbDropdownPtPart, BbDropdownPtState } from './types';
+import { PassthroughBindings } from '../../composables/usePassthrough';
 /**
  * Shared state and actions published by `BbDropdown` to every (recursive)
  * `BbDropdownList`. Passing it through provide/inject keeps the recursive
  * panel free of prop-drilling across submenu levels.
  */
 export type DropdownContext = {
+    /**
+     * The dropdown's passthrough resolver: the lists resolve `item` (and its `itemText` / `itemIcon` / `itemDescription`) per entry
+     * with `part()`, the adaptive sheet forwards `root` / `header` / `footer`.
+     */
+    passthrough: PassthroughBindings<BbDropdownPtPart, BbDropdownPtState>;
     /** Root component id, used to derive item ids and the activator selector. */
     rootId: string;
     /**
@@ -25,7 +31,7 @@ export type DropdownContext = {
     /** Dropdown-level default placeholder text while a pipeline group loads. */
     loadingText: ComputedRef<string | undefined>;
     /** Dropdown-level default placeholder text when a pipeline group is empty. */
-    noDataText: ComputedRef<string | undefined>;
+    emptyText: ComputedRef<string | undefined>;
     /** Dropdown-level default for pipeline-group selection coherence enforcement. */
     enforceCoherence: ComputedRef<boolean | undefined>;
     /** Live search query for a searchable group, by group key ('' when none). */
@@ -73,7 +79,7 @@ export type DropdownContext = {
      * `item:selected`/`item:unselected` events and handling the top-level
      * single-group radio auto-close.
      */
-    toggleSelect: (group: NormalizedGroup, item: InternalItem) => void;
+    toggleSelect: (group: NormalizedGroup, item: KeyedItem) => void;
     /** Whether `item`'s async `onClick` is currently in flight (per item key). */
     isItemLoading: (key: string) => boolean;
     /**
@@ -83,7 +89,7 @@ export type DropdownContext = {
      * Without `close` (selectable items) the menu stays open and the item is
      * flagged as loading until the handler settles.
      */
-    runItemAction: (item: InternalItem, event: Event, options?: {
+    runItemAction: (item: KeyedItem, event: Event, options?: {
         close?: boolean;
     }) => Promise<void>;
     /** `BbDropdown`'s slots, forwarded so any level can render named item slots. */

package/dist/components/BbDropdown/useDropdownGroupRegistry.d.ts

@@ -62,6 +62,7 @@ export type DropdownGroupRegistry = {
         valueByKey: Map<string, any>;
         itemByKey: Map<string, any>;
         textByKey: Map<string, string>;
+        descriptionByKey: Map<string, string>;
     } | null) => void;
     /**
      * Published by the internal pipeline resolver: whether a re-fetch is running

package/dist/components/BbDropdownButton/BbDropdownButton.vue.d.ts

@@ -1,8 +1,23 @@
-import { BbDropdownButtonProps, BbDropdownButtonSlots } from './types';
-export type { BbDropdownButtonProps, BbDropdownButtonSlots };
+import { BbDropdownButtonEvents, BbDropdownButtonProps, BbDropdownButtonSlots } from './types';
+export type { BbDropdownButtonEvents, BbDropdownButtonProps, BbDropdownButtonSlots, };
 type __VLS_Slots = BbDropdownButtonSlots;
-declare const __VLS_base: import('vue').DefineComponent<BbDropdownButtonProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<BbDropdownButtonProps> & Readonly<{}>, {
+declare const __VLS_base: import('vue').DefineComponent<BbDropdownButtonProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "item:selected": (value: any) => any;
+    "item:unselected": (value: any) => any;
+    show: () => any;
+    shown: () => any;
+    hide: () => any;
+    hidden: () => any;
+}, string, import('vue').PublicProps, Readonly<BbDropdownButtonProps> & Readonly<{
+    "onItem:selected"?: ((value: any) => any) | undefined;
+    "onItem:unselected"?: ((value: any) => any) | undefined;
+    onShow?: (() => any) | undefined;
+    onShown?: (() => any) | undefined;
+    onHide?: (() => any) | undefined;
+    onHidden?: (() => any) | undefined;
+}>, {
     size: import('../..').Responsive<"sm" | "md" | "lg" | "xl" | "2xl" | "xs">;
+    adaptive: boolean;
     variant: import('../..').ButtonVariantType;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;