@kode4/react-foundation 0.1.0

package/layout/TopBar/TopBar.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react';
+import type { MenuItem } from '../../router/menu';
+import './TopBar.css';
+export type TopBarProps = {
+    items: MenuItem[];
+    /** Rendered at the far left — typically the app's brand link. */
+    brand?: ReactNode;
+    /** Rendered at the far right — typically an auth/user widget. */
+    end?: ReactNode;
+    /**
+     * Menu rendered inside the mobile drawer. Defaults to `items`; pass the full
+     * nested menu tree here so phone/tablet users reach every page (including the
+     * sub-navigation that a SideBar would show on desktop).
+     */
+    mobileMenu?: MenuItem[];
+    /**
+     * Hard floor: at/below this query the inline nav ALWAYS collapses to the
+     * drawer, even if it would fit. Above it, the nav collapses automatically the
+     * moment its items no longer fit the available width (overflow detection), so
+     * it adapts to the menu length and device — e.g. an iPad in portrait. Pass
+     * `null` to rely purely on overflow detection.
+     */
+    mobileQuery?: string | null;
+};
+/**
+ * Responsive top navigation. The inline nav is shown while it fits; when its
+ * items would overflow the available width it collapses into a hamburger that
+ * opens a left-side drawer. Collapsing is content-aware (measured, not a fixed
+ * breakpoint), so it adapts to the number/length of menu items and to the
+ * device — phones and iPads in portrait get the drawer out of the box.
+ */
+export declare function TopBar({ items, brand, end, mobileMenu, mobileQuery, }: TopBarProps): import("react").JSX.Element;

package/layout/TopBar/index.d.ts

@@ -0,0 +1 @@
+export * from './TopBar';

package/layout/index.d.ts

@@ -0,0 +1,12 @@
+export * from './AppLayout';
+export * from './CenteredLayout';
+export * from './Columns';
+export * from './Container';
+export * from './DashboardGrid';
+export * from './FillHeight';
+export * from './Footer';
+export * from './Header';
+export * from './SideBar';
+export * from './SiteLayout';
+export * from './SkipLink';
+export * from './TopBar';

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@kode4/react-foundation",
+	"version": "0.1.0",
+	"description": "Typed router, themed UI component library, and design system for kode4 projects.",
+	"keywords": [
+		"react",
+		"react-router",
+		"typed-router",
+		"component-library",
+		"design-system",
+		"radix-ui",
+		"tailwind",
+		"shadcn"
+	],
+	"license": "MIT",
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": [
+		"*.css"
+	],
+	"main": "./index.js",
+	"module": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./router/context": {
+			"types": "./router/context.d.ts"
+		},
+		"./styles.css": "./style.css"
+	},
+	"peerDependencies": {
+		"react": "^19.2.7",
+		"react-dom": "^19.2.7",
+		"react-router-dom": "^7.17.0",
+		"zod": "^4.4.3",
+		"@tanstack/react-query": "^5.101.0"
+	},
+	"dependencies": {
+		"radix-ui": "^1.5.0",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"lucide-react": "^1.18.0",
+		"cmdk": "^1.1.1",
+		"sonner": "^2.0.7",
+		"react-hook-form": "^7.78.0"
+	}
+}

package/query/index.d.ts

@@ -0,0 +1 @@
+export * from './sort';

package/query/sort.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generic sort descriptors, shared across data-fetching code.
+ *
+ * The string values (`'ASC'` / `'DESC'`) match the common backend convention,
+ * so a `SortOrder` can be sent straight to an API as a query/body param. Use
+ * `SortOrderInput` wherever an endpoint accepts either a single sort or a
+ * prioritized list of sorts.
+ */
+export declare enum SortDirection {
+    Asc = "ASC",
+    Desc = "DESC"
+}
+export type SortOrder = {
+    /** The field/property to sort by. */
+    property: string;
+    direction: SortDirection;
+};
+/** One sort, or a prioritized list of sorts (first has highest priority). */
+export type SortOrderInput = SortOrder | SortOrder[];

package/router/DefaultErrorBoundary.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Default route error boundary. Delegates rendering to ErrorBlock.
+ * Used by the router adapter as the fallback for every route.
+ */
+export declare function DefaultErrorBoundary(): import("react").JSX.Element;

package/router/TypedLink/TypedLink.d.ts

