flet-box 1.1.0 → 1.1.1

package/bin/utils/templates.js

@@ -709,54 +709,6 @@ echo "Press Ctrl+C to stop"
 python3 -m http.server $PORT --bind $BIND
 `;
 
-export const createBundleSh = (target = "www") => `#!/bin/bash
-# createBundle.sh — Bundle UNIFICADO a \${TARGET}/ (un solo app.js + PWA)
-# Uso: bash createBundle.sh [target]
-set -euo pipefail
-cd "\$(dirname "\$0")"
-TARGET="\${1:-${target}}"
-
-if ! npx --no-install esbuild --version >/dev/null 2>&1; then
-    echo "📦 Instalando esbuild (devDependency)…"
-    npm install --save-dev esbuild >/dev/null
-fi
-
-rm -rf "\$TARGET"
-mkdir -p "\$TARGET/src" "\$TARGET/assets"
-
-# Root static files (PWA + preview)
-for f in index.html manifest.json run.sh service-worker.js; do
-    [ -f "\$f" ] && cp "\$f" "\$TARGET/"
-done
-[ -f "\$TARGET/run.sh" ] && chmod +x "\$TARGET/run.sh"
-
-# Assets: iconos PWA + fuentes de iconos
-if [ -d "src/assets" ]; then
-    cp -R src/assets/. "\$TARGET/src/assets/"
-    cp -R src/assets/. "\$TARGET/assets/"
-fi
-
-# CSS global (lo carga index.html)
-if [ -f "src/styles/global.css" ]; then
-    mkdir -p "\$TARGET/src/styles"
-    cp src/styles/global.css "\$TARGET/src/styles/"
-fi
-
-# BUNDLE UNIFICADO: flet-box + widgets en UN solo app.js
-echo "📦 Bundling (esbuild + tree-shaking)…"
-npx esbuild src/app.js \\
-    --bundle --outfile="\$TARGET/src/app.js" --format=esm --minify \\
-    --tree-shaking=true --target=es2020 --define:FLETBOX_DEV=false \\
-    --external:*.css --external:*.woff2 --resolve-extensions=.js,.json
-
-# App source code (required by the "View code" button)
-for d in modules screens database components; do
-    [ -d "src/\$d" ] && cp -R "src/\$d" "\$TARGET/src/"
-done
-
-echo "✅ Bundle listo: \$TARGET/   Prueba: cd \$TARGET && bash run.sh"
-`;
-
 export const serviceWorkerJs = () => `// service-worker.js - PWA offline support
 const CACHE_NAME = 'fletbox-v2';
 // Deployment prefix: a worker's own URL always sits at the app root, so this
