flet-box 1.0.3 → 1.0.5

package/docs/guides/router.md

@@ -0,0 +1,282 @@
+# Routing with FletBox
+
+The FletBox router changes the visible screen without rebuilding a whole HTML page. It supports fixed paths, dynamic parameters, query values, browser history, and route subscriptions.
+
+## Create routes
+
+A route map connects URL paths with widgets or screen functions:
+
+```javascript
+import { Container, Text, runApp } from "flet-box";
+
+const HomeScreen = () => Container({
+  padding: 24,
+  child: Text({ text: "Home" }),
+});
+
+const AboutScreen = () => Container({
+  padding: 24,
+  child: Text({ text: "About" }),
+});
+
+const routes = {
+  "/": HomeScreen,
+  "/about": AboutScreen,
+};
+
+runApp(HomeScreen, "root", true, routes);
+```
+
+When routes are passed to `runApp`, the router is initialized automatically.
+
+## Navigate with `goTo`
+
+```javascript
+import { Button, goTo } from "flet-box";
+
+Button({
+  text: "Open About",
+  onPress: () => goTo("/about"),
+});
+```
+
+The browser URL and the current route are updated together.
+
+## Use a dynamic parameter
+
+Define a parameter with `:name`:
+
+```javascript
+const routes = {
+  "/users/:id": UserScreen,
+};
+```
+
+Read it inside the screen:
+
+```javascript
+import { Text, useParams } from "flet-box";
+
+const UserScreen = () => {
+  const { id } = useParams();
+  return Text({ text: `User: ${id}` });
+};
+```
+
+Navigate to it:
+
+```javascript
+goTo("/users/42");
+```
+
+The value is decoded and available as `id: "42"`.
+
+## Query parameters
+
+Navigate with a query string:
+
+```javascript
+goTo("/search?term=widgets", { page: 2 });
+```
+
+Read query values:
+
+```javascript
+import { Text, useQueryParams } from "flet-box";
+
+const SearchScreen = () => {
+  const { term, page } = useQueryParams();
+  return Text({ text: `Search: ${term}, page ${page}` });
+};
+```
+
+You can also build URLs safely:
+
+```javascript
+import { buildUrl } from "flet-box";
+
+const url = buildUrl(
+  "/users/:id",
+  { id: 42 },
+  { tab: "profile" },
+);
+
+// /users/42?tab=profile
+```
+
+## Go back and forward
+
+```javascript
+import { goBack, goForward } from "flet-box";
+
+goBack();
+goForward();
+```
+
+`replace()` changes the current URL without adding another entry to the application history:
+
+```javascript
+import { replace } from "flet-box";
+
+replace("/login");
+```
+
+## Read the current route
+
+```javascript
+import {
+  getCurrentPath,
+  getCurrentRoute,
+  getCurrentRouteConfig,
+  isActive,
+} from "flet-box";
+
+const path = getCurrentPath();
+const route = getCurrentRoute();
+const config = getCurrentRouteConfig();
+const isHome = isActive("/", true);
+```
+
+`getCurrentRouteConfig()` returns the route, params, query, and path together.
+
+## Subscribe to navigation
+
+```javascript
+import { subscribe } from "flet-box";
+
+const unsubscribe = subscribe((route, params, query) => {
+  console.log({ route, params, query });
+});
+
+// Call when the integration is destroyed.
+unsubscribe();
+```
+
+The router also listens to browser back and forward events.
+
+## Router with `Scaffold`
+
+For larger applications, combine routes with `Scaffold`:
+
+```javascript
+import { Scaffold, Text, runApp } from "flet-box";
+
+const routes = {
+  "/": () => Text({ text: "Home" }),
+  "/settings": () => Text({ text: "Settings" }),
+};
+
+const App = () => Scaffold({
+  routes,
+  body: routes,
+});
+
+runApp(App, "root", true, routes);
+```
+
+Use `AppBar`, `DrawerItem`, `BottomNavigation`, or `Button` to call `goTo()`.
+
+## Deploy under a subpath
+
+A router URL is app-relative: `"/settings"`. Static hosts such as GitHub Pages
+serve a project site under a prefix — `https://user.github.io/my-app/` — so the
+browser sees `/my-app/settings` while the route map only knows `/settings`. The
+router handles that prefix on its own. It reads the deployment base when it
+initializes and adds it back to every URL it writes, so `goTo()` and the
+back/forward buttons stay inside `/my-app/` instead of jumping to the host root.
+
+The base is resolved in this order:
+
+1. The explicit option, which wins over everything:
+   `initRouter(routes, path, { base: "/my-app" })`, or
+   `Scaffold({ routes, basePath: "/my-app" })`.
+2. `window.__FLETBOX_BASE__`, when the live URL actually sits under it. Set it
+   in the page before the app loads: `<script>window.__FLETBOX_BASE__ = "/my-app/";</script>`.
+   The guard is what lets one build run both at `/my-app/` on Pages and at the
+   origin root inside a Capacitor WebView.
+3. Auto-detection: the shortest leading segment of the URL whose remainder
+   matches a registered route becomes the base (`/my-app/settings` → base
+   `/my-app`, route `/settings`). A root-hosted app resolves to `""` and its
+   URLs are untouched.
+
+Read the result with `getBasePath()` — it returns `"/my-app"` or `""`. Use it
+for anything the router does not touch, such as fetching content files, and
+compute it at call time rather than at import time, because the base only
+exists once the router has initialized:
+
+```javascript
+import { getBasePath } from "flet-box";
+
+const assetUrl = (path) =>
+  new URL(path, `${window.location.origin}${getBasePath()}/`).href;
+// https://user.github.io/my-app/docs/guides/router.md  ·  http://localhost:8000/docs/…
+```
+
+## Deep links on a static host
+
+Being able to *write* `/my-app/settings` is only half of it: a static host has
+no such file, so a visitor who opens or reloads that URL gets a 404. GitHub
+Pages answers a missing path by serving the project's `404.html` **under the
+requested URL**, which is exactly the hook an SPA needs — make `404.html` a
+copy of `index.html` and the router will read the real path from the address
+bar and render it.
+
+Generate it at build time so it never drifts from the real entry point. Two
+details make the copy work at any depth, and both are easy to get wrong:
+
+- **Absolute references.** A page served for `/my-app/docs/guides/router.md`
+  resolves `"./loader.js"` against `/my-app/docs/guides/`, not the app root.
+  Rewrite every relative reference, including the import map and the
+  `serviceWorker.register()` path.
+- **Declare the base.** A deep URL is not always recognizable as a route (an
+  unknown path matches nothing), so publish `window.__FLETBOX_BASE__` in the
+  fallback page.
+
+A build script does the whole job in a few lines:
+
+```javascript
+// scripts/spa-fallback.mjs — run after the bundle is written.
+const base = "/my-app/";
+const html = await readFile("www/index.html", "utf8");
+
+const fallback = html
+  .replace(/(["'])\.\//g, `$1${base}`)
+  .replace(
+    /register\((["'])service-worker\.js\1\)/g,
+    `register($1${base}service-worker.js$1)`,
+  )
+  .replace(
+    "</head>",
+    `    <script>window.__FLETBOX_BASE__ = "${base}";</script>\n  </head>`,
+  );
+
+await writeFile("www/404.html", fallback, "utf8");
+```
+
+Keep the service worker in the same scheme: derive its prefix from
+`new URL("./", self.location).pathname` instead of hard-coding `/`, otherwise
+the precache and the offline navigation fallback miss every file under a
+subpath.
+
+## Unknown routes
+
+If the initial URL is not found, the router redirects to the first configured route. You can also define a `*` or `/404` route for navigation attempts that do not exist.
+
+## Common mistakes
+
+- Forgetting to pass routes to `runApp` or call `initRouter`.
+- Using `/user/:id` but navigating to `/user` without an id.
+- Reading query values from params, or params from query values.
+- Calling `goTo()` before the router has been initialized.
+- Forgetting to unsubscribe from route listeners in a long-lived integration.
+- Expecting `goBack()` to work like a server redirect; it uses browser history.
+- Assuming the app owns the host root: under a subpath, content fetches need
+  `getBasePath()` and the host needs a `404.html` fallback for deep links.
+
+---
+
+## Continue reading
+
+- **Previous:** [State with `useState`](state.md)
+- **Next:** [Frontend services guide](frontend-services.md) — Chapter 9 · State, Router & Services
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/state.md

