@bmsuisse/ui 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -15,7 +15,7 @@ import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { ClassValue } from 'clsx';
 
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "outline" | "ghost" | "destructive" | "secondary" | "link" | "swiss-primary" | "swiss-secondary" | null | undefined;
+    variant?: "default" | "outline" | "ghost" | "destructive" | "secondary" | "link" | "swiss-primary" | "swiss-secondary" | "ai" | "ai-subtle" | "ai-ghost" | null | undefined;
     size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -741,6 +741,8 @@ interface KpiCardProps {
     segments?: DonutSegment[];
     /** Donut variant only: big label centered in the ring. Defaults to the sum of `segments`' values. */
     centerValue?: string;
+    /** Any CSS color/gradient, overriding the variant's default surface (`--color-primary` for `hero`, `bg-card` for the rest). */
+    background?: string;
     /** For E2E tests to target a specific tile unambiguously when `label` also appears elsewhere on the page (e.g. a chart legend). */
     testId?: string;
 }
@@ -918,6 +920,207 @@ declare function SidebarNav({ children, className, ...rest }: SidebarNavProps):
  */
 declare function useSidebarCollapsed(): boolean;
 
+/** The three `buttonVariants` entries that carry the violet AI accent. */
+type AiButtonVariant = "ai" | "ai-subtle" | "ai-ghost";
+interface AiButtonProps extends Omit<ButtonProps, "variant"> {
+    /** `ai` = solid CTA, `ai-subtle` = tinted chip, `ai-ghost` = inline text action. @default "ai-subtle" */
+    variant?: AiButtonVariant;
+    /** Swaps the leading icon for a spinner and disables the button while an AI call is in flight. */
+    loading?: boolean;
+    /** Leading icon. @default Sparkles */
+    icon?: ElementType<NavIconProps>;
+}
+/**
+ * The "do something with AI" button: sparkle icon plus a built-in in-flight
+ * state on top of `Button`'s `ai*` variants. Forwards its ref like `Button`
+ * so it works as a Radix `asChild` trigger — `AiExplainButton` mounts one
+ * inside `PopoverTrigger`, which needs the DOM node to anchor the popover.
+ */
+declare const AiButton: react.ForwardRefExoticComponent<AiButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface AiExplainButtonProps extends Omit<AiButtonProps, "children" | "onClick" | "loading" | "title" | "aria-busy"> {
+    /**
+     * Produces the explanation, called the first time the popover opens (and on
+     * "Try again" after a failure) — not on mount, so nothing is spent on a
+     * button nobody clicks.
+     */
+    onExplain: () => Promise<ReactNode> | ReactNode;
+    /** Button text. @default "Explain" */
+    label?: string;
+    /** Heading inside the popover. @default the label */
+    title?: string;
+    /** Popover alignment relative to the button. @default "start" */
+    align?: "start" | "center" | "end";
+    /** Class names for the popover panel, e.g. to widen it. @default "w-80" */
+    contentClassName?: string;
+}
+/**
+ * "What am I looking at?" button: a sparkle affordance next to a chart, a KPI
+ * or a form field that opens a popover and lazily asks the caller's model to
+ * explain it. The caller returns any node, so an explanation can be prose,
+ * a list, or a small rendered breakdown. Every other prop (`variant`, `size`,
+ * `icon`, `data-testid`, ...) goes to the underlying `AiButton`.
+ */
+declare function AiExplainButton({ onExplain, label, title, align, contentClassName, size, ...props }: AiExplainButtonProps): ReactElement;
+
+interface SpeechRecognitionAlternative {
+    transcript: string;
+}
+interface SpeechRecognitionResult {
+    isFinal: boolean;
+    0: SpeechRecognitionAlternative;
+}
+interface SpeechRecognitionEventLike {
+    resultIndex: number;
+    results: {
+        length: number;
+        [index: number]: SpeechRecognitionResult;
+    };
+}
+/**
+ * The recognizer contract `useSpeechRecognition` drives — matches the shape
+ * of the browser's built-in `SpeechRecognition`/`webkitSpeechRecognition`,
+ * which is also what the default engine (below) wraps. Implement this to
+ * swap in something other than the browser's on-device recognizer — for
+ * example a server-side transcription API — via the `engine` option.
+ * Whatever backs it, finalized chunks and interim words must arrive through
+ * `onresult` the same way the Web Speech API delivers them.
+ */
+interface SpeechRecognitionEngine {
+    lang: string;
+    continuous: boolean;
+    interimResults: boolean;
+    start(): void;
+    stop(): void;
+    abort(): void;
+    onresult: ((event: SpeechRecognitionEventLike) => void) | null;
+    onerror: ((event: {
+        error: string;
+    }) => void) | null;
+    onend: (() => void) | null;
+}
+/** Builds one `SpeechRecognitionEngine` per dictation session (`start()` calls it fresh each time). */
+type SpeechRecognitionEngineFactory = () => SpeechRecognitionEngine;
+/**
+ * Turns a recognizer error code into a sentence a user can act on, or `null`
+ * for codes that aren't the user's problem (`aborted` fires on every
+ * programmatic stop/unmount and would otherwise flash an alert on each one).
+ * `onError` still receives the raw code, for callers who want to branch.
+ */
+declare function describeSpeechError(code: string): string | null;
+interface UseSpeechRecognitionOptions {
+    /** BCP-47 tag passed to the recognizer, e.g. `"de-CH"`. @default the document language, else "en-US" */
+    lang?: string;
+    /** Called with each finalized chunk of speech. */
+    onResult?: (text: string) => void;
+    /** Called when the recognizer reports an error (`"not-allowed"`, `"no-speech"`, ...). */
+    onError?: (error: string) => void;
+    /**
+     * Overrides what backs dictation — e.g. to stream audio to a server-side
+     * transcription API instead of the browser's on-device `SpeechRecognition`.
+     * Called once per `start()` to build that session's engine; must satisfy
+     * `SpeechRecognitionEngine`. Omit to use the browser's Web Speech API
+     * (`supported` then reflects whether that API exists); passing `engine`
+     * makes `supported` unconditionally `true`, since the caller's factory is
+     * assumed to work wherever the app decides to render the button.
+     */
+    engine?: SpeechRecognitionEngineFactory;
+}
+interface SpeechRecognitionState {
+    /** False when neither a custom `engine` nor the browser's Web Speech API is available (Firefox, most of mobile, SSR). */
+    supported: boolean;
+    listening: boolean;
+    /** The not-yet-finalized words the recognizer is still revising. */
+    interim: string;
+    error: string | null;
+    start: () => void;
+    stop: () => void;
+    toggle: () => void;
+}
+/**
+ * Thin hook over a `SpeechRecognitionEngine` — by default the browser's
+ * built-in `SpeechRecognition`, so no dependency and no server round-trip;
+ * pass `engine` to back it with something else (e.g. a server-side
+ * transcription API) instead. Finalized chunks are pushed to `onResult`;
+ * the caller owns the accumulated transcript (so it stays editable), this
+ * only reports what's currently being heard.
+ */
+declare function useSpeechRecognition({ lang, onResult, onError, engine, }?: UseSpeechRecognitionOptions): SpeechRecognitionState;
+
+interface VoiceInputButtonProps extends Omit<ButtonProps, "onError" | "variant" | "children"> {
+    /** Called with each finalized chunk of speech, ready to append to whatever the caller is filling in. */
+    onTranscript: (text: string) => void;
+    /** Called with the recognizer's raw error code (`"not-allowed"`, `"no-speech"`, ...) — see `describeSpeechError` for user-facing text. */
+    onError?: (error: string) => void;
+    /** BCP-47 tag, e.g. `"de-CH"`. Defaults to the document language. */
+    lang?: string;
+    /**
+     * Overrides what backs dictation — e.g. to stream audio to a server-side
+     * transcription API instead of the browser's on-device `SpeechRecognition`.
+     * See `useSpeechRecognition`'s `engine` option. Passing this makes the
+     * button render enabled unconditionally, since browser support no longer
+     * applies.
+     */
+    engine?: SpeechRecognitionEngineFactory;
+    /** Rendered next to the icon. Icon-only (the default) when omitted. */
+    label?: string;
+    /** Accessible name while idle (icon-only buttons only). @default "Start dictation" */
+    startLabel?: string;
+    /** Accessible name while listening (icon-only buttons only). @default "Stop dictation" */
+    stopLabel?: string;
+    /** Renders the interim (not yet finalized) words next to the button. @default false */
+    showInterim?: boolean;
+}
+/**
+ * Push-to-dictate microphone button, backed by the browser's built-in
+ * `SpeechRecognition` by default — no API key, no upload, no extra
+ * dependency. Pass `engine` to back it with something else instead, such as
+ * a server-side transcription API (see `useSpeechRecognition`'s `engine`
+ * option). While listening it takes the `destructive` tint (the same one
+ * AlertBox's `error` uses) and only the mic icon pulses, so the "recording"
+ * signal reads at a glance without the whole control throbbing. Where
+ * neither `engine` nor the browser API is available (Firefox, most mobile)
+ * the button renders disabled with a crossed-out mic rather than vanishing,
+ * so the layout doesn't shift between browsers.
+ */
+declare const VoiceInputButton: react.ForwardRefExoticComponent<VoiceInputButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface VoiceTranscriptProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** The transcript. Controlled, like `SearchBar` — the caller owns the text. */
+    value: string;
+    onChange: (value: string) => void;
+    /**
+     * Rewrites the transcript with AI (clean up, translate, summarize —
+     * whatever the caller's model does) and resolves with the new text.
+     * Omitted hides the transform button, leaving plain dictation.
+     */
+    onTransform?: (text: string) => Promise<string> | string;
+    /** @default "Transform with AI" */
+    transformLabel?: string;
+    /** @default "Speak or type…" */
+    placeholder?: string;
+    /** BCP-47 tag for dictation, e.g. `"de-CH"`. Defaults to the document language. */
+    lang?: string;
+    /**
+     * Overrides what backs dictation — e.g. to stream audio to a server-side
+     * transcription API instead of the browser's on-device `SpeechRecognition`.
+     * Forwarded to `VoiceInputButton`; see `useSpeechRecognition`'s `engine`
+     * option.
+     */
+    engine?: SpeechRecognitionEngineFactory;
+    /** @default 4 */
+    rows?: number;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * Dictate → edit → rewrite-with-AI, in one box: a mic button feeding an
+ * editable transcript, plus a "Transform with AI" action that hands the text
+ * to the caller's model and swaps in the result (with one-click undo, since
+ * a model rewriting your own words is exactly where you want an escape hatch).
+ */
+declare function VoiceTranscript({ value, onChange, onTransform, transformLabel, placeholder, lang, engine, rows, disabled, className, ...props }: VoiceTranscriptProps): ReactElement;
+
 /** The minimal shape this component needs to render one chip in the stepper. */
 interface StepperStep {
     /** 1-based step number, also used as the React key and navigation target. */
@@ -991,4 +1194,4 @@ type ConfirmButtonPlacement = "leading" | "trailing";
  */
 declare function getConfirmButtonPlacement(): ConfirmButtonPlacement;
 
-export { AlertBox, type AlertBoxProps, type AlertBoxVariant, Badge, type BadgeProps, Button, ButtonGroup, type ButtonGroupOption, type ButtonGroupProps, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Combobox, type GridColumn as ComboboxColumn, type ComboboxMultiProps, type ComboboxOption, type ComboboxProps, type ComboboxSingleProps, type ConfirmButtonPlacement, ConfirmDialog, type ConfirmDialogProps, Dialog, DialogActions, type DialogActionsProps, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DonutChart, type DonutSegment, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FormField, type FormFieldProps, FormModal, type FormModalProps, Input, type InputProps, KpiCard, type KpiCardProps, Label, LoadingOverlay, type LoadingOverlayProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, NavGroup, type NavGroupProps, type NavIconProps, NavItem, type NavItemProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, QuestionDialog, type QuestionDialogAction, type QuestionDialogProps, ResponsivePanel, type ResponsivePanelProps, type ResponsivePanelSize, ScrollArea, ScrollBar, SearchBar, type SearchBarProps, SearchPanel, type SearchPanelMode, type SearchPanelProps, SearchTrigger, type SearchTriggerProps, Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarNav, type SidebarNavProps, type SidebarProps, Skeleton, Sparkline, StatusBadge, type StatusBadgeProps, type StatusTone, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TagCombobox, type TagComboboxOption, type TagComboboxProps, Textarea, type TextareaProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, cn, getConfirmButtonPlacement, isWindowsPlatform, loadingSpinnerIconVariants, sheetVariants, useMediaQuery, useSidebarCollapsed };
+export { AiButton, type AiButtonProps, type AiButtonVariant, AiExplainButton, type AiExplainButtonProps, AlertBox, type AlertBoxProps, type AlertBoxVariant, Badge, type BadgeProps, Button, ButtonGroup, type ButtonGroupOption, type ButtonGroupProps, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Combobox, type GridColumn as ComboboxColumn, type ComboboxMultiProps, type ComboboxOption, type ComboboxProps, type ComboboxSingleProps, type ConfirmButtonPlacement, ConfirmDialog, type ConfirmDialogProps, Dialog, DialogActions, type DialogActionsProps, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DonutChart, type DonutSegment, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FormField, type FormFieldProps, FormModal, type FormModalProps, Input, type InputProps, KpiCard, type KpiCardProps, Label, LoadingOverlay, type LoadingOverlayProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, NavGroup, type NavGroupProps, type NavIconProps, NavItem, type NavItemProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, QuestionDialog, type QuestionDialogAction, type QuestionDialogProps, ResponsivePanel, type ResponsivePanelProps, type ResponsivePanelSize, ScrollArea, ScrollBar, SearchBar, type SearchBarProps, SearchPanel, type SearchPanelMode, type SearchPanelProps, SearchTrigger, type SearchTriggerProps, Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetPortal, SheetTitle, SheetTrigger, Sidebar, SidebarNav, type SidebarNavProps, type SidebarProps, Skeleton, Sparkline, type SpeechRecognitionEngine, type SpeechRecognitionEngineFactory, type SpeechRecognitionState, StatusBadge, type StatusBadgeProps, type StatusTone, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TagCombobox, type TagComboboxOption, type TagComboboxProps, Textarea, type TextareaProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseSpeechRecognitionOptions, VoiceInputButton, type VoiceInputButtonProps, VoiceTranscript, type VoiceTranscriptProps, badgeVariants, buttonVariants, cn, describeSpeechError, getConfirmButtonPlacement, isWindowsPlatform, loadingSpinnerIconVariants, sheetVariants, useMediaQuery, useSidebarCollapsed, useSpeechRecognition };