flet-box 1.1.0 → 1.1.2

package/src/tools/fonts.js

@@ -0,0 +1,99 @@
+// src/tools/fonts.js
+// Webfont loading, so a `fontFamily` prop has something to name.
+
+/**
+ * `fontFamily` is a CSS family name; if the bytes of that face are not on the
+ * machine, the browser silently paints its fallback and the app ships a typeface
+ * nobody chose. This module is the missing half: ask for the family, get a
+ * promise that settles when the request is done, and set the prop from it.
+ *
+ * One thing this cannot promise: a webfont is a network request. A self-hosted
+ * same-origin stylesheet survives an offline launch; a provider URL does not.
+ * `loadFont` therefore never fails a screen — it resolves `false` when the face
+ * could not be had, and the app keeps its fallback.
+ */
+
+/** @type {Map<string, Promise<boolean>>} One request per family, however many callers ask. */
+const loading = new Map();
+
+const toCssTime = (weights) => weights.map((weight) => Number(weight) || 0).join(";");
+
+const googleUrl = (family, weights, display) =>
+  `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}${
+    weights.length ? `:wght@${toCssTime(weights)}` : ""
+  }&display=${display}`;
+
+const appendLink = (rel, href, attributes = {}) => {
+  const link = document.createElement("link");
+  link.rel = rel;
+  if (href) link.href = href;
+  for (const [name, value] of Object.entries(attributes)) link.setAttribute(name, value);
+  document.head.appendChild(link);
+  return link;
+};
+
+// A cross-origin stylesheet wants its origin warm before the request, or the face
+// arrives a round trip late. Once per origin: every family on the same host would
+// otherwise add its own pair.
+const preconnect = (href) => {
+  if (document.head.querySelector(`link[rel="preconnect"][href="${href}"]`)) return;
+  appendLink("preconnect", href, { crossorigin: "anonymous" });
+};
+
+/**
+ * Load a webfont family.
+ *
+ * @param {string} family - The CSS family name, e.g. `"Inter"`.
+ * @param {object} [options]
+ * @param {number[]} [options.weights] - Weights to fetch (`[400, 600]`). A Google
+ *   family with no weight list arrives at 400 only, which is a face that cannot
+ *   carry a heading.
+ * @param {string} [options.url] - A stylesheet to load instead of Google's: a
+ *   self-hosted `@font-face` file, or any other provider.
+ * @param {"auto" | "block" | "swap" | "fallback" | "optional"} [options.display="swap"]
+ *   CSS `font-display`, Google URLs only. `swap` paints the fallback at once and
+ *   replaces it when the face lands; `optional` may skip it on a slow connection.
+ * @returns {Promise<boolean>} `true` when the stylesheet landed, `false` when it
+ *   did not — and an immediate `false` where there is no document to write to, so
+ *   importing this module in Node never throws.
+ */
+export const loadFont = (family, options = {}) => {
+  if (typeof document === "undefined" || !family) return Promise.resolve(false);
+  const key = String(family);
+  if (loading.has(key)) return loading.get(key);
+
+  const run = new Promise((resolve) => {
+    const { weights = [], url, display = "swap" } = options;
+    const href = url || googleUrl(key, weights, display);
+    if (!url) {
+      preconnect("https://fonts.googleapis.com");
+      preconnect("https://fonts.gstatic.com");
+    }
+
+    const link = appendLink("stylesheet", href, { "data-fb-font": key });
+    // The face itself still has to paint; `document.fonts.ready` is the point
+    // where the engine has finished everything it started, loaded or not.
+    const settle = () => {
+      if (typeof document.fonts?.ready?.then !== "function") return resolve(true);
+      document.fonts.ready.then(() => resolve(true), () => resolve(false));
+    };
+    link.addEventListener("load", settle);
+    link.addEventListener("error", () => resolve(false));
+  });
+
+  loading.set(key, run);
+  return run;
+};
+
+/**
+ * Wait for every face the document has already started, without asking for one.
+ * Use it before a canvas paint or an export, where text that reflows after the
+ * drawing is a visible bug.
+ *
+ * @returns {Promise<boolean>} `true` when the font engine settled, `false` where
+ *   there is none.
+ */
+export const fontsReady = () => {
+  if (typeof document === "undefined" || !document.fonts) return Promise.resolve(false);
+  return document.fonts.ready.then(() => true, () => false);
+};

