flet-box 1.0.4 → 1.0.5

package/docs/guides/first-app.md

@@ -0,0 +1,208 @@
+# Chapter 0 · Your first FletBox app, step by step
+
+This page is for **absolute beginners**. You do not need to know any trick — you only need a text editor, a terminal, and the [FletBox CLI](../cli/README.md) installed. At the end you will have a working app with a button and a list.
+
+## Before you start
+
+FletBox is not published to the npm registry, so first you install the CLI once and link it globally:
+
+```bash
+git clone https://github.com/kuko53348/flet-box.git
+cd flet-box
+npm link                          # link the flet-box CLI globally
+```
+
+Then create an empty project, link the framework into it, and start the dev server:
+
+```bash
+cd ..
+flet-box create my-app
+cd my-app
+npm link flet-box                 # or: npm install ../path/to/flet-box
+npm run dev
+```
+
+Open your browser at `http://localhost:8000`. You should see "Hello FletBox" (or a small welcome screen). If you do, everything is working.
+
+## Step 1: the smallest app
+
+Open the file the CLI created (usually `src/app.js`). Edit it to this:
+
+```javascript
+import { runApp, Text } from "flet-box";
+
+const app = Text({ text: "Hello, world!" });
+
+runApp(app, "root");
+```
+
+`Text` makes a piece of text. `runApp` puts your app on the page, inside an element with `id="root"`. Save the file and look at the browser: it says "Hello, world!".
+
+## Step 2: a button that counts
+
+A button is a `Button` widget. It can run code when you press it. Inside that code we build a counter.
+
+```javascript
+import { runApp, Column, Text, Button } from "flet-box";
+
+async function main() {
+  const [count, setCount] = useState("counter", 0);
+
+  const app = Column({
+    gap: 12,
+    children: [
+      Text({ text: `You pressed ${count} times` }),
+      Button({
+        text: "Add one",
+        onPress: () => setCount((previous) => previous + 1),
+      }),
+    ],
+  });
+
+  runApp(app, "root");
+}
+
+main();
+```
+
+Wait — we used `useState` but did not import it. Fix the import line:
+
+```javascript
+import { runApp, Column, Text, Button, useState } from "flet-box";
+```
+
+What just happened?
+
+- `useState("counter", 0)` creates a value stored under the key `"counter"`, starting at `0`.
+- `count` is the current value.
+- `setCount` is the function that changes it.
+- When we press the button, we tell FletBox to run the screen again with the new value, so the text updates.
+
+`Column` stacks its `children` vertically, one under the other, with `gap` space between them.
+
+## Step 3: write and add tasks
+
+Now the fun part — a real todo list. A `Row` puts widgets side by side. An `Input` is a text box, and its `.value` holds what the user typed.
+
+```javascript
+import { runApp, Column, Row, Text, Input, Button, useState } from "flet-box";
+
+async function main() {
+  const tasks = Column({ gap: 8, children: [] });
+  const [allTasks, setAllTasks] = useState("tasks", [], tasks, "children");
+
+  const input = Input({ placeholder: "Write a task" });
+
+  const app = Column({
+    gap: 16,
+    children: [
+      Text({ text: "My tasks", type: "h2" }),
+      Row({
+        gap: 8,
+        children: [
+          input,
+          Button({
+            text: "Add",
+            onPress: () => {
+              if (input.value.trim() === "") return;
+              setAllTasks([...allTasks, input.value]);
+              input.value = "";
+            },
+          }),
+        ],
+      }),
+      tasks,
+    ],
+  });
+
+  runApp(app, "root");
+}
+
+main();
+```
+
+Type something in the box, press **Add**, and watch it appear in the list below.
+
+How it works:
+
+- `tasks` is an empty `Column` — it will hold the rows of the list.
+- The 4th argument of `useState` (“children”) tells FletBox: *when this state changes, update the `children` of `tasks`*.
+- `setAllTasks([...allTasks, input.value])` puts the new task at the end of the list. FletBox then re-renders `tasks` with the new rows.
+- Clearing `input.value` empties the box so you can write the next task.
+
+## Step 4: make each task removable
+
+Giving every task its own "x" button means each row is a small `Row` with a `Text` and a `Button`. We rebuild the whole list whenever it changes, using the widget's own `update` method:
+
+```javascript
+import { runApp, Column, Row, Text, Input, Button } from "flet-box";
+
+let allTasks = [];
+const tasks = Column({ gap: 8, children: [] });
+const input = Input({ placeholder: "Write a task" });
+
+const taskRow = (task) =>
+  Row({
+    gap: 8,
+    children: [
+      Text({ text: task }),
+      Button({
+        text: "x",
+        size: "small",
+        onPress: () => {
+          allTasks = allTasks.filter((item) => item !== task);
+          render();
+        },
+      }),
+    ],
+  });
+
+const render = () => tasks.update({ children: allTasks.map(taskRow) });
+
+const addTask = () => {
+  if (input.value.trim() === "") return;
+  allTasks.push(input.value);
+  input.value = "";
+  render();
+};
+
+const app = Column({
+  gap: 16,
+  children: [
+    Text({ text: "My tasks", type: "h2" }),
+    Row({
+      gap: 8,
+      children: [
+        input,
+        Button({ text: "Add", onPress: addTask }),
+      ],
+    }),
+    tasks,
+  ],
+});
+
+runApp(app, "root");
+```
+
+- `taskRow` builds one line: the task name plus a small **x** button.
+- `render()` asks `tasks` to replace its children with the current list, rebuilt as rows.
+- Pressing **x** removes that task from `allTasks` and re-renders.
+
+This app grows with you: the widgets you used — `Row`, `Column`, `Text`, `Input`, `Button` — are the same ones every FletBox screen is built from. To go deeper into shared, automatic state, read the [State guide](state.md).
+
+## What is next
+
+You just built a real app. Now learn what widgets look like and how to mix them:
+
+- **[Start here](../widget/START_HERE.md)** — how to read the widget book.
+- **[The widget book](../widget/README.md)** — all widgets, in order, from basic to advanced.
+
+---
+
+## Continue reading
+
+- **Previous:** [The FletBox Book](../README.md) — front cover.
+- **Next:** [Start here](../widget/START_HERE.md) — how to read the widget book.
+- **Index:** [Guides index](README.md).
+
+You are reading **Chapter 0 · Your first app** (before Chapter 1).

