flet-box 1.0.4 → 1.0.5

package/docs/tools/README.md

@@ -0,0 +1,138 @@
+# Tools: FletBox helper functions
+
+This directory is the reference index for the helper functions that ship with FletBox — the pre-built code that lets you solve common problems **inside the framework**, without reaching for a third-party library or a search engine.
+
+Tools are plain JavaScript functions. You import them from `flet-box` exactly like widgets:
+
+```javascript
+import { rgba, uuid, sort, formatDate } from "flet-box";
+```
+
+> **Tools vs. Services.** *Tools* are pure helpers — they take input and give you back a value (a color string, a sorted array, a formatted date, a new id). *Services* talk to the outside world — browser storage and the network. Find services in the [services index](../services/README.md).
+
+For a task-oriented walkthrough of the most common helpers, read the [Utilities guide](../guides/utilities.md). This index lists everything the framework actually exports today, grouped by category, and **each category has its own reference page** with full signatures, returns, and examples. Every name below is present in `src/index.js`; the implementation lives in `src/tools/` and `src/utils/` (plus `src/animations/` for the animation helpers).
+
+## The tourist's map
+
+Each category is the next chapter of the reading path:
+
+| Page | What you find there |
+| --- | --- |
+| [Styling helpers](styling.md) | CSS-in-JS strings: `border`, `margin`, `gradient`, `color`, `transform`, … |
+| [Lists, arrays & data](lists.md) | `mapList`, `repeat`, `sort`, `unique`, `createList`, `dict`, `random` |
+| [Text & time](text-and-time.md) | `capitalize`, `truncate`, `formatDate`, media-time helpers |
+| [State, memo & refs](state.md) | `useState`, `memo`, `ref` |
+| [Reactivity in FletBox](reactivity.md) | Every way a widget updates: state, setters, theme, router, and more |
+| [Async, ids & logging](async-ids-log.md) | `delay`, `retry`, `uuid`, `shortId`, `print` |
+| [Device & environment](device.md) | `device`, `os`, `dimensions`, `clipboard` |
+| [Themes](theme.md) | `colors`, `setTheme`, `ThemeProvider`, `useTheme` |
+| [Markdown, code & HTML](markdown.md) | markdown → HTML/widgets, syntax highlighting, `escapeHtml` |
+| [Visual effects](visual-effects.md) | `applyShimmer`, `applyGlow`, `applyPulse`, `injectKeyframes` |
+| [Widget introspection](introspection.md) | `getWidgetProps`, `getWidgetProp`, `stringifyWidgetProps` |
+| [Input validation](validation.md) | `TextInputValidator` rules |
+| [Animation helpers](animation.md) | `animate`, `fadeIn`, `pulse` + `AnimatedBox` and friends |
+
+## Styling helpers (CSS in JS)
+
+Small functions that return CSS values, so you can style widgets without writing raw CSS strings.
+
+- `animation(value)` — build a CSS `animation` shorthand string.
+- `border(width, style, color)` — build a `border` shorthand string.
+- `gradient(type, colors, angle)` — build linear, radial, and conic gradients.
+- `margin(...)` / `padding(...)` — turn numbers or CSS shorthand into a spacing value.
+- `rgba(r, g, b, a)` — build an `rgba()` string from parts.
+- `shadow(value)` — build a `box-shadow` string.
+- `transform(value)` / `transition(value)` — build CSS `transform`/`transition` strings.
+- `filter(value)` — build a CSS `filter` string.
+- `flex(...)` — build a `flex` shorthand string.
+- `grid(...)` — build grid template and area strings.
+- `color(value)` — create a chainable Color object: `hex()`, `rgb()`, `rgba()`, `lighten(n)`, `darken(n)`, `alpha(a)`, `complement()`, plus `isDark()`/`isLight()` and `contrast()`.
+- `stackPosition(...)` — apply absolute stacking position + centering.
+- `toREM(value)`, `toPX(value)`, `setBaseFontSize(px)`, `getBaseFontSize()` — unit conversion helpers.
+
+## Lists, arrays & data
+
+Helpers for shaping collections and generating data.
+
+- `mapList(list, fn)` — map a list; `repeat(n, fn)` and `range(a, b)` generate lists.
+- `shuffle(list)`, `reverse(list)`, `sort(list)`, `unique(list)`, `chunk(list, size)` — collection transforms.
+- `dict(...)` / `emptyDict()` — a Python-like dictionary with chainable methods.
+- `fromJSON(text)` / `fromEntries(entries)` — object building helpers.
+- `createList(schema, count)` — generate mock/structured data.
+- `random(...)` — random numbers, ids, colors, and fake data.
+
+## Text & time
+
+- `capitalize(text)`, `capitalizeWords(text)`, `lowerCase(text)`, `upperCase(text)`, `reverseString(text)`, `truncate(text, len)` — text transforms.
+- `formatDate(date)`, `relativeTime(date)`, `now()` — date helpers; `sleep(ms)` — async delay.
+- Media-time helpers: `formatMediaTime(sec)`, `formatMediaTimeLong(sec)`, `getProgressPercent(current, total)`, `percentToSeconds(pct, total)`, `formatMediaProgress(current, total)`.
+
+## State, memo & refs
+
+- `useState(key, initial, widget?, propName?)` — reactive state that re-renders widgets.
+- `useWatchState(key, callback)` — subscribe to state changes; returns an unsubscribe function.
+- `memo(fn)`, `memoWithKey(fn, keyFn)`, `clearMemo(memoizedFn)` — cache expensive results.
+- `ref(...)` — hold a live reference to a widget and update it.
+- See [Reactivity in FletBox](reactivity.md) for the full catalogue of update mechanisms.
+
+## Async, ids & logging
+
+- `delay(ms)` — async sleep; `withMinDelay(promise, ms)` — enforce a minimum delay; `retry(call, retries, delayMs)` — retry an async call.
+- `uuid()`, `shortId()`, `numericId()`, `timestampId()` — id generators.
+- `print(...)` — a small logging helper.
+
+## Device & environment
+
+- `device` — detect device type, touch, and orientation.
+- `os` — detect the operating system and browser.
+- `dimensions` — live viewport dimensions; `width` and `height` — viewport helpers.
+- `clipboard` — copy and read text from the clipboard.
+- `addNavigation(...)` — navigation helper.
+
+## Themes
+
+- `colors` and `palettes` — theme color tokens.
+- `setTheme(theme)`, `getTheme()`, `toggleTheme()`, `subscribeTheme(callback)`, `applySystemTheme()`, `watchSystemTheme()`, `getColor(name)` — theme control.
+
+## Markdown, code & HTML helpers
+
+- `parseMarkdown(md)`, `parseInlineMarkdown(md)` — reserved placeholders that pass text through unchanged (real rendering is `markdownToWidgets`/`parseInlineToWidgets`).
+- `markdownToWidgets(md)` / `parseMarkdownToWidgets(md)` — markdown string → widgets (alias names for the same function).
+- `tokenize(code)`, `generateHighlightedHtml(code)`, `highlightColors` — syntax highlighting.
+- `escapeHtml(text)` — escape untrusted text before inserting it as HTML.
+
+## Visual effects
+
+- `applyStripes(el)`, `removeStripes(el)`, `applyShimmer(el)`, `applyGlow(el)` — static visual effects.
+- `applyIndeterminate(el)`, `applyPulse(el)`, `injectKeyframes(name, keyframes)` — animation-driven effects.
+
+## Widget introspection
+
+- `getWidgetProps(widget)`, `getWidgetProp(widget, name)`, `stringifyWidgetProps(widget)` — inspect a widget's props.
+
+## Input validation
+
+- `TextInputValidator` — rules (`isEmail`, `onlyNumbers`, `onlyLetters`, `limitLength`, `sanitize`, `filter`, …) used by the `Input` widget's `validation` prop.
+
+## Animation helpers
+
+- `animate(el, ...)`, `animateAsync(el, ...)`, `fadeIn(el, ...)`, `fadeOut(el, ...)`, `pulse(el, ...)` and their `*Async` variants.
+- Widgets: `AnimatedBox`, `AnimatedText`, `MatrixRain`, `ParallaxBox`.
+
+## Where to go next
+
+- [Utilities guide](../guides/utilities.md) — the practical walkthrough for the most-used helpers.
+- [Frontend services guide](../guides/frontend-services.md) — storage and network services.
+- [Guides index](../guides/README.md) — every FletBox guide in reading order.
+- [Services index](../services/README.md) — the storage and HTTP service reference.
+- [Widgets](../widget/README.md) — the widget book.
+
+---
+
+## Continue reading
+
+- **Previous:** [HTTP client](../services/http.md)
+- **Next:** [Styling helpers](styling.md)
+- **Index:** [Services index](../services/README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (chapter opener).

package/docs/tools/animation.md

@@ -0,0 +1,87 @@
+# Animation helpers
+
+## Overview
+Two ways to animate in FletBox: `animate`/`fadeIn`/`fadeOut`/`pulse` (and their `Async` variants) run animations on existing elements, while the widgets `AnimatedBox`, `AnimatedText`, `MatrixRain`, and `ParallaxBox` give you animated UI out of the box. Every helper-driven animation is cancelable — through the function it returns or later with `stopAnimation(widget)`.
+
+## When to use
+- Animate an element when something happens: fade a panel in, pulse a button, animate a value change.
+- Stop an animation the element no longer needs: `onUnmount(() => stopAnimation(el))`.
+- Add moving backgrounds (`MatrixRain`, `ParallaxBox`).
+
+## Import
+
+```javascript
+import { animate, fadeIn, fadeOut, pulse, stopAnimation, AnimatedBox } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `animate` | `animate(widget, property, from, to, duration?, easing?)` | cancel `() => boolean` | Animate one CSS `property` of a widget from `from` to `to` (both numbers or colors). `duration` is ms, `easing` defaults to `"linear"`. Calling the returned function stops the loop and returns `true` if it was still running. |
+| `animateAsync` | `animateAsync(widget, property, from, to, duration?, easing?)` | `Promise` | Same, resolves with the widget when the animation finishes — or as soon as it is cancelled or replaced, so `await` never hangs. |
+| `stopAnimation` | `stopAnimation(widget, property?)` | `boolean` | Stop what is animating `widget` — one `property`, or every animated property when it is omitted. Use it in `onUnmount` when you did not keep the cancel function. |
+| `fadeIn` | `fadeIn(widget, duration?)` | cancel `() => boolean` | Fade the widget in (default 300 ms). |
+| `fadeOut` | `fadeOut(widget, duration?)` | cancel `() => boolean` | Fade it out. |
+| `pulse` | `pulse(widget, duration?)` | cancel `() => boolean` | A quick scale pulse: up for the first half, back down for the second. |
+| `fadeInAsync` / `fadeOutAsync` / `pulseAsync` | same, `Async` suffix | `Promise` | Promise variants that resolve on completion. |
+
+Starting a second animation on the same widget and property **replaces** the first one; two loops writing
+one style would otherwise fight, and the older animation would resume after the newer had finished.
+
+## Widgets
+
+- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget. `animations` is an array of `{ effect, from, to, duration }` entries; effects include `backgroundColor`, `color`, `borderRadius`, `opacity`, `scale`, `translate`, `rotate`, `width`, `height`, spacing, `boxShadow`, and gradients.
+- `AnimatedText({ child, animations, sameTime, delayBetween, orientation })` — animates a `Text` widget (letters split per animation).
+- `MatrixRain({ chars, fontSize, speed, fadeAmount, resetProbability, useDynamicColor, position, zIndex })` — the falling-characters canvas effect (returns a `canvas`).
+- `ParallaxBox({ type, speed, direction, maxOffset, reverse, child })` — content that moves; `type` is `"scroll"`, `"mouse"`, or `"hover"`, `direction` is `"vertical"`, `"horizontal"`, or `"both"`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Button, Container, Text, fadeOut } from "flet-box";
+
+const panel = Container({ padding: 24, child: Text({ text: "Hi" }) });
+
+Button({
+  text: "Hide",
+  onPress: () => fadeOut(panel, 300),
+});
+```
+
+### Full example
+
+```javascript
+import { AnimatedBox, Text } from "flet-box";
+
+AnimatedBox({
+  animations: [
+    { effect: "scale", from: 0.5, to: 1, duration: 600 },
+    { effect: "opacity", from: 0, to: 1, duration: 400 },
+  ],
+  child: Text({ text: "Welcome!" }),
+});
+```
+
+## Notes
+
+- Animation timing follows CSS `animation-duration` speeds (seconds/ms values depending on context — pass a number for ms in the widget props).
+- The `Async` variants are handy for sequences: `await fadeInAsync(el); await fadeOutAsync(el);`
+- For CSS-string animations use the `animation()` styling helper from [Styling helpers](styling.md).
+
+## Related pages
+- [Input validation](validation.md) — previous chapter.
+- [Utilities guide](../guides/utilities.md) — next stop: the whole toolkit walkthrough.
+- [Styling helpers](styling.md) — the `animation()` CSS builder.
+
+---
+
+## Continue reading
+
+- **Previous:** [Input validation](validation.md)
+- **Next:** [Utilities guide](../guides/utilities.md) — Chapter 10 wrap-up
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (12 of 12).

package/docs/tools/async-ids-log.md

@@ -0,0 +1,80 @@
+# Async, ids & logging
+
+## Overview
+Handy one-liners for async work, unique identifiers, and pleasant logging.
+
+## When to use
+- Pause code with `delay`/`sleep`, enforce a minimum loading time, or retry a flaky network call.
+- Generate unique keys for lists and data (`uuid`, `shortId`, `numericId`, `timestampId`).
+- Replace `console.log` with a colored, labeled `print`.
+
+## Import
+
+```javascript
+import { delay, withMinDelay, retry, uuid, shortId, print } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `delay` | `delay(ms)` | `Promise<void>` | Resolve after `ms` milliseconds. |
+| `sleep` | `sleep(ms)` | `Promise<void>` | Alias-style async sleep. |
+| `withMinDelay` | `withMinDelay(promise, minMs?)` | `Promise<T>` | Resolve only after both the promise and `minMs` complete. |
+| `retry` | `retry(fn, retries?, delayMs?)` | `Promise<T>` | Call `fn` again on rejection, up to `retries` times, waiting `delayMs` between attempts. |
+| `uuid` | `uuid()` | `string` | A version-4 style UUID. |
+| `shortId` | `shortId()` | `string` | A short unique id. |
+| `numericId` | `numericId(length?)` | `string` | A numeric id of `length` digits. |
+| `timestampId` | `timestampId()` | `string` | A time-based unique id. |
+| `print` | `print(message, type?, options?)` | `void` | Log with styling and [types](#the-print-signature). |
+
+### The `print` signature
+
+`print(message, type = "log", options = {})`
+
+- `type`: `"log" | "warn" | "error" | "info" | "success" | "debug"`.
+- `options`: `{ timestamp?: boolean, label?: string, prefix?: boolean }`.
+- Objects are pretty-printed as JSON.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { delay } from "flet-box";
+
+await delay(500); // wait half a second
+```
+
+### Full example
+
+```javascript
+import { withMinDelay, retry, uuid, print } from "flet-box";
+
+const data = await withMinDelay(fetchData(), 600);
+const saved = await retry(saveData, 3, 300);
+
+print("User created", "success", { timestamp: true });
+console.log(uuid()); // e.g. "f47ac10b..."
+```
+
+## Notes
+
+- `retry` re-runs the **whole** promise factory on each failure, so it is safe to retry lazy calls like `() => fetch(...)`.
+- `withMinDelay` is perfect for loading spinners: the UI stays visible for at least `minMs`.
+- `print` uses the correct console method per type and is safe to remove later without touching logic.
+
+## Related pages
+- [State, memo & refs](state.md) — previous chapter.
+- [Device & environment](device.md) — next chapter.
+- [HTTP client](../services/http.md) — network calls you may want to retry.
+
+---
+
+## Continue reading
+
+- **Previous:** [State, memo & refs](state.md)
+- **Next:** [Device & environment](device.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (5 of 12).

package/docs/tools/device.md

@@ -0,0 +1,132 @@
+# Device & environment
+
+## Overview
+Detect what your app is running on: screen, orientation, operating system, and clipboard access. These helpers read the browser and stay in sync when the window changes.
+
+## When to use
+- Layout that changes between phone and desktop (`device`, `dimensions`).
+- Show platform-specific UI (`os`).
+- Copy and paste text with one call (`clipboard`).
+- Walk the widget tree (`addNavigation`).
+
+## Import
+
+```javascript
+import { device, os, dimensions, width, height, clipboard } from "flet-box";
+```
+
+## Objects
+
+### `device`
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `isMobile()` | `boolean` | Is it a phone? |
+| `isTablet()` | `boolean` | Is it a tablet? |
+| `isDesktop()` | `boolean` | Is it a desktop/laptop? |
+| `orientation()` | `'portrait' \| 'landscape'` | Current orientation. |
+| `isTouch()` | `boolean` | Does the device support touch? |
+| `hasGesture()` | `boolean` | Gesture events available? |
+| `onOrientationChange(cb)` | `() => void` | Run `cb(orientation)` on change; returns an unsubscribe function. |
+| `onResize(cb)` | `() => void` | Run `cb({ width, height, orientation })` on resize; returns an unsubscribe function. |
+
+### `dimensions` (plus `width` / `height`)
+
+| Member | Returns | Description |
+| --- | --- | --- |
+| `width` / `height` | `number` | Live viewport dimensions. |
+| `get()` | `{ width, height }` | Both at once. |
+| `getWidth()` / `getHeight()` | `number` | Each dimension. |
+| `addListener(cb)` | `() => void` | Subscribe to size changes; returns an unsubscribe function. |
+| `removeListener(cb)` | `void` | Remove a subscription. |
+
+`width` and `height` are also exported directly as numbers.
+
+### `os`
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `name()` | `string` | Operating system: `"Windows"`, `"macOS"`, `"Android"`, `"iOS"`, `"Linux"`, `"ChromeOS"`, or `"Unknown"`. |
+| `version()` | `string` | OS version (or `"Unknown"`). |
+| `isMobile()` / `isDesktop()` | `boolean` | Platform family helpers. |
+
+### `clipboard`
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `copy(text)` | `void` | Copy text to the clipboard. |
+| `read()` | `Promise<string>` | Read the current clipboard text. |
+| `copyWithFeedback(text, element)` | `void` | Copy and briefly show feedback near an element. |
+
+### `addNavigation(widget)` — walk the widget tree
+
+`addNavigation(widget)` attaches tree-walking members to a widget and returns it:
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `parent` | `Widget \| null` | The parent widget (when mounted). |
+| `children` | `Widget[]` | Direct children. |
+| `firstChild` / `lastChild` | `Widget \| null` | First/last direct child. |
+| `siblings` | `Widget[]` | Siblings (excluding itself). |
+| `nextSibling` / `prevSibling` | `Widget \| null` | Adjacent siblings. |
+| `index` | `number` | Position among siblings (`-1` when root). |
+| `root` | `Widget` | The root of the tree. |
+| `path` | `object[]` | `{ name, id, index }` for each ancestor up to the root. |
+| `depth` | `number` | Distance from the root. |
+| `findById(id)` | `Widget \| null` | Search the subtree for a widget `id`. |
+| `findAll(widgetName)` | `Widget[]` | Collect all widgets with a `_widgetName`. |
+| `tree` | `string` | An ASCII tree dump for debugging. |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Text, device } from "flet-box";
+
+Text({
+  text: device.isMobile() ? "Mobile layout" : "Desktop layout",
+});
+```
+
+### Full example
+
+```javascript
+import { Column, Button, clipboard, dimensions } from "flet-box";
+
+Column({
+  gap: 8,
+  children: [
+    Button({
+      text: "Copy invite link",
+      onPress: () => clipboard.copy("https://myapp.app/invite"),
+    }),
+  ],
+});
+
+dimensions.addListener(({ width, height }) => {
+  console.log(`viewport ${width}x${height}`);
+});
+```
+
+## Notes
+
+- `dimensions` subscribes to window resize internally; `addListener` returns an **unsubscribe function** — call it when the feature is destroyed to avoid leaks. Same for `device.onResize`/`onOrientationChange`.
+- `clipboard.read()` requires a user gesture in most browsers (it uses the same rules as `navigator.clipboard`).
+- `addNavigation` is idempotent — calling it twice on a widget is safe, and widgets already expose these members when they are built by the factory.
+- `os` also detects mobile/desktop families, which `device` derives for touch+screen decisions.
+
+## Related pages
+- [Async, ids & logging](async-ids-log.md) — previous chapter.
+- [Themes](theme.md) — next chapter.
+- [AdaptiveScaffold](../widget/AdaptiveScaffold.md) — a shell that adapts to the device.
+
+---
+
+## Continue reading
+
+- **Previous:** [Async, ids & logging](async-ids-log.md)
+- **Next:** [Themes](theme.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (6 of 12).

package/docs/tools/introspection.md

@@ -0,0 +1,67 @@
+# Widget introspection
+
+## Overview
+Inspect any widget instance: read its received props, resolve one prop, or get a string dump. This is the engine behind the [Inspector](../widget/Inspector.md) widget.
+
+## When to use
+- Debug what props a widget actually received at runtime.
+- Build dev tools that show widget state.
+- Export or serialize widget configs.
+
+## Import
+
+```javascript
+import { getWidgetProps, getWidgetProp, stringifyWidgetProps } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `getWidgetProps` | `getWidgetProps(widget)` | `Record<string, any>` | The props the widget was built with. |
+| `getWidgetProp` | `getWidgetProp(widget, propName)` | `any` | One prop value. |
+| `stringifyWidgetProps` | `stringifyWidgetProps(widget)` | `string` | Props as a readable string. |
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { getWidgetProps } from "flet-box";
+
+const button = Button({ text: "Save", onPress: save });
+console.log(getWidgetProps(button));
+// { text: "Save", onPress: save }
+```
+
+### Full example
+
+```javascript
+import { Text, getWidgetProp, stringifyWidgetProps } from "flet-box";
+
+const label = Text({ text: "Hello", size: 24 });
+
+getWidgetProp(label, "size"); // 24
+console.log(stringifyWidgetProps(label));
+```
+
+## Notes
+
+- `getWidgetProps` returns what was passed at build time (before defaults are expanded).
+- These helpers are used by `printWidgetCode` and `inspectWidget` to reconstruct source-like descriptions of widgets.
+- Widgets expose an `update(props)` method and prop accessors; introspection is read-only and never mutates the widget.
+
+## Related pages
+- [Visual effects](visual-effects.md) — previous chapter.
+- [Input validation](validation.md) — next chapter.
+- [Inspector widget](../widget/Inspector.md).
+
+---
+
+## Continue reading
+
+- **Previous:** [Visual effects](visual-effects.md)
+- **Next:** [Input validation](validation.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (10 of 12).

package/docs/tools/lists.md

@@ -0,0 +1,96 @@
+# Lists, arrays & data
+
+## Overview
+Helpers for shaping collections and generating data: iterate lists into widgets, pick random values, create mock data, and treat dictionaries with a Python-like API.
+
+## When to use
+- Turn an array into widget rows (`mapList`, grid/carousel/lists heavily use these).
+- Sort, filter out duplicates, chunk, or shuffle arrays.
+- Build fake data for demos and prototypes (`createList`, `random`).
+
+## Import
+
+```javascript
+import { mapList, repeat, range, sort, unique, dict, createList } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `mapList` | `mapList(list, fn)` | `Widget[]` | Map a list (or a number, or a record) into widgets. `fn` receives `(item, index, key?)`. |
+| `repeat` | `repeat(count, widget \| fn)` | `Widget[]` | Repeat a widget, or build one per index via `fn(index)`. |
+| `range` | `range(start, end?, step?)` | `number[]` | A numeric sequence. |
+| `shuffle` | `shuffle(arr)` | `T[]` | A new array with shuffled order. |
+| `reverse` | `reverse(arr)` | `T[]` | A new array, reversed. |
+| `sort` | `sort(arr, by?, order?)` | `T[]` | Sort by a string key or a comparator; `order` is `'asc'`/`'desc'`. |
+| `unique` | `unique(arr, key?)` | `T[]` | Remove duplicates; optionally by a `key` field. |
+| `chunk` | `chunk(arr, size)` | `T[][]` | Split into arrays of `size`. |
+| `createList` | `createList(schema, count?)` | `T[]` | Generate mock data from a schema. |
+| `createList.fromData` | `(data, mapper)` | `R[]` | Map real data through a schema mapper. |
+| `createList.range` | `(start, end, mapper?)` | `any[]` | Range with optional mapper. |
+| `createList.repeat` | `(value, count)` | `T[]` | Repeat a value. |
+| `createList.paginate` | `(list, page?, pageSize?)` | object | `{ data, page, pageSize, total, totalPages, hasNext, hasPrev, startIndex, endIndex }`. |
+| `createList.search` | `(list, query, fields?)` | `T[]` | Filter by a string (or predicate) across fields. |
+| `createList.sort` | `(list, field, order?)` | `T[]` | Sort by a field. |
+| `createList.groupBy` | `(list, field)` | `Record<string, T[]>` | Group by a field. |
+| `dict` | `dict(obj?)` | any | A Python-like dictionary with chainable methods. |
+| `emptyDict` | `emptyDict()` | any | A new empty dictionary. |
+| `fromJSON` | `fromJSON(jsonStr)` | any | Parse JSON into a dict/value. |
+| `fromEntries` | `fromEntries(entries)` | any | Build from `[key, value]` pairs. |
+| `random` | see below | — | Random numbers, ids, colors, and fake data. |
+
+### The `random` object
+
+`random.number(min?, max?)`, `random.string(length?)`, `random.firstName()`, `random.lastName()`, `random.fullName()`, `random.email(name?)`, `random.age()`, `random.boolean()`, `random.choice(arr)`, `random.id()`, `random.hexColor()`, `random.rgbColor()`, `random.date(start?, end?)`, `random.dateString(start?, end?)`, `random.time()`, `random.timeAmPm()`, `random.datetime()`, `random.timestamp()`, `random.dayOfWeek()`, `random.month()`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Column, Text, mapList, repeat } from "flet-box";
+
+Column({
+  children: repeat(3, Text({ text: "hello" })),
+});
+```
+
+### Full example
+
+```javascript
+import { Column, Text, createList, sort } from "flet-box";
+
+const people = createList(
+  { name: "firstName", age: "age" },
+  5,
+);
+
+Column({
+  children: sort(people, "age", "asc").map((p) =>
+    Text({ text: `${p.name} (${p.age})` }),
+  ),
+});
+```
+
+## Notes
+
+- `mapList` accepts a **number** (renders that many items), an **array**, or a **record** of items — so it works with `for`-style and object-style data alike.
+- The collection helpers (`sort`, `shuffle`, `unique`, `chunk`, `reverse`) return **new arrays**: your original array is never mutated.
+- `createList` takes a schema of fields: a string is a generator name (`"firstName"`, `"age"`, `"email"`) and a function is called to produce the value.
+- `dict` is an object with Python-dict methods (chainable); `fromEntries` builds it from pairs.
+
+## Related pages
+- [Text & time](text-and-time.md) — next chapter.
+- [Styling helpers](styling.md) — previous chapter.
+- [Widget introspection](introspection.md) — inspect widget props.
+
+---
+
+## Continue reading
+
+- **Previous:** [Styling helpers](styling.md)
+- **Next:** [Text & time](text-and-time.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (2 of 12).

package/docs/tools/markdown.md

@@ -0,0 +1,79 @@
+# Markdown, code & HTML
+
+## Overview
+Render markdown as HTML or as real FletBox widgets, highlight code, and escape untrusted text. These helpers power the [Markdown](../widget/Markdown.md) and [CodeViewer](../widget/CodeViewer.md) widgets.
+
+## When to use
+- Show user-written or file-provided markdown in your app.
+- Render highlighted code snippets.
+- Sanitize text before inserting it into the DOM (`escapeHtml`).
+
+## Import
+
+```javascript
+import { parseMarkdown, markdownToWidgets, escapeHtml } from "flet-box";
+```
+
+## Functions
+
+| Function | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `markdownToWidgets` | `markdownToWidgets(text, options?)` | `Widget[]` | Markdown → FletBox widgets. This is the real renderer. |
+| `parseMarkdownToWidgets` | `parseMarkdownToWidgets(text, options?)` | `Widget[]` | Alias of `markdownToWidgets`. |
+| `parseInlineToWidgets` | `parseInlineToWidgets(text)` | `Widget[]` | Inline markdown (bold, links, code) → FletBox widgets. |
+| `parseMarkdown` | `parseMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `markdownToWidgets`. |
+| `parseInlineMarkdown` | `parseInlineMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `parseInlineToWidgets`. |
+| `tokenize` | `tokenize(code)` | `{ type, value }[]` | Split code into token objects. |
+| `generateHighlightedHtml` | `generateHighlightedHtml(code)` | `string` | Code → highlighted HTML. |
+| `escapeHtml` | `escapeHtml(text)` | `string` | Escape `<`, `>`, `&`, quotes so text is safe as HTML. |
+| `highlightColors` | const | `Record<string, string>` | The token color map used by the highlighter. |
+
+`markdownToWidgets` options: `{ codeMaxHeight?: number, codeFontSize?: number }`.
+
+## Examples
+
+### Everyday example
+
+```javascript
+import { Column, markdownToWidgets } from "flet-box";
+
+Column({
+  padding: 16,
+  children: markdownToWidgets("# Hello\n\n**bold** and a [link](https://example.com)"),
+});
+```
+
+### Full example
+
+```javascript
+import { Column, parseInlineToWidgets, generateHighlightedHtml, escapeHtml } from "flet-box";
+
+const note = Column({
+  children: parseInlineToWidgets("Read the **docs** today"),
+});
+
+const code = generateHighlightedHtml("const x = 1;");
+const safe = escapeHtml(userInput); // safe to put into innerHTML
+```
+
+## Notes
+
+- `markdownToWidgets` builds real widget elements (headings, paragraphs, code blocks, lists) that you can place inside any container — this is what the `Markdown` widget uses.
+- `parseMarkdown` and `parseInlineMarkdown` are reserved placeholders that currently pass text through unchanged; the widget rendering is `markdownToWidgets`/`parseInlineToWidgets`.
+- `escapeHtml` should be used for **any** text you insert into the DOM that you did not write yourself. Never trust raw input.
+- `tokenize` returns flat token objects and is the base for custom highlighters; `highlightColors` lets you theme them.
+
+## Related pages
+- [Themes](theme.md) — previous chapter.
+- [Visual effects](visual-effects.md) — next chapter.
+- [Markdown widget](../widget/Markdown.md) and [CodeViewer widget](../widget/CodeViewer.md).
+
+---
+
+## Continue reading
+
+- **Previous:** [Themes](theme.md)
+- **Next:** [Visual effects](visual-effects.md)
+- **Index:** [Tools index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 10 · Tools & Utilities** (8 of 12).