flet-box 1.1.0 → 1.1.2

package/src/widgets/InstallButton.js

@@ -3,11 +3,16 @@
  * @description PWA install prompt button; hidden unless install is available.
  */
 import { Button } from "./Button.js";
-import { colors } from "../utils/themes.js";
 
 export const InstallButton = (props) => {
   const {
-    text = "📲 Install",
+    // The glyph used to be the 📲 emoji inside the text. An emoji is a picture the
+    // operating system draws, so the button rendered as a tofu box wherever that
+    // font is missing (and the framework already stopped putting emoji in UI in
+    // favour of the bundled Material vocabulary). `get_app` is in `icons.css` for
+    // every platform and inherits `color`, so it themes with the button.
+    text = "Install",
+    icon = "get_app",
     variant = "filled",
     size = "medium",
     borderRadius = 16,
@@ -59,6 +64,7 @@ export const InstallButton = (props) => {
   button = Button({
     widgetName: "InstallButton",
     text: text,
+    icon: icon,
     variant: variant,
     size: size,
     bgColor: backgroundColor,

package/src/widgets/ListTile.js

@@ -92,9 +92,8 @@ export const ListTile = (props) => {
     textChildren.push(
       Text({
         text: subtitle,
-        size: 13,
+        size: 14,
         color: colors.textSecondary,
-        marginTop: 2,
         ...subtitleProps,
       }),
     );
@@ -105,8 +104,10 @@ export const ListTile = (props) => {
       Text({
         text: description,
         size: 12,
-        color: colors.textDisabled,
-        marginTop: 2,
+        // `textDisabled` is the ink of a control that cannot be used, and the
+        // dark palette answers it with #52525B — 2.57:1 on the page. A
+        // description is content, so it takes the muted-but-readable token.
+        color: colors.textSecondary,
         ...descriptionProps,
       }),
     );
@@ -116,7 +117,7 @@ export const ListTile = (props) => {
   const centerColumn =
     textChildren.length > 0
       ? Column({
-          gap: 2,
+          gap: 4,
           alignItems: "flex-start",
           flex: 1,
           minWidth: 0, // allows the column to shrink below its content size in a flex row

package/src/widgets/ListView.js

@@ -4,6 +4,7 @@
  */
 import { WidgetFactory } from "../widget-factory/index.js";
 import { injectKeyframes } from "../utils/styleInjector.js";
+import { markMotionLoop } from "../animations/motion.js";
 import { toREM, getBaseFontSize } from "../utils/units.js";
 
 /**
@@ -77,12 +78,6 @@ export const ListView = (props) => {
     ...rest
   } = props;
 
-  // When expand is true the widget fills its flex parent, ignoring the fixed height prop
-  let finalHeight = height;
-  if (expand) {
-    finalHeight = "100%";
-  }
-
   // Outer element — owns the overall dimensions
   const element = WidgetFactory({
     tag: "div",
@@ -184,11 +179,18 @@ export const ListView = (props) => {
    * Calculates the logical height of the virtual item area. Header and footer are
    * siblings of `innerContainer` and contribute to the scrollbar through their own
    * layout boxes, so they must not be added here.
+   *
+   * Grid mode keeps the trailing gutter. Each cell carries half of the spacing on
+   * every side, so a row ends `slotHeight()` below where it starts and the last one
+   * really is that tall; subtracting the gap there shortened the area by a gutter and
+   * the final row painted over the footer.
+   *
    * @returns {number} Total height in pixels.
    */
   const getTotalHeight = () => {
     const rows = getTotalRows();
     if (rows === 0) return 0;
+    if (isGridMode) return rows * slotHeight();
     return Math.max(0, rows * slotHeight() - gapHeight());
   };
 
@@ -258,8 +260,19 @@ export const ListView = (props) => {
         const col = i % cols;
         wrapper.style.left = `${(col / cols) * 100}%`;
         wrapper.style.width = `${100 / cols}%`;
-        wrapper.style.padding = `0 ${toREM(gap / 2)}`;
+        // The slot is the cell: `itemSize` tall, with `gap` split across the four
+        // sides so two neighbours meet at exactly one gutter. Without the height the
+        // wrapper was only as tall as its content, so `itemSize` reserved the row but
+        // never sized the cell — a grid of labels floating at the top of their rows.
+        // Written in framework units, like the `getItemTop` pitch it must match.
+        wrapper.style.height = toREM(itemSize + gap);
+        wrapper.style.padding = toREM(gap / 2);
         wrapper.style.boxSizing = "border-box";
+        // The cell fills its slot by being stretched, not by writing a height into
+        // the element the caller handed over: their node stays theirs, and a cell
+        // that asked for its own height still keeps it.
+        wrapper.style.display = "grid";
+        wrapper.style.gridTemplateRows = "minmax(0, 1fr)";
       } else {
         wrapper.style.left = "0";
         wrapper.style.right = "0";
@@ -391,6 +404,7 @@ export const ListView = (props) => {
     spinner.style.borderTop = "2px solid #007aff";
     spinner.style.borderRadius = "50%";
     spinner.style.animation = "flet-spin 0.8s linear infinite";
+    markMotionLoop(spinner);
     refreshIndicator.appendChild(spinner);
     scrollContainer.insertBefore(refreshIndicator, scrollContainer.firstChild);
 

package/src/widgets/Markdown.js

@@ -7,25 +7,9 @@ import { WidgetFactory } from "../widget-factory/index.js";
 import { colors } from "../utils/themes.js";
 import { composeUpdate } from "../utils/composeUpdate.js";
 import { generateHighlightedHtml } from "../utils/syntaxHighlight.js";
-
-/**
- * Escapes text for safe insertion as HTML. Local to this file on purpose:
- * importing it from utils/markdownParser.js would pull six widget modules into
- * the dependency graph of every Markdown instance.
- *
- * @param {string} text - Raw text to escape.
- * @returns {string} Text with `&`, `<`, `>`, `"` and `'` replaced by entities.
- */
+import { escapeHtml } from "../helpers/html.js";
 import { toREM } from "../utils/units.js";
 
-const escapeCode = (text) =>
-  String(text)
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
-
 /** Monotonic counter giving each Markdown instance its own CSS scope class. */
 let markdownScopeUid = 0;
 
@@ -113,19 +97,6 @@ const SH = {
   variable: "#e5c07b",
 };
 
-/**
- * Wraps `text` in a `<span>` with the given color, HTML-escaping the content.
- * Returns plain escaped text when `color` is falsy.
- *
- * @param {string} text
- * @param {string} [color]
- * @returns {string}
- */
-const shSpan = (text, color) => {
-  const safe = escapeCode(text);
-  return color ? `<span style="color:${color}">${safe}</span>` : safe;
-};
-
 /**
  * Applies a sequence of `[regex, color]` replacement rules to `line`, escaping
  * every character that is NOT inside a match so raw `<`/`>` cannot break the
@@ -152,15 +123,15 @@ const applyRules = (line, rules) => {
   let m;
   while ((m = combined.exec(line)) !== null) {
     // Text between the previous match and this one — escape and emit as-is.
-    if (m.index > last) out += escapeCode(line.slice(last, m.index));
+    if (m.index > last) out += escapeHtml(line.slice(last, m.index));
     // Find which named group matched.
     const ruleIndex = rules.findIndex((_, i) => m.groups[`r${i}`] !== undefined);
     const color = rules[ruleIndex][1];
-    out += `<span style="color:${color}">${escapeCode(m[0])}</span>`;
+    out += `<span style="color:${color}">${escapeHtml(m[0])}</span>`;
     last = m.index + m[0].length;
   }
   // Remaining plain text.
-  if (last < line.length) out += escapeCode(line.slice(last));
+  if (last < line.length) out += escapeHtml(line.slice(last));
   return out;
 };
 
@@ -212,8 +183,6 @@ const RULES_JSON = [
   [/([{}[\]:,])/, SH.punctuation],
 ];
 
-const RULES_TS = RULES_PYTHON; // TypeScript re-uses the applyRules path below via JS highlighter override
-
 /**
  * Highlights one source line using the appropriate language highlighter.
  * Falls through to plain HTML-escaped text for unknown languages.
@@ -258,7 +227,7 @@ const highlightLine = (line, lang) => {
       return applyRules(line, RULES_JSON);
 
     default:
-      return escapeCode(line);
+      return escapeHtml(line);
   }
 };
 
@@ -311,7 +280,7 @@ const legacyCopy = (text) => {
 const renderFencedBlock = (block) => {
   const lang = block.lang.replace(/[^A-Za-z0-9#+._-]/g, "").toLowerCase();
   const cls = lang ? ` class="language-${lang}"` : "";
-  const label = lang ? `<span class="md-lang-label">${escapeCode(lang)}</span>` : "";
+  const label = lang ? `<span class="md-lang-label">${escapeHtml(lang)}</span>` : "";
 
   // Highlight line-by-line. Lines are joined with a bare "\n" — no wrapper
   // <span> per line because display:block + \n produced two line separators,
@@ -323,7 +292,7 @@ const renderFencedBlock = (block) => {
 
   // The raw code is embedded in a hidden <textarea> so the copy handler can
   // read it without stripping HTML and without touching the DOM of <code>.
-  const safeRaw = escapeCode(block.code);
+  const safeRaw = escapeHtml(block.code);
 
   return (
     `<div class="md-code-block">` +
@@ -591,7 +560,7 @@ const parseMarkdown = (text) => {
   // a `<style>` opened by a sample swallows every following block as CSS.
   html = html.replace(
     /`(.*?)`/g,
-    (_match, code) => `<code>${escapeCode(code)}</code>`,
+    (_match, code) => `<code>${escapeHtml(code)}</code>`,
   );
 
   // Pull real HTML tags out too, so the inline rules below never rewrite an
@@ -623,7 +592,7 @@ const parseMarkdown = (text) => {
   html = html.replace(
     /!\[(.*?)\]\((.*?)\)/g,
     (_match, alt, src) =>
-      `<img src="${escapeCode(src)}" alt="${escapeCode(alt)}" loading="lazy">`,
+      `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}" loading="lazy">`,
   );
 
   // Links — opens in a new tab with rel="noopener" for security. The URL is
@@ -632,7 +601,7 @@ const parseMarkdown = (text) => {
   html = html.replace(
     /\[(.*?)\]\((.*?)\)/g,
     (_match, label, href) =>
-      `<a href="${escapeCode(href)}" target="_blank" rel="noopener">${label}</a>`,
+      `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${label}</a>`,
   );
 
   // Unordered lists — tag each "- item" line as an unordered <li>, then group
@@ -813,13 +782,25 @@ export const Markdown = (props) => {
     color = colors.text,
 
     // Link styling
-    linkColor = colors.primary,
-    linkHoverColor = colors.primary,
+    //
+    // `primary` is the palette's plate, and in light that plate is #18181B — the
+    // page's own ink. A link coloured with it measured rgb(24,24,27) against text
+    // rgb(9,9,11) — 1.12:1 apart, a sentence with an invisible word in it, since `linkUnderline` is off by
+    // default and colour was the only cue. `infoStrong` is the blue this palette
+    // already writes words in (the focus ring uses it for the same reason):
+    // 6.70:1 on the light page, 9.82:1 on the dark card, and unmistakably not body
+    // ink. Hover keeps the same hue and adds the underline — brightening to `info`
+    // would drop to 3.68:1 in light, and a hover state is still text.
+    linkColor = colors.infoStrong,
+    linkHoverColor = colors.infoStrong,
     linkUnderline = false,
 
     // Inline code styling
     codeBgColor = colors.gray100,
-    codeColor = colors.danger,
+    // `danger` is a signal colour for icons and borders; as 12px words on the
+    // `gray100` plate it measured 3.42:1 in light. `dangerStrong` is the palette's
+    // own "red you may write words in" — 5.89:1 on that plate, 8.68:1 in dark.
+    codeColor = colors.dangerStrong,
     codeFontSize = 12,
     codeFontFamily =
       'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Courier New", monospace',

package/src/widgets/Modal.js

@@ -6,6 +6,7 @@ import { WidgetFactory } from "../widget-factory/index.js";
 import { transition } from "../tools/index.js";
 import { colors } from "../utils/themes.js";
 import { injectKeyframes } from "../utils/styleInjector.js";
+import { trapFocus } from "../utils/focusScope.js";
 import { Container } from "./Container.js";
 import { Column } from "./Column.js";
 import { Row } from "./Row.js";
@@ -25,6 +26,17 @@ const ModalOverlay = ({
   // main modal transparent
   return WidgetFactory({
     tag: "div",
+    // The scrim closes the dialog for a pointer, and is nothing at all for a
+    // keyboard: the close button and the actions are the controls. Without these
+    // two the engine would read its `click` as a control and put a full-viewport
+    // "button" on the Tab path, inside the trap, ahead of the dialog's own.
+    role: "presentation",
+    tabIndex: -1,
+    // And no press feedback either: the panel is this element's child, so the
+    // engine's `scale: 0.98` shrank the whole layer — the dialog dipped 1.45px and
+    // lost 9px of width for the length of the press. A scrim dismisses; it is not
+    // a control that answers to being pushed.
+    disableTransform: true,
     position: "fixed",
     top: "0",
     left: "0",
@@ -68,7 +80,10 @@ const ModalHeader = ({
       Text({
         text: title,
         size: 18,
-        weight: "80%",
+        // `80%` is not a font weight — the browser drops the declaration and the
+        // dialog title rendered at the body weight. The sibling overlay header
+        // (`BottomSheet`) asks for `bold`, and this is the same decision.
+        weight: "bold",
         color: headerTextColor || colors.text,
         flex: 1,
       }),
@@ -77,10 +92,13 @@ const ModalHeader = ({
   if (showCloseButton) {
     const closeIcon = Icon({
       name: "close",
-      size: 22,
+      size: 24,
       color: headerTextColor || colors.textSecondary,
       cursor: "pointer",
       onclick: onClose,
+      // A glyph is not a name. The engine makes this pressable reachable; this is
+      // what a screen reader then reads.
+      "aria-label": "Close dialog",
       transition: transition({
         property: "opacity",
         duration: 0.2,
@@ -89,7 +107,10 @@ const ModalHeader = ({
       }),
       // transition: "opacity 0.2s ease",
       borderRadius: "50%",
-      padding: 4,
+      // 24 + 2 x 8 = the 40-unit target; framework units, so it scales with the
+      // reader's font instead of freezing at a pixel size.
+      paddingVertical: 8,
+      paddingHorizontal: 8,
     });
     // Hover effect for close button
     closeIcon.addEventListener("mouseenter", () => {
@@ -309,8 +330,6 @@ export const Modal = (props = {}) => {
     // Callbacks
     onOpen,
     onClose,
-
-    ...rest
   } = props;
 
   let isOpen = false;
@@ -318,6 +337,11 @@ export const Modal = (props = {}) => {
   // Pending "hide after the close animation" timer, so it can be cancelled.
   let closeTimer = null;
   let modalBody = null;
+  // What `trapFocus` hands back while the dialog is open: a keyboard user must
+  // not be able to Tab out behind the scrim, and focus must return to the button
+  // that opened the dialog when it closes. The release is idempotent, so close
+  // and unmount can both call it.
+  let releaseFocusScope = () => {};
 
   // Handlers
   const handleClose = () => {
@@ -336,6 +360,7 @@ export const Modal = (props = {}) => {
       if (overlay) overlay.style.visibility = "hidden";
     }, 300);
     if (closeOnEsc) document.removeEventListener("keydown", handleKeyDown);
+    releaseFocusScope();
     if (onClose) onClose();
   };
 
@@ -357,6 +382,7 @@ export const Modal = (props = {}) => {
     }
     if (onOpen) onOpen();
     if (closeOnEsc) document.addEventListener("keydown", handleKeyDown);
+    releaseFocusScope = trapFocus(modalBody);
   };
 
   const handleKeyDown = (e) => {
@@ -416,6 +442,15 @@ export const Modal = (props = {}) => {
     zIndex,
     overlayColor,
   });
+  // What the panel is to an assistive technology: a dialog, modal while it is
+  // open, and named by its title. `aria-modal` is not decoration — without it a
+  // screen reader keeps reading the page behind the scrim as if it were live.
+  modalBody.setAttribute("role", "dialog");
+  modalBody.setAttribute("aria-modal", "true");
+  if (typeof title === "string" && title) {
+    modalBody.setAttribute("aria-label", title);
+  }
+
   overlay.appendChild(modalBody);
   document.body.appendChild(overlay);
 
@@ -429,6 +464,7 @@ export const Modal = (props = {}) => {
       closeTimer = null;
     }
     if (closeOnEsc) document.removeEventListener("keydown", handleKeyDown);
+    releaseFocusScope();
   });
 
   // Public API
@@ -440,6 +476,7 @@ export const Modal = (props = {}) => {
       if (overlay && overlay.parentNode)
         overlay.parentNode.removeChild(overlay);
       if (closeOnEsc) document.removeEventListener("keydown", handleKeyDown);
+      releaseFocusScope();
     },
     get isOpen() {
       return isOpen;
@@ -492,7 +529,7 @@ export const Modal = (props = {}) => {
                 height: 32,
                 border: `2px solid ${colors.border}`,
                 borderTop: `2px solid ${colors.primary}`,
-                borderRadius: 32,
+                borderRadius: "50%",
                 animation: "modal-spin 0.8s linear infinite",
               }),
               Text({

package/src/widgets/Pagination.js

@@ -2,7 +2,6 @@
  * @file Pagination.js
  * @description Page-number control built from Buttons inside a Row.
  */
-import { WidgetFactory } from "../widget-factory/index.js";
 import { Row } from "./Row.js";
 import { Button } from "./Button.js";
 import { Text } from "./Text.js";
@@ -84,6 +83,10 @@ export const Pagination = (props) => {
 
     return Button({
       text: String(page),
+      // The plate is the only thing that says "this is the page you are on", and a
+      // colour is not something a reader hears. `aria-current` is the same fact in
+      // the accessibility tree.
+      ...(isActive ? { "aria-current": "page" } : null),
       variant: buttonVariant,
       bgColor: isActive ? color : "transparent",
       color: buttonColor,
@@ -95,7 +98,18 @@ export const Pagination = (props) => {
   };
 
   const createIconButton = (iconName, onClick, isDisabled = false) => {
+    // A glyph button has no text to read. The `Icon` inside is decoration — the
+    // ligature would be spoken as `chevron_left` — so the name belongs to the
+    // button, and these five glyphs are the whole vocabulary this strip uses.
+    const glyphNames = {
+      first_page: "First page",
+      last_page: "Last page",
+      chevron_left: "Previous page",
+      chevron_right: "Next page",
+    };
+
     return Button({
+      "aria-label": glyphNames[iconName] || "Page",
       child: Icon({
         name: iconName,
         size: sz.iconSize,
@@ -113,6 +127,10 @@ export const Pagination = (props) => {
   // Main container using Row (already a widget)
   const container = Row({
     widgetName: "Pagination",
+    // A row of bare numbers is not a landmark. Named, it is something a reader can
+    // jump to, jump past, and understand the buttons inside.
+    role: "navigation",
+    "aria-label": "Pagination",
     alignItems: "center",
     gap: sz.gap,
     justifyContent: "center",
@@ -143,7 +161,14 @@ export const Pagination = (props) => {
     container.appendChild(createPageButton(1));
     if (pageNumbers[0] > 2) {
       container.appendChild(
-        Text({ text: "...", size: sz.fontSize, color: colors.textSecondary }),
+        Text({
+          text: "...",
+          // The skipped pages are a visual ellipsis: spoken as "dot dot dot" it is
+          // noise, and the jump is already implied by the numbers around it.
+          "aria-hidden": "true",
+          size: sz.fontSize,
+          color: colors.textSecondary,
+        }),
       );
     }
   }
@@ -155,7 +180,14 @@ export const Pagination = (props) => {
   if (pageNumbers[pageNumbers.length - 1] < totalPages) {
     if (pageNumbers[pageNumbers.length - 1] < totalPages - 1) {
       container.appendChild(
-        Text({ text: "...", size: sz.fontSize, color: colors.textSecondary }),
+        Text({
+          text: "...",
+          // The skipped pages are a visual ellipsis: spoken as "dot dot dot" it is
+          // noise, and the jump is already implied by the numbers around it.
+          "aria-hidden": "true",
+          size: sz.fontSize,
+          color: colors.textSecondary,
+        }),
       );
     }
     container.appendChild(createPageButton(totalPages));

package/src/widgets/ProgressBar.js

@@ -5,6 +5,7 @@
 import { WidgetFactory } from "../widget-factory/index.js";
 import { colors } from "../utils/themes.js";
 import { injectKeyframes } from "../utils/styleInjector.js";
+import { markMotionLoop } from "../animations/motion.js";
 
 import { toREM } from "../utils/units.js";
 
@@ -54,6 +55,7 @@ export const ProgressBar = (props) => {
   // Animated stripes
   if (animatedStripes || indeterminate) {
     fill.style.animation = `progress-stripes ${indeterminate ? "1.5s" : "0.5s"} linear infinite`;
+    markMotionLoop(fill);
     injectKeyframes(
       "progress-stripes",
       "0% { background-position: 0 0; } 100% { background-position: 28px 0; }",
@@ -65,6 +67,7 @@ export const ProgressBar = (props) => {
     fill.style.width = "50%";
     fill.style.transform = "translateX(-100%)";
     fill.style.animation = "indeterminate-progress 1.5s ease-in-out infinite";
+    markMotionLoop(fill);
     injectKeyframes(
       "indeterminate-progress",
       "0% { transform: translateX(-100%); } 50% { transform: translateX(0%); } 100% { transform: translateX(100%); }",
@@ -146,6 +149,18 @@ export const ProgressBar = (props) => {
   // Main container
   const container = WidgetFactory({
     widgetName: "ProgressBar",
+    // A bar is a picture of a number, and a picture says nothing. The role is what
+    // lets a reader hear the number instead: `aria-valuenow` is the same value the
+    // fill width is drawn from.
+    role: "progressbar",
+    "aria-valuemin": "0",
+    "aria-valuemax": String(max),
+    // An indeterminate bar has no progress to report — giving it a number would be
+    // a confident lie, so it is left to `aria-busy` and the label.
+    ...(indeterminate
+      ? { "aria-busy": "true" }
+      : { "aria-valuenow": String(progressValue) }),
+    ...(label ? { "aria-label": label } : null),
     display: "flex",
     flexDirection: isColumn ? "column" : "row",
     alignItems: "center",
@@ -161,6 +176,9 @@ export const ProgressBar = (props) => {
     progressValue = Math.min(Math.max(newValue, 0), max);
     percentage = (progressValue / max) * 100;
     fill.style.width = `${percentage}%`;
+    // The announced number has to be the drawn number: a reader kept on the build
+    // value would hear "0%" while the bar filled.
+    container.setAttribute("aria-valuenow", String(progressValue));
 
     if (valueElRef) {
       valueElRef.textContent = `${Math.round(percentage)}%`;

package/src/widgets/Radio.js

@@ -35,6 +35,7 @@ export const Radio = (props) => {
   const offColor = disabled ? colors.border : colors.gray500;
 
   const updateUI = (newSelected) => {
+    if (radio) radio.setAttribute("aria-checked", String(Boolean(newSelected)));
     if (radioRef) {
       radioRef.style.backgroundColor = newSelected ? activeColor : "transparent";
       radioRef.style.border = `2px solid ${newSelected ? activeColor : offColor}`;
@@ -89,6 +90,11 @@ export const Radio = (props) => {
 
   const rootProps = {
     widgetName: "Radio",
+    // A ring and a dot are drawing instructions, not a control. The role names it
+    // and `aria-checked` is the state; both are set before the factory runs so the
+    // engine does not settle for `button`.
+    role: "radio",
+    "aria-checked": String(Boolean(internalSelected)),
     display: "inline-flex",
     alignItems: "center",
     justifyContent: isLabelled ? "flex-start" : "center",
@@ -121,6 +127,7 @@ export const Radio = (props) => {
   // Inline usage (a radio dropped mid-paragraph) would otherwise baseline-align
   // the box's bottom edge and lift the ring above the text.
   radio.style.verticalAlign = "middle";
+  if (disabled) radio.setAttribute("aria-disabled", "true");
 
   // Handle click
   if (!disabled) {