package/docs/guides/frontend-services.md

@@ -0,0 +1,171 @@
+# Frontend services
+
+FletBox includes three browser storage layers and a small HTTP client. Choose the layer based on how long the data should live.
+
+## Choose a storage layer
+
+| Service | Lifetime | Best for |
+| --- | --- | --- |
+| `RamStore` | Until the page is reloaded | Shared reactive UI state. |
+| `Session` | Until the browser tab/session ends | Temporary session data. |
+| `Storage` | Until the user or app removes it | Small persistent preferences. |
+
+None of these services should be used for passwords, private keys, or security secrets.
+
+## RamStore
+
+`RamStore` keeps values in memory and can notify subscribers:
+
+```javascript
+import { getRam, saveRam, subscribeRam } from "flet-box";
+
+saveRam("cart", [{ id: 1, name: "Book" }]);
+const cart = getRam("cart");
+
+const unsubscribe = subscribeRam((key, newValue, oldValue) => {
+  if (key === "cart") {
+    console.log({ newValue, oldValue });
+  }
+});
+
+unsubscribe();
+```
+
+Values disappear when the page reloads.
+
+## Session storage
+
+Use `Session` for data that should survive navigation but not remain as a permanent preference:
+
+```javascript
+import { getSession, saveSession, deleteSession } from "flet-box";
+
+saveSession("checkout-step", 2);
+const step = getSession("checkout-step");
+deleteSession("checkout-step");
+```
+
+The data is backed by `sessionStorage`.
+
+## Persistent storage
+
+Use `Storage` for small preferences:
+
+```javascript
+import { getData, saveData, deleteData } from "flet-box";
+
+saveData("preferences", {
+  theme: "dark",
+  language: "en",
+});
+
+const preferences = getData("preferences");
+deleteData("preferences");
+```
+
+The data is backed by `localStorage` and serialized as JSON.
+
+## Storage rules
+
+- Use namespaced keys such as `fletbox:preferences`.
+- Store small values only.
+- Handle `null` when a key does not exist.
+- Do not store credentials or sensitive tokens unless you understand the security tradeoff.
+- Do not call `clearAllData()` in a shared page unless you intentionally want to clear every local-storage key for that origin.
+- Do not call `clearAllSession()` in a shared page unless you intentionally want to clear every session-storage key for that origin.
+- Use a server-side session or secure platform storage for sensitive authentication data.
+
+## Check availability
+
+Storage can be disabled by browser privacy settings, sandboxing, or restricted contexts:
+
+```javascript
+import { isStorageAvailable, isSessionAvailable } from "flet-box";
+
+if (isStorageAvailable()) {
+  saveData("visited", true);
+}
+
+if (isSessionAvailable()) {
+  saveSession("step", 1);
+}
+```
+
+## HTTP requests
+
+The HTTP helpers use `fetch` and return parsed JSON when the response content type is JSON:
+
+```javascript
+import { httpGet, httpPost } from "flet-box";
+
+const users = await httpGet("/api/users", {
+  params: { page: 1 },
+});
+
+const created = await httpPost("/api/users", {
+  body: { name: "Ada" },
+});
+```
+
+Available helpers:
+
+```text
+httpGet
+httpPost
+httpPut
+httpPatch
+httpDelete
+httpRequest
+```
+
+## Headers and authentication
+
+```javascript
+const data = await httpGet("/api/private", {
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+});
+```
+
+Never hardcode a private secret in frontend source code. A bearer token in browser code must be treated as accessible to the user and protected by server-side authorization.
+
+## Timeout and errors
+
+```javascript
+try {
+  const data = await httpGet("/api/slow", {
+    timeout: 5000,
+  });
+  console.log(data);
+} catch (error) {
+  console.error("Request failed:", error.message);
+}
+```
+
+Non-2xx responses throw an error containing `response` and, when available, parsed response data in `error.data`.
+
+## Query parameters
+
+```javascript
+const result = await httpGet("/api/search", {
+  params: {
+    query: "widgets",
+    page: 2,
+  },
+});
+```
+
+Use encoded values through the `params` option instead of manually concatenating user input into URLs.
+
+## Service API status
+
+Every storage and HTTP function is declared in `src/index.d.ts`, exported from `src/index.js`, and detailed on the [services reference pages](../services/README.md). The runtime also exports namespace objects (`RamStore`, `Session`, `Storage`) that group each layer.
+
+---
+
+## Continue reading
+
+- **Previous:** [Routing with FletBox](router.md)
+- **Next:** [Services index](../services/README.md) — the full reference
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/minification-and-protection.md

