flet-box 1.0.3 → 1.0.5

package/docs/guides/utilities.md

@@ -0,0 +1,241 @@
+# FletBox utilities
+
+FletBox includes small helpers for common UI and application tasks. Import only the helpers you need from `flet-box`.
+
+## Layout helpers
+
+Use direct props for the simplest code:
+
+```javascript
+Container({
+  padding: 16,
+  margin: "8px 0",
+  gap: 12,
+});
+```
+
+Use helpers when spacing or layout becomes more descriptive:
+
+```javascript
+import { border, flex, grid, margin, padding, shadow } from "flet-box";
+
+Container({
+  padding: padding({ horizontal: 20, vertical: 12 }),
+  margin: margin({ top: 8, bottom: 16 }),
+  border: border(1, "solid", "#e5e7eb"),
+  shadow: shadow(0, 4, 12, 0, "rgba(0,0,0,0.12)"),
+});
+
+const columns = grid({ columns: 3, gap: 16 });
+const flexible = flex(1, 0, "auto");
+```
+
+## Colors and effects
+
+```javascript
+import { color, gradient, rgba } from "flet-box";
+
+const transparentBlue = rgba(37, 99, 235, 0.2);
+const background = gradient("linear", ["#6366f1", "#8b5cf6"], 135);
+const lighter = color("#6366f1").lighten(20);
+```
+
+Color helpers can lighten, darken, adjust alpha, inspect contrast, and create related colors.
+
+Effects such as transforms and transitions return values that can be used by supported direct props:
+
+```javascript
+import { transform, transition } from "flet-box";
+
+Container({
+  transform: transform({ translateY: -4, scale: 1.02 }),
+  transition: transition({ property: "all", duration: 0.3, timing: "ease" }),
+});
+```
+
+## Lists and mapping
+
+```javascript
+import { createList, mapList, range, repeat } from "flet-box";
+
+const numbers = range(0, 10, 2);
+const repeated = repeat(3, (index) => Text({ text: `Item ${index}` }));
+const widgets = mapList(users, (user) => Text({ text: user.name }));
+```
+
+`createList` provides data helpers:
+
+```javascript
+const page = createList.paginate(users, 2, 20);
+const matches = createList.search(users, "ada", ["name", "email"]);
+const grouped = createList.groupBy(users, "role");
+const sorted = createList.sort(users, "name", "asc");
+```
+
+Array helpers include `shuffle`, `reverse`, `sort`, `unique`, and `chunk`.
+
+## Random values and ids
+
+```javascript
+import { random, shortId, uuid } from "flet-box";
+
+const userId = uuid();
+const short = shortId();
+const name = random.fullName();
+const email = random.email();
+const colorValue = random.hexColor();
+```
+
+Use random helpers for demos and sample data. Do not use generated demo values as security credentials.
+
+## Strings and dates
+
+```javascript
+import {
+  capitalizeWords,
+  formatDate,
+  relativeTime,
+  truncate,
+} from "flet-box";
+
+capitalizeWords("flet box");
+truncate("A very long sentence", 10, "...");
+formatDate(new Date(), "YYYY-MM-DD");
+relativeTime("2026-01-01");
+```
+
+## Delays and retries
+
+```javascript
+import { delay, retry, withMinDelay } from "flet-box";
+
+await delay(500);
+await retry(fetchData, 3, 1000);
+await withMinDelay(fetchData(), 800);
+```
+
+Use these helpers for loading states, demos, and recoverable network operations.
+
+## Device and dimensions
+
+```javascript
+import { device, dimensions, height, width } from "flet-box";
+
+if (device.isMobile()) {
+  console.log("Mobile layout");
+}
+
+console.log(dimensions.getWidth(), dimensions.getHeight());
+console.log(width, height);
+```
+
+Subscribe to changes:
+
+```javascript
+const removeListener = dimensions.addListener(({ width, height }) => {
+  console.log(width, height);
+});
+
+removeListener();
+```
+
+## Themes and colors
+
+```javascript
+import {
+  colors,
+  getColor,
+  getTheme,
+  setTheme,
+  toggleTheme,
+} from "flet-box";
+
+const primary = colors.primary;
+const text = getColor("text");
+setTheme("dark");
+const current = getTheme();
+toggleTheme();
+```
+
+React to theme changes:
+
+```javascript
+import { subscribeTheme } from "flet-box";
+
+const unsubscribe = subscribeTheme((nextColors) => {
+  console.log(nextColors.primary);
+});
+```
+
+## Clipboard
+
+```javascript
+import { clipboard } from "flet-box";
+
+clipboard.copy("Copied text");
+const text = await clipboard.read();
+```
+
+Browser permissions may be required for reading clipboard content.
+
+## Text input validation
+
+```javascript
+import { TextInputValidator } from "flet-box";
+
+TextInputValidator.isEmail("user@example.com");
+TextInputValidator.onlyNumbers("abc123");
+TextInputValidator.sanitize(userInput);
+TextInputValidator.limitLength(userInput, 50);
+```
+
+The `Input` widget can use these rules through its `validation` prop.
+
+## Markdown and code helpers
+
+```javascript
+import {
+  escapeHtml,
+  generateHighlightedHtml,
+  markdownToWidgets,
+} from "flet-box";
+
+const content = markdownToWidgets("# Hello\n\nThis is **bold**");
+const safe = escapeHtml(userText);
+const highlighted = generateHighlightedHtml(code);
+```
+
+Escape untrusted text before displaying it as HTML.
+
+## Media time helpers
+
+```javascript
+import {
+  formatMediaProgress,
+  formatMediaTime,
+  getProgressPercent,
+  percentToSeconds,
+} from "flet-box";
+
+formatMediaTime(125); // 02:05
+getProgressPercent(30, 120);
+percentToSeconds(50, 120);
+formatMediaProgress(30, 120);
+```
+
+## Choosing a utility
+
+- Need spacing? Start with direct `padding`, `margin`, and `gap` props.
+- Need reusable data? Use `createList`, `mapList`, or `range`.
+- Need shared UI state? Read [State with `useState`](state.md).
+- Need URL changes? Read [Routing](router.md).
+- Need colors that follow the app theme? Use `colors` and `getColor`.
+- Need browser information? Use `device`, `os`, and `dimensions`.
+
+---
+
+## Continue reading
+
+- **Previous:** [Animation helpers](../tools/animation.md) — end of the tools chapter.
+- **Next:** [The FletBox CLI](../cli/README.md) — Chapter 11
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/widget-structure.md

