bubble-toolbar 1.0.0 → 1.2.0

package/README.md

@@ -155,6 +155,146 @@ Both toolbar and group accept these props; group appearance overrides the toolba
 
 The effect follows circular and pill shapes without changing their dimensions. With `prefers-reduced-motion: reduce`, the border remains visible and static. Browsers without animated custom property support retain a static gradient; browsers without CSS masking retain a static colored border.
 
+## Live Activities
+
+Like iOS Live Activities: while a task runs, the whole toolbar collapses into a single pill with a spinner; when it finishes, the pill becomes a card with the result and a close button; after its duration (or on close) the toolbar is restored. The groups stay mounted the whole time, so their state (an open search, a counter) is kept.
+
+```tsx
+import { BubbleToolbar, useBubbleLiveActivity } from 'bubble-toolbar';
+
+export function App() {
+  const live = useBubbleLiveActivity({ duration: 4000 });
+
+  const upload = async (files: File[]) => {
+    // Resolves or rejects exactly like the task itself.
+    const result = await live.run(() => api.upload(files), {
+      pending: { title: 'Uploading…' },
+      success: (r) => ({ title: 'Upload complete', description: `${r.count} files ready` }),
+      error: (e) => ({ title: 'Upload failed', description: String(e) }),
+    });
+    return result;
+  };
+
+  return (
+    <>
+      <UploadButton onFiles={upload} />
+      <BubbleToolbar position="top" liveActivity={live}>
+        {/* groups */}
+      </BubbleToolbar>
+    </>
+  );
+}
+```
+
+- `live.run(task, options)` shows the task and returns its own promise. `live.show(content, { duration })` shows a card without a task, and `live.dismiss()` closes the current one.
+- Activities are queued (FIFO). The pill shows `+n` when more are waiting, and a task that already finished goes straight to its card.
+- The pill stays at least `minPendingMs` (600ms by default) so fast tasks do not flicker. `duration: 0` keeps the card until it is closed.
+- The timer pauses while the card is hovered or focused. Esc closes the card. Results are announced through a polite live region, and errors through an alert.
+- If focus was inside the toolbar, it moves to the pill and comes back to the same element afterwards.
+- Inside the toolbar, `useBubbleToolbarLiveActivity()` returns the same controller without passing it down.
+- Content has a fixed shape: `{ title, description?, icon?, tone?: 'neutral' | 'success' | 'error' }`. Texts go in `labels` (`pending`, `success`, `error`, `close`, `group`) and the look in `tokens`, both as `useBubbleLiveActivity` options.
+- With `prefers-reduced-motion`, the toolbar switches without the width morph.
+
+| `tokens` key | CSS variable | Default | Guard |
+| :--- | :--- | :--- | :--- |
+| `compactWidth` | `--bubble-live-compact-width` | `200px` | Capped at `100vw - 32px` |
+| `width` | `--bubble-live-width` | `360px` | Capped at `100vw - 32px` |
+| `radius` | `--bubble-live-radius` | `24px` | |
+| `progressColor` | `--bubble-live-progress-color` | `currentColor` at 40% | |
+| `successColor` / `errorColor` | `--bubble-live-success-color` / `--bubble-live-error-color` | `#22c55e` / `#ef4444` | |
+| `titleSize` | `--bubble-live-title-size` | `13px` | 11–18px |
+| `metaSize` | `--bubble-live-meta-size` | `11px` | 9–14px |
+| `duration` | `--bubble-live-duration` | `320ms` | 0–600ms |
+
+## Search and breadcrumb search
+
+`BubbleSearch` is a search bubble: a button that expands into an accessible combobox with async results. `BubbleBreadcrumbSearch` shows the current location as a breadcrumb and turns into the same search when its button is pressed.
+
+```tsx
+import { BubbleBreadcrumbSearch, BubbleToolbar } from 'bubble-toolbar';
+
+const searchPages = async (query: string, signal: AbortSignal) => {
+  const response = await fetch(`/api/pages?q=${encodeURIComponent(query)}`, { signal });
+  return response.json(); // [{ id, title, description? }]
+};
+
+export function Header({ location, navigate }) {
+  return (
+    <BubbleToolbar position="top" style={{ alignItems: 'flex-start' }}>
+      <BubbleToolbar.BreadcrumbSearch
+        items={location} // [{ label: 'Projects', href: '/projects' }, { label: 'Overview' }]
+        onSearch={searchPages}
+        onSelect={(page) => navigate(page.id)}
+        suggestions={recentPages}
+        labels={{ location: 'Current page', placeholder: 'Search pages…' }}
+      />
+    </BubbleToolbar>
+  );
+}
+```
+
+- `onSearch` receives the trimmed, lower-cased query and an `AbortSignal`. The signal is aborted when the query changes, the search closes or the component unmounts, so stale results never replace newer ones. While a search is pending, the group shows the async activity border.
+- Items have a fixed shape, `{ id, title, description? }`, so the listbox layout and keyboard navigation always work.
+- The breadcrumb is controlled: pass the current `items` (usually from your router) and update them in `onSelect`. The last item is the current page and stays visible while parent levels truncate first.
+- Keyboard: ↑ ↓ move through options, Enter selects, Esc closes and returns focus to the button. Clicking or tabbing outside closes the search.
+- Without a breadcrumb, `BubbleSearch` is a circle while closed and expands when opened.
+- In `top` and `static` toolbars the panel opens downward; give the toolbar `alignItems: 'flex-start'` so the other groups stay in place. In `bottom` toolbars it opens upward; use `alignItems: 'flex-end'`.
+- The open/close collapse is applied inline, so the search works without `styles.css`; import it for the default look and the token-driven styles.
+
+## Theming with tokens
+
+Customization goes through CSS custom properties. Structure, layout and behavior stay fixed, and tokens that could break the layout are clamped. Import `bubble-toolbar/styles.css` to get the defaults.
+
+Toolbar tokens, set on `:root` or any ancestor:
+
+| Token | Default |
+| :--- | :--- |
+| `--bubble-blur` | `16px` (ignored when `blurAmount` is set) |
+| `--bubble-glass-bg` / `--bubble-glass-bg-solid` | `rgba(255, 255, 255, 0.65)` / `rgba(255, 255, 255, 0.92)` |
+| `--bubble-glass-border` / `--bubble-glass-fg` | `rgba(255, 255, 255, 0.4)` / `#09090b` |
+| `--bubble-glass-shadow` | Default floating shadow |
+| `--bubble-light-bg` / `-bg-solid` / `-border` / `-fg` | `rgba(255, 255, 255, 0.75)` / `0.95` / `rgba(0, 0, 0, 0.08)` / `#18181b` |
+| `--bubble-dark-bg` / `-bg-solid` / `-border` / `-fg` | `rgba(24, 24, 27, 0.72)` / `0.95` / `rgba(255, 255, 255, 0.12)` / `#f4f4f5` |
+| `--bubble-button-hover-bg` / `--bubble-button-active-bg` | `rgba(0, 0, 0, 0.05)` / `rgba(0, 0, 0, 0.08)` |
+| `--bubble-focus-ring` | `#3b82f6` |
+
+The `blurred` prop picks the `-bg` (translucent) or `-bg-solid` variant. A string `shadow` prop still wins over `--bubble-glass-shadow`.
+
+Search tokens can be passed through the typed `tokens` prop, where numbers become `px` (or `ms` for `duration`), or set as CSS variables:
+
+```tsx
+<BubbleToolbar.Search tokens={{ width: 420, radius: 14, focusRing: '#f97316' }} … />
+```
+
+```css
+.brand-search {
+  --bubble-search-option-active-bg: rgb(249 115 22 / 16%);
+}
+```
+
+| `tokens` key | CSS variable | Default | Guard |
+| :--- | :--- | :--- | :--- |
+| `width` | `--bubble-search-width` | `360px` | Capped at `100vw - 96px` |
+| `radius` | `--bubble-search-radius` | `24px` | |
+| `divider` | `--bubble-search-divider` | `rgb(128 128 128 / 18%)` | |
+| `focusRing` | `--bubble-search-focus-ring` | `#818cf8` | |
+| `optionActiveBg` | `--bubble-search-option-active-bg` | `rgb(129 140 248 / 18%)` | |
+| `optionRadius` | `--bubble-search-option-radius` | `12px` | |
+| `titleSize` | `--bubble-search-title-size` | `13px` | 10–20px |
+| `titleWeight` | `--bubble-search-title-weight` | `600` | |
+| `metaSize` | `--bubble-search-meta-size` | `11px` | 9–16px |
+| `mutedOpacity` | `--bubble-search-muted-opacity` | `0.7` | 0.4–1 |
+| `resultsMaxHeight` | `--bubble-search-results-max-height` | `220px` | Capped at `100dvh - 208px` |
+| `panelPadding` | `--bubble-search-panel-padding` | `8px` | 0–16px |
+| `duration` | `--bubble-search-duration` | `180ms` | 0–600ms |
+| `easing` | `--bubble-search-easing` | `ease` | |
+| `breadcrumbSize` | `--bubble-breadcrumb-size` | `12px` | 10–16px |
+| `breadcrumbSeparatorColor` | `--bubble-breadcrumb-separator-color` | `currentColor` | |
+| `breadcrumbCurrentWeight` | `--bubble-breadcrumb-current-weight` | `500` | |
+| `breadcrumbMutedOpacity` | `--bubble-breadcrumb-muted-opacity` | `0.7` | 0.4–1 |
+
+Unknown `tokens` keys are ignored. The `breadcrumb*` keys only apply to `BubbleBreadcrumbSearch`.
+
 ## Adaptive shapes
 
 | Group content | Shape | Behavior |
