@caqophony/ui 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1716 @@
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+import { ReactNode, ReactElement, ComponentType } from 'react';
+import * as SwitchPrimitives from '@radix-ui/react-switch';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { MarkdownRenderer } from './markdown.mjs';
+import { LucideIcon } from 'lucide-react';
+import { ClassValue } from 'clsx';
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+    /** Show loading spinner and disable button */
+    loading?: boolean;
+    /** Text to show when loading (defaults to children) */
+    loadingText?: string;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Input Component
+ *
+ * Standard form input with consistent sizing, focus ring, and disabled state.
+ * Mobile-first: 44px minimum height for touch targets.
+ *
+ * Usage:
+ *   import { Input } from '@caqophony/ui';
+ *   <Input type="email" placeholder="Enter email" />
+ *
+ * Authored by Caqophony
+ */
+
+interface InputProps extends React.ComponentProps<'input'> {
+    /** Show error styling (red border + aria-invalid) */
+    error?: boolean;
+    /** ID of the element describing the error, for aria-describedby */
+    errorMessageId?: string;
+}
+declare const Input: React.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Card Component
+ *
+ * Composable card container with header, content, footer, title, and description.
+ * Uses Gossamer semantic tokens — no hardcoded colors.
+ *
+ * Usage:
+ *   import { Card, CardHeader, CardTitle, CardContent } from '@caqophony/ui';
+ *   <Card>
+ *     <CardHeader><CardTitle>Title</CardTitle></CardHeader>
+ *     <CardContent>Body</CardContent>
+ *   </Card>
+ *
+ * Authored by Caqophony
+ */
+
+declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Switch Component
+ *
+ * Accessible toggle switch using Radix UI primitives.
+ * Uses Gossamer semantic tokens for dark mode support.
+ *
+ * Authored by Caqophony
+ */
+
+interface SwitchProps extends React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root> {
+    /** Optional label to display next to the switch */
+    label?: string;
+    /** Optional description text below the label */
+    description?: string;
+}
+declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Tooltip Component
+ *
+ * A reusable tooltip using Radix UI primitives.
+ * Use for showing additional information on hover.
+ *
+ * Usage:
+ * ```tsx
+ * import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@caqophony/ui';
+ *
+ * <TooltipProvider>
+ *   <Tooltip>
+ *     <TooltipTrigger>Hover me</TooltipTrigger>
+ *     <TooltipContent>Tooltip text</TooltipContent>
+ *   </Tooltip>
+ * </TooltipProvider>
+ * ```
+ *
+ * Authored by Caqophony
+ */
+
+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 FormFieldProps {
+    /** Field label text */
+    label: string;
+    /** Field name (used for htmlFor) */
+    name: string;
+    /** Error message to display */
+    error?: string;
+    /** Optional description/hint text */
+    description?: string;
+    /** Whether field is required */
+    required?: boolean;
+    /** Whether the field and its child input are disabled */
+    disabled?: boolean;
+    /** Children (typically Input, Select, etc.) */
+    children: React.ReactNode;
+    /** Additional className for the wrapper */
+    className?: string;
+}
+/**
+ * FormField - Wrapper component for form inputs with validation feedback
+ *
+ * Features:
+ * - Label with optional required indicator
+ * - Error state with red border on child input
+ * - Error message displayed below input
+ * - Optional description/hint text
+ * - Mobile-first responsive design
+ */
+declare function FormField({ label, name, error, description, required, disabled, children, className, }: FormFieldProps): react_jsx_runtime.JSX.Element;
+/**
+ * FormFieldGroup - Groups multiple FormFields horizontally on larger screens
+ *
+ * Usage:
+ *   <FormFieldGroup>
+ *     <FormField label="First Name" name="firstName">...</FormField>
+ *     <FormField label="Last Name" name="lastName">...</FormField>
+ *   </FormFieldGroup>
+ */
+interface FormFieldGroupProps {
+    children: React.ReactNode;
+    className?: string;
+}
+declare function FormFieldGroup({ children, className }: FormFieldGroupProps): react_jsx_runtime.JSX.Element;
+/**
+ * FormSection - Groups related form fields with an optional heading
+ *
+ * Usage:
+ *   <FormSection title="Personal Information">
+ *     <FormField label="Name" name="name">...</FormField>
+ *   </FormSection>
+ */
+interface FormSectionProps {
+    title?: string;
+    description?: string;
+    children: React.ReactNode;
+    className?: string;
+}
+declare function FormSection({ title, description, children, className, }: FormSectionProps): react_jsx_runtime.JSX.Element;
+/**
+ * FormError - Displays form-level errors (not field-specific)
+ *
+ * Usage:
+ *   <FormError error="Unable to save changes. Please try again." />
+ */
+interface FormErrorProps {
+    error?: string | null;
+    className?: string;
+}
+declare function FormError({ error, className }: FormErrorProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * FormSuccess - Displays form-level success messages
+ *
+ * Usage:
+ *   <FormSuccess message="Changes saved successfully!" />
+ */
+interface FormSuccessProps {
+    message?: string | null;
+    className?: string;
+}
+declare function FormSuccess({ message, className }: FormSuccessProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Global Error Content Component
+ *
+ * Centralized error UI for global-error.tsx pages across all apps.
+ * This component provides the error display content that each app wraps
+ * in their own global-error.tsx with the required <html> and <body> tags.
+ *
+ * IMPORTANT: Next.js 16 with Turbopack prerenders global-error.tsx during build.
+ * This component must be completely STATELESS - no hooks (useState, useEffect, etc.)
+ * allowed. If you need client-side logic, use event handlers that check `typeof window`.
+ *
+ * Sentry reporting should happen server-side via error.tsx instead.
+ *
+ * @see https://github.com/vercel/next.js/issues/85668
+ *
+ * Authored by Caqophony
+ */
+
+interface GlobalErrorContentProps {
+    /** The error that occurred */
+    error: Error & {
+        digest?: string;
+    };
+    /** Next.js reset function to re-render the page */
+    reset: () => void;
+    /** Optional app name for branding/support context */
+    appName?: string;
+    /** Support address for the "contact support" link. The link is omitted when not provided. */
+    supportEmail?: string;
+    /** Optional custom action buttons to display instead of defaults */
+    customActions?: ReactNode;
+}
+/**
+ * Stateless error content component for global-error pages.
+ *
+ * Usage in app/global-error.tsx:
+ * ```tsx
+ * 'use client';
+ * import { GlobalErrorContent } from '@caqophony/ui';
+ *
+ * export default function GlobalError({ error, reset }) {
+ *   return (
+ *     <html lang="en">
+ *       <body style={{ margin: 0 }}>
+ *         <GlobalErrorContent error={error} reset={reset} appName="My App" />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function GlobalErrorContent({ error, reset, appName, supportEmail, customActions, }: GlobalErrorContentProps): ReactElement;
+
+interface SidebarContextValue {
+    isCollapsed: boolean;
+    toggle: () => void;
+}
+declare function useSidebar(): SidebarContextValue;
+interface NavItem {
+    name: string;
+    href: string;
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    description?: string;
+}
+type LinkComponentProps = {
+    href: unknown;
+    className?: string;
+    children: ReactNode;
+};
+interface CollapsibleSidebarProps {
+    /** Unique key for localStorage persistence */
+    storageKey?: string;
+    /** Default collapsed state */
+    defaultCollapsed?: boolean;
+    /** Header content (title, logo) */
+    header?: ReactNode;
+    /** Header content when collapsed (optional, defaults to null) */
+    collapsedHeader?: ReactNode;
+    /** Navigation items */
+    items: NavItem[];
+    /** Function to check if item is active */
+    isActive?: (href: string) => boolean;
+    /** Custom link component (for Next.js Link) */
+    linkComponent?: ComponentType<LinkComponentProps>;
+    /** Footer content */
+    footer?: ReactNode;
+    /** Footer content when collapsed (optional) */
+    collapsedFooter?: ReactNode;
+    /** Additional className */
+    className?: string;
+    /** Custom collapsed width (default: 64px) */
+    collapsedWidth?: number;
+    /** Custom expanded width (default: 256px) */
+    expandedWidth?: number;
+}
+declare function CollapsibleSidebar({ storageKey, defaultCollapsed, header, collapsedHeader, items, isActive, linkComponent: LinkComponent, footer, collapsedFooter, className, collapsedWidth, expandedWidth, }: CollapsibleSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface AccordionSingleProps {
+    type?: 'single';
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    collapsible?: boolean;
+    children: React.ReactNode;
+    className?: string;
+}
+interface AccordionMultipleProps {
+    type: 'multiple';
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    children: React.ReactNode;
+    className?: string;
+}
+type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+declare function Accordion(props: AccordionProps): react_jsx_runtime.JSX.Element;
+interface AccordionItemProps {
+    value: string;
+    children: React.ReactNode;
+    className?: string;
+    disabled?: boolean;
+    /** Optional data-testid for the item wrapper */
+    testId?: string;
+}
+declare function AccordionItem({ value, children, className, disabled, testId, }: AccordionItemProps): react_jsx_runtime.JSX.Element;
+interface AccordionTriggerProps {
+    children: React.ReactNode;
+    className?: string;
+    icon?: React.ReactNode;
+    /** Additional content on the right side (before chevron) */
+    rightContent?: React.ReactNode;
+    /** Optional data-testid for the trigger button */
+    testId?: string;
+}
+declare function AccordionTrigger({ children, className, icon, rightContent, testId, }: AccordionTriggerProps): react_jsx_runtime.JSX.Element;
+interface AccordionContentProps {
+    children: React.ReactNode;
+    className?: string;
+    /** Optional data-testid for the content wrapper */
+    testId?: string;
+}
+declare function AccordionContent({ children, className, testId, }: AccordionContentProps): react_jsx_runtime.JSX.Element;
+/**
+ * SimpleAccordion - A single, self-contained accordion section
+ *
+ * For when you just need one expandable section without the full Accordion setup.
+ *
+ * Usage:
+ *   <SimpleAccordion
+ *     title="Advanced Settings"
+ *     icon={<Settings className="size-5" />}
+ *     defaultOpen={false}
+ *   >
+ *     Content here...
+ *   </SimpleAccordion>
+ */
+interface SimpleAccordionProps {
+    /** The trigger title */
+    title: React.ReactNode;
+    /** Optional icon before the title */
+    icon?: React.ReactNode;
+    /** Content on the right side of the trigger (before chevron) */
+    rightContent?: React.ReactNode;
+    /** Whether the accordion is open by default */
+    defaultOpen?: boolean;
+    /** Controlled open state */
+    open?: boolean;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** The accordion content */
+    children: React.ReactNode;
+    /** Additional class for the container */
+    className?: string;
+    /** Additional class for the trigger */
+    triggerClassName?: string;
+    /** Additional class for the content wrapper */
+    contentClassName?: string;
+    /** Optional data-testid for the trigger button */
+    triggerTestId?: string;
+    /** Optional data-testid for the content area */
+    contentTestId?: string;
+}
+declare function SimpleAccordion({ title, icon, rightContent, defaultOpen, open: controlledOpen, onOpenChange, children, className, triggerClassName, contentClassName, triggerTestId, contentTestId, }: SimpleAccordionProps): react_jsx_runtime.JSX.Element;
+
+interface ConfirmDialogProps {
+    /** Dialog title */
+    title: string;
+    /** Dialog message/description */
+    message: string;
+    /** Confirm button text */
+    confirmLabel: string;
+    /** Callback when confirmed */
+    onConfirm: () => void;
+    /** Callback when cancelled */
+    onCancel: () => void;
+    /** Loading state (disables buttons and shows spinner) */
+    isLoading?: boolean;
+    /** Test ID for the confirm button */
+    confirmTestId?: string;
+    /** Test ID for the cancel button */
+    cancelTestId?: string;
+    /** Test ID for the dialog overlay */
+    dialogTestId?: string;
+    /** Cancel button text (default: "Cancel") */
+    cancelLabel?: string;
+    /** Variant for confirm button (default: "default") */
+    confirmVariant?: 'default' | 'destructive';
+    /** Additional class for the dialog container */
+    className?: string;
+}
+declare function ConfirmDialog({ title, message, confirmLabel, onConfirm, onCancel, isLoading, confirmTestId, cancelTestId, dialogTestId, cancelLabel, confirmVariant, className, }: ConfirmDialogProps): react_jsx_runtime.JSX.Element;
+
+/** Supported DiceBear avatar styles */
+type DiceBearStyle = 'adventurer' | 'adventurer-neutral' | 'avataaars' | 'avataaars-neutral' | 'big-ears' | 'big-ears-neutral' | 'bottts' | 'bottts-neutral' | 'croodles' | 'croodles-neutral' | 'fun-emoji' | 'icons' | 'identicon' | 'initials' | 'lorelei' | 'lorelei-neutral' | 'micah' | 'miniavs' | 'notionists' | 'notionists-neutral' | 'open-peeps' | 'personas' | 'pixel-art' | 'pixel-art-neutral' | 'rings' | 'shapes' | 'thumbs';
+declare const avatarVariants: (props?: ({
+    size?: "sm" | "lg" | "xs" | "md" | "xl" | "2xl" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+/**
+ * Build a DiceBear avatar URL from a seed and style.
+ * Deterministic — same seed + style always produces the same avatar.
+ */
+declare function buildDiceBearUrl(seed: string, style?: DiceBearStyle): string;
+interface DiceBearAvatarProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof avatarVariants> {
+    /** Seed string for deterministic avatar generation (e.g. agent ID or name) */
+    seed: string;
+    /** DiceBear style to use. Defaults to 'adventurer-neutral'. */
+    avatarStyle?: DiceBearStyle;
+    /** Alt text for accessibility. Defaults to 'Avatar'. */
+    alt?: string;
+    /** Fallback content when image fails to load (e.g. initials) */
+    fallback?: React.ReactNode;
+}
+declare const DiceBearAvatar: React.ForwardRefExoticComponent<DiceBearAvatarProps & React.RefAttributes<HTMLDivElement>>;
+
+interface IntentIconProps {
+    intent?: 'success' | 'warning' | 'error' | 'info';
+    size?: 'sm' | 'md';
+}
+declare function IntentIcon({ intent, size, }: IntentIconProps): react_jsx_runtime.JSX.Element;
+
+interface SectionHeadingProps {
+    title: string;
+    description?: string;
+    align?: 'center' | 'left';
+    size?: 'display' | 'h1' | 'h2' | 'h3';
+}
+declare function SectionHeading({ title, description, align, size, }: SectionHeadingProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * FilterChip Atom Component
+ *
+ * Inline filter toggle with optional count badge.
+ * Uses Gossamer semantic tokens for dark mode support.
+ *
+ * Authored by Caqophony
+ */
+interface FilterChipProps {
+    /** Display label */
+    label: string;
+    /** Whether the chip is currently selected */
+    active?: boolean;
+    /** Optional count badge */
+    count?: number;
+    /** Chip size */
+    size?: 'sm' | 'md';
+    /** Click handler */
+    onClick?: () => void;
+}
+/**
+ * FilterChip — a pill-shaped toggle for filter bars.
+ *
+ * - **Inactive**: white bg, border, muted text
+ * - **Active**: foreground bg, white text
+ * - Optional count badge with accessible contrast (WCAG AA 5.7:1)
+ */
+declare function FilterChip({ label, active, count, size, onClick, }: FilterChipProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * DistributionChip — a color-dotted count chip for reading a state/cost mix at a
+ * glance in a focal header (e.g. "● 12 running  ● 3 failed"). The count/label
+ * distribution idiom used across the design-sweep headers.
+ *
+ * Authored by Caqophony
+ */
+interface DistributionChipProps {
+    /** The count (or short value) shown in the chip. */
+    count: number | string;
+    /** The label describing what the count measures. */
+    label: string;
+    /** Tailwind class for the leading status dot (e.g. `bg-intent-success`). */
+    dotClass: string;
+    /** Optional test id. */
+    testId?: string;
+}
+declare function DistributionChip({ count, label, dotClass, testId, }: DistributionChipProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SkeletonBar Atom Component
+ *
+ * Simple loading placeholder rectangle with muted fill and pill radius.
+ * Used as a building block in SkeletonCard and SkeletonRow.
+ *
+ * Authored by Caqophony
+ */
+interface SkeletonBarProps {
+    /** Width in px, or "full" for 100%. Default: "full" */
+    width?: number | 'full';
+    /** Height in px. Default: 14 */
+    height?: number;
+    /** Optional CSS class name */
+    className?: string;
+}
+/**
+ * SkeletonBar — a single loading placeholder bar.
+ *
+ * Mirrors the Figma skeletonBar helper: muted fill, pill radius (height/2),
+ * animate-pulse for loading indication.
+ */
+declare function SkeletonBar({ width, height, className, }: SkeletonBarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SkeletonCard Atom Component
+ *
+ * Card-shaped loading placeholder with 3 skeleton bars inside.
+ * Static placeholder requiring no props.
+ *
+ * Authored by Caqophony
+ */
+interface SkeletonCardProps {
+    /** Optional CSS class name */
+    className?: string;
+}
+/**
+ * SkeletonCard — a card loading placeholder.
+ *
+ * Mirrors the Figma skeletonCard helper: card bg, border, rounded-xl,
+ * padding 20px, gap 10px, containing 3 skeleton bars (80x10, 60x24, 100x10).
+ */
+declare function SkeletonCard({ className }: SkeletonCardProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SkeletonRow Atom Component
+ *
+ * Row-shaped loading placeholder with avatar circle + 2 skeleton bars.
+ * Static placeholder requiring no props.
+ *
+ * Authored by Caqophony
+ */
+interface SkeletonRowProps {
+    /** Optional CSS class name */
+    className?: string;
+}
+/**
+ * SkeletonRow — a row loading placeholder with avatar and text lines.
+ *
+ * Mirrors the Figma skeletonRow helper: card bg, border, rounded-[10px],
+ * padding 14px/18px, gap 14px, with 36px circle avatar + 2 bars (200x12, 140x10).
+ */
+declare function SkeletonRow({ className }: SkeletonRowProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * StackedList Component
+ *
+ * Vertical list of items with avatar, content, and action slots.
+ * Common pattern for entity lists, activity feeds, and notification panels.
+ *
+ * Usage:
+ *   import { StackedList, StackedListItem } from '@caqophony/ui';
+ *   <StackedList divided>
+ *     <StackedListItem
+ *       avatar={<Avatar />}
+ *       title="Item title"
+ *       description="Description text"
+ *       action={<Button size="sm">Edit</Button>}
+ *     />
+ *   </StackedList>
+ *
+ * Issue #2630 — B-4: Stacked Lists + Grid Lists
+ * Authored by Caqophony
+ */
+
+interface StackedListProps extends React.HTMLAttributes<HTMLUListElement> {
+    divided?: boolean;
+    density?: 'compact' | 'default';
+}
+declare const StackedList: React.ForwardRefExoticComponent<StackedListProps & React.RefAttributes<HTMLUListElement>>;
+interface StackedListItemProps extends React.HTMLAttributes<HTMLLIElement> {
+    avatar?: React.ReactNode;
+    title: string;
+    description?: string;
+    meta?: string;
+    action?: React.ReactNode;
+    density?: 'compact' | 'default';
+}
+declare const StackedListItem: React.ForwardRefExoticComponent<StackedListItemProps & React.RefAttributes<HTMLLIElement>>;
+
+/**
+ * GridList Component
+ *
+ * Responsive grid of card-style items. Common pattern for entity galleries,
+ * product grids, and dashboard card layouts.
+ *
+ * Usage:
+ *   import { GridList, GridListItem } from '@caqophony/ui';
+ *   <GridList columns={3} gap="md">
+ *     <GridListItem>Card content</GridListItem>
+ *   </GridList>
+ *
+ * Issue #2630 — B-4: Stacked Lists + Grid Lists
+ * Authored by Caqophony
+ */
+
+interface GridListProps extends React.HTMLAttributes<HTMLDivElement> {
+    columns?: 2 | 3 | 4;
+    gap?: 'sm' | 'md' | 'lg';
+}
+declare const GridList: React.ForwardRefExoticComponent<GridListProps & React.RefAttributes<HTMLDivElement>>;
+interface GridListItemProps extends React.HTMLAttributes<HTMLDivElement> {
+    hoverable?: boolean;
+}
+declare const GridListItem: React.ForwardRefExoticComponent<GridListItemProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Pagination Component
+ *
+ * Page navigation controls for data tables and list views.
+ * Supports simple (prev/next), numbered, and centered variants.
+ *
+ * Usage:
+ *   import { Pagination } from '@caqophony/ui';
+ *   <Pagination currentPage={1} totalPages={10} onPageChange={setPage} />
+ *
+ * Issue #2634 — B-8: Pagination + Stepper
+ * Authored by Caqophony
+ */
+
+interface PaginationProps extends React.HTMLAttributes<HTMLElement> {
+    currentPage: number;
+    totalPages: number;
+    onPageChange?: (page: number) => void;
+    variant?: 'simple' | 'numbered' | 'centered';
+    siblingCount?: number;
+}
+declare function getPageRange(current: number, total: number, siblings: number): (number | 'ellipsis')[];
+declare const PaginationButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    active?: boolean;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLElement>>;
+
+/**
+ * Stepper Component
+ *
+ * Multi-step progress indicator for wizards and multi-phase workflows.
+ * Supports horizontal (progress bar) and vertical (sidebar checklist) variants.
+ *
+ * Usage:
+ *   import { Stepper, StepperStep } from '@caqophony/ui';
+ *   <Stepper variant="horizontal" activeStep={1}>
+ *     <StepperStep label="Account" />
+ *     <StepperStep label="Profile" />
+ *     <StepperStep label="Review" />
+ *   </Stepper>
+ *
+ * Issue #2634 — B-8: Pagination + Stepper
+ * Authored by Caqophony
+ */
+
+interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: 'horizontal' | 'vertical';
+    activeStep: number;
+    size?: 'sm' | 'md' | 'lg';
+}
+interface StepperStepProps extends React.HTMLAttributes<HTMLDivElement> {
+    label: string;
+    description?: string;
+    icon?: React.ReactNode;
+    /** Mark this step as having an error */
+    error?: boolean;
+    /** Disable this step (prevents interaction, muted styling) */
+    disabled?: boolean;
+    /**
+     * Force the completed (✓) indicator even when this step is the current one.
+     * Steps before activeStep are completed automatically; this covers the case
+     * where the user revisits an already-completed step (current AND done).
+     */
+    completed?: boolean;
+    /** Optional href — wraps the indicator + label in an anchor tag for navigation */
+    href?: string;
+}
+declare const StepperStep: React.ForwardRefExoticComponent<StepperStepProps & React.RefAttributes<HTMLDivElement>>;
+declare const Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * CommandPalette Component
+ *
+ * Power-user search/navigation overlay (Cmd+K).
+ *
+ * Token mapping:
+ *   bg-card        -> colors.card      (palette bg)
+ *   border-border  -> colors.border    (input border, dividers)
+ *   bg-muted       -> colors.muted     (active result bg)
+ *   text-foreground -> colors.foreground (result text)
+ *   text-muted-fg  -> colors.mutedFg   (group labels, shortcuts)
+ *   z-modal        -> zIndex.modal     (above everything)
+ *
+ * Issue #2631 — B-5: Command Palette (Cmd+K)
+ * Authored by Caqophony
+ */
+
+interface CommandPaletteResult {
+    id: string;
+    label: string;
+    group?: string;
+    shortcut?: string;
+    icon?: React.ReactNode;
+    onSelect?: () => void;
+}
+interface CommandPaletteProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'results'> {
+    open?: boolean;
+    onClose?: () => void;
+    results?: CommandPaletteResult[];
+    placeholder?: string;
+    onSearch?: (query: string) => void;
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const CommandPalette: React.ForwardRefExoticComponent<CommandPaletteProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * AppShell Component
+ *
+ * Generic application layout shells for generated apps.
+ * Stacked (top nav + content), Sidebar (collapsible + content),
+ * Multi-column (sidebar + main + detail panel).
+ *
+ * Token mapping:
+ *   bg-background  -> colors.background  (page bg)
+ *   bg-card        -> colors.card         (sidebar bg)
+ *   border-border  -> colors.border       (sidebar border)
+ *
+ * Issue #2629 — B-3: Application Shells
+ * Authored by Caqophony
+ */
+
+interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: 'stacked' | 'sidebar' | 'multi-column';
+    sidebarPosition?: 'left' | 'right';
+    sidebarCollapsed?: boolean;
+    header?: React.ReactNode;
+    sidebar?: React.ReactNode;
+    detailPanel?: React.ReactNode;
+}
+declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Popover + HoverCard Components
+ *
+ * Content-rich tooltips for entity previews and contextual help.
+ *
+ * Token mapping:
+ *   bg-card        -> colors.card      (popover bg)
+ *   border-border  -> colors.border    (popover border)
+ *   z-popover      -> zIndex.popover   (80)
+ *   shadow-lg      -> elevation-3
+ *
+ * Issue #2651 — B-19: Popover + Hover Card
+ * Authored by Caqophony
+ */
+
+interface PopoverProps extends React.HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    trigger: React.ReactNode;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+    align?: 'start' | 'center' | 'end';
+}
+declare const Popover: React.ForwardRefExoticComponent<PopoverProps & React.RefAttributes<HTMLDivElement>>;
+interface HoverCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    trigger: React.ReactNode;
+    side?: 'top' | 'bottom';
+    align?: 'start' | 'center' | 'end';
+    delay?: number;
+}
+declare const HoverCard: React.ForwardRefExoticComponent<HoverCardProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Calendar + DatePicker Components
+ *
+ * Calendar renders a month grid with selectable days, event dots,
+ * single/range selection, and full keyboard navigation.
+ * DatePicker wraps Calendar in a popover triggered by an input.
+ *
+ * Token mapping:
+ *   bg-card          -> colors.card       (calendar bg)
+ *   border-border    -> colors.border     (calendar border, input border)
+ *   bg-primary       -> colors.primary    (selected day, range endpoints)
+ *   bg-primary/10    -> colors.primary10  (range middle days)
+ *   text-primary-foreground -> colors.white (selected day text)
+ *   bg-muted         -> colors.muted      (today highlight)
+ *   text-muted-foreground -> colors.mutedFg (weekday headers)
+ *   text-foreground  -> colors.foreground (day text, navigation)
+ *   bg-intent-info   -> colors.info       (event dots)
+ *   z-popover        -> zIndex.popover    (datepicker dropdown)
+ *
+ * Issue #2640 — B-13: Calendar + DatePicker
+ * Authored by Caqophony
+ */
+
+interface CalendarEvent {
+    date: Date;
+    color?: string;
+}
+interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** Currently selected date (single mode) */
+    value?: Date | null;
+    /** Called when a day is clicked (single mode) */
+    onChange?: (date: Date) => void;
+    /** Selection mode */
+    selectionMode?: 'single' | 'range';
+    /** Range start date (range mode) */
+    rangeStart?: Date | null;
+    /** Range end date (range mode) */
+    rangeEnd?: Date | null;
+    /** Called when a range endpoint is selected */
+    onRangeChange?: (start: Date | null, end: Date | null) => void;
+    /** Minimum selectable date */
+    minDate?: Date;
+    /** Maximum selectable date */
+    maxDate?: Date;
+    /** Events to show as dots under day numbers */
+    events?: CalendarEvent[];
+    /** Override "today" date (for testing or server-injected current date) */
+    today?: Date;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const Calendar: React.ForwardRefExoticComponent<CalendarProps & React.RefAttributes<HTMLDivElement>>;
+interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** Selection variant */
+    variant?: 'single' | 'range';
+    /** Currently selected date (single mode) */
+    value?: Date | null;
+    /** Called when a date is selected (single mode) */
+    onChange?: (date: Date) => void;
+    /** Range start date (range mode) */
+    rangeStart?: Date | null;
+    /** Range end date (range mode) */
+    rangeEnd?: Date | null;
+    /** Called when range changes */
+    onRangeChange?: (start: Date | null, end: Date | null) => void;
+    /** Placeholder text when no date is selected */
+    placeholder?: string;
+    /** Minimum selectable date */
+    minDate?: Date;
+    /** Maximum selectable date */
+    maxDate?: Date;
+    /** Events to show on calendar */
+    events?: CalendarEvent[];
+    /** Controlled open state */
+    open?: boolean;
+    /** Called when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Calendar size */
+    calendarSize?: 'sm' | 'md' | 'lg';
+    /** Disabled state */
+    disabled?: boolean;
+}
+declare const DatePicker: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Navbar Component
+ *
+ * Top navigation bar with simple, centered, withSearch, twoLevel variants.
+ *
+ * Token mapping:
+ *   bg-card        -> colors.card      (nav bg)
+ *   border-border  -> colors.border    (bottom border)
+ *   text-foreground -> colors.foreground (active links)
+ *   text-muted-fg  -> colors.mutedFg   (inactive links)
+ *
+ * Issue #2647 — B-16: Extended Navbar Variants
+ * Authored by Caqophony
+ */
+
+interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
+    variant?: 'simple' | 'centered' | 'withSearch' | 'twoLevel';
+    transparent?: boolean;
+    logo?: React.ReactNode;
+    actions?: React.ReactNode;
+    search?: React.ReactNode;
+    secondaryNav?: React.ReactNode;
+}
+declare const Navbar: React.ForwardRefExoticComponent<NavbarProps & React.RefAttributes<HTMLElement>>;
+interface NavbarLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    active?: boolean;
+}
+declare const NavbarLink: React.ForwardRefExoticComponent<NavbarLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+
+/**
+ * Extended Card Variants
+ *
+ * Beyond the basic Card: horizontal, image, stat, action card patterns.
+ *
+ * Token mapping:
+ *   bg-card         -> colors.card
+ *   border-border   -> colors.border
+ *   text-foreground -> colors.foreground
+ *   text-muted-fg   -> colors.mutedFg
+ *   hover:shadow-md -> elevation-2 (hoverable)
+ *
+ * Issue #2648 — B-17: Extended Card Variants
+ * Authored by Caqophony
+ */
+
+interface HorizontalCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    media?: React.ReactNode;
+    hoverable?: boolean;
+}
+declare const HorizontalCard: React.ForwardRefExoticComponent<HorizontalCardProps & React.RefAttributes<HTMLDivElement>>;
+interface ImageCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    imageSrc?: string;
+    imageAlt?: string;
+    hoverable?: boolean;
+}
+declare const ImageCard: React.ForwardRefExoticComponent<ImageCardProps & React.RefAttributes<HTMLDivElement>>;
+interface StatCardExtendedProps extends React.HTMLAttributes<HTMLDivElement> {
+    label: string;
+    value: string;
+    trend?: {
+        direction: 'up' | 'down' | 'neutral';
+        text: string;
+    };
+    icon?: React.ReactNode;
+}
+declare const StatCardExtended: React.ForwardRefExoticComponent<StatCardExtendedProps & React.RefAttributes<HTMLDivElement>>;
+interface ActionCardProps extends React.HTMLAttributes<HTMLDivElement> {
+    title: string;
+    description?: string;
+    actions?: React.ReactNode;
+}
+declare const ActionCard: React.ForwardRefExoticComponent<ActionCardProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ModalDialog Component
+ *
+ * Overlay dialog with backdrop, focus trap, and composable slots.
+ *
+ * Token mapping:
+ *   bg-background/overlay -> opacity-overlay (backdrop)
+ *   bg-card              -> colors.card (modal bg)
+ *   border-border        -> colors.border
+ *   z-modal              -> zIndex.modal (70)
+ *   z-overlay            -> zIndex.overlay (60)
+ *   duration-default     -> transition.duration.default
+ *
+ * Issue #2628 — B-2: Modal Dialog + Drawer
+ * Authored by Caqophony
+ */
+
+interface ModalDialogProps extends React.HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onClose?: () => void;
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+}
+declare const ModalDialog: React.ForwardRefExoticComponent<ModalDialogProps & React.RefAttributes<HTMLDivElement>>;
+declare const ModalHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const ModalBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const ModalFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Drawer Component
+ *
+ * Slide-over panel from left, right, or bottom edges.
+ *
+ * Token mapping:
+ *   bg-background/overlay -> opacity-overlay (backdrop)
+ *   bg-card              -> colors.card (drawer bg)
+ *   border-border        -> colors.border
+ *   z-modal              -> zIndex.modal (70)
+ *   duration-drawer      -> transition.duration.drawer (500ms)
+ *
+ * Issue #2628 — B-2: Modal Dialog + Drawer
+ * Authored by Caqophony
+ */
+
+interface DrawerProps extends React.HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onClose?: () => void;
+    side?: 'left' | 'right' | 'bottom';
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const Drawer: React.ForwardRefExoticComponent<DrawerProps & React.RefAttributes<HTMLDivElement>>;
+declare const DrawerHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const DrawerBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const DrawerFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * FormLayout Component
+ *
+ * Responsive form section layout: stacked, inline, or two-column.
+ *
+ * Token mapping: border-border -> colors.border (section dividers)
+ *
+ * Issue #2633 — B-7: Advanced Form Family
+ * Authored by Caqophony
+ */
+
+interface FormLayoutProps extends React.FormHTMLAttributes<HTMLFormElement> {
+    layout?: 'stacked' | 'inline' | 'two-column';
+}
+declare const FormLayout: React.ForwardRefExoticComponent<FormLayoutProps & React.RefAttributes<HTMLFormElement>>;
+interface FormLayoutSectionProps extends React.HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    description?: string;
+}
+declare const FormLayoutSection: React.ForwardRefExoticComponent<FormLayoutSectionProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * InputGroup Component
+ *
+ * Input with prefix/suffix addons (text, icon, or button).
+ *
+ * Token mapping:
+ *   bg-muted      -> colors.muted     (addon background)
+ *   border-input  -> colors.border    (input border)
+ *   text-muted-fg -> colors.mutedFg   (addon text)
+ *
+ * Issue #2633 — B-7: Advanced Form Family
+ * Authored by Caqophony
+ */
+
+interface InputGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    addon?: 'prefix' | 'suffix' | 'both';
+    addonContent?: React.ReactNode;
+    suffixContent?: React.ReactNode;
+}
+declare const InputGroup: React.ForwardRefExoticComponent<InputGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * RadioGroup Component
+ *
+ * Radio selection with simple, card, and stacked visual variants.
+ *
+ * Token mapping:
+ *   bg-card       -> colors.card       (card variant bg)
+ *   border-border -> colors.border     (card border)
+ *   border-primary -> colors.primary   (selected card border)
+ *   text-foreground -> colors.foreground (label)
+ *   text-muted-fg -> colors.mutedFg    (description)
+ *
+ * Issue #2633 — B-7: Advanced Form Family
+ * Authored by Caqophony
+ */
+
+interface RadioGroupOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLFieldSetElement>, 'onChange'> {
+    options: RadioGroupOption[];
+    value?: string;
+    onChange?: (value: string) => void;
+    variant?: 'simple' | 'card' | 'stacked';
+    name?: string;
+    label?: string;
+}
+declare const RadioGroup: React.ForwardRefExoticComponent<RadioGroupProps & React.RefAttributes<HTMLFieldSetElement>>;
+
+/**
+ * Combobox Component
+ *
+ * Searchable dropdown with filtering and multi-select support.
+ *
+ * Token mapping:
+ *   bg-card        -> colors.card        (dropdown bg)
+ *   bg-muted       -> colors.muted       (hover item)
+ *   border-input   -> colors.border      (input border)
+ *   text-foreground -> colors.foreground  (option text)
+ *   text-muted-fg  -> colors.mutedFg     (placeholder)
+ *   bg-primary     -> colors.primary     (selected tag)
+ *
+ * Issue #2633 — B-7: Advanced Form Family
+ * Authored by Caqophony
+ */
+
+interface ComboboxOption {
+    value: string;
+    label: string;
+}
+interface ComboboxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    options: ComboboxOption[];
+    value?: string | string[];
+    onChange?: (value: string | string[]) => void;
+    placeholder?: string;
+    multi?: boolean;
+    filterable?: boolean;
+}
+declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * NotificationBanner Component
+ *
+ * Inline notification banners with 4 intents and dismiss animation.
+ *
+ * Token mapping:
+ *   bg-intent-[intent]/10  -> solidFillAlpha(intent, 0.1)
+ *   text-intent-[intent]-fg -> intent foreground colors
+ *   border-intent-[intent]/20 -> solidFillAlpha(intent, 0.2)
+ *
+ * Usage:
+ *   import { NotificationBanner } from '@caqophony/ui';
+ *   <NotificationBanner intent="success" dismissible>
+ *     Your changes have been saved.
+ *   </NotificationBanner>
+ *
+ * Issue #2632 — B-6: Notification Panel + Banner
+ * Authored by Caqophony
+ */
+
+interface NotificationBannerProps extends React.HTMLAttributes<HTMLDivElement> {
+    intent?: 'success' | 'warning' | 'error' | 'info';
+    variant?: 'subtle' | 'solid' | 'accent';
+    title?: string;
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    action?: React.ReactNode;
+}
+declare const NotificationBanner: React.ForwardRefExoticComponent<NotificationBannerProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * NotificationPanel Component
+ *
+ * Dropdown notification list triggered from a bell icon.
+ * Renders a list of notification items with unread badge and mark-all-read.
+ *
+ * Token mapping:
+ *   bg-card       → colors.card       (panel bg)
+ *   border-border → colors.border     (panel border, dividers)
+ *   text-primary  → colors.primary    (unread indicator)
+ *   text-muted-fg → colors.mutedFg    (timestamps)
+ *
+ * Usage:
+ *   import { NotificationPanel, NotificationPanelItem } from '@caqophony/ui';
+ *   <NotificationPanel unreadCount={3} onMarkAllRead={handleMarkAll}>
+ *     <NotificationPanelItem title="New comment" time="2m ago" unread />
+ *   </NotificationPanel>
+ *
+ * Issue #2632 — B-6: Notification Panel + Banner
+ * Authored by Caqophony
+ */
+
+interface NotificationPanelProps extends React.HTMLAttributes<HTMLDivElement> {
+    unreadCount?: number;
+    onMarkAllRead?: () => void;
+}
+declare const NotificationPanel: React.ForwardRefExoticComponent<NotificationPanelProps & React.RefAttributes<HTMLDivElement>>;
+interface NotificationPanelItemProps extends React.HTMLAttributes<HTMLDivElement> {
+    title: string;
+    description?: string;
+    time?: string;
+    unread?: boolean;
+    icon?: React.ReactNode;
+}
+declare const NotificationPanelItem: React.ForwardRefExoticComponent<NotificationPanelItemProps & React.RefAttributes<HTMLDivElement>>;
+
+interface SkeletonTableProps extends React.HTMLAttributes<HTMLDivElement> {
+    rows?: number;
+    columns?: number;
+}
+declare function SkeletonTable({ className, rows, columns, ...props }: SkeletonTableProps): react_jsx_runtime.JSX.Element;
+declare namespace SkeletonTable {
+    var displayName: string;
+}
+interface SkeletonCardGridProps extends React.HTMLAttributes<HTMLDivElement> {
+    cards?: number;
+    columns?: 2 | 3;
+}
+declare function SkeletonCardGrid({ className, cards, columns, ...props }: SkeletonCardGridProps): react_jsx_runtime.JSX.Element;
+declare namespace SkeletonCardGrid {
+    var displayName: string;
+}
+interface SkeletonDetailProps extends React.HTMLAttributes<HTMLDivElement> {
+}
+declare function SkeletonDetail({ className, ...props }: SkeletonDetailProps): react_jsx_runtime.JSX.Element;
+declare namespace SkeletonDetail {
+    var displayName: string;
+}
+
+/**
+ * Toggle + ToggleGroup Components
+ *
+ * Icon toggles and view-mode selectors (grid/list/table).
+ * Beyond Switch: pressed/unpressed visual state with icon support.
+ *
+ * Token mapping:
+ *   bg-muted      → colors.muted       (group container, active toggle)
+ *   bg-transparent → transparent         (inactive toggle)
+ *   text-foreground → colors.foreground  (active)
+ *   text-muted-fg  → colors.mutedFg     (inactive)
+ *   border-input   → colors.border      (outline variant)
+ *
+ * Usage:
+ *   import { Toggle, ToggleGroup } from '@caqophony/ui';
+ *   <ToggleGroup type="single" value={view} onValueChange={setView}>
+ *     <Toggle value="grid" aria-label="Grid view">Grid</Toggle>
+ *     <Toggle value="list" aria-label="List view">List</Toggle>
+ *   </ToggleGroup>
+ *
+ * Issue #2650 — B-18: Toggle + Toggle Group
+ * Authored by Caqophony
+ */
+
+interface ToggleProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    pressed?: boolean;
+    variant?: 'default' | 'outline';
+    size?: 'sm' | 'md' | 'lg';
+    value?: string;
+}
+declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLButtonElement>>;
+interface ToggleGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    type?: 'single' | 'multiple';
+    value?: string | string[];
+    onValueChange?: (value: string | string[]) => void;
+    variant?: 'default' | 'outline';
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const ToggleGroup: React.ForwardRefExoticComponent<ToggleGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * AvatarGroup Component
+ *
+ * Overlapping avatar circles with +N overflow indicator.
+ * Common for team displays, assignee fields, and user lists.
+ *
+ * Token mapping:
+ *   bg-muted         → colors.muted          (avatar placeholder bg)
+ *   border-background → colors.background     (ring around each avatar)
+ *   text-muted-fg    → colors.mutedFg         (overflow text)
+ *
+ * Usage:
+ *   import { AvatarGroup, AvatarGroupItem } from '@caqophony/ui';
+ *   <AvatarGroup max={3}>
+ *     <AvatarGroupItem src="/user1.jpg" alt="Jane" />
+ *     <AvatarGroupItem src="/user2.jpg" alt="John" />
+ *     <AvatarGroupItem src="/user3.jpg" alt="Sarah" />
+ *     <AvatarGroupItem src="/user4.jpg" alt="Mike" />
+ *   </AvatarGroup>
+ *
+ * Issue #2639 — B-12: Avatar Groups + Badge Extensions
+ * Authored by Caqophony
+ */
+
+interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    max?: number;
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+}
+declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;
+interface AvatarGroupItemProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+    fallback?: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+}
+declare const AvatarGroupItem: React.ForwardRefExoticComponent<AvatarGroupItemProps & React.RefAttributes<HTMLImageElement>>;
+
+/**
+ * TabBar Component
+ *
+ * Tabbed navigation with underline, pills, and enclosed visual variants.
+ *
+ * Token mapping (React ↔ Figma):
+ *   bg-muted         → colors.muted          (pills container bg)
+ *   text-foreground   → colors.foreground      (active tab text)
+ *   text-muted-fg     → colors.mutedFg         (inactive tab text)
+ *   border-primary    → colors.primary         (underline indicator)
+ *   bg-background     → colors.background      (active pill bg)
+ *
+ * Usage:
+ *   import { TabBar, TabBarItem } from '@caqophony/ui';
+ *   <TabBar variant="underline">
+ *     <TabBarItem active>Overview</TabBarItem>
+ *     <TabBarItem>Settings</TabBarItem>
+ *   </TabBar>
+ *
+ * Issue #2637 — B-11: Breadcrumb + Tab Extensions
+ * Authored by Caqophony
+ */
+
+interface TabBarProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: 'underline' | 'pills' | 'enclosed';
+}
+declare const TabBar: React.ForwardRefExoticComponent<TabBarProps & React.RefAttributes<HTMLDivElement>>;
+interface TabBarItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    active?: boolean;
+    /** @internal injected by TabBar */
+    _variant?: 'underline' | 'pills' | 'enclosed';
+}
+declare const TabBarItem: React.ForwardRefExoticComponent<TabBarItemProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface StickyActionBarProps {
+    /** Left slot — page title, status/verdict pill, a short summary. */
+    context?: ReactNode;
+    /** Right slot — the action button(s). The primary is the visually dominant. */
+    actions: ReactNode;
+    /** Sticky top offset — defaults to `top-16` (below the app header). */
+    topClassName?: string;
+    /** Extra classes on the sticky wrapper. */
+    className?: string;
+    /** testid for the bar (defaults to sticky-action-bar). */
+    testId?: string;
+}
+declare function StickyActionBar({ context, actions, topClassName, className, testId, }: StickyActionBarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ButtonGroup Component
+ *
+ * Segmented controls, toggle groups, and split buttons.
+ * Connected borders between buttons (no double borders).
+ *
+ * Usage:
+ *   import { ButtonGroup, ButtonGroupItem } from '@caqophony/ui';
+ *   <ButtonGroup variant="segmented">
+ *     <ButtonGroupItem active>Grid</ButtonGroupItem>
+ *     <ButtonGroupItem>List</ButtonGroupItem>
+ *     <ButtonGroupItem>Table</ButtonGroupItem>
+ *   </ButtonGroup>
+ *
+ * Issue #2642 — B-15: Button Groups
+ * Authored by Caqophony
+ */
+
+interface ButtonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: 'default' | 'outlined' | 'segmented';
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const ButtonGroup: React.ForwardRefExoticComponent<ButtonGroupProps & React.RefAttributes<HTMLDivElement>>;
+interface ButtonGroupItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    active?: boolean;
+    /** @internal injected by ButtonGroup */
+    _variant?: 'default' | 'outlined' | 'segmented';
+    /** @internal injected by ButtonGroup */
+    _size?: 'sm' | 'md' | 'lg';
+}
+declare const ButtonGroupItem: React.ForwardRefExoticComponent<ButtonGroupItemProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * DataTable Component
+ *
+ * Sortable, selectable data table with density variants.
+ * The highest-reuse component across SaaS — every generated app needs one.
+ *
+ * Token mapping (React ↔ Figma):
+ *   bg-card          → colors.card          (table background)
+ *   border-border    → colors.border        (cell borders)
+ *   text-foreground  → colors.foreground     (cell text)
+ *   text-muted-fg    → colors.mutedFg        (header text)
+ *   bg-muted         → colors.muted          (striped rows, header bg)
+ *   bg-primary       → colors.primary        (selected row indicator)
+ *
+ * Usage:
+ *   import { DataTable, TableHeader, TableRow, TableCell } from '@caqophony/ui';
+ *   <DataTable density="default" striped bordered>
+ *     <TableHeader>
+ *       <TableRow>
+ *         <TableCell header sortDirection="asc">Name</TableCell>
+ *         <TableCell header>Email</TableCell>
+ *       </TableRow>
+ *     </TableHeader>
+ *     <tbody>
+ *       <TableRow>
+ *         <TableCell>Jane Cooper</TableCell>
+ *         <TableCell>jane@example.com</TableCell>
+ *       </TableRow>
+ *     </tbody>
+ *   </DataTable>
+ *
+ * Issue #2627 — B-1: DataTable + TableHeader + TableRow + TableCell
+ * Authored by Caqophony
+ */
+
+interface DataTableProps extends React.TableHTMLAttributes<HTMLTableElement> {
+    density?: 'compact' | 'default' | 'relaxed';
+    striped?: boolean;
+    bordered?: boolean;
+}
+declare const DataTable: React.ForwardRefExoticComponent<DataTableProps & React.RefAttributes<HTMLTableElement>>;
+declare const TableHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
+declare const TableBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
+interface TableRowProps extends React.HTMLAttributes<HTMLTableRowElement> {
+    selected?: boolean;
+}
+declare const TableRow: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
+interface TableCellProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
+    header?: boolean;
+    sortDirection?: 'asc' | 'desc' | null;
+    onSort?: () => void;
+}
+declare const TableCell: React.ForwardRefExoticComponent<TableCellProps & React.RefAttributes<HTMLTableCellElement>>;
+declare const TableCaption: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableCaptionElement> & React.RefAttributes<HTMLTableCaptionElement>>;
+
+/**
+ * StatGroup Component
+ *
+ * Responsive grid of stat cards for dashboards. Composes with StatCard atoms.
+ *
+ * Token mapping: bg-card → colors.card, border-border → colors.border
+ *
+ * Usage:
+ *   import { StatGroup } from '@caqophony/ui';
+ *   <StatGroup columns={3} variant="card">
+ *     <div>Stat 1</div><div>Stat 2</div><div>Stat 3</div>
+ *   </StatGroup>
+ *
+ * Issue #2635 — B-9
+ * Authored by Caqophony
+ */
+
+interface StatGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    columns?: 2 | 3 | 4;
+    variant?: 'card' | 'inline';
+}
+declare const StatGroup: React.ForwardRefExoticComponent<StatGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * DescriptionList Component
+ *
+ * Key-value pairs for detail pages, settings views, and entity summaries.
+ *
+ * Token mapping:
+ *   text-muted-foreground → colors.mutedFg (labels)
+ *   text-foreground       → colors.foreground (values)
+ *   border-border         → colors.border (dividers)
+ *
+ * Usage:
+ *   import { DescriptionList, DescriptionItem } from '@caqophony/ui';
+ *   <DescriptionList layout="side-by-side">
+ *     <DescriptionItem label="Name" value="Jane Cooper" />
+ *     <DescriptionItem label="Email" value="jane@example.com" />
+ *   </DescriptionList>
+ *
+ * Issue #2635 — B-9
+ * Authored by Caqophony
+ */
+
+interface DescriptionListProps extends React.HTMLAttributes<HTMLDListElement> {
+    layout?: 'stacked' | 'side-by-side' | 'grid';
+}
+declare const DescriptionList: React.ForwardRefExoticComponent<DescriptionListProps & React.RefAttributes<HTMLDListElement>>;
+interface DescriptionItemProps extends React.HTMLAttributes<HTMLDivElement> {
+    label: string;
+    value: React.ReactNode;
+    layout?: 'stacked' | 'side-by-side' | 'grid';
+}
+declare const DescriptionItem: React.ForwardRefExoticComponent<DescriptionItemProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ActivityFeed Component
+ *
+ * Vertical timeline of events with avatar, content, and timestamp.
+ *
+ * Token mapping:
+ *   bg-primary    → colors.primary     (timeline connector)
+ *   bg-muted      → colors.muted       (inactive connector)
+ *   text-foreground → colors.foreground (content)
+ *   text-muted-foreground → colors.mutedFg (timestamp)
+ *
+ * Usage:
+ *   import { ActivityFeed, ActivityFeedItem } from '@caqophony/ui';
+ *   <ActivityFeed>
+ *     <ActivityFeedItem
+ *       avatar={<Avatar />}
+ *       eventDescription="Jane created a new project"
+ *       timestamp="2 hours ago"
+ *     />
+ *   </ActivityFeed>
+ *
+ * Issue #2635 — B-9
+ * Authored by Caqophony
+ */
+
+interface ActivityFeedProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: 'simple' | 'withComments';
+}
+declare const ActivityFeed: React.ForwardRefExoticComponent<ActivityFeedProps & React.RefAttributes<HTMLDivElement>>;
+interface ActivityFeedItemProps extends React.HTMLAttributes<HTMLDivElement> {
+    avatar?: React.ReactNode;
+    eventDescription: React.ReactNode;
+    timestamp?: string;
+    isLast?: boolean;
+}
+declare const ActivityFeedItem: React.ForwardRefExoticComponent<ActivityFeedItemProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Alert Component
+ *
+ * Contextual feedback messages with 4 intents × 3 visual variants.
+ *
+ * Token mapping (React ↔ Figma):
+ *   bg-intent-success/10  → solidFillAlpha(colors.success, 0.1)  [subtle]
+ *   bg-intent-success     → colors.success                        [solid]
+ *   border-intent-success → solidFill(intentSuccessBorder)        [outline]
+ *   text-intent-success   → colors.success                        [icon/title]
+ *
+ * Usage:
+ *   import { Alert } from '@caqophony/ui';
+ *   <Alert intent="error" variant="subtle" title="Error" dismissible>
+ *     Something went wrong.
+ *   </Alert>
+ *
+ * Issue #2636 — B-10: Action Panels + Alert Component
+ * Authored by Caqophony
+ */
+
+interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+    intent?: 'success' | 'warning' | 'error' | 'info';
+    variant?: 'subtle' | 'solid' | 'outline';
+    title?: string;
+    dismissible?: boolean;
+    onDismiss?: () => void;
+}
+declare const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
+
+interface EmptyStateProps {
+    /**
+     * Lucide icon shown in the circular badge above the title. Optional — when
+     * omitted the badge is hidden and the title leads.
+     */
+    icon?: LucideIcon;
+    /** Short headline, e.g. "No projects yet". */
+    title: string;
+    /**
+     * Body copy: explain what will populate this space and what to do next,
+     * e.g. "Items you create will appear here." Keep to ~2 lines.
+     */
+    description?: React.ReactNode;
+    /**
+     * Primary call-to-action node (a Button, a Link-wrapped Button, etc.). The
+     * page owns routing/handlers; this slot just places it. Optional — some
+     * empty states (e.g. "all clear") are informational with no action.
+     */
+    action?: React.ReactNode;
+    /**
+     * Visual size. `default` is the full-page/section empty state; `compact`
+     * fits inside a card or sidebar panel (smaller badge + padding).
+     */
+    size?: 'default' | 'compact';
+    /** Override the test id (defaults to the rubric-mandated "empty-state"). */
+    testId?: string;
+    className?: string;
+}
+/**
+ * EmptyState
+ *
+ * The shared empty-state block. A list / grid / feed page renders this when it
+ * has no data: an icon badge, a headline, body copy and a contextual
+ * call-to-action, with `data-testid="empty-state"`. Gossamer semantic tokens
+ * only.
+ *
+ * @example
+ * <EmptyState
+ *   icon={Rocket}
+ *   title="No projects yet"
+ *   description="Describe what you want to build and your AI team takes it from there."
+ *   action={<Button asChild><Link href="/projects/new">Create project</Link></Button>}
+ * />
+ *
+ * Authored by Caqophony
+ */
+declare function EmptyState({ icon: Icon, title, description, action, size, testId, className, }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ActionPanel Component
+ *
+ * Settings-style section with title, description, and action button.
+ * Used for confirmation blocks, settings sections, and CTA panels.
+ *
+ * Token mapping (React ↔ Figma):
+ *   bg-card           → colors.card          (panel background)
+ *   border-border     → colors.border        (panel border)
+ *   text-foreground   → colors.foreground     (title)
+ *   text-muted-fg     → colors.mutedFg        (description)
+ *   border-intent-*   → colors[intent]        (withBorder left accent)
+ *
+ * Usage:
+ *   import { ActionPanel } from '@caqophony/ui';
+ *   <ActionPanel
+ *     title="Delete project"
+ *     description="This action cannot be undone."
+ *     intent="destructive"
+ *     action={<Button variant="destructive">Delete</Button>}
+ *   />
+ *
+ * Issue #2636 — B-10: Action Panels + Alert Component
+ * Authored by Caqophony
+ */
+
+interface ActionPanelProps extends React.HTMLAttributes<HTMLDivElement> {
+    title: string;
+    description?: string;
+    action?: React.ReactNode;
+    variant?: 'simple' | 'split' | 'withBorder';
+    intent?: 'default' | 'warning' | 'destructive';
+}
+declare const ActionPanel: React.ForwardRefExoticComponent<ActionPanelProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Divider Component
+ *
+ * Section separator with optional label. Supports solid/dashed/dotted styles.
+ *
+ * Usage:
+ *   import { Divider } from '@caqophony/ui';
+ *   <Divider />
+ *   <Divider label="Or continue with" />
+ *   <Divider label="Section" labelPosition="left" variant="dashed" />
+ *
+ * Issue #2641 — B-14: Dividers + Containers + Media Objects
+ * Authored by Caqophony
+ */
+
+interface DividerProps extends React.HTMLAttributes<HTMLDivElement> {
+    label?: string;
+    labelPosition?: 'left' | 'center' | 'right';
+    variant?: 'solid' | 'dashed' | 'dotted';
+    orientation?: 'horizontal' | 'vertical';
+}
+declare const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Container Component
+ *
+ * Max-width content wrapper with responsive padding.
+ * Centers content and constrains width for readability.
+ *
+ * Usage:
+ *   import { Container } from '@caqophony/ui';
+ *   <Container size="lg" padded>
+ *     <h1>Page Content</h1>
+ *   </Container>
+ *
+ * Issue #2641 — B-14: Dividers + Containers + Media Objects
+ * Authored by Caqophony
+ */
+
+interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    padded?: boolean;
+}
+declare const Container: React.ForwardRefExoticComponent<ContainerProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * PageContent — Standard page-level content wrapper.
+ *
+ * Provides consistent vertical padding and spacing for page content
+ * rendered inside app shells (ProjectNavShell, SetupWizardShell, etc.).
+ *
+ * The shell provides the structural frame (sidebar, header, breadcrumb).
+ * PageContent provides the content padding every page needs.
+ *
+ * Usage:
+ *   import { PageContent } from '@caqophony/ui';
+ *   <PageContent>
+ *     <HeroSection />
+ *     <DataGrid />
+ *   </PageContent>
+ *
+ * Authored by Caqophony
+ */
+
+interface PageContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Vertical gap between direct children. Default: 'md' (space-y-6) */
+    gap?: 'sm' | 'md' | 'lg' | 'none';
+    /** Whether to include page-level padding. Default: true */
+    padded?: boolean;
+}
+declare const PageContent: React.ForwardRefExoticComponent<PageContentProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * MediaObject Component
+ *
+ * Horizontal layout with media (icon/image/avatar) + content + optional action.
+ * Common pattern for comments, chat messages, notifications, and list items.
+ *
+ * Usage:
+ *   import { MediaObject } from '@caqophony/ui';
+ *   <MediaObject
+ *     media={<Avatar src={user.avatar} />}
+ *     title="John Doe"
+ *     description="Left a comment on your post"
+ *     action={<Button size="sm">Reply</Button>}
+ *   />
+ *
+ * Issue #2641 — B-14: Dividers + Containers + Media Objects
+ * Authored by Caqophony
+ */
+
+interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
+    media: React.ReactNode;
+    title?: string;
+    description?: string;
+    action?: React.ReactNode;
+    align?: 'top' | 'center';
+    mediaSize?: 'sm' | 'md' | 'lg';
+    stacked?: boolean;
+}
+declare const MediaObject: React.ForwardRefExoticComponent<MediaObjectProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * UI Package Utilities
+ *
+ * Provides cn utility for consistent class name merging
+ *
+ * Authored by Caqophony
+ */
+
+/**
+ * Merges class names with Tailwind CSS conflict resolution
+ * Combines clsx for conditional classes with tailwind-merge for deduplication
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+declare function useDebounce<T>(value: T, ms: number): T;
+
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, ActionCard, type ActionCardProps, ActionPanel, type ActionPanelProps, ActivityFeed, ActivityFeedItem, type ActivityFeedItemProps, type ActivityFeedProps, Alert, type AlertProps, AppShell, type AppShellProps, AvatarGroup, AvatarGroupItem, type AvatarGroupItemProps, type AvatarGroupProps, Button, ButtonGroup, ButtonGroupItem, type ButtonGroupItemProps, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarEvent, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CollapsibleSidebar, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteProps, type CommandPaletteResult, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, DataTable, type DataTableProps, DatePicker, type DatePickerProps, DescriptionItem, type DescriptionItemProps, DescriptionList, type DescriptionListProps, DiceBearAvatar, type DiceBearAvatarProps, type DiceBearStyle, DistributionChip, type DistributionChipProps, Divider, type DividerProps, Drawer, DrawerBody, DrawerFooter, DrawerHeader, type DrawerProps, EmptyState, type EmptyStateProps, FilterChip, type FilterChipProps, FormError, type FormErrorProps, FormField, FormFieldGroup, type FormFieldGroupProps, type FormFieldProps, FormLayout, type FormLayoutProps, FormLayoutSection, type FormLayoutSectionProps, FormSection, type FormSectionProps, FormSuccess, type FormSuccessProps, GlobalErrorContent, type GlobalErrorContentProps, GridList, GridListItem, type GridListItemProps, type GridListProps, HorizontalCard, type HorizontalCardProps, HoverCard, type HoverCardProps, ImageCard, type ImageCardProps, Input, InputGroup, type InputGroupProps, type InputProps, IntentIcon, type IntentIconProps, MediaObject, type MediaObjectProps, ModalBody, ModalDialog, type ModalDialogProps, ModalFooter, ModalHeader, type NavItem, Navbar, NavbarLink, type NavbarLinkProps, type NavbarProps, NotificationBanner, type NotificationBannerProps, NotificationPanel, NotificationPanelItem, type NotificationPanelItemProps, type NotificationPanelProps, PageContent, type PageContentProps, Pagination, PaginationButton, type PaginationProps, Popover, type PopoverProps, RadioGroup, type RadioGroupOption, type RadioGroupProps, SectionHeading, type SectionHeadingProps, type NavItem as SidebarNavItem, SimpleAccordion, SkeletonBar, type SkeletonBarProps, SkeletonCard, SkeletonCardGrid, type SkeletonCardGridProps, type SkeletonCardProps, SkeletonDetail, type SkeletonDetailProps, SkeletonRow, type SkeletonRowProps, SkeletonTable, type SkeletonTableProps, StackedList, StackedListItem, type StackedListItemProps, type StackedListProps, StatCardExtended, type StatCardExtendedProps, StatGroup, type StatGroupProps, Stepper, type StepperProps, StepperStep, type StepperStepProps, StickyActionBar, type StickyActionBarProps, Switch, type SwitchProps, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TableBody, TableCaption, TableCell, type TableCellProps, TableHeader, TableRow, type TableRowProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, avatarVariants, buildDiceBearUrl, buttonVariants, cn, getPageRange, useDebounce, useSidebar };