flet-box 1.1.0 → 1.1.1

package/docs/tools/device.md

@@ -1,18 +1,26 @@
 # 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.
+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. The same page carries the two halves a responsive screen needs — the **breakpoint** vocabulary (`BREAKPOINTS`, `currentBreakpoint`, `atLeast`, `pick`, `onBreakpointChange`), which says *which layout this viewport wants*, and `loadFont`, which makes a `fontFamily` prop real.
 
 ## When to use
 - Layout that changes between phone and desktop (`device`, `dimensions`).
+- One value per viewport (`pick({ xs: 8, md: 16 })`), or a decision that has to agree with `AdaptiveScaffold` (`atLeast("md")`).
+- Rebuild a screen when the viewport *crosses a step*, not when it moves a pixel (`onBreakpointChange`).
 - Show platform-specific UI (`os`).
 - Copy and paste text with one call (`clipboard`).
 - Walk the widget tree (`addNavigation`).
+- Load a webfont before you name it in `fontFamily` (`loadFont`, `fontsReady`).
 
 ## Import
 
 ```javascript
-import { device, os, dimensions, width, height, clipboard } from "flet-box";
+import {
+  device, os, dimensions, width, height, clipboard,
+  BREAKPOINTS, BREAKPOINT_NAMES, breakpointForWidth,
+  currentBreakpoint, atLeast, pick, onBreakpointChange,
+  loadFont, fontsReady,
+} from "flet-box";
 ```
 
 ## Objects
@@ -42,6 +50,67 @@ import { device, os, dimensions, width, height, clipboard } from "flet-box";
 
 `width` and `height` are also exported directly as numbers.
 
