rich-react-component 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,118 @@
+# rich-react-component
+
+Repository: [github.com/suleymangulle/rich-react-component](https://github.com/suleymangulle/rich-react-component) (private) · [npm](https://www.npmjs.com/package/rich-react-component)
+
+[![npm version](https://img.shields.io/npm/v/rich-react-component.svg)](https://www.npmjs.com/package/rich-react-component)
+
+Enterprise React + TypeScript component library built on **Bootstrap + Metronic** conventions, organized into three capability layers:
+
+```text
+Base    — pure UI behavior, no HTTP, no backend knowledge
+Remote  — adds remote-data fetching to Base components by composing them
+Smart   — metadata-driven configuration layer (Phases 1-5 complete)
+```
+
+Each layer **reuses** the one below it instead of reimplementing it — `RemoteComboBox` composes `ComboBox`, it does not contain a second combobox implementation. See [`react-components-initial.md`](./react-components-initial.md) for the original architecture brief this library follows.
+
+## Install
+
+```bash
+npm install rich-react-component bootstrap react react-dom
+```
+
+`bootstrap`, `react`, and `react-dom` are peer dependencies — the library ships no CSS of its own beyond what Bootstrap classes provide.
+
+```tsx
+import "bootstrap/dist/css/bootstrap.min.css";
+```
+
+## Quick example
+
+```tsx
+import { ComboBox, SmartField } from "rich-react-component";
+import { RemoteComboBox } from "rich-react-component";
+
+// Base — you own the data
+<ComboBox
+  options={[{ value: "tr", label: "Turkey" }]}
+  value={countryId}
+  onChange={setCountryId}
+/>
+
+// Remote — the component owns fetching, cancellation, and stale-response
+// protection; you only describe the endpoint and the field mapping
+<RemoteComboBox
+  url="/api/countries"
+  valueMember="id"
+  displayMember="name"
+  value={countryId}
+  onChange={setCountryId}
+/>
+
+// Smart — the server describes the field, SmartField resolves it onto
+// RemoteComboBox for you; visible/readOnly/required/validation all come
+// from metadata instead of being written by hand at every call site
+<SmartField
+  metadata={{
+    name: "countryId", component: "ComboBox",
+    valueMember: "id", displayMember: "name",
+    dataSource: { id: "Countries" },
+  }}
+  ctx={ctx} // { values, onFieldChange, registry, dataSources, actions }
+/>
+```
+
+## What's in each layer
+
+**Base** (49 components) — form fields (`Input`, `NumberInput`, `PasswordInput`, `FileInput`, `CheckBox`, `Switch`, `RadioGroup`, `Select`, `MultiSelect`, `DatePicker`, `TimePicker`, `DateTimePicker`, `ComboBox`, `AutoComplete`, `FormField`), feedback (`Modal`, `Toast`, `Confirm`, `Alert`, `Spinner`, `Badge`, `Skeleton`), data display (`DataGrid`, `Pagination`, `Avatar`, `Tag`, `Rating`, `ProgressBar`), navigation (`Breadcrumb`, `Menu`, `Stepper`, `Tabs`, `Navbar`, `Sidebar`, `PageHeader`), layout (`Card`, `Divider`, `Stack`, `Container`, `Row`, `Col`), and more (`Button`, `Tooltip`, `Popover`, `Accordion`, `Icon`).
+
+**Remote** — `RemoteComboBox`, `RemoteAutoComplete`, `RemoteSelect`, `RemoteMultiSelect`, `RemoteDataGrid`, backed by a shared `HttpClient` abstraction and a `useRemoteData` hook that handles request cancellation, stale-response protection, and a consistent `idle/loading/success/empty/error` state model.
+
+**Smart** — *Phases 1-5 complete, the full approved plan.* A metadata-driven layer: the server describes a field or action, Smart resolves that description onto the exact Base/Remote component that already exists — it never reimplements one.
+
+- **Metadata contract** — a discriminated union per component type (`InputMetadata | ComboBoxMetadata | DatePickerMetadata | DataGridMetadata`), plus `SmartActionMetadata` for buttons. Declarative only: no expressions, no serialized functions.
+- **Registries** — `SmartComponentRegistry` (keyed by the `component` discriminant, not a switch), `SmartDataSourceRegistry` and `SmartActionRegistry` (id-based indirection — metadata never carries a raw URL or a function).
+- **Built-in resolvers** — Input, ComboBox, DatePicker, and DataGrid, registered via `registerBuiltInResolvers()` through the exact same call a custom application component would use. DataGrid's column metadata (`format: "text" | "date" | "currency" | "boolean"`) maps to a small, Smart-owned set of formatters — the server requests a formatter, never ships one.
+- **Headless engine** — `useSmartField` / `useSmartAction` resolve one field/action's metadata (visibility, validation, localized label, resolved request params); `useSmartDependencies` tracks `dependsOn` and reports which field needs fresh metadata when a value it depends on changes.
+- **Components** — `SmartField` / `SmartAction` resolve one piece of metadata into UI; `SmartForm` / `SmartActions` are thin iteration helpers over a whole `SmartFormMetadata` — no field-value ownership, no business-rule evaluation, no layout decisions.
+
+## Demo pages
+
+Two dev-only pages exercise the library live — not part of the published package:
+
+```bash
+npm run dev
+```
+
+- `/index.html` — every Base/Remote component in one manual-test page
+- `/smart-demo.html` — the full Phase 1-5 Smart engine end to end: a cascading Country/City form and server-driven field visibility/validation rendered through one `<SmartForm>` call, a paginated DataGrid through one `<SmartField>` call, `<SmartActions>` with a real fail-safe-disabled button, a dependency-refresh log, and EN/TR localization (including the DataGrid's boolean formatter) — with in-page documentation popups
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the demo pages with Vite |
+| `npm run build` | Type-check + build the library to `dist/` (ESM, CJS, `.d.ts`) |
+| `npm test` | Run the test suite once (Vitest) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run typecheck` | Type-check the whole project without emitting |
+
+## Project structure
+
+```text
+src/
+├── base/     # Base layer — no dependency on remote/ or smart/
+├── remote/   # Remote layer — may depend on base/, not on smart/
+├── smart/    # Smart layer (Phases 1-5) — may depend on base/ and remote/
+└── index.ts  # public entry point
+
+demo/         # dev-only manual-test pages (not published)
+```
+
+## Testing
+
+Behavioral tests over snapshots. Every capability layer is tested against its own contract — Base components never call `fetch`, Remote components reuse (not duplicate) their Base counterpart's UI, dependency-driven param changes reload correctly without stale-response races, and the Smart registry falls back safely for an unresolved component type instead of rendering the wrong thing.
+
+## License
+
+[MIT](./LICENSE) © suleymangulle

package/dist/base/Accordion.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+export interface AccordionItem {
+    key: string;
+    header: string;
+    content: ReactNode;
+    disabled?: boolean;
+}
+export interface AccordionProps {
+    items: AccordionItem[];
+    /** false (default) = single-open (classic accordion); true = multiple sections can be open at once. */
+    multiple?: boolean;
+    openKeys?: string[];
+    defaultOpenKeys?: string[];
+    onChange?: (openKeys: string[]) => void;
+    className?: string;
+}
+export declare function Accordion({ items, multiple, openKeys, defaultOpenKeys, onChange, className }: AccordionProps): import("react").JSX.Element;

package/dist/base/Alert.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+export type AlertVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
+export interface AlertProps {
+    variant?: AlertVariant;
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Presentation only (doc section 15) — deliberately not a toast
+ * service/notification bus/error-management system. A consumer owns when
+ * an Alert mounts/unmounts and what triggers it.
+ */
+export declare function Alert({ variant, dismissible, onDismiss, className, children }: AlertProps): import("react").JSX.Element;

package/dist/base/AutoComplete.d.ts

@@ -0,0 +1,20 @@
+import { FieldIdentity, FieldPresentation, FieldState, SelectOption } from './shared/fieldTypes';
+export interface AutoCompleteProps<TValue extends string | number = string> extends FieldIdentity, FieldState, FieldPresentation {
+    options: SelectOption<TValue>[];
+    value?: TValue | null;
+    defaultValue?: TValue | null;
+    onChange?: (value: TValue | null) => void;
+    /** Controlled search text, independent from the selected `value`. */
+    inputValue?: string;
+    onInputValueChange?: (text: string) => void;
+    /** Presentational-only loading flag — see ComboBox's `loading` prop. */
+    loading?: boolean;
+    emptyText?: string;
+    /**
+     * Local filter predicate. Defaults to a case-insensitive substring match.
+     * RemoteAutoComplete overrides this with `() => true` because the server
+     * already filtered the results — Base must never re-filter server output.
+     */
+    filter?: (option: SelectOption<TValue>, query: string) => boolean;
+}
+export declare function AutoComplete<TValue extends string | number = string>({ options, value, defaultValue, onChange, inputValue, onInputValueChange, loading, emptyText, filter, id, name, disabled, readOnly, required, className, label, placeholder, helpText, error, }: AutoCompleteProps<TValue>): import("react").JSX.Element;

package/dist/base/Avatar.d.ts

@@ -0,0 +1,8 @@
+export interface AvatarProps {
+    src?: string;
+    /** Used both for the image's alt text and for the initials fallback when there's no `src`. */
+    name?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+export declare function Avatar({ src, name, size, className }: AvatarProps): import("react").JSX.Element;

package/dist/base/Badge.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export type BadgeVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
+export interface BadgeProps {
+    variant?: BadgeVariant;
+    pill?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+export declare function Badge({ variant, pill, className, children }: BadgeProps): import("react").JSX.Element;

package/dist/base/Breadcrumb.d.ts

@@ -0,0 +1,10 @@
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+}
+export interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+    className?: string;
+}
+export declare function Breadcrumb({ items, className }: BreadcrumbProps): import("react").JSX.Element;

package/dist/base/Button.d.ts

@@ -0,0 +1,13 @@
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+export type ButtonVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark" | "link" | "outline-primary" | "outline-secondary";
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className" | "type" | "disabled"> {
+    variant?: ButtonVariant;
+    size?: "sm" | "lg";
+    disabled?: boolean;
+    loading?: boolean;
+    type?: "button" | "submit" | "reset";
+    className?: string;
+    children?: ReactNode;
+}
+/** Reuses Spinner for the loading indicator (doc section 13) instead of a bespoke inline spinner. */
+export declare function Button({ variant, size, disabled, loading, type, className, children, onClick, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/base/Card.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export interface CardProps {
+    header?: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+}
+/** Generic content container — the most basic layout primitive, used to group everything else. */
+export declare function Card({ header, footer, className, children }: CardProps): import("react").JSX.Element;

package/dist/base/CheckBox.d.ts

@@ -0,0 +1,17 @@
+import { FieldIdentity, FieldState } from './shared/fieldTypes';
+export interface CheckBoxProps extends FieldIdentity, FieldState {
+    className?: string;
+    label?: string;
+    helpText?: string;
+    error?: string;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+}
+/**
+ * Deliberately doesn't use FieldShell — a checkbox's label sits beside the
+ * control, not above it, so the layout genuinely differs (doc section 13:
+ * shared contracts only where a real semantic relationship exists). Shares
+ * its actual rendering with Switch via BooleanFieldControl.
+ */
+export declare function CheckBox(props: CheckBoxProps): import("react").JSX.Element;

package/dist/base/Col.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+export interface ColProps {
+    /** Column width at the default breakpoint (1-12). Omit for `col` (auto-width). */
+    span?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    className?: string;
+    children?: ReactNode;
+}
+export declare function Col({ span, sm, md, lg, xl, className, children }: ColProps): import("react").JSX.Element;

package/dist/base/ComboBox.d.ts

@@ -0,0 +1,17 @@
+import { FieldIdentity, FieldPresentation, FieldState, SelectOption } from './shared/fieldTypes';
+export type { SelectOption };
+export interface ComboBoxProps<TValue extends string | number = string> extends FieldIdentity, FieldState, FieldPresentation {
+    options: SelectOption<TValue>[];
+    value?: TValue | null;
+    defaultValue?: TValue | null;
+    onChange?: (value: TValue | null) => void;
+    /**
+     * Presentational-only loading flag. ComboBox has no idea *why* it's
+     * loading (doc section 8: don't pollute Base with HTTP concepts) — this
+     * is set by RemoteComboBox, but could equally be driven by any other
+     * async source.
+     */
+    loading?: boolean;
+    emptyText?: string;
+}
+export declare function ComboBox<TValue extends string | number = string>({ options, value, defaultValue, onChange, loading, emptyText, id, name, disabled, readOnly, required, className, label, placeholder, helpText, error, }: ComboBoxProps<TValue>): import("react").JSX.Element;

package/dist/base/Confirm.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from 'react';
+import { ButtonVariant } from './Button';
+export interface ConfirmOptions {
+    title?: string;
+    message: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    confirmVariant?: ButtonVariant;
+}
+export type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+/**
+ * Imperative yes/no dialog. Built on Modal + Button (doc section 20: reuse,
+ * don't reimplement) instead of every screen wiring its own "are you sure"
+ * modal-open state and footer buttons by hand.
+ *
+ * Known limitation: a second confirm() call while one is still pending
+ * replaces it — the first promise never settles. Acceptable for v1 (doc
+ * section 6: avoid speculative infrastructure); a queue can be added if a
+ * real screen needs overlapping confirms.
+ */
+export declare function ConfirmProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Throws outside ConfirmProvider — same fail-fast contract as other context-backed hooks in this library. */
+export declare function useConfirm(): ConfirmFn;

package/dist/base/Container.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+export interface ContainerProps {
+    fluid?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+export declare function Container({ fluid, className, children }: ContainerProps): import("react").JSX.Element;

package/dist/base/DataGrid.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+export interface DataGridColumn<TRow> {
+    key: string;
+    header: string;
+    render?: (row: TRow) => ReactNode;
+    sortable?: boolean;
+    width?: string;
+}
+export type DataGridSort = {
+    key: string;
+    direction: "asc" | "desc";
+};
+export interface DataGridProps<TRow> {
+    columns: DataGridColumn<TRow>[];
+    rows: TRow[];
+    rowKey: (row: TRow) => string | number;
+    loading?: boolean;
+    error?: string;
+    emptyText?: string;
+    className?: string;
+    /** Selection is a generic UI concern — Base doesn't know how selection maps to anything remote. */
+    selectedRowKeys?: Array<string | number>;
+    onSelectionChange?: (keys: Array<string | number>) => void;
+    /**
+     * Sort UI only. Base renders sort indicators and calls back on header
+     * click — it has no idea whether sorting happens client-side or via a
+     * server request (doc section 10).
+     */
+    sort?: DataGridSort | null;
+    onSortChange?: (sort: DataGridSort | null) => void;
+    /** Pagination UI only, fully controlled from outside — same principle as sort. */
+    page?: number;
+    pageSize?: number;
+    totalCount?: number;
+    onPageChange?: (page: number) => void;
+}
+/**
+ * Intentionally focused first iteration (doc section 10/18): columns, rows,
+ * selection, sort UI, pagination UI, loading/empty/error presentation.
+ * No built-in filtering UI, column resize/reorder, or virtualization yet —
+ * those are future extensions, not implemented speculatively.
+ */
+export declare function DataGrid<TRow>({ columns, rows, rowKey, loading, error, emptyText, className, selectedRowKeys, onSelectionChange, sort, onSortChange, page, pageSize, totalCount, onPageChange, }: DataGridProps<TRow>): import("react").JSX.Element;

package/dist/base/DatePicker.d.ts

@@ -0,0 +1,23 @@
+import { FieldIdentity, FieldPresentation, FieldState } from './shared/fieldTypes';
+export interface DatePickerProps extends FieldIdentity, FieldState, FieldPresentation {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onChange?: (value: Date | null) => void;
+    min?: Date;
+    max?: Date;
+}
+/**
+ * Exported so TimePicker/DateTimePicker can compose the exact same
+ * date-part parsing/formatting instead of reimplementing it (doc section
+ * 12 — a coherent Date/Time value strategy across the whole family).
+ */
+export declare function toDateInputValue(date: Date | null | undefined): string;
+export declare function fromDateInputValue(raw: string): Date | null;
+/**
+ * Intentionally minimal: reuses Input + the native date picker UI rather
+ * than building a calendar widget (doc section 10/18 — don't overbuild the
+ * first iteration). value/onChange work in terms of `Date`, so a richer
+ * Popup-based calendar can replace the native input later without breaking
+ * this public contract. See "Known Limitations" in the final report.
+ */
+export declare function DatePicker({ value, defaultValue, onChange, min, max, ...rest }: DatePickerProps): import("react").JSX.Element;

package/dist/base/DateTimePicker.d.ts

@@ -0,0 +1,17 @@
+import { FieldIdentity, FieldPresentation, FieldState } from './shared/fieldTypes';
+export interface DateTimePickerProps extends FieldIdentity, FieldState, FieldPresentation {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onChange?: (value: Date | null) => void;
+    min?: Date;
+    max?: Date;
+}
+/**
+ * Reuses DatePicker's/TimePicker's exported date-part/time-part parsing so
+ * the whole family shares one coherent `Date` value strategy (doc section
+ * 12) — this is the actual "behavior reuse" the doc asks for. Renders two
+ * plain native inputs rather than nesting two <Input>s: Input always wraps
+ * itself in FieldShell, and nesting it twice here would produce two labels
+ * for one field. A single FieldShell wraps both inputs as one field group.
+ */
+export declare function DateTimePicker({ value, defaultValue, onChange, min, max, id, name, disabled, readOnly, required, className, label, helpText, error, }: DateTimePickerProps): import("react").JSX.Element;

package/dist/base/Divider.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+export interface DividerProps {
+    className?: string;
+    vertical?: boolean;
+    /** Optional centered label (e.g. "OR") — renders a labeled horizontal divider instead of a plain line. */
+    label?: ReactNode;
+}
+export declare function Divider({ className, vertical, label }: DividerProps): import("react").JSX.Element;

package/dist/base/FileInput.d.ts

@@ -0,0 +1,19 @@
+import { FieldIdentity, FieldPresentation } from './shared/fieldTypes';
+export interface FileInputProps extends FieldIdentity, FieldPresentation {
+    disabled?: boolean;
+    required?: boolean;
+    accept?: string;
+    multiple?: boolean;
+    onChange?: (files: FileList | null) => void;
+}
+/**
+ * File selection only — no upload/API/cloud-storage/chunking (doc section
+ * 11; that belongs to a future Remote-layer concern, not Base).
+ *
+ * Intentionally uncontrolled-only: browsers do not allow programmatically
+ * setting `<input type="file">`'s value for security reasons, so this is a
+ * documented, deliberate exception to the library's controlled/uncontrolled
+ * policy rather than an inconsistency — there is no `value`/`defaultValue`
+ * to be controlled.
+ */
+export declare function FileInput({ id, name, disabled, required, className, label, helpText, error, accept, multiple, onChange }: FileInputProps): import("react").JSX.Element;

package/dist/base/FormField.d.ts

@@ -0,0 +1,12 @@
+import { FieldShellProps } from './shared/FieldShell';
+export type FormFieldProps = FieldShellProps;
+/**
+ * Public composition of Label + control + ValidationMessage for consumers
+ * who need our field chrome around a *custom* control (e.g. a group of
+ * RadioButtons, a Switch, a third-party widget) rather than one of our own
+ * field components. Deliberately a thin re-export of FieldShell — the two
+ * names serve different audiences (FieldShell: internal plumbing for our
+ * own fields; FormField: the same behavior, public), not two
+ * implementations (doc section 9 — no form-framework infrastructure here).
+ */
+export declare function FormField(props: FormFieldProps): import("react").JSX.Element;

package/dist/base/Icon.d.ts

@@ -0,0 +1,15 @@
+export interface IconProps {
+    /**
+     * Full icon class name(s) — e.g. "bi bi-trash" (Bootstrap Icons) or
+     * "ki-outline ki-trash" (Metronic Keenicons). Icon-set agnostic by design:
+     * this component bundles no icon font of its own (doc section 15 — stay
+     * on Bootstrap/Metronic, don't introduce another framework or a
+     * duplicate asset), it only standardizes sizing and accessibility.
+     */
+    name: string;
+    size?: "sm" | "lg" | "xl";
+    className?: string;
+    /** Accessible label. Omit for a purely decorative icon (default: aria-hidden). */
+    label?: string;
+}
+export declare function Icon({ name, size, className, label }: IconProps): import("react").JSX.Element;

package/dist/base/Input.d.ts

@@ -0,0 +1,30 @@
+import { FocusEventHandler, InputHTMLAttributes, ReactNode } from 'react';
+import { FieldIdentity, FieldPresentation, FieldState } from './shared/fieldTypes';
+type NativePassthroughProps = Omit<InputHTMLAttributes<HTMLInputElement>, "id" | "name" | "value" | "defaultValue" | "onChange" | "onBlur" | "className" | "disabled" | "readOnly" | "required" | "placeholder">;
+export interface InputProps extends FieldIdentity, FieldState, FieldPresentation {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onBlur?: FocusEventHandler<HTMLInputElement>;
+    type?: "text" | "email" | "password" | "tel" | "url" | "search";
+    maxLength?: number;
+    autoFocus?: boolean;
+    /**
+     * Escape hatch for native attributes that don't deserve a first-class prop
+     * on every text-like field (e.g. `inputMode`, `min`/`max`/`step`, `type`
+     * override). Keeps the primary prop surface small (doc section 13) while
+     * still letting NumberInput/DatePicker compose Input instead of
+     * reimplementing it.
+     */
+    inputProps?: NativePassthroughProps;
+    /**
+     * Generic trailing slot rendered inside a Bootstrap `input-group` (e.g. a
+     * visibility-toggle button, a unit suffix, a clear button). Not
+     * password-specific — PasswordInput is just its first consumer, reusing
+     * Input's full controlled-state/markup instead of reimplementing a
+     * parallel text field (doc section 4/19).
+     */
+    endAdornment?: ReactNode;
+}
+export declare function Input(props: InputProps): import("react").JSX.Element;
+export {};

package/dist/base/Menu.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+export interface MenuItem {
+    key: string;
+    label: ReactNode;
+    disabled?: boolean;
+    danger?: boolean;
+    onSelect?: () => void;
+}
+export interface MenuProps {
+    items: MenuItem[];
+    children: ReactNode;
+    placement?: "start" | "end";
+    className?: string;
+}
+/**
+ * A generic click-triggered action menu (e.g. a "..." row action button) —
+ * distinct from Select/ComboBox, which pick a *value*. Reuses Popup +
+ * useListNavigation, the same headless pair ComboBox/AutoComplete/
+ * MultiSelect already share (doc's reuse mandate).
+ */
+export declare function Menu({ items, children, placement, className }: MenuProps): import("react").JSX.Element;

package/dist/base/Modal.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+export interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title?: string;
+    children: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+}
+/**
+ * Centered/backdrop dialog overlay — a different interaction model from
+ * Popup's anchored dropdown, so it's a separate component, but shares the
+ * escape-to-close behavior via useEscapeKey.
+ *
+ * Known limitation: not rendered through a portal yet (renders in place).
+ * Can be swapped to `createPortal(..., document.body)` later without
+ * changing this component's props.
+ */
+export declare function Modal({ open, onClose, title, children, footer, className }: ModalProps): import("react").JSX.Element | null;

package/dist/base/MultiSelect.d.ts

@@ -0,0 +1,25 @@
+import { FieldIdentity, FieldPresentation, FieldState, SelectOption } from './shared/fieldTypes';
+export interface MultiSelectProps<TValue extends string | number = string> extends FieldIdentity, FieldState, FieldPresentation {
+    options: SelectOption<TValue>[];
+    values?: TValue[];
+    defaultValues?: TValue[];
+    onChange?: (values: TValue[]) => void;
+    loading?: boolean;
+    emptyText?: string;
+}
+/**
+ * Follows ComboBox's established `options: SelectOption<TValue>[]` /
+ * FieldShell / Popup / useListNavigation conventions rather than the raw
+ * `items`+`valueMember`+`displayMember` shape shown as a *conceptual*
+ * example in the source spec — that mapping-by-key convention belongs to
+ * the Remote layer (where raw API objects need mapping); Base MultiSelect
+ * receives already-typed `SelectOption`s, consistent with Base ComboBox.
+ * (Documented in the final report as a deliberate reconciliation of the
+ * spec's own two instructions: "follow this example" vs. "follow ComboBox's
+ * existing, good convention" — the latter wins per the spec's own priority.)
+ *
+ * Reuses Popup + useListNavigation from ComboBox/AutoComplete; the only
+ * real behavioral difference is that selecting an option toggles it in a
+ * `values` array and leaves the popup open instead of closing it.
+ */
+export declare function MultiSelect<TValue extends string | number = string>({ options, values, defaultValues, onChange, loading, emptyText, id, name, disabled, readOnly, required, className, label, placeholder, helpText, error, }: MultiSelectProps<TValue>): import("react").JSX.Element;

package/dist/base/Navbar.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+export interface NavbarProps {
+    brand?: ReactNode;
+    /** Left-aligned slot, e.g. primary nav links. */
+    start?: ReactNode;
+    /** Right-aligned slot, e.g. search, notifications, user menu. */
+    end?: ReactNode;
+    variant?: "light" | "dark";
+    className?: string;
+}
+/**
+ * Top app bar shell. Brand/start/end are plain slots — actual nav links,
+ * routing, and auth/user menus belong to the consuming app (doc section 22:
+ * Base must not touch routing or auth), not to this component.
+ */
+export declare function Navbar({ brand, start, end, variant, className }: NavbarProps): import("react").JSX.Element;

package/dist/base/NumberInput.d.ts

@@ -0,0 +1,17 @@
+import { FocusEventHandler } from 'react';
+import { FieldIdentity, FieldPresentation, FieldState } from './shared/fieldTypes';
+export interface NumberInputProps extends FieldIdentity, FieldState, FieldPresentation {
+    value?: number | null;
+    defaultValue?: number | null;
+    onChange?: (value: number | null) => void;
+    onBlur?: FocusEventHandler<HTMLInputElement>;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Composes Input (the "Input foundation" from doc section 19) instead of
+ * reimplementing field markup/controlled-state logic — only the numeric
+ * value coercion is unique to NumberInput.
+ */
+export declare function NumberInput({ value, defaultValue, onChange, min, max, step, ...rest }: NumberInputProps): import("react").JSX.Element;

package/dist/base/PageHeader.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+import { BreadcrumbItem } from './Breadcrumb';
+export interface PageHeaderProps {
+    title: ReactNode;
+    description?: ReactNode;
+    breadcrumbItems?: BreadcrumbItem[];
+    /** Right-aligned slot, typically page-level Buttons. */
+    actions?: ReactNode;
+    className?: string;
+}
+/** Composes Breadcrumb (doc section 20 — reuse, don't re-derive trail markup) for the standard title/breadcrumb/actions row atop a page. */
+export declare function PageHeader({ title, description, breadcrumbItems, actions, className }: PageHeaderProps): import("react").JSX.Element;