@@ -0,0 +1,283 @@
+# State with `useState`
+
+FletBox state lets widgets share values and update the interface when those values change.
+
+## The simple idea
+
+A state value is a named value stored by a key:
+
+```javascript
+const [count, setCount] = useState("counter", 0);
+```
+
+- `"counter"` is the shared key.
+- `0` is the initial value.
+- `count` is the current reactive value.
+- `setCount` changes the value.
+
+## Small counter example
+
+```javascript
+import { Button, Column, Text, useState } from "flet-box";
+
+const Counter = () => {
+  const [count, setCount] = useState("counter", 0);
+
+  return Column({
+    gap: 12,
+    children: [
+      Text({ text: `Count: ${count}` }),   // derived text → app render (see below)
+      Button({
+        text: "Add one",
+        onPress: () => setCount((previous) => previous + 1),
+      }),
+    ],
+  });
+};
+```
+
+When `setCount` runs, FletBox writes the new value to the store and then decides how much
+of the UI has to change. That decision is the subject of the next section, and it is worth
+getting right: one style of using the value updates a single element, the other re-runs
+your whole component.
+
+## Surgical updates vs. app renders
+
+A state value is a **live** value. If you hand it to a prop, the framework remembers that
+link and, on change, patches only that widget:
+
+```javascript
+const [count, setCount] = useState("counter", 0);
+
+Text({ text: count });                 // surgical: this element is patched
+Container({ bgColor: theme });         // surgical
+```
+
+If you *compute with it inside the component*, the value is consumed before it ever
+reaches a prop, so there is nothing left to patch — the only way to reflect the change is
+to re-run the app:
+
+```javascript
+Text({ text: `Count: ${count}` });     // app render
+Text({ text: count > 5 ? "MUCHO" : "poco" });   // app render
+items.map((item) => Row({ child: Text({ text: item }) }));  // app render
+```
+
+Measured on the same screen, three changes to one key:
+
+| How the key is used | App re-renders | Widgets patched |
+| --- | --- | --- |
+| `Text({ text: count })` only | **0** | the one `Text` |
+| mixed with a template literal | 1 | patched, then replaced |
+| template literal only | 1 | — |
+
+Two details that make this easier to live with:
+
+- **Reads outside the render are free.** Reading the value inside `onPress`, or inside a
+  `subscribe` callback, does **not** force an app render — only reads that happen while the
+  component is building its tree do.
+- **Renders coalesce.** Several `setState` calls in the same tick produce **one** app
+  render, not one per call.
+
+If you need derived text but want to stay surgical, derive it in the subscriber:
+
+```javascript
+const App = () => {
+  const [count, setCount, onCount] = useState("counter", 0);
+  const label = Text({ text: "Count: 0" });
+
+  onCount((n) => label.update({ text: `Count: ${n}` }));
+
+  return Column({ children: [label] });
+};
+```
+
+The app render has no Virtual DOM diff behind it: it re-runs the component and **creates
+new elements**, discarding the old ones. That is why passing the value straight into a prop
+is worth the small change in style. See
+[Reactivity in FletBox](../tools/reactivity.md) for the full decision rule.
+
+## Set a direct value
+
+```javascript
+const [theme, setTheme] = useState("theme", "light");
+
+setTheme("dark");
+```
+
+## Use an updater function
+
+Use an updater when the new value depends on the previous value:
+
+```javascript
+setCount((previous) => previous + 1);
+```
+
+This is useful for counters, arrays, and objects.
+
+## Store an object
+
+```javascript
+const [user, setUser] = useState("user", {
+  name: "Ada",
+  online: false,
+});
+
+setUser((previous) => ({
+  ...previous,
+  online: true,
+}));
+```
+
+Create a new object or array when updating nested data. This makes the change clear and prevents accidental mutation.
+
+## Store an array
+
+```javascript
+const [items, setItems] = useState("items", []);
+
+setItems((previous) => [
+  ...previous,
+  { id: Date.now(), title: "New item" },
+]);
+```
+
+## Shared state between widgets
+
+Two widgets using the same key can read and update the same stored value:
+
+```javascript
+const Status = () => {
+  const [enabled] = useState("feature-enabled", false);
+  return Text({ text: enabled ? "Enabled" : "Disabled" });
+};
+
+const ToggleFeature = () => {
+  const [enabled, setEnabled] = useState("feature-enabled", false);
+  return Button({
+    text: enabled ? "Turn off" : "Turn on",
+    onPress: () => setEnabled((value) => !value),
+  });
+};
+```
+
+Use descriptive, unique keys. A key is global within the state store, so reusing a key accidentally can connect unrelated widgets.
+
+## Watch a state key
+
+`useWatchState` subscribes to changes without creating a state value:
+
+```javascript
+import { useWatchState } from "flet-box";
+
+const stopWatching = useWatchState("counter", (newValue, oldValue) => {
+  console.log({ newValue, oldValue });
+});
+
+// Later:
+stopWatching();
+```
+
+## Subscribe from `useState`
+
+The current implementation returns a third value for subscriptions:
+
+```javascript
+const [value, setValue, subscribe] = useState("status", "idle");
+
+const unsubscribe = subscribe((newValue, oldValue) => {
+  console.log(newValue, oldValue);
+});
+
+// Later:
+unsubscribe();
+```
+
+## State and widgets
+
+Normally you do not register anything: pass the state value into a prop and the widget
+factory binds it to the key for you, releasing the binding when the widget is removed.
+
+```javascript
+const [theme, setTheme] = useState("theme", "light");
+
+const panel = Container({ bgColor: theme });  // bound automatically
+setTheme("dark");                             // patches `panel` only
+```
+
+There is an explicit form for the case where the widget already exists and you want one of
+its props driven by a key:
+
+```javascript
+const [label, setLabel] = useState(
+  "button-label",
+  "Save",
+  button,
+  "text",
+);
+```
+
+Both push the new value through `widget.update({ prop: value })`, so the update touches one
+element instead of rebuilding the screen.
+
+## Reading the value
+
+The value returned by `useState` behaves like the current state in most expressions —
+`${count}` and `count + 1` work — but under the hood it is a live function, and that shows
+up in two places:
+
+```javascript
+typeof count;          // "function", not "number"
+count.valueOf();       // the current value, explicitly
+```
+
+For objects and arrays, **property access does not go through the state**:
+
+```javascript
+const [user, setUser] = useState("user", { name: "Ada", online: false });
+
+user.name;             // ✗ "live" — the function's own name, not the state's
+user.online;           // ✗ undefined
+user().name;           // ✓ "Ada"  — call it, or pass it straight into a prop
+```
+
+So for object state, prefer letting a widget resolve it (pass the value itself as the prop,
+not a field of it) or read it by calling the value inside a handler, where reads are free.
+
+## Persistence during the session
+
+FletBox stores state through its RAM store. The value is available by key while the application is running:
+
+```javascript
+import { saveRam, getRam } from "flet-box";
+
+saveRam("language", "en");
+const language = getRam("language");
+```
+
+Use the storage services when you need browser persistence or a different lifetime.
+
+## Important rules
+
+- Call `useState` with a stable key.
+- Do not create random keys on every render.
+- Use updater functions for values based on previous state.
+- Avoid mutating arrays and objects in place.
+- Pass the state value straight into a prop when you can: that is what keeps the update
+  surgical instead of re-running the app.
+- Do not read object state with `user.name`; call the value (`user()`) or let a widget
+  resolve it.
+- Unsubscribe from manual watchers when the feature is destroyed.
+- Use `runApp()` when you want global re-render behavior for a complete app.
+
+## TypeScript note
+
+The runtime currently returns `[value, setValue, subscribe]`. Keep the declaration file and this behavior aligned when changing the public API.
+
+---
+
+## Continue reading
+
+- **Previous:** [CollapsibleSideBar](../widget/CollapsibleSideBar.md) — end of the widget book.
+- **Next:** [Routing with FletBox](router.md) — Chapter 9 · State, Router & Services
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/syntax-philosophy.md

