@bmsuisse/ui 0.13.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> {
@@ -209,6 +209,41 @@ interface ConfirmDialogProps {
  */
 declare const ConfirmDialog: ({ open, onOpenChange, title, description, confirmLabel, cancelLabel, onConfirm, variant, confirmTestId, cancelTestId, }: ConfirmDialogProps) => ReactElement;
 
+interface DialogActionsProps {
+    /**
+     * The dialog's non-cancel actions, ordered from *nearest to Cancel* to
+     * *most primary* — e.g. `[secondaryAction, primaryAction]`. For a plain
+     * two-button confirm dialog, pass a single primary action here.
+     */
+    actions: ReactNode[];
+    /** The dismissive/cancel action. */
+    cancel: ReactNode;
+}
+/**
+ * Renders `actions` and `cancel` in the order the current platform's own
+ * dialogs use — Windows puts Cancel on the right (trailing), every other
+ * platform we target (iOS/iPadOS, macOS, Android, Linux) puts it on the
+ * left (leading) — instead of a fixed order every caller has to get right
+ * itself. `ConfirmDialog` and `QuestionDialog` use this internally; use it
+ * directly for any other dialog/panel footer with the same
+ * actions-plus-cancel shape.
+ *
+ * Matches native multi-button "Save changes?"-style dialogs: the most
+ * primary action sits at the edge *opposite* Cancel (Windows:
+ * `Save · Don't Save · Cancel`; iOS/macOS: `Cancel · Don't Save · Save`),
+ * not next to it. `actions` is reversed when Cancel sits on the right
+ * (Windows), so the last element of `actions` — the primary action — is
+ * always the one furthest from Cancel, and the first element is always the
+ * one nearest Cancel, regardless of platform — a caller picks the order
+ * once, by meaning, and doesn't have to reason about which edge Cancel
+ * lands on.
+ *
+ * Renders no wrapping element of its own — nest it inside the caller's own
+ * footer container (e.g. `DialogFooter`, or `Modal`'s `footer` prop) for
+ * layout/spacing.
+ */
+declare function DialogActions({ actions, cancel }: DialogActionsProps): ReactElement;
+
 interface FormModalProps {
     /** Whether the modal is open. Fully controlled — no internal open state. */
     open: boolean;
@@ -313,6 +348,53 @@ interface ResponsivePanelProps {
  */
 declare const ResponsivePanel: ({ open, onOpenChange, title, description, children, footer, className, breakpoint, size, resizable, draggable, closeOnOutsideClick, }: ResponsivePanelProps) => ReactElement;
 
+interface QuestionDialogAction {
+    /** Button label. */
+    label: string;
+    /** Called when this action is clicked. May return a promise; the dialog waits for it before closing. */
+    onClick: () => void | Promise<void>;
+    /** Visual style of this action's button. Defaults to `"default"`. */
+    variant?: ButtonProps["variant"];
+    /** Forwarded to this action's `Button`, for test targeting. */
+    testId?: string;
+}
+interface QuestionDialogProps {
+    /** Whether the dialog is open. Fully controlled — no internal open state. */
+    open: boolean;
+    /** Called when Radix wants to change the open state (backdrop click, Esc, close button, Cancel). */
+    onOpenChange: (open: boolean) => void;
+    /** Dialog title. */
+    title: string;
+    /** Optional supporting copy shown under the title. */
+    description?: string;
+    /**
+     * The dialog's non-cancel actions, ordered from *nearest Cancel* to *most
+     * primary* (see `DialogActions`) — e.g.
+     * `[{ label: "Don't Save", ... }, { label: "Save", ... }]` puts "Save",
+     * the primary action, at the edge opposite Cancel on every platform,
+     * matching native "Save changes?"-style dialogs.
+     */
+    actions: QuestionDialogAction[];
+    /** Label for the cancel button. Defaults to `"Cancel"`. */
+    cancelLabel?: string;
+    /** Forwarded to the cancel button, for test targeting. */
+    cancelTestId?: string;
+}
+/**
+ * A dialog asking a question with any number of actions plus a Cancel —
+ * `ConfirmDialog` generalized past the fixed confirm/cancel pair, for
+ * prompts like "Save changes before closing?" (Don't Save / Cancel / Save).
+ * Like `ConfirmDialog`, it closes itself automatically after a successful
+ * action click — if the clicked action's `onClick` throws/rejects, the
+ * dialog stays open (and the error isn't swallowed) so a caller can surface
+ * its own error UI. Cancel always closes immediately.
+ *
+ * Button order follows the current platform's own convention via
+ * `DialogActions` — pick `actions`' order by *meaning* (least to most
+ * primary), not by which edge Cancel happens to land on.
+ */
+declare const QuestionDialog: ({ open, onOpenChange, title, description, actions, cancelLabel, cancelTestId, }: QuestionDialogProps) => ReactElement;
+
 interface FormFieldProps {
     /** Visible label text for the field. */
     label: string;
@@ -659,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;
 }
@@ -836,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. */
@@ -891,4 +1176,22 @@ declare function cn(...inputs: ClassValue[]): string;
  */
 declare function useMediaQuery(query: string): boolean;
 
-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, ConfirmDialog, type ConfirmDialogProps, Dialog, 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, 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, loadingSpinnerIconVariants, sheetVariants, useMediaQuery, useSidebarCollapsed };
+/**
+ * Whether the current runtime is Windows, based on the UA string. Returns
+ * `false` outside a browser (SSR, tests) so platform-dependent UI falls back
+ * to the non-Windows default rather than guessing.
+ */
+declare function isWindowsPlatform(): boolean;
+type ConfirmButtonPlacement = "leading" | "trailing";
+/**
+ * Where a dialog's affirmative/confirm button should sit, matching each
+ * platform's own system convention: Windows dialogs place OK/Save on the
+ * left (Cancel on the right); every other platform we target — iOS/iPadOS,
+ * macOS, Android, Linux — places the affirmative action on the right (the
+ * iOS/macOS Human Interface Guidelines require this, and it's the de facto
+ * default everywhere else too). Windows is the one exception, so this is
+ * driven entirely by `isWindowsPlatform`.
+ */
+declare function getConfirmButtonPlacement(): ConfirmButtonPlacement;
+
+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 };