@@ -176,12 +316,13 @@ Use the `shape` prop on a group to override its automatic shape.
 | `theme` | `'glass' \| 'light' \| 'dark' \| 'auto'` | `'glass'` | Visual theme. |
 | `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | Group height and circle diameter: 40px, 48px, 56px, or a custom pixel value. |
 | `blurred` | `boolean` | `true` | Enables background blur. |
-| `blurAmount` | `number \| string` | `16` | Blur radius in pixels or a CSS length. |
+| `blurAmount` | `number \| string` | `--bubble-blur` | Blur radius in pixels or a CSS length. Overrides the `--bubble-blur` token; negative numbers become `0`. |
 | `groupGap` | `number \| string` | `8` | Space between groups, in pixels or a CSS length. |
 | `itemGap` | `number \| string` | `8` | Space between children within a pill. |
 | `bordered` | `boolean` | `true` | Shows subtle borders. |
 | `shadow` | `boolean \| string` | `true` | Enables the default shadow or supplies a custom CSS shadow. |
 | `ariaLabel` | `string` | `'Toolbar'` | Accessible toolbar label. |
+| `liveActivity` | `BubbleLiveActivityController` | `undefined` | Controller from `useBubbleLiveActivity`; see [Live Activities](#live-activities). |
 
 ### `<BubbleGroup />` / `<BubbleToolbar.Group />`
 
@@ -211,7 +352,34 @@ Use the `shape` prop on a group to override its automatic shape.
 | `minWidth` | `number \| string` | `120` | Minimum width in pixels or a CSS length. |
 | `maxWidth` | `number \| string` | `undefined` | Maximum width in pixels or a CSS length. |
 
-All components accept `className`, `style`, and standard attributes for their underlying element. Toolbar, group, and area refs point to a `div`; icon button refs point to a `button`.
+### `<BubbleSearch />` / `<BubbleToolbar.Search />`
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `onSearch` | `(query, signal) => Promise<T[]>` | Required | Async search; `T extends { id, title, description? }`. |
+| `onSelect` | `(item: T) => void` | Required | Called when an option is chosen. |
+| `suggestions` | `T[]` | `[]` | Shown for an empty query and when nothing matches. |
+| `onError` | `(error: unknown) => void` | `undefined` | Search errors other than cancellations. |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` / `boolean` / `(open) => void` | Uncontrolled, `false` | Controlled or uncontrolled open state. |
+| `debounceMs` | `number` | `0` | Delay before searching. |
+| `labels` | `Partial<BubbleSearchLabels>` | English | Accessible names and visible texts (`group`, `button`, `input`, `listbox`, `placeholder`, `searching`, `noResults`, `suggestions`, `results(count)`, `hint`). |
+| `tokens` | `BubbleSearchTokens` | `undefined` | See [Theming with tokens](#theming-with-tokens). |
+| `className` | `string` | `undefined` | Class for the group, useful to scope tokens. |
+
+### `<BubbleBreadcrumbSearch />` / `<BubbleToolbar.BreadcrumbSearch />`
+
+Accepts every `BubbleSearch` prop, plus:
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `{ label: string; href?: string }[]` | Required | Current location; the last item is the current page. |
+| `separator` | `string` | `'/'` | Text between levels. |
+| `labels.location` | `string` | `'Breadcrumb'` | Accessible name of the breadcrumb navigation. |
+| `tokens` | `BubbleBreadcrumbSearchTokens` | `undefined` | Search tokens plus `breadcrumb*` tokens. |
+
+The search components intentionally accept no `style` and render a fixed structure; refs point to the group `div`.
+
+The toolbar, group, area and icon button accept `className`, `style`, and standard attributes for their underlying element. Toolbar, group, and area refs point to a `div`; icon button refs point to a `button`.
 
 ## Development
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { HTMLAttributes, ReactNode, CSSProperties, ButtonHTMLAttributes, ForwardRefExoticComponent, RefAttributes } from 'react';
+import { HTMLAttributes, ReactNode, CSSProperties, ButtonHTMLAttributes, RefAttributes, ReactElement, ForwardRefExoticComponent } from 'react';
 
 interface BubbleActivityValue {
     isBusy: boolean;
@@ -59,8 +59,8 @@ interface BubbleToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'child
      */
     blurred?: boolean;
     /**
-     * Amount of backdrop blur in pixels or CSS string.
-     * @default 16
+     * Amount of backdrop blur in pixels or CSS string. Negative numbers are clamped to 0.
+     * When omitted, the `--bubble-blur` CSS token is used (16px by default).
      */
     blurAmount?: number | string;
     /**
@@ -96,6 +96,11 @@ interface BubbleToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'child
      * @default 'Toolbar'
      */
     ariaLabel?: string;
+    /**
+     * Controller from useBubbleLiveActivity. While an activity is shown, the groups collapse
+     * into a single pill (and then a card) and are restored afterwards, keeping their state.
+     */
+    liveActivity?: BubbleLiveActivityController;
 }
 interface BubbleGroupProps extends HTMLAttributes<HTMLDivElement>, BubbleActivityProps {
     /**
@@ -166,11 +171,226 @@ interface BubbleAreaProps extends HTMLAttributes<HTMLDivElement> {
      */
     maxWidth?: number | string;
 }
+/** A search result or suggestion. Its shape is fixed so the listbox layout stays intact. */
+interface BubbleSearchItem {
+    /** Stable identifier, used as React key. */
+    id: string;
+    /** Main line of the option. */
+    title: string;
+    /** Optional secondary line, e.g. a path. */
+    description?: string;
+}
+/** Visible and accessible texts of BubbleSearch. */
+interface BubbleSearchLabels {
+    /** Accessible name of the search group. @default 'Search' */
+    group: string;
+    /** Accessible name of the search button. @default 'Search' */
+    button: string;
+    /** Accessible name of the combobox input. @default 'Search' */
+    input: string;
+    /** Accessible name of the results listbox. @default 'Results' */
+    listbox: string;
+    /** @default 'Search…' */
+    placeholder: string;
+    /** @default 'Searching…' */
+    searching: string;
+    /** @default 'No results. Try another term or explore a suggestion.' */
+    noResults: string;
+    /** @default 'Suggestions' */
+    suggestions: string;
+    /** @default (count) => '1 result' | `${count} results` */
+    results: (count: number) => string;
+    /** @default '↑ ↓ to explore · Enter to select · Esc to close' */
+    hint: string;
+}
+/**
+ * Visual tokens of BubbleSearch, written as CSS custom properties `--bubble-search-*`.
+ * Numbers are px for lengths and ms for `duration`. Structure and layout are not customizable.
+ */
+interface BubbleSearchTokens {
+    /** Expanded width, capped to the viewport. @default 360px */
+    width?: number | string;
+    /** Corner radius of the expanded search. @default 24px */
+    radius?: number | string;
+    /** Divider between the header and the results. @default rgb(128 128 128 / 18%) */
+    divider?: string;
+    /** Focus ring of the header. @default #818cf8 */
+    focusRing?: string;
+    /** Background of the hovered / active option. @default rgb(129 140 248 / 18%) */
+    optionActiveBg?: string;
+    /** @default 12px */
+    optionRadius?: number | string;
+    /** Option title size, clamped to 10–20px. @default 13px */
+    titleSize?: number | string;
+    /** @default 600 */
+    titleWeight?: number | string;
+    /** Size of descriptions, status and hint, clamped to 9–16px. @default 11px */
+    metaSize?: number | string;
+    /** Opacity of secondary texts, clamped to 0.4–1. @default 0.7 */
+    mutedOpacity?: number | string;
+    /** Results max height, capped to the viewport. @default 220px */
+    resultsMaxHeight?: number | string;
+    /** Panel padding, clamped to 0–16px. @default 8px */
+    panelPadding?: number | string;
+    /** Expand / collapse duration, clamped to 0–600ms. @default 180ms */
+    duration?: number | string;
+    /** @default ease */
+    easing?: string;
+}
+interface BubbleSearchProps<T extends BubbleSearchItem = BubbleSearchItem> {
+    /**
+     * Async search. Receives the trimmed, lower-cased query and an AbortSignal that is
+     * aborted when the query changes, the search closes or the component unmounts.
+     */
+    onSearch: (query: string, signal: AbortSignal) => Promise<T[]>;
+    /** Called when an option is chosen. The search closes and focus returns to the button. */
+    onSelect: (item: T) => void;
+    /** Shown while the query is empty and when nothing matches. */
+    suggestions?: T[];
+    /** Receives errors from onSearch, except cancellations. The status then shows no results. */
+    onError?: (error: unknown) => void;
+    /** Controlled open state. */
+    open?: boolean;
+    /** @default false */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Wait before searching. 0 searches immediately. @default 0 */
+    debounceMs?: number;
+    labels?: Partial<BubbleSearchLabels>;
+    tokens?: BubbleSearchTokens;
+    /** Class for the search group, useful to scope tokens in CSS. */
+    className?: string;
+}
+/** A breadcrumb level. The last item is the current page. */
+interface BubbleBreadcrumbItem {
+    label: string;
+    href?: string;
+}
+interface BubbleBreadcrumbSearchLabels extends BubbleSearchLabels {
+    /** Accessible name of the breadcrumb navigation. @default 'Breadcrumb' */
+    location: string;
+}
+/** BubbleSearch tokens plus `--bubble-breadcrumb-*` tokens. */
+interface BubbleBreadcrumbSearchTokens extends BubbleSearchTokens {
+    /** Breadcrumb text size, clamped to 10–16px. @default 12px */
+    breadcrumbSize?: number | string;
+    /** @default currentColor */
+    breadcrumbSeparatorColor?: string;
+    /** Weight of the current page. @default 500 */
+    breadcrumbCurrentWeight?: number | string;
+    /** Opacity of parent levels, clamped to 0.4–1. @default 0.7 */
+    breadcrumbMutedOpacity?: number | string;
+}
+interface BubbleBreadcrumbSearchProps<T extends BubbleSearchItem = BubbleSearchItem> extends Omit<BubbleSearchProps<T>, 'labels' | 'tokens'> {
+    /** Current location, controlled by the app (usually its router). */
+    items: BubbleBreadcrumbItem[];
+    /** Text between levels. @default '/' */
+    separator?: string;
+    labels?: Partial<BubbleBreadcrumbSearchLabels>;
+    tokens?: BubbleBreadcrumbSearchTokens;
+}
+/** Content of a Live Activity. Its shape is fixed so the pill and the card keep their layout. */
+interface BubbleLiveContent {
+    title: string;
+    description?: string;
+    /** Replaces the default spinner / outcome icon. */
+    icon?: ReactNode;
+    /** @default 'success' after a resolved task, 'error' after a rejected one, otherwise 'neutral' */
+    tone?: 'neutral' | 'success' | 'error';
+}
+type BubbleLiveState = 'idle' | 'compact' | 'expanded';
+interface BubbleLiveRunOptions<T> {
+    /** Shown in the compact pill while the task runs. Defaults to `labels.pending`. */
+    pending?: BubbleLiveContent;
+    /** Card shown when the task resolves. Defaults to `labels.success`. */
+    success?: (value: T) => BubbleLiveContent;
+    /** Card shown when the task rejects. Defaults to `labels.error`. */
+    error?: (error: unknown) => BubbleLiveContent;
+    /** Milliseconds the card stays visible; 0 keeps it until dismissed. Defaults to the controller's. */
+    duration?: number;
+}
+/** Texts of the Live Activity. */
+interface BubbleLiveLabels {
+    /** @default 'Working…' */
+    pending: string;
+    /** @default 'Done' */
+    success: string;
+    /** @default 'Something went wrong' */
+    error: string;
+    /** Accessible name of the close button. @default 'Dismiss' */
+    close: string;
+    /** Accessible name of the live group. @default 'Live activity' */
+    group: string;
+}
+/**
+ * Visual tokens of the Live Activity, written as `--bubble-live-*` custom properties.
+ * Numbers are px for lengths and ms for `duration`.
+ */
+interface BubbleLiveTokens {
+    /** Width of the compact pill, capped to the viewport. @default 200px */
+    compactWidth?: number | string;
+    /** Width of the card, capped to the viewport. @default 360px */
+    width?: number | string;
+    /** Corner radius of the card. @default 24px */
+    radius?: number | string;
+    /** Remaining-time bar. @default currentColor at 40% */
+    progressColor?: string;
+    /** @default #22c55e */
+    successColor?: string;
+    /** @default #ef4444 */
+    errorColor?: string;
+    /** Title size, clamped to 11–18px. @default 13px */
+    titleSize?: number | string;
+    /** Description size, clamped to 9–14px. @default 11px */
+    metaSize?: number | string;
+    /** Morph duration, clamped to 0–600ms. @default 320ms */
+    duration?: number | string;
+}
+interface BubbleLiveActivityOptions {
+    /** Default card duration in ms; 0 keeps cards until dismissed. @default 4000 */
+    duration?: number;
+    /** Minimum time the compact pill stays, so fast tasks do not flicker. @default 600 */
+    minPendingMs?: number;
+    labels?: Partial<BubbleLiveLabels>;
+    tokens?: BubbleLiveTokens;
+}
+/** Controller returned by useBubbleLiveActivity. Stable across renders; usable from anywhere. */
+interface BubbleLiveActivityController {
+    /** Shows the task in the toolbar and returns its own promise (value or original error). */
+    run: <T>(task: () => Promise<T> | T, options?: BubbleLiveRunOptions<T>) => Promise<T>;
+    /** Queues a card without a task. */
+    show: (content: BubbleLiveContent, options?: {
+        duration?: number;
+    }) => void;
+    /** Closes the current activity and moves to the next queued one. */
+    dismiss: () => void;
+    /** Current state, for tests or custom UI. Not reactive; subscribe for updates. */
+    readonly state: BubbleLiveState;
+    subscribe: (listener: () => void) => () => void;
+}
 
 declare const BubbleGroup: react.ForwardRefExoticComponent<BubbleGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Shows the current location as a breadcrumb and turns into a search when its button is pressed.
+ * The last item is the current page; it stays visible while parents truncate first.
+ */
+declare const BubbleBreadcrumbSearch: (<T extends BubbleSearchItem>(props: BubbleBreadcrumbSearchProps<T> & RefAttributes<HTMLDivElement>) => ReactElement | null) & {
+    displayName?: string;
+};
+
+/**
+ * Search bubble: a button that expands into a combobox with async results.
+ * Use it inside BubbleToolbar. Customize it through `labels` and `tokens`.
+ */
+declare const BubbleSearch: (<T extends BubbleSearchItem>(props: BubbleSearchProps<T> & RefAttributes<HTMLDivElement>) => ReactElement | null) & {
+    displayName?: string;
+};
+
 interface BubbleToolbarComponent extends ForwardRefExoticComponent<BubbleToolbarProps & RefAttributes<HTMLDivElement>> {
     Group: typeof BubbleGroup;
+    Search: typeof BubbleSearch;
+    BreadcrumbSearch: typeof BubbleBreadcrumbSearch;
 }
 declare const BubbleToolbar: BubbleToolbarComponent;
 
@@ -182,14 +402,27 @@ interface BubbleToolbarContextValue extends BubbleActivityProps {
     size: BubbleToolbarSize;
     theme: BubbleToolbarTheme;
     blurred: boolean;
-    blurAmount: number | string;
+    /** Undefined falls back to the --bubble-blur token. */
+    blurAmount?: number | string;
     itemGap: number | string;
     bordered: boolean;
     shadow: boolean | string;
+    /** Toolbar placement; undefined outside a BubbleToolbar. */
+    position?: BubbleToolbarPosition;
+    /** Live Activity controller of the toolbar, if any. */
+    liveActivity?: BubbleLiveActivityController;
 }
 declare const BubbleToolbarContext: react.Context<BubbleToolbarContextValue>;
 declare const useBubbleToolbar: () => BubbleToolbarContextValue;
 
+/**
+ * Creates a stable Live Activity controller. Pass it to `<BubbleToolbar liveActivity>` and call
+ * `run`, `show` or `dismiss` from anywhere. Options are read on every render.
+ */
+declare const useBubbleLiveActivity: (options?: BubbleLiveActivityOptions) => BubbleLiveActivityController;
+/** Reads the controller of the surrounding BubbleToolbar. */
+declare const useBubbleToolbarLiveActivity: () => BubbleLiveActivityController;
+
 /**
  * Returns an array of non-null, non-undefined, non-boolean child elements.
  * Unpacks Fragment if encountered at the top level.
@@ -198,6 +431,6 @@ declare function getValidChildren(children: ReactNode): ReactNode[];
 
 declare function resolveSize(size: BubbleToolbarSize): number;
 declare function formatPx(val: number | string): string;
-declare function getGlassStyles(theme: BubbleToolbarTheme, blurred: boolean, blurAmount: number | string, bordered: boolean, shadow: boolean | string): CSSProperties;
+declare function getGlassStyles(theme: BubbleToolbarTheme, blurred: boolean, blurAmount: number | string | undefined, bordered: boolean, shadow: boolean | string): CSSProperties;
 
-export { type BubbleActivityProps, type BubbleActivityValue, BubbleArea, type BubbleAreaProps, BubbleGroup, type BubbleGroupProps, BubbleIconButton, type BubbleIconButtonProps, type BubbleShape, BubbleToolbar, type BubbleToolbarComponent, BubbleToolbarContext, type BubbleToolbarPosition, type BubbleToolbarProps, type BubbleToolbarSize, type BubbleToolbarTheme, formatPx, getGlassStyles, getValidChildren, resolveSize, useBubbleActivity, useBubbleToolbar };
+export { type BubbleActivityProps, type BubbleActivityValue, BubbleArea, type BubbleAreaProps, type BubbleBreadcrumbItem, BubbleBreadcrumbSearch, type BubbleBreadcrumbSearchLabels, type BubbleBreadcrumbSearchProps, type BubbleBreadcrumbSearchTokens, BubbleGroup, type BubbleGroupProps, BubbleIconButton, type BubbleIconButtonProps, type BubbleLiveActivityController, type BubbleLiveActivityOptions, type BubbleLiveContent, type BubbleLiveLabels, type BubbleLiveRunOptions, type BubbleLiveState, type BubbleLiveTokens, BubbleSearch, type BubbleSearchItem, type BubbleSearchLabels, type BubbleSearchProps, type BubbleSearchTokens, type BubbleShape, BubbleToolbar, type BubbleToolbarComponent, BubbleToolbarContext, type BubbleToolbarPosition, type BubbleToolbarProps, type BubbleToolbarSize, type BubbleToolbarTheme, formatPx, getGlassStyles, getValidChildren, resolveSize, useBubbleActivity, useBubbleLiveActivity, useBubbleToolbar, useBubbleToolbarLiveActivity };