@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/lib/download.ts

@@ -0,0 +1,172 @@
+/**
+ * Saving a file the page fetched itself, and reading the name the server gave it
+ * (round 0.34 C6, KS U5).
+ *
+ * Every app behind a token downloads this way: an `<a href>` to an API route carries no
+ * `Authorization` header, so the app fetches the bytes and hands them to the browser
+ * through an object URL and a link with a `download` name. The kit had written that
+ * three times (the translation corrections export, a feedback attachment, the account
+ * data export) in three spellings, and Kurvenschmiede had a fourth beside them, each
+ * with its own answer to the two questions that matter — whether the link is in the
+ * document when it is clicked, and when the URL is revoked. One answer, here:
+ *
+ * - **The link is attached** (hidden, `rel="noopener"`), clicked once and taken out
+ *   again. A detached link downloads in today's Chromium, but Firefox long ignored a
+ *   click on a link outside the document, and attaching it costs nothing.
+ * - **The URL is revoked a minute later**, not at once. The click only STARTS the
+ *   download; the browser reads the URL after this function has returned, and a URL
+ *   revoked before that is a download that fails without a word. A minute holds one
+ *   reference to a blob the page already had; Kastlan's `openAuthenticatedFile` waits
+ *   the same minute for the tab it opens.
+ *
+ * And the name: server-kit's `content_disposition` writes the ORIGINAL name only in the
+ * RFC 6266 / RFC 8187 `filename*=UTF-8''…`, and an ASCII stand-in in the plain
+ * `filename=` (accents folded from 0.8). A reader that takes `filename=` alone saves
+ * "Grun.pdf" for "Grün.pdf" and "____.pdf" for a name in Chinese, so
+ * {@link filenameFromDisposition} reads `filename*` first.
+ */
+
+/** How long an object URL handed to a download stays valid. See the module note. */
+export const SAVE_BLOB_REVOKE_MS = 60_000;
+
+/**
+ * Hand `href` to the browser as a download named `filename`: a hidden link with a
+ * `download` name, attached, clicked once and taken out again. The one way a page saves
+ * a file without opening a tab that shows it instead.
+ *
+ * For a URL the caller keeps alive itself — `DataExportSetting` keeps its object URL for
+ * the "Didn't start? Save the file" link under the button. Everything else wants
+ * {@link saveBlob}.
+ */
+export function clickDownload(href: string, filename: string): void {
+  const link = document.createElement("a");
+  link.href = href;
+  link.download = filename;
+  link.rel = "noopener";
+  link.hidden = true;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+}
+
+/**
+ * Save `blob` as a file named `filename` — the browser's own download, as if the person
+ * had clicked a link to it.
+ *
+ * Call it from the handler of the click that asked for the file. After an `await` (the
+ * fetch) most browsers still count the click as the person's; a browser that does not
+ * holds the download back, and a page that must not lose it keeps a link of its own
+ * under the button, as `DataExportSetting` does.
+ *
+ * ```ts
+ * const res = await api.get(path, { responseType: "blob" });
+ * saveBlob(res.data, filenameFromDisposition(res.headers["content-disposition"], "report.pdf"));
+ * ```
+ */
+export function saveBlob(blob: Blob, filename: string): void {
+  const href = URL.createObjectURL(blob);
+  clickDownload(href, filename);
+  setTimeout(() => URL.revokeObjectURL(href), SAVE_BLOB_REVOKE_MS);
+}
+
+/* ── Content-Disposition ─────────────────────────────────────────────────── */
+
+/**
+ * The parameters of a `Content-Disposition` value, names lower-cased. `;` separates
+ * them except inside a quoted string, whose backslash escapes are undone; a bare token
+ * (the disposition type, `attachment`) is skipped. The first of a repeated name wins.
+ */
+function dispositionParams(header: string): Map<string, string> {
+  const params = new Map<string, string>();
+  const n = header.length;
+  let i = 0;
+  while (i < n) {
+    let j = i;
+    while (j < n && header[j] !== "=" && header[j] !== ";") j++;
+    const name = header.slice(i, j).trim().toLowerCase();
+    if (j >= n || header[j] === ";") {
+      i = j + 1;
+      continue;
+    }
+    j++; // past "="
+    while (j < n && (header[j] === " " || header[j] === "\t")) j++;
+    let value = "";
+    if (header[j] === '"') {
+      j++;
+      while (j < n && header[j] !== '"') {
+        if (header[j] === "\\" && j + 1 < n) j++;
+        value += header[j];
+        j++;
+      }
+      // Past the closing quote and whatever stray text follows it up to the next ";".
+      while (j < n && header[j] !== ";") j++;
+    } else {
+      const end = header.indexOf(";", j);
+      value = header.slice(j, end === -1 ? n : end).trim();
+      j = end === -1 ? n : end;
+    }
+    if (name && !params.has(name)) params.set(name, value);
+    i = j + 1;
+  }
+  return params;
+}
+
+/** An RFC 8187 ext-value — `charset'language'percent-encoded` — decoded, or undefined
+ *  for a charset it cannot read or an encoding that is broken. */
+function decodeExtValue(value: string): string | undefined {
+  const match = /^([^']*)'[^']*'(.*)$/.exec(value);
+  if (!match) return undefined;
+  const charset = match[1].trim().toLowerCase();
+  const encoded = match[2];
+  if (charset === "utf-8" || charset === "utf8") {
+    try {
+      return decodeURIComponent(encoded);
+    } catch {
+      return undefined; // a stray "%" or a cut-off sequence
+    }
+  }
+  if (charset === "iso-8859-1") {
+    return encoded.replace(/%([0-9a-f]{2})/gi, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+  }
+  return undefined;
+}
+
+/** A name safe to put in a `download` attribute or on screen: the last path segment
+ *  (RFC 6266 §4.3 — a recipient strips directory information), without control
+ *  characters, trimmed; undefined when nothing is left. */
+function cleanFilename(name: string | undefined): string | undefined {
+  if (name === undefined) return undefined;
+  const base = name.slice(Math.max(name.lastIndexOf("/"), name.lastIndexOf("\\")) + 1);
+  const clean = Array.from(base)
+    .filter((c) => {
+      const code = c.charCodeAt(0);
+      return code >= 0x20 && code !== 0x7f;
+    })
+    .join("")
+    .trim();
+  return clean && !/^\.+$/.test(clean) ? clean : undefined;
+}
+
+/**
+ * The file name a `Content-Disposition` header asks for: the RFC 8187 `filename*`
+ * (`UTF-8''Gr%C3%BCn.pdf`, the one that carries a name in any script) first, then the
+ * plain `filename=`, quoted or not. Directory parts are dropped. Never throws: a missing
+ * header, a header with no name, a broken encoding all come back as `fallback` —
+ * `undefined` when none is given.
+ *
+ * Reads exactly what server-kit's `content_disposition` writes. With axios the header is
+ * `res.headers["content-disposition"]`, with `fetch` `res.headers.get("Content-Disposition")`
+ * — and across origins only when the server lists it in `Access-Control-Expose-Headers`.
+ */
+export function filenameFromDisposition(header: string | null | undefined): string | undefined;
+export function filenameFromDisposition(header: string | null | undefined, fallback: string): string;
+export function filenameFromDisposition(header: string | null | undefined, fallback?: string): string | undefined {
+  if (typeof header !== "string" || header === "") return fallback;
+  const params = dispositionParams(header);
+  const extended = params.get("filename*");
+  return (
+    cleanFilename(extended === undefined ? undefined : decodeExtValue(extended)) ??
+    cleanFilename(params.get("filename")) ??
+    fallback
+  );
+}

package/src/lib/floating-stack.ts

@@ -3,7 +3,7 @@
  * can sit above it instead of on it.
  *
  * kastlan 0.18: its offline pill is a `bottom-start` FloatingActionButton, and
- * `ServerWakeNotice` sits in the same corner — right after a break both show at once
+ * `ServerWakeNotice` sat in the same corner — right after a break both show at once
  * (the photo outbox syncs while the first reads wake the server), one over the other.
  * The FAB's `offset` cannot help: the notice comes and goes, and on a phone it is
  * nearly as wide as the screen, so a FAB in EITHER corner can be under it.
@@ -14,6 +14,10 @@
  * that is `hidden` measures 0 × 0 and is skipped, so kastlan's pill, which stays
  * mounted and hidden while there is nothing to report, costs the notice nothing.
  *
+ * NO READER since 0.34: `ServerWakeNotice` moved to the top of the screen (keksdose
+ * live #399), out of every FAB's corner. FloatingActionButton still registers; the
+ * next notice that has to sit above the bottom's floating controls reads this.
+ *
  * Internal: not exported from the barrel.
  */
 

package/src/lib/format.ts

@@ -1,6 +1,7 @@
 import { useMemo } from "react";
 import { useKitLocale } from "../i18n/kit-labels";
 import { parseIsoDate } from "./dates";
+import { roundHalfAway } from "./round";
 
 /**
  * Number, money, percentage, date and relative-time formatting — `Intl`, in one place,
@@ -387,6 +388,8 @@ export interface RoundToCurrencyOptions {
  * FX estimate set into an AmountInput showed four decimals) — unless the options form
  * gives `fallbackDigits`: `roundToCurrency(v, code, { fallbackDigits: 2 })` rounds a
  * figure whose currency is not chosen yet to cents rather than leaving 0.1 + 0.2 as is.
+ * A finite value never comes back NaN or -0, however small or large (BUG-11):
+ * 0.1 + 0.2 - 0.3 → 0, -0.004 → 0.
  */
 export function roundToCurrency(
   value: number,
@@ -395,7 +398,6 @@ export function roundToCurrency(
 ): number {
   const options = typeof digits === "object" && digits !== null ? digits : { digits };
   const places = options.digits ?? currencyMinorDigits(currency) ?? options.fallbackDigits;
-  if (places === undefined || !Number.isFinite(value)) return value;
-  const magnitude = Number(`${Math.round(Number(`${Math.abs(value)}e${places}`))}e-${places}`);
-  return value < 0 ? -magnitude : magnitude;
+  if (places === undefined) return value;
+  return roundHalfAway(value, places);
 }

package/src/lib/ime.ts

@@ -0,0 +1,24 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+
+/**
+ * Whether a key press belongs to an IME composition (Chinese, Japanese, Korean input):
+ * `isComposing` while the composition is open, or `keyCode` 229, which is how Safari
+ * reports the key that ENDED one — its keydown arrives after `compositionend`, with
+ * `isComposing` already false (the note in `feedback-thread.tsx`). Takes a React event
+ * or a native one.
+ */
+export function isComposing(e: KeyboardEvent | ReactKeyboardEvent): boolean {
+  const native = "nativeEvent" in e ? e.nativeEvent : e;
+  return native.isComposing || native.keyCode === 229;
+}
+
+/**
+ * An Enter that confirms an IME composition rather than the field (round 0.34 Wave 2,
+ * BUG-9). It picks the IME's candidate, so a list must not also take the highlighted
+ * option and a field must not submit: every Enter branch in the combobox family returns
+ * early on it. Typing 北京 with a pinyin IME is "beijing", then Enter — and that Enter
+ * chose option 1, or created a category through `onSubmit` (keksdose's budget cells).
+ */
+export function isImeEnter(e: KeyboardEvent | ReactKeyboardEvent): boolean {
+  return e.key === "Enter" && isComposing(e);
+}

package/src/lib/presence.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+
+/**
+ * Whether a node says anything — the one copy of the rule (DUP-11, refactor audit
+ * 2026-10: it was written fourteen times as `hasContent` / `hasMessage` / `hasReason` /
+ * `present` / `given`, and FeedbackComposer's own `!= null && !== false` drifted from it
+ * and took `""` for a reason).
+ *
+ * `undefined`, `null`, `false` and `""` are what a caller's `cond && "…"` or
+ * `touched && errors.x` evaluates to when there is nothing to say; none of them is
+ * content, and pointing a control's `aria-describedby` at one would describe it with an
+ * empty node. A numeric `0` is content.
+ *
+ * Package-private — not re-exported from the barrel.
+ */
+export function hasContent(node: ReactNode): boolean {
+  return node !== undefined && node !== null && node !== false && node !== "";
+}

package/src/lib/reduced-motion.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether the user has asked for no motion (`prefers-reduced-motion: reduce`), read NOW —
+ * not at mount: the setting can change under a long-lived page. The kit's one copy
+ * (DUP-11, refactor audit 2026-10: the settings focus and the exit timers each had their
+ * own, with opposite answers where `matchMedia` is missing).
+ *
+ * Where there is no `matchMedia` to ask (SSR, jsdom) the answer is `whereUnknown`,
+ * default `false`: motion allowed — the platform's own default, `no-preference`, which
+ * is what a browser that cannot say otherwise has. A smooth scroll there is harmless.
+ *
+ * An exit animation passes `true` (`skipsExitAnimation` in `hooks/use-close-transition`):
+ * without `matchMedia` nothing is painting, and a timer that holds an unpainted panel on
+ * screen only delays its `onClose` — every test suite, the kit's and the apps', reads a
+ * closed overlay as gone at once.
+ *
+ * Package-private — not re-exported from the barrel.
+ */
+export function prefersReducedMotion(whereUnknown = false): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return whereUnknown;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}

package/src/lib/refs.ts

@@ -0,0 +1,22 @@
+/** Internal (not exported from the package): the kit's ref plumbing. Here, rather than in
+ *  components/field-parts (which re-exports both), since round 0.35: Tooltip needs them,
+ *  and field-parts renders a Tooltip, so importing them from there closed a cycle. */
+import type { Ref, RefCallback } from "react";
+
+/** Point a ref — a callback or an object — at `node`. `undefined` and `null` are no ref. */
+export function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void {
+  if (typeof ref === "function") ref(node);
+  else if (ref) (ref as { current: T | null }).current = node;
+}
+
+/**
+ * One callback ref feeding several — the caller's forwarded `ref` and a field's own
+ * (DUP-11: AmountInput, FormActions, ScrollArea and SearchField each wrote this by hand).
+ * Wrap it in `useCallback` (or `useMemo`) over the same refs where a new callback every
+ * render would detach and re-attach the node.
+ */
+export function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) assignRef(ref, node);
+  };
+}

package/src/lib/round.ts

@@ -0,0 +1,38 @@
+/**
+ * Decimal rounding, half away from zero — the one copy behind {@link roundToCurrency}
+ * and AmountInput's settle (BUG-11, refactor audit 2026-10).
+ *
+ * Package-private — not re-exported from the barrel; `format.ts` and `calc.ts` are
+ * re-exported wholesale, so a helper there would become API.
+ *
+ * WHY THE STRING SHIFT. `Math.round(1.005 * 100)` is 100, because 1.005 is 1.00499…
+ * in binary. Shifting the decimal point in the number's SHORTEST spelling instead
+ * ("1.005e2" is exactly 100.5) rounds the figure a person typed. Both helpers did that
+ * by gluing `e${digits}` onto `String(n)` — but `String(n)` is itself in exponent form
+ * below 1e-6 and at or above 1e21, and "5.55e-17e2" is NaN: `roundToCurrency(0.1 + 0.2
+ * - 0.3, "EUR")` was NaN, and AmountInput blanked a typed "0.0000001" on blur (U-2's
+ * class, 2026-08-24). {@link shiftDecimal} moves the exponent the string already has.
+ */
+
+/** `value × 10^by`, by moving the exponent of its shortest spelling ("1.005" → "1.005e2",
+ *  "5.55e-17" → "5.55e-15"), so no binary multiplication creeps in. */
+function shiftDecimal(value: number, by: number): number {
+  const [mantissa, exponent = "0"] = String(value).split("e");
+  return Number(`${mantissa}e${Number(exponent) + by}`);
+}
+
+/**
+ * `n` rounded to `digits` decimals, half away from zero, in decimal arithmetic:
+ * 1.005 → 1.01, -2.5 at 0 → -3. Never NaN for a finite `n`, and never -0 — `formatMoney`
+ * prints -0 as "-0,00 €", so a negative that rounds away comes back as 0. A non-finite
+ * `n` comes back unchanged.
+ */
+export function roundHalfAway(n: number, digits: number): number {
+  if (!Number.isFinite(n)) return n;
+  const abs = Math.abs(n);
+  // Every double from 2^53 up is a whole number already, and scaling one near
+  // Number.MAX_VALUE up would overflow to Infinity.
+  const magnitude = abs >= 2 ** 53 ? abs : shiftDecimal(Math.round(shiftDecimal(abs, digits)), -digits);
+  // The sign goes back on after rounding, so `|| 0` must see the signed result.
+  return (n < 0 ? -magnitude : magnitude) || 0;
+}

package/src/lib/safe-storage.ts

@@ -13,25 +13,49 @@
  * 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.
+ *
+ * Since 0.34 (DUP-11, refactor audit 2026-10) it also removes, and guards
+ * `sessionStorage` the same way: `landing/routing`, `billing/checkout-processing` and
+ * the demo banner each wrote that guard again by hand. `removeStored` and the session
+ * pair are package-private — the barrel exports `readStored` / `writeStored` only.
  */
 
-/** 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;
+/** `access` on the storage area, or `fallback` where there is none (SSR) or it throws. */
+function guarded<T>(area: "localStorage" | "sessionStorage", fallback: T, access: (storage: Storage) => T): T {
+  if (typeof window === "undefined") return fallback;
   try {
-    return window.localStorage.getItem(key);
+    return access(window[area]);
   } catch {
-    return null;
+    // private mode, quota, partitioned or blocked storage
+    return fallback;
   }
 }
 
+/** The stored string for `key`, or null when absent, unreadable, or blocked. */
+export function readStored(key: string): string | null {
+  return guarded("localStorage", null, (storage) => storage.getItem(key));
+}
+
 /** 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)
-  }
+  guarded("localStorage", undefined, (storage) => storage.setItem(key, value));
+}
+
+/** Forget `key`, silently doing nothing when storage is blocked — there is nothing to
+ *  forget then. */
+export function removeStored(key: string): void {
+  guarded("localStorage", undefined, (storage) => storage.removeItem(key));
+}
+
+/** {@link readStored} for `sessionStorage`: this tab's value, or null. */
+export function readSessionStored(key: string): string | null {
+  return guarded("sessionStorage", null, (storage) => storage.getItem(key));
+}
+
+/** {@link writeStored} for `sessionStorage`; `null` removes the key. */
+export function writeSessionStored(key: string, value: string | null): void {
+  guarded("sessionStorage", undefined, (storage) =>
+    value === null ? storage.removeItem(key) : storage.setItem(key, value),
+  );
 }