@@ -0,0 +1,163 @@
+# Widget structure: one shape for every widget
+
+Every widget in FletBox is a plain function that returns an `HTMLElement`, built
+on top of the single rendering engine: [`src/widget-factory/`](../../src/widget-factory/).
+This page is the **canonical structure** all widgets follow — existing and future —
+so the library stays modular, predictable, and easy to review.
+
+Reference implementation: [`src/widgets/QRCode.js`](../../src/widgets/QRCode.js).
+
+## The shape
+
+```javascript
+/**
+ * @file MyWidget.js
+ * @description One paragraph: what the widget renders and how it behaves.
+ */
+
+import { WidgetFactory } from "../widget-factory/index.js";
+// import shared helpers (theme, composeUpdate, ...) — never a second engine.
+
+// ---------------------------------------------------------------------------
+// Module-level constants and pure helpers (no DOM, no side effects)
+// ---------------------------------------------------------------------------
+
+const WIDGET_PROP_KEYS = ["value", "onPress", /* ... */];
+
+const normalize = (value) => /* pure transform */;
+
+// ---------------------------------------------------------------------------
+// Widget
+// ---------------------------------------------------------------------------
+
+/**
+ * JSDoc for every prop, its type and default.
+ * @returns {HTMLElement}
+ */
+export const MyWidget = (props) => {
+  // 1. Destructure with defaults; keep the rest for the factory.
+  const { value = "", onPress, size = 200, ...rest } = props;
+
+  // 2. Early guards. Never leave a half-built element.
+  if (!value) return WidgetFactory({ widgetName: "MyWidget", ...rest });
+
+  // 3. Closure state / refs (private, mutable).
+  let currentValue = value;
+  let ref = null;
+
+  // 4. Exactly ONE factory root.
+  const container = WidgetFactory({
+    widgetName: "MyWidget",
+    ...defaults,
+    ...rest,
+  });
+
+  // 5. Children via the factory (`child`/`children`) or `appendChild`.
+  //    Raw `createElement` only for what the factory cannot express (canvas...).
+
+  // 6. Public, reactive surface. Compose — never overwrite — `container.update`.
+  container.setValue = (v) => { currentValue = v; render(); };
+  container.getValue = () => currentValue;
+
+  // 7. Resources: every listener/timer/rAF/observer/subscription goes through
+  //    onUnmount, and the disposer must be idempotent.
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    // removeEventListener / clearTimeout / disconnect ...
+  };
+  container.onUnmount(dispose);
+
+  return container;
+};
+
+export default MyWidget;
+```
+
+## The rules
+
+1. **One root, one engine.** A widget returns a single element created by
+   `WidgetFactory`. Never hand-roll a parallel rendering path.
+2. **Module scope is pure.** Constants and helpers at the top of the file do no
+   DOM work and register no side effects.
+3. **Props in, element out.** Destructure with defaults, forward `...rest` to the
+   factory, guard early. A widget with no data returns a valid element (or a
+   documented controller object — see below).
+4. **`widgetName` labels the widget.** Pass `widgetName: "<Name>"` to the root
+   factory call so `Inspector`, `printWidgetCode`, and navigation helpers see the
+   real name instead of the capitalised HTML tag. (`name` is *not* reserved — it
+   is a public prop of `Icon`/`Avatar`.)
+5. **Compose `update`.** Keep widget state in the closure and route updates
+   through [`composeUpdate()`](../../src/utils/composeUpdate.js). Overwriting
+   `container.update` silently disables the factory's style/event reactivity.
+6. **No ad-hoc global styles.** Scope injected CSS with
+   `<style data-widget="<Name>">` or a per-instance adopted stylesheet
+   (`markdown-scope-N` pattern) and remove it on unmount. Never inject an
+   unscoped `<style>` tag into `document.head` yourself — `@keyframes` cannot be
+   scoped, so the only sanctioned global injection is the shared, idempotent
+   [`injectKeyframes()`](../../src/utils/styleInjector.js) helper.
+7. **Portals clean up after themselves.** Widgets that append to
+   `document.body` (dialogs, dropdowns, tooltips) must remove their node and
+   close over the parent's lifecycle via `onUnmount`.
+8. **`onUnmount` is the single cleanup hook.** Register disposers there; they can
+   run from more than one teardown path, so make them idempotent. Do not
+   monkey-patch `_cleanup`.
+9. **Public API is additive.** Expose behavior through named methods
+   (`updateValue`, `getValue`, ...) and reactive accessors. Never mutate
+   `container.update` or `container._cleanup`.
+10. **Complete the three surfaces.** Runtime file, export from
+    `src/widgets/index.js` **and** `src/index.js`, types in `src/index.d.ts`,
+    plus a doc page in `docs/widget/<Name>.md` with `basic`/`normal`/`full`
+    examples.
+11. **Flat, aliased CSS props — never `style:`.** FletBox has no `style` object:
+    pass CSS props directly (`backgroundColor`, `padding`, `flexDirection`,
+    `whiteSpace`, …) with aliases resolved by the factory. `style: { ... }` is
+    rejected with a warning (`processProps`), so it never silently half-applies.
+
+## Controller widgets
+
+A few widgets manage transient UI that lives outside the tree (modals, sheets,
+snackbars). They may return a **controller object** instead of an element, but
+the exception is explicit and typed:
+
+| Widget | Returns |
+| --- | --- |
+| `AlertDialog` | `{ open, close, modal }` |
+| `SnackBar` | `{ close, show, getElement }` |
+| `BottomSheet` | `{ open, close, toggle, destroy }` |
+| `Modal` | controller instance (`open`/`close`/`updateContent`) |
+
+Everything else returns an `HTMLElement`.
+
+## Adding a widget — checklist
+
+1. Copy the shape above into `src/widgets/<Name>.js`.
+2. Implement props with defaults and JSDoc; forward `...rest`.
+3. Pass `widgetName: "<Name>"` to the root factory call.
+4. Register every resource with an idempotent `onUnmount` disposer.
+5. Export from `src/widgets/index.js` and `src/index.js`.
+6. Add types and props to `src/index.d.ts` (regenerate docs with
+   `python3 scripts/generate_widget_docs.py`).
+7. Add `docs/widget/<Name>.md` with `basic`/`normal`/`full` examples.
+8. Verify:
+   ```bash
+   node --check src/widgets/<Name>.js
+   node scripts/check-widgets.mjs          # static contract (no new violations)
+   npm run dev                             # then open the test harnesses:
+   #   /tests/widget-contract.html  — runtime contract
+   #   /tests/smoke.html            — instantiates every widget
+   #   /tests/widget-factory.html   — frozen engine regression suite
+   ```
+
+## Tooling
+
+- `node scripts/check-widgets.mjs` — static contract checker. It compares the
+  code against `scripts/widget-contract-baseline.json`; the baseline records
+  pre-existing debt and must shrink as widgets are refactored. Adding a widget
+  to the baseline is never the fix.
+- `node scripts/check-widgets.mjs --write-baseline` — re-snapshot after a batch
+  of fixes (only to *remove* entries in practice).
+- `/tests/widget-contract.html` — runtime contract: every widget instantiates,
+  returns an element (or a documented controller), exposes `update()`, and
+  reports its real `_widgetName`.

