@furcrer/fullstack-components 0.1.0

package/README.md

@@ -0,0 +1,328 @@
+# FullStack Components
+
+Universal React + TypeScript component and application library.
+
+## Current foundation
+
+The repository currently provides:
+
+- automatically discovered React components and generated metadata
+- a local component playground with props, events, fixtures, zoom, pan and responsive viewport modes
+- reusable native form primitives and accessible state components
+- an accessible Modal/Dialog with focus management
+- generic Table, Resource, form and CRUD abstractions
+- framework-agnostic API adapters
+- theme tokens with light/dark foundations and runtime theme validation
+- `ThemeProvider` / `useTheme` with light, dark and system modes
+- automated typecheck, test, build, package-consumer and browser validation
+
+The project is intentionally backend-agnostic. React components do not depend on a specific database, API framework or application framework.
+
+## Architecture
+
+The library is built in layers:
+
+1. Primitive UI components
+2. Composed components
+3. Forms and validation
+4. Data and table components
+5. Resource/API abstractions
+6. CRUD workflows
+7. Development preview and automatic metadata generation
+
+Components are discovered automatically from `src/components`, with data and form component directories also included in the development discovery configuration. The tooling generates metadata and a registry from the source tree instead of requiring manual component registration.
+
+## Development preview
+
+The repository contains a local component playground. It automatically discovers components and displays:
+
+- the component catalog with category information
+- centered live component preview
+- detected props and generated controls
+- emitted events
+- optional custom previews
+- desktop, tablet and mobile viewport modes
+- zoom controls and mouse-wheel zoom
+- canvas panning
+- preview reset
+- light, dark and system theme controls
+
+Inside the preview canvas:
+
+- mouse wheel zooms in and out
+- drag the canvas background to move the preview
+- `+` / `-` change zoom
+- `0` resets zoom and position
+- `Desktop`, `Tablet` and `Mobile` change the preview viewport
+- `Reset` returns the preview to 100% and its centered position
+
+New components should appear automatically after saving their files; the Vite discovery plugin regenerates the registry and reloads the preview.
+
+### Component discovery contract
+
+A public component is discovered from a `.ts` or `.tsx` source file under the configured source directories when the discovery scanner identifies a PascalCase React component export. Discovery metadata includes the component name, category, source path and detected props.
+
+Adjacent `*.fixture.tsx` files provide reusable preview fixtures. An adjacent `*.preview.tsx` file is a curated preview override and takes precedence over a fixture when both exist. Discovery ignores type-only declarations and known fixture/preview/type files rather than exposing them as catalogue entries.
+
+The generated files under `src/generated` are build outputs and are intentionally not handwritten or treated as the source of truth.
+
+## Start locally
+
+Requirements: Node.js 20+ and npm.
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the local URL printed by Vite, normally:
+
+```text
+http://localhost:5173
+```
+
+For validation and library builds:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run test:package
+npm run test:e2e
+```
+
+`npm run build` generates the public component registry, TypeScript declaration files and the Vite library bundle.
+
+`npm run test:package` packs the library exactly as npm would and installs it into a temporary consumer project. The smoke test verifies representative UI, theme, form and data APIs from the package root, checks generic type consumption from a clean TypeScript project and verifies that generated public component declarations are present in the packed package.
+
+## Primitive components
+
+The public UI catalogue includes foundational primitives such as `Badge`, `Button`, `Card`, `Checkbox`, `EmptyState`, `ErrorState`, `FormField`, `IconButton`, `Input`, `Label`, `LoadingState`, `Modal`, `Radio`, `Select`, `StatCard`, `Switch`, `Textarea`, `Skeleton`, `Spinner`, `Alert`, `Progress`, `Avatar`, `Separator`, `Breadcrumb`, `Pagination`, `Tabs`, `Accordion`, `Tooltip`, `DropdownMenu`, `Drawer`, `Toast`, `Heading`, `Text` and `Link`; layout primitives `Stack` and `Grid`; common form controls `NumberInput`, `SearchInput`, `PasswordInput`, `DateInput`, `ColorInput`, `FileInput`, `Slider` and `RadioGroup`; plus the data-oriented `Table`, `ResourceTable` and discovered form infrastructure components.
+
+Native HTML semantics are preferred for interactive primitives. For example:
+
+```tsx
+import {
+  Button,
+  Checkbox,
+  FormField,
+  Input,
+  Select,
+} from "@furcrer/fullstack-components";
+
+export function Example() {
+  return (
+    <form>
+      <FormField label="Email" type="email" required />
+      <Input aria-label="Search" placeholder="Search" />
+      <Select
+        aria-label="Sort order"
+        options={[
+          { value: "name", label: "Name" },
+          { value: "price", label: "Price" },
+        ]}
+      />
+      <label>
+        <Checkbox />
+        Accept terms
+      </label>
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+`Button` supports `primary`, `secondary` and `ghost` variants, `small`/`medium`/`large` sizes and a `loading` state. Loading automatically disables the native button and exposes `aria-busy="true"`.
+
+`Modal` requires `open` and `title`, supports optional `onClose`/`dismissible`, moves focus into the dialog, traps Tab navigation while open, closes on Escape when dismissible and restores focus to the trigger when it closes.
+
+## Forms API
+
+The form infrastructure is framework-light and can be used without a specific API library.
+
+```tsx
+import {
+  FormProvider,
+  FormSubmit,
+  createFormStore,
+  useFormState,
+} from "@furcrer/fullstack-components";
+
+type FormValues = {
+  name: string;
+};
+
+const store = createFormStore<FormValues>({
+  initialValues: { name: "" },
+  validate: async (values) =>
+    values.name.trim() ? {} : { name: "Name is required." },
+  onSubmit: async (values) => {
+    console.log(values.name);
+  },
+});
+
+function SubmitState() {
+  const { submitting, status } = useFormState<FormValues>();
+  return <span>{submitting ? "Saving…" : status}</span>;
+}
+
+export function FormExample() {
+  return (
+    <FormProvider store={store}>
+      <form onSubmit={(event) => { event.preventDefault(); void store.submit(); }}>
+        <input
+          name="name"
+          value={store.getState().values.name}
+          onChange={(event) => store.setValue("name", event.target.value)}
+        />
+        <FormSubmit>Save</FormSubmit>
+        <SubmitState />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+For strongly typed field-level bindings, use `createFieldController` or the `BoundFormField` API. `BoundFormField` is the form-state-aware field component exported under an explicit name because the generated visual `FormField` already uses that name at the package root.
+
+The forms family also includes `FormReset`, adapters and `createResourceForm` for resource-backed create/edit flows.
+
+## Data, tables and resources
+
+`Table` is the low-level generic table. It accepts typed row data and typed column definitions while preserving native table semantics.
+
+```tsx
+import { Table, type TableColumn } from "@furcrer/fullstack-components";
+
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+const columns: TableColumn<Product>[] = [
+  { key: "name", header: "Name" },
+  { key: "price", header: "Price", render: (value) => `${String(value)} €` },
+];
+
+export function ProductTable({ products }: { products: Product[] }) {
+  return (
+    <Table
+      caption="Products"
+      data={products}
+      columns={columns}
+      emptyState="No products found."
+    />
+  );
+}
+```
+
+For resource-backed tables and CRUD, use a `Resource<TData, TId>` implementation with `ResourceController`, `ResourceTable` or `useResourceCrud`.
+
+```ts
+import {
+  createArrayResource,
+  createResourceController,
+} from "@furcrer/fullstack-components";
+
+const products = createArrayResource("products", [
+  { id: "1", name: "Phone", price: 499 },
+]);
+
+const controller = createResourceController(products);
+
+await controller.list({
+  page: 1,
+  pageSize: 10,
+  search: "phone",
+});
+
+await controller.update("1", { price: 449 });
+```
+
+`createArrayResource` is intended for local/in-memory examples and development workflows. `createApiResource` adapts a typed `ApiClient` to the same `Resource` contract, while `createFetchApiClient` provides a framework-agnostic fetch implementation.
+
+## CRUD workflow
+
+A typical resource-backed CRUD flow is:
+
+1. create or inject a `Resource<TData, TId>`
+2. create a `ResourceController` or use `useResourceCrud`
+3. render data with `ResourceTable`
+4. use `createResourceForm` for typed create/edit form state
+5. refresh/list through the controller after mutations
+6. surface controller/form errors through the provided state objects
+
+`CrudExample` in the component catalogue is a working in-repository example of this workflow, including create, edit, delete, validation, busy state and event reporting.
+
+## Theme API
+
+Wrap application content in `ThemeProvider` to enable runtime theme variables. The `system` mode follows the user's `prefers-color-scheme` preference.
+
+```tsx
+import {
+  ResourceTable,
+  StatCard,
+  ThemeProvider,
+  createArrayResource,
+} from "@furcrer/fullstack-components";
+
+const orders = createArrayResource("orders", [
+  { id: "1", name: "First order" },
+]);
+
+export function App() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <main>
+        <StatCard label="Orders" value="128" trend="up" trendValue="+12%" />
+        <ResourceTable resource={orders} columns={[{ key: "name", header: "Name" }]} />
+      </main>
+    </ThemeProvider>
+  );
+}
+```
+
+`ThemeProvider` supports `light`, `dark` and `system` modes and injects the `--fsc-*` token variables into the document root or a supplied container. Use `useTheme()` inside the provider to read `mode`, `resolvedMode`, the active theme and `setMode`.
+
+The theme model also exposes `createTheme`, `defaultTheme`, `darkTheme`, `applyTheme`, `themeToCss`, `themeToCssVariables` and `validateTheme` for consumers that need lower-level control.
+
+The library entrypoint loads the CSS layer used by the visual components.
+
+## Accessibility
+
+Public components follow the accessibility contract in `src/components/ACCESSIBILITY.md`.
+
+The baseline includes native control semantics, accessible naming, validation relationships, live status/error regions, dialog focus management, keyboard behaviour and table semantics. Accessibility contracts are backed by automated tests where practical.
+
+Important consumer rules remain simple:
+
+- give standalone interactive controls an accessible name
+- use labels for form controls instead of visual text alone
+- provide useful `aria-describedby` content when additional instructions or validation messages describe a control
+- keep native disabled controls genuinely disabled
+- do not rely on colour alone to communicate status
+- keep focus visible
+
+## Package API
+
+The package root exports generated public components together with shared types, tokens, themes, forms and data abstractions from `src/index.ts`.
+
+The public UI surface is generated from the component catalogue. The root API also exposes theme utilities, form state/controllers, resource/data APIs, CRUD hooks and fetch-based API adapters.
+
+The root intentionally keeps the generated visual `FormField` separate from the form-state-aware `BoundFormField` name.
+
+The package currently uses version `0.1.0`. Publishing is still intentionally manual and should happen only after the complete CI pipeline is green and npm credentials/configuration are available.
+
+## Release readiness
+
+The repository has automated verification for:
+
+- TypeScript typechecking
+- unit/integration tests
+- production package build and declaration generation
+- packed npm consumer imports and type consumption
+- critical playground browser flows
+- responsive narrow-viewport browser checks
+
+Remaining work is focused on release polish: completing the public API audit, deeper accessibility/theme coverage, final successful CI verification after the latest audit commits, and the eventual 1.0.0/release decision.