From 957a403383e492142bc5849a3bb0f591c1f154a9 Mon Sep 17 00:00:00 2001 From: yadroRus <37119397+yadroRus@users.noreply.github.com> Date: Thu, 27 Aug 2026 13:29:48 +0300 Subject: [PATCH] docs: add what-aura-is-not doc --- README.md | 2 +- ROADMAP.md | 5 ++-- docs/guide.md | 1 + docs/what-aura-is-not.md | 49 ++++++++++++++++++++++++++++++++++++++++ package.json | 5 ++-- 5 files changed, 57 insertions(+), 5 deletions(-) create mode 100644 docs/what-aura-is-not.md diff --git a/README.md b/README.md index d7ffb8eb..ee1aed31 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ It runs in the browser; it is not a Node SSR runtime. Your server or static host Current release: **0.3.0** -**Documentation:** [Guide](./docs/guide.md) · [Recipes](./docs/recipes/) · [MAGA](https://github.com/aura-ui/MAGA) · [Playground](./playground/) · [Known limitations](./LIMITATIONS.md) +**Documentation:** [Guide](./docs/guide.md) · [What Aura is not](./docs/what-aura-is-not.md) · [Recipes](./docs/recipes/) · [MAGA](https://github.com/aura-ui/MAGA) · [Playground](./playground/) · [Known limitations](./LIMITATIONS.md) **Development:** [Changelog](./CHANGELOG.md) · [Roadmap](./ROADMAP.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md) diff --git a/ROADMAP.md b/ROADMAP.md index 649cb619..f31ae36a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,8 +1,8 @@ # Aura Router — Roadmap -**Declarative routing for Web Components — what is shipped, what is being built, and why it matters.** +**HTML-first navigation for Web Components and plain pages — what is shipped, what is being built, and why it matters.** -> Current release: `0.3.0` · Updated: 2026-08-25 +> Current release: `0.3.0` · Updated: 2026-08-27 > > [Tutorial](./docs/tutorial.md) · [README](./README.md) · [Guide](./docs/guide.md) · [Recipes](./docs/recipes/README.md) · [Limitations](./LIMITATIONS.md) · [Security](./SECURITY.md) · [Changelog](./CHANGELOG.md) @@ -13,6 +13,7 @@ | Build an app with Aura Router | [Guide](./docs/guide.md) | | See what is already available | [README](./README.md) → [Changelog](./CHANGELOG.md) | | Upgrade an existing HTML site from MPA to SPA | [10-minute tutorial](./docs/tutorial.md) → [MPA → SPA roadmap](#phase-8--mpa--spa) | +| See what Aura is not (vs Turbo / Unpoly / swup / htmx) | [What Aura is not](./docs/what-aura-is-not.md) | | Copy a working pattern | [Recipes](./docs/recipes/README.md) | | Understand what is being built now | [Current focus](#current-focus) | | Contribute to a specific area | [Explore the roadmap](#explore-the-roadmap) | diff --git a/docs/guide.md b/docs/guide.md index 8b59717c..1026de2b 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -59,6 +59,7 @@ Use the [recipes](./recipes/README.md) when you want a focused copy-and-paste pa ## Related documentation - [10-minute tutorial](./tutorial.md) — upgrade two complete HTML pages and verify progressive enhancement +- [What Aura is not](./what-aura-is-not.md) — boundaries vs Turbo / Unpoly / swup / htmx; forms stay in the app - [README](../README.md) — project overview and quick start - [Known limitations](../LIMITATIONS.md) - [Security policy](../SECURITY.md) diff --git a/docs/what-aura-is-not.md b/docs/what-aura-is-not.md new file mode 100644 index 00000000..d7e28b86 --- /dev/null +++ b/docs/what-aura-is-not.md @@ -0,0 +1,49 @@ +# What Aura is not + +Boundaries for [`@auraui/router`](https://www.npmjs.com/package/@auraui/router) — what it does, what it refuses, and how that differs from Turbo, Unpoly, swup, and htmx. + +[Guide](./guide.md) · [Tutorial](./tutorial.md) · [Limitations](../LIMITATIONS.md) + +--- + +## Aura is + +HTML-first **client navigation** on pages your host already serves: opt-in link upgrades (default `data-aura-link`), `extract` / first-paint adopt, nested layouts, route lifecycle. Plain HTML, Web Components, or Lit — no framework adapter, no Aura server. + +Complete documents per URL are the main path; fragment / template / component views are also supported. + +--- + +## Aura is not + +| Not | Meaning | +| --- | ------- | +| React / Vue / TanStack-style SPA router | HTML + URL stay the substrate, not a virtual app tree | +| Turbo / htmx replacement | Upgrades **link navigation**, not a hypermedia app runtime | +| Form / mutation layer | No `
` intercept; mutations stay in the app, then `navigate()` / `invalidate()` | +| Data framework | Has `load` / cache; not a query library. Nav-time SWR not shipped ([Limitations](../LIMITATIONS.md)) | +| Incremental DOM / React-lite | Outlet replace/adopt — no DOM diffing | + +--- + +## vs Turbo / Unpoly / swup / htmx + +| | **Aura** | **Turbo** | **Unpoly** | **swup** | **htmx** | +| -- | -------- | --------- | ---------- | -------- | -------- | +| **Idea** | Opt-in SPA nav on real HTML | Drive + Frames / Streams | PE via HTML attrs | Page transitions + cache | Hypermedia attrs + swaps | +| **Links** | Marker (default `data-aura-link`) | Intercept by default | Attribute-driven | Enhanced nav | `hx-*` | +| **Forms** | No — app + `navigate()` | Yes | Yes | No by default | Yes | +| **Nested UI** | Routes / layouts / `` | Frames | Layers / fragments | Page-oriented | Swap targets | +| **Pick when** | Keep pages; add nested SPA nav + lifecycle | Want Drive/Frames + form PE | Want rich HTML PE / layers | Want transition-focused MPA | Want hypermedia as the model | + +--- + +## Forms + +Router owns **GET navigation**. The app owns submit / upload / validation. + +1. Handle the form in a component or plain JS. +2. `fetch` (or your handler) to the API / endpoint. +3. On success: `router.navigate(...)` / `invalidate()`. + +No-JS form submit = full page load. That is expected, not a gap. diff --git a/package.json b/package.json index b3107155..7f509d2c 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@auraui/router", "version": "0.3.0", - "description": "HTML-first declarative router. Real HTML pages with client navigation (MPA→SPA). Works with plain HTML or Web Components.", + "description": "HTML-first client navigation for real HTML pages (MPA→SPA). Works with plain HTML, Web Components, or Lit.", "type": "module", "main": "./dist/index.js", "module": "./dist/index.js", @@ -21,7 +21,8 @@ "docs/tutorial.md", "docs/guide.md", "docs/guide/*", - "docs/recipes/*" + "docs/recipes/*", + "docs/what-aura-is-not.md" ], "sideEffects": false, "publishConfig": {