@bmsuisse/ui 0.16.2 → 0.17.0

package/dist/index.d.ts

@@ -434,6 +434,20 @@ interface GridColumn {
     className?: string;
 }
 
+/** Structured error shown by `ErrorState`/`InlineError`. */
+interface ErrorInfo {
+    /** Short headline, e.g. "Couldn't load data". */
+    title?: string;
+    /** Human-readable explanation. */
+    message?: string;
+    /** Technical details (stack, response body) — shown behind a "Show details" toggle. */
+    details?: string;
+}
+/** What components accept for their `error` prop — pass a TanStack Query / SWR / `catch` error straight through. */
+type ErrorInput = ErrorInfo | Error | string | null | undefined | false;
+/** Normalizes any `ErrorInput` (or a raw thrown value) to an `ErrorInfo`; `undefined` when there is no error. */
+declare function toErrorInfo(error: unknown): ErrorInfo | undefined;
+
 interface ComboboxOption {
     value: string;
     label: string;
@@ -467,6 +481,10 @@ interface ComboboxBaseProps {
     loading?: boolean;
     /** Trigger text shown while `loading` is true. Defaults to `"Loading…"`. */
     loadingMessage?: string;
+    /** The options fetch failed. The trigger stays openable and the list shows an `InlineError` (with Retry when `onRetry` is set) instead of the options. */
+    error?: ErrorInput;
+    /** Re-runs the failed options fetch. */
+    onRetry?: () => void;
     /** Shows a clear ("x") affordance on the trigger when a value is selected. Defaults to `true`. */
     clearable?: boolean;
     className?: string;
@@ -570,6 +588,10 @@ interface TagComboboxProps {
     loading?: boolean;
     /** Message shown in the option list while `loading` is true. Defaults to `"Loading…"`. */
     loadingMessage?: string;
+    /** The options fetch failed. The list shows an `InlineError` (with Retry when `onRetry` is set) instead of the options. */
+    error?: ErrorInput;
+    /** Re-runs the failed options fetch. */
+    onRetry?: () => void;
     className?: string;
     id?: string;
     /** Forwarded to the field, for test targeting (e.g. Playwright/Testing Library). */
@@ -603,7 +625,7 @@ interface TagComboboxProps {
  * built on the same `Popover`/keyboard-nav shape rather than forking it,
  * so both patterns share one mental model.
  */
-declare function TagCombobox({ options, value, onChange, placeholder, emptyMessage, disabled, loading, loadingMessage, className, id, onSearchChange, container, groupLabels, columns, ...rest }: TagComboboxProps): ReactElement;
+declare function TagCombobox({ options, value, onChange, placeholder, emptyMessage, disabled, loading, loadingMessage, error, onRetry, className, id, onSearchChange, container, groupLabels, columns, ...rest }: TagComboboxProps): ReactElement;
 
 type AlertBoxVariant = "error" | "warning" | "info" | "success";
 interface AlertBoxProps {
@@ -616,7 +638,7 @@ interface AlertBoxProps {
     className?: string;
     /**
      * Overrides the default variant icon entirely. Pass `null` to hide the
-     * icon. Defaults to a variant-specific lucide-react icon.
+     * icon. Defaults to a variant-specific heroicons icon.
      */
     icon?: ReactNode;
 }
@@ -692,11 +714,86 @@ interface LoadingOverlayProps extends HTMLAttributes<HTMLDivElement>, Pick<Loadi
 /** Centers a larger `LoadingSpinner` inside a full container/page — use as a route or panel loading state. */
 declare const LoadingOverlay: ({ size, label, className, ...props }: LoadingOverlayProps) => ReactElement;
 
+/** Returns `true` only once `active` has been true for `delayMs` — avoids a spinner flash on fast responses. */
+declare function useDelayedFlag(active: boolean, delayMs?: number): boolean;
+interface LoadingStateProps extends HTMLAttributes<HTMLDivElement> {
+    /** `skeleton` (default) shows placeholder lines; `spinner` shows a centered spinner. */
+    variant?: "skeleton" | "spinner";
+    /** Skeleton line count. Defaults to 3. */
+    lines?: number;
+    label?: string;
+    /** Wait this long before showing anything. Defaults to 150ms; pass 0 to show immediately. */
+    delayMs?: number;
+}
+/** Initial-load placeholder for a content area. Announces itself as `role="status"`. */
+declare const LoadingState: ({ variant, lines, label, delayMs, className, ...props }: LoadingStateProps) => ReactElement;
+/** Thin indeterminate bar for a refetch over already-visible data. Place inside a `relative` container. */
+declare const RefreshBar: ({ active, className }: {
+    active: boolean;
+    className?: string;
+}) => ReactElement | null;
+
+interface ErrorStateLabels {
+    title: string;
+    retry: string;
+    showDetails: string;
+}
+declare const defaultErrorStateLabels: ErrorStateLabels;
+interface ErrorStateProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    error: ErrorInput;
+    /** Shows a Retry button when set. */
+    onRetry?: () => void;
+    /** `block` (default) is a centered panel for a whole content area; `compact` is a left-aligned tinted box for cards/popovers. */
+    variant?: "block" | "compact";
+    labels?: Partial<ErrorStateLabels>;
+}
+/** Content-area error: icon, title, message, optional collapsible details and a Retry button. Renders nothing when `error` is empty. */
+declare const ErrorState: ({ error, onRetry, variant, labels, className, ...props }: ErrorStateProps) => ReactElement | null;
+interface InlineErrorProps extends Omit<HTMLAttributes<HTMLSpanElement>, "title"> {
+    error: ErrorInput;
+    onRetry?: () => void;
+    labels?: Partial<Pick<ErrorStateLabels, "title" | "retry">>;
+}
+/** One-line error for tight spaces (dropdowns, filters, tree nodes, stale-data banners): "⚠ message · Retry". */
+declare const InlineError: ({ error, onRetry, labels, className, ...props }: InlineErrorProps) => ReactElement | null;
+
+interface AsyncBoundaryProps {
+    /** A request is in flight. */
+    loading?: boolean;
+    error?: ErrorInput;
+    onRetry?: () => void;
+    /** The request finished with no data. Renders `emptyContent`. */
+    empty?: boolean;
+    emptyContent?: ReactNode;
+    /** Placeholder for the first load. Defaults to `<LoadingState />`. */
+    loadingContent?: ReactNode;
+    /**
+     * Whether `children` already has data to show (stale or previous), e.g. `hasData={query.data !== undefined}`.
+     * When true, a refetch keeps the content with a refresh bar and an error becomes a slim banner above it.
+     * Defaults to `false`: `loading` shows the skeleton and `error` the ErrorState, so children never
+     * render without data.
+     */
+    hasData?: boolean;
+    children: ReactNode;
+}
+/**
+ * Standard loading → error → empty → content switch for server-fetched data.
+ * First load: skeleton. Refetch: content + thin bar. Error without data: `ErrorState`.
+ * Error with stale data: content under an `InlineError` banner.
+ */
+declare const AsyncBoundary: ({ loading, error, onRetry, empty, emptyContent, loadingContent, hasData, children, }: AsyncBoundaryProps) => ReactElement;
+
 interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "onChange" | "size"> {
     value: string;
     onChange: (value: string) => void;
     /** Swaps the leading search icon for a spinner while a search request is in flight. */
+    loading?: boolean;
+    /** @deprecated Use `loading`. */
     isLoading?: boolean;
+    /** A failed search request. Marks the input invalid and shows an `InlineError` below it. */
+    error?: ErrorInput;
+    /** Shows a Retry action in the error line. */
+    onRetry?: () => void;
     /** Called when the clear (×) button is pressed. Defaults to `onChange("")`. Pass `false` to hide the button entirely, even with a non-empty value. */
     onClear?: (() => void) | false;
     /** Accessible label for the clear button. @default "Clear search" */
@@ -712,7 +809,7 @@ interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "ty
  * unlike `Combobox`, this has no dropdown/result list of its own, just the
  * input chrome; the caller owns whatever renders the results.
  */
-declare function SearchBar({ value, onChange, isLoading, onClear, clearLabel, inputRef, className, ...props }: SearchBarProps): ReactElement;
+declare function SearchBar({ value, onChange, loading, isLoading, error, onRetry, onClear, clearLabel, inputRef, className, ...props }: SearchBarProps): ReactElement;
 
 interface KpiCardProps {
     label: string;
@@ -728,6 +825,10 @@ interface KpiCardProps {
     /** @default "default" */
     variant?: "hero" | "mini" | "default" | "donut";
     loading?: boolean;
+    /** The metric failed to load: replaces the value with "—" and a warning marker (message in its tooltip) in every variant. */
+    error?: ErrorInput;
+    /** Shows a Retry link under the error marker. */
+    onRetry?: () => void;
     sub?: string;
     /** Colors `sub` on the mini variant — "warn"/"danger" flag something worth acting on (overdue, at-risk), "default" stays muted. */
     subTone?: "default" | "warn" | "danger";
@@ -785,7 +886,13 @@ interface SearchPanelProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "
     value: string;
     onChange: (value: string) => void;
     /** Swaps the leading search icon for a spinner while a search request is in flight. */
+    loading?: boolean;
+    /** @deprecated Use `loading`. */
     isLoading?: boolean;
+    /** A failed search request. Shows an `InlineError` row below the input. */
+    error?: ErrorInput;
+    /** Shows a Retry action in the error row. */
+    onRetry?: () => void;
     /** Extra content after the input, e.g. a mic button. */
     trailingSlot?: ReactNode;
     /** Keyboard-shortcut hint rendered after `trailingSlot`, e.g. `"⌘K"`. Omit to hide it. */
@@ -805,7 +912,7 @@ interface SearchPanelProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "
  * mode-switcher pills below it. Headless on results — the caller renders
  * whatever dropdown or inline results belong under it.
  */
-declare function SearchPanel({ value, onChange, isLoading, trailingSlot, shortcutHint, modes, activeMode, onModeChange, expanded, inputRef, className, ...props }: SearchPanelProps): ReactElement;
+declare function SearchPanel({ value, onChange, loading, isLoading, error, onRetry, trailingSlot, shortcutHint, modes, activeMode, onModeChange, expanded, inputRef, className, ...props }: SearchPanelProps): ReactElement;
 
 interface SearchTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
     /** Accessible label, also used as the tooltip text by callers that wrap this in one. @default "Search" */
@@ -818,7 +925,7 @@ interface SearchTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement
  */
 declare function SearchTrigger({ label, ...props }: SearchTriggerProps): ReactElement;
 
-/** Shape a `lucide-react` icon component satisfies — `NavItem` sizes and colors it itself. */
+/** Shape a `@heroicons/react` icon component satisfies — `NavItem` sizes and colors it itself. */
 interface NavIconProps {
     className?: string;
     strokeWidth?: string | number;
@@ -929,7 +1036,7 @@ interface AiButtonProps extends Omit<ButtonProps, "variant"> {
     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 */
+    /** Leading icon. @default SparklesIcon */
     icon?: ElementType<NavIconProps>;
 }
 /**
@@ -1196,4 +1303,4 @@ type ConfirmButtonPlacement = "leading" | "trailing";
  */
 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, DialogBody, 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, SheetBody, 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 };
+export { AiButton, type AiButtonProps, type AiButtonVariant, AiExplainButton, type AiExplainButtonProps, AlertBox, type AlertBoxProps, type AlertBoxVariant, AsyncBoundary, type AsyncBoundaryProps, 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, DialogBody, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DonutChart, type DonutSegment, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type ErrorInfo, type ErrorInput, ErrorState, type ErrorStateLabels, type ErrorStateProps, FormField, type FormFieldProps, FormModal, type FormModalProps, InlineError, type InlineErrorProps, Input, type InputProps, KpiCard, type KpiCardProps, Label, LoadingOverlay, type LoadingOverlayProps, LoadingSpinner, type LoadingSpinnerProps, LoadingState, type LoadingStateProps, Modal, type ModalProps, NavGroup, type NavGroupProps, type NavIconProps, NavItem, type NavItemProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, QuestionDialog, type QuestionDialogAction, type QuestionDialogProps, RefreshBar, 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, SheetBody, 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, defaultErrorStateLabels, describeSpeechError, getConfirmButtonPlacement, isWindowsPlatform, loadingSpinnerIconVariants, sheetVariants, toErrorInfo, useDelayedFlag, useMediaQuery, useSidebarCollapsed, useSpeechRecognition };