create-aziz-app 3.1.1 → 3.1.3

package/template/docs/03-pages-and-layouts.md

@@ -1,140 +1,140 @@
-# 03 · Pages & Layouts
-
-Pages are screens. Layouts wrap screens in shared chrome (nav, footer, providers).
-
-## Pages
-
-A page is a file named `page.js` (or `page.jsx`) that **exports a default component**.
-
-```js
-// app/about/page.js  →  /about
-export default function About() {
-    return (
-        <div>
-            <h1>About</h1>
-            <p>We build lightweight frameworks.</p>
-        </div>
-    );
-}
-```
-
-Rules:
-
-- The file must be named **`page.js`** inside a folder under `app/`.
-- It must have a **default export**.
-- **JSX works out of the box** — no imports needed.
-
-### Pages can use state and hooks
-
-```js
-// app/clock/page.js
-export default function Clock() {
-    const [now, setNow] = useState(new Date());
-
-    useEffect(() => {
-        const id = setInterval(() => setNow(new Date()), 1000);
-        return () => clearInterval(id);   // cleanup runs on unmount
-    }, []);
-
-    return <p>{now.toLocaleTimeString()}</p>;
-}
-```
-
-Hooks are global: `useState`, `useEffect`, `useMemo`, `useRef`, `useReducer`, `useContext`, `useLocalStorage`, `useFetch`, `useApi`, `useRouter`, `useParams`, `useSearchParams`. Full list in [Hooks](./05-hooks.md).
-
-### Page metadata
-
-Export a `metadata` object to set the document title / description per page:
-
-```js
-// app/about/page.js
-export default function About() { /* … */ }
-
-export const metadata = {
-    title: 'About us',
-    description: 'Who we are',
-};
-```
-
-Layout metadata is merged outermost → innermost, and **page metadata wins** for `title`.
-
-## Layouts
-
-A layout is a file named `layout.js` that **exports a default component receiving `{ children }`**:
-
-```js
-// app/layout.js  →  wraps EVERY page
-import Navbar from '/components/Navbar.js';
-import Footer from '/components/Footer.js';
-
-export default function Layout({ children }) {
-    return (
-        <div style={{ display: 'flex', flexDirection: 'column', minHeight: '100vh' }}>
-            <Navbar />
-            <main style={{ flex: 1 }}>{children}</main>
-            <Footer />
-        </div>
-    );
-}
-
-export const metadata = {
-    title: 'My App',
-    description: 'Built with Aziz.js',
-};
-```
-
-`children` is whatever page (or nested layout) the router mounted. Always render it — otherwise nothing below the layout appears.
-
-### Nested layouts
-
-A `layout.js` inside a folder applies to **that folder and everything under it**, outermost-first:
-
-```
-app/layout.js              → wraps /            (root)
-app/about/layout.js        → wraps /about       (and children)
-app/blog/layout.js         → wraps /blog/*
-```
-
-For a request to `/blog/hello`, the chain is:
-
-```
-app/layout.js → app/blog/layout.js → app/blog/[slug]/page.js
-```
-
-Layouts do **not** re-mount when you navigate between sibling routes (their state persists); only the page below them changes.
-
-## The 404 page
-
-`app/not-found.js` renders when no route matches (or a page exports nothing usable):
-
-```js
-// app/not-found.js
-export default function NotFound() {
-    return (
-        <div style={{ padding: '60px 24px', textAlign: 'center' }}>
-            <h1 style={{ fontSize: '72px' }}>404</h1>
-            <p>This page could not be found.</p>
-            <button onClick={() => navigate('/')}>Go Home</button>
-        </div>
-    );
-}
-```
-
-If you don't ship one, a built-in default 404 is used.
-
-## Root entry
-
-`index.html` is the only real HTML file. It defines `<div id="root">`, loads `/_framework/boot.js`, and the client router renders the matching page into `#root`. You normally **don't touch `index.html`** except to add global `<link>`/`<script>` (the CSS-framework flags inject these for you).
-
-## Programmatic navigation from a page
-
-```js
-navigate('/about');                 // global function
-window.__rerenderPage?.();          // force re-render (advanced)
-```
-
-See [Routing](./04-routing.md) for links, params, and search strings.
-
-## Continue
-
-→ [Routing](./04-routing.md)
+# 03 · Pages & Layouts
+
+Pages are screens. Layouts wrap screens in shared chrome (nav, footer, providers).
+
+## Pages
+
+A page is a file named `page.js` (or `page.jsx`) that **exports a default component**.
+
+```js
+// app/about/page.js  →  /about
+export default function About() {
+    return (
+        <div>
+            <h1>About</h1>
+            <p>We build lightweight frameworks.</p>
+        </div>
+    );
+}
+```
+
+Rules:
+
+- The file must be named **`page.js`** inside a folder under `app/`.
+- It must have a **default export**.
+- **JSX works out of the box** — no imports needed.
+
+### Pages can use state and hooks
+
+```js
+// app/clock/page.js
+export default function Clock() {
+    const [now, setNow] = useState(new Date());
+
+    useEffect(() => {
+        const id = setInterval(() => setNow(new Date()), 1000);
+        return () => clearInterval(id);   // cleanup runs on unmount
+    }, []);
+
+    return <p>{now.toLocaleTimeString()}</p>;
+}
+```
+
+Hooks are global: `useState`, `useEffect`, `useMemo`, `useRef`, `useReducer`, `useContext`, `useLocalStorage`, `useFetch`, `useApi`, `useRouter`, `useParams`, `useSearchParams`. Full list in [Hooks](./05-hooks.md).
+
+### Page metadata
+
+Export a `metadata` object to set the document title / description per page:
+
+```js
+// app/about/page.js
+export default function About() { /* … */ }
+
+export const metadata = {
+    title: 'About us',
+    description: 'Who we are',
+};
+```
+
+Layout metadata is merged outermost → innermost, and **page metadata wins** for `title`.
+
+## Layouts
+
+A layout is a file named `layout.js` that **exports a default component receiving `{ children }`**:
+
+```js
+// app/layout.js  →  wraps EVERY page
+import Navbar from '/components/Navbar.js';
+import Footer from '/components/Footer.js';
+
+export default function Layout({ children }) {
+    return (
+        <div style={{ display: 'flex', flexDirection: 'column', minHeight: '100vh' }}>
+            <Navbar />
+            <main style={{ flex: 1 }}>{children}</main>
+            <Footer />
+        </div>
+    );
+}
+
+export const metadata = {
+    title: 'My App',
+    description: 'Built with Aziz.js',
+};
+```
+
+`children` is whatever page (or nested layout) the router mounted. Always render it — otherwise nothing below the layout appears.
+
+### Nested layouts
+
+A `layout.js` inside a folder applies to **that folder and everything under it**, outermost-first:
+
+```
+app/layout.js              → wraps /            (root)
+app/about/layout.js        → wraps /about       (and children)
+app/blog/layout.js         → wraps /blog/*
+```
+
+For a request to `/blog/hello`, the chain is:
+
+```
+app/layout.js → app/blog/layout.js → app/blog/[slug]/page.js
+```
+
+Layouts do **not** re-mount when you navigate between sibling routes (their state persists); only the page below them changes.
+
+## The 404 page
+
+`app/not-found.js` renders when no route matches (or a page exports nothing usable):
+
+```js
+// app/not-found.js
+export default function NotFound() {
+    return (
+        <div style={{ padding: '60px 24px', textAlign: 'center' }}>
+            <h1 style={{ fontSize: '72px' }}>404</h1>
+            <p>This page could not be found.</p>
+            <button onClick={() => navigate('/')}>Go Home</button>
+        </div>
+    );
+}
+```
+
+If you don't ship one, a built-in default 404 is used.
+
+## Root entry
+
+`index.html` is the only real HTML file. It defines `<div id="root">`, loads `/_framework/boot.js`, and the client router renders the matching page into `#root`. You normally **don't touch `index.html`** except to add global `<link>`/`<script>` (the CSS-framework flags inject these for you).
+
+## Programmatic navigation from a page
+
+```js
+navigate('/about');                 // global function
+window.__rerenderPage?.();          // force re-render (advanced)
+```
+
+See [Routing](./04-routing.md) for links, params, and search strings.
+
+## Continue
+
+→ [Routing](./04-routing.md)