@@ -879,6 +831,28 @@ self.addEventListener('fetch', event => {
 });
 `;
 
+// Not TypeScript: an editor reads this file and runs its bundled JS language
+// service over `flet-box`'s own .d.ts, so a prop autocompletes and a prop that
+// does not exist is a squiggle. `bundler` is the resolution an unbundled-ESM
+// app needs, and TypeScript 7 removed `node10` outright — an older editor that
+// still only knows `node` ignores the whole jsconfig, which is no worse than
+// not having one. Nothing here is compiled or installed.
+export const jsconfig = () => `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "checkJs": true,
+    "strict": false,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules", "www", "dist"]
+}`;
+
 export const packageJson = (name) => `{
   "name": ${JSON.stringify(name)},
   "version": "1.0.0",
@@ -1663,6 +1637,15 @@ npm install
 npm run dev
 \`\`\`
 
+## Autocomplete without TypeScript
+
+\`jsconfig.json\` points the editor's own JavaScript language service at
+\`flet-box\`'s bundled \`.d.ts\` — nothing to install, nothing to compile. Every
+widget, prop, colour token and helper autocompletes in VS Code (or any editor
+that reads jsconfig), and a prop that does not exist is underlined as an error
+instead of failing silently at runtime. \`src/\` is the only folder checked;
+\`npm run check\` remains the gate that runs in CI.
+
 ## Working with an AI assistant
 
 This project ships an in-project agent contract, so an AI editing the app uses the
@@ -2066,7 +2049,7 @@ import { AppBar, Icon, Tooltip, colors, openDrawer, toggleTheme, getTheme } from
 // It reads the theme instead of subscribing to it: setTheme() re-renders the app,
 // so a component that subscribed would add a listener on every render and never
 // remove it.
-export const AppBarComponent = ({ title, isMobile = false, showBack = false, onBack }) => {
+export const AppBarComponent = ({ title, isMobile = false, showBack = false, onBack = () => {} }) => {
     const isDark = getTheme() === 'dark';
 
     return AppBar({
@@ -2244,7 +2227,7 @@ runApp(App, 'root');
 `;
 
 export const basicAppJs = () => `// app.js - Basic template (AppBar + Drawer)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2264,13 +2247,14 @@ const routes = {
 };
 
 // The drawer is only reachable through the AppBar's menu button, so the shell has
-// to know whether it is on a phone. Key-based state keeps the width across
-// re-renders; the resize listener is registered once, at module scope.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+// to know whether it is on a phone. Key-based state keeps the answer across
+// re-renders; the subscription is registered once, at module scope, and only
+// fires when the viewport crosses a breakpoint, not on every pixel of a resize.
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 const MyApp = () => {
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2284,7 +2268,7 @@ runApp(MyApp, 'root');
 
 export const fullAppJs =
   () => `// app.js - Full template (AppBar + Drawer + BottomNav)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2304,15 +2288,15 @@ const routes = {
     '/about': AboutScreen
 };
 
-// State is key-based, so the viewport width survives re-renders. One resize
+// State is key-based, so the layout answer survives re-renders. One breakpoint
 // subscription feeds it from module scope: registering it inside the component
