flet-box 1.0.4 → 1.0.6

package/docs/guides/app-templates.md

@@ -0,0 +1,197 @@
+# Build your first FletBox app
+
+This guide shows complete app shapes. You can copy one example, run it, and then replace the text or widgets with your own ideas.
+
+## 1. The smallest app
+
+Start with one widget and mount it with `runApp`.
+
+```javascript
+import { runApp, Container, Text } from "flet-box";
+
+const App = () => {
+  return Container({
+    padding: 20,
+    child: Text({ text: "Hello World" }),
+  });
+};
+
+runApp(App, "root");
+```
+
+What happens:
+
+- `App` is a function that describes the screen.
+- `Container` creates a layout box.
+- `Text` writes words inside the box.
+- `runApp` places the result in the HTML element with id `root`.
+
+## 2. A styled page
+
+```javascript
+import { runApp, Container, Text, colors } from "flet-box";
+
+const App = () => {
+  return Container({
+    padding: 20,
+    bgColor: colors.background,
+    borderRadius: 16,
+    child: Text({
+      text: "My App",
+      size: 24,
+      weight: "bold",
+    }),
+  });
+};
+
+runApp(App, "root");
+```
+
+Use `padding` for space inside the box. Use `bgColor` to change its background. Use `borderRadius` to soften its corners.
+
+## 3. A page with a top bar
+
+```javascript
+import { runApp, Scaffold, AppBar, Text, colors } from "flet-box";
+
+const App = () => {
+  return Scaffold({
+    appBar: AppBar({
+      title: "My App",
+      centerTitle: true,
+    }),
+    body: Text({ text: "Main content" }),
+    backgroundColor: colors.background,
+  });
+};
+
+runApp(App, "root");
+```
+
+`Scaffold` gives a page a standard structure. `appBar` is the top area and `body` is the main content.
+
+## 4. A page with a side menu
+
+```javascript
+import {
+  runApp,
+  Scaffold,
+  AppBar,
+  Drawer,
+  DrawerItem,
+  Icon,
+  Text,
+  colors,
+  openDrawer,
+} from "flet-box";
+
+const App = () => {
+  return Scaffold({
+    appBar: AppBar({
+      title: "My App",
+      leading: Icon({
+        name: "menu",
+        onPress: () => openDrawer(),
+      }),
+    }),
+    drawer: Drawer({
+      header: Text({ text: "Menu", size: 20, weight: "bold", padding: 20 }),
+      body: [
+        DrawerItem({ icon: "home", label: "Home", route: "/" }),
+        DrawerItem({ icon: "settings", label: "Settings", route: "/settings" }),
+      ],
+    }),
+    body: Text({ text: "Main content" }),
+    backgroundColor: colors.background,
+  });
+};
+
+runApp(App, "root");
+```
+
+The menu button calls `openDrawer`. Each `DrawerItem` describes one navigation option.
+
+## 5. A page with tabs
+
+```javascript
+import { runApp, Scaffold, AppBar, Tabs, Text, colors } from "flet-box";
+
+const App = () => {
+  return Scaffold({
+    appBar: AppBar({ title: "My App", centerTitle: true }),
+    body: Tabs({
+      tabs: ["Home", "Profile", "Settings"],
+      children: [
+        Text({ text: "Home screen" }),
+        Text({ text: "User profile" }),
+        Text({ text: "Settings" }),
+      ],
+    }),
+    backgroundColor: colors.background,
+  });
+};
+
+runApp(App, "root");
+```
+
+The first item in `tabs` matches the first item in `children`, the second matches the second, and so on.
+
+## 6. A reusable component
+
+```javascript
+import { Container, Text, colors } from "flet-box";
+
+export const ProfileCard = ({ title, onPress }) => {
+  return Container({
+    padding: 16,
+    bgColor: colors.surface,
+    borderRadius: 12,
+    onPress,
+    child: Text({
+      text: title || "My Profile",
+      size: 18,
+      weight: "bold",
+    }),
+  });
+};
+```
+
+A component is a function that receives values and returns widgets. This lets you reuse the same design in many places.
+
+## 7. A list with data
+
+```javascript
+import { ListView, ListTile, createList, random } from "flet-box";
+
+const createUsers = () => createList({
+  id: () => random.id(),
+  title: () => random.fullName(),
+  subtitle: () => random.email(),
+}, 20);
+
+export const UserList = ({ data = createUsers(), onSelect }) => {
+  return ListView({
+    data,
+    renderItem: (item) => ListTile({
+      title: item.title,
+      subtitle: item.subtitle,
+      onPress: () => onSelect(item),
+    }),
+  });
+};
+```
+
+`data` is the collection. `renderItem` explains how one item should look. FletBox repeats that design for every item.
+
+## A simple learning path
+
+1. Build a page with `Container` and `Text`.
+2. Add `Column` and `Row` to arrange content.
+3. Add a `Button` and an event such as `onPress`.
+4. Add `Input`, `Checkbox`, `Switch`, or `Dropdown` for user input.
+5. Use `Scaffold`, `AppBar`, `Drawer`, or `Tabs` for a larger screen.
+6. Extract repeated designs into reusable components.
+
+For individual widget details, return to the [widget documentation](../widget/README.md) or begin with [Start here](../widget/START_HERE.md).
+
+If you already have a page and only want to add one interactive area, read [Add FletBox to an existing page](embedding.md).