package/docs/server/README.md

@@ -0,0 +1,68 @@
+# FletBox Server
+
+FletBox Server is the backend toolkit for building APIs with Node.js. It gives you a simple route definition, automatic schemas, validation, authentication, security middleware, data tools, and generated API documentation.
+
+It is a **separate package with its own repository** — [kuko53348/flet-box-server](https://github.com/kuko53348/flet-box-server) — because the frontend and the backend release independently. Nothing here is required to build a FletBox app; the docs live in this book so the whole stack is documented in one place.
+
+```bash
+npm install flet-box-server
+```
+
+Import the core from the package root, and each tool from its own module. The tools are deliberately not re-exported at the root: `pdf.js` pulls puppeteer, `sms.js` pulls twilio, `csv.js` pulls xlsx, and the speech modules need optional Google Cloud packages, so a single root import would force all of them to load.
+
+```javascript
+import { Api, runServer } from "flet-box-server";                        // core
+import { SQLite } from "flet-box-server/tools/betterSqlite.js";           // one tool
+```
+
+## Start here
+
+If this is your first backend, read [Start here](START_HERE.md).
+
+## Documentation map
+
+- [Start here](START_HERE.md): create your first API step by step.
+- [API and routes](api.md): define endpoints, handlers, parameters, and schemas.
+- [Authentication and security](security.md): JWT, roles, sanitization, blocking, headers, and rate limits.
+- [Database and services](data-services.md): where data lives (browser vs server), a dedicated SQLite API server example, cache, files, email, PDF, CSV, queues, and more.
+- [Deployment](deployment.md): environment variables, production settings, Docker, and operational checks.
+
+## What the server does
+
+- Defines routes with `Api()`.
+- Runs on the native Node.js HTTP server or an Express adapter.
+- Creates JSON responses automatically for returned objects.
+- Generates schemas from request examples.
+- Validates request bodies with `SchemaValidator`.
+- Serves generated API documentation at `/docs`.
+- Supports JWT authentication and role checks.
+- Provides security headers, sanitization, malicious-input blocking, and rate limiting.
+- Includes modules for SQLite, Redis, files, email, SMS, PDF, CSV/XLSX, WebSockets, queues, speech, translation, and logging.
+
+## Important production rule
+
+The example server in `flet-box-server/app.js` is a test server. It disables some protections and contains a development admin account. Do not copy those values into production. Use `runSecureServer`, environment variables, a real database, a strong `JWT_SECRET`, and explicit CORS origins.
+
+## Minimal server
+
+```javascript
+import { Api, runServer } from "flet-box-server";
+
+const routes = Api({
+  "/": {
+    GET: () => ({ message: "Hello from FletBox Server" }),
+  },
+});
+
+runServer(routes, {
+  port: 3000,
+  docs: true,
+});
+```
+
+Then open:
+
+```text
+http://localhost:3000/
+http://localhost:3000/docs
+```

package/docs/server/START_HERE.md

@@ -0,0 +1,121 @@
+# Start here
+
+This guide teaches the backend in small steps. You only need JavaScript and a terminal.
+
+## 1. Install
+
+Inside `flet-box-server`:
+
+```bash
+npm install
+```
+
+The server requires Node.js and uses ES modules.
+
+## 2. Create one route
+
+Create `server.js`:
+
+```javascript
+import { Api, runServer } from "flet-box-server";
+
+const routes = Api({
+  "/hello": {
+    GET: () => ({ message: "Hello" }),
+  },
+});
+
+runServer(routes, { port: 3000, docs: true });
+```
+
+Start it:
+
+```bash
+node server.js
+```
+
+Test it:
+
+```bash
+curl http://localhost:3000/hello
+```
+
+## 3. Understand the route
+
+```javascript
+"/users/:id": {
+  GET: ({ id, query, req }) => ({
+    id,
+    filters: query,
+    userAgent: req.headers["user-agent"],
+  }),
+}
+```
+
+- `/users/:id` is the URL pattern.
+- `id` comes from the URL.
+- `query` contains values such as `?page=2`.
+- `req` is the native request object.
+- Returning an object sends JSON to the client.
+
+## 4. Accept JSON data
+
+```javascript
+const routes = Api({
+  "/tasks": {
+    POST: {
+      handler: ({ title, completed }) => ({
+        title,
+        completed,
+      }),
+      example: {
+        title: "Learn FletBox Server",
+        completed: false,
+      },
+    },
+  },
+});
+```
+
+The `example` documents the expected body and can be used to generate a schema.
+
+Request it with:
+
+```bash
+curl -X POST http://localhost:3000/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Learn FletBox Server","completed":false}'
+```
+
+## 5. Add protection
+
+For a production-style default, use:
+
+```javascript
+import { Api, runSecureServer } from "flet-box-server";
+
+const routes = Api({
+  "/private": {
+    GET: () => ({ secret: "protected data" }),
+  },
+});
+
+runSecureServer(routes, {
+  port: 3000,
+  docs: true,
+  rateLimit: { max: 100, windowMs: 60_000 },
+});
+```
+
+Add authentication to routes that require a logged-in user. See [Authentication and security](security.md).
+
+## 6. Learn the normal workflow
+
+1. Define routes with `Api()`.
+2. Add `example` objects for request bodies.
+3. Add `responseExample` objects for documented responses.
+4. Add middleware such as authentication or roles.
+5. Start with `runSecureServer()`.
+6. Test with curl or your frontend.
+7. Open `/docs` to inspect generated documentation.
+8. Move secrets and configuration to environment variables.