@@ -0,0 +1,22 @@
+import { type LinkProps } from 'react-router-dom';
+import type { IsEmpty } from '../../internal/type-utils';
+import type { RouteDef } from '../types';
+export type TypedLinkProps<TParams, TSearch> = Omit<LinkProps, 'to'> & {
+    route: RouteDef<TParams, TSearch, any>;
+} & (IsEmpty<TParams> extends true ? {
+    params?: TParams;
+    search?: Partial<TSearch>;
+} : {
+    params: TParams;
+    search?: Partial<TSearch>;
+});
+/**
+ * Type-safe link to a route. The route's params/search shape is enforced.
+ *
+ * @example
+ *   <TypedLink route={userDetailRoute} params={{ id: 5 }}>Profile</TypedLink>
+ *   <TypedLink route={projectDetailRoute} params={{ id: 1 }} search={{ tab: 'tasks' }}>
+ *     Tasks
+ *   </TypedLink>
+ */
+export declare function TypedLink<TParams, TSearch>(props: TypedLinkProps<TParams, TSearch>): import("react").JSX.Element;

package/router/TypedLink/index.d.ts

@@ -0,0 +1 @@
+export * from './TypedLink';

package/router/adapter.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentType } from 'react';
+import type { RouteObject } from 'react-router-dom';
+import type { AppContext } from './context';
+import type { AnyRouteDef } from './types';
+/**
+ * Converts a tree of `RouteDef`s into the `RouteObject[]` shape that
+ * React Router's `createBrowserRouter` expects, while populating the
+ * route registry so `pathTo()` works.
+ *
+ * Wraps the entire tree in a pathless root route with an error boundary,
+ * so errors that escape all route-level boundaries (or unmatched URLs)
+ * are always caught.
+ *
+ * Note: every route gets `DefaultErrorBoundary` unless it declares its own.
+ * Errors therefore render inside the nearest layout's outlet rather than
+ * bubbling to a parent route's boundary.
+ *
+ * The `context` is captured in a closure and passed to every loader,
+ * so guards and loaders can reach the auth state, query client, etc.
+ */
+export type BuildRouterOptions = {
+    /** Shown only while the data router boots (not for later suspenses). Defaults to DefaultHydrateFallback. */
+    hydrateFallback?: ComponentType;
+    /** Root error boundary for errors that escape all routes (incl. unmatched URLs). Defaults to DefaultErrorBoundary. */
+    errorBoundary?: ComponentType;
+};
+export declare function buildRouterConfig(routes: AnyRouteDef[], context: AppContext, options?: BuildRouterOptions): RouteObject[];

package/router/chain.d.ts

@@ -0,0 +1,17 @@
+import type { LoaderArgs, LoaderMiddlewareCtx } from './types';
+type Ctx<P, S, D extends Record<string, unknown>> = LoaderMiddlewareCtx<D> & {
+    params: P;
+    search: S;
+};
+type AnyStepFn = (ctx: any) => any;
+declare class Chain<P, S, D extends Record<string, unknown> = Record<string, never>> {
+    private steps;
+    constructor(steps?: AnyStepFn[]);
+    /** Side-effect step (guard, prefetch). Does not contribute to data. */
+    use(fn: (ctx: Ctx<P, S, D>) => void | Promise<void>): Chain<P, S, D>;
+    /** Data step. Returned object is merged into the accumulator. */
+    use<T extends Record<string, unknown>>(fn: (ctx: Ctx<P, S, D>) => T | Promise<T>): Chain<P, S, D & T>;
+    build(): (args: LoaderArgs<P, S>) => Promise<D>;
+}
+export declare function chain<P = unknown, S = unknown>(): Chain<P, S>;
+export {};

package/router/context.d.ts

@@ -0,0 +1,24 @@
+import type { QueryClient } from '@tanstack/react-query';
+/**
+ * Application-level context passed into every loader.
+ *
+ * The library only knows about the query client. Apps inject their own
+ * services (auth, feature flags, …) via TypeScript module augmentation
+ * targeting THIS module (the one that declares the interface):
+ *
+ *   // app code, e.g. src/demo/app/context.ts
+ *   declare module '@/lib/router/context' {
+ *       interface AppContext {
+ *           auth: AuthState;
+ *       }
+ *   }
+ *
+ * (After extraction to a package the target becomes
+ * '@kode4/react-foundation/router/context'.)
+ *
+ * The object passed to `createAppRouter`/`buildRouterConfig` must satisfy
+ * the augmented shape, and loaders/guards see the full type on `context`.
+ */
+export interface AppContext {
+    queryClient: QueryClient;
+}

