flet-box 1.0.9 → 1.1.1

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
 

package/docs/widget/Stack.md

@@ -1,6 +1,6 @@
 # Stack
 
-Overlay container that lets children occupy the same box. It is relative by default so children can be positioned, and it supports a nine-point alignment.
+Overlay container: every child after the first paints in the same box, anchored by a nine-point `alignment` or by its own edges.
 
 ## When to use it
 
@@ -101,9 +101,10 @@ const stack = Stack({
 
 ## Tips
 
-- Stack is `position: "relative"` by default, which makes it a positioning context for absolute children.
-- `alignment` anchors children at one of nine points from top-left to bottom-right.
+- The first child stays in the flow and gives the stack its size; every child after it floats over that box.
+- `alignment` anchors the children that name no edges, at one of nine points from top-left to bottom-right. Top-left is the default.
 - Later children paint on top, so order them from back to front.
+- A child that names its own `top`/`right`/`bottom`/`left` keeps those, and a child that declares `position` is left alone — that is how a child stays in the flow.
 
 ## Accessibility
 
@@ -111,8 +112,8 @@ const stack = Stack({
 
 ## Behavior
 
-- The root is a plain block by default and children are laid out per `position` and `alignment`.
-- Set `width` and `height` (or `expand`) when the stack needs a definite size for layered content.
+- The root is a flex column, so `alignment` places the in-flow child too; an explicit `justifyContent` or `alignItems` wins over it.
+- The layers take no space. Give the stack a `width` and `height`, or make the first child the size you want the box to be, or there is nothing for them to sit on.
 
 ## Related widgets
 

package/docs/widget/Stepper.md

@@ -122,6 +122,8 @@ const checkout = Stepper({
 
 - Steps are clickable, so users can jump around; use onStepChange to validate a step before allowing the move.
 - variant: icons pulls each step's icon; circles and numbers ignore it.
+- A step's content is a live widget and a DOM node has one parent, so build the steps array where the Stepper is built: sharing one array between two steppers empties the first slot, and the widget warns when it happens.
+- orientation: vertical puts each label beside its marker; horizontal puts it underneath. showLabels: false hides it in both.
 
 ## Accessibility
 

package/docs/widget/Tooltip.md

@@ -116,11 +116,12 @@ const tip = Tooltip({
 
 - Attach it to any widget via child; the tooltip is a separate portal, so overflow hidden ancestors do not cut it off.
 - delay controls how long the pointer must rest before the tooltip appears; lower it for dense toolbars, raise it for error-prone hints.
-- The bubble is clamped to the viewport edges, so top/left placements can sit slightly inside the window bounds.
+- The bubble keeps to the device's safe area, so a placement is a request: an edge with no room for it gets the opposite edge instead.
 
 ## Accessibility
 
 - The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get the same tooltip as mouse hover.
+- On a device that cannot hover the bubble stays hidden. iOS answers the first tap with a synthetic mouseenter and never sends the matching mouseleave, so a tap-shown tooltip is a bubble nothing can dismiss. Anything a tooltip explains has to be explained by the control's own label too.
 
 ## Behavior
 
@@ -128,6 +129,7 @@ const tip = Tooltip({
 - The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition helpers for imperative control.
 - A pointer that leaves before the wait is over never shows the bubble: leaving clears the timer.
 - tooltipDelay is the old name of delay. When both are given, delay wins.
+- The requested position is a preference, not a promise: when the bubble would not fit between the trigger and the safe-area edge it is placed on the opposite side, and the arrow follows it.
 
 ## Related widgets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.9",
+  "version": "1.1.1",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
+    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-shared-helpers.mjs && node scripts/check-a11y.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-time-helpers.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-framework-ui.mjs && node scripts/check-skills.mjs && node scripts/check-app-types.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
     "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
@@ -47,12 +47,14 @@
   "devDependencies": {
     "chokidar": "^4.0.3",
     "esbuild": "^0.28.0",
+    "typescript": "^7.0.2",
     "ws": "^8.21.0"
   },
   "files": [
     "bin/",
     "src/",
     "docs/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],