package/src/tools/index.js

@@ -4,6 +4,16 @@ export { shuffle, reverse, sort, unique, chunk } from "./array.js";
 export { border } from "./border.js";
 export { clipboard } from "./clipboard.js";
 export { color } from "./color.js";
+export {
+  BREAKPOINTS,
+  BREAKPOINT_NAMES,
+  breakpointForWidth,
+  currentBreakpoint,
+  atLeast,
+  pick,
+  onBreakpointChange,
+} from "./breakpoints.js";
+export { loadFont, fontsReady } from "./fonts.js";
 export { createList } from "./createList.js";
 export { delay, withMinDelay, retry } from "./delay.js";
 export { device } from "./device.js";
@@ -36,8 +46,71 @@ export {
   upperCase,
   reverseString,
   truncate,
+  startsWith,
+  endsWith,
+  includes,
+  split,
+  join,
+  trim,
 } from "./string.js";
-export { formatDate, relativeTime, sleep, now } from "./time.js";
+export {
+  // units
+  seconds,
+  minutes,
+  hours,
+  days,
+  weeks,
+  months,
+  years,
+  // current
+  now,
+  today,
+  yesterday,
+  tomorrow,
+  // info
+  dayOfWeek,
+  monthName,
+  isToday,
+  isYesterday,
+  isTomorrow,
+  isWeekend,
+  isLeapYear,
+  // format
+  formatDate,
+  formatDateLong,
+  formatDateShort,
+  formatTime,
+  formatTimeAmPm,
+  // parse & diff
+  parseDate,
+  dateDiff,
+  // manipulate
+  addDays,
+  addHours,
+  addMinutes,
+  addSeconds,
+  subtractDays,
+  subtractHours,
+  subtractMinutes,
+  subtractSeconds,
+  // relative
+  timeAgo,
+  relativeTime,
+  timeAgoLocale,
+  // wait
+  waitFor,
+  wait,
+  sleep,
+  waitUntil,
+  waitForElement,
+  // timer & interval
+  timer,
+  every,
+  everySecond,
+  everyMinute,
+  everyHour,
+  everyDay,
+} from "./time.js";
 export { transform } from "./transform.js";
 export { transition } from "./transition.js";
 export { useState, useWatchState } from "./useState.js";

package/src/tools/margin.js

@@ -1,4 +1,5 @@
 // tools/margin.js
+import { boxEdges } from "../helpers/boxEdges.js";
 
 /**
  * Generates a CSS `margin` shorthand string from a number, a plain CSS string,
@@ -14,6 +15,9 @@
  * - `vertical` — applies to `top` and `bottom`.
  * - `top`, `right`, `bottom`, `left` — individual side overrides.
  *
+ * The grammar is shared with `padding()` and lives in `helpers/boxEdges.js`, so
+ * the two cannot disagree about how a side is resolved.
+ *
  * @param {number|string|Object} value
  *   A number (converted to `px`), a raw CSS string, or an options object.
  * @returns {string} CSS margin value.
@@ -26,68 +30,6 @@
  * margin({ left: 20, right: 20 })                   // "0px 20px"
  * margin({ top: 10, bottom: 10 })                   // "10px 0px"
  */
