flet-box 1.0.4 → 1.0.5

package/docs/tools/reactivity.md

@@ -0,0 +1,288 @@
+# Reactivity in FletBox
+
+## Overview
+
+Reactivity in FletBox means **a widget changes when something else changes** — a state
+value, the theme, the route, or a prop you assign at runtime. There is no Virtual DOM
+layer: each mechanism below writes to a real element in place, and the most efficient one
+updates a single widget without re-running any component code.
+
+This page is the **catalogue** of every reactivity path the framework ships. There is no single magic system; there are complementary layers, from the in-memory store up to per-widget DOM accessors.
+
+## The catalogue at a glance
+
+| # | Mechanism | Produced by | Scope of the update |
+| --- | --- | --- | --- |
+| 1 | Key-based shared state | `useState(key, value)` | Bound widgets patched; app render only when needed |
+| 2 | Low-level store | `subscribeRam` / `saveRam` | Any code subscribed to RamStore keys |
+| 3 | Registered-widget updates | `useState(key, value, widget, propName)` | A single widget prop |
+| 4 | Reactive property setters | `widget.prop = value` | A single widget, no global render |
+| 5 | Imperative updates | `widget.update(props)` | One widget's merged props |
+| 6 | Live handles | `ref()` | The bound widget (methods + props) |
+| 7 | Side-effect watchers | `useWatchState(key, cb)` | A callback, no widget |
+| 8 | Theme reactivity | `subscribeTheme(cb)` / `watchSystemTheme()` | Theme subscribers |
+| 9 | Router reactivity | `subscribe(cb)` (Router) | Route subscribers (Scaffold, nav bars) |
+| 10 | Reactive prop values | `_isReactive` objects/functions | Resolved at apply time **and bound to the key** |
+
+## 1. Key-based shared state — `useState`
+
+The public state hook. Values live in the in-memory store keyed by a string and survive re-renders.
+
+```javascript
+const [count, setCount, subscribe] = useState("counter", 0);
+setCount((previous) => previous + 1);
+```
+
+`setState` writes to RamStore. One shared dispatcher then, in order: patches every
+widget bound to that key, runs the `subscribe` / `useWatchState` callbacks for the key,
+and **only if necessary** schedules an app render (debounced, so several changes made in
+the same tick cost one render). See **The surgical decision**, further down this page.
+
+Read the full rules in [State, memo & refs](state.md) and the [State guide](../guides/state.md).
+
+## 2. The low-level store — `RamStore`
+
+The raw reactive map behind `useState`. You can talk to it directly when you want one store shared by several subsystems.
+
+```javascript
+import { saveRam, getRam, subscribeRam } from "flet-box";
+
+subscribeRam((key, newValue, oldValue) => {
+  if (key === "user") renderProfile(newValue);
+});
+saveRam("user", { name: "Ada" });
+```
+
+`saveRam`, `updateRam`, and `deleteRam` all notify subscribers with `(key, newValue, oldValue)`; `clearAllRam` notifies with `null`s.
+
+## 3. Registered-widget updates — `useState(key, value, widget, propName)`
+
+The optional `widget` and `propName` arguments register a specific widget so a state change pushes the new value straight into it via `widget.update({ [propName]: newValue })` — the machinery that powers targeted updates.
+
+```javascript
+const label = Text({ text: "waiting…" });
+const [status, setStatus] = useState("status", "idle", label, "text");
+
+setStatus("done"); // calls label.update({ text: "done" })
+```
+
+Because the widget is now bound to the key, this form is surgical on its own: `setStatus`
+patches `label` and skips the app render, unless the component also *computed* with that
+key during its last render (see **The surgical decision**). Prefer passing the state value
+straight into a prop — mechanism 10 binds it for you — and use this signature when the
+widget already exists.
+
+## 4. Reactive property setters — `widget.prop = value`
+
+Every style, spacing, colour, typography, and text prop installed by the widget factory becomes a live accessor: reading `widget.prop` returns the current value, assigning calls `widget.update({ prop })` and patches **that element only**. No app render, no subscribers involved.
+
+```javascript
+header.text = "New title";        // element.textContent updates in place
+panel.update({ bgColor: "#e11d48" });
+```
+
+Two protections, by design:
+
+- `value` is never shadowed on form elements so the browser keeps live input state (use `setValue` or `widget.value` on inputs).
+- `width` / `height` are not shadowed on replaced elements (`img`, `canvas`, `video`, `iframe`, `embed`, `object`, `source`) to preserve their native intrinsic-size behaviour.
+
+## 5. Imperative updates — `widget.update(props)`
+
+The factory-level update method on every widget. It merges the new props into the stored props and re-applies styles, attributes, events, children, and effects through the same pipeline used at construction. A recursion guard (`MAX_UPDATE_DEPTH`) prevents runaway loops, and `child` / `children` are normalised so only one wins.
+
+```javascript
+card.update({ padding: 24, borderRadius: 16 });
+```
+
+## 6. Live handles — `ref()`
+
+A `ref` is a function bound to a widget's `ref` prop. The handle mirrors the widget's methods and property accessors, so you can read and write live:
+
+```javascript
+const label = ref();
+Text({ text: "Hi", ref: label });
+
+label.update({ text: "Saved!" }); // same as widget.update
+label.text = "Also works";        // forwarded to the widget
+```
+
+## 7. Side-effect watchers — `useWatchState`
+
+Like `useState`'s `subscribe`, but for side effects that should not touch widgets. Returns an unsubscribe function.
+
+```javascript
+const unsubscribe = useWatchState("counter", (newValue) => {
+  console.log("Counter hit", newValue);
+});
+```
+
+## 8. Theme reactivity — `subscribeTheme`
+
+Theme changes re-render subscribers. `runApp` subscribes itself so the whole app recolors on `setTheme` / `toggleTheme`, and some widgets (`ListTile`, `Rating`, `Badge`) subscribe individually to stay themed. `watchSystemTheme()` follows OS light/dark preference.
+
+```javascript
+const unsubscribeTheme = subscribeTheme((palette) => {
+  root.style.backgroundColor = palette.background;
+});
+```
+
+## 9. Router reactivity — `subscribe`
+
+The router notifies subscribers on navigation. Layout shells and navigation widgets (`Scaffold`, `BottomNavigation`, `DrawerItem`) subscribe so highlighting and route content stay in sync; they unsubscribe automatically when removed from the DOM.
+
+```javascript
+subscribe((route, params, query) => setBreadcrumb(route.path));
+```
+
+## 10. Reactive prop values — resolved **and bound when passed directly**
+
+A prop value can be a function or object flagged as reactive (`_isReactive`). The
+factory resolves it to its current value when the prop is applied — and when the
+value carries a state key (what `useState` returns), the factory **binds the widget
+to that key automatically**.
+
+```javascript
+const [color, setColor] = useState("color", "red");
+
+const box = Container({ bgColor: color });   // ← the binding is created here
+setColor("blue");                            // ← only `box` is patched
+```
+
+A directly-passed reactive prop gives you a **surgical** update: the change patches
+that one widget. The app does **not** re-render — not even once — and the DOM node
+is reused, so `widget.prop = value` writes made earlier are not thrown away.
+
+The binding is released automatically when the widget is removed (`onUnmount`), so
+detached widgets stop receiving updates.
+
+### The surgical decision
+
+The value returned by `useState` is a **live function**. When it reaches a prop, the
+factory resolves it *and* records the `(key → widget → prop)` link, so a later change
+patches that widget instead of re-running anything. When it is consumed inside the
+component, the string or boolean that reaches the prop carries no key left to bind, so the
+only way to reflect a change is to re-run the app.
+
+The dispatcher decides **per key, per change**, from exactly two facts:
+
+```javascript
+if (handled === 0 || isStructuralRead(changedKey)) triggerRender();
+```
+
+- `handled` — how many widgets were patched for this key (mechanisms 3 and 10).
+- `isStructuralRead(key)` — whether the component read that value *while rendering*,
+  during the last app render pass.
+
+So the app re-renders when the key has no bound widget, or when the component computed
+with it. A key can be both: then the widget **is** patched *and* the app re-renders, and
+the patch is wasted work on a node the rebuild replaces.
+
+What counts as a structural read:
+
+| Code inside the component | Kind of read | Update |
+| --- | --- | --- |
+| `Text({ text: count })` | value passed as a prop | surgical |
+| `Container({ bgColor: color })` | value passed as a prop | surgical |
+| `Text({ text: "Count: " + count })` | concatenation | app render |
+| `count > 5 ? A : B` | comparison in the component | app render |
+| `getState("items").map(…)` | list shape | app render |
+| `onPress: () => setCount(count + 1)` | inside an event handler | surgical |
+| `onCount((n) => …)` | inside a subscriber | surgical |
+
+Two properties of that set are worth knowing:
+
+- **It is rebuilt on every render pass.** A structural read that only happens under a
+  condition stops costing app renders as soon as the component stops doing it.
+- **Changes coalesce.** The render is scheduled with `setTimeout(…, 0)`, so three
+  `setCount` calls in one tick cost **one** app render.
+
+Measured on a `Column` whose `Text` children depend on one key:
+
+| component | changes | app renders | `Text` built | node reused |
+| --- | --- | --- | --- | --- |
+| only `Text({ text: count })` | 3 in one tick | **0** | 1 | yes |
+| Concatenation + `text: count` + ternary | 3 in one tick | 1 | 2 | no |
+| Only the concatenation | 2 in separate ticks | 2 | 3 | no |
+
+The first row is the surgical path: no component code runs, `count`'s single bound widget
+gets `update({ text: … })`. The last row shows the coalescing limit — a render per tick, not
+per change.
+
+### Keeping derived text surgical
+
+A derived string does not need an app render if you derive it in the subscriber instead of
+in the template:
+
+```javascript
+const App = () => {
+  const [count, setCount, onCount] = useState("counter", 0);
+  const label = Text({ text: "Count: 0" });
+  const badge = Text({ text: "poco" });
+
+  onCount((n) => {
+    label.update({ text: `Count: ${n}` });
+    badge.update({ text: n > 5 ? "MUCHO" : "poco" });
+  });
+
+  return Column({ children: [label, badge] });
+};
+```
+
+`onCount` runs outside a render pass, so its reads are not structural and the key stays
+surgical — measured at **0 app renders** for three changes. This is the same reason reading
+state inside `onPress` is free.
+
+### What the app render does *not* do
+
+There is no Virtual DOM and no reconciliation: an app render **re-runs the component and
+creates new elements**, and the previous ones are dropped. Earlier `widget.prop = value`
+writes and any internal state of the replaced subtree are lost (form fields keep what the
+user typed, because `value` is never shadowed). A key read structurally is therefore the
+one case where the framework does more work than it needs to — which is why the
+recommendation is always the same: pass state values straight into props.
+
+## Widget-owned reactivity
+
+Beyond the generic layer, many widgets expose their own imperative APIs and some are reactive setters themselves (`Slider.value`, `Accordion.expanded`, `Dropdown.options`). Each widget page lists them under **Instance methods**. These follow the same rule: they call `update(...)` internally on that widget.
+
+## Lifecycle containment
+
+Every subscriber API returns an unsubscribe function. State bindings are released through
+the widget's `onUnmount` hook — fired on both teardown paths — so a detached widget stops
+receiving patches and its key entry is dropped once no widget is left bound to it.
+`runApp`'s teardown sweeps the whole tree so re-renders do not leak listeners, timers, or
+observers.
+
+Note that `_cleanup` is **not** a lifecycle hook the framework calls; it is legacy. Resource
+release belongs in `onUnmount`.
+
+## Which one should you use?
+
+| You want to… | Use | Cost |
+| --- | --- | --- |
+| Update ONE widget from a state value, without touching the app | `useState` + pass the value straight into a prop (`Container({ bgColor: color })`) | surgical — 0 app renders |
+| Update ONE widget that already exists | `useState(key, value, widget, propName)` | surgical — 0 app renders |
+| Show derived text (`Count: 3`) without an app render | derive inside `subscribe` / `onCount` and call `widget.update(…)` | surgical — 0 app renders |
+| Change the structure of the tree from state | `useState` + read it in the component (ternary, `.map()`) | one app render per tick |
+| Update one widget without state at all | `widget.prop = value`, `widget.update(props)`, `ref().update` | surgical — 0 app renders |
+| React to any RamStore change | `subscribeRam` | surgical |
+| Run a side effect on a key | `useWatchState` / `subscribe` | none |
+| Follow the theme or the route | `subscribeTheme` / router `subscribe` | theme re-renders the app |
+| Update a widget's whole prop set | `widget.update(props)` | surgical |
+
+## Related pages
+
+- [State, memo & refs](state.md) — the `useState` / `ref` / `memo` reference (previous chapter).
+- [State guide](../guides/state.md) — full `useState` semantics for app state.
+- [Async, ids & logging](async-ids-log.md) — next chapter.
+- [Themes](theme.md) — theme tokens and theme control.
+
+---
+
+## Continue reading
+
+- **Previous:** [State, memo & refs](state.md)
+- **Next:** [Async, ids & logging](async-ids-log.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (4.5 of 12).

package/docs/tools/state.md

@@ -0,0 +1,103 @@
+# State, memo & refs
+
+## Overview
+Three power-ups for state and performance: `useState`/`useWatchState` for reactive values, `memo`/`memoWithKey`/`clearMemo` for caching expensive results, and `ref` for keeping a live handle to a widget.
+
+## When to use
+- Share values between widgets and re-render on change (`useState`).
+- Cache an expensive computation (parsing, formatting, mapping) with `memo`.
+- Grab a widget instance to update it later (`ref`).
+
+## Import
+
+```javascript
+import { useState, useWatchState, memo, ref } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `useState` | `useState(key, initialState, widget?, propName?)` | `[value, setValue, subscribe]` | Reactive state stored under `key`. `value` is live: pass it straight into a prop and the factory binds that widget to the key, so `setValue` patches only it. Optional `widget` + `propName` binds an existing widget explicitly. |
+| `useWatchState` | `useWatchState(key, callback)` | `() => void` | Watch a state key; returns an unsubscribe function. |
+| `memo` | `memo(fn)` | `T & { cache? }` | Cache a function by its arguments. |
+| `memoWithKey` | `memoWithKey(fn, keyFn)` | `T` | Cache using a custom result key. |
+| `clearMemo` | `clearMemo(memoizedFn)` | `void` | Drop a memoized function's cache. |
+| `ref` | `ref()` | `(widget) => widget & { update }` | Assign to a widget's `ref` prop to get a live handle. |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { useState, Button, Text, Column } from "flet-box";
+
+const [count, setCount] = useState("counter", 0);
+
+Column({
+  children: [
+    Text({ text: `Count: ${count}` }),   // derived here → app render
+    Text({ text: count }),               // passed as a prop → surgical
+    Button({
+      text: "Add one",
+      onPress: () => setCount((previous) => previous + 1),
+    }),
+  ],
+});
+```
+
+### Full example — live widget updates via `ref`
+
+```javascript
+import { Text, Button, ref } from "flet-box";
+
+const label = ref();
+
+Button({
+  text: "Rename",
+  onPress: () => label.update({ text: "Saved!" }),
+  ref: label,
+});
+```
+
+### Caching with `memo`
+
+```javascript
+import { memo } from "flet-box";
+
+const parseData = (raw) => JSON.parse(raw);
+const parseMemo = memo(parseData);
+
+const first = parseMemo(jsonText); // runs
+const second = parseMemo(jsonText); // cached, fast
+```
+
+## Notes
+
+- Read the full [State guide](../guides/state.md) for the complete `useState` rules: stable keys, updater functions, immutability, and widget binding.
+- `useState` returns `[value, setValue, subscribe]` — `subscribe(cb)` returns an unsubscribe function.
+- The returned value is **live**: passing it as a prop (`Text({ text: count })`) binds that
+  widget to the key and `setValue` patches it alone, with no app render. Computing with it
+  inside a component (`` `Count: ${count}` ``, a ternary, a `.map()`) is a structural read,
+  and that does re-render the app — see
+  [Reactivity in FletBox](reactivity.md).
+- Reads inside an event handler or a `subscribe` callback are never structural, so they
+  never cost an app render.
+- `memo` caches by serialized arguments; use `memoWithKey` when you want to control the cache key yourself, and `clearMemo` to free memory when the cache grows too large.
+- `ref()` returns a function for a widget's `ref` prop; the handle gives you `update(props)` to push new props into the widget.
+
+## Related pages
+- [Reactivity in FletBox](reactivity.md) — the full catalogue of every update mechanism.
+- [State guide](../guides/state.md) — full `useState` semantics.
+- [Text & time](text-and-time.md) — previous chapter.
+- [Async, ids & logging](async-ids-log.md) — next chapter.
+
+---
+
+## Continue reading
+
+- **Previous:** [Text & time](text-and-time.md)
+- **Next:** [Reactivity in FletBox](reactivity.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (4 of 12).

package/docs/tools/styling.md

@@ -0,0 +1,92 @@
+# Styling helpers (CSS in JS)
+
+## Overview
+Each styling helper returns a **CSS string** you can pass to a widget prop (`style`, `shadow`, `gradient`, etc.) — so you style widgets without hand-writing raw CSS. Sizes are in px unless the widget converts units for you.
+
+## When to use
+- Build `border`, `margin`, `padding`, `shadow`, `transform`, or `transition` values on the fly.
+- Create gradients and color variations with one line.
+
+## Import
+
+```javascript
+import { border, margin, padding, gradient, shadow, color } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `animation` | `animation(name, duration?, timing?, iteration?)` | `string` | CSS `animation` shorthand. `name` can also be an options object (`{ name, duration, timing, delay, iteration, direction, fillMode }`). |
+| `border` | `border(width = 1, style = "solid", color?)` | `string` | CSS `border` shorthand, e.g. `1px solid #e2e8f0`. |
+| `gradient` | `gradient(type, colors, angle = 135)` | `string` | A CSS gradient background. `type` is `"linear"`, `"circle"` (radial), or `"conic"`; `colors` is an array of color strings. |
+| `margin` / `padding` | `margin(value)` / `padding(value)` | `string` | Spacing CSS. `value` can be a number, a string, or `{ all, horizontal, vertical, top, right, bottom, left }`. |
+| `rgba` | `rgba(r, g, b, a = 1)` | `string` | `rgba(r, g, b, a)` with an alpha default of `1`. |
+| `shadow` | `shadow(x, y, blur, spread, color)` | `string` | A `box-shadow` value. |
+| `transform` | `transform(options)` | `string` | CSS `transform` built from `{ translate, translateX, rotate, scale, skew, matrix, matrix3d, perspective, … }`. |
+| `transition` | `transition(options)` | `string` | CSS `transition` built from `{ property, duration, timing, delay }` (or an array of them). |
+| `filter` | `filter(options)` | `string` | CSS `filter` from `{ blur, brightness, contrast, dropShadow, grayscale, hueRotate, invert, opacity, saturate, sepia }`. |
+| `flex` | `flex(grow, shrink = 1, basis = "0%")` | `string` | CSS `flex` shorthand. `grow` can also be `{ grow, shrink, basis }`. |
+| `grid` | `grid(options)` | `string` | CSS grid template from `{ columns, rows, gap }`; `gap` can be a number or `{ row, column }`. |
+| `color` | `color(value)` | Color object | A mutable, chainable color. See the Color object below. |
+| `stackPosition` | `stackPosition(widget, props)` | `Widget` | Applies absolute positioning/centering to a widget and returns it. |
+| `toREM` / `toPX` | `toREM(value)` / `toPX(value)` | `string \| undefined` | Convert a value between `rem` and `px`. |
+| `setBaseFontSize` | `setBaseFontSize(px)` | `void` | Change the `rem` base (default `16`). |
+| `getBaseFontSize` | `getBaseFontSize()` | `number` | The current `rem` base. |
+
+### The Color object
+
+`color(value)` returns a chainable object:
+
+`hex()`, `rgb()`, `rgba()` — string forms · `lighten(percent)`, `darken(percent)`, `alpha(value)`, `complement()` — mutate and return the object · `isDark()`, `isLight()` — booleans · `contrast()` — a readable contrast color.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Text, border } from "flet-box";
+
+Text({
+  text: "Card",
+  padding: 12,
+  border: border(1, "solid", "#cbd5e1"),
+});
+```
+
+### Full example
+
+```javascript
+import { Container, Text, gradient, shadow, color } from "flet-box";
+
+const blue = color("#2563eb").lighten(10);
+
+Container({
+  padding: 24,
+  gradient: gradient("linear", ["#2563eb", "#7c3aed"], 120),
+  shadow: shadow(0, 8, 24, 0, "rgba(0,0,0,0.2)"),
+  child: Text({ text: blue.hex(), color: "white" }),
+});
+```
+
+## Notes
+
+- These helpers only build **strings** — they do not render anything by themselves. Hand the result to a widget prop or `style`.
+- A number passed to `margin`/`padding` becomes `Npx`; a string is used as-is (so you can write `"1rem"` or `"10px 20px"`).
+- `animation(...)` differs from the [animate function](animation.md): this builds the CSS string, `animate()` runs an animation on an element.
+- The Color object is stateful — create a copy (`color(value)`) when you need two different variations.
+
+## Related pages
+- [Lists, arrays & data](lists.md) — the next chapter.
+- [Visual effects](visual-effects.md) — effects that apply to elements directly.
+- [Animation helpers](animation.md) — run animations on elements.
+
+---
+
+## Continue reading
+
+- **Previous:** [Tools index](README.md)
+- **Next:** [Lists, arrays & data](lists.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (1 of 12).

package/docs/tools/text-and-time.md

@@ -0,0 +1,89 @@
+# Text & time
+
+## Overview
+Small pure helpers for strings, dates, and media time. They take a value and return a formatted one — no side effects.
+
+## When to use
+- Normalize user names or titles before display (`capitalize`, `truncate`).
+- Show friendly dates and "2 minutes ago" labels.
+- Format audio/video positions in player UIs.
+
+## Import
+
+```javascript
+import { capitalize, truncate, formatDate, relativeTime } from "flet-box";
+```
+
+## Functions
+
+### Text
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `capitalize` | `capitalize(str)` | `string` | First letter uppercase. |
+| `capitalizeWords` | `capitalizeWords(str)` | `string` | First letter of every word uppercase. |
+| `lowerCase` | `lowerCase(str)` | `string` | All lowercase. |
+| `upperCase` | `upperCase(str)` | `string` | All uppercase. |
+| `reverseString` | `reverseString(str)` | `string` | Reversed text. |
+| `truncate` | `truncate(str, length?, suffix?)` | `string` | Cut to `length` characters and append `suffix` (default `"..."`). |
+
+### Dates & time
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `formatDate` | `formatDate(date, format?)` | `string` | Format a date/string/number as text. |
+| `relativeTime` | `relativeTime(date)` | `string` | A human label, e.g. `"2 minutes ago"`. |
+| `now` | `now()` | `number` | Timestamp in milliseconds. |
+
+### Media time
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `formatMediaTime` | `formatMediaTime(seconds)` | `string` | Compact `m:ss` (or `h:mm:ss`). |
+| `formatMediaTimeLong` | `formatMediaTimeLong(seconds)` | `string` | Long form with units. |
+| `getProgressPercent` | `getProgressPercent(current, total)` | `number` | `current/total` as a `0–100` percent. |
+| `percentToSeconds` | `percentToSeconds(percent, total)` | `number` | Inverse of `getProgressPercent`. |
+| `formatMediaProgress` | `formatMediaProgress(current, total)` | `string` | `"current / total"` formatted for a player. |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Text, capitalizeWords, relativeTime } from "flet-box";
+
+Text({
+  text: `${capitalizeWords("hello fletbox")} — ${relativeTime(Date.now() - 120000)}`,
+});
+// "Hello Fletbox — 2 minutes ago"
+```
+
+### Full example
+
+```javascript
+import { formatMediaProgress, getProgressPercent } from "flet-box";
+
+const pct = getProgressPercent(90, 300); // 30
+const label = formatMediaProgress(90, 300); // "1:30 / 5:00"
+```
+
+## Notes
+
+- `formatDate(date, format?)` accepts a `Date`, a timestamp, or a date string; `format` is optional and platform-specific tokens apply.
+- The media-time helpers are used by the [Audio](../widget/Audio.md) and [Video](../widget/Video.md) widgets.
+- All functions return new values — inputs are never modified.
+
+## Related pages
+- [Lists, arrays & data](lists.md) — previous chapter.
+- [State, memo & refs](state.md) — next chapter.
+- [Input validation](validation.md) — more string rules.
+
+---
+
+## Continue reading
+
+- **Previous:** [Lists, arrays & data](lists.md)
+- **Next:** [State, memo & refs](state.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (3 of 12).

package/docs/tools/theme.md

@@ -0,0 +1,102 @@
+# Themes
+
+## Overview
+FletBox ships a built-in color system: `colors` is the palette of the current theme, `palettes` holds all named palettes, and the theme functions switch between light and dark, subscribe to changes, and follow the system preference. A `ThemeProvider` and the `useTheme()` hook wrap them for component-based apps.
+
+## When to use
+- Style widgets with semantic tokens (`colors.surface`, `colors.primary`, `colors.error`) instead of hard-coded hex values.
+- Add a light/dark toggle that re-colors the whole app instantly.
+- Follow the OS dark/light setting automatically.
+
+## Import
+
+```javascript
+import { colors, setTheme, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `setTheme` | `setTheme('light' \| 'dark')` | `Record<string, string>` | Switch the active palette. |
+| `getTheme` | `getTheme()` | `string` | The active theme name. |
+| `toggleTheme` | `toggleTheme()` | `string` | Flip light/dark and return the new name. |
+| `getColor` | `getColor(name, opacity?)` | `string` | Resolve a token (optionally with alpha). |
+| `subscribeTheme` | `subscribeTheme(callback)` | `() => void` | Subscribe to theme changes; returns an unsubscribe function. |
+| `applySystemTheme` | `applySystemTheme()` | `string` | Apply light/dark from the OS preference. |
+| `watchSystemTheme` | `watchSystemTheme()` | `() => void` | Follow the OS preference live; returns an unsubscribe function. |
+| `ThemeProvider` | `ThemeProvider({ children, theme? })` | `Widget` | Provide a theme (defaults to system) for a subtree. |
+| `useTheme` | `useTheme()` | object | `{ colors, setTheme, getTheme, toggleTheme, getColor, applySystemTheme }`. |
+
+Plus the constants: `colors` (current palette) and `palettes` (all named palettes, keyed by name).
+
+## Color tokens
+
+Every token is available on `colors`:
+
+- **Brand:** `primary`, `secondary`, `info`, `success`, `warning`, `danger`, `error`.
+- **Surfaces:** `background`, `surface`, `card`, `overlay`.
+- **Text:** `text`, `textSecondary`, `textDisabled`, `divider`, `border`, `shadow`.
+- **Tints:** `gray50` … `gray900`, plus the soft backgrounds `errorBg`, `successBg`, `warningBg`, `infoBg`.
+
+The `dark` palette overrides the surface/text tokens; `gray*` and brand colors also shift to keep contrast. Read [the palette walkthrough](../guides/utilities.md) for usage patterns.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Button, colors, toggleTheme } from "flet-box";
+
+Button({
+  text: "Switch theme",
+  onPress: () => toggleTheme(),
+});
+
+const card = { backgroundColor: colors.surface, color: colors.text };
+```
+
+### Full example
+
+```javascript
+import { runApp, Container, Column, Button, Text, useTheme } from "flet-box";
+
+const ThemedApp = () => {
+  const theme = useTheme();
+
+  return Container({
+    backgroundColor: theme.colors.background,
+    padding: 24,
+    child: Column({
+      gap: 12,
+      children: [
+        Text({ text: `Theme: ${theme.getTheme()}`, color: theme.colors.text }),
+        Button({ text: "Toggle", onPress: () => theme.toggleTheme() }),
+      ],
+    }),
+  });
+};
+
+runApp(ThemeProvider({ children: ThemedApp() }), "root");
+```
+
+## Notes
+
+- The shared palette tokens are updated across all widgets when you switch themes; widgets referencing `colors.*` at build time pick up the active palette.
+- `watchSystemTheme()` and `applySystemTheme()` read `prefers-color-scheme`; both return/need cleanup to release listeners.
+- `subscribeTheme(callback)` fires with the new palette object — remember to unsubscribe when a feature is destroyed.
+
+## Related pages
+- [Device & environment](device.md) — previous chapter.
+- [Markdown, code & HTML](markdown.md) — next chapter.
+- [Colors and utilities guide](../guides/utilities.md) — palette walkthrough.
+
+---
+
+## Continue reading
+
+- **Previous:** [Device & environment](device.md)
+- **Next:** [Markdown, code & HTML](markdown.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (7 of 12).