bubble-toolbar 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -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 };