-export const margin = (value) => {
-  // A number or raw CSS string applies uniformly to all sides
-  if (typeof value === "number" || typeof value === "string") {
-    const px = typeof value === "number" ? `${value}px` : value;
-    return px;
-  }
-
-  // Object form — resolve each side independently
-  if (typeof value === "object") {
-    const top =
-      value.top !== undefined
-        ? value.top
-        : value.vertical !== undefined
-          ? value.vertical
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const right =
-      value.right !== undefined
-        ? value.right
-        : value.horizontal !== undefined
-          ? value.horizontal
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const bottom =
-      value.bottom !== undefined
-        ? value.bottom
-        : value.vertical !== undefined
-          ? value.vertical
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const left =
-      value.left !== undefined
-        ? value.left
-        : value.horizontal !== undefined
-          ? value.horizontal
-          : value.all !== undefined
-            ? value.all
-            : 0;
-
-    const topPx = typeof top === "number" ? `${top}px` : top;
-    const rightPx = typeof right === "number" ? `${right}px` : right;
-    const bottomPx = typeof bottom === "number" ? `${bottom}px` : bottom;
-    const leftPx = typeof left === "number" ? `${left}px` : left;
-
-    // All sides equal — return a single value
-    if (topPx === rightPx && rightPx === bottomPx && bottomPx === leftPx) {
-      return topPx;
-    }
-
-    // Only horizontal and vertical differ — use two-value shorthand
-    if (topPx === bottomPx && rightPx === leftPx) {
-      return `${topPx} ${rightPx}`;
-    }
-
-    // Full four-value form
-    return `${topPx} ${rightPx} ${bottomPx} ${leftPx}`;
-  }
-
-  return "0px";
-};
+export const margin = boxEdges;
 
 export default margin;

package/src/tools/padding.js

@@ -1,4 +1,5 @@
 // tools/padding.js
+import { boxEdges } from "../helpers/boxEdges.js";
 
 /**
  * Generates a CSS `padding` shorthand string from a number, a plain CSS string,
@@ -14,6 +15,9 @@
  * - `vertical` — applies to `top` and `bottom`.
  * - `top`, `right`, `bottom`, `left` — individual side overrides.
  *
+ * The grammar is shared with `margin()` and lives in `helpers/boxEdges.js`, so
+ * the two cannot disagree about how a side is resolved.
+ *
  * @param {number|string|Object} value
  *   A number (converted to `px`), a raw CSS string, or an options object.
  * @returns {string} CSS padding value.
@@ -26,68 +30,6 @@
  * padding({ left: 20, right: 20 })                   // "0px 20px"
  * padding({ top: 10, bottom: 10 })                   // "10px 0px"
  */
-export const padding = (value) => {
-  // A number or raw CSS string applies uniformly to all sides
-  if (typeof value === "number" || typeof value === "string") {
-    const px = typeof value === "number" ? `${value}px` : value;
-    return px;
-  }
-
-  // Object form — resolve each side independently
-  if (typeof value === "object") {
-    const top =
-      value.top !== undefined
-        ? value.top
-        : value.vertical !== undefined
-          ? value.vertical
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const right =
-      value.right !== undefined
-        ? value.right
-        : value.horizontal !== undefined
-          ? value.horizontal
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const bottom =
-      value.bottom !== undefined
-        ? value.bottom
-        : value.vertical !== undefined
-          ? value.vertical
-          : value.all !== undefined
-            ? value.all
-            : 0;
-    const left =
-      value.left !== undefined
-        ? value.left
-        : value.horizontal !== undefined
-          ? value.horizontal
-          : value.all !== undefined
-            ? value.all
-            : 0;
-
-    const topPx = typeof top === "number" ? `${top}px` : top;
-    const rightPx = typeof right === "number" ? `${right}px` : right;
-    const bottomPx = typeof bottom === "number" ? `${bottom}px` : bottom;
-    const leftPx = typeof left === "number" ? `${left}px` : left;
-
-    // All sides equal — return a single value
-    if (topPx === rightPx && rightPx === bottomPx && bottomPx === leftPx) {
-      return topPx;
-    }
-
-    // Only horizontal and vertical differ — use two-value shorthand
-    if (topPx === bottomPx && rightPx === leftPx) {
-      return `${topPx} ${rightPx}`;
-    }
-
-    // Full four-value form
-    return `${topPx} ${rightPx} ${bottomPx} ${leftPx}`;
-  }
-
-  return "0px";
-};
+export const padding = boxEdges;
 
 export default padding;