package/router/createAppRouter.d.ts

@@ -0,0 +1,15 @@
+import { type BuildRouterOptions } from './adapter';
+import type { AppContext } from './context';
+import type { AnyRouteDef } from './types';
+/**
+ * One-step router setup: converts the RouteDef tree and creates the
+ * browser router. Equivalent to
+ * `createBrowserRouter(buildRouterConfig(routes, context, options))`.
+ *
+ * @example
+ *   export const router = createAppRouter([shellRoute, loginRoute], {
+ *       queryClient,
+ *       auth: authState,
+ *   });
+ */
+export declare function createAppRouter(routes: AnyRouteDef[], context: AppContext, options?: BuildRouterOptions): import("react-router").DataRouter;

package/router/defineRoute.d.ts

@@ -0,0 +1,11 @@
+import type { RouteDef } from './types';
+/**
+ * Identity function that exists purely for TypeScript inference.
+ *
+ * When you write `defineRoute({ params: z.object({ id: z.coerce.number() }), ... })`,
+ * TS infers TParams as { id: number } from the Zod schema and threads it through
+ * the loader and component types.
+ *
+ * Use `typeof someRoute` to refer to the inferred type elsewhere.
+ */
+export declare function defineRoute<TParams, TSearch, TData>(def: RouteDef<TParams, TSearch, TData>): RouteDef<TParams, TSearch, TData>;

package/router/index.d.ts

@@ -0,0 +1,11 @@
+export * from './adapter';
+export * from './chain';
+export * from './context';
+export * from './createAppRouter';
+export * from './DefaultErrorBoundary';
+export * from './defineRoute';
+export * from './menu';
+export * from './pathTo';
+export * from './TypedLink';
+export * from './types';
+export * from './useRoute';

package/router/menu.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+import type { AnyRouteDef } from './types';
+/**
+ * Authored by the developer in the manual menu tree.
+ */
+export type MenuRouteNode = {
+    route: AnyRouteDef;
+    label?: string;
+    icon?: ReactNode;
+    children?: MenuNode[];
+};
+export type MenuGroupNode = {
+    group: string;
+    children: MenuNode[];
+};
+export type MenuContentNode = {
+    content: ReactNode;
+};
+export type MenuNode = MenuRouteNode | MenuGroupNode | 'separator' | MenuContentNode;
+/**
+ * Resolved menu items ready for rendering.
+ */
+export type MenuItemRoute = {
+    kind: 'item';
+    label: string;
+    icon?: ReactNode;
+    path: string;
+    children?: MenuItem[];
+};
+export type MenuItemGroup = {
+    kind: 'group';
+    label: string;
+    items: MenuItem[];
+};
+export type MenuItemSeparator = {
+    kind: 'separator';
+};
+export type MenuItemContent = {
+    kind: 'content';
+    content: ReactNode;
+};
+export type MenuItem = MenuItemRoute | MenuItemGroup | MenuItemSeparator | MenuItemContent;
+/**
+ * Resolves a manually-authored `MenuNode[]` tree into renderable `MenuItem[]`.
+ */
+export declare function resolveMenu(nodes: MenuNode[]): MenuItem[];
+/**
+ * Finds the top-level menu item that "owns" the given pathname, matching
+ * the longest prefix first. Only route items are considered.
+ */
+export declare function findActiveTopItem(items: MenuItem[], pathname: string): MenuItemRoute | undefined;

package/router/pathTo.d.ts

@@ -0,0 +1,21 @@
+import type { RouteDef } from './types';
+import type { IsEmpty } from '../internal/type-utils';
+type PathToArgs<TParams, TSearch> = IsEmpty<TParams> extends true ? [] | [args: {
+    search?: Partial<TSearch>;
+}] : [args: {
+    params: TParams;
+    search?: Partial<TSearch>;
+}];
+/**
+ * Produces a fully-qualified URL string for a route, with type-safe params and search.
+ *
+ * @example
+ *   pathTo(userDetailRoute, { params: { id: 5 } })
+ *   pathTo(projectDetailRoute, { params: { id: 5 }, search: { tab: 'tasks' } })
+ *   pathTo(homeRoute) // no params, no search
+ *
+ * Search values are filtered through the route's Zod schema so defaults are
+ * applied and unknown keys are dropped.
+ */
+export declare function pathTo<TParams, TSearch, TData>(route: RouteDef<TParams, TSearch, TData>, ...args: PathToArgs<TParams, TSearch>): string;
+export {};

