@dimaan/ui 0.0.9 → 0.0.11

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { HTMLAttributes, ReactNode, ReactElement, ButtonHTMLAttributes, InputHTMLAttributes, ChangeEvent, FieldsetHTMLAttributes, AnchorHTMLAttributes, Ref, TextareaHTMLAttributes } from 'react';
+import { HTMLAttributes, ReactNode, ReactElement, ButtonHTMLAttributes, InputHTMLAttributes, ChangeEvent, ComponentPropsWithoutRef, FieldsetHTMLAttributes, Ref, AnchorHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import * as RadixDropdown from '@radix-ui/react-dropdown-menu';
 import { FieldValues, FieldPath, Control } from 'react-hook-form';
+import * as RadixRadioGroup from '@radix-ui/react-radio-group';
 import { ClassValue } from 'clsx';
 
 interface DashboardLayoutContextValue {
@@ -131,6 +133,43 @@ interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
 }
 declare function Avatar({ src, alt, fallback, size, className, ...props }: AvatarProps): react_jsx_runtime.JSX.Element;
 
+type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'outline';
+type BadgeSize = 'sm' | 'md';
+declare const badgeVariantClass: Record<BadgeVariant, string>;
+declare const badgeSizeClass: Record<BadgeSize, string>;
+/** The dot-indicator size for each badge size. */
+declare const badgeDotSizeClass: Record<BadgeSize, string>;
+declare const badgeBaseClass = "inline-flex shrink-0 items-center rounded-full border font-medium leading-none whitespace-nowrap select-none transition-colors";
+
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** Render a small dot before the label (useful for online/status indicators). */
+    dot?: boolean;
+}
+/**
+ * Inline status pill. Most common use: status column in a table (Active /
+ * Pending / Archived), category labels, or counts in nav items.
+ *
+ * @example Status pill in a table cell
+ * ```tsx
+ * <Badge variant="success">Active</Badge>
+ * <Badge variant="warning">Pending</Badge>
+ * <Badge variant="default">Archived</Badge>
+ * ```
+ *
+ * @example With status dot
+ * ```tsx
+ * <Badge variant="success" dot>Online</Badge>
+ * ```
+ *
+ * @example Outline (border-only, no fill)
+ * ```tsx
+ * <Badge variant="outline">Beta</Badge>
+ * ```
+ */
+declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
+
 type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'success' | 'warning' | 'link';
 type ButtonSize = 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
 declare const buttonVariantClass: Record<ButtonVariant, string>;
@@ -193,6 +232,153 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'typ
 }
 declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
 