@@ -0,0 +1,150 @@
+# FletBox syntax philosophy
+
+FletBox is designed around the developer, not the other way around.
+
+You should be able to describe an interface in a way that feels natural to you. Developers coming from Flet, Flutter, React, or vanilla JavaScript may use slightly different names for the same idea. FletBox is intentionally friendly to those styles.
+
+## One idea, several comfortable names
+
+Some props have aliases because different ecosystems use different words.
+
+```javascript
+Container({
+  bgColor: "#eff6ff",
+  padding: 16,
+});
+```
+
+A developer coming from traditional web development may prefer:
+
+```javascript
+Container({
+  backgroundColor: "#eff6ff",
+  padding: "16px",
+});
+```
+
+The goal is not to force one vocabulary. The goal is to make the intention obvious.
+
+## Events that read naturally
+
+Depending on your background, either event name may feel more familiar:
+
+```javascript
+Button({
+  text: "Save",
+  onPress: save,
+});
+```
+
+```javascript
+Button({
+  text: "Save",
+  onClick: save,
+});
+```
+
+Both express the same human idea: run this function when the user activates the button.
+
+## Children and composition
+
+Flet and Flutter developers may think in terms of a single `child`:
+
+```javascript
+Container({
+  child: Text({ text: "Hello" }),
+});
+```
+
+React developers may prefer `children`:
+
+```javascript
+Container({
+  children: [
+    Text({ text: "Hello" }),
+    Text({ text: "Welcome" }),
+  ],
+});
+```
+
+Use `child` for one child and `children` for several children when the widget supports both.
+
+## Direct values or helper functions
+
+FletBox keeps simple values simple:
+
+```javascript
+Container({
+  padding: 16,
+  margin: "8px 0",
+});
+```
+
+You can also use helpers when you prefer an expressive style:
+
+```javascript
+import { margin, padding } from "flet-box";
+
+Container({
+  padding: padding({ horizontal: 20, vertical: 12 }),
+  margin: margin({ top: 8, bottom: 16 }),
+});
+```
+
+The first style is quick. The second style can make complex spacing more descriptive. Choose the one that makes your code easiest to read.
+
+## Styling vocabulary
+
+FletBox accepts familiar CSS-like values:
+
+```javascript
+Container({
+  width: "100%",
+  minHeight: "100vh",
+  borderRadius: 12,
+  bgColor: "#ffffff",
+});
+```
+
+Numbers normally represent pixels. Strings can contain CSS units such as `%`, `vh`, `rem`, or `px`.
+
+## Preferred and compatible syntax
+
+For new projects, choose one style and use it consistently within a file. The examples in this documentation generally use the short, readable widget style:
+
+```javascript
+Text({ text: "Hello", size: 18, weight: "bold" });
+```
+
+Aliases exist to make migration and adoption easier. They are not a requirement to mix every style in the same component.
+
+Think of the API in three layers:
+
+- **Preferred syntax**: the clearest style recommended by the current documentation.
+- **Friendly aliases**: equivalent names that help developers coming from another ecosystem.
+- **Compatibility syntax**: older names preserved so existing projects do not break.
+
+## The rule for documentation
+
+Every widget page should answer three questions:
+
+1. What does this widget represent?
+2. What is the smallest example that works?
+3. Which alternative names or styles can a developer use?
+
+That is why each widget page contains a basic example, an everyday example, a full example, common prop explanations, and beginner tips.
+
+## The rule for framework design
+
+FletBox should adapt to the developer wherever that flexibility remains clear, testable, and maintainable.
+
+Friendly syntax must still have:
+
+- Clear documentation.
+- Consistent behavior.
+- Type declarations.
+- Working examples.
+- Tests for important aliases.
+- A migration path when an alias changes.
+
+This keeps the experience soft for beginners without making the framework mysterious for experienced developers.