flet-box 1.1.2 → 1.1.3

package/src/widgets/ThemePicker.js

@@ -0,0 +1,234 @@
+/**
+ * @file ThemePicker.js
+ * @description A grid of two-tone swatches that picks the screen's accent color.
+ *
+ * One control, twelve choices, no color theory. Each swatch is a square split
+ * down its diagonal: the upper-left half is the family's accent in the light
+ * theme, the lower-right half is the same family in the dark one. That is the
+ * iOS Settings shape, and it is the only honest way to show a *pair* — a FletBox
+ * accent is not one color but the two stops one hue wears in the two themes, and
+ * a reader who sees both knows what the app will look like before tapping.
+ *
+ * Tapping calls `setAccent`, which repaints every widget already on screen and
+ * writes the choice to `localStorage`, so the next visit opens in the same color.
+ * With `surfaces: true` the tap lays the family over the page as well — background,
+ * panels, cards and hairlines all read off the same ramp — so the picker chooses a
+ * *theme* and not only a brand color. The picker subscribes to the theme, so a
+ * toggle somewhere else on the screen moves the selection here without this widget
+ * being asked.
+ */
+import { WidgetFactory } from "../widget-factory/index.js";
+import { Text } from "./Text.js";
+import { Icon } from "./Icon.js";
+import {
+  colors,
+  getAccent,
+  getAccentSurfaces,
+  setAccent,
+  listAccents,
+  subscribeTheme,
+} from "../utils/themes.js";
+import { readableInk } from "../utils/readableInk.js";
+import { composeUpdate } from "../utils/composeUpdate.js";
+import { TAP_MINIMUM, LABEL_TEXT, PILL } from "../tools/scale.js";
+
+/**
+ * @param {Object} props
+ * @returns {HTMLElement} The picker's root row.
+ */
+export const ThemePicker = (props = {}) => {
+  const {
+    accents = listAccents(),
+    size = TAP_MINIMUM,
+    showLabels = false,
+    label = "Accent color",
+    disabled = false,
+    surfaces = false,
+    onChange,
+    ...rest
+  } = props;
+
+  // What the cells are built from, and what a rebuild replaces. Reading these from
+  // the closure instead of the destructured props is what lets `update()` change
+  // the list: a cell built at construction time would keep painting the family it
+  // was born with.
+  let choices = accents;
+  let labelled = showLabels;
+  let off = disabled;
+  // Whether a tap lays the family over the page too, or only over the brand.
+  let tinted = surfaces;
+
+  // The diagonal split. `135deg` runs from the top-left corner, so the first stop
+  // owns the half a reader's eye reaches first — which is the light theme, the one
+  // a picker is usually opened under.
+  const swatchPaint = (accent) =>
+    `linear-gradient(135deg, ${accent.light} 0 50%, ${accent.dark} 50% 100%)`;
+
+  // The rim is the only thing that says "this one is on", so it is the one thing
+  // that must not be a color nobody can see: `colors.border` measures 1.3:1 on
+  // white and 1.2:1 on a dark card. An unselected swatch wears `gray500` — 3:1 on
+  // both surfaces, the same choice `Checkbox` makes for an empty box — and the
+  // selected one wears the page's own ink, the strongest value the theme has. The
+  // tick badge is ink too, and `readableInk` picks whichever of black and white
+  // reads on it, so the selected state is unmistakable without spending the accent
+  // on it — which rule 28 forbids anyway.
+  const rimFor = (selected) =>
+    selected ? colors.text : off ? colors.border : colors.gray500;
+
+  const cells = [];
+
+  const paintCell = (cell, selected) => {
+    cell.swatch.style.border = `2px solid ${rimFor(selected)}`;
+    cell.badge.style.display = selected ? "flex" : "none";
+    cell.root.setAttribute("aria-checked", String(selected));
+  };
+
+  const paintAll = () => {
+    const active = getAccent();
+    cells.forEach((cell) => paintCell(cell, cell.accent.id === active));
+  };
+
+  const buildCell = (accent) => {
+    const tickSize = Math.max(14, Math.round(size * 0.42));
+
+    // The tick only ever paints on its own badge, so the pair it has to clear is
+    // badge ink on badge plate — a value this file controls, not a user's color.
+    const badge = WidgetFactory({
+      tag: "span",
+      display: "none",
+      alignItems: "center",
+      justifyContent: "center",
+      width: tickSize,
+      height: tickSize,
+      borderRadius: PILL,
+      backgroundColor: colors.text,
+      child: Icon({
+        name: "check",
+        size: Math.max(10, Math.round(size * 0.28)),
+        color: readableInk(colors.text, colors.onPrimary),
+      }),
+    });
+
+    const swatch = WidgetFactory({
+      tag: "span",
+      width: size,
+      height: size,
+      gradient: swatchPaint(accent),
+      border: `2px solid ${rimFor(false)}`,
+      borderRadius: 8,
+      boxSizing: "border-box",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      flexShrink: 0,
+      transition: "border-color 0.2s ease",
+      child: badge,
+    });
+
+    const root = WidgetFactory({
+      // The square is a `span` inside a row, so nothing here is a radio unless the
+      // widget says so. `role` reaches the factory before `applyEffects`, which is
+      // what keeps the engine from labelling the control `button`.
+      role: "radio",
+      "aria-checked": "false",
+      "aria-label": accent.label,
+      widgetName: "ThemePicker",
+      display: "inline-flex",
+      flexDirection: "column",
+      alignItems: "center",
+      gap: labelled ? 4 : undefined,
+      minWidth: size,
+      minHeight: size,
+      padding: labelled ? 4 : 0,
+      cursor: off ? "not-allowed" : "pointer",
+      opacity: off ? 0.5 : 1,
+      // Pressing a caption must not scale the caption: the root is the hit box and
+      // the square is the thing that reads as selected.
+      disableTransform: labelled || undefined,
+      child: labelled
+        ? [
+            swatch,
+            Text({
+              text: accent.label,
+              size: LABEL_TEXT,
+              color: off ? colors.textDisabled : colors.textSecondary,
+            }),
+          ]
+        : swatch,
+    });
+
+    const cell = { accent, root, swatch, badge };
+
+    if (off) {
+      root.setAttribute("aria-disabled", "true");
+    } else {
+      // Routed through the factory rather than assigned to `onclick`: `applyEffects`
+      // is what gives this cell Enter, Space and a Tab stop, and it only sees
+      // handlers that arrive as props.
+      root.update({
+        onPress: () => {
+          // Re-tapping the ticked cell still has to work when the cell changed
+          // meaning: the same id paints brand-only or a whole theme depending on
+          // `surfaces`, and that flag can arrive through `update()`.
+          if (getAccent() === accent.id && getAccentSurfaces() === tinted) return;
+          setAccent(accent.id, { surfaces: tinted });
+          if (onChange) onChange(accent.id);
+        },
+      });
+    }
+
+    return cell;
+  };
+
+  const rebuild = () => {
+    cells.forEach((cell) => cell.root.remove());
+    cells.length = 0;
+    choices.forEach((accent) => {
+      const cell = buildCell(accent);
+      cells.push(cell);
+      group.appendChild(cell.root);
+    });
+    paintAll();
+  };
+
+  const group = WidgetFactory({
+    widgetName: "ThemePicker",
+    // A row of colored squares is not a control. Named, it is one, and the twelve
+    // radios inside it are read as options of a single question.
+    role: "radiogroup",
+    "aria-label": label,
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "flex-start",
+    gap: 8,
+    ...rest,
+  });
+
+  rebuild();
+
+  // The selection is the theme's state, not this widget's. A toggle in the app bar,
+  // an OS flip, or a `setAccent` from a settings screen all move what is checked
+  // here, and none of them can be reached by a prop.
+  const unsubscribe = subscribeTheme(paintAll);
+  group.onUnmount(() => {
+    unsubscribe();
+    cells.length = 0;
+  });
+
+  composeUpdate(
+    group,
+    ["accents", "showLabels", "label", "disabled", "surfaces"],
+    (next) => {
+      if (next.label !== undefined) group.setAttribute("aria-label", next.label);
+      if (next.accents !== undefined) choices = next.accents;
+      if (next.showLabels !== undefined) labelled = next.showLabels;
+      if (next.disabled !== undefined) off = next.disabled;
+      if (next.surfaces !== undefined) tinted = next.surfaces;
+      if (next.accents || next.showLabels || next.disabled || next.surfaces) rebuild();
+    },
+  );
+
+  return group;
+};
+
+export default ThemePicker;

