create-aziz-app 3.1.2 → 3.1.3

package/template/docs/07-api-client.md

@@ -1,151 +1,151 @@
-# 07 · API Client
-
-The API client is the browser-side companion to [API routes](./06-api-routes.md). It's a tiny, dependency-free `fetch` wrapper with JSON handling, timeouts, retries, and typed errors.
-
-A global `api` is available everywhere:
-
-```js
-const users = await api.get('/api/users');
-await api.post('/api/users', { name: 'Aziz' });
-```
-
-You can also import it explicitly:
-
-```js
-import api, { ApiError } from '/_framework/api.js';
-```
-
-## Methods
-
-```js
-await api.get('/api/users');
-await api.post('/api/users', { name: 'Aziz' });
-await api.put('/api/users?id=7', { name: 'B' });
-await api.patch('/api/users/7', { email: 'new@x.com' });
-await api.delete('/api/users/7');
-await api.del('/api/users/7');          // alias
-await api.head('/api/users');           // returns the raw Response
-await api.form('/api/upload', formData);// multipart/form-data
-await api.raw('/api/users');            // returns the raw Response object
-
-// Low-level escape hatch:
-await api.request('/api/users', { method: 'POST', body: { a: 1 } });
-```
-
-### Options (all methods)
-
-```js
-await api.get('/api/search', {
-    query: { q: 'aziz', tag: ['a', 'b'], skip: undefined },  // → ?q=aziz&tag=a&tag=b
-    headers: { Authorization: 'Bearer …' },
-    timeout: 5000,          // ms, 0 disables
-    retries: 2,             // for 5xx/429 only
-    signal,                 // external AbortSignal
-    raw: false,             // true → return the Response, not parsed data
-});
-```
-
-- **`query`** serializes objects; arrays become repeated params; `undefined`/`null` are skipped.
-- **`raw`** returns the untouched `Response` instead of parsed JSON.
-
-## Responses
-
-- JSON responses are parsed automatically (`Content-Type: application/json`).
-- Text-ish responses (`text/*`, html, xml) return the text.
-- **`204`/`205` return `null`.**
-
-## Errors
-
-Failures throw an **`ApiError`** with `status`, `data`, and `url`:
-
-```js
-import { ApiError } from '/_framework/api.js';
-
-try {
-    await api.post('/api/users', bad);
-} catch (err) {
-    if (err instanceof ApiError) {
-        if (err.status === 400) console.warn(err.message, err.data);
-        else if (err.status === 0) console.error('Network/timeout:', err.message);
-        else console.error('Server error', err.status);
-    }
-}
-```
-
-- `err.message` is extracted from the server's `error` / `message` / `detail` field when present.
-- `err.status === 0` means network failure or **timeout** (`"Request timed out after …ms"`).
-
-## Retry policy
-
-| Status | Retried? |
-|--------|----------|
-| `4xx` | **No** (client errors are your bug — retrying won't help) |
-| `429` | Yes (rate limit) |
-| `5xx` | Yes |
-| Network / timeout | Yes |
-
-Backoff is `200ms, 400ms, 800ms…`. `retries` defaults to `0`; set it per request or globally.
-
-```js
-api.configure({ retries: 1, timeout: 10000 });
-```
-
-## Configuration
-
-```js
-api.setBaseURL('https://api.example.com');   // prefix for relative paths
-api.setHeaders({ Authorization: `Bearer ${token}` });
-api.configure({
-    baseURL: 'https://api.example.com',
-    timeout: 15000,
-    retries: 0,
-    headers: { 'X-App': 'aziz' },
-});
-
-console.log(api.defaults);  // { baseURL, timeout, retries, headers }
-```
-
-Defaults are merged under each request's own headers, so per-call `headers` win.
-
-## Declarative fetching: `useFetch`
-
-For read-only data with loading/error state built in, use the [hook](./05-hooks.md#usefetch--useapi):
-
-```js
-const { data, loading, error, refetch } = useFetch('/api/users');
-```
-
-Use **`api`** for imperative flows (POST/PUT, custom retries, non-JSON bodies); use **`useFetch`** for declarative reads.
-
-## Full example: form → API → UI
-
-```js
-function Contact() {
-    const [form, setForm] = useState({ name: '', message: '' });
-    const [status, setStatus] = useState('idle');
-
-    async function submit(e) {
-        e.preventDefault();
-        setStatus('sending');
-        try {
-            await api.post('/api/contact', form);
-            setStatus('sent');
-        } catch (err) {
-            setStatus('error: ' + err.message);
-        }
-    }
-
-    return (
-        <form onSubmit={submit}>
-            <input value={form.name} onInput={e => setForm({ ...form, name: e.target.value })} />
-            <textarea value={form.message} onInput={e => setForm({ ...form, message: e.target.value })} />
-            <button disabled={status === 'sending'}>Send</button>
-            <p>{status}</p>
-        </form>
-    );
-}
-```
-
-## Continue
-
-→ [Styling](./08-styling.md)
+# 07 · API Client
+
+The API client is the browser-side companion to [API routes](./06-api-routes.md). It's a tiny, dependency-free `fetch` wrapper with JSON handling, timeouts, retries, and typed errors.
+
+A global `api` is available everywhere:
+
+```js
+const users = await api.get('/api/users');
+await api.post('/api/users', { name: 'Aziz' });
+```
+
+You can also import it explicitly:
+
+```js
+import api, { ApiError } from '/_framework/api.js';
+```
+
+## Methods
+
+```js
+await api.get('/api/users');
+await api.post('/api/users', { name: 'Aziz' });
+await api.put('/api/users?id=7', { name: 'B' });
+await api.patch('/api/users/7', { email: 'new@x.com' });
+await api.delete('/api/users/7');
+await api.del('/api/users/7');          // alias
+await api.head('/api/users');           // returns the raw Response
+await api.form('/api/upload', formData);// multipart/form-data
+await api.raw('/api/users');            // returns the raw Response object
+
+// Low-level escape hatch:
+await api.request('/api/users', { method: 'POST', body: { a: 1 } });
+```
+
+### Options (all methods)
+
+```js
+await api.get('/api/search', {
+    query: { q: 'aziz', tag: ['a', 'b'], skip: undefined },  // → ?q=aziz&tag=a&tag=b
+    headers: { Authorization: 'Bearer …' },
+    timeout: 5000,          // ms, 0 disables
+    retries: 2,             // for 5xx/429 only
+    signal,                 // external AbortSignal
+    raw: false,             // true → return the Response, not parsed data
+});
+```
+
+- **`query`** serializes objects; arrays become repeated params; `undefined`/`null` are skipped.
+- **`raw`** returns the untouched `Response` instead of parsed JSON.
+
+## Responses
+
+- JSON responses are parsed automatically (`Content-Type: application/json`).
+- Text-ish responses (`text/*`, html, xml) return the text.
+- **`204`/`205` return `null`.**
+
+## Errors
+
+Failures throw an **`ApiError`** with `status`, `data`, and `url`:
+
+```js
+import { ApiError } from '/_framework/api.js';
+
+try {
+    await api.post('/api/users', bad);
+} catch (err) {
+    if (err instanceof ApiError) {
+        if (err.status === 400) console.warn(err.message, err.data);
+        else if (err.status === 0) console.error('Network/timeout:', err.message);
+        else console.error('Server error', err.status);
+    }
+}
+```
+
+- `err.message` is extracted from the server's `error` / `message` / `detail` field when present.
+- `err.status === 0` means network failure or **timeout** (`"Request timed out after …ms"`).
+
+## Retry policy
+
+| Status | Retried? |
+|--------|----------|
+| `4xx` | **No** (client errors are your bug — retrying won't help) |
+| `429` | Yes (rate limit) |
+| `5xx` | Yes |
+| Network / timeout | Yes |
+
+Backoff is `200ms, 400ms, 800ms…`. `retries` defaults to `0`; set it per request or globally.
+
+```js
+api.configure({ retries: 1, timeout: 10000 });
+```
+
+## Configuration
+
+```js
+api.setBaseURL('https://api.example.com');   // prefix for relative paths
+api.setHeaders({ Authorization: `Bearer ${token}` });
+api.configure({
+    baseURL: 'https://api.example.com',
+    timeout: 15000,
+    retries: 0,
+    headers: { 'X-App': 'aziz' },
+});
+
+console.log(api.defaults);  // { baseURL, timeout, retries, headers }
+```
+
+Defaults are merged under each request's own headers, so per-call `headers` win.
+
+## Declarative fetching: `useFetch`
+
+For read-only data with loading/error state built in, use the [hook](./05-hooks.md#usefetch--useapi):
+
+```js
+const { data, loading, error, refetch } = useFetch('/api/users');
+```
+
+Use **`api`** for imperative flows (POST/PUT, custom retries, non-JSON bodies); use **`useFetch`** for declarative reads.
+
+## Full example: form → API → UI
+
+```js
+function Contact() {
+    const [form, setForm] = useState({ name: '', message: '' });
+    const [status, setStatus] = useState('idle');
+
+    async function submit(e) {
+        e.preventDefault();
+        setStatus('sending');
+        try {
+            await api.post('/api/contact', form);
+            setStatus('sent');
+        } catch (err) {
+            setStatus('error: ' + err.message);
+        }
+    }
+
+    return (
+        <form onSubmit={submit}>
+            <input value={form.name} onInput={e => setForm({ ...form, name: e.target.value })} />
+            <textarea value={form.message} onInput={e => setForm({ ...form, message: e.target.value })} />
+            <button disabled={status === 'sending'}>Send</button>
+            <p>{status}</p>
+        </form>
+    );
+}
+```
+
+## Continue
+
+→ [Styling](./08-styling.md)

package/template/docs/08-styling.md

@@ -1,94 +1,94 @@
-# 08 · Styling
-
-Aziz.js ships plain CSS. You can also opt into Bootstrap or Tailwind from the CLI.
-
-## Global stylesheet
-
-`index.html` links your main stylesheet:
-
-```html
-<link rel="stylesheet" href="/styles/globals.css">
-```
-
-Add more by editing `index.html` (or inject `<link>` tags dynamically):
-
-```html
-<head>
-    <link rel="stylesheet" href="/styles/globals.css">
-    <link rel="stylesheet" href="/styles/theme.css">
-</head>
-```
-
-## Inline styles
-
-Use the `style` prop with an object (React-style), or a string:
-
-```jsx
-<div style={{ padding: '40px', maxWidth: '900px', margin: '0 auto' }} />
-<div style="color: red" />
-```
-
-## Class names
-
-Both `class` and `className` work:
-
-```jsx
-<div class="card" />
-<div className="card" />
-```
-
-## CSS frameworks via the CLI
-
-Pick one at creation time:
-
-```bash
-npx create-aziz-app my-app --css bootstrap
-npx create-aziz-app my-app --css tailwind
-npx create-aziz-app my-app --css none
-```
-
-- **bootstrap** — adds Bootstrap 5 + Bootstrap Icons (CDN `<link>`/`<script>` injected into `index.html`).
-- **tailwind** — adds the Tailwind CDN `<script>` plus a `tailwind.config` block with `primary`/`dark` colors.
-- **none** — just your `globals.css`.
-
-The flag injects tags into `index.html` before `</head>` / `</body>`. Because these are CDNs, an internet connection is required at runtime.
-
-> Prefer to install CSS locally (e.g. `npm i tailwindcss` + a build step) if you need offline/production builds — the CDN approach is for speed in development.
-
-## Scoped styles?
-
-There's no built-in CSS Modules / scoped styles. Options:
-
-1. **BEM or a naming convention** in `globals.css`.
-2. **Inline `style` objects** for truly one-off layout.
-3. **A `<style>` tag** rendered inside a component (works, but it's global unless you namespace the selectors).
-
-## Theming with context
-
-Because hooks and context are global, a dark-mode toggle is easy:
-
-```js
-const ThemeContext = createContext('light');
-
-function Root({ children }) {
-    const [theme, setTheme] = useLocalStorage('theme', 'light');
-    return (
-        <ThemeContext.Provider value={theme}>
-            <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
-                Toggle theme
-            </button>
-            {children}
-        </ThemeContext.Provider>
-    );
-}
-```
-
-Set `document.body.dataset.theme = theme` and switch colors in CSS:
-
-```css
-[data-theme="dark"] { background: #111; color: #eee; }
-```
-
-## Continue
-
-→ [Imports & Modules](./09-imports-and-modules.md)
+# 08 · Styling
+
+Aziz.js ships plain CSS. You can also opt into Bootstrap or Tailwind from the CLI.
+
+## Global stylesheet
+
+`index.html` links your main stylesheet:
+
+```html
+<link rel="stylesheet" href="/styles/globals.css">
+```
+
+Add more by editing `index.html` (or inject `<link>` tags dynamically):
+
+```html
+<head>
+    <link rel="stylesheet" href="/styles/globals.css">
+    <link rel="stylesheet" href="/styles/theme.css">
+</head>
+```
+
+## Inline styles
+
+Use the `style` prop with an object (React-style), or a string:
+
+```jsx
+<div style={{ padding: '40px', maxWidth: '900px', margin: '0 auto' }} />
+<div style="color: red" />
+```
+
+## Class names
+
+Both `class` and `className` work:
+
+```jsx
+<div class="card" />
+<div className="card" />
+```
+
+## CSS frameworks via the CLI
+
+Pick one at creation time:
+
+```bash
+npx create-aziz-app my-app --css bootstrap
+npx create-aziz-app my-app --css tailwind
+npx create-aziz-app my-app --css none
+```
+
+- **bootstrap** — adds Bootstrap 5 + Bootstrap Icons (CDN `<link>`/`<script>` injected into `index.html`).
+- **tailwind** — adds the Tailwind CDN `<script>` plus a `tailwind.config` block with `primary`/`dark` colors.
+- **none** — just your `globals.css`.
+
+The flag injects tags into `index.html` before `</head>` / `</body>`. Because these are CDNs, an internet connection is required at runtime.
+
+> Prefer to install CSS locally (e.g. `npm i tailwindcss` + a build step) if you need offline/production builds — the CDN approach is for speed in development.
+
+## Scoped styles?
+
+There's no built-in CSS Modules / scoped styles. Options:
+
+1. **BEM or a naming convention** in `globals.css`.
+2. **Inline `style` objects** for truly one-off layout.
+3. **A `<style>` tag** rendered inside a component (works, but it's global unless you namespace the selectors).
+
+## Theming with context
+
+Because hooks and context are global, a dark-mode toggle is easy:
+
+```js
+const ThemeContext = createContext('light');
+
+function Root({ children }) {
+    const [theme, setTheme] = useLocalStorage('theme', 'light');
+    return (
+        <ThemeContext.Provider value={theme}>
+            <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+                Toggle theme
+            </button>
+            {children}
+        </ThemeContext.Provider>
+    );
+}
+```
+
+Set `document.body.dataset.theme = theme` and switch colors in CSS:
+
+```css
+[data-theme="dark"] { background: #111; color: #eee; }
+```
+
+## Continue
+
+→ [Imports & Modules](./09-imports-and-modules.md)