@bmsuisse/ui 0.4.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BMS Suisse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @bmsuisse/ui
+
+Shared shadcn/ui-based React primitives and composed UI patterns: `Modal`,
+`ConfirmDialog`, `FormModal`, `FormField`, `AlertBox`, `StatusBadge`,
+`LoadingSpinner`/`LoadingOverlay`, `Combobox`, plus base primitives
+(`Button`, `Input`, `Dialog`, `Popover`, `Select`, `Sheet`, `Tooltip`, …).
+
+## Install
+
+```
+npm install @bmsuisse/ui
+```
+
+Peer dependencies: `react` and `react-dom` (`^18` or `^19`).
+
+## Usage
+
+```tsx
+import { Button, FormField, AlertBox } from "@bmsuisse/ui";
+
+function Example() {
+  return (
+    <FormField label="Name">
+      <input />
+    </FormField>
+  );
+}
+```
+
+See [AGENTS.md](../../AGENTS.md) for the full design rationale, and
+`packages/ui/demo` for a runnable example of every component.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import * as react from 'react';
+import { ButtonHTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, HTMLAttributes, ReactElement, ComponentPropsWithoutRef, TdHTMLAttributes, ThHTMLAttributes, ReactNode, ComponentProps } from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import * as SelectPrimitive from '@radix-ui/react-select';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import * as SwitchPrimitive from '@radix-ui/react-switch';
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+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;
+    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> {
+    asChild?: boolean;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+type InputProps = InputHTMLAttributes<HTMLInputElement>;
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+declare const Label: react.ForwardRefExoticComponent<LabelHTMLAttributes<HTMLLabelElement> & react.RefAttributes<HTMLLabelElement>>;
+
+type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
+
+declare const Card: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const CardHeader: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const CardTitle: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const CardDescription: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const CardContent: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const CardFooter: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "outline" | "destructive" | "secondary" | "warning" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface BadgeProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+}
+declare const Badge: ({ className, variant, ...props }: BadgeProps) => ReactElement;
+
+declare const Dialog: react.FC<DialogPrimitive.DialogProps>;
+declare const DialogTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const DialogContent: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & {
+    showCloseButton?: boolean;
+    /** data-testid for the built-in header close button, since it renders no DOM a caller controls directly. */
+    closeButtonTestId?: string;
+} & react.RefAttributes<HTMLDivElement>>;
+declare const DialogHeader: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const DialogTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
+declare const DialogDescription: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
+declare const DialogFooter: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+
+declare const Popover: react.FC<PopoverPrimitive.PopoverProps>;
+declare const PopoverTrigger: react.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const PopoverAnchor: react.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & react.RefAttributes<HTMLDivElement>>;
+declare const PopoverContent: react.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & {
+    /** Portal target for the popover content. Defaults to `document.body` (Radix's
+     * own default) when omitted. Needed when the popover is opened from inside a
+     * modal Dialog/Sheet: Radix's Dialog `FocusScope` traps focus within its own
+     * content subtree, and a popover portaled to `document.body` sits outside that
+     * subtree — so pass the Dialog/Sheet content element here to portal into it
+     * instead. */
+    container?: ComponentPropsWithoutRef<typeof PopoverPrimitive.Portal>["container"];
+} & react.RefAttributes<HTMLDivElement>>;
+
+declare const Select: react.FC<SelectPrimitive.SelectProps>;
+declare const SelectGroup: react.ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & react.RefAttributes<HTMLDivElement>>;
+declare const SelectValue: react.ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & react.RefAttributes<HTMLSpanElement>>;
+interface SelectTriggerProps extends ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> {
+    size?: "sm" | "default";
+}
+declare const SelectTrigger: react.ForwardRefExoticComponent<SelectTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const SelectContent: react.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const SelectItem: react.ForwardRefExoticComponent<Omit<SelectPrimitive.SelectItemProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const Skeleton: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+
+declare const Checkbox: react.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+
+interface SwitchProps extends ComponentPropsWithoutRef<typeof SwitchPrimitive.Root> {
+    size?: "sm" | "default";
+}
+declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLButtonElement>>;
+
+declare const Tabs: react.ForwardRefExoticComponent<TabsPrimitive.TabsProps & react.RefAttributes<HTMLDivElement>>;
+declare const TabsList: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsListProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const TabsTrigger: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+declare const TabsContent: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const Separator: react.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const ScrollBar: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaScrollbarProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const ScrollArea: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const Table: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableElement> & react.RefAttributes<HTMLTableElement>>;
+declare const TableHeader: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableSectionElement> & react.RefAttributes<HTMLTableSectionElement>>;
+declare const TableBody: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableSectionElement> & react.RefAttributes<HTMLTableSectionElement>>;
+declare const TableFooter: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableSectionElement> & react.RefAttributes<HTMLTableSectionElement>>;
+declare const TableRow: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableRowElement> & react.RefAttributes<HTMLTableRowElement>>;
+declare const TableHead: react.ForwardRefExoticComponent<ThHTMLAttributes<HTMLTableCellElement> & react.RefAttributes<HTMLTableCellElement>>;
+declare const TableCell: react.ForwardRefExoticComponent<TdHTMLAttributes<HTMLTableCellElement> & react.RefAttributes<HTMLTableCellElement>>;
+declare const TableCaption: react.ForwardRefExoticComponent<HTMLAttributes<HTMLTableCaptionElement> & react.RefAttributes<HTMLTableCaptionElement>>;
+
+declare const DropdownMenu: react.FC<DropdownMenuPrimitive.DropdownMenuProps>;
+declare const DropdownMenuTrigger: react.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const DropdownMenuGroup: react.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuGroupProps & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuPortal: react.FC<DropdownMenuPrimitive.DropdownMenuPortalProps>;
+declare const DropdownMenuSub: react.FC<DropdownMenuPrimitive.DropdownMenuSubProps>;
+declare const DropdownMenuRadioGroup: react.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuRadioGroupProps & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuContent: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuItem: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & react.RefAttributes<HTMLDivElement>, "ref"> & {
+    danger?: boolean;
+} & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuCheckboxItem: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuCheckboxItemProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuRadioItem: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuRadioItemProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuSeparator: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSeparatorProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuLabel: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuLabelProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuShortcut: ({ className, ...props }: HTMLAttributes<HTMLSpanElement>) => react.JSX.Element;
+declare const DropdownMenuSubTrigger: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSubTriggerProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuSubContent: react.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSubContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
+declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
+declare const SheetPortal: react.FC<DialogPrimitive.DialogPortalProps>;
+declare const sheetVariants: (props?: ({
+    side?: "top" | "right" | "bottom" | "left" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants> {
+}
+declare const SheetContent: react.ForwardRefExoticComponent<SheetContentProps & react.RefAttributes<HTMLDivElement>>;
+declare const SheetHeader: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const SheetFooter: ({ className, ...props }: HTMLAttributes<HTMLDivElement>) => ReactElement;
+declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
+declare const SheetDescription: react.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
+
+declare const TooltipProvider: react.FC<TooltipPrimitive.TooltipProviderProps>;
+declare const Tooltip: react.FC<TooltipPrimitive.TooltipProps>;
+declare const TooltipTrigger: react.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const TooltipContent: react.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+interface ModalProps {
+    /** Whether the modal is open. Modal is fully controlled — no internal open state. */
+    open: boolean;
+    /** Called when Radix wants to change the open state (backdrop click, Esc, close button). */
+    onOpenChange: (open: boolean) => void;
+    /** Dialog title, rendered in `DialogTitle`. */
+    title: string;
+    /** Optional supporting copy, rendered in `DialogDescription` under the title. */
+    description?: string;
+    /** Body content of the modal. */
+    children: ReactNode;
+    /** Optional footer content (typically action buttons), rendered in `DialogFooter`. */
+    footer?: ReactNode;
+    /** Extra classes applied to `DialogContent`, e.g. to override the default width. */
+    className?: string;
+}
+/**
+ * Base structural wrapper around the `@bmsuisse/ui` Dialog primitives: title,
+ * optional description, body, and an optional footer. Use this directly for
+ * modals that don't fit `ConfirmDialog` or `FormModal`; those two are built
+ * on top of the same shape.
+ */
+declare const Modal: ({ open, onOpenChange, title, description, children, footer, className, }: ModalProps) => ReactElement;
+
+interface ConfirmDialogProps {
+    /** 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). */
+    onOpenChange: (open: boolean) => void;
+    /** Dialog title. */
+    title: string;
+    /** Optional supporting copy shown under the title. */
+    description?: string;
+    /** Label for the confirm button. Defaults to `"Confirm"`. */
+    confirmLabel?: string;
+    /** Label for the cancel button. Defaults to `"Cancel"`. */
+    cancelLabel?: string;
+    /** Called when the user clicks confirm. May return a promise; the dialog waits for it. */
+    onConfirm: () => void | Promise<void>;
+    /** Visual style of the confirm button. Defaults to `"default"`. */
+    variant?: "default" | "destructive";
+    /** Forwarded to the confirm button, for test targeting (e.g. Playwright/Testing Library). */
+    confirmTestId?: string;
+    /** Forwarded to the cancel button, for test targeting. */
+    cancelTestId?: string;
+}
+/**
+ * "Are you sure?" confirmation dialog. Unlike `FormModal`, this DOES close
+ * itself automatically after a successful `onConfirm` — confirmations are a
+ * single yes/no action with no follow-up state to inspect, so there's nothing
+ * for the caller to decide. If `onConfirm` throws/rejects, the dialog stays
+ * open and the error is not swallowed, so a caller can surface its own error
+ * UI without the dialog disappearing out from under it.
+ */
+declare const ConfirmDialog: ({ open, onOpenChange, title, description, confirmLabel, cancelLabel, onConfirm, variant, confirmTestId, cancelTestId, }: ConfirmDialogProps) => ReactElement;
+
+interface FormModalProps {
+    /** Whether the modal is open. Fully controlled — no internal open state. */
+    open: boolean;
+    /** Called when Radix wants to change the open state (backdrop click, Esc, close button). */
+    onOpenChange: (open: boolean) => void;
+    /** Dialog title. */
+    title: string;
+    /** Optional supporting copy shown under the title. */
+    description?: string;
+    /** Form field content, rendered inside the `<form>`. */
+    children: ReactNode;
+    /** Called on submit (button click or Enter in a field). May return a promise. */
+    onSubmit: () => void | Promise<void>;
+    /** Label for the submit button. Defaults to `"Save"`. */
+    submitLabel?: string;
+    /** Label for the cancel button. Defaults to `"Cancel"`. */
+    cancelLabel?: string;
+    /**
+     * Disables the submit button (e.g. required fields still empty), on top of
+     * the automatic disable while `onSubmit`'s promise is pending. Cancel
+     * stays enabled either way. Defaults to `false`.
+     */
+    submitDisabled?: boolean;
+    /** Extra classes applied to `DialogContent`, e.g. to override the default width. */
+    className?: string;
+    /** Forwarded to the submit button, for test targeting (e.g. Playwright/Testing Library). */
+    submitTestId?: string;
+    /** Forwarded to the cancel button, for test targeting. */
+    cancelTestId?: string;
+}
+/**
+ * Modal wrapping a form. Unlike `ConfirmDialog`, this does NOT close itself
+ * after a successful `onSubmit` — forms commonly have server-side validation
+ * and shouldn't vanish on failure, so closing after success is left entirely
+ * to the caller (typically by calling `onOpenChange(false)` once its own
+ * submit handler resolves without error).
+ */
+declare const FormModal: ({ open, onOpenChange, title, description, children, onSubmit, submitLabel, cancelLabel, submitDisabled, className, submitTestId, cancelTestId, }: FormModalProps) => ReactElement;
+
+interface FormFieldProps {
+    /** Visible label text for the field. */
+    label: string;
+    /** Explicit id to associate the label with the child control. Auto-generated when omitted. */
+    htmlFor?: string;
+    /** Validation error text. When set, takes precedence over `description` and marks the child as invalid. */
+    error?: string;
+    /** Helper text shown below the child control when there's no `error`. */
+    description?: string;
+    /** Renders a visual "required" indicator next to the label. */
+    required?: boolean;
+    /** The single form control (e.g. `Input`, `Textarea`, `Select`) this field wraps. */
+    children: ReactElement;
+    /** Additional class names for the outer wrapper. */
+    className?: string;
+}
+/**
+ * Wraps a single form control with a `Label`, optional required indicator, and
+ * either an `error` or `description` message — the "label + input + error"
+ * pattern used throughout the consuming apps' forms.
+ *
+ * Handles id plumbing automatically: generates a stable id (via `useId`) for
+ * the label/control pair unless `htmlFor` or the child's own `id` is set, and
+ * wires up `aria-invalid` / `aria-describedby` so the error or description
+ * text is announced by assistive tech.
+ */
+declare function FormField({ label, htmlFor, error, description, required, children, className, }: FormFieldProps): ReactElement;
+
+interface ComboboxOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /** Groups this option under a header with the given key, rendered as a bold label
+     * (plus a tri-state "select all" checkbox in multi-select mode — see `groupLabels`
+     * on the base props). Options sharing a `group` must be contiguous in `options` —
+     * the component renders a header the first time a group key is seen and does not
+     * re-sort the list, so interleaved groups would render more than one header for the
+     * same key. Ungrouped options (no `group`) render individually, with no header. */
+    group?: string;
+}
+interface ComboboxBaseProps {
+    /** The full option list. Filtering happens client-side against `label`. */
+    options: ComboboxOption[];
+    /** Trigger text shown when nothing is selected. Defaults to `"Select…"`. */
+    placeholder?: string;
+    /** Placeholder for the search input inside the popover. Defaults to `"Search…"`. */
+    searchPlaceholder?: string;
+    /** Shown when the search term matches nothing. Defaults to `"No matches."`. */
+    emptyMessage?: string;
+    disabled?: boolean;
+    /** Shows `loadingMessage` on the trigger instead of the placeholder/selection, and
+     * disables the trigger and clear affordance alongside `disabled`. For a combobox whose
+     * `options` are still being fetched. Defaults to `false`. */
+    loading?: boolean;
+    /** Trigger text shown while `loading` is true. Defaults to `"Loading…"`. */
+    loadingMessage?: string;
+    /** Shows a clear ("x") affordance on the trigger when a value is selected. Defaults to `true`. */
+    clearable?: boolean;
+    className?: string;
+    id?: string;
+    /** Forwarded to the trigger button, for test targeting (e.g. Playwright/Testing Library). */
+    "data-testid"?: string;
+    /** Display label for a group key (`ComboboxOption.group`). Falls back to the raw key
+     * when an entry is missing. Only relevant when at least one option sets `group`. */
+    groupLabels?: Record<string, string>;
+    /** Portal target for the popover, forwarded to the underlying `PopoverContent`.
+     * Needed when the combobox is opened from inside a modal Dialog/Sheet — pass the
+     * Dialog/Sheet content element so the popover portals inside it instead of
+     * `document.body`, which would otherwise fight with the Dialog's focus trap. */
+    container?: ComponentProps<typeof PopoverContent>["container"];
+    /** Switches the search input to server-driven mode: called with the raw search
+     * text on every keystroke (and with `""` when the popover opens), and `options`
+     * is rendered as-is instead of being filtered locally against `label`. Omit for
+     * the default client-side filtering behavior. */
+    onSearchChange?: (search: string) => void;
+    /** Fallback trigger label used when the current selection's `value`(s) aren't
+     * present in `options` — the case in server-driven search mode where the
+     * selected option was found by an earlier query and isn't part of the current
+     * result page. Ignored once a matching option is found in `options`. */
+    selectedLabel?: string;
+}
+interface ComboboxSingleProps extends ComboboxBaseProps {
+    /** Omitted or `false` for the (default) single-select shape below. */
+    multiple?: false;
+    /** Selected option's `value`, or `null`/`undefined` for no selection. */
+    value?: string | null;
+    /** Called with the newly selected option's `value`, or `null` when cleared. */
+    onChange: (value: string | null) => void;
+}
+interface ComboboxMultiProps extends ComboboxBaseProps {
+    /** `true` selects the multi-select shape below. */
+    multiple: true;
+    /** Selected options' `value`s. */
+    value: string[];
+    /** Called with the full updated selection after a toggle, or `[]` when cleared. */
+    onChange: (value: string[]) => void;
+}
+/**
+ * Discriminated on `multiple`: the default (omitted/`false`) shape is the
+ * original single-select API, unchanged (`value: string | null`); passing
+ * `multiple: true` switches to the array-valued shape (`value: string[]`).
+ */
+type ComboboxProps = ComboboxSingleProps | ComboboxMultiProps;
+/**
+ * A searchable dropdown ("autocomplete box"), single- or multi-select
+ * depending on the `multiple` prop: a button trigger showing the current
+ * selection, opening a popover with a text filter above a scrollable option
+ * list. Deliberately built on the existing `Popover` + `Input` primitives
+ * rather than a `cmdk`-based `Command` component — this mirrors
+ * `@bmsuisse/datagrid`'s `EnumFilter` (plain substring filter over a manually
+ * rendered list), keeping the dependency footprint the same as the rest of
+ * this package instead of introducing a new list/command library.
+ */
+declare function Combobox(props: ComboboxProps): ReactElement;
+
+type AlertBoxVariant = "error" | "warning" | "info" | "success";
+interface AlertBoxProps {
+    /** Determines the color scheme and the default icon. */
+    variant: AlertBoxVariant;
+    /** Optional bold heading line shown above the body content. */
+    title?: string;
+    /** Body text/content. Always rendered. */
+    children: ReactNode;
+    className?: string;
+    /**
+     * Overrides the default variant icon entirely. Pass `null` to hide the
+     * icon. Defaults to a variant-specific lucide-react icon.
+     */
+    icon?: ReactNode;
+}
+declare const AlertBox: ({ variant, title, children, className, icon }: AlertBoxProps) => ReactElement;
+
+/** Semantic color intent for a {@link StatusBadge}. */
+type StatusTone = "success" | "warning" | "error" | "info" | "neutral";
+interface StatusBadgeProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Raw status value from the caller's domain, e.g. `"pending"`, `"APPROVED"`, `"in_review"`. */
+    status: string;
+    /** Overrides the displayed text. Defaults to a title-cased, space-separated derivation of `status`. */
+    label?: string;
+    /** Explicit tone override. When provided, `toneMap` and the built-in default map are skipped entirely. */
+    tone?: StatusTone;
+    /** Caller-supplied status-to-tone mapping (case-insensitive keys), checked before the built-in default map. */
+    toneMap?: Record<string, StatusTone>;
+}
+/**
+ * A status-to-color badge, built on the shared `Badge` primitive.
+ *
+ * Centralizes the status->color mapping that's otherwise reimplemented ad hoc
+ * per app: callers can rely on the built-in English status vocabulary, supply
+ * their own `toneMap` for domain-specific statuses, or force a `tone`
+ * outright.
+ */
+declare const StatusBadge: ({ status, label, tone, toneMap, className, ...props }: StatusBadgeProps) => ReactElement;
+
+declare const loadingSpinnerIconVariants: (props?: ({
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface LoadingSpinnerProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof loadingSpinnerIconVariants> {
+    /** Optional text rendered next to the spinner. Omitted entirely renders an icon-only spinner. */
+    label?: string;
+}
+/** Inline loading indicator: a spinning icon with an optional label, e.g. `<LoadingSpinner label="Saving…" />`. */
+declare const LoadingSpinner: ({ size, label, className, ...props }: LoadingSpinnerProps) => ReactElement;
+interface LoadingOverlayProps extends HTMLAttributes<HTMLDivElement>, Pick<LoadingSpinnerProps, "label"> {
+    size?: LoadingSpinnerProps["size"];
+}
+/** 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;
+
+/** Merges conditional class names, then dedupes conflicting Tailwind utility classes. */
+declare function cn(...inputs: ClassValue[]): string;
+
+export { AlertBox, type AlertBoxProps, type AlertBoxVariant, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Combobox, type ComboboxMultiProps, type ComboboxOption, type ComboboxProps, type ComboboxSingleProps, ConfirmDialog, type ConfirmDialogProps, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, FormField, type FormFieldProps, FormModal, type FormModalProps, Input, type InputProps, Label, LoadingOverlay, type LoadingOverlayProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetPortal, SheetTitle, SheetTrigger, Skeleton, StatusBadge, type StatusBadgeProps, type StatusTone, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, type TextareaProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, cn, loadingSpinnerIconVariants, sheetVariants };