package/src/widgets/TreeView.js

@@ -13,7 +13,8 @@ export const TreeView = (props) => {
     nodes = [],
     onSelect,
     onToggle,
-    /** @deprecated Use onPress instead */
+    // The tree's own name for the selection callback. `onPress` is the
+    // framework-wide spelling and works here too — it receives the node.
     onPress: onPressProp,
     expandedNodes = [],
     indent = 16,

package/src/widgets/index.js

@@ -37,9 +37,11 @@ export { DroppBox } from "./DroppBox.js";
 export { DataTable } from "./DataTable.js";
 export { Carousel } from "./Carousel.js";
 export { Tooltip } from "./Tooltip.js";
+export { Menu } from "./Menu.js";
 export { Pagination } from "./Pagination.js";
 export { TreeView } from "./TreeView.js";
 export { Stepper } from "./Stepper.js";
+export { ThemePicker } from "./ThemePicker.js";
 export { Skeleton } from "./Skeleton.js";
 export { Chart } from "./Chart.js";
 export { QRCode } from "./QRCode.js";

package/docs/CONTRIBUTING.md

@@ -1,156 +0,0 @@
-# Contributing to FletBox
-
-Thank you for helping improve FletBox. The project is designed to stay friendly to developers, so contributions should keep the API readable, predictable, and practical.
-
-## Project areas
-
-```text
-src/core/          Runtime, mounting, PWA, and HMR
-src/widgets/       UI widgets
-src/widget-factory/Widget creation and prop processing
-src/navigations/   Scaffold, drawer, tabs, and router
-src/services/      Browser storage and HTTP helpers
-src/tools/         State and general-purpose tools
-src/utils/         Themes, parsing, effects, units, and validation
-bin/               CLI and project generators
-docs/              User and API documentation
-```
-
-## Before changing code
-
-1. Read the owning module and its nearest tests or examples.
-2. Check `src/index.js` to understand the public export.
-3. Check `src/index.d.ts` when changing public types.
-4. Search for existing aliases and related widgets.
-5. Keep unrelated refactors out of the change.
-
-## Adding a widget
-
-A widget should normally include:
-
-- A file under `src/widgets/`.
-- An export in `src/widgets/index.js`.
-- An export in `src/index.js`.
-- A prop interface and function declaration in `src/index.d.ts`.
-- Basic, everyday, and full examples.
-- A documentation page under `docs/widget/`.
-- Accessibility notes when it is interactive.
-- Cleanup for timers, listeners, observers, and subscriptions.
-
-Use the existing `WidgetFactory` patterns instead of creating a second rendering system.
-
-## Adding a prop
-
-When adding a public prop:
-
-1. Implement it in the widget.
-2. Add its TypeScript type.
-3. Add its default value and behavior documentation.
-4. Add an example that proves the behavior.
-5. Check whether it should have a friendly alias.
-6. Test both the preferred name and aliases when aliases are intentional.
-
-FletBox supports developer-friendly aliases, but each alias must have one clear meaning.
-
-## Documentation pattern
-
-Widget pages follow this structure:
-
-1. Overview.
-2. Learn it in one minute.
-3. When to use.
-4. Common props.
-5. Full prop list.
-6. How props work.
-7. Example usage.
-8. Basic, everyday, and full examples.
-9. Common layout and styling examples.
-10. Beginner tips.
-11. Common mistakes.
-12. Behavior notes.
-13. Accessibility.
-14. Related widgets.
-
-Regenerate widget documentation with:
-
-```bash
-python3 scripts/generate_widget_docs.py
-```
-
-The generator uses `src/index.d.ts` and the supplied snippet library as references.
-
-## Runtime and types must agree
-
-A public API is not complete until these three surfaces agree:
-
-```text
-runtime implementation
-src/index.js exports
-src/index.d.ts declarations
-```
-
-If a function is declared but not exported, or exported but not typed, do not ship it as stable: fix the source of truth.
-
-`npm test` enforces this with `scripts/check-api-surface.mjs`. It imports `src/index.js` for real, so it fails when a runtime export has no declaration, when a declared value does not exist at runtime, when an `interface`/`type` is not `export`ed (a consumer could not `import type` it), or when the barrel re-exports a name that no longer exists. It also fails when the package stops being importable in Node, so never touch `window` / `document` at module scope — guard with `typeof window !== "undefined"`.
-
-## Cleanup rules
-
-Components that register resources must release them:
-
-- `window` and `document` listeners.
-- Timers and animation frames.
-- `ResizeObserver` and `MutationObserver`.
-- Router subscriptions.
-- Storage subscriptions.
-- WebSocket connections.
-
-Use the widget cleanup lifecycle when available.
-
-## Validation checklist
-
-Before opening a pull request:
-
-```bash
-npm test
-node --check path/to/changed-file.js
-python3 -m py_compile scripts/generate_widget_docs.py
-python3 scripts/generate_widget_docs.py
-```
-
-`npm test` runs the two static checkers described above — the widget-structure contract (`scripts/check-widgets.mjs`) and the API surface coupling (`scripts/check-api-surface.mjs`) — and must pass before a pull request.
-
-The behavioral tests are dependency-free browser harnesses in `tests/`. Serve the repo with the dev server (`npm run dev` or `node bin/cli.js run-spa`), then open:
-
-- `/tests/index.html` — widget-factory regression contract
-- `/tests/smoke.html` — instantiates every widget
-- `/tests/doccheck.html` — chapters 1-2 documented behavior
-- `/tests/doccheck-all.html` — chapters 3-7 documented behavior
-- `/tests/propscan.html` — custom-prop scanner
-
-Each harness writes a global (`window.__TESTS`, `window.__SMOKE`, `window.__DOCCHECK`) and must pass with 0 failures.
-
-Also verify the feature in a real browser when it changes DOM behavior. For build changes, run:
-
-```bash
-npm run build
-```
-
-For CLI changes, test:
-
-```bash
-node bin/cli.js --help
-node bin/cli.js --version
-```
-
-## Pull request guidance
-
-A good pull request explains:
-
-- What user problem it solves.
-- Which files changed.
-- Which public API changed.
-- Whether types and docs were updated.
-- Which commands or tests were run.
-- Any remaining compatibility or migration concern.
-
-Avoid committing generated output, secrets, local databases, APKs, logs, or credentials.