package/docs/guides/compatibility.md

@@ -0,0 +1,95 @@
+# Compatibility and support
+
+> **Level: Advanced.** This page is for shipping — skip it on a first read. It follows [mobile and platforms](mobile-and-platforms.md) in the book's reading path.
+
+FletBox targets browser-based applications and can also be packaged for mobile platforms.
+
+## Platform matrix
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Modern browsers | Supported | Uses DOM, ES modules, and browser APIs. |
+| Static web hosting | Supported | Build with `npm run build`. |
+| PWA | Supported | Requires manifest, service worker, and HTTPS in production. |
+| Android | Supported through Capacitor | Build the web app first, then sync Capacitor. |
+| iOS | Supported through Capacitor | Requires macOS and Xcode. |
+| Desktop | Possible through Electron or Tauri | Package the generated web build. |
+| Server-side rendering | Not a primary target | Widgets depend on browser DOM APIs. |
+
+## Runtime requirements
+
+### Browser
+
+The application expects support for:
+
+- ES modules.
+- `fetch`.
+- `localStorage` and `sessionStorage` when storage services are used.
+- DOM events and `HTMLElement`.
+- `AbortSignal.timeout` when using the default HTTP timeout behavior.
+- `WebSocket` when HMR is enabled.
+
+Private browsing, sandboxed iframes, and strict browser policies may disable some APIs. Check availability before using storage or device features.
+
+### Node.js
+
+Node.js 18 or newer is required for the CLI and build tooling. FletBox widgets themselves are browser-oriented and should not be rendered directly in a Node process without a DOM environment.
+
+## Build targets
+
+The main build path is:
+
+```bash
+npm run build
+```
+
+Then use the output in `dist/` for hosting or Capacitor:
+
+```bash
+npx cap sync android
+npx cap sync ios
+```
+
+See [Mobile and platforms](mobile-and-platforms.md) for APK, AAB, iOS, PWA, and desktop workflows.
+
+## Browser feature checks
+
+```javascript
+import { device, isStorageAvailable } from "flet-box";
+
+if (device.isMobile()) {
+  console.log("Mobile device");
+}
+
+if (!isStorageAvailable()) {
+  console.warn("Persistent storage is not available");
+}
+```
+
+## API stability labels
+
+Documentation uses these meanings:
+
+- **Stable**: exported, documented, and intended for normal application use.
+- **Compatible alias**: an alternative name kept to make migration easier.
+- **Experimental**: available but subject to behavior or API changes.
+- **Legacy**: retained for older projects; prefer the current documented form.
+
+When the runtime and `index.d.ts` disagree, the implementation must be verified before treating the feature as stable.
+
+## Known compatibility boundaries
+
+- Browser storage is origin-scoped and limited in size.
+- WebView behavior can differ from desktop browsers.
+- Native device features require Capacitor plugins and permissions.
+- HMR is a development feature and should not be required in production.
+- Direct browser DOM access is required for widget mounting.
+- Source maps can expose original source and should be handled intentionally.
+
+---
+
+## Continue reading
+
+- **Previous:** [Build FletBox for mobile and other platforms](mobile-and-platforms.md)
+- **Next:** [Add FletBox to an existing page](embedding.md) — Appendix D
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/embedding.md

