@kode4/react-foundation

A typed application foundation for React: a typed router that turns route definitions into the app's single source of truth, a themed UI component library, and a CSS-variable design system — built to be consumed by humans and by AI agents.

• Typed router as the app spine — declare each route once with defineRoute (path, Zod-validated params/search, loader, typed action, eager or lazyComponent code-split component, document title, menu/tabs metadata); the library derives the React Router v7 config plus typed links (TypedLink with prefetch/viewTransition, pathTo), menus, breadcrumbs, guards via chain(), scroll restoration (window + inner containers), an aria-live route announcer, a designed 404 (notFoundRoute), and onNavigate/onError observability seams.
• UI component library — 70+ components on Radix primitives (shadcn/ui as the blueprint): the full input family (incl. PasswordInput, OTPInput, TagInput, NumberInput, Rating, MaskInput, ComboBox), date/time pickers with a partial-aware value model + DateRangePicker, rich editors (MarkdownEditor, HtmlEditor, SignaturePad), media (Gallery, Video, ZoomImage), a multi-step Wizard (branching, persistence, per-step loaders), EmptyState, DataTable (sorting, pagination, row selection, column visibility, global filter, pinning/resizing, per-column filters, row expanding + grouping/aggregation, CSV export + a virtualization recipe — client or server mode, over TanStack Table), and the layout frames/nav chrome.
• Forms layer — react-hook-form + Zod with 20+ form-bound …Field components (label/description/error wired for you), WizardForm for multi-step forms, and a busy-gate for async fields like uploads.
• Charts — LineChart/BarChart/PieChart over recharts, colored by design tokens (dark mode included).
• File uploads — a headless upload layer (progress, cancel, hashing, dedupe, upload-handle model) behind FileField/ImageField (with cropper).
• Design system — semantic CSS-variable tokens (shadcn standard names) with light/dark mode; re-theme everything without a rebuild, no Tailwind required in your app. Built-in label layer (I18nProvider) for i18n with no framework dependency.
• A11y + tests as a posture — every component is axe-checked in the unit suite, with Playwright end-to-end and pixel visual-regression suites over the showcase demo.

Quick start

Scaffold a ready-wired app (Vite + React + TS, provider stack, typed router, locale routing, sample routes):

npm create @kode4/react-foundation@latest my-app
cd my-app && npm install && npm run dev

Or add the library to an existing app:

npm install @kode4/react-foundation

import { createAppRouter, defineRoute, ThemeProvider } from '@kode4/react-foundation';
import '@kode4/react-foundation/styles.css'; // once, near the app root
import { RouterProvider } from 'react-router-dom';

const homeRoute = defineRoute({ index: true, component: HomePage, title: 'Home' });
const shellRoute = defineRoute({ component: Shell, children: [homeRoute] });

const router = createAppRouter([shellRoute], { queryClient });

export const App = () => (
	<ThemeProvider>
		<RouterProvider router={router} />
	</ThemeProvider>
);

The full bootstrap (providers, menus, guards, theming) is in docs/INSTRUCTIONS.md.

If you are an AI agent building an app on this library, read docs/INSTRUCTIONS.md first — it is written for you. It is the complete consumer contract: the mental model, the typed-router patterns, the component catalog with props and idioms, theming, data/forms recipes, and the pitfall checklist. Follow it and the app comes out idiomatic, type-safe, and themeable.

Documentation

These consumer docs ship inside the npm package, so the links below resolve from node_modules/@kode4/react-foundation:

• docs/INSTRUCTIONS.md — start here. The consumer contract: read it when building or extending an app on the library (router, catalog, theming, data, forms, uploads, effects, errors, testing).
• docs/DESIGN-SYSTEM.md — the theming/token contract: read it when restyling — every token, the -foreground convention, fonts, light/dark mechanics.
• docs/combo-box.md — the ComboBox living spec: read it when working with async sources, value modes, or creatable selects.
• docs/date-picker.md — the date/time design contract: read it when you need the partial-aware value model, ranges, or bounds explained in depth.
• docs/gallery.md — the Gallery carousel/lightbox living spec: read it when composing galleries, slideshows, or the lightbox.

Package entry points

import { Button, defineRoute, useRoute } from '@kode4/react-foundation';
import '@kode4/react-foundation/styles.css'; // batteries-included styles, once near the app root

// Module augmentation target for your app's route context:
declare module '@kode4/react-foundation/router/context' {
	/* extend AppContext */
}

The package is graph-splittable: with a tree-shaking bundler you pay only for the components you import (per-component CSS included), while ./styles.css remains the single batteries-included stylesheet. See docs/INSTRUCTIONS.md §2.1–2.2.

Versioning & upgrades

This package is pre-1.0 and still has deliberate API inconsistencies to settle, so the commitment is about how breaking changes arrive rather than that they never will:

| Bump | May break? | | ------------------------- | ------------------------------------------------------ | | Patch (0.6.0→0.6.1) | No. Fixes, warnings, docs, widened dep ranges. | | Minor (0.6.x→0.7.0) | Yes — always with a ### Breaking migration note. | | Major | Reserved for 1.0.0, once the API is worth freezing. |

Patch upgrades are always safe to take. Minor upgrades are safe to take after reading CHANGELOG.md — which ships inside this package, so you can read it straight from node_modules without visiting the repository. A minor that breaks something without a migration note is a bug; please report it.

Pin ~0.6.0 for patches only, or ^0.6.0 to take minors and read the entries.

Links

• Changelog — CHANGELOG.md (ships with the package)
• Source — https://gitlab.com/kode4/react-foundation
• Report a bug — https://gitlab.com/kode4/react-foundation/-/issues

License: MIT.