@kode4/react-foundation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kode4
+
+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,53 @@
+# @kode4/react-foundation
+
+Typed router, themed UI component library, and design system for kode4 projects.
+
+- **Typed router** — a thin layer over React Router DOM v7 that makes route
+  definitions the single source of truth for paths, params, search, loaders,
+  guards, error boundaries, and menus (all Zod-validated, fully inferred).
+- **UI component library** — 30+ components on Radix primitives (shadcn/ui as
+  the blueprint), styled entirely through CSS variables.
+- **Design system** — semantic tokens with light/dark mode; responsive,
+  touch-first layout frames.
+
+`src/lib` is the library (published as a public npm package). `src/demo` is the
+showcase app that exercises it.
+
+## Quickstart
+
+```bash
+npm install
+npm run dev        # demo at http://localhost:5173
+```
+
+## Scripts
+
+```bash
+npm run build              # typecheck + boundary check + production bundle (demo)
+npm run build:lib          # build the publishable package into dist-lib/
+npm run typecheck          # tsc --noEmit
+npm run lint               # eslint
+npm run format             # prettier --write
+npm run check:boundaries   # enforce lib/demo import boundaries
+```
+
+Publish: `npm run build:lib && npm publish ./dist-lib`.
+
+## Consuming the library
+
+```ts
+import { Button, defineRoute, useRoute } from '@kode4/react-foundation';
+import '@kode4/react-foundation/styles.css'; // once, near the app root
+```
+
+See **[`INSTRUCTIONS.md`](./INSTRUCTIONS.md)** for the full consumer guide (router patterns,
+component catalog, theming, data/forms idioms).
+
+## Docs
+
+- **[`INSTRUCTIONS.md`](./INSTRUCTIONS.md)** — building apps with the library (consumer contract).
+- **[`DESIGN-SYSTEM.md`](./DESIGN-SYSTEM.md)** — theming tokens and the styling contract.
+- **[`CLAUDE.md`](./CLAUDE.md)** — conventions for working inside the library repo.
+- **[`roadmap.md`](./roadmap.md)** — planned components.
+
+License: [MIT](./LICENSE).

package/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured application error. Throw this in your own code
+ * when you want a machine-readable code alongside the message.
+ */
+export declare class AppError extends Error {
+    code: string;
+    details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+/**
+ * Consistent shape for displaying any error, regardless of origin.
+ */
+export type NormalizedError = {
+    code?: string;
+    message: string;
+    details?: unknown;
+    original: unknown;
+};
+/**
+ * Converts any thrown value into a consistent display shape.
+ * Handles AppError, React Router responses, standard Errors,
+ * strings, and unknown values.
+ */
+export declare function normalizeError(error: unknown): NormalizedError;

package/forms/Form/Form.d.ts

@@ -0,0 +1,30 @@
+import { Slot } from 'radix-ui';
+import { type ComponentProps } from 'react';
+import { type ControllerProps, type FieldPath, type FieldValues } from 'react-hook-form';
+import { Label } from '../../ui/Label';
+import './Form.css';
+/**
+ * react-hook-form integration, mirroring shadcn's Form API:
+ * <Form> (FormProvider) → <FormField> (Controller) → <FormItem> with
+ * <FormLabel>/<FormControl>/<FormDescription>/<FormMessage>, all wired for
+ * accessibility (ids, aria-describedby, aria-invalid).
+ */
+export declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, watch, getValues, getFieldState, setError, clearErrors, setValue, setValues, trigger, formState, resetField, reset, handleSubmit, unregister, control, register, setFocus, subscribe, }: import("react-hook-form").FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React.JSX.Element;
+export declare function FormField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: ControllerProps<TFieldValues, TName>): import("react").JSX.Element;
+export declare function useFormField(): {
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: import("react-hook-form").FieldError;
+    id: string;
+    name: string;
+    formItemId: string;
+    formDescriptionId: string;
+    formMessageId: string;
+};
+export declare function FormItem({ className, ...props }: ComponentProps<'div'>): import("react").JSX.Element;
+export declare function FormLabel({ className, ...props }: ComponentProps<typeof Label>): import("react").JSX.Element;
+export declare function FormControl(props: ComponentProps<typeof Slot.Root>): import("react").JSX.Element;
+export declare function FormDescription({ className, ...props }: ComponentProps<'p'>): import("react").JSX.Element;
+export declare function FormMessage({ className, children, ...props }: ComponentProps<'p'>): import("react").JSX.Element | null;

package/forms/Form/index.d.ts

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

package/forms/index.d.ts

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

package/hooks/index.d.ts

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

package/hooks/useMediaQuery.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reactively tracks a CSS media query. Returns whether it currently matches and
+ * updates on change. Use for responsive behaviour that can't be pure CSS — e.g.
+ * swapping an inline nav for a mobile drawer.
+ *
+ *   const isMobile = useMediaQuery('(max-width: 768px)');
+ */
+export declare function useMediaQuery(query: string): boolean;

package/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Public entry point of @kode4/react-foundation. Apps (including the demo)
+ * should import ONLY from here.
+ *
+ * Importing this barrel also loads the design system (theme.css) — no
+ * separate stylesheet import is needed by consumers.
+ *
+ * Convention: every folder in src/lib has an index.ts that re-exports its
+ * children with `export *`, so consumers never need to know the internal
+ * structure. When adding a folder or file, add it to the parent barrel.
+ * Exception: `internal/` folders are private and never re-exported.
+ */
+import './theme.css';
+import './text.css';
+import './surface.css';
+export * from './errors';
+export * from './forms';
+export * from './hooks';
+export * from './layout';
+export * from './query';
+export * from './router';
+export * from './theme';
+export * from './ui';
+export * from './utils';