package/router/types.d.ts

@@ -0,0 +1,72 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { z } from 'zod';
+import type { AppContext } from './context';
+/**
+ * The argument shape passed to a route's typed loader function.
+ * `params` and `search` are validated against the route's Zod schemas.
+ */
+export type LoaderArgs<TParams, TSearch> = {
+    params: TParams;
+    search: TSearch;
+    request: Request;
+    context: AppContext;
+};
+/**
+ * Context available to every middleware step.
+ * Includes loader args (params, search, request, context) plus the
+ * accumulated `data` from prior steps in the chain.
+ */
+export type LoaderMiddlewareCtx<TDeps extends Record<string, unknown> = Record<string, unknown>> = LoaderArgs<unknown, unknown> & {
+    data: TDeps;
+};
+/**
+ * A middleware function for use with `chain().use(...)`.
+ *
+ * - `TResult`: the object this step contributes (merged into data), or `void` for guards/side effects.
+ * - `TDeps`: the accumulated data shape this step requires from prior steps.
+ *
+ * @example
+ *   // Guard that contributes { user } — no deps on prior data
+ *   const requireAuth: LoaderMiddleware<{ user: User }> = ({ context, request }) => { ... };
+ *
+ *   // Guard that reads data.user — depends on requireAuth running first
+ *   function requireRole(role: Role): LoaderMiddleware<void, { user: User }> { ... }
+ */
+export type LoaderMiddleware<TResult extends Record<string, unknown> | void = void, TDeps extends Record<string, unknown> = Record<string, unknown>> = (ctx: LoaderMiddlewareCtx<TDeps>) => TResult | Promise<TResult>;
+export type MenuMeta = {
+    label: string;
+    icon?: ReactNode;
+};
+export type TabDef = {
+    id: string;
+    label: string;
+};
+/**
+ * The single source of truth for a route.
+ *
+ * - Path is the SEGMENT (e.g. "users/:id"), not the full path.
+ * - Params and search are validated by Zod at loader time.
+ * - Loaders are plain typed functions; use guard functions at the top
+ *   for auth checks and similar cross-cutting concerns.
+ * - Components read params/search/data via `useRoute(thisRoute)`.
+ * - Tabs/accordions live in `tabs` metadata + the search schema (URL-as-state),
+ *   not as nested routes.
+ */
+export type RouteDef<TParams = any, TSearch = any, TData = any> = {
+    /** Path segment relative to the parent. Omit for pathless layouts and index routes. */
+    path?: string;
+    params?: z.ZodSchema<TParams>;
+    search?: z.ZodSchema<TSearch>;
+    loader?: (args: LoaderArgs<TParams, TSearch>) => Promise<TData> | TData;
+    component: ComponentType;
+    /** Custom error boundary. Uses useRouteError() internally. Falls back to the default if omitted. */
+    errorBoundary?: ComponentType;
+    /** Menu integration metadata. Routes without this are not auto-rendered in menus. */
+    menu?: MenuMeta;
+    /** Tab metadata for routes whose tabs are state-in-URL (not sub-routes). */
+    tabs?: TabDef[];
+    /** Whether this route is the parent's index route (renders at the parent's path). */
+    index?: boolean;
+    children?: RouteDef<any, any, any>[];
+};
+export type AnyRouteDef = RouteDef<any, any, any>;

package/router/useRoute.d.ts

@@ -0,0 +1,22 @@
+import type { RouteDef } from './types';
+/**
+ * Type-safe access to a route's params, search, and loader data.
+ * This is THE way page components read route state — call it with the
+ * route definition co-located in the same file.
+ *
+ * The schemas on the route are used to parse and coerce values so that the
+ * returned types match what you declared in `defineRoute`. Components never
+ * see invalid data — validation failures throw at the loader boundary and
+ * are caught by the error element.
+ *
+ * @example
+ *   const { params, search, data } = useRoute(userDetailRoute);
+ *   //       ^ { id: number }
+ *   //                ^ { tab: 'profile' | 'posts' }
+ *   //                          ^ { user: User }
+ */
+export declare function useRoute<TParams, TSearch, TData>(route: RouteDef<TParams, TSearch, TData>): {
+    params: TParams;
+    search: TSearch;
+    data: Awaited<TData>;
+};