+### Breakpoints
+
+`dimensions` answers "how wide is the window"; a screen almost always wants the
+next question, "which layout does that width ask for". One table answers it, and
+`md` is 768 — the same line `AdaptiveScaffold` draws between a drawer and a
+permanent sidebar, so a screen and its shell cannot disagree.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `BREAKPOINTS` | `{ xs, sm, md, lg, xl }` | The widths in **CSS pixels** (0 · 560 · 768 · 1024 · 1280). A viewport is not a framework unit: it does not scale with the reader's font, and pretending otherwise puts a phone layout on a desktop. |
+| `BREAKPOINT_NAMES` | `['xs' … 'xl']` | The same names in width order. |
+| `currentBreakpoint()` | `() => Breakpoint` | The step the live window is in. `"xs"` where there is no window, so a Node import never throws. |
+| `breakpointForWidth(px)` | `(px: number) => Breakpoint` | The pure read behind it — a test, or a width that is not the viewport (an embed's container). |
+| `atLeast(name)` | `(name: Breakpoint) => boolean` | `atLeast("md")` is the sentence a two-column layout needs. |
+| `pick(values, fallback?)` | `(Record<Breakpoint, T>, T) => T` | A value per step. An unnamed step inherits the nearest smaller one: `pick({ xs: 8, md: 16 })` reads 8, 8, 16, 16, 16. |
+| `onBreakpointChange(listener)` | `(cb) => () => void` | Fires when the *name* changes, not on every pixel of a resize. Returns the unsubscribe; hand it to the widget's `onUnmount` so the subscription dies with the screen. |
+
+```javascript
+// One screen, two shapes, no second codebase.
+const gutter = pick({ xs: 16, md: 24, lg: 32 });
+
+const items = atLeast("md")
+  ? [listPane, detailPane]
+  : [currentPane];
+
+const [name, setName] = useState("bp", currentBreakpoint());
+const header = Column({ padding: gutter, children: [Text({ text: name })] });
+header.onUnmount(onBreakpointChange(setName));
+```
+
+A breakpoint is a *decision*, not a device. `device.isMobile()` reads a user
+agent, which a desktop in a narrow window cannot change and a tablet on desktop
+mode will not admit; `currentBreakpoint()` reads the width the app actually has.
+Use the width for layout and the UA only for a genuinely platform question (touch
+long-press, a native back gesture).
+
+### Fonts
+
+`fontFamily` is a name. If the bytes of that face are not on the machine, the
+browser paints its fallback and the app ships a typeface nobody chose.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `loadFont(family, options?)` | `(string, { weights?, url?, display? }) => Promise<boolean>` | Ask for a family. `weights` is required for a Google family if you want anything but 400 — a heading needs its weight asked for by name. `url` loads your own stylesheet instead of a provider's, which is the same-origin answer an offline launch keeps. Resolves `false` when the face could not be had; the screen keeps its fallback instead of failing. |
+| `fontsReady()` | `() => Promise<boolean>` | Wait for the faces already started. Use it before a canvas paint or an export, where text that reflows *after* the drawing is a visible bug. |
+
+```javascript
+import { Text, loadFont } from "flet-box";
+
+const body = Text({ text: "Reading", fontFamily: "Georgia, serif" });
+
+// One request per family, whoever asks first.
+loadFont("Inter", { weights: [400, 600] }).then((ok) => {
+  if (ok) body.style.fontFamily = "Inter, Georgia, serif";
+});
+```
+
+> A webfont is a network request. A self-hosted `@font-face` in the app's own CSS
+> is free of that and is the right answer for a product; a provider URL is fine
+> for a demo and is what a tunnel, a firewall or an offline launch breaks on.
+
 ### `os`
 
 | Method | Returns | Description |
@@ -111,7 +180,10 @@ dimensions.addListener(({ width, 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`.
+- `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` and `onBreakpointChange`.
+- `onBreakpointChange` keeps **one** window listener for the whole app and fires only when the step name changes. Subscribing per card would still be one listener, but each callback would run on every pixel — a `Row` that re-renders on a pixel can change the scrollbar and resize the window again.
+- `BREAKPOINTS` are pixels by design. Everything else about a FletBox screen is a framework unit that grows with the reader's font; the viewport is the browser's own number and the layout switch has to be in the same currency as the window.
+- `loadFont` is idempotent per family and never rejects: a blocked request resolves `false`, and the app keeps its fallback. It writes a `<link>` into `document.head`, so a page with a strict CSP needs that host allowed — a self-hosted `url` avoids the question entirely.
 - `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.

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

@@ -1,17 +1,32 @@
 # Text & time
 
 ## Overview
-Small pure helpers for strings, dates, and media time. They take a value and return a formatted one — no side effects.
+Small pure helpers for strings, dates, waiting and repeating. They take a value
+and return a formatted one — no side effects, except the four that hand back a
+timer id or a promise.
 
 ## When to use
 - Normalize user names or titles before display (`capitalize`, `truncate`).
-- Show friendly dates and "2 minutes ago" labels.
+- Show friendly dates, weekday names and "2 minutes ago" labels.
+- Step a date by a calendar day, or measure the gap between two.
+- Wait for a condition or an element without writing the poll loop twice.
 - Format audio/video positions in player UIs.
 
 ## Import
 
 ```javascript
-import { capitalize, truncate, formatDate, relativeTime } from "flet-box";
+import {
+  capitalize,
+  truncate,
+  formatDate,
+  formatDateLong,
+  addDays,
+  dateDiff,
+  relativeTime,
+  seconds,
+  sleep,
+  everySecond,
+} from "flet-box";
 ```
 
 ## Functions
@@ -20,6 +35,12 @@ import { capitalize, truncate, formatDate, relativeTime } from "flet-box";
 
 | Function | Signature | Returns | Description |
 | --- | --- | --- | --- |
+| `startsWith` | `startsWith(str, prefix)` | `boolean` | Whether `str` begins with `prefix`. |
+| `endsWith` | `endsWith(str, suffix)` | `boolean` | Whether `str` ends with `suffix`. |
+| `includes` | `includes(str, substr)` | `boolean` | Whether `str` contains `substr`. |
+| `split` | `split(str, separator)` | `string[]` | Text into parts. |
+| `join` | `join(arr, separator?)` | `string` | Parts back into text. |
+| `trim` | `trim(str)` | `string` | Leading and trailing whitespace removed. |
 | `capitalize` | `capitalize(str)` | `string` | First letter uppercase. |
 | `capitalizeWords` | `capitalizeWords(str)` | `string` | First letter of every word uppercase. |
 | `lowerCase` | `lowerCase(str)` | `string` | All lowercase. |
@@ -27,13 +48,66 @@ import { capitalize, truncate, formatDate, relativeTime } from "flet-box";
 | `reverseString` | `reverseString(str)` | `string` | Reversed text. |
 | `truncate` | `truncate(str, length?, suffix?)` | `string` | Cut to `length` characters and append `suffix` (default `"..."`). |
 
+### Units
+
+Every one of these takes a count and returns **milliseconds**, so it reads as a
+sentence at the call site: `waitFor(seconds(30))`, `now() - days(2)`.
+
+| Function | Signature | Returns |
+| --- | --- | --- |
+| `seconds` | `seconds(n)` | `n * 1000` |
+| `minutes` | `minutes(n)` | `n * 60 * 1000` |
+| `hours` | `hours(n)` | `n * 60 * 60 * 1000` |
+| `days` | `days(n)` | `n * 24 * 60 * 60 * 1000` |
+| `weeks` | `weeks(n)` | `7 * days(n)` |
+| `months` | `months(n)` | `30 * days(n)` — an approximation, on purpose |
+| `years` | `years(n)` | `365 * days(n)` — an approximation, on purpose |
+
+`months()` and `years()` are calendar lies told for arithmetic: use them for a
+cache window or a retry backoff, never for an age or a birthday.
+
 ### 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. |
+| `today` | `today()` | `string` | This day as `"YYYY-MM-DD"`. |
+| `yesterday` | `yesterday()` | `string` | Yesterday as `"YYYY-MM-DD"`. |
+| `tomorrow` | `tomorrow()` | `string` | Tomorrow as `"YYYY-MM-DD"`. |
+| `dayOfWeek` | `dayOfWeek(date)` | `string` | Full weekday name, e.g. `"Monday"`. |
+| `monthName` | `monthName(date)` | `string` | Full month name, e.g. `"January"`. |
+| `isToday` | `isToday(date)` | `boolean` | Same calendar day as now. |
+| `isYesterday` | `isYesterday(date)` | `boolean` | The day before now. |
+| `isTomorrow` | `isTomorrow(date)` | `boolean` | The day after now. |
+| `isWeekend` | `isWeekend(date)` | `boolean` | Saturday or Sunday. |
+| `isLeapYear` | `isLeapYear(year)` | `boolean` | Whether a four-digit year has a February 29. |
+| `formatDate` | `formatDate(date, format?)` | `string` | Tokens `YYYY MM DD HH mm ss`; anything else passes through. |
+| `formatDateLong` | `formatDateLong(date, locale?)` | `string` | `"Monday, January 15, 2024"`. |
+| `formatDateShort` | `formatDateShort(date, locale?)` | `string` | `"Jan 15, 2024"`. |
+| `formatTime` | `formatTime(date)` | `string` | 24-hour `"14:05:30"`. |
+| `formatTimeAmPm` | `formatTimeAmPm(date)` | `string` | 12-hour `"02:05:30 PM"`. |
+| `parseDate` | `parseDate(str, format?)` | `Date` | Reads `"15/01/2024"` with `"DD/MM/YYYY"`. |
+| `dateDiff` | `dateDiff(a, b, unit?)` | `number` | Absolute difference; `unit` is one of the names above. |
+| `addDays` | `addDays(date, n)` | `Date` | `n` calendar days along (negative goes back). |
+| `addHours` / `addMinutes` / `addSeconds` | `addHours(date, n)` | `Date` | Elapsed time, not calendar time. |
+| `subtractDays` / `subtractHours` / `subtractMinutes` / `subtractSeconds` | `subtractDays(date, n)` | `Date` | The same steps backwards. |
+| `timeAgo` | `timeAgo(date)` | `string` | `"5 minutes ago"`, `"just now"` under a second. |
+| `relativeTime` | `relativeTime(date)` | `string` | Alias of `timeAgo`. |
+| `timeAgoLocale` | `timeAgoLocale(date, locale?)` | `string` | The same label in `"en"` or `"es"` — `"hace 1 hora"`. |
+| `waitFor` | `waitFor(ms)` | `Promise<void>` | Resolves after `ms`. |
+| `wait` / `sleep` | `sleep(ms)` | `Promise<void>` | Aliases of `waitFor`. |
+| `waitUntil` | `waitUntil(condition, timeout?, interval?)` | `Promise<true>` | Polls `condition`; **throws** at the timeout (default 30s, 1s apart). |
+| `waitForElement` | `waitForElement(selector, timeout?, interval?)` | `Promise<Element>` | Polls the DOM; needs a document, so call it from a screen (default 10s, 0.5s apart). |
+| `timer` | `timer(label)` | `{ stop, elapsed }` | `stop()` logs and returns the milliseconds; `elapsed()` reads without logging. |
+| `every` | `every(ms, callback)` | `number` | `setInterval` with the duration first. Release the id it returns. |
+| `everySecond` / `everyMinute` / `everyHour` / `everyDay` | `everySecond(callback)` | `number` | The same, at a named period. |
+
+`date` is a `Date`, a timestamp, or a string. A bare `"YYYY-MM-DD"` is read as a
+**calendar day in the reader's own zone**, so `isToday(today())` is true on every
+machine; a string with an offset or a `Z` is read as an instant, and a formatter
+then prints it in local time. `addDays` counts days on the calendar, which is why
+it survives a DST night, while `addHours` counts real elapsed time — the right
+choice for a countdown and the wrong one for "this time next week".
 
 ### Media time
 
@@ -58,6 +132,40 @@ Text({
 // "Hello Fletbox — 2 minutes ago"
 ```
 
+### A due date, read as a day
+
+```javascript
+import { addDays, dateDiff, dayOfWeek, formatDate, isWeekend, timeAgoLocale } from "flet-box";
+
+const due = addDays(new Date(), 7);
+const label = `${dayOfWeek(due)}, ${formatDate(due, "DD MMM")} · in ${dateDiff(new Date(), due, "days")} days`;
+const note = isWeekend(due) ? " (it lands on a weekend)" : "";
+
+Text({ text: label + note });
+Text({ text: timeAgoLocale(Date.now() - seconds(90), "es") }); // "hace 1 minuto"
+```
+
+### Waiting, and releasing what repeats
+
+```javascript
+import { Column, Text, everySecond, formatTime, now, seconds, useState, waitUntil } from "flet-box";
+
+export const ClockScreen = () => {
+  const [clock, setClock] = useState("clock", formatTime(now()));
+  const root = Column({ children: [Text({ text: clock })] });
+
+  const tick = everySecond(() => setClock(formatTime(now())));
+  // R6: a repeating helper hands back an id, and the screen releases it.
+  root.onUnmount(() => clearInterval(tick));
+
+  waitUntil(() => navigator.onLine, seconds(30), seconds(1))
+    .then(() => setClock("back online"))
+    .catch(() => setClock("still offline")); // waitUntil throws at its timeout
+
+  return root;
+};
+```
+
 ### Full example
 
 ```javascript
@@ -69,7 +177,9 @@ 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.
+- `formatDate(date, format?)` accepts a `Date`, a timestamp, or a date string. The tokens it reads are `YYYY MM DD HH mm ss`; it has no `ddd`, so build a weekday name with `dayOfWeek()`.
+- `waitUntil()` and `waitForElement()` **throw** on their timeout — await them inside a `try`, or attach a `.catch`.
+- `every()`, `everySecond()` and friends return a `setInterval` id. Per the working contract, whatever a screen registers it also releases in `onUnmount`.
 - 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.
 

package/docs/widget/Accordion.md

@@ -130,6 +130,8 @@ const faq = Accordion({
 
 - onToggle receives the new expanded boolean whenever the header is activated.
 - disabled blocks toggling, and animate: false skips the open/close transition.
+- A shut panel still shows its edge: the header keeps the divider and the
+- 'contained' variant paints the raised plate, so it never reads as plain text.
 
 ## Related widgets
 

package/docs/widget/AnimatedBox.md

@@ -9,9 +9,9 @@ Use it to animate a widget's position, transform, color, or size without hand-wr
 ## Quick start
 
 ```javascript
-import { AnimatedBox, Text, pulse } from "flet-box";
+import { AnimatedBox, Text } from "flet-box";
 
-const pulse = AnimatedBox({
+const badge = AnimatedBox({
   child: Text({ text: "Hello" }),
   animations: [{ effect: "scale", from: 1, to: 1.2 }],
 });
@@ -23,10 +23,10 @@ const pulse = AnimatedBox({
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `animations` | `AnimationStep[]` | Animations to apply, as a name or an array of names. |
+| `animations` | `AnimationStep[]` | The steps to play, each `{ effect, from, to }` plus its own `duration`, `delay`, `loop` and `reverse`. |
 | `child` | `Widget` | A single child widget. Alias: `children` for a list. |
-| `timing` | `string` | Timing function for the animation. |
-| `delay` | `string` | Delay before the animation starts, in milliseconds. |
+| `timing` | `string` | Timing function for the animation, passed straight to CSS. |
+| `delay` | `number \| string` | Default delay for the steps that do not name one: milliseconds as a number, or a CSS time as a string (`"0.2s"`). |
 | `fillMode` | `string` | How styles persist before and after the animation (CSS `fill-mode`). |
 | `top` | `number \| string` | The `top` value for the widget. |
 | `right` | `number \| string` | The `right` value for the widget. |
@@ -87,9 +87,14 @@ import { AnimatedBox, Text } from "flet-box";
 
 const toast = AnimatedBox({
   child: Text({ text: "Saved" }),
-  animations: [{ effect: "opacity", from: 0, to: 1 }],
-  timing: "ease-in-out",
-  delay: "200ms",
+  // Each step keeps its own clock: the fade is over while the lift is still moving.
+  animations: [
+    { effect: "opacity", from: 0, to: 1, duration: 200 },
+    { effect: "translateY", from: 16, to: 0, duration: 400, delay: 120 },
+    { effect: "backgroundColor", from: "#fef3c7", to: "#ffffff", duration: 600 },
+  ],
+  timing: "ease-out",
+  delay: 200,
   fillMode: "forwards",
   top: 16,
   right: 16,
@@ -98,24 +103,45 @@ const toast = AnimatedBox({
 
 ## Tips
 
-- Each animation is { effect, from, to } where effect is a CSS property like opacity,
-- scale, translateY, or backgroundColor. It runs once and holds `to` at the end.
-- Set timing (ease, ease-out, linear) and delay at the widget level; add reverse: true
-- to cycle back to `from`, together with loop: true for a breathing pulse.
-- top, right, bottom, and left are forwarded to the child as positioning hints for
-- layout systems.
+- A step is `{ effect, from, to }`, where the effect is one of `scale`, `scaleX`,
+  `scaleY`, `rotate`, `rotateX`, `rotateY`, `rotateZ`, `skewX`, `skewY`, `translateX`,
+  `translateY`, `translateZ`, `opacity`, `color`, `backgroundColor`, `borderColor`,
+  `borderWidth`, `borderRadius`, `width`, `height`, `boxShadow`, `background` or
+  `textGradient` (the margin and padding steps work as well). A name outside that list
+  does nothing, silently.
+- Each step's `duration`, `delay` and `loop` are read off **that step**:
+  a 600 ms `scale` and a 400 ms `opacity` in one entrance run together for 600 ms,
+  with the fade holding from 400 ms on. Times are milliseconds as a number
+  (`duration: 400`) or a CSS time as a string (`delay: "0.4s"`); a bare number as a
+  `delay` used to make the whole `animation` shorthand invalid, which read as the
+  widget not animating at all.
+- `reverse: true` makes a step swing back to `from` instead of holding `to`; with
+  `loop: true` it breathes.
+- A looping step and a one-shot step cannot share one `@keyframes` rule — repeating
+  the rule repeats the entrance — so they are generated as two rules. Two rules
+  cannot compose one `transform`, so keep every transform step in one group: mixing
+  a looping `rotate` with a one-shot `translateY` moves only one of them, and the
+  widget warns about it.
+- A length is a framework unit, not a pixel: `translateY: 20` is `20 / base-font-size`
+  rem, so the movement grows with the reader's font like the rest of the UI.
+- `top`, `right`, `bottom` and `left` are forwarded to the child's dataset as
+  positioning hints for layout systems.
 
 ## Accessibility
 
-- Honor prefers-reduced-motion by keeping animations subtle or giving users a way to
-- disable them.
+- Nothing to do here: the engine reads `prefers-reduced-motion` and the
+  [motion mode](../tools/animation.md#reduced-motion), and a looping or entering
+  step collapses to one frame that lands on its `to` values, so content is never
+  held invisible behind an animation the reader refused.
 
 ## Behavior
 
-- The first animation step is applied as an inline style immediately, so there is no
-- flash of the final state before the keyframes run.
-- Generated @keyframes are injected once per sequence and reused, so repeated
-- animations stay cheap.
+- Every step's `from` is written on the element before its rule starts, including
+  the ones that begin later — so there is no flash of the final state before the
+  keyframes run, and no flash of the *first* step's end while a delayed step waits.
+- Generated `@keyframes` are named by their content and injected once, so a sequence
+  repeated — or one word staggered across `AnimatedText` letters — reuses one rule
+  instead of adding a `<style>` per call.
 
 ## Related widgets
 

package/docs/widget/AnimatedText.md

@@ -24,9 +24,9 @@ const title = AnimatedText({
 | Prop | Type | Description |
 | --- | --- | --- |
 | `child` | `Widget` | A single child widget. Alias: `children` for a list. |
-| `animations` | `AnimationStep[]` | Animations to apply, as a name or an array of names. |
+| `animations` | `AnimationStep[]` | The steps to play, each `{ effect, from, to }` plus its own `duration`, `delay`, `loop` and `reverse`. |
 | `sameTime` | `boolean` | Runs child animations at the same time. |
-| `delayBetween` | `number` | Stagger delay between each child animation. |
+| `delayBetween` | `number` | Stagger between each child animation, in seconds (`0.05` is 50 ms). |
 | `orientation` | `'row' \| 'column'` | Orientation of the widget or control. |
 
 ### Common props
@@ -92,11 +92,17 @@ const title = AnimatedText({
 
 ## Tips
 
-- child must be a Text widget, because its text is split into single-character
-- widgets that inherit the original props.
-- Set sameTime: false and control delayBetween to create a wave; use sameTime: true
-- for a synchronized pop.
-- orientation: "column" stacks the letters vertically for vertical-word effects.
+- `child` must be a Text widget, because its text is split into single-character
+  widgets that inherit the original props.
+- Set `sameTime: false` and control `delayBetween` to create a wave; use
+  `sameTime: true` for a synchronized pop. `delayBetween` is in **seconds** —
+  `0.05` staggers the letters 50 ms apart, while `5` is a five-second wait per
+  character.
+- The letters share one generated `@keyframes` rule and each carries its own delay,
+  so a staggered headline costs one rule, not one per character.
+- `orientation: "column"` stacks the letters vertically for vertical-word effects.
+- Each step is [AnimatedBox's](AnimatedBox.md) step, so a per-letter `duration`
+  belongs to the step, not to the widget.
 
 ## Accessibility
 

package/docs/widget/Badge.md

@@ -114,6 +114,7 @@ const inbox = Badge({
 
 - showZero: false hides the marker entirely when value is 0.
 - A borderWidth with a matching borderColor creates a clean cutout against the child.
+- The wrapper is the child's box: it shrinks to the child and refuses a flex parent's cross-axis stretch, so every `position` anchors on a corner of the child and not on the edge of the row it happens to sit in.
 
 ## Related widgets
 

package/docs/widget/COMMON_PROPS.md

@@ -47,6 +47,7 @@ natural. Each group below maps to the same underlying style or behavior:
 | `flexDirection` | `direction` | CSS `flex-direction` |
 | `justifyContent` | `justify` | CSS `justify-content` |
 | `alignItems` | `align` | CSS `align-items` |
+| `alignSelf` | `selfAlign` | CSS `align-self` (one child's own answer to `alignItems`) |
 | `flexWrap` | `wrap` | CSS `flex-wrap` |
 | `lineHeight` | `lineH` | CSS `line-height` |
 | `letterSpacing` | `letterSpace` | CSS `letter-spacing` |
@@ -70,9 +71,31 @@ These expand to two sides at once (numeric values are pixels):
 ## Layout and display
 
 `display`, `flexDirection` (`direction`), `justifyContent` (`justify`),
-`alignItems` (`align`), `flexWrap` (`wrap`), `flex`, `flexGrow`, `flexShrink`,
-`flexBasis`, `gap`, `boxSizing`, `overflow`, `overflowX`, `overflowY`,
-`position` (`pos`), `top`, `right`, `bottom`, `left`, `inset`, `zIndex` (`z`).
+`alignItems` (`align`), `alignSelf` (`selfAlign`), `flexWrap` (`wrap`), `flex`,
+`flexGrow`, `flexShrink`, `flexBasis`, `gap`, `boxSizing`, `overflow`,
+`overflowX`, `overflowY`, `position` (`pos`), `top`, `right`, `bottom`, `left`,
+`inset`, `zIndex` (`z`).
+
+### One child, its own alignment
+
+`alignItems` is the parent's answer for every child; `alignSelf` is one child's
+answer for itself. The values are CSS's: `'auto'` (inherit the parent),
+`'flex-start'`, `'center'`, `'flex-end'`, `'baseline'`, `'stretch'`. It goes on
+the child, on any widget — `alignSelf` is a `CommonProps` entry, not a layout
+prop — and it is what keeps a short label from being stretched to the full height
+of a row of inputs:
+
+```js
+Row({
+  alignItems: 'stretch',
+  gap: 8,
+  children: [
+    Input({ label: 'Coupon', value: '', onChange: () => {} }),
+    // The row stretches its children; this one refuses.
+    Button({ text: 'Apply', onPress: () => {}, alignSelf: 'flex-end' }),
+  ],
+});
+```
 
 ### Stack positioning
 

package/docs/widget/Chart.md

@@ -136,6 +136,7 @@ const trend = Chart({
 ## Behavior
 
 - The canvas redraws when data, labels, type or styling props change.
+- Grid lines and their labels sit on one round step (1, 2 or 5 times a power of ten), so the numbers agree with the lines they name.
 - Candle charts read open, high, low and close in that order from each data object.
 
 ## Related widgets

package/docs/widget/Checkbox.md

@@ -28,6 +28,7 @@ const terms = Checkbox({
 | `size` | `number` | Overall size preset or pixel value, depending on the widget. |
 | `activeColor` | `Color` | Color used in the active state. |
 | `label` | `string` | Label or caption shown near the control. |
+| `variant` | `'outlined' \| 'filled'` | How the checked state reads: `outlined` keeps the box hollow with the tick in `activeColor`, `filled` turns the box into an `activeColor` plate and takes the tick to whichever ink reads on it. |
 
 ### Common props
 
@@ -80,10 +81,11 @@ const remember = Checkbox({
 import { Checkbox } from "flet-box";
 
 const updates = Checkbox({
-  checked: false,
+  checked: true,
   label: "Email me product updates",
   size: 24,
   activeColor: "#7c3aed",
+  variant: "filled",
   disabled: false,
   onCheck: (checked) => {
     console.log("updates:", checked);
@@ -95,6 +97,7 @@ const updates = Checkbox({
 
 - Use Checkbox inside forms where several options may be true together; use Switch for one immediate on/off setting.
 - onCheck fires with the new boolean, so write it straight into your state.
+- A filled checkbox needs no second color: `activeColor` is the plate and the tick reads itself on it.
 
 ## Accessibility
 
@@ -104,6 +107,9 @@ const updates = Checkbox({
 
 - Uncontrolled when checked is omitted; the widget tracks its own state and reports changes through onCheck.
 - The returned element exposes setChecked(value) and getChecked() for programmatic control.
+- `size` is the edge of the drawn box; the press target around it stays 40 units and does not shrink with it.
+- The box carries a step of the radius scale (4 by default, 8 from `size: 28`), and a `borderRadius` rounds the box rather than the invisible target around it.
+- `variant: 'filled'` changes the checked state only: the box becomes an `activeColor` plate and the tick takes whichever ink reads on it. An unchecked box keeps its rim, because a filled box that means off is a button.
 
 ## Related widgets
 

package/docs/widget/CircularChart.md

@@ -148,6 +148,8 @@ const chart = CircularChart({
 ## Behavior
 
 - centerContent accepts a string or a widget rendered in the donut hole.
+- The hole is the page showing through, not a filled disc, so a donut reads
+- as a ring on any surface.
 - onHover receives (slice | null, index) as the pointer moves between slices, and
 - onComplete fires when the entry sweep finishes.
 

package/docs/widget/Drawer.md

@@ -116,6 +116,7 @@ openDrawer();
 - The drawer keeps itself sized to the viewport on resize (`dimensions.addListener`), and `destroy()` removes that listener and the `keydown` handler.
 - When you pass `drawer` to a [Scaffold](Scaffold.md), a `menu` icon in the [AppBar](AppBar.md) opens it, `closeDrawerOnNavigate` can close it on route change, and the shell tears it down with its `_cleanup`.
 - Keydown (`Escape`) and resize listeners are only active while the drawer exists or is open — no leaks on the normal lifecycle.
+- The panel paints the screen edge to edge and pads its content by `env(safe-area-inset-*)`, so on a notched phone the `header` clears the status bar and the `footer` clears the home indicator without the background leaving a gap. Nothing has to be configured, and the `width`/`height` of the panel stay what you passed: the padding is inside the box (`border-box`). On a device with no inset the values are `0`, so the drawer looks exactly as it did.
 
 ## Related widgets
 - [DrawerItem](DrawerItem.md)

package/docs/widget/GridView.md

@@ -41,6 +41,7 @@ const grid = GridView({
 | `columns` | `number` | Number of grid columns. |
 | `spacing` | `number` | Space between grid items. |
 | `itemHeight` | `number` | Height of each grid cell. |
+| `children` | `Widget[] \| Widget` | The cells themselves, laid out `columns` per row. The same contract as `data` + `renderItem` read the other way round: pass built widgets here, or the items plus a builder. `data` wins when both are given. |
 
 ### Common props
 
@@ -115,7 +116,7 @@ const grid = GridView({
 
 - `columns` sets the number of columns and `spacing` sets the gap between cells.
 - `itemHeight` fixes each cell's height, which is what makes virtualization possible.
-- It accepts the same `data` and `renderItem` contract as ListView.
+- Give it `data` + `renderItem` when the cells are built from values, and `children` when you already have the widgets: the two are the same contract read from either end.
 
 ## Accessibility
 
@@ -124,6 +125,8 @@ const grid = GridView({
 ## Behavior
 
 - GridView is implemented as ListView with grid wrapping enabled, so it shares the same scrolling and update APIs.
+- Each cell is stretched to fill its slot: `itemHeight` tall, with half of `spacing` on every side so two neighbours meet at exactly one gutter. A cell that asks for its own height keeps it.
+- The number of columns is fixed, not a breakpoint: cells are percentages of the container, so the grid adapts to the width it is given.
 - Rows outside the viewport are removed, so keep per-tile state out of the DOM and in widget state when needed.
 
 ## Related widgets

package/docs/widget/Input.md

@@ -127,6 +127,7 @@ const password = Input({
 
 - Match type to the data (email, password, search) so mobile keyboards adapt.
 - Set validation and showValidationMessage to get inline feedback without extra code.
+- The trailing controls are Icon glyphs from the Material face the app links in its own index.html, drawn in the theme's secondary ink. An emoji in that slot ignores the colour, the font and the size the field sets.
 
 ## Accessibility
 
@@ -137,6 +138,7 @@ const password = Input({
 
 - onChange fires on every keystroke; onEnter fires when the user presses Enter.
 - clearable and passwordToggle add trailing controls that manage the value for you.
+- passwordToggle swaps visibility for visibility_off and moves the button's accessible name with the state.
 
 ## Related widgets
 

package/docs/widget/InstallButton.md

@@ -23,6 +23,7 @@ const install = InstallButton({
 | Prop | Type | Description |
 | --- | --- | --- |
 | `text` | `string` | Visible text content. |
+| `icon` | `string` | Name of the icon to render. |
 | `variant` | `'filled' \| 'outlined' \| 'text'` | Visual variation or style preset. |
 | `size` | `'small' \| 'medium' \| 'large'` | Overall size preset or pixel value, depending on the widget. |
 | `borderRadius` | `number` | Rounds the corners of the widget. |

package/docs/widget/Markdown.md

@@ -161,6 +161,10 @@ const guide = Markdown({
 - CSS into each other.
 - Rendered HTML is sanitized before insert; allowDangerousHtml stays false by default
 - for untrusted input.
+- Inline code writes the palette's readable red, so 12px words clear 4.5:1 on the code
+- plate in both themes.
+- A link takes the palette's readable blue, because in light `primary` is the page's
+- own ink and the link would vanish into the sentence.
 
 ## Related widgets
 

package/docs/widget/Rating.md

@@ -117,6 +117,8 @@ const rating = Rating({
 
 - onChange receives the numeric value each time the user picks a rating.
 - readOnly disables onChange while keeping the current value visible.
+- An unfilled star uses the palette's control grey and a filled one its readable
+- amber, so both states clear 3:1 against the surface they sit on.
 
 ## Related widgets
 

package/docs/widget/Slider.md

@@ -123,6 +123,7 @@ const price = Slider({
 
 - onChanged fires continuously while dragging; use onChangeEnd for the value to commit, such as a filter request.
 - Set step to snap to meaningful increments instead of every integer.
+- On a vertical slider, width is the rail's length and height its thickness.
 
 ## Accessibility
 
@@ -132,6 +133,7 @@ const price = Slider({
 
 - Dragging the track or thumb updates the value and fires onChanged; releasing fires onChangeEnd once.
 - The returned element exposes value, min, max, step, setValue() and getValue(), and disconnects its ResizeObserver on unmount.
+- During a drag the fill follows the pointer with no easing; the 0.1s ease belongs to a value that changes by itself, from a key press or setValue().
 
 ## Related widgets