package/src/tools/print.js

@@ -58,12 +58,4 @@ export const print = (message, type = "log", options = {}) => {
   console[config.method](finalMessage);
 };
 
-// Shorthand aliases (uncomment to enable individual exports):
-// export const log = (msg) => print(msg, "log");
-// export const warn = (msg) => print(msg, "warn");
-// export const error = (msg) => print(msg, "error");
-// export const info = (msg) => print(msg, "info");
-// export const success = (msg) => print(msg, "success");
-// export const debug = (msg) => print(msg, "debug");
-
 export default print;

package/src/tools/scale.js

@@ -28,8 +28,15 @@ export const PILL = 999;
 /** The 8-based rhythm, with the two steps a real layout needs (18 for field text, 96 for hero gutters). */
 export const SPACING_SCALE = new Set([0, 4, 8, 12, 16, 18, 24, 32, 40, 48, 64, 96]);
 
-/** Corner radii. `999` is a pill, `0` a flush edge — both are decisions, not omissions. */
-export const RADIUS_SCALE = new Set([0, 4, 8, 12, 16, PILL]);
+/**
+ * Corner radii. `999` is a pill, `0` a flush edge — both are decisions, not omissions.
+ *
+ * The scale reaches 24 on purpose. The nesting rule (`outer = inner + padding`) is
+ * arithmetic, not taste: a 16-radius tile inside 8 of padding *needs* a 24 card, so a
+ * scale that stops at 16 makes the correct radius illegal and pushes the screen to a
+ * pill it did not ask for.
+ */
+export const RADIUS_SCALE = new Set([0, 4, 8, 12, 16, 20, 24, PILL]);
 
 /** Type sizes. Two steps per jump: a 15 next to a 16 reads as a mistake, not as hierarchy. */
 export const TYPE_SCALE = new Set([12, 14, 16, 18, 24, 32, 40, 48]);

package/src/tools/time.js

@@ -6,6 +6,35 @@
  * ============================================================
  */
 
+// ========== INPUT ==========
+
+/**
+ * Turns any accepted date input into a `Date`, reading a bare calendar date as a
+ * calendar date.
+ *
+ * `new Date("2024-01-15")` is not January the fifteenth: the spec parses a
+ * date-only string as UTC midnight, and every getter then reads it back in the
+ * local zone. West of Greenwich that is the fourteenth, which is how
+ * `isToday(today())` came back `false` and `dayOfWeek("2024-01-15")` said
+ * "Sunday" — the module disagreeing with itself, on a date the module produced.
+ *
+ * A value that carries a time, an offset or a `Z` is a timestamp, not a day, and
+ * `new Date` already places it; only `YYYY-MM-DD` needs the local reading.
+ *
+ * @param {Date|number|string} date - Any value a time helper accepts.
+ * @returns {Date}
+ */
+const toDate = (date) => {
+  if (typeof date === "string") {
+    const calendarDay = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (calendarDay) {
+      const [, year, month, day] = calendarDay;
+      return new Date(Number(year), Number(month) - 1, Number(day));
+    }
+  }
+  return new Date(date);
+};
+
 // ========== TIME UNITS ==========
 
 /**
@@ -100,7 +129,7 @@ export const dayOfWeek = (date) => {
     "Friday",
     "Saturday",
   ];
-  return days[new Date(date).getDay()];
+  return days[toDate(date).getDay()];
 };
 
 /**
@@ -123,7 +152,7 @@ export const monthName = (date) => {
     "November",
     "December",
   ];
-  return months[new Date(date).getMonth()];
+  return months[toDate(date).getMonth()];
 };
 
 /**
@@ -152,7 +181,7 @@ export const isTomorrow = (date) => formatDate(date) === tomorrow();
  * @param {Date|number|string} date - Date to check.
  * @returns {boolean}
  */