-// would add a listener on every render.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+// would add a listener on every render, and it only fires when a step is crossed.
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 const MyApp = () => {
     // Structural read of the key, so crossing the breakpoint re-renders the shell.
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2357,7 +2341,7 @@ runApp(MyApp, 'root');
 
 export const adaptiveAppJs =
   () => `// app.js - Adaptive template (mobile + desktop)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2380,11 +2364,11 @@ const routes = {
     '/profile': ProfileScreen
 };
 
-// State is key-based, so the viewport width survives re-renders. The resize
+// State is key-based, so the layout answer survives re-renders. The breakpoint
 // subscription is registered once at module scope; doing it inside the component
 // would add another listener on every render.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 // One menu, three surfaces: the drawer and the bottom bar on a phone, the
 // sidebar on a desktop. The labels stay short because the bottom bar has to fit
@@ -2397,9 +2381,9 @@ const menu = [
 ];
 
 const MyApp = () => {
-    // Structural read of the keyed viewport state, so crossing the breakpoint
+    // Structural read of the keyed layout state, so crossing the breakpoint
     // re-renders the shell (drawer + bottom bar <-> sidebar).
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2547,9 +2531,13 @@ export const agentsMd = (appName, template, version) =>
     'Real `Scaffold` props: `appBar body bottomBar fab drawer leftNavBar',
     'leftNavBarWidth rightNavBar rightNavBarWidth routes basePath backgroundColor',
     'closeDrawerOnNavigate`. (`--props Scaffold` is authoritative.)',
-    'For a responsive app, branch in JS on the keyed viewport state — `useState`',
-    'seeded from `dimensions.getWidth()` plus one `dimensions.addListener()` at',
-    'module scope — not on CSS alone. See `src/app.js` in this project.',
+    'For a responsive app, branch in JS on the breakpoint table, not on CSS alone:',
+    '`useState` seeded from `atLeast("md")` plus one `onBreakpointChange()` at',
+    'module scope — it fires when the viewport crosses a step, not on every pixel',
+    'of a resize. `md` is 768, the same line `AdaptiveScaffold` crosses, so a',
+    'screen and its shell cannot disagree. A number that really wants to be',
+    'different at 400px and 1400px comes from `pick({ xs: 16, md: 24 })`.',
+    'See `src/app.js` in this project.',
     '',
     'Custom widgets follow the same shape every framework widget uses',
     '(`QRCode.js` is the reference):',
@@ -2566,8 +2554,25 @@ export const agentsMd = (appName, template, version) =>
     '  idempotent `onUnmount` disposer. Never monkey-patch `_cleanup`.',
     '- State is key-based: `useState("key", 0)` plus subscribers. There is no',
     '  component re-render tree to reason about.',
-    '- Reuse the framework utilities (`colors`, `margin`, `padding`, `gradient',
-    '  shadow`, `rgba`, `stackPosition`) instead of hand-writing CSS.',
+    '- The package exports 123 helpers next to the widgets and they are the short',
+    '  form of the code you would otherwise write: `mapList` (an array, a number or',
+    "  an object), `createList`, `range`, `repeat`, `sort`, `unique`, `chunk`,",
+    '  `shadow`, `gradient`, `rgba`, `transform`, `transition`, `filter` (a CSS',
+    '  filter, not a list filter), `color(hex).darken(12).hex()`, `random.*`,',
+    '  `shortId`, `uuid`, `formatDate`, `formatTimeAmPm`, `relativeTime`, `timeAgo`,',
+    '  `addDays`, `subtractDays`, `dateDiff`, `dayOfWeek`, `isWeekend`, `today`,',
+    '  `seconds`, `days`, `parseDate`, `timer`, `every`, `everySecond`, `waitUntil`,',
+    '  `split`, `join`, `trim`, `startsWith`, `endsWith`, `includes`,',
+    '  `delay`, `withMinDelay`,',
+    '  `retry`, `memo`, `dict`, `print`, `ref`, `atLeast`, `pick`,',
+    '  `onBreakpointChange`, `loadFont`, `clipboard`. Hand-write the long version',
+    '  only when it is genuinely shorter or clearer. `npm run check -- --list`',
+    '  prints the set for the version actually installed.',
+    '  The trap: a routed prop already IS the short form. `padding: 16` reaches the',
+    '  rem contract; `padding(16)` returns a pixel string. Use the helpers for a',
+    '  CSS value a prop cannot express, never instead of a number.',
+    '  Second trap: `months(1)` is 30 days and `years(1)` is 365, and `addDays`',
+    '  counts calendar days while `addHours` counts real elapsed ones.',
     '',
     'One rendering engine exists: `src/widget-factory/`. Never add a second one, and',
     'never style by reaching around the factory. **If you believe the engine is',
@@ -2625,7 +2630,7 @@ export const agentsMd = (appName, template, version) =>
     '         40  ·  the smallest tap target, a roomy control',
     '         48  ·  hero spacing',
     '         64 / 96  ·  a full-bleed section, a landing hero',
-    'radius     4 / 8 / 12 / 16 / 999 (pill)',
+    'radius     4 / 8 / 12 / 16 / 20 / 24 / 999 (pill)',
     'type      12 caption · 14 body-small · 16 body · 18 subtitle · 24 title',
     '          32 headline · 40 / 48 display (a hero, a big number)',
     'weight    400 body · 500 label · 600 title · 700 headline',

package/docs/README.md

@@ -17,6 +17,7 @@ This documentation is one continuous book. Start at **Chapter 0** and follow the
 | 10 | [Tools & Utilities](tools/README.md) | The helper functions that ship with the framework | Intermediate |
 | 11 | [The CLI](cli/README.md) | Create, run, and build projects with `flet-box` | Intermediate |
 | 12 | [Clean UI](guides/clean-ui.md) | The four skills every app ships with, the design system they hold, and the gate that enforces it | Intermediate |
+| 13 | [Accessibility](guides/accessibility.md) | The focus ring, the keyboard pass over every press, the roles the widgets declare, and the overlays that hold the keyboard | Intermediate |
 | A | [Appendices](guides/minification-and-protection.md) | Minification, mobile, compatibility, embedding, online updates (OTA) | Advanced |
 
 > **Levels.** *Beginner:* start here and read in order. *Intermediate:* continue in order — you are comfortable with widgets. *Advanced:* for when you ship, skip on a first read.
@@ -54,6 +55,7 @@ Front cover (this page)
 → Utilities guide · guides/utilities.md
 → The CLI · cli/README.md
 → Clean UI · guides/clean-ui.md
+→ Accessibility · guides/accessibility.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```

package/docs/cli/README.md

@@ -275,6 +275,7 @@ A typical generated project looks like this:
 ```text
 my-app/
 ├── index.html
+├── jsconfig.json
 ├── package.json
 ├── capacitor.config.json
 ├── manifest.json
@@ -301,7 +302,23 @@ my-app/
 
 The exact folders depend on the selected template.
 
-## A complete beginner workflow
+### Autocomplete without TypeScript
+
+`jsconfig.json` is not a build step: it tells the editor's own JavaScript
+language service to read `flet-box`'s bundled `src/index.d.ts`. With `checkJs`
+on, VS Code, Cursor and any editor that understands `jsconfig.json` autocomplete
+every widget, prop, colour token and helper — and underline a prop that does not
+exist, which is the same error `npm run check` reports from the command line.
+
+Nothing is installed and nothing is compiled. The framework keeps the promise
+honest with `scripts/check-app-types.mjs`, which creates all five templates and
+requires zero diagnostics over their `src/` — a starter that produces red
+squiggles fails `npm test`.
+
+```bash
+npm run check   # the gate: real API, real props, real imports
+```
+
 
 ```bash
 # 1. Create the project

package/docs/guides/README.md

@@ -11,8 +11,11 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[FletBox utilities](utilities.md)** — Chapter 10 · layout/theme/format helpers and validator tools.
 - **[The CLI](../cli/README.md)** — Chapter 11 · create, run, and build projects with `flet-box`.
 - **[Clean UI](clean-ui.md)** — Chapter 12 · the four skills `flet-box create`
-  installs, the token scale, the 25 rules, and the `flet-box check-ui` gate that
-  enforces them.
+  installs, the token scale, the numbered rules (00–24 enforced, 25–37 the
+  visual atlas), and the `flet-box check-ui` gate that enforces them.
+- **[Accessibility](accessibility.md)** — Chapter 13 · the focus ring, the
+  keyboard pass over every press, the roles and states the widgets declare, and
+  the overlays that hold the keyboard.
 - **[Widget structure](widget-structure.md)** — the canonical, modular shape every widget follows (and how new ones are added).
 
 ## Appendices (Advanced — for shipping)

package/docs/guides/accessibility.md

@@ -0,0 +1,282 @@
+# Accessibility: the engine's half and your screen's half
+
+A FletBox control is a `div` that the framework teaches to behave like a
+`button`. That is what makes the syntax pleasant — `Container({ onPress })`
+instead of a stylesheet and three event listeners — and it is also where
+accessibility is won or lost. Three things have to be true for someone with no
+pointer: the control must be **reachable** (Tab), **operable** (Enter and
+Space), **announced** (a role and a name), and the person must be able to see
+**where they are** (a focus ring). An overlay owes a fourth: hold the keyboard
+while it is open, and give it back when it closes.
+
+The engine already does all four. This chapter is about the half it cannot do
+for you, and about the two ways an app destroys the half it was given.
+
+## 1. The focus ring is a stylesheet, not a paint
+
+A focus ring is not a decoration — it is a *state*, and a state can only live in
+a stylesheet. `src/utils/focusRing.js` appends one `<style id="fletbox-focus-ring">`
+to `<head>` the first time any widget is created, and never appends a second:
+
+```css
+:where(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+```
+
+Three deliberate choices, each worth knowing when you want something different:
+
+- **`:focus-visible`, not `:focus`.** A click with a mouse does not ring; the
+  keyboard does. That is the browser's own distinction, not the framework's.
+- **`:where(…)` keeps specificity at zero.** One class of yours overrides it,
+  and no `!important` is needed anywhere.
+- **The color is a token.** `--color-focusRing` is written by `applyPalette` for
+  every theme, so the ring moves with the theme instead of being a literal that
+  only suits one background. The light palette's `#1d4ed8` is 6.4:1 on the page,
+  the dark one's `#93c5fd` is 11:1, and the literal after the comma in the rule
+  is the boot value a page shows before the first `setTheme`.
+
+The widths are pixels on purpose, next to `SHADOW_LEVELS` and the hairline
+`borderWidth`: a 1px ring is invisible and a 6px one is a blob, whatever the
+reader's font size is.
+
+### The one thing an app must never do
+
+```javascript
+// Never. An inline declaration outranks every stylesheet rule, including the
+// engine's, so this is what "the focus ring does not work" looks like in code.
+element.style.outline = "none";
+
+// Never, for the same reason, anywhere in a global stylesheet:
+// *:focus { outline: none; }
+```
+
+If you do not like the ring's colour, change the token — or override the rule
+with one class of your own, which `:where()` makes possible:
+
+```javascript
+import { registerPalette } from "flet-box";
+
+// The token is part of the palette, so both themes move it and nothing is
+// overridden behind the framework's back. A registered palette repaints only
+// when it is the one on screen.
+registerPalette("light", { focusRing: "#0f766e" });
+registerPalette("dark", { focusRing: "#5eead4" });
+```
+
+```css
+/* or, for one component only: a class beats :where(...) whatever the order */
+.chart:focus-visible { outline-color: var(--color-primary); }
+```
+
+### A field rings as a whole control
+
+`Input` is a wrapper with a border, an icon and sometimes a reveal button, and
+the native `<input>` inside it is only part of the control. A ring around the
+text box alone draws a box *inside* the thing it is supposed to mark. So the
+rule has a second pair:
+
+```css
+:where([data-fb-field]):has(> input:focus-visible) {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+:where([data-fb-field]) > input:focus-visible {
+  outline: none;
+}
+```
+
+The `outline: none` there is a *rule*, at zero specificity, which any app can
+still override — that is the whole difference between silencing the inner box
+and killing the ring. The marker (`data-fb-field`) is written by `Input`; if you
+build your own composite field (a text box with a button inside), put the same
+marker on the wrapper and the ring lands where the control is.
+
+And keep the two jobs apart: **the border is validation, the ring is focus.**
+A field that paints focus by recolouring its rim, or by adding a `box-shadow`,
+puts two indicators where one belongs and loses the validation state the moment
+someone types.
+
+## 2. A press is a press, however it arrives
+
+Give any widget a click handler as a prop and the engine runs a keyboard pass
+over it — `src/widget-factory/effects.js`:
+
+- it sets `role="button"` **if you have not set a role**;
+- it sets `tabIndex = 0` **if you have not set one** (an explicit `-1` is your
+  decision to keep the element off the Tab path, and it is respected);
+- Enter and Space fire the same handler a pointer fires, with Space's default
+  (scrolling the page) cancelled and a held key counted as one press;
+- a nested control keeps its own keys — Enter on a `Button` inside a pressable
+  `Card` presses the button and the card, not twice the card;
+- native `button`/`a[href]` are left alone, and disabled controls are not made
+  Tab stops.
+
+```javascript
+Container({ onPress: openDetails, children: [Text({ text: "Details" })] });
+// role="button", tabIndex=0, Enter and Space → openDetails
+```
+
+The one way an app defeats this is to attach the handler to the element after
+the widget was built. The pass runs during construction; a handler assigned
+afterwards leaves a control with a click, no role, no Tab stop and no keyboard:
+
+```javascript
+const card = Container({ children: [Text({ text: "Details" })] });
+card.onclick = openDetails; // mouse-only: the engine already ran
+```
+
+Express the control with a prop instead — `onPress` (or `onClick`) on any
+widget — and the engine sees it.
+
+### An icon is decoration until it is a control
+
+`Icon` has two lives, and it picks one by itself:
+
+- `Icon({ name: "search" })` — no name for a reader, so it is marked
+  `aria-hidden="true"` and kept off the Tab path. Correct inside a `Button`
+  that already has text.
+- `Icon({ name: "search", onPress: focusSearch, "aria-label": "Search" })` — a
+  named, pressable icon keeps `role="button"` and is read as "Search, button".
+
+An icon-only control with no `aria-label` is read as "button", which is the
+worst of both worlds: reachable, operable, and anonymous. The places where the
+framework wires a glyph up for you already name it — the `AppBar` back arrow,
+`Input`'s `onIconPress` and reveal button, and the menu icon a `Scaffold`
+connects to its drawer.
+
+## 3. Names, roles and states the widgets already declare
+
+You can pass `role` and `tabIndex` as ordinary props, and any `aria-*`
+attribute reaches the element verbatim (`"aria-label": "…"`). Everything below
+is already in place; the table exists so you know what not to duplicate.
+
+| Widget | Role | States it keeps in sync |
+| --- | --- | --- |
+| `Button`, `Container` with `onPress` | `button` | — (engine pass) |
+| `Switch` | `switch` | `aria-checked` |
+| `Checkbox` | `checkbox` | `aria-checked` |
+| `Radio` / `Rating` | `radio` / `radiogroup` | `aria-checked` |
+| `Slider` | `slider` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-orientation` |
+| `ProgressBar`, `CircularBar` | `progressbar` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-busy` while indeterminate |
+| `Dropdown` | `combobox` | `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-invalid`, `aria-labelledby` |
+| `Dropdown` list | `listbox` / `option` | `aria-selected` |
+| `Tabs` | `tablist` / `tab` / `tabpanel` | `aria-selected`, roving `tabIndex`, `aria-controls` |
+| `Accordion` | `button` / `region` | `aria-expanded`, `aria-controls` |
+| `Pagination` | `navigation` | `aria-current="page"` |
+| `Stepper` | — | `aria-current="step"` |
+| `BottomNavigation` | — | `aria-current="page"` |
+| `Modal`, `BottomSheet`, `Drawer` | `dialog` | `aria-modal="true"` |
+| `SnackBar` | live region | `aria-live="polite"`, `"assertive"` for error and warning |
+| `Tooltip` | `tooltip` | `aria-describedby` on the trigger while shown |
+| `Maps` | `application` | — |
+| `CircularChart` | `img` | give it an `aria-label`; it is a picture of data |
+
+Composite widgets answer the keyboard the way their ARIA pattern says: `Tabs`,
+`Dropdown`, `Rating` and `Slider` move with the arrow keys, take `Home` and
+`End`, and keep a single Tab stop per group. The Dropdown's options are
+deliberately *not* Tab stops — the selector holds focus, the arrows move the
+highlight and `aria-activedescendant` names the row.
+
+What is left for you is **naming**: a visible `label` where the widget has one
+(`Input`, `Dropdown`), `text` for a button (`"Save"` is a name; `"OK"` is not —
+see the clean-UI rule about generic action labels), `alt` on images, and
+`aria-label` for anything that has no visible words of its own.
+
+## 4. An invalid field says so in two places
+
+A red rim is the visual half. The other half is the state and the reason, and
+`Input` keeps them together: while a message is showing, the field carries
+`aria-invalid="true"` and an `aria-describedby` pointing at the message, which
+is a `polite` live region; when the value becomes valid, all three leave
+together. A described-by pointing at a `display: none` node would be a control
+claiming a description it does not have.
+
+```javascript
+const email = Input({ label: "Email", validation: "email", required: true });
+
+// submit
+const { valid, message } = email.validate(); // paints, links and announces
+```
+
+Use `validate()` (or `setValue()`, which validates) rather than colouring a rim
+by hand: `showValidationMessage` decides whether the reason is on screen, and a
+ring with no message tells a reader "wrong" and nothing else.
+
+## 5. Overlays hold the keyboard, then give it back
+
+`Modal`, `BottomSheet` and `Drawer` share one scope (`src/utils/focusScope.js`),
+and one implementation on purpose:
+
+- focus moves into the panel when it opens — the first control, or the panel
+  itself (`tabIndex="-1"`) when it has none, so an alert with two lines of text
+  still takes the keyboard;
+- Tab and Shift+Tab cycle **inside** the panel instead of walking out behind
+  the scrim into a page the person can no longer see;
+- Escape closes it (each overlay already listens);
+- closing hands focus back to whatever was focused before, and skips that if the
+  element has left the page (a route change replaced it).
+
+The trap and the ring read the same list of reachable elements — `a[href]`,
+`button`, `input`, `select`, `textarea`, `summary` and anything on the Tab path
+— so a stop you can Tab to is always a stop that shows a ring.
+
+For an app, the contract is simply: open and close these through their props and
+refs, and do not build a full-screen scrim by hand with its own Escape listener.
+
+## 6. Verify it with the keyboard
+
+Five minutes, no screen reader needed:
+
+1. Press Tab from the top of the screen. Every control gets a ring; nothing is
+   skipped and nothing rings twice.
+2. Press Enter and Space on each control. The same thing happens as with a click.
+3. Focus a field and type. The rim stays put until there is a verdict.
+4. Submit an invalid form. The message is under the field, the field says
+   `aria-invalid`, and the message disappears with the fix.
+5. Open a modal. Tab to the last control and press Tab once more: focus is back
+   at the first, not behind the scrim.
+6. Press Escape. Focus is back on whatever opened it.
+7. Repeat 1–6 with a screen reader (VoiceOver: `Cmd+F5`; TalkBack on Android) and
+   listen for names: "Search, button", "Email, invalid entry, Invalid email
+   address".
+
+Then let the gates do what they do:
+
+```bash
+npm run check    # the API is real: widgets, props, imports
+npm run ui       # names, labels, tap targets, contrast:
+                 #   UNLABELED_FIELD, UNLABELED_TOGGLE, ICON_ONLY_CONTROL,
+                 #   IMAGE_NO_ALT, SMALL_TAP_TARGET, LOW_CONTRAST*, UNREADABLE
+npm run dev      # then Tab through it; the checker has no keyboard
+```
+
+In the framework repository itself, `node scripts/check-a11y.mjs` runs inside
+`npm test` and holds the invariants of this chapter: nothing writes an inline
+`outline`; the ring rule is injected and carries the token; both palettes define
+`focusRing`; the pressable path sets role, Tab stop and Enter/Space and releases
+its listener; every overlay that reads Escape also traps focus; the trap and the
+ring agree on what is reachable; and no handler is attached after the factory
+returned. Every one of those rules has been proven to fail on the bug it
+forbids. The runtime half lives in `/tests/a11y.html`.
+
+## See also
+
+- [Clean UI](clean-ui.md) — the design rules this chapter's checklist comes from.
+- [Themes](../tools/theme.md) — `registerPalette`, the call that moves the ring.
+- [Input](../widget/Input.md) — the props used above.
+- [Modal](../widget/Modal.md) · [BottomSheet](../widget/BottomSheet.md) ·
+  [Drawer](../widget/Drawer.md) — the three overlays and what they return.
+- [Widget structure](widget-structure.md) — where a widget's defaults and
+  disposers live.
+
+---
+
+## Continue reading
+
+- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
+- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 13 · Accessibility**.