package/template/docs/04-routing.md

@@ -1,120 +1,120 @@
-# 04 · Routing
-
-Aziz.js maps files under `app/` to URLs, the same way the Next.js App Router does.
-
-## File → URL table
-
-| File | URL |
-|------|-----|
-| `app/page.js` | `/` |
-| `app/about/page.js` | `/about` |
-| `app/blog/page.js` | `/blog` |
-| `app/blog/[slug]/page.js` | `/blog/:slug` |
-| `app/docs/[...path]/page.js` | `/docs/*` (catch-all) |
-| `app/not-found.js` | (renders 404) |
-
-The file must be named **`page.js`** — that's what registers a route.
-
-## Dynamic segments
-
-Create `app/blog/[slug]/page.js`. Brackets become a **parameter**:
-
-```js
-// app/blog/[slug]/page.js  →  /blog/:slug
-export default function Post() {
-    const { slug } = useParams();
-    return <article>Post: {slug}</article>;
-}
-```
-
-Visiting `/blog/hello-world` renders `Post: hello-world`.
-
-Multiple dynamic segments are fine: `app/shop/[category]/[id]/page.js` → `useParams()` gives `{ category, id }`.
-
-## Catch-all segments
-
-`[...name]` captures **the rest of the path** as an array:
-
-```js
-// app/docs/[...path]/page.js  →  /docs/*
-export default function Docs() {
-    const { path } = useParams();
-    //   /docs/a/b   →  path === ['a', 'b']
-    //   /docs/one   →  path === ['one']
-    return <pre>{JSON.stringify(path, null, 2)}</pre>;
-}
-```
-
-The literal prefix is validated — `/docs/[...path]` will **not** match `/other/a`.
-
-## Route specificity
-
-When several routes could match, the most specific wins:
-
-1. **Static** (`/blog/new`) beats
-2. **Dynamic** (`/blog/[slug]`) beats
-3. **Catch-all** (`/[...all]`)
-
-So with all three present:
-
-- `/blog/new` → static route
-- `/blog/hello` → dynamic route
-- `/other/x` → catch-all route
-
-Trailing slashes are normalized: `/about/` matches `/about`.
-
-## Navigation
-
-### `<Link>` (client-side, no full reload)
-
-```js
-<Link href="/about">About</Link>
-<Link href="/blog/hello" class="nav-link">Post</Link>
-```
-
-`<Link>` intercepts ordinary left-clicks and calls `navigate()`, but **respects** modifier/middle clicks (⌘/Ctrl/Shift/Alt, middle-click) and external/hash/mailto URLs, so the browser behaves normally.
-
-### `navigate()`
-
-```js
-navigate('/about');        // pushState + render
-```
-
-### `useRouter()`
-
-```js
-const { pathname, push, replace, back, forward, refresh, params } = useRouter();
-
-push('/about');
-replace('/search?q=aziz');
-refresh();                 // re-render current route
-```
-
-### `useParams()` / `useSearchParams()`
-
-```js
-const { slug } = useParams();
-
-const search = useSearchParams();
-const q = search.get('q');          // ?q=aziz → "aziz"
-```
-
-### Browser history
-
-The router listens for `popstate`, so Back/Forward work as expected, and scroll position / focus are restored on same-route re-renders.
-
-## Custom 404
-
-See [Pages & Layouts](./03-pages-and-layouts.md#the-404-page) — export a default component from `app/not-found.js`.
-
-## How the router finds pages
-
-1. The dev server scans `app/` and emits `/_framework/routes.json` (the **manifest**).
-2. On boot, the client imports that manifest and `import()`s each `page.js` / `layout.js`.
-3. On every navigation it normalizes the path, resolves the most specific route, collects the layout chain, and mounts it into `#root`.
-
-You can inspect the manifest live at **<http://localhost:3000/_framework/routes.json>**.
-
-## Continue
-
-→ [Hooks](./05-hooks.md)
+# 04 · Routing
+
+Aziz.js maps files under `app/` to URLs, the same way the Next.js App Router does.
+
+## File → URL table
+
+| File | URL |
+|------|-----|
+| `app/page.js` | `/` |
+| `app/about/page.js` | `/about` |
+| `app/blog/page.js` | `/blog` |
+| `app/blog/[slug]/page.js` | `/blog/:slug` |
+| `app/docs/[...path]/page.js` | `/docs/*` (catch-all) |
+| `app/not-found.js` | (renders 404) |
+
+The file must be named **`page.js`** — that's what registers a route.
+
+## Dynamic segments
+
+Create `app/blog/[slug]/page.js`. Brackets become a **parameter**:
+
+```js
+// app/blog/[slug]/page.js  →  /blog/:slug
+export default function Post() {
+    const { slug } = useParams();
+    return <article>Post: {slug}</article>;
+}
+```
+
+Visiting `/blog/hello-world` renders `Post: hello-world`.
+
+Multiple dynamic segments are fine: `app/shop/[category]/[id]/page.js` → `useParams()` gives `{ category, id }`.
+
+## Catch-all segments
+
+`[...name]` captures **the rest of the path** as an array:
+
+```js
+// app/docs/[...path]/page.js  →  /docs/*
+export default function Docs() {
+    const { path } = useParams();
+    //   /docs/a/b   →  path === ['a', 'b']
+    //   /docs/one   →  path === ['one']
+    return <pre>{JSON.stringify(path, null, 2)}</pre>;
+}
+```
+
+The literal prefix is validated — `/docs/[...path]` will **not** match `/other/a`.
+
+## Route specificity
+
+When several routes could match, the most specific wins:
+
+1. **Static** (`/blog/new`) beats
+2. **Dynamic** (`/blog/[slug]`) beats
+3. **Catch-all** (`/[...all]`)
+
+So with all three present:
+
+- `/blog/new` → static route
+- `/blog/hello` → dynamic route
+- `/other/x` → catch-all route
+
+Trailing slashes are normalized: `/about/` matches `/about`.
+
+## Navigation
+
+### `<Link>` (client-side, no full reload)
+
+```js
+<Link href="/about">About</Link>
+<Link href="/blog/hello" class="nav-link">Post</Link>
+```
+
+`<Link>` intercepts ordinary left-clicks and calls `navigate()`, but **respects** modifier/middle clicks (⌘/Ctrl/Shift/Alt, middle-click) and external/hash/mailto URLs, so the browser behaves normally.
+
+### `navigate()`
+
+```js
+navigate('/about');        // pushState + render
+```
+
+### `useRouter()`
+
+```js
+const { pathname, push, replace, back, forward, refresh, params } = useRouter();
+
+push('/about');
+replace('/search?q=aziz');
+refresh();                 // re-render current route
+```
+
+### `useParams()` / `useSearchParams()`
+
+```js
+const { slug } = useParams();
+
+const search = useSearchParams();
+const q = search.get('q');          // ?q=aziz → "aziz"
+```
+
+### Browser history
+
+The router listens for `popstate`, so Back/Forward work as expected, and scroll position / focus are restored on same-route re-renders.
+
+## Custom 404
+
+See [Pages & Layouts](./03-pages-and-layouts.md#the-404-page) — export a default component from `app/not-found.js`.
+
+## How the router finds pages
+
+1. The dev server scans `app/` and emits `/_framework/routes.json` (the **manifest**).
+2. On boot, the client imports that manifest and `import()`s each `page.js` / `layout.js`.
+3. On every navigation it normalizes the path, resolves the most specific route, collects the layout chain, and mounts it into `#root`.
+
+You can inspect the manifest live at **<http://localhost:3000/_framework/routes.json>**.
+
+## Continue
+
+→ [Hooks](./05-hooks.md)