-export const isWeekend = (date) => [0, 6].includes(new Date(date).getDay());
+export const isWeekend = (date) => [0, 6].includes(toDate(date).getDay());
 
 /**
  * Returns `true` if the given year is a leap year.
@@ -179,7 +208,7 @@ export const isLeapYear = (year) => {
  * formatDate(new Date(), "YYYY-MM-DD HH:mm:ss") // "2024-01-15 09:30:00"
  */
 export const formatDate = (date, format = "YYYY-MM-DD") => {
-  const d = new Date(date);
+  const d = toDate(date);
   const year = d.getFullYear();
   const month = String(d.getMonth() + 1).padStart(2, "0");
   const day = String(d.getDate()).padStart(2, "0");
@@ -204,7 +233,7 @@ export const formatDate = (date, format = "YYYY-MM-DD") => {
  * @returns {string} Long date string, e.g. `"Monday, January 15, 2024"`.
  */
 export const formatDateLong = (date, locale = "en-US") => {
-  return new Date(date).toLocaleDateString(locale, {
+  return toDate(date).toLocaleDateString(locale, {
     weekday: "long",
     year: "numeric",
     month: "long",
@@ -220,7 +249,7 @@ export const formatDateLong = (date, locale = "en-US") => {
  * @returns {string} Short date string, e.g. `"Jan 15, 2024"`.
  */
 export const formatDateShort = (date, locale = "en-US") => {
-  return new Date(date).toLocaleDateString(locale, {
+  return toDate(date).toLocaleDateString(locale, {
     year: "numeric",
     month: "short",
     day: "numeric",
@@ -240,7 +269,7 @@ export const formatTime = (date) => formatDate(date, "HH:mm:ss");
  * @returns {string} Time string, e.g. `"02:05:30 PM"`.
  */
 export const formatTimeAmPm = (date) => {
-  const d = new Date(date);
+  const d = toDate(date);
   let hours = d.getHours();
   const ampm = hours >= 12 ? "PM" : "AM";
   hours = hours % 12 || 12;
@@ -304,7 +333,7 @@ export const parseDate = (str, format = "YYYY-MM-DD") => {
  * dateDiff("2024-01-01", "2024-01-15", "days") // 14
  */
 export const dateDiff = (date1, date2, unit = "days") => {
-  const diff = Math.abs(new Date(date1) - new Date(date2));
+  const diff = Math.abs(toDate(date1) - toDate(date2));
   const units = {
     milliseconds: 1,
     seconds: 1000,
@@ -322,12 +351,24 @@ export const dateDiff = (date1, date2, unit = "days") => {
 
 /**
  * Adds `n` days to a date and returns a new `Date`.
+ *
+ * Whole days are counted on the calendar, not in milliseconds: a 24h step lands
+ * an hour off the wall clock either side of a DST change, so
+ * `addDays("2024-10-26", 7)` in Madrid would print November 1. A fractional `n`
+ * is elapsed time and keeps the millisecond walk.
+ *
  * @param {Date|number|string} date - Base date.
  * @param {number} n - Number of days to add (negative to subtract).
  * @returns {Date}
  */
-export const addDays = (date, n) =>
-  new Date(new Date(date).getTime() + days(n));
+export const addDays = (date, n) => {
+  const d = toDate(date);
+  if (Number.isInteger(n)) {
+    d.setDate(d.getDate() + n);
+    return d;
+  }
+  return new Date(d.getTime() + days(n));
+};
 
 /**
  * Adds `n` hours to a date and returns a new `Date`.
@@ -336,7 +377,7 @@ export const addDays = (date, n) =>
  * @returns {Date}
  */
 export const addHours = (date, n) =>
-  new Date(new Date(date).getTime() + hours(n));
+  new Date(toDate(date).getTime() + hours(n));
 
 /**
  * Adds `n` minutes to a date and returns a new `Date`.
@@ -345,7 +386,7 @@ export const addHours = (date, n) =>
  * @returns {Date}
  */
 export const addMinutes = (date, n) =>
-  new Date(new Date(date).getTime() + minutes(n));
+  new Date(toDate(date).getTime() + minutes(n));
 
 /**
  * Adds `n` seconds to a date and returns a new `Date`.
@@ -354,7 +395,7 @@ export const addMinutes = (date, n) =>
  * @returns {Date}
  */
 export const addSeconds = (date, n) =>
-  new Date(new Date(date).getTime() + seconds(n));
+  new Date(toDate(date).getTime() + seconds(n));
 
 /**
  * Subtracts `n` days from a date and returns a new `Date`.
@@ -402,7 +443,7 @@ export const subtractSeconds = (date, n) => addSeconds(date, -n);
  */
 export const timeAgo = (date) => {
   const now = new Date();
-  const d = new Date(date);
+  const d = toDate(date);
   const diff = Math.floor((now - d) / 1000);
 
   const intervals = [
@@ -439,7 +480,7 @@ export const relativeTime = timeAgo;
  * timeAgoLocale(Date.now() - 3600000, "es") // "hace 1 hora"
  */
 export const timeAgoLocale = (date, locale = "en") => {
-  const d = new Date(date);
+  const d = toDate(date);
   const now = new Date();
   const diff = Math.floor((now - d) / 1000);
 

package/src/tools/useState.js

@@ -3,7 +3,6 @@ import { saveRam, getRam, subscribeRam } from "../services/RamStore.js";
 import {
   createReactiveValue,
   isStructuralRead,
-  resetStructuralReads,
 } from "../widget-factory/reactiveValue.js";
 
 // Store callbacks for each state key
@@ -57,7 +56,7 @@ const ensureRamDispatcher = () => {
   if (ramDispatcherReady) return;
   ramDispatcherReady = true;
 
-  const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
+  subscribeRam((changedKey, newValue, oldValue) => {
     const callbacks = subscribers.get(changedKey);
     // A key nobody ever passed to `useState` has no listeners: ignore it.
     if (!callbacks) return;
@@ -83,11 +82,6 @@ const ensureRamDispatcher = () => {
     // list): the surgical patch above cannot change what the component computes.
     if (handled === 0 || isStructuralRead(changedKey)) triggerRender();
   });
-
-  if (typeof window !== "undefined") {
-    if (!window._useStateCleanups) window._useStateCleanups = [];
-    window._useStateCleanups.push(unsubscribe);
-  }
 };
 
 /**
@@ -251,53 +245,6 @@ export const useWatchState = (key, callback) => {
   };
 };
 
-/**
- * Cleans up all state subscriptions, widget registrations, and pending render
- * timers. Should be called during hot-reload to reset the module to a clean state.
- *
- * @returns {void}
- */
-export const cleanupUseState = () => {
-  if (window._useStateCleanups) {
-    window._useStateCleanups.forEach((cleanup) => {
-      if (typeof cleanup === "function") cleanup();
-    });
-    window._useStateCleanups = [];
-  }
-  subscribers.clear();
-  widgetsByKey.clear();
-  resetStructuralReads();
-  // The dispatcher was unsubscribed above, so a later call must reinstall it.
-  ramDispatcherReady = false;
-  globalRender = null;
-  if (renderTimeout) clearTimeout(renderTimeout);
-};
-
-/**
- * Returns diagnostic statistics about the current state of the useState module.
- * Useful for debugging subscription leaks or widget registration issues.
- *
- * @returns {{ stateKeys: number, boundWidgets: number, watchers: number, globalRender: boolean }}
- */
-export const getUseStateStats = () => {
-  // `widgetsByKey` maps key -> widget -> prop names, so its size is the number of
-  // watched *keys*, not of widgets. Count one per widget.
-  let boundWidgets = 0;
-  let watchers = 0;
-  widgetsByKey.forEach((perWidget) => {
-    boundWidgets += perWidget.size;
-  });
-  subscribers.forEach((callbacks) => {
-    watchers += callbacks.size;
-  });
-  return {
-    stateKeys: subscribers.size,
-    boundWidgets,
-    watchers,
-    globalRender: !!globalRender,
-  };
-};
-
 // Re-export RamStore functions under convenience aliases
 export {
   saveRam as saveState,