@@ -0,0 +1,260 @@
+# Minify and protect a FletBox build
+
+> **Level: Advanced.** This page is for shipping — skip it on a first read. It follows [the FletBox CLI](../cli/README.md) in the book's reading path.
+
+FletBox can produce a smaller production build by bundling only the code used by the application, removing development whitespace, and applying tree shaking.
+
+This guide explains two different goals:
+
+- **Minification** reduces file size and load time.
+- **Code protection** makes the generated JavaScript harder to read, but cannot make browser code truly secret.
+
+## What `createBundle` does
+
+The FletBox bundle process uses esbuild with production-oriented options:
+
+```bash
+flet-box createBundle
+```
+
+Aliases:
+
+```bash
+flet-box build
+flet-box bundle
+npm run build
+```
+
+The build process bundles `src/app.js` and writes the result to `dist/src/app.js` with options equivalent to:
+
+```text
+--bundle
+--format=esm
+--minify
+--tree-shaking=true
+--target=es2020
+```
+
+It also copies the HTML file, assets, fonts, service worker, and `run.sh` when they exist.
+
+## Basic production workflow
+
+```bash
+# Install dependencies
+npm install
+
+# Create the optimized web build
+npm run build
+
+# Inspect the generated output
+find dist -maxdepth 3 -type f
+
+# Preview the production build
+cd dist
+./run.sh
+```
+
+Always test the `dist` directory, not only the development server. A development build and a production build can behave differently.
+
+## What minification changes
+
+Minification normally:
+
+- Removes unnecessary whitespace.
+- Removes comments that are not required at runtime.
+- Shortens local variable names when safe.
+- Compresses expressions.
+- Removes unreachable code.
+- Combines imported modules into the application bundle.
+- Removes unused exports through tree shaking.
+
+Minification does not change the intended public behavior of the application.
+
+## Reduce bundle size
+
+### Import only what you use
+
+Prefer focused imports:
+
+```javascript
+import { Button, Container, Text } from "flet-box";
+```
+
+Avoid importing a large internal surface when a focused import is enough. The bundler can remove unused code more effectively when imports are statically analyzable.
+
+### Avoid unnecessary dependencies
+
+Every dependency can add code, assets, initialization time, and security maintenance. Add a package only when it solves a real problem.
+
+### Keep assets outside JavaScript
+
+Images, fonts, videos, and large data files should usually remain assets instead of being embedded into JavaScript strings. Copy only the assets required by the application.
+
+### Use lazy loading for large features
+
+For large optional screens, load code only when the user needs it:
+
+```javascript
+const openReports = async () => {
+  const module = await import("./screens/ReportsScreen.js");
+  return module.ReportsScreen();
+};
+```
+
+The exact loading strategy depends on your application and server. Test lazy routes in the final `dist` directory.
+
+### Remove development-only code
+
+Keep debug panels, test data, verbose logs, and development-only routes out of the production entry point.
+
+```javascript
+if (import.meta.env?.DEV) {
+  console.log("Development information");
+}
+```
+
+Use a build setup that actually replaces environment flags before relying on them. Do not assume every bundler provides `import.meta.env` automatically.
+
+## Protecting browser code: the honest rule
+
+JavaScript shipped to a browser can be downloaded, inspected, and debugged by the user. Minification and obfuscation can slow down casual inspection, but they cannot provide real secrecy.
+
+Never put these values in frontend code:
+
+- Passwords.
+- Private API keys.
+- JWT signing secrets.
+- Database credentials.
+- SMTP passwords.
+- Cloud service private keys.
+- Internal security rules that must remain secret.
+
+Keep sensitive operations in FletBox Server or another backend and expose only the minimum API needed by the frontend.
+
+## Minification versus obfuscation
+
+### Minification
+
+Recommended for every production build:
+
+```bash
+flet-box build
+```
+
+It reduces size and removes readable formatting. It is usually fast and has low runtime risk.
+
+### Obfuscation
+
+Obfuscation changes code structure and names to make manual reading more difficult. It can increase bundle size, reduce performance, make debugging harder, and break code that depends on function names or dynamic property access.
+
+Use obfuscation only after measuring its impact. It is not a replacement for authentication, authorization, or server-side protection.
+
+If an obfuscator is introduced, run it only on the final browser bundle and test:
+
+- Application startup.
+- Router navigation.
+- Event handlers.
+- Dynamic imports.
+- PWA installation.
+- Capacitor Android builds.
+- Capacitor iOS builds.
+
+## Source maps
+
+Source maps make production debugging easier but also make original source code easier to recover. Decide intentionally whether to publish them.
+
+For a private staging build, source maps can be useful. For a public production build, do not publish source maps unless you understand the exposure and have access controls.
+
+The current FletBox shell build does not enable source maps by default. If you add them, keep them out of public hosting when the source is private.
+
+## Protect API calls
+
+The frontend is not a safe place for secrets. Protect backend routes instead:
+
+```javascript
+import { authenticate, hasRole } from "flet-box-server";
+
+const routes = Api({
+  "/admin/report": {
+    GET: {
+      handler: createReport,
+      middleware: [authenticate, hasRole("admin")],
+    },
+  },
+});
+```
+
+The browser may know that this endpoint exists, but it should not be able to use it without a valid token and role.
+
+## Protect the production build pipeline
+
+Use a repeatable build process:
+
+```bash
+rm -rf dist
+npm ci
+npm run build
+```
+
+Then verify:
+
+```bash
+# Check that the bundle exists
+ test -s dist/src/app.js
+
+# Check that development secrets are not present
+ grep -R "JWT_SECRET\|password\|apiKey" dist || true
+```
+
+Do not print or commit secret values while checking files. The example searches names only; inspect matches carefully.
+
+## Capacitor builds
+
+Build the web code before synchronizing native projects:
+
+```bash
+npm run build
+npx cap sync android
+npx cap sync ios
+```
+
+Then create a debug Android APK:
+
+```bash
+cd android
+./gradlew assembleDebug
+```
+
+For a production APK or an Android App Bundle, use the release tasks:
+
+```bash
+./gradlew assembleRelease
+./gradlew bundleRelease
+```
+
+The AAB is the usual format for Google Play. Release artifacts must be signed with a production key.
+
+Minification reduces the web payload inside the native application. It does not replace Android or iOS signing, secure storage, transport security, or native permission review.
+
+## Production checklist
+
+- Run `npm run build` from a clean state.
+- Confirm tree shaking is active.
+- Inspect the size of `dist/src/app.js`.
+- Remove development routes and debug data.
+- Do not ship secrets in frontend code.
+- Decide whether source maps should be private.
+- Test the actual `dist` output.
+- Test direct navigation to SPA routes.
+- Test PWA and Capacitor builds when used.
+- Use HTTPS for API calls.
+- Protect backend routes with authentication and authorization.
+- Keep signing keys and deployment credentials outside Git.
+
+---
+
+## Continue reading
+
+- **Previous:** [The FletBox CLI](../cli/README.md)
+- **Next:** [Build FletBox for mobile and other platforms](mobile-and-platforms.md) — Appendix B
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)