+type DropdownMenuItemVariant = 'default' | 'destructive';
+declare const dropdownMenuContentClass = "z-50 min-w-32 overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95";
+declare const dropdownMenuItemBaseClass = "relative flex w-full cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0";
+declare const dropdownMenuItemVariantClass: Record<DropdownMenuItemVariant, string>;
+/** Indent items without an icon so they align with items that have one. */
+declare const dropdownMenuItemInsetClass = "ps-8";
+declare const dropdownMenuSeparatorClass = "-mx-1 my-1 h-px bg-border";
+declare const dropdownMenuLabelClass = "px-2 py-1.5 text-xs font-semibold text-muted-foreground select-none";
+declare const dropdownMenuShortcutClass = "ms-auto text-xs tracking-widest text-muted-foreground";
+
+/**
+ * Compound dropdown menu built on `@radix-ui/react-dropdown-menu`. Use for
+ * row actions (⋯ menu in tables), header overflow menus, user avatar menus.
+ *
+ * @example Row actions in a table
+ * ```tsx
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <Button variant="ghost" size="icon" aria-label="More actions">
+ *       <MoreHorizontal />
+ *     </Button>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent align="end">
+ *     <DropdownMenuItem onSelect={() => edit(row)}>
+ *       <Pencil />
+ *       Edit
+ *     </DropdownMenuItem>
+ *     <DropdownMenuItem onSelect={() => archive(row)}>
+ *       <Archive />
+ *       Archive
+ *     </DropdownMenuItem>
+ *     <DropdownMenuSeparator />
+ *     <DropdownMenuItem variant="destructive" onSelect={() => del(row)}>
+ *       <Trash2 />
+ *       Delete
+ *     </DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ *
+ * @example With label, group, and keyboard shortcut
+ * ```tsx
+ * <DropdownMenu>
+ *   <DropdownMenuTrigger asChild>
+ *     <Button variant="outline">Options</Button>
+ *   </DropdownMenuTrigger>
+ *   <DropdownMenuContent>
+ *     <DropdownMenuLabel>My account</DropdownMenuLabel>
+ *     <DropdownMenuItem>
+ *       Profile
+ *       <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
+ *     </DropdownMenuItem>
+ *     <DropdownMenuItem>
+ *       Settings
+ *       <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
+ *     </DropdownMenuItem>
+ *   </DropdownMenuContent>
+ * </DropdownMenu>
+ * ```
+ */
+declare const DropdownMenu: react.FC<RadixDropdown.DropdownMenuProps>;
+declare const DropdownMenuTrigger: react.ForwardRefExoticComponent<RadixDropdown.DropdownMenuTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const DropdownMenuGroup: react.ForwardRefExoticComponent<RadixDropdown.DropdownMenuGroupProps & react.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuPortal: react.FC<RadixDropdown.DropdownMenuPortalProps>;
+interface DropdownMenuContentProps extends ComponentPropsWithoutRef<typeof RadixDropdown.Content> {
+}
+declare const DropdownMenuContent: react.ForwardRefExoticComponent<DropdownMenuContentProps & react.RefAttributes<HTMLDivElement>>;
+interface DropdownMenuItemProps extends ComponentPropsWithoutRef<typeof RadixDropdown.Item> {
+    variant?: DropdownMenuItemVariant;
+    /** Indent items without a leading icon so they align with iconed siblings. */
+    inset?: boolean;
+}
+declare const DropdownMenuItem: react.ForwardRefExoticComponent<DropdownMenuItemProps & react.RefAttributes<HTMLDivElement>>;
+interface DropdownMenuSeparatorProps extends ComponentPropsWithoutRef<typeof RadixDropdown.Separator> {
+}
+declare const DropdownMenuSeparator: react.ForwardRefExoticComponent<DropdownMenuSeparatorProps & react.RefAttributes<HTMLDivElement>>;
+interface DropdownMenuLabelProps extends ComponentPropsWithoutRef<typeof RadixDropdown.Label> {
+    /** Indent to align with iconed items. */
+    inset?: boolean;
+}
+declare const DropdownMenuLabel: react.ForwardRefExoticComponent<DropdownMenuLabelProps & react.RefAttributes<HTMLDivElement>>;
+/**
+ * Visual hint for a keyboard shortcut, rendered at the trailing edge of an
+ * item. Pure presentation — does **not** register a keyboard handler.
+ */
+interface DropdownMenuShortcutProps extends HTMLAttributes<HTMLSpanElement> {
+    children: ReactNode;
+}
+declare const DropdownMenuShortcut: react.ForwardRefExoticComponent<DropdownMenuShortcutProps & react.RefAttributes<HTMLSpanElement>>;
+
+type EmptyStateSize = 'sm' | 'md' | 'lg';
+declare const emptyStateContainerSizeClass: Record<EmptyStateSize, string>;
+declare const emptyStateIconWrapperSizeClass: Record<EmptyStateSize, string>;
+declare const emptyStateTitleSizeClass: Record<EmptyStateSize, string>;
+declare const emptyStateDescriptionSizeClass: Record<EmptyStateSize, string>;
+declare const emptyStateActionsSpacingClass: Record<EmptyStateSize, string>;
+declare const emptyStateBaseClass = "flex flex-col items-center justify-center text-center px-4";
+declare const emptyStateIconWrapperBaseClass = "inline-flex items-center justify-center rounded-full bg-muted text-muted-foreground";
+
+interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Optional icon rendered in a circular muted background. Sized via `size` prop. */
+    icon?: ReactNode;
+    /** Required title — what's missing or what state we're in. */
+    title: ReactNode;
+    /** Secondary text — explain why the state is empty, suggest next action. */
+    description?: ReactNode;
+    /** Slot for primary (and optional secondary) action buttons. Rendered below description. */
+    action?: ReactNode;
+    /** Visual size — `sm` for inline empties (e.g. inside a popover), `md` (default) for table cells, `lg` for full-page empties. */
+    size?: EmptyStateSize;
+}
+/**
+ * Inline empty-state placeholder. Use when a list, table, or section has no
+ * data to show — either because the user hasn't created anything yet, or
+ * because filters/search returned zero results.
+ *
+ * The most common dashboard pattern: render inside a table's `tbody` colspan
+ * cell, or as a sibling to a list when the list is empty.
+ *
+ * @example No-results in a filtered table
+ * ```tsx
+ * <EmptyState
+ *   icon={<SearchX />}
+ *   title="No users match your filters"
+ *   description="Try clearing the search or changing the status filter."
+ *   action={<Button variant="outline" onClick={resetFilters}>Reset filters</Button>}
+ * />
+ * ```
+ *
+ * @example First-run empty (encourage creation)
+ * ```tsx
+ * <EmptyState
+ *   size="lg"
+ *   icon={<Users />}
+ *   title="No users yet"
+ *   description="Add your first team member to get started."
+ *   action={<Button onClick={openCreate}>Add user</Button>}
+ * />
+ * ```
+ *
+ * @example Compact (inline)
+ * ```tsx
+ * <EmptyState size="sm" title="No notifications" />
+ * ```
+ */
+declare const EmptyState: react.ForwardRefExoticComponent<EmptyStateProps & react.RefAttributes<HTMLDivElement>>;
+
 interface FieldRHFProps<TValues extends FieldValues = FieldValues, TName extends FieldPath<TValues> = FieldPath<TValues>> {
     /**
      * RHF `Control` returned from `useForm()`. Optional when `Field` is rendered
@@ -314,47 +500,45 @@ declare const inputBaseClass = "group/input relative inline-flex w-full items-ce
 interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'prefix'> {
     variant?: InputVariant;
     inputSize?: InputSize;
-    /** Optional label rendered above the field. */
-    label?: ReactNode;
-    /** Helper text rendered under the field when not in an error state. */
-    helperText?: ReactNode;
-    /** Error message — renders in destructive style and sets aria-invalid. */
-    error?: ReactNode;
     /** Element rendered before the input (icon, prefix text, etc.). */
     leadingIcon?: ReactNode;
     /** Element rendered after the input (icon, suffix text, etc.). */
     trailingIcon?: ReactNode;
-    /** Stretch the wrapper to fill the parent's inline width. Defaults to `true`. */
-    fullWidth?: boolean;
     /** Class applied to the outer wrapper that holds the icons + input. */
     wrapperClassName?: string;
-    /** Class applied to the field container (`<label>` block). */
-    containerClassName?: string;
 }
 /**
- * Text input with optional label, helper text, error message, and leading/trailing icons.
- * Works standalone (uses `label`/`helperText`/`error` props) OR wrapped inside `<Field>`
- * (id and aria-* are injected by Field via `cloneElement`).
+ * Bare text input — renders the wrapper + native `<input>` + optional leading /
+ * trailing icons. **No label/helperText/error props by design** (per ADR-007:
+ * Field owns all form layout). Wrap in `<Field label="…">` for label, helper,
+ * error rendering and full a11y wiring.
  *
- * @example Standalone with label + helper
+ * @example Inside a Field (RHF + Zod)
  * ```tsx
- * <Input label="Email" helperText="We'll never share it." type="email" />
+ * <Field name="email" label="Email" description="…" required>
+ *   <Input type="email" />
+ * </Field>
  * ```
  *
  * @example With icons
  * ```tsx
- * <Input
- *   label="Search"
- *   leadingIcon={<Search />}
- *   trailingIcon={<X onClick={clear} />}
- * />
+ * <Field label="Search">
+ *   <Input
+ *     leadingIcon={<Search />}
+ *     trailingIcon={<X onClick={clear} />}
+ *     placeholder="Type to search…"
+ *   />
+ * </Field>
  * ```
  *
- * @example Inside a Field (RHF + Zod)
+ * @example Bare in a filter bar (no Field)
  * ```tsx
- * <Field name="email" label="Email" required>
- *   <Input type="email" />
- * </Field>
+ * <Input
+ *   value={search}
+ *   onChange={(e) => setSearch(e.target.value)}
+ *   placeholder="Search…"
+ *   aria-label="Search products"
+ * />
  * ```
  */
 declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