@@ -0,0 +1,284 @@
+# Add FletBox to an existing page
+
+> **Level: Advanced.** This page is for integration work. It is the last page of the book.
+
+FletBox does not have to control your whole application. You can add one widget to an existing HTML page and keep using your current backend, CSS, JavaScript, or frontend framework.
+
+This is useful when you want to add an interactive feature without rewriting the rest of the page.
+
+## Two ways to use FletBox
+
+### Complete application
+
+Use `runApp()` when FletBox owns the main interface, routing, theme, and rendering lifecycle:
+
+```javascript
+import { runApp, Container, Text } from "flet-box";
+
+const App = () => Container({
+  padding: 24,
+  child: Text({ text: "A complete FletBox screen" }),
+});
+
+runApp(App, "root");
+```
+
+### Add one part to an existing page
+
+Use `insertBy()` when your page already exists and you only want to add a widget:
+
+```javascript
+import { Button, insertBy } from "flet-box";
+
+insertBy(
+  Button({
+    text: "Open panel",
+    onPress: () => console.log("clicked"),
+  }),
+  "existing-root",
+);
+```
+
+The existing HTML only needs an element with the matching id:
+
+```html
+<div id="existing-root"></div>
+```
+
+## Add FletBox with a browser import map
+
+A plain HTML page can import FletBox as an ES module:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "flet-box": "./node_modules/flet-box/src/index.js"
+  }
+}
+</script>
+
+<div id="toolbar"></div>
+
+<script type="module">
+  import { Button, insertBy } from "flet-box";
+
+  insertBy(
+    Button({
+      text: "Save",
+      onPress: () => alert("Saved"),
+    }),
+    "toolbar",
+  );
+</script>
+```
+
+Your page must be served through a development server or web server. Browser module imports usually do not work correctly when opening the file directly with `file://`.
+
+## Add a widget after existing content
+
+Use `insertBy()` to append a widget:
+
+```javascript
+import { Card, Text, insertBy } from "flet-box";
+
+insertBy(
+  Card({
+    padding: 16,
+    child: Text({ text: "This card was added to an existing page." }),
+  }),
+  "content",
+);
+```
+
+## Add a widget before or after another element
+
+The target is an element id:
+
+```javascript
+import { Button, insertBefore, insertAfter } from "flet-box";
+
+const button = Button({ text: "Action" });
+
+insertBefore(button, "original-heading");
+insertAfter(Button({ text: "Next action" }), "original-heading");
+```
+
+HTML:
+
+```html
+<h1 id="original-heading">Existing heading</h1>
+```
+
+## Replace an existing element
+
+Use `replaceBy()` when a FletBox widget should take the place of an existing DOM element:
+
+```javascript
+import { Container, Text, replaceBy } from "flet-box";
+
+replaceBy(
+  Container({
+    padding: 20,
+    bgColor: "#eff6ff",
+    child: Text({ text: "This replaces the old content." }),
+  }),
+  "legacy-message",
+);
+```
+
+## Insert at the beginning
+
+Use `prependBy()` to place the widget before the current first child:
+
+```javascript
+import { Text, prependBy } from "flet-box";
+
+prependBy(Text({ text: "Welcome", color: "#2563eb" }), "page-content");
+```
+
+## Mount the same widget in several roots
+
+`mountAll()` clones a widget and appends a copy to each root id:
+
+```javascript
+import { Text, mountAll } from "flet-box";
+
+const notice = Text({
+  text: "Updated content",
+  color: "#2563eb",
+});
+
+mountAll(notice, ["header-notice", "footer-notice"]);
+```
+
+HTML:
+
+```html
+<div id="header-notice"></div>
+<div id="footer-notice"></div>
+```
+
+For complex interactive widgets, prefer creating a fresh widget for each root so each instance has its own state and event handlers.
+
+## Use a custom HTML page
+
+FletBox can live beside normal HTML:
+
+```html
+<section class="legacy-profile">
+  <h2>Existing profile</h2>
+  <p>This content was already on the page.</p>
+  <div id="profile-actions"></div>
+</section>
+```
+
+```javascript
+import { Button, Row, Text, insertBy } from "flet-box";
+
+insertBy(
+  Row({
+    gap: 8,
+    children: [
+      Text({ text: "Actions:" }),
+      Button({ text: "Edit", onPress: () => openEditor() }),
+      Button({ text: "Delete", variant: "outlined", onPress: () => removeProfile() }),
+    ],
+  }),
+  "profile-actions",
+);
+```
+
+FletBox only owns the DOM node where the widget is mounted. The rest of the page remains yours.
+
+## Use FletBox with another frontend
+
+You can mount a FletBox widget from React, Vue, Angular, or another application as long as you have a DOM element:
+
+```javascript
+const target = document.querySelector("#external-toolbar");
+const widget = Button({ text: "FletBox action" });
+
+target.appendChild(widget);
+```
+
+For a framework integration, mount and remove the widget inside that framework's lifecycle. Keep the widget reference so you can remove it during cleanup.
+
+## Direct DOM access
+
+Every widget is a real `HTMLElement`. You can use standard DOM APIs when needed:
+
+```javascript
+const button = Button({ text: "Inspect me" });
+
+button.setAttribute("aria-label", "Inspect me");
+button.addEventListener("mouseenter", () => {
+  console.log("native DOM event");
+});
+
+document.querySelector("#actions").appendChild(button);
+```
+
+Prefer direct widget props such as `className` and framework event props when they are enough. Use direct DOM access for integration with existing page code.
+
+## Choosing the right mounting API
+
+| Goal | API |
+| --- | --- |
+| Build the whole FletBox application | `runApp()` |
+| Add a widget at the end of a root | `insertBy()` |
+| Add a widget at the beginning | `prependBy()` |
+| Place a widget before an element | `insertBefore()` |
+| Place a widget after an element | `insertAfter()` |
+| Replace an existing element | `replaceBy()` |
+| Add copies to several roots | `mountAll()` |
+| Create a controllable app instance | `createApp()` |
+
+## `createApp()` for a controlled application
+
+Use `createApp()` when you want explicit `start()` and `destroy()` methods:
+
+```javascript
+import { Container, Text, createApp } from "flet-box";
+
+const app = createApp(
+  {
+    "/": () => Container({
+      padding: 20,
+      child: Text({ text: "Home" }),
+    }),
+  },
+  {
+    rootId: "app-root",
+    fallback: Container({
+      padding: 20,
+      child: Text({ text: "Loading..." }),
+    }),
+  },
+);
+
+app.start();
+
+// Later, when the page or integration is destroyed:
+// app.destroy();
+```
+
+## Important integration tips
+
+- Mount into a dedicated element instead of replacing an unrelated page section.
+- Give every integration root a stable id.
+- Use `children: [ ... ]` for several widgets and `child: widget` for one child.
+- Keep application state inside the integration when possible.
+- Clean up app instances when a page is removed.
+- Use `runApp()` only when FletBox should own the root lifecycle.
+- Use `insertBy()` and related helpers when FletBox is only one part of the page.
+
+---
+
+## Continue reading
+
+- **Previous:** [Compatibility and support](compatibility.md)
+- **Next:** [Ship updates without the store (OTA / online updates)](online-updates.md) — Appendix E
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
+
+> The [FletBox Server](../server/README.md) toolkit is a separate backend product and is not part of the reading path.