@madojs/mado 0.8.0 → 0.10.0

package/README.md

@@ -6,82 +6,107 @@
   />
 
   <p>
-    <strong>A small native-web SPA framework you can read in an evening.</strong>
+    <strong>Build business apps. Keep maintenance boring.</strong>
   </p>
 
   <p>
-    <code>tsc → browser</code> · Zero runtime dependencies · No required bundler
+    Browser-native · TypeScript-first · Zero runtime dependencies
   </p>
 </div>
 
 
 # Mado
 
-> A small native-web SPA framework you can read in an evening.
+> A calm frontend stack for internal tools, admin panels and business SPA.
 
 [![npm](https://img.shields.io/npm/v/@madojs/mado.svg)](https://www.npmjs.com/package/@madojs/mado)
 [![CI](https://github.com/madojs/mado/actions/workflows/ci.yml/badge.svg)](https://github.com/madojs/mado/actions/workflows/ci.yml)
 [![Browser Regression](https://github.com/madojs/mado/actions/workflows/browser.yml/badge.svg)](https://github.com/madojs/mado/actions/workflows/browser.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-Mado is a thin TypeScript framework on top of the browser platform: Web
-Components, signals, tagged-template `html`, a router, resources, forms,
-context, persisted state and static prerender. No runtime dependencies, no
-required bundler, no hidden build pipeline: `tsc → browser`.
+Mado is a browser-native SPA framework for teams that want routing, forms,
+data fetching and state management — without turning their frontend into an
+infrastructure project.
 
-Mado (`窓`) means “window” in Japanese: a calm native-web window into an app,
-without dragging a whole frontend factory into the room.
+You write TypeScript, run `tsc`, and open the browser. No JSX transform, no
+Vite required, no hidden build pipeline. The entire runtime is readable in an
+evening. When something breaks, you can read the source and fix it.
 
-Mado does not try to replace the browser platform. The browser already gives
-us modules, custom elements, attributes, events, forms, CSS, URLs, history,
-fetch and the DOM. Mado's job is to make those primitives comfortable enough
-for small and serious applications, without taking away your understanding of
-what is happening.
+Mado (`窓`) means "window" in Japanese: a calm window into your app, without
+dragging a whole frontend factory into the room.
 
-```txt
-Runtime budget after build:
-  native ESM graph: ~60 KB raw, ~24 KB gzip across separate modules
-  bundled/minified full API: ~32 KB raw, ~11 KB gzip, ~10 KB brotli
-Runtime dependencies: 0
-Required dev dependency: typescript
-```
+## When to use Mado
+
+- **Admin panels and dashboards** — forms, tables, filters, auth, role guards.
+- **Internal tools and backoffice** — CRUD workflows, settings, billing UI.
+- **Small SaaS frontends** — where long-term maintainability matters more than
+  ecosystem size.
+- **Embedded widgets** — where small footprint and independence from host
+  frameworks matter.
+
+The common thread: apps where **the frontend should not become its own
+infrastructure problem**.
+
+## When not to use Mado
+
+- **SEO-heavy public sites** that need SSR with hydration.
+- **Large teams optimizing for hiring compatibility** — React/Vue have bigger
+  talent pools.
+- **Projects that need a mature UI-kit ecosystem** comparable to React today.
+- **Beginners learning frontend** — React, Vue and Svelte have far larger
+  learning resources.
+- **Teams uncomfortable with a pre-v1 framework** — Mado is honest about its
+  stage.
 
-## Who It Is For
+## What Mado will not build
 
-- Backend developers who need admin panels, dashboards or internal tools
-  without learning another build stack first.
-- Frontend developers who like the browser platform and want a compact,
-  readable tool instead of a large ecosystem contract.
-- Small teams that value ownership: if something breaks, `src/` is small
-  enough to inspect and patch.
-- Landing pages, widgets, embedded tools and CRUD-heavy SPA surfaces where
-  predictable code matters more than framework fashion.
+Mado stays useful by saying no. These are intentionally out of scope:
 
-## Who It Is Not For
+- SSR with hydration. Use `bake` or edge prerender for SEO-oriented static
+  output.
+- A template compiler, JSX transform, or VDOM compatibility layer.
+- A separate store library. Use `signal()`, `computed()` and `resource()`.
+- Suspense primitives or a router plugin system.
+- Built-in i18n, animation, or virtual-scroll primitives.
+- Non-evergreen browser support. The baseline is modern evergreen browsers with
+  Baseline 2023 platform features.
 
-- Beginners learning frontend for the first time. React, Vue and Svelte have
-  far larger learning ecosystems.
-- Teams that need a ready-made UI-kit ecosystem comparable to React.
-- Products that require SSR with hydration as a hard requirement.
-- Projects that need a mature plugin marketplace today.
-- Teams that are uncomfortable using a pre-v1 framework.
+## Why teams pick Mado
 
-## Why Not Lit, Solid Or htmx?
+| What matters to you | Best choice |
+|---|---|
+| Largest ecosystem, most hires available | React or Vue |
+| Reusable design-system components across host frameworks | Lit |
+| Maximum rendering performance, JSX workflow | Solid or Svelte 5 |
+| Progressive enhancement of server-rendered pages | htmx + your backend |
+| Full app stack with minimal infrastructure and calm maintenance | **Mado** |
+
+**Honest tradeoffs:**
+
+- **vs Lit** — Lit is better for design systems. Mado is for whole apps:
+  router, data, forms and prerender in one package, no assembly required.
+- **vs Solid** — Solid is faster and more mature. It also requires Vite + a
+  babel plugin. Mado requires nothing but `tsc`.
+- **vs htmx** — htmx is excellent when your backend owns HTML. Mado is for
+  cases where you want a real SPA: local state, optimistic updates, cached
+  resources, lazy modules and persisted UI state.
+
+## What you get
 
-Short honest version:
+Routing, forms, state, data fetching and prerendering — without ecosystem tax:
 
-- **Lit** is better for design systems and reusable components that must live
-  inside many host frameworks. Mado is for whole apps: router, data, forms and
-  SEO tools in one small package.
-- **Solid** is faster and more mature. It also expects a JSX transform and a
-  build pipeline. Mado intentionally works with browser ESM and `tsc`.
-- **htmx** is excellent when your backend wants to own HTML fragments. Mado is
-  for cases where you still want an SPA: local state, optimistic updates,
-  cached resources, query params, lazy modules and persisted UI state.
+- No runtime dependencies to audit, update or break
+- No bundler required to start (`tsc` is enough)
+- Fewer moving parts to debug
+- Compact API surface you can learn in a day
+- Lower long-term cognitive load
 
-Mado does not try to win synthetic benchmark marketing. It avoids a Virtual DOM,
-uses fine-grained signals and keyed DOM reconciliation, and aims to stay fast
-enough for serious admin apps while remaining small and readable.
+```txt
+Runtime budget:
+  enforced in CI with npm run size
+Runtime dependencies: 0
+Required dev dependencies: typescript, esbuild, linkedom
+```
 
 ## Quick Start
 
@@ -94,8 +119,8 @@ npm install
 npm run dev
 ```
 
-Use the admin starter when you want the blessed production shape out of the box:
-layouts, guards, auth/API client, dev proxy, forms and a small admin shell.
+The admin starter gives you the blessed production shape: layouts, guards,
+auth/API client, forms and a small admin shell.
 
 ```bash
 npm exec --package @madojs/mado@latest -- mado init dashboard --starter admin
@@ -104,151 +129,56 @@ npm install
 npm run dev
 ```
 
-Use the CRUD starter when you want a compact resource/mutation/forms example:
+The CRUD starter is a compact resource/mutation/forms example:
 
 ```bash
 npm exec --package @madojs/mado@latest -- mado init my-app --starter crud
 ```
 
-### Try the repository examples
+### Try the flagship example
 
 ```bash
 git clone https://github.com/madojs/mado.git
 cd mado
 npm install
 npm run build
-npm run serve -- basic
+npm run serve -- showcase
 ```
 
-### Small component example
+The showcase is a CRM-shaped pressure app with auth, tables, filters, nested
+routes, context services, forms and real data patterns.
 
-```ts
-// src/pages/counter.ts
-import { component, css, html, page, signal } from "@madojs/mado";
+## How it works
 
-component(
-  "x-counter",
-  () => {
-    const count = signal(0);
-    return () => html`
-      <button @click=${() => count.update((n) => n + 1)}>${count}</button>
-    `;
-  },
-  { styles: css`button { padding: .5rem 1rem; }` },
-);
-
-export default page({
-  title: "Counter",
-  view: () => html`<x-counter></x-counter>`,
-});
-```
+### Signals — reactive state
 
 ```ts
-// src/routes.ts
-import { routes } from "@madojs/mado";
-
-export const manifest = {
-  "/": () => import("./pages/counter.js"),
-  "*": () => import("./pages/not-found.js"),
-};
-
-export default routes(manifest);
-```
-
-The developer convenience CLI is available as `mado`:
-
-```bash
-mado init my-app
-mado init dashboard --starter admin
-mado init my-app --starter crud
-mado dev
-mado build
-mado typecheck
-mado test
-mado release
-mado preview
-mado serve basic
-mado dev showcase
-mado examples
-```
-
-## Documentation
-
-- [Language index](./docs/README.md)
-- [English docs](./docs/en/README.md)
-- [Russian docs](./docs/ru/README.md)
-- [Documentation française](./docs/fr/README.md)
-- [Ukrainian docs](./docs/uk/README.md)
-
-Core topics:
-
-- [The Mado way](./docs/en/00-the-mado-way.md)
-- [Routing](./docs/en/01-routing.md)
-- [Project layout](./docs/en/02-project-layout.md)
-- [Static bake & SEO](./docs/en/03-static-bake.md)
-- [IDE setup](./docs/en/04-ide-setup.md)
-- [Why Mado](./docs/en/05-why-mado.md)
-- [For backenders](./docs/en/06-for-backenders.md)
-- [LLM pitfalls](./docs/en/07-llm-pitfalls.md)
-- [Shadow DOM vs Light DOM](./docs/en/09-shadow-vs-light-dom.md)
-- [App architecture](./docs/en/10-app-architecture.md)
-- [Layouts](./docs/en/11-layouts.md)
-- [Auth and API](./docs/en/12-auth-and-api.md)
-- [Deployment](./docs/en/13-deployment.md)
-- [Testing](./docs/en/14-testing.md)
-- [Error handling](./docs/en/15-error-handling.md)
-- [Bake cookbook](./docs/en/16-bake-cookbook.md)
-
-AI-agent entrypoints:
-
-- [AGENTS.md](./AGENTS.md)
-- [llms.txt](./llms.txt)
-
-## Examples
-
-- [`examples/basic`](./examples/basic/) — minimal API tour.
-- [`examples/tickets`](./examples/tickets/) — LLM zero-history CRUD validation.
-- [`examples/showcase`](./examples/showcase/) — flagship SaaS CRM pressure app.
-- [`examples/cloudflare`](./examples/cloudflare/) — edge prerender / deployment PoC.
-
-## Core API
-
-### Signals
-
-```ts
-import { batch, computed, effect, flushSync, signal } from "@madojs/mado";
+import { signal, computed, effect } from "@madojs/mado";
 
 const count = signal(0);
 const doubled = computed(() => count() * 2);
-
 effect(() => console.log(count()));
 
-batch(() => {
-  count.set(1);
-  count.set(2);
-});
-
-flushSync();
+count.set(1);
 ```
 
-Signals are getter functions: read with `count()`, write with `count.set(next)`
+Signals are getter functions: read with `count()`, write with `count.set(v)`
 or `count.update(fn)`.
 
-### Templates
+### Templates — tagged template html
 
 ```ts
-html`<button @click=${fn} ?disabled=${loading} class=${className}>${label}</button>`;
+html`<button @click=${fn} ?disabled=${loading} class=${cls}>${label}</button>`;
 ```
 
-- Child bindings accept text, nodes, arrays, nested `html```, and `each(...)`.
-- `attr=${v}` writes an attribute.
-- `@event=${fn}` attaches an event listener.
-- `.prop=${v}` writes a DOM property.
-- `?attr=${flag}` toggles a boolean attribute.
-- Function values, including signals and computed values, are tracked
-  reactively.
+- `${value}` — child content (text, nodes, arrays, nested `html`, `each`)
+- `@event=${fn}` — event listener
+- `attr=${v}` — attribute
+- `.prop=${v}` — DOM property
+- `?attr=${flag}` — boolean attribute
+- Functions and signals are tracked reactively
 
-### Components
+### Components — Web Components
 
 ```ts
 import { component, css, html } from "@madojs/mado";
@@ -257,55 +187,30 @@ component(
   "x-card",
   () => () => html`<section><slot></slot></section>`,
   {
-    styles: css`
-      :host { display: block; }
-      section { padding: 1rem; border: 1px solid var(--border); }
-    `,
+    styles: css`:host { display: block; padding: 1rem; }`,
   },
 );
 ```
 
-Components are Custom Elements. Shadow DOM is enabled by default. Use
-`{ shadow: false }` for app shells and admin layouts that should inherit global
-utility classes.
-
-### Lists
-
-```ts
-import { each } from "@madojs/mado";
-
-html`
-  <ul>
-    ${() => each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`)}
-  </ul>
-`;
-```
-
-`each()` performs keyed reconciliation and reuses DOM nodes across reorder,
-insert and delete operations.
-
-### Routing
+### Routing — file-based-free
 
 ```ts
 import { routes } from "@madojs/mado";
 
-export const manifest = {
+export default routes({
   "/": () => import("./pages/home.js"),
   "/users/:id": () => import("./pages/user-detail.js"),
   "*": () => import("./pages/not-found.js"),
-};
-
-export default routes(manifest);
+});
 ```
 
-The router provides lazy page loading, nested routes, query params, hover
-prefetch, async stale guards, loading delay, View Transitions support and
-`dispose()` for tests/dev overlays.
+Lazy loading, nested routes, query params, guards, hover prefetch, scroll
+restoration, error boundary, View Transitions.
 
-### Data
+### Data — resource + mutation
 
 ```ts
-import { invalidate, jsonFetcher, mutation, resource } from "@madojs/mado";
+import { resource, mutation, invalidate, jsonFetcher } from "@madojs/mado";
 
 const user = resource(
   () => `/api/users/${userId()}`,
@@ -316,18 +221,19 @@ const user = resource(
 const save = mutation(api.saveUser, {
   invalidates: ["/api/users*"],
 });
-
-await save.run(values);
-invalidate("/api/users*");
 ```
 
-`resource()` handles cache, loading/error state, aborts, refresh and optimistic
-local `mutate()`. Inside `component()` setup it is lifecycle-aware.
+Cache, loading/error state, abort, refresh, optimistic `mutate()`,
+glob-based invalidation. Lifecycle-aware inside components.
+
+Resource keys are the cache identity. Use keys that include the endpoint, params
+and data shape; two resources with the same key share cached data and in-flight
+requests.
 
-### Forms
+### Forms — schema-based validation
 
 ```ts
-import { html, useForm } from "@madojs/mado";
+import { useForm, html } from "@madojs/mado";
 
 const form = useForm({
   email: { required: true, type: "email" },
@@ -342,39 +248,86 @@ html`
 `;
 ```
 
-Validation is schema-based and intentionally close to native HTML constraints:
-`required`, `min`, `max`, `pattern`, `type=email/url/number`, plus optional
-custom `validate(values)`. Async validators and field arrays are available via
-`validateAsync`, `validateField()` and `form.array("items")`.
+HTML-like constraints (`required`, `min`, `max`, `pattern`, `type`), async
+validators, field arrays. Close to the platform, not fighting it.
 
-Only the root import is the stable public API:
+### Lists — keyed reconciliation
 
 ```ts
-import { html, component, signal } from "@madojs/mado";
+import { each } from "@madojs/mado";
+
+html`<ul>${() => each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`)}</ul>`;
 ```
 
-Deep imports may exist in the package for tooling and generated files, but they
-are internal and can change before v1.
+### Static prerender — SEO without SSR
 
-## Static HTML Without Hydration
+```bash
+mado release
+```
+
+Build-time prerender of routes into static HTML with meta tags and JSON-LD.
+No hydration runtime. For dynamic content, see the Cloudflare edge-prerender
+PoC in [`examples/cloudflare`](./examples/cloudflare/).
 
-Mado intentionally does not ship SSR with hydration. For SEO-oriented pages it
-offers `bake`: build-time prerender of finite routes into HTML with meta tags,
-JSON-LD and baked data. For very large or changing catalogs, see the
-Cloudflare Worker edge-prerender PoC in [`examples/cloudflare`](./examples/cloudflare/).
+## Production
+
+```bash
+mado release    # typecheck + build + bundle + bake + copy public -> out/
+mado preview    # serve out/ like a static host
+```
 
-## Production Bundle
+One command, one artifact (`out/`). Upload anywhere: VPS, Cloudflare Pages,
+any static CDN.
 
-Native ESM is the default development path. For production, use the one-command
-release pipeline:
+## CLI
 
 ```bash
-mado release
-mado preview
+mado init my-app              # scaffold new app
+mado init dashboard --starter admin
+mado dev                      # dev server with hot reload
+mado build                    # tsc compile
+mado typecheck                # type check without emit
+mado test                     # run test suite
+mado release                  # full production build
+mado preview                  # serve production build locally
 ```
 
-`release` runs typecheck, build, bundle, bake and public asset copy, then writes
-the deployable artifact into `out/`. `preview` serves `out/` like a static host.
+## Documentation
+
+- [The Mado way](./docs/en/00-the-mado-way.md) — conventions and principles
+- [Routing](./docs/en/01-routing.md)
+- [Project layout](./docs/en/02-project-layout.md)
+- [Static bake & SEO](./docs/en/03-static-bake.md)
+- [App architecture](./docs/en/10-app-architecture.md)
+- [Layouts](./docs/en/11-layouts.md)
+- [Auth and API](./docs/en/12-auth-and-api.md)
+- [Deployment](./docs/en/13-deployment.md)
+- [Testing](./docs/en/14-testing.md)
+- [Error handling](./docs/en/15-error-handling.md)
+- [For backend developers](./docs/en/06-for-backenders.md)
+- [Why Mado (detailed comparison)](./docs/en/05-why-mado.md)
+
+Localized docs: [French](./docs/fr/README.md) · [Ukrainian](./docs/uk/README.md) · [Russian](./docs/ru/README.md) 
+
+AI-agent entrypoints: [AGENTS.md](./AGENTS.md) · [llms.txt](./llms.txt)
+
+## Examples
+
+- [`examples/showcase`](./examples/showcase/) — flagship CRM pressure app
+  (auth, tables, filters, forms, nested routes, context services).
+- [`examples/tickets`](./examples/tickets/) — CRUD validation app.
+- [`examples/basic`](./examples/basic/) — minimal API tour.
+- [`examples/cloudflare`](./examples/cloudflare/) — edge prerender PoC.
+
+## Known Limits
+
+| Limit | What it means |
+|---|---|
+| No SSR hydration | Use `bake` or edge prerender for SEO. Server rendering is out of scope. |
+| Small ecosystem | No UI-kit or plugin marketplace. You own your components. |
+| Pre-v1 API | Public API is small and intentional, but may change before v1. |
+| Evergreen browsers only | Modern Chrome, Edge, Firefox, Safari. No IE/legacy. |
+| Template IDE support | `html`` highlighting needs lit-plugin or similar. |
 
 ## Tests
 
@@ -385,25 +338,14 @@ npm test
 npm run test:browser
 ```
 
-The test suite covers signals, computed values, effects, dynamic dependencies,
-the html parser, keyed reconciliation, resources, mutations, forms, router
-isolation, component lifecycle and example smoke tests.
-
-## Known Limits
-
-| Limit | Meaning |
-|---|---|
-| No SSR hydration | Use `bake` or edge prerender for SEO. Per-user server rendering is intentionally out of scope for now. |
-| Small ecosystem | No plugin marketplace or UI-kit ecosystem comparable to React. |
-| Template IDE support needs plugins | `html`` syntax highlighting/type tooling usually needs lit-plugin or similar tooling. |
-| Evergreen browsers | Targets modern Chrome/Edge/Firefox/Safari. Legacy browsers are out of scope. |
-| Pre-v1 API | Public API is intentionally small, but v0.x may still change before v1. |
+Covers signals, computed, effects, html parser, keyed reconciliation, resources,
+mutations, forms, router isolation, component lifecycle and example smoke tests.
 
 ## Contributing
 
-Read [CONTRIBUTING.md](./CONTRIBUTING.md). The short version: bug fixes with
-tests, docs improvements, examples and carefully discussed small core changes
-are welcome. Runtime dependencies are not.
+Read [CONTRIBUTING.md](./CONTRIBUTING.md). Bug fixes with tests, docs
+improvements, examples and carefully discussed core changes are welcome.
+Runtime dependencies are not.
 
 ## License