@@ -467,6 +651,445 @@ interface SelectProps {
  */
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
 
+type TableSize = 'sm' | 'md' | 'lg';
+interface TableSizeClasses {
+    /** Applied to <tr> when needed (currently empty — present for symmetry). */
+    row: string;
+    /** Applied to <td>. */
+    cell: string;
+    /** Applied to <th>. */
+    head: string;
+}
+declare const tableSizeClass: Record<TableSize, TableSizeClasses>;
+declare const tableBaseClass = "w-full caption-bottom border-collapse";
+declare const selectedRowClass = "bg-muted/40";
+declare const sortIconClass = "inline-flex h-3 w-3 shrink-0 items-center justify-center";
+declare const alignClass: Record<ColumnAlign, string>;
+
+type SortDirection = 'asc' | 'desc';
+interface SortState {
+    /** Column id being sorted, or `null` when no sort is active. */
+    columnId: string | null;
+    direction: SortDirection;
+}
+interface PaginationState {
+    /** 0-based page index. */
+    pageIndex: number;
+    pageSize: number;
+}
+/** Set of row ids (returned from `getRowId`) that are currently selected. */
+type RowSelectionState = ReadonlySet<string>;
+type SortableValue = string | number | bigint | boolean | Date | null | undefined;
+type ColumnAlign = 'start' | 'center' | 'end';
+interface Column<T> {
+    /** Stable column id. Used for sort state and React keys. */
+    id: string;
+    /** Header label, ReactNode, or a function that returns the header content. */
+    header: ReactNode | (() => ReactNode);
+    /** Field on T to read for default rendering and default sorting. */
+    accessor?: keyof T;
+    /** Custom cell renderer. If omitted, renders `String(row[accessor] ?? '')`. */
+    render?: (row: T, rowIndex: number) => ReactNode;
+    /** Enable click-to-sort UI on the header. */
+    sortable?: boolean;
+    /** Optional override for the value used to compare during sorting. */
+    sortAccessor?: (row: T) => SortableValue;
+    /** Tailwind classes applied to both <th> and <td>. */
+    className?: string;
+    /** Inline alignment hint. Defaults to 'start'. */
+    align?: ColumnAlign;
+}
+interface TableProps<T> {
+    /** Source rows. In server-side mode, this is just the current page. */
+    data: readonly T[];
+    /** Column definitions. */
+    columns: ReadonlyArray<Column<T>>;
+    /** Stable id for each row. Required for selection; recommended always. */
+    getRowId: (row: T, index: number) => string;
+    /**
+     * Total row count across all pages. Pass this when the parent paginates/sorts
+     * server-side — Table will skip its local sort + slice.
+     */
+    totalCount?: number;
+    defaultSort?: SortState;
+    sort?: SortState;
+    onSortChange?: (next: SortState) => void;
+    defaultPagination?: PaginationState;
+    pagination?: PaginationState;
+    onPaginationChange?: (next: PaginationState) => void;
+    /** Page size dropdown options. Defaults to [10, 25, 50]. */
+    pageSizeOptions?: readonly number[];
+    /** Force the paginator to render even when rowCount <= pageSize. */
+    showPagination?: boolean;
+    /** Adds the selection column + header checkbox. */
+    enableRowSelection?: boolean;
+    defaultSelectedRowIds?: ReadonlySet<string>;
+    selectedRowIds?: ReadonlySet<string>;
+    onSelectedRowIdsChange?: (next: ReadonlySet<string>) => void;
+    /** Per-row guard. Disabled rows have a disabled checkbox and are excluded from "select all". */
+    isRowSelectable?: (row: T) => boolean;
+    /** Render prop receives the array of selected rows currently present in `data`. */
+    bulkActions?: (selectedRows: T[]) => ReactNode;
+    /** Override the "{n} selected" label (i18n / RTL). */
+    renderSelectionLabel?: (count: number) => ReactNode;
+    /** Label for the "Clear" button on the toolbar. */
+    clearSelectionLabel?: ReactNode;
+    loading?: boolean;
+    /** Number of skeleton rows shown while loading. Defaults to current pageSize. */
+    loadingRowCount?: number;
+    /** Empty-state slot. Defaults to a centered "No data" message. */
+    emptyState?: ReactNode;
+    size?: TableSize;
+    className?: string;
+    tableClassName?: string;
+    /**
+     * Constrain the scrollable region's height. Accepts any CSS length (e.g. `400`,
+     * `'24rem'`, `'60vh'`). When set, the body scrolls vertically and the header
+     * sticks to the top.
+     */
+    maxHeight?: number | string;
+    /** Stripe alternating rows. Defaults to false. */
+    striped?: boolean;
+    /** Optional row click handler. */
+    onRowClick?: (row: T, rowIndex: number) => void;
+    /** Optional ref to the underlying <table> element. */
+    tableRef?: Ref<HTMLTableElement>;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** Caption rendered as <caption className="sr-only"> for assistive tech. */
+    caption?: ReactNode;
+}
+
+declare function Table<T>(props: TableProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * One filter dropdown definition for `<ListPage>`. ListPage manages each
+ * filter's state internally — you provide options + accessor.
+ */
+interface ListPageFilter<T> {
+    /** Unique key for state tracking. */
+    key: string;
+    /** Aria-label on the Select trigger. */
+    ariaLabel?: string;
+    /** Returns the row value to match against the filter selection. */
+    accessor: (row: T) => string;
+    /** Options to choose from. The first option's value is treated as "no filter / show all". */
+    options: SelectOption[];
+    /** Override the "no filter" default. Defaults to the first option's `value`. */
+    defaultValue?: string;
+    /** Width of the Select. Defaults to `'default'` (~11rem). */
+    width?: 'narrow' | 'default' | 'wide';
+}
+interface ListPageEmptyState {
+    icon?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Override the default "Reset filters" action button. Pass `null` to hide entirely. */
+    action?: ReactNode | null;
+}
+interface ListPageLabels {
+    /** Default search input placeholder. */
+    searchPlaceholder?: string;
+    /** Default search aria-label (falls back to placeholder). */
+    searchAriaLabel?: string;
+    /** Default "Reset filters" button label. */
+    reset?: string;
+    /** Default empty-state title (when filters return zero). */
+    emptyTitle?: string;
+    /** Default empty-state description. */
+    emptyDescription?: string;
+}
+interface ListPageProps<T> {
+    title: ReactNode;
+    description?: ReactNode;
+    /** Page-header bordered separator. Defaults to `true` for list pages. */
+    bordered?: boolean;
+    /** Header action slot — primary "Add" button, etc. */
+    actions?: ReactNode;
+    data: T[];
+    columns: Column<T>[];
+    getRowId: (row: T) => string;
+    /** Keys on `T` to search. Search input only renders when this is provided. */
+    searchKeys?: Array<keyof T>;
+    filters?: ListPageFilter<T>[];
+    enableRowSelection?: boolean;
+    bulkActions?: (selected: T[]) => ReactNode;
+    emptyState?: ListPageEmptyState;
+    labels?: ListPageLabels;
+    className?: string;
+}
+/**
+ * Declarative list-page template — composes `PageHeader + search input +
+ * filter selects + Table + EmptyState` into a single configurable component.
+ *
+ * **Owns state internally** for search and filter selections — you pass raw
+ * `data` and ListPage filters it for you. For server-side data fetching or URL
+ * sync, drop down to the underlying primitives directly (see the
+ * `RecipeListPage` playground page for the manual composition pattern).
+ *
+ * @example Basic — Users list
+ * ```tsx
+ * <ListPage
+ *   title="Users"
+ *   description="Manage your team members."
+ *   actions={<Button onClick={openCreate}>Add user</Button>}
+ *   data={users}
+ *   columns={USER_COLUMNS}
+ *   getRowId={(u) => u.id}
+ *   searchKeys={['name', 'email']}
+ *   filters={[
+ *     {
+ *       key: 'status',
+ *       ariaLabel: 'Status',
+ *       accessor: (u) => u.status,
+ *       options: [
+ *         { value: 'all', label: 'All statuses' },
+ *         { value: 'active', label: 'Active' },
+ *         { value: 'invited', label: 'Invited' },
+ *       ],
+ *     },
+ *   ]}
+ *   enableRowSelection
+ *   bulkActions={(rows) => <Button variant="destructive">Delete ({rows.length})</Button>}
+ * />
+ * ```
+ *
+ * @example With localized labels
+ * ```tsx
+ * <ListPage
+ *   {...props}
+ *   labels={{
+ *     searchPlaceholder: 'ابحث…',
+ *     reset: 'إعادة الفلاتر',
+ *     emptyTitle: 'لا توجد نتائج',
+ *     emptyDescription: 'حاول مسح البحث أو تغيير الفلاتر.',
+ *   }}
+ * />
+ * ```
+ */
+declare function ListPage<T>({ title, description, bordered, actions, data, columns, getRowId, searchKeys, filters, enableRowSelection, bulkActions, emptyState, labels: labelsProp, className, }: ListPageProps<T>): react_jsx_runtime.JSX.Element;
+
+type PageHeaderHeadingLevel = 'h1' | 'h2' | 'h3' | 'h4';
+/** Props passed to the routing-library `render` slot of the back button. */
+interface PageHeaderBackRenderProps {
+    href?: string;
+    className?: string;
+    children: ReactNode;
+    onClick?: () => void;
+}
+interface PageHeaderBackProps {
+    /** Visible label next to the arrow. Defaults to `"Back"`. */
+    label?: ReactNode;
+    /** Target href — renders an `<a>`. */
+    href?: string;
+    /** Click handler — renders a `<button>` (or wraps the `render` element). */
+    onClick?: () => void;
+    /** Routing-library render prop (e.g. wrap React Router `<Link>`). Wins over `href`. */
+    render?: (props: PageHeaderBackRenderProps) => ReactElement;
+}
+interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Page title (required). */
+    title: ReactNode;
+    /** Optional secondary text under the title. */
+    description?: ReactNode;
+    /** Slot above the title for breadcrumbs (e.g. `<Breadcrumbs items={…} />` or your own JSX). */
+    breadcrumbs?: ReactNode;
+    /** Optional back button rendered above the title row. */
+    back?: PageHeaderBackProps;
+    /** Slot on the trailing side of the title row — buttons, dropdowns, etc. */
+    actions?: ReactNode;
+    /** Heading level for the title element. Defaults to `'h1'`. */
+    as?: PageHeaderHeadingLevel;
+    /** Add a bottom border separator. Default: `false`. */
+    bordered?: boolean;
+}
+/**
+ * Top-of-page header — title, optional description, breadcrumbs, back button,
+ * and actions slot. The first thing a user sees on any list / detail / form
+ * page in a dashboard.
+ *
+ * Designed to drop directly into `<DashboardContent>` (or any padded page
+ * container). Has no outer padding of its own — the surrounding layout owns
+ * spacing.
+ *
+ * @example List page header with primary action
+ * ```tsx
+ * <PageHeader
+ *   title="Users"
+ *   description="Manage your team members and their roles."
+ *   actions={<Button onClick={openCreate}>Add user</Button>}
+ *   bordered
+ * />
+ * ```
+ *
+ * @example Detail page header with back button
+ * ```tsx
+ * <PageHeader
+ *   title={user.name}
+ *   description={user.email}
+ *   back={{
+ *     label: 'Users',
+ *     render: (props) => <Link to="/users" {...props} />,
+ *   }}
+ *   actions={
+ *     <>
+ *       <Button variant="outline">Edit</Button>
+ *       <Button variant="destructive">Delete</Button>
+ *     </>
+ *   }
+ * />
+ * ```
+ *
+ * @example With breadcrumbs slot
+ * ```tsx
+ * <PageHeader
+ *   breadcrumbs={
+ *     <nav aria-label="Breadcrumb">
+ *       <ol className="flex items-center gap-1">
+ *         <li><Link to="/">Home</Link></li>
+ *         <li>/</li>
+ *         <li>Users</li>
+ *       </ol>
+ *     </nav>
+ *   }
+ *   title="Users"
+ * />
+ * ```
+ */
+declare const PageHeader: react.ForwardRefExoticComponent<PageHeaderProps & react.RefAttributes<HTMLElement>>;
+
+declare const pageHeaderBaseClass = "flex w-full flex-col gap-3";
+/** Adds a bottom border separator below the header. */
+declare const pageHeaderBorderedClass = "border-b border-border pb-4";
+declare const pageHeaderTitleRowClass = "flex flex-wrap items-start justify-between gap-3 sm:gap-4";
+declare const pageHeaderTitleBlockClass = "min-w-0 flex-1 space-y-1";
+declare const pageHeaderTitleClass = "text-2xl font-semibold tracking-tight text-foreground";
+declare const pageHeaderDescriptionClass = "text-sm text-muted-foreground";
+declare const pageHeaderActionsClass = "flex shrink-0 flex-wrap items-center gap-2";
+declare const pageHeaderBackClass = "inline-flex items-center gap-1.5 self-start text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-2 focus-visible:ring-offset-background rounded-md";
+declare const pageHeaderBackIconClass = "size-4 shrink-0 rtl:rotate-180";
+declare const pageHeaderBreadcrumbsClass = "text-xs text-muted-foreground";
+
+type RadioGroupSize = 'sm' | 'md' | 'lg';
+/** Outer circle (radio button itself) — sized + bordered. */
+declare const radioItemSizeClass: Record<RadioGroupSize, string>;
+/** Inner indicator (the filled dot when selected). Centred via flex on the parent. */
+declare const radioIndicatorSizeClass: Record<RadioGroupSize, string>;
+/** Label text size that pairs naturally with each radio size. */
+declare const radioLabelSizeClass: Record<RadioGroupSize, string>;
+declare const radioItemBaseClass = "aspect-square shrink-0 rounded-full border border-input bg-background text-primary outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-2 focus-visible:ring-offset-background hover:border-ring disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:focus-visible:ring-destructive/40 data-[state=checked]:border-primary";
+declare const radioIndicatorBaseClass = "flex h-full w-full items-center justify-center";
+declare const radioIndicatorDotClass = "rounded-full bg-primary";
+/** Each option row: radio + label + optional description. */
+declare const radioOptionRowClass = "flex cursor-pointer items-start gap-2 has-[button:disabled]:cursor-not-allowed";
+/** The group container — vertical stack by default, horizontal row when orientation="horizontal". */
+declare const radioGroupBaseClass = "flex gap-3";
+declare const radioGroupOrientationClass: {
+    readonly vertical: "flex-col";
+    readonly horizontal: "flex-row flex-wrap";
+};
+
+interface RadioGroupOption {
+    value: string;
+    /** Visible label rendered next to the radio button. */
+    label: ReactNode;
+    /** Optional secondary text rendered below the label (e.g. plan description). */
+    description?: ReactNode;
+    disabled?: boolean;
+}
+type RadioGroupOrientation = 'vertical' | 'horizontal';
+interface RadioGroupProps {
+    /** Visual size of each radio + label. */
+    radioSize?: RadioGroupSize;
+    /** Layout direction within the group. `'vertical'` (default) stacks options; `'horizontal'` lays them out in a row. */
+    orientation?: RadioGroupOrientation;
+    /** Controlled selected value (Radix-style). */
+    value?: string;
+    /** Initial selected value for uncontrolled usage. */
+    defaultValue?: string;
+    /** Radix-style change handler — receives the new value directly. */
+    onValueChange?: (value: string) => void;
+    /** Synthetic-event handler for `react-hook-form`'s `field.onChange` and other consumers. */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Called when focus leaves the group. */
+    onBlur?: () => void;
+    /** Form name (for native form submission). */
+    name?: string;
+    /** Disables the entire group. */
+    disabled?: boolean;
+    /** Marks the group as required. */
+    required?: boolean;
+    /** Override id (otherwise auto-generated via useId). */
+    id?: string;
+    /** Declarative options. When `children` is provided it wins (escape hatch for custom content). */
+    options?: RadioGroupOption[];
+    /** Class on the outer group container. */
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean | 'true' | 'false';
+    /** Radix children — used for advanced composition (custom RadioGroupItem layouts). */
+    children?: ReactNode;
+}
+/**
+ * Group of mutually-exclusive radio buttons built on `@radix-ui/react-radio-group`.
+ * Use for **3–5 options** where Select would be overkill (pricing tier, privacy
+ * level, single-choice settings). Bare component — wrap in `<Field label="…">`
+ * for the GROUP label, helper, and error rendering.
+ *
+ * Each option carries its own per-radio `label` (and optional `description`).
+ * The Field's outer label names the group; the option labels name each choice.
+ *
+ * @example Inside a Field (RHF + Zod)
+ * ```tsx
+ * <Field name="plan" label="Subscription plan" description="You can change anytime.">
+ *   <RadioGroup
+ *     options={[
+ *       { value: 'free', label: 'Free', description: 'Up to 3 projects' },
+ *       { value: 'pro', label: 'Pro', description: 'Unlimited projects' },
+ *       { value: 'enterprise', label: 'Enterprise', description: 'Custom limits' },
+ *     ]}
+ *   />
+ * </Field>
+ * ```
+ *
+ * @example Horizontal row in a settings card
+ * ```tsx
+ * <Field label="Visibility" orientation="horizontal">
+ *   <RadioGroup
+ *     orientation="horizontal"
+ *     value={visibility}
+ *     onValueChange={setVisibility}
+ *     options={[
+ *       { value: 'public', label: 'Public' },
+ *       { value: 'private', label: 'Private' },
+ *     ]}
+ *   />
+ * </Field>
+ * ```
+ */
+declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & react.RefAttributes<HTMLDivElement>>;
+/**
+ * `<RadioGroupItem>` — re-exported for consumers building custom option layouts
+ * (icons, badges, etc.) via the `children` escape hatch.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup value={plan} onValueChange={setPlan}>
+ *   {plans.map((p) => (
+ *     <label key={p.value} htmlFor={p.value} className="flex items-center gap-2">
+ *       <RadioGroupItem id={p.value} value={p.value} />
+ *       <PlanCard {...p} />
+ *     </label>
+ *   ))}
+ * </RadioGroup>
+ * ```
+ */
+declare const RadioGroupItem: react.ForwardRefExoticComponent<Omit<RadixRadioGroup.RadioGroupItemProps & react.RefAttributes<HTMLButtonElement>, "ref"> & {
+    radioSize?: RadioGroupSize;
+} & react.RefAttributes<HTMLButtonElement>>;
+
 type SidebarProps = HTMLAttributes<HTMLElement>;
 declare function Sidebar({ className, children, ...props }: SidebarProps): react_jsx_runtime.JSX.Element;
 
@@ -595,117 +1218,6 @@ interface SwitchProps {
  */
 declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLButtonElement>>;
 
-type TableSize = 'sm' | 'md' | 'lg';
-interface TableSizeClasses {
-    /** Applied to <tr> when needed (currently empty — present for symmetry). */
-    row: string;
-    /** Applied to <td>. */
-    cell: string;
-    /** Applied to <th>. */
-    head: string;
-}
-declare const tableSizeClass: Record<TableSize, TableSizeClasses>;
-declare const tableBaseClass = "w-full caption-bottom border-collapse";
-declare const selectedRowClass = "bg-muted/40";
-declare const sortIconClass = "inline-flex h-3 w-3 shrink-0 items-center justify-center";
-declare const alignClass: Record<ColumnAlign, string>;
-
-type SortDirection = 'asc' | 'desc';
-interface SortState {
-    /** Column id being sorted, or `null` when no sort is active. */
-    columnId: string | null;
-    direction: SortDirection;
-}
-interface PaginationState {
-    /** 0-based page index. */
-    pageIndex: number;
-    pageSize: number;
-}
-/** Set of row ids (returned from `getRowId`) that are currently selected. */
-type RowSelectionState = ReadonlySet<string>;
-type SortableValue = string | number | bigint | boolean | Date | null | undefined;
-type ColumnAlign = 'start' | 'center' | 'end';
-interface Column<T> {
-    /** Stable column id. Used for sort state and React keys. */
-    id: string;
-    /** Header label, ReactNode, or a function that returns the header content. */
-    header: ReactNode | (() => ReactNode);
-    /** Field on T to read for default rendering and default sorting. */
-    accessor?: keyof T;
-    /** Custom cell renderer. If omitted, renders `String(row[accessor] ?? '')`. */
-    render?: (row: T, rowIndex: number) => ReactNode;
-    /** Enable click-to-sort UI on the header. */
-    sortable?: boolean;
-    /** Optional override for the value used to compare during sorting. */
-    sortAccessor?: (row: T) => SortableValue;
-    /** Tailwind classes applied to both <th> and <td>. */
-    className?: string;
-    /** Inline alignment hint. Defaults to 'start'. */
-    align?: ColumnAlign;
-}
-interface TableProps<T> {
-    /** Source rows. In server-side mode, this is just the current page. */
-    data: readonly T[];
-    /** Column definitions. */
-    columns: ReadonlyArray<Column<T>>;
-    /** Stable id for each row. Required for selection; recommended always. */
-    getRowId: (row: T, index: number) => string;
-    /**
-     * Total row count across all pages. Pass this when the parent paginates/sorts
-     * server-side — Table will skip its local sort + slice.
-     */
-    totalCount?: number;
-    defaultSort?: SortState;
-    sort?: SortState;
-    onSortChange?: (next: SortState) => void;
-    defaultPagination?: PaginationState;
-    pagination?: PaginationState;
-    onPaginationChange?: (next: PaginationState) => void;
-    /** Page size dropdown options. Defaults to [10, 25, 50]. */
-    pageSizeOptions?: readonly number[];
-    /** Force the paginator to render even when rowCount <= pageSize. */
-    showPagination?: boolean;
-    /** Adds the selection column + header checkbox. */
-    enableRowSelection?: boolean;
-    defaultSelectedRowIds?: ReadonlySet<string>;
-    selectedRowIds?: ReadonlySet<string>;
-    onSelectedRowIdsChange?: (next: ReadonlySet<string>) => void;
-    /** Per-row guard. Disabled rows have a disabled checkbox and are excluded from "select all". */
-    isRowSelectable?: (row: T) => boolean;
-    /** Render prop receives the array of selected rows currently present in `data`. */
-    bulkActions?: (selectedRows: T[]) => ReactNode;
-    /** Override the "{n} selected" label (i18n / RTL). */
-    renderSelectionLabel?: (count: number) => ReactNode;
-    /** Label for the "Clear" button on the toolbar. */
-    clearSelectionLabel?: ReactNode;
-    loading?: boolean;
-    /** Number of skeleton rows shown while loading. Defaults to current pageSize. */
-    loadingRowCount?: number;
-    /** Empty-state slot. Defaults to a centered "No data" message. */
-    emptyState?: ReactNode;
-    size?: TableSize;
-    className?: string;
-    tableClassName?: string;
-    /**
-     * Constrain the scrollable region's height. Accepts any CSS length (e.g. `400`,
-     * `'24rem'`, `'60vh'`). When set, the body scrolls vertically and the header
-     * sticks to the top.
-     */
-    maxHeight?: number | string;
-    /** Stripe alternating rows. Defaults to false. */
-    striped?: boolean;
-    /** Optional row click handler. */
-    onRowClick?: (row: T, rowIndex: number) => void;
-    /** Optional ref to the underlying <table> element. */
-    tableRef?: Ref<HTMLTableElement>;
-    'aria-label'?: string;
-    'aria-labelledby'?: string;
-    /** Caption rendered as <caption className="sr-only"> for assistive tech. */
-    caption?: ReactNode;
-}
-
-declare function Table<T>(props: TableProps<T>): react_jsx_runtime.JSX.Element;
-
 type TextareaVariant = 'default' | 'filled' | 'ghost';
 type TextareaSize = 'sm' | 'md' | 'lg';
 type TextareaResize = 'none' | 'vertical' | 'horizontal' | 'both';
@@ -719,41 +1231,26 @@ interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>
     textareaSize?: TextareaSize;
     /** Controls the native CSS `resize` behaviour. Defaults to `'vertical'`. */
     resize?: TextareaResize;
-    /** Optional label rendered above the field. */
-    label?: ReactNode;
-    /** Helper text rendered under the field when not in an error state. */
-    helperText?: ReactNode;
-    /** Error message — renders in destructive style and sets aria-invalid. */
-    error?: ReactNode;
-    /** Stretch the wrapper to fill the parent's inline width. Defaults to `true`. */
-    fullWidth?: boolean;
     /** Class applied to the outer wrapper that frames the textarea. */
     wrapperClassName?: string;
-    /** Class applied to the field container (`<label>` block). */
-    containerClassName?: string;
 }
 /**
- * Multi-line text input with the same label/helper/error/aria contract as `<Input>`.
- * Works standalone OR wrapped inside `<Field>`.
- *
- * @example Standalone
- * ```tsx
- * <Textarea label="Bio" helperText="Up to 280 characters." rows={4} />
- * ```
+ * Bare multi-line text input — renders the wrapper + native `<textarea>`. **No
+ * label/helperText/error props by design** (per ADR-007: Field owns all form
+ * layout). Wrap in `<Field label="…">` for label, helper, error rendering and
+ * full a11y wiring.
  *
- * @example With error + custom resize
+ * @example Inside a Field (RHF + Zod)
  * ```tsx
- * <Textarea
- *   label="Notes"
- *   error={errors.notes?.message}
- *   resize="vertical"
- * />
+ * <Field name="bio" label="Bio" description="Up to 280 characters.">
+ *   <Textarea rows={4} />
+ * </Field>
  * ```
  *
- * @example Inside a Field (RHF + Zod)
+ * @example Custom resize behaviour
  * ```tsx
- * <Field name="bio" label="Bio">
- *   <Textarea rows={4} />
+ * <Field label="Notes">
+ *   <Textarea resize="none" rows={6} />
  * </Field>
  * ```
  */
@@ -764,4 +1261,4 @@ declare function useDirection(): Direction;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AppShell, type AppShellBrand, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, Avatar, type AvatarProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, type CheckboxSize, type Column, type ColumnAlign, DashboardContent, type DashboardContentProps, DashboardHeader, type DashboardHeaderProps, DashboardLayout, type DashboardLayoutContextValue, type DashboardLayoutProps, DashboardMain, type DashboardMainProps, type Direction, Field, type FieldOrientation, type FieldProps, type FieldRHFProps, HeaderActions, type HeaderActionsProps, HeaderCollapseTrigger, type HeaderCollapseTriggerProps, HeaderMobileTrigger, type HeaderMobileTriggerProps, HeaderSearch, type HeaderSearchProps, HeaderTitle, type HeaderTitleProps, Input, type InputProps, type InputSize, type InputVariant, type LanguageOption, LanguageSwitcher, type LanguageSwitcherProps, type PaginationState, type RowSelectionState, Select, type SelectOption, type SelectProps, type SelectSize, type SelectVariant, Sidebar, SidebarFooter, type SidebarFooterProps, SidebarGroup, type SidebarGroupProps, SidebarHeader, type SidebarHeaderProps, SidebarNav, SidebarNavGroup, type SidebarNavGroupProps, SidebarNavItem, type SidebarNavItemProps, type SidebarNavItemRenderProps, type SidebarNavProps, type SidebarProps, type SortDirection, type SortState, type SortableValue, Switch, type SwitchProps, type SwitchSize, Table, type TableProps, type TableSize, type TableSizeClasses, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type TextareaVariant, buttonBaseClass, buttonSizeClass, buttonVariantClass, cn, inputBaseClass, inputSizeClass, inputVariantClass, selectBaseClass, selectSizeClass, selectVariantClass, switchThumbBaseClass, switchThumbClass, switchTrackBaseClass, switchTrackClass, alignClass as tableAlignClass, tableBaseClass, selectedRowClass as tableSelectedRowClass, tableSizeClass, sortIconClass as tableSortIconClass, textareaBaseClass, textareaResizeClass, textareaSizeClass, textareaVariantClass, useDashboardLayout, useDirection };
+export { AppShell, type AppShellBrand, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, type CheckboxSize, type Column, type ColumnAlign, DashboardContent, type DashboardContentProps, DashboardHeader, type DashboardHeaderProps, DashboardLayout, type DashboardLayoutContextValue, type DashboardLayoutProps, DashboardMain, type DashboardMainProps, type Direction, DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, type DropdownMenuItemVariant, DropdownMenuLabel, type DropdownMenuLabelProps, DropdownMenuPortal, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuShortcut, type DropdownMenuShortcutProps, DropdownMenuTrigger, EmptyState, type EmptyStateProps, type EmptyStateSize, Field, type FieldOrientation, type FieldProps, type FieldRHFProps, HeaderActions, type HeaderActionsProps, HeaderCollapseTrigger, type HeaderCollapseTriggerProps, HeaderMobileTrigger, type HeaderMobileTriggerProps, HeaderSearch, type HeaderSearchProps, HeaderTitle, type HeaderTitleProps, Input, type InputProps, type InputSize, type InputVariant, type LanguageOption, LanguageSwitcher, type LanguageSwitcherProps, ListPage, type ListPageEmptyState, type ListPageFilter, type ListPageLabels, type ListPageProps, PageHeader, type PageHeaderBackProps, type PageHeaderBackRenderProps, type PageHeaderHeadingLevel, type PageHeaderProps, type PaginationState, RadioGroup, RadioGroupItem, type RadioGroupOption, type RadioGroupOrientation, type RadioGroupProps, type RadioGroupSize, type RowSelectionState, Select, type SelectOption, type SelectProps, type SelectSize, type SelectVariant, Sidebar, SidebarFooter, type SidebarFooterProps, SidebarGroup, type SidebarGroupProps, SidebarHeader, type SidebarHeaderProps, SidebarNav, SidebarNavGroup, type SidebarNavGroupProps, SidebarNavItem, type SidebarNavItemProps, type SidebarNavItemRenderProps, type SidebarNavProps, type SidebarProps, type SortDirection, type SortState, type SortableValue, Switch, type SwitchProps, type SwitchSize, Table, type TableProps, type TableSize, type TableSizeClasses, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type TextareaVariant, badgeBaseClass, badgeDotSizeClass, badgeSizeClass, badgeVariantClass, buttonBaseClass, buttonSizeClass, buttonVariantClass, cn, dropdownMenuContentClass, dropdownMenuItemBaseClass, dropdownMenuItemInsetClass, dropdownMenuItemVariantClass, dropdownMenuLabelClass, dropdownMenuSeparatorClass, dropdownMenuShortcutClass, emptyStateActionsSpacingClass, emptyStateBaseClass, emptyStateContainerSizeClass, emptyStateDescriptionSizeClass, emptyStateIconWrapperBaseClass, emptyStateIconWrapperSizeClass, emptyStateTitleSizeClass, inputBaseClass, inputSizeClass, inputVariantClass, pageHeaderActionsClass, pageHeaderBackClass, pageHeaderBackIconClass, pageHeaderBaseClass, pageHeaderBorderedClass, pageHeaderBreadcrumbsClass, pageHeaderDescriptionClass, pageHeaderTitleBlockClass, pageHeaderTitleClass, pageHeaderTitleRowClass, radioGroupBaseClass, radioGroupOrientationClass, radioIndicatorBaseClass, radioIndicatorDotClass, radioIndicatorSizeClass, radioItemBaseClass, radioItemSizeClass, radioLabelSizeClass, radioOptionRowClass, selectBaseClass, selectSizeClass, selectVariantClass, switchThumbBaseClass, switchThumbClass, switchTrackBaseClass, switchTrackClass, alignClass as tableAlignClass, tableBaseClass, selectedRowClass as tableSelectedRowClass, tableSizeClass, sortIconClass as tableSortIconClass, textareaBaseClass, textareaResizeClass, textareaSizeClass, textareaVariantClass, useDashboardLayout, useDirection };