@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/lib/calc.ts

@@ -0,0 +1,309 @@
+/**
+ * A tiny, dependency-free arithmetic evaluator for the numeric input fields.
+ * It lets users type a calculation (e.g. "12.50+3.20" or "100/3") straight into
+ * an amount field, or build one in the calculator popover, and have it resolve
+ * to a number. Deliberately NOT backed by `eval`/`Function` — it's a hand-rolled
+ * tokenizer + recursive-descent parser over a closed grammar (digits, decimals,
+ * `+ - * /`, unary minus, parentheses), so no arbitrary code can run.
+ */
+
+type Token =
+  | { kind: "num"; value: number }
+  | { kind: "op"; value: "+" | "-" | "*" | "/" }
+  | { kind: "lparen" }
+  | { kind: "rparen" };
+
+function tokenize(input: string): Token[] | null {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i];
+    if (ch === " ") {
+      i++;
+      continue;
+    }
+    if (ch === "+" || ch === "-" || ch === "*" || ch === "/") {
+      tokens.push({ kind: "op", value: ch });
+      i++;
+      continue;
+    }
+    if (ch === "(") {
+      tokens.push({ kind: "lparen" });
+      i++;
+      continue;
+    }
+    if (ch === ")") {
+      tokens.push({ kind: "rparen" });
+      i++;
+      continue;
+    }
+    if ((ch >= "0" && ch <= "9") || ch === ".") {
+      let j = i;
+      let dotSeen = false;
+      while (j < input.length && ((input[j] >= "0" && input[j] <= "9") || input[j] === ".")) {
+        if (input[j] === ".") {
+          if (dotSeen) return null; // two dots in one number → invalid
+          dotSeen = true;
+        }
+        j++;
+      }
+      const num = Number(input.slice(i, j));
+      if (!Number.isFinite(num)) return null;
+      tokens.push({ kind: "num", value: num });
+      i = j;
+      continue;
+    }
+    return null; // unknown character
+  }
+  return tokens;
+}
+
+/**
+ * Recursive-descent parse honouring `* /` over `+ -` and left-associativity.
+ * Returns `null` for any malformed input (the `null` sentinel is safe because a
+ * valid result of 0 is distinct from it). Division by zero is treated as invalid.
+ *
+ *   expr   := term (('+' | '-') term)*
+ *   term   := factor (('*' | '/') factor)*
+ *   factor := ('+' | '-') factor | number | '(' expr ')'
+ */
+function parse(tokens: Token[]): number | null {
+  let pos = 0;
+
+  function parseExpr(): number | null {
+    let value = parseTerm();
+    if (value === null) return null;
+    while (pos < tokens.length) {
+      const tok = tokens[pos];
+      if (tok.kind === "op" && (tok.value === "+" || tok.value === "-")) {
+        pos++;
+        const rhs = parseTerm();
+        if (rhs === null) return null;
+        value = tok.value === "+" ? value + rhs : value - rhs;
+      } else break;
+    }
+    return value;
+  }
+
+  function parseTerm(): number | null {
+    let value = parseFactor();
+    if (value === null) return null;
+    while (pos < tokens.length) {
+      const tok = tokens[pos];
+      if (tok.kind === "op" && (tok.value === "*" || tok.value === "/")) {
+        pos++;
+        const rhs = parseFactor();
+        if (rhs === null) return null;
+        if (tok.value === "/") {
+          if (rhs === 0) return null;
+          value = value / rhs;
+        } else {
+          value = value * rhs;
+        }
+      } else break;
+    }
+    return value;
+  }
+
+  function parseFactor(): number | null {
+    const tok = tokens[pos];
+    if (!tok) return null;
+    if (tok.kind === "op" && (tok.value === "+" || tok.value === "-")) {
+      pos++;
+      const operand = parseFactor();
+      if (operand === null) return null;
+      return tok.value === "-" ? -operand : operand;
+    }
+    if (tok.kind === "lparen") {
+      pos++;
+      const inner = parseExpr();
+      if (inner === null) return null;
+      if (tokens[pos]?.kind !== "rparen") return null;
+      pos++;
+      return inner;
+    }
+    if (tok.kind === "num") {
+      pos++;
+      return tok.value;
+    }
+    return null;
+  }
+
+  const result = parseExpr();
+  if (result === null) return null;
+  if (pos !== tokens.length) return null; // leftover tokens → invalid
+  return result;
+}
+
+/** Evaluate an arithmetic string, returning `null` if it isn't a valid sum.
+ * Accepts the on-screen operator glyphs (`× ÷ −`) and comma decimals too. */
+export function evaluateExpression(expr: string): number | null {
+  const normalized = expr
+    .replace(/×/g, "*")
+    .replace(/÷/g, "/")
+    .replace(/[−–—]/g, "-") // unicode minus / en / em dash → ascii
+    .replace(/,/g, ".")
+    .trim();
+  if (normalized === "") return null;
+  const tokens = tokenize(normalized);
+  if (tokens === null || tokens.length === 0) return null;
+  const result = parse(tokens);
+  if (result === null || !Number.isFinite(result)) return null;
+  return result;
+}
+
+/** True when `s` carries arithmetic beyond a single leading minus — i.e. a plain
+ * number (or a lone negative like "-5") is NOT an expression, but "12+5" is.
+ * Used to decide whether a field's text should be evaluated on commit.
+ *
+ * The operator set is the one {@link evaluateExpression} accepts, on-screen glyphs
+ * included: the calculator keypad inserts `× ÷ −`, and a `−` that this said was not
+ * arithmetic went on to be read as a plain number — where the digits-only fallback
+ * in {@link commitExpression} silently ate it, turning "-42−−50" (= 8) into a bare
+ * 8 with no record that a sum had happened at all. */
+export function looksLikeExpression(s: string): boolean {
+  const t = s.trim();
+  if (t === "") return false;
+  if (/^-?\d*[.,]?\d*$/.test(t)) return false; // plain (optionally negative) decimal
+  return /[+\-*/×÷−–—()]/.test(t.replace(/^-/, ""));
+}
+
+/** Render an evaluated number back to a field-friendly string, trimming binary
+ * float noise (so 0.1 + 0.2 reads "0.3", not "0.30000000000000004").
+ *
+ * FIXED notation, always, and that is the whole point of the function rather than a
+ * detail of it. This used to end in `parseFloat(n.toFixed(10)).toString()`, and
+ * `Number.prototype.toString` switches to EXPONENT notation below 1e-6 and at or
+ * above 1e21 — an alphabet containing `e`, `+` and `-`. Neither function that reads a
+ * field's text back accepts it: {@link tokenize} rejects `e` as an unknown character
+ * and {@link sanitizeLive} deletes it. So {@link commitExpression} fell through to
+ * its digits-only cleanup, which stripped the `e` and CONCATENATED the mantissa to
+ * the exponent. A field committed its own output as a different number:
+ *
+ *     "1/10000000"                -> "1e-7"               -> "17"   (AmountInput: "6")
+ *     "999999999999*999999999999" -> "9.99999999998e+23"  -> "9.9999999999823"
+ *
+ * Both controls commit on blur AND on Enter, so Enter-then-click-away was enough on
+ * its own, it was silent, and it was in a money field.
+ *
+ * The invariant, which the test asserts directly rather than by example:
+ * **`commitExpression(formatResult(n))` equals `formatResult(n)` for every finite
+ * `n`.** Anything rendered here has to survive being read back. */
+export function formatResult(n: number): string {
+  if (!Number.isFinite(n)) return "";
+  // At or above 1e21 `toFixed` gives up and hands back `toString`'s exponent form —
+  // but every double that large is an integer, so BigInt renders it exactly.
+  if (Math.abs(n) >= 1e21) return BigInt(n).toString();
+  return trimTrailingZeros(n.toFixed(10));
+}
+
+/** "15.7000000000" -> "15.7", "0.0000000000" -> "0". The ten decimals are where the
+ *  binary float noise gets rounded off; this is only about not showing the padding. */
+function trimTrailingZeros(fixed: string): string {
+  if (!fixed.includes(".")) return fixed;
+  const trimmed = fixed.replace(/0+$/, "").replace(/\.$/, "");
+  // `toFixed` keeps the sign on a magnitude that rounded away to nothing
+  // ("-0.0000000000"); `toString` did not, and "-0" in an amount field is noise.
+  return trimmed === "-0" || trimmed === "" ? "0" : trimmed;
+}
+
+/** The single "on blur / Enter" transform a numeric field applies: evaluate the
+ * text if it's an expression, otherwise normalise it to a bare number string
+ * (comma → dot, dropping stray characters, non-leading minuses and anything after
+ * a second decimal point).
+ *
+ * The last clause is the backstop for Keksdose live #201. A field the user typed in
+ * cannot reach here malformed any more — {@link sanitizeLive} runs on every change,
+ * including a paste — but a value handed in from elsewhere (a recurring rule, an
+ * import, a test) still can, and "1.2.3" is not an expression (no operator), so it
+ * used to fall straight through unchanged and be read as NaN. Here the text is CUT
+ * at the second dot ("1.2") rather than joined ("1.23"): with no keystroke to
+ * ignore there is nothing to say which reading was meant, and the shorter one
+ * cannot silently invent a bigger number. */
+export function commitExpression(raw: string): string {
+  const s = raw.trim();
+  if (looksLikeExpression(s)) {
+    const n = evaluateExpression(s);
+    if (n !== null) return formatResult(n);
+    // Unparseable (e.g. a half-typed "12+"): fall through to a digits-only clean.
+  }
+  // Global, like sanitizeLive's: these two are the two halves of one rule and must
+  // not appear to state it differently. (The `[^0-9.-]` strip on the same line
+  // already ate whatever commas a non-global replace missed, so this changes no
+  // behaviour — it removes the need for the next reader to run it to find that out.)
+  const cleaned = s.replace(/,/g, ".").replace(/[^0-9.-]/g, "").replace(/(?!^)-/g, "");
+  return cleaned.replace(/^(-?\d*\.?\d*).*$/, "$1");
+}
+
+/** The live, per-keystroke transform a numeric field applies: comma → dot and
+ * drop anything that isn't a digit, decimal point, arithmetic operator (incl.
+ * the on-screen `× ÷` glyphs) or paren — so a typed calculation survives
+ * keystroke-by-keystroke but stray characters can't be entered. A lone leading
+ * `-` is kept — in a plain field it is simply a negative amount; in a field whose
+ * caller owns the sign it is read off again by {@link splitLeadingSign}. The text
+ * is resolved to a plain number on blur/Enter via {@link commitExpression}. */
+export function sanitizeLive(raw: string): string {
+  return dropExtraDots(raw.replace(/,/g, ".").replace(/[^0-9.+\-*/×÷()]/g, ""));
+}
+
+/**
+ * At most ONE decimal point per number (Keksdose live #201).
+ *
+ * Per NUMBER, not per string: "1.5+2.5" is a legitimate calculation with two dots
+ * in two operands, so the counter resets at every operator and parenthesis.
+ *
+ * A second dot inside one operand is a **no-op keystroke** — the digits after it
+ * keep landing, so "1.2" + "." + "3" is "1.23". That is what every calculator does
+ * with a repeated decimal point, and it is the only option that does not make the
+ * field feel broken ("my 3 disappeared"). This runs on paste as well as on typing,
+ * so the malformed value never reaches the rest of the app: everything downstream
+ * reads the field with `Number()`, NaN became a silent 0, and on the create form
+ * that 0 was painted with the income green — a figure that was not a number at all
+ * asserting money was coming in.
+ */
+function dropExtraDots(s: string): string {
+  let out = "";
+  let dotInNumber = false;
+  for (const ch of s) {
+    if (ch === ".") {
+      if (dotInNumber) continue;
+      dotInNumber = true;
+    } else if (ch < "0" || ch > "9") {
+      // An operator or a paren ends the current operand.
+      dotInNumber = false;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/** A bare, unsigned amount: digits with at most one decimal separator and nothing
+ *  else — "42", "42.", ".5", "0,5". NOT "" (an empty field has no figure to put a
+ *  sign in front of), not "-42", not "12+5". It is the only shape a DISPLAYED sign
+ *  prefix makes sense in front of; an expression carries its own arithmetic and has
+ *  to survive keystroke-for-keystroke. */
+export function isBareAmount(s: string): boolean {
+  const t = s.trim();
+  return t !== "" && /^\d*[.,]?\d*$/.test(t);
+}
+
+/**
+ * Split a LEADING sign off a plain signed number (Keksdose live #201 rework):
+ * `"-42"` → `{ sign: "-", rest: "42" }`, everything else → `{ sign: "", rest: text }`.
+ *
+ * Only in front of a bare amount, because a minus with arithmetic after it IS
+ * arithmetic: "12-30" is a subtraction, and "-12+5" is -7, not -(12+5). Those come
+ * back untouched and are resolved by {@link commitExpression} on blur — at which
+ * point the RESULT is a plain signed number and this function does get to speak.
+ *
+ * A lone "-" splits (rest ""): the sign is a statement about the direction the
+ * moment it is typed, before any digit exists.
+ */
+export function splitLeadingSign(text: string): { sign: "" | "-" | "+"; rest: string } {
+  const trimmed = text.trimStart();
+  const sign = trimmed.charAt(0);
+  if (sign !== "-" && sign !== "+") return { sign: "", rest: text };
+  const rest = trimmed.slice(1);
+  if (rest !== "" && !isBareAmount(rest)) return { sign: "", rest: text };
+  return { sign, rest };
+}

package/src/lib/cn.ts

@@ -0,0 +1,5 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** Merge class lists with Tailwind conflict resolution (later wins). */
+export const cn = (...inputs: Parameters<typeof clsx>) => twMerge(clsx(inputs));

package/src/lib/dates.ts

@@ -0,0 +1,187 @@
+/**
+ * ISO date helpers, collected from copies that were scattered across the pages.
+ *
+ * **Every "what day is it" helper here reads the LOCAL calendar** — one family, not
+ * two. It used to be two: these all built a local Date and then read it back through
+ * `toISOString()`, which is UTC, so east of Greenwich they all returned YESTERDAY
+ * between local midnight and the UTC rollover. The old module note called that
+ * deliberate and warned against changing it. It was not defensible, and dev#471 is
+ * what it cost:
+ *
+ * > *"Just entered a tx now from scheduled. But it still shows as upcoming. Is there
+ * > a problem with timezones? It is currently 1 o clock middle european summer time."*
+ *
+ * There was: at 01:00 CEST `todayIso()` answered with the 14th, the row the scheduler
+ * had just booked was dated the 15th, and `isUpcoming` compares the two strings — so a
+ * transaction entered a second ago read as one still to come. The same slip moved
+ * `startOfMonthIso()` onto the last day of the PREVIOUS month for an hour every first
+ * of the month, which is a report range nobody would have questioned.
+ *
+ * A calendar day only means anything to the human reading it, and every caller here —
+ * the register's today, the date-range presets, the budget cursor, a new
+ * transaction's default date — is asking that question. There is no caller for whom
+ * "the UTC day" is the right answer; the server compares plain dates with no zone at
+ * all, so sending it the user's local day is also what it wants.
+ */
+
+/** Zero-pad a number to two digits ("3" -> "03"). */
+export function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Today as "YYYY-MM-DD" on the LOCAL calendar (see the module note). */
+export function todayIso(): string {
+  return toLocalIso(new Date());
+}
+
+/** A Date as a local-time "YYYY-MM-DD" string. */
+export function toLocalIso(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/** A Date as a local-time "YYYY-MM" month key. */
+export function monthKey(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}`;
+}
+
+// ---------- Date-range presets + calendar helpers ----------
+// Local-calendar like todayIso (see the module note); used by the data-table date
+// filter and its MiniCalendar. Each one mutates a local Date and must therefore READ
+// it back locally — going out through toISOString() is what shifted every one of
+// these by a day near midnight (dev#471).
+
+/** Today shifted by `days`, as "YYYY-MM-DD". */
+export function shiftIso(days: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() + days);
+  return toLocalIso(d);
+}
+
+/** First day (Monday) of the current week, as "YYYY-MM-DD". */
+export function startOfWeekIso(): string {
+  const d = new Date();
+  const day = d.getDay();
+  const diff = (day + 6) % 7; // monday = 0
+  d.setDate(d.getDate() - diff);
+  return toLocalIso(d);
+}
+
+/** First day of the month `offsetMonths` from now, as "YYYY-MM-DD". */
+export function startOfMonthIso(offsetMonths = 0): string {
+  const d = new Date();
+  d.setDate(1);
+  d.setMonth(d.getMonth() + offsetMonths);
+  return toLocalIso(d);
+}
+
+/** Last day of the month `offsetMonths` from now, as "YYYY-MM-DD". */
+export function endOfMonthIso(offsetMonths = 0): string {
+  const d = new Date();
+  d.setDate(1);
+  d.setMonth(d.getMonth() + offsetMonths + 1);
+  d.setDate(0);
+  return toLocalIso(d);
+}
+
+/** First day of the year `offsetYears` from now, as "YYYY-MM-DD". */
+export function startOfYearIso(offsetYears = 0): string {
+  const d = new Date();
+  d.setMonth(0);
+  d.setDate(1);
+  d.setFullYear(d.getFullYear() + offsetYears);
+  return toLocalIso(d);
+}
+
+/** Last day of the year `offsetYears` from now, as "YYYY-MM-DD". */
+export function endOfYearIso(offsetYears = 0): string {
+  const d = new Date();
+  d.setMonth(11);
+  d.setDate(31);
+  d.setFullYear(d.getFullYear() + offsetYears);
+  return toLocalIso(d);
+}
+
+/** Parse a "YYYY-MM-DD" string to a local-midnight Date, or null if malformed —
+ *  where "malformed" includes a date that does not exist.
+ *
+ *  The falsy check alone was not enough. `new Date(y, m - 1, d)` ROLLS OVER out-of-range
+ *  components rather than refusing them, so "2026-13-45" came back as 2027-02-14 and
+ *  "2026-02-30" as 2026-03-02: a valid-looking Date for a day that never happened. No
+ *  caller could tell — {@link formatIsoDate} blanks only on `null`, so the invented
+ *  date formatted and displayed exactly like a real one.
+ *
+ *  The round-trip is the check: build the Date, then read the components back off it.
+ *  A value that rolled over cannot answer with the numbers it was given. That is the
+ *  same shape {@link sameYmd} already expresses, applied to a Date and its source. */
+export function parseIsoDate(s: string): Date | null {
+  if (!s) return null;
+  const [y, m, d] = s.split("-").map(Number);
+  if (!y || !m || !d) return null;
+  if (!Number.isInteger(y) || !Number.isInteger(m) || !Number.isInteger(d)) return null;
+  const dt = new Date(y, m - 1, d);
+  if (Number.isNaN(dt.getTime())) return null;
+  if (dt.getFullYear() !== y || dt.getMonth() !== m - 1 || dt.getDate() !== d) return null;
+  return dt;
+}
+
+/** Format a "YYYY-MM-DD" string for display in `locale` (empty string when
+ *  unparseable). Defaults to the locale's short numeric date; pass `options` to
+ *  override (e.g. `{ dateStyle: "medium" }`). */
+export function formatIsoDate(
+  iso: string,
+  locale: string,
+  options?: Intl.DateTimeFormatOptions,
+): string {
+  const d = parseIsoDate(iso);
+  return d ? d.toLocaleDateString(locale, options) : "";
+}
+
+/** A "YYYY-MM-DD" string shifted by `days` (negative shifts back), or the input
+ *  unchanged when it isn't a parseable date.
+ *
+ *  Local-time throughout — {@link parseIsoDate} builds a local-midnight Date and
+ *  {@link toLocalIso} reads local components back, so this never slides a day the way
+ *  a `toISOString()` round-trip does west of UTC. */
+export function addDaysIso(iso: string, days: number): string {
+  const d = parseIsoDate(iso);
+  if (!d) return iso;
+  d.setDate(d.getDate() + days);
+  return toLocalIso(d);
+}
+
+/** Whether two Dates fall on the same local calendar day. */
+export function sameYmd(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+export interface DateRangePreset {
+  key: string;
+  from: string;
+  to: string;
+}
+
+/**
+ * The named ranges offered by the data-table date filter (local-calendar, like
+ * {@link todayIso} — see the module note). `key` maps to the consumer's
+ * `table.preset_*` labels.
+ */
+export function dateRangePresets(): DateRangePreset[] {
+  const mondayOffset = (new Date().getDay() + 6) % 7; // monday = 0
+  return [
+    { key: "today", from: todayIso(), to: todayIso() },
+    { key: "yesterday", from: shiftIso(-1), to: shiftIso(-1) },
+    { key: "this_week", from: startOfWeekIso(), to: todayIso() },
+    { key: "last_week", from: shiftIso(-7 - mondayOffset), to: shiftIso(-1 - mondayOffset) },
+    { key: "last_7_days", from: shiftIso(-6), to: todayIso() },
+    { key: "last_30_days", from: shiftIso(-29), to: todayIso() },
+    { key: "this_month", from: startOfMonthIso(0), to: todayIso() },
+    { key: "last_month", from: startOfMonthIso(-1), to: endOfMonthIso(-1) },
+    { key: "last_3_months", from: shiftIso(-90), to: todayIso() },
+    { key: "ytd", from: startOfYearIso(0), to: todayIso() },
+    { key: "last_year", from: startOfYearIso(-1), to: endOfYearIso(-1) },
+  ];
+}

package/src/lib/logger.ts

@@ -0,0 +1,73 @@
+import type { StateCreator, StoreMutatorIdentifier } from "zustand";
+
+import { readStored } from "./safe-storage";
+
+/**
+ * zustand logging middleware.
+ *
+ * Logs every state transition (a store "action") to the DevTools console as a
+ * single grouped line showing the prev/next state. Enabled in dev (Vite
+ * `import.meta.env.DEV`) by default; override at runtime with
+ * `localStorage.setItem("store_log", "0")` to silence or `"1"` to force-on in a
+ * production build.
+ */
+type Logger = <
+  T,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+>(
+  f: StateCreator<T, Mps, Mcs>,
+  name?: string,
+) => StateCreator<T, Mps, Mcs>;
+
+type LoggerImpl = <T>(f: StateCreator<T, [], []>, name?: string) => StateCreator<T, [], []>;
+
+/**
+ * Read ONCE, at module scope, not on every `set`.
+ *
+ * This used to run inside the wrapped `set`, which means a synchronous
+ * `localStorage.getItem` on every state transition of every logged store — in
+ * production builds too, because the override has to stay readable there by design.
+ * The stores this middleware wraps include ones that transition per pointer event.
+ *
+ * The override cannot change without someone opening devtools and reloading, so
+ * once per session is the same behaviour at a fraction of the cost. {@link setStoreLog}
+ * keeps the ability to flip it live from a console, which is the only thing the
+ * per-call read was actually buying.
+ */
+let storeLog: boolean = (() => {
+  const override = readStored("store_log");
+  if (override === "0") return false;
+  if (override === "1") return true;
+  // NOT under vitest. `DEV` distinguishes a dev build from a production one; a test
+  // run is neither, and vitest sets `DEV=true` — so every transition of every logged
+  // store printed a prev/next object into the suite output. Measured on the consumer's
+  // suite: 822 blocks, several thousand lines, in a log whose whole job is to make one
+  // real `console.error` findable. `store_log=1` still forces it on.
+  // Optional-chained because `import.meta.env` is a Vite injection: it is
+  // undefined under plain Node ESM, and this package is published publicly,
+  // so a non-Vite consumer must be able to import it without throwing.
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+})();
+
+/** Turn store logging on or off for the rest of the session (devtools escape hatch). */
+export function setStoreLog(enabled: boolean): void {
+  storeLog = enabled;
+}
+
+const loggerImpl: LoggerImpl = (f, name) => (set, get, store) => {
+  const loggedSet = ((...args: unknown[]) => {
+    const prev = get();
+    (set as (...a: unknown[]) => void)(...args);
+    if (storeLog) {
+      console.debug(
+        `%c[store${name ? `:${name}` : ""}]`,
+        "color:#0d9488",
+        { prev, next: get() },
+      );
+    }
+  }) as typeof set;
+  return f(loggedSet, get, store);
+};
+
+export const logger = loggerImpl as unknown as Logger;

package/src/lib/safe-storage.ts

@@ -0,0 +1,37 @@
+/**
+ * `localStorage` that cannot take the page down with it.
+ *
+ * Accessing `window.localStorage` **throws** — rather than returning null — when a
+ * browser has site data blocked: Safari private browsing, Chrome with third-party
+ * site data disabled, a partitioned webview. Three places in this package already
+ * knew that and wrapped their calls in try/catch (`logger.ts`, and the DataTable's
+ * `loadPersisted`/`savePersisted`). One did not: `AppShell` read the sidebar's
+ * collapse flag straight out of a `useState` initialiser, so the throw happened
+ * during render of the application's top-level shell. That is not a lost preference
+ * — nothing mounts, in every consumer of this package at once.
+ *
+ * So the guard lives here, once, and the next storage-backed preference cannot
+ * forget it. A read that cannot happen is indistinguishable from a key that was
+ * never set, which is the right answer for every caller: the default.
+ */
+
+/** The stored string for `key`, or null when absent, unreadable, or blocked. */
+export function readStored(key: string): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/** Store `value` under `key`, silently doing nothing when storage is unavailable
+ *  or full. A preference that cannot be persisted is not worth an exception. */
+export function writeStored(key: string, value: string): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // ignore (private mode, quota, partitioned storage)
+  }
+}