@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/lib/day-format.ts

@@ -1,96 +0,0 @@
-import { useCallback } from "react";
-import { useKitDateFormatter, useKitLocale, useKitTimeZone } from "../i18n/kit-labels";
-import { toLocalIso } from "./dates";
-import { clockTime } from "./date-format";
-import { EMPTY_FORMATTED_VALUE, formatDate, toDate, type DateInput, type FormatDateStyle } from "./format";
-import { dateFormatter } from "./intl-cache";
-import { isBareIsoDay } from "./iso-day";
-
-/**
- * How a kit component prints a day — ONE ladder (refactor audit 2026-10-30, DUP-2):
- *
- *  1. the component's own prop (`formatDate`, `renderDate`), when the app gave one and it
- *     answers;
- *  2. else the `<UiKitProvider formatDate>` (keksdose K12: the app's date-format
- *     preference), asked for the calendar day with `source: "dateMark"`;
- *  3. else the kit's `formatDate` in the provider's locale AND `timeZone` (0.46).
- *
- * 0.46's rule — "a label that identifies a day follows the preference" — held only where
- * a component wrote that ladder itself: four copies (admin's `useDayText`, AccountStateChip,
- * DateMark, the feedback table), while about twelve components took their own prop or
- * nothing and went straight to `lib/format`. keksdose set the provider's `formatDate` and
- * still passed it into six components by hand; and the 10 that imported the raw
- * `formatDate` ignored the provider's `timeZone`.
- *
- * @internal Not part of the barrel: the components' props are the public way in.
- */
-
-/** What a {@link DayFormatter} call may ask for. */
-export interface DayTextOptions {
-  /**
-   * Name the day of the week — what the provider's formatter is told (its `weekday`).
-   * keksdose's rule: a date in a COLUMN carries it, a date in a SENTENCE does not
-   * (dev#546). Default `false`. The kit's own rendering follows `style`, not this.
-   */
-  weekday?: boolean;
-  /** Add the clock time, in the language (date-format rule 3): a timestamp. Default false. */
-  time?: boolean;
-  /** The kit's own rendering (step 3). Default `"medium"`, `"dateTime"` with `time`. */
-  style?: FormatDateStyle | Intl.DateTimeFormatOptions;
-  /** `false`: skip the provider (step 2) — a component's explicit style wins over it,
-   *  as `DateMark`'s `dateStyle` does. Default `true`. */
-  preference?: boolean;
-  /** Printed for no value. Default "—". */
-  empty?: string;
-}
-
-/** A component's day printer: a value in, its text out. */
-export type DayFormatter<V extends DateInput = DateInput> = (value: V, options?: DayTextOptions) => string;
-
-/** The calendar day `date` falls on in `timeZone`, as "YYYY-MM-DD" — so the day the
- *  provider is asked for is the day the kit's own rendering would print. */
-function isoDayIn(date: Date, timeZone: string | undefined): string {
-  if (!timeZone) return toLocalIso(date);
-  try {
-    // `en-CA` writes YYYY-MM-DD with Latin digits.
-    const parts = dateFormatter("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(
-      date,
-    );
-    const part = (type: Intl.DateTimeFormatPartTypes) => parts.find((p) => p.type === type)?.value ?? "";
-    return `${part("year")}-${part("month")}-${part("day")}`;
-  } catch {
-    return toLocalIso(date);
-  }
-}
-
-/**
- * The component's day printer, bound to its `prop`, the provider's `formatDate`, locale
- * and `timeZone`. `prop` is called with the value as the component passed it, and wins
- * whenever it answers non-empty. A value that does not parse is printed as it came
- * (a bug upstream is better seen than hidden behind a dash).
- */
-export function useDayFormatter<V extends DateInput = DateInput>(
-  prop?: ((value: V) => string) | null,
-  localeProp?: string,
-): DayFormatter<V> {
-  const locale = useKitLocale(localeProp);
-  const timeZone = useKitTimeZone();
-  const fromProvider = useKitDateFormatter();
-  return useCallback<DayFormatter<V>>(
-    (value, options = {}) => {
-      const own = prop?.(value);
-      if (own) return own;
-      if (value === null || value === undefined || value === "") return options.empty ?? EMPTY_FORMATTED_VALUE;
-      const date = toDate(value);
-      if (!date) return String(value);
-      const bareDay = isBareIsoDay(value);
-      if (fromProvider && options.preference !== false) {
-        const iso = bareDay ? value : isoDayIn(date, timeZone);
-        const day = fromProvider(iso, { unit: "day", source: "dateMark", locale, weekday: options.weekday ?? false });
-        if (day) return options.time && !bareDay ? `${day}, ${clockTime(date, locale, timeZone)}` : day;
-      }
-      return formatDate(value, options.style ?? (options.time ? "dateTime" : "medium"), { locale, timeZone });
-    },
-    [prop, fromProvider, locale, timeZone],
-  );
-}

package/src/lib/decimal-marks.ts

@@ -1,108 +0,0 @@
-/**
- * The locale's decimal mark and the reading of typed grouping marks, shared by the
- * kit's numeric text fields: {@link AmountInput}, {@link NumberInput} and, through
- * NumberInput, {@link NumberField} and {@link MoneyField}.
- *
- * Package-private — not re-exported from the barrel. It lives here rather than in
- * `calc.ts` because that module is re-exported wholesale (`export * from
- * "./lib/calc"`), and these are the fields' plumbing, not API.
- *
- * WHY ONE MODULE. AmountInput learned the locale's mark (kastlan 40) and the grouping
- * parse (keksdose G1); NumberInput learned neither, so the same "1.234,56" a German
- * user typed into a money field read as 1234.56 and, typed into the budget-goal field
- * next to it, as 1.23456 (keksdose K5). Two private copies of the same rule are how
- * that happened, so the rule now has one home.
- */
-import { sanitizeLive } from "./calc";
-
-/**
- * The locale's decimal mark, as far as a field can type it: "," or "." (kastlan 40).
- * A mark outside those two (Arabic's "٫") is not one {@link sanitizeLive} lets
- * through, so those locales keep the dot rather than get a field that eats the key it
- * shows. `undefined` is the runtime's own locale, which is what `Intl` reads it as.
- */
-export function decimalMark(locale: string | undefined): "," | "." {
-  try {
-    const part = new Intl.NumberFormat(locale).formatToParts(1.5).find((p) => p.type === "decimal");
-    return part?.value === "," ? "," : ".";
-  } catch {
-    // An invalid tag throws a RangeError; a typo in a locale must not take the form down.
-    return ".";
-  }
-}
-
-/**
- * Which typed mark is the decimal one (keksdose G1). {@link sanitizeLive} folds every
- * "," into ".", so on its own it read the German "1.234,56" as 1.23456 — and a money
- * field's settle then made that 1.23, final. This decides per operand, from the
- * typist's own text, before that fold:
- *
- * - both marks present: the LAST one is the decimal mark, whichever the locale's is, and
- *   the other is grouping and goes. The order says the convention the figure was written
- *   in — "1.234,56" German, "1,234.56" English — and a figure pasted from another app or
- *   locale keeps it. Taking the non-locale mark as grouping wherever it stood read
- *   "1.234,56" in a "." locale (en, de-CH) as 1.23456, which a money field then settled
- *   to 1.23 (refactor audit 2026-10-30, INP-3). Typed in the locale's own convention, its
- *   mark comes last and nothing changes;
- * - in a "," locale, only "." present: grouping when it cannot be a decimal as a
- *   German reader writes it — twice ("1.234.567"), or in thousands shape ("1.234",
- *   "12.500") — otherwise a decimal ("1.5", typed by a dot-decimal habit). A first
- *   group that starts with 0 is never thousands: "0.500" is a half, not five hundred
- *   (BUG-6, refactor audit 2026-10);
- * - in a "." locale, only "," present: grouping when it appears twice ("1,234,567");
- *   once it stays a decimal, because Swiss and German typists write "1,5" in a
- *   de-CH form (kastlan 40) and a unit price "1,789" is a decimal.
- *
- * Only a keystroke's text comes through here. A calculator result is dot-decimal
- * already, and "1.234" from `100/81.03…` is never a thousand.
- */
-export function normalizeTypedMarks(raw: string, mark: "," | "."): string {
-  const other = mark === "," ? "." : ",";
-  return raw.replace(/[0-9.,]+/g, (operand) => {
-    const count = operand.split(other).length - 1;
-    if (count === 0) return operand;
-    if (operand.includes(mark)) {
-      const grouping = operand.lastIndexOf(mark) > operand.lastIndexOf(other) ? other : mark;
-      return operand.split(grouping).join("");
-    }
-    const grouping = count > 1 || (mark === "," && /^[1-9]\d{0,2}(\.\d{3})+$/.test(operand));
-    return grouping ? operand.split(other).join("") : operand;
-  });
-}
-
-/** What a keystroke's raw text reports: grouping read off, then the field's live
- *  sanitising (comma → dot, stray characters out, one decimal point per operand). */
-export function readTyped(raw: string, mark: "," | "."): string {
-  return sanitizeLive(normalizeTypedMarks(raw, mark));
-}
-
-// Spacing a typist uses to group digits — a space, the no-break and narrow no-break
-// spaces `Intl` itself writes for fr-CH ("1 234,5" with U+202F), and the Swiss
-// apostrophes ("1'234.50"). The live sanitising drops them, so they never reach the
-// value; the draft may still show them.
-const GROUP_SPACING = /[\s'’\u00a0\u202f]/g;
-
-/**
- * Whether the field may keep SHOWING `raw` — the typist's own text — while it holds
- * `canonical` (dot-decimal, as `onChange` reported it).
- *
- * Showing the typed text rather than re-spelling the value is what keeps the caret
- * where the typist put it, and what keeps a grouping "." from being turned into a ","
- * under their fingers — after which no rule could tell the two apart (keksdose G1).
- * But only text that says the same as the value, and says it with nothing the field
- * would have DROPPED: a letter, or a second decimal point in one operand ("1.2.3"),
- * must not stay on screen while the value says "1.23" (Keksdose live #201 is the bug
- * that showing it would bring back). Grouping marks and grouping spaces may stay.
- */
-export function showsTyped(raw: string, mark: "," | ".", canonical: string): boolean {
-  const read = normalizeTypedMarks(raw, mark).replace(GROUP_SPACING, "");
-  const sanitized = sanitizeLive(read);
-  // Nothing dropped: the read text is the sanitised one, but for which mark it uses.
-  return sanitized === read.replace(/,/g, ".") && sanitized === sanitizeLive(canonical);
-}
-
-/** A dot-decimal text spelt in `mark` — display only, one character for one, so a
- *  re-spelling never moves a caret. */
-export function localizeMark(text: string, mark: "," | "."): string {
-  return mark === "," ? text.replace(/\./g, ",") : text;
-}

package/src/lib/describe-failure.ts

@@ -1,18 +0,0 @@
-import type { ReactNode } from "react";
-import { hasContent } from "./presence";
-
-/**
- * The failure ladder, once: the app's words for a failure when it has any, else the
- * kit's `fallback`.
- *
- * "Any" is {@link hasContent}, so an app's `describeError` answering `""` (nothing to say
- * about this one) gets the kit's sentence. Written as `own ?? fallback` in the auth forms,
- * where `""` printed an empty alert, and both ways within one file in the reviewer scope
- * editor; it lived in the notification cards' parts only (refactor audit 2026-10-30,
- * DUP-14).
- *
- * @internal Package-private — not re-exported from the barrel.
- */
-export function describeFailure(own: ReactNode | undefined, fallback: ReactNode): ReactNode {
-  return hasContent(own) ? own : fallback;
-}

package/src/lib/device-settings.ts

@@ -1,147 +0,0 @@
-import { readSessionStored, readStored, removeStored, storedKeys, writeSessionStored } from "./safe-storage";
-
-/**
- * What this device keeps of how it shows the app, and the one action that puts it all
- * back: "Reset this device's settings" (docs/settings-harmonization.md §11).
- *
- * A registry, because no one part knows every key. The kit's own stores and components
- * join it themselves — the theme, palette, text-size and contrast stores when they are
- * created, `UiKitProvider` (the prefix its tables keep their views under) and `AppShell`
- * (the sidebar's folded state) while they are mounted — and an app adds its own keys
- * beside the store or accessor that owns each (keksdose's date format, kastlan's
- * language, Kurvenschmiede's curve channels). {@link resetDeviceSettings} then clears
- * exactly what joined, and nothing else: the sign-in, the session, what waits to be sent
- * and the account never join (§11.2 decision 2), so a key nobody registered survives.
- *
- * No React and no router: a store joins at module scope, when it is created. Here in
- * `src/lib` beside `safe-storage.ts`, which the stores and the shell already import, so
- * `src/theme` and `src/shell` do not import `src/settings`. One module instance, one
- * module-level list.
- */
-
-/** What a reset of this device's settings clears (§11.2 decision 1): how the app looks
- *  here, and how its tables and panels were left. An app's own list may add a third kind
- *  of its own for what never goes (Kurvenschmiede's "never"). */
-export type DeviceSettingKind = "appearance" | "view";
-
-export interface DeviceSetting {
-  /** The storage key; with `prefix`, every key that starts with it. */
-  key: string;
-  /** `true`: `key` is a prefix (a table's views, keksdose's display currency per budget).
-   *  It matches by `startsWith`: `budget.displayCurrency.` does not take the legacy
-   *  `budget.displayCurrency`. */
-  prefix?: boolean;
-  /** Default `"local"`. */
-  storage?: "local" | "session";
-  kind: DeviceSettingKind;
-  /**
-   * Puts the live value back to its default through the store's own setter, the one its
-   * control calls, so whatever that setter also does still happens — never
-   * `setState(getInitialState())`, which skips it. REQUIRED for anything held in memory:
-   * every persisted zustand store (removing its key alone, it writes its value back on its
-   * next change), a mounted component's state. With `reset` the key is left to it (a
-   * persisted store writes its default itself); without, the key, or every key under the
-   * prefix, is removed — for what is read where it is next used (a table at its mount, a
-   * plain accessor).
-   */
-  reset?: () => void;
-}
-
-/** Whoever joined one key, in join order; the last one's entry is the key's entry. */
-type Holders = { entry: DeviceSetting }[];
-
-/** One slot per key and storage area, in the order each was first joined. */
-const slots = new Map<string, Holders>();
-
-const areaOf = (entry: DeviceSetting): "local" | "session" => (entry.storage === "session" ? "session" : "local");
-const slotOf = (entry: DeviceSetting) => `${areaOf(entry)}:${entry.key}`;
-
-/**
- * Join the registry; answers the leave function. A store joins once, at creation, and
- * never leaves; a component joins while mounted and leaves in its effect's cleanup.
- *
- * **One entry per key** (and storage area): joining a key again replaces its entry and
- * adds a holder, and a leave drops its holder — the entry goes with the last one, and
- * until then the latest remaining holder's entry is the key's. So a module evaluated twice
- * (a test, a hot reload) does not reset twice, and two nested providers with one prefix
- * keep their entry until the outer one unmounts.
- */
-export function registerDeviceSetting(entry: DeviceSetting): () => void {
-  const slot = slotOf(entry);
-  const holder = { entry: { ...entry } };
-  const holders = slots.get(slot);
-  if (holders) holders.push(holder);
-  else slots.set(slot, [holder]);
-  let left = false;
-  return () => {
-    if (left) return;
-    left = true;
-    // A holder that has not left is in its slot: only its own leave takes it out, and a
-    // slot goes only once it is empty.
-    const current = slots.get(slot) as Holders;
-    current.splice(current.indexOf(holder), 1);
-    if (current.length === 0) slots.delete(slot);
-  };
-}
-
-/** Every entry, in join order: for an app's own test (Kurvenschmiede holds it to its
- *  `STORAGE` list) or its privacy page. */
-export function deviceSettings(): readonly DeviceSetting[] {
-  return [...slots.values()].map((holders) => holders[holders.length - 1].entry);
-}
-
-/** Is this a development build? `import.meta.env` is a Vite injection, absent under Node. */
-function devBuild(): boolean {
-  return Boolean(import.meta.env?.DEV);
-}
-
-/** The keys an entry covers now: a prefix's keys found under it, else its own key. */
-function keysOf(entry: DeviceSetting): string[] {
-  return entry.prefix ? storedKeys(entry.key, areaOf(entry)) : [entry.key];
-}
-
-/** Remove what `entry` covers; answers the keys that were there. */
-function removeEntry(entry: DeviceSetting): string[] {
-  const session = areaOf(entry) === "session";
-  const present = keysOf(entry).filter((key) => (session ? readSessionStored(key) : readStored(key)) !== null);
-  for (const key of present) {
-    if (session) writeSessionStored(key, null);
-    else removeStored(key);
-  }
-  return present;
-}
-
-/**
- * Reset every entry, at once; answers the keys it reset or removed, prefixes expanded.
- *
- * Synchronous, in two passes: first every `reset`, in join order, so each live store puts
- * its value back (and writes its default); then the keys of the entries without one. A
- * `reset` that throws is caught (`console.error` in development), its key is removed
- * instead, and the rest still run. It never reloads, navigates or sends a request, and
- * never touches a key nobody registered. Where the browser refuses storage, the live
- * values still reset and nothing throws.
- *
- * The answer: an entry with a `reset` lists its key (a prefix, the keys found under it);
- * an entry without lists the keys it removed, those that were there.
- */
-export function resetDeviceSettings(): string[] {
-  const keys: string[] = [];
-  const remove: DeviceSetting[] = [];
-  for (const entry of deviceSettings()) {
-    if (!entry.reset) {
-      remove.push(entry);
-      continue;
-    }
-    const covered = keysOf(entry);
-    try {
-      entry.reset();
-      keys.push(...covered);
-    } catch (error) {
-      if (devBuild())
-        console.error(`resetDeviceSettings: the reset of "${entry.key}" threw; its key is removed instead.`, error);
-      remove.push(entry);
-    }
-  }
-  for (const entry of remove) keys.push(...removeEntry(entry));
-  return [...new Set(keys)];
-}

package/src/lib/direction.ts

@@ -1,74 +0,0 @@
-/**
- * Reading direction, as the DOM has it — internal, not exported from the barrel.
- *
- * The kit lays itself out with logical classes (`ps-*`, `end-*`, `text-start`), which
- * need no JavaScript. These helpers are for the two things CSS cannot do:
- *
- * - **Arrow keys.** ←/→ mean previous/next in LTR and the reverse in RTL. Resolve the
- *   key through {@link horizontalStep} instead of comparing to "ArrowRight".
- * - **Portals.** A panel portalled to `document.body` leaves the subtree whose `dir`
- *   it inherited. Read the anchor's direction with {@link dirOf} and put it on the
- *   portalled root, and position it from the anchor's START edge, not `rect.left`.
- */
-
-export type Direction = "ltr" | "rtl";
-
-/** The effective direction at `el`: its nearest `[dir]` ancestor (or itself), else the
- *  document's, else LTR. Attribute-based on purpose — jsdom computes no `direction`. */
-export function dirOf(el: Element | null | undefined): Direction {
-  const source = el?.closest("[dir]") ?? (typeof document !== "undefined" ? document.documentElement : null);
-  return source?.getAttribute("dir") === "rtl" ? "rtl" : "ltr";
-}
-
-export function isRtl(el: Element | null | undefined): boolean {
-  return dirOf(el) === "rtl";
-}
-
-/**
- * +1 for a key that moves FORWARD along the reading direction, -1 for backward, 0 for
- * any other key. ArrowRight is forward in LTR and backward in RTL.
- */
-export function horizontalStep(key: string, el: Element | null | undefined): 1 | -1 | 0 {
-  if (key !== "ArrowRight" && key !== "ArrowLeft") return 0;
-  const forward = (key === "ArrowRight") !== isRtl(el);
-  return forward ? 1 : -1;
-}
-
-/**
- * Where a key moves the focus in a list with ONE tab stop (a roving tabindex): the index
- * to focus from `at` among `count` items, or `undefined` for a key that moves nothing.
- * ←/→ along `dir` — → is next in `ltr` and previous in `rtl` — ↓/↑ as next and previous,
- * Home and End to the ends. With `wrap`, past the last is the first and before the first
- * the last (a ring: PieChart's slices); without, the ends hold (a plane: Treemap's tiles).
- *
- * The charts each mapped the keys themselves, and differently at the ends (0.52 code
- * review of treemap.tsx, finding 9); the end rule is now a word at the call.
- *
- * `dir` and not an element to read it off (0.52 code review, deep, charts, findings 1 and
- * 14): a list in the page's flow takes the page's (`dirOf(el)`), but a plot is laid out
- * left to right in any page (see `ChartContainer`) and passes `"ltr"` — read off the
- * element, Treemap's → walked an RTL page's tiles backwards, against the picture.
- */
-export function rovingTarget(
-  key: string,
-  dir: Direction,
-  at: number,
-  count: number,
-  wrap: boolean,
-): number | undefined {
-  const physical = key === "ArrowRight" ? 1 : key === "ArrowLeft" ? -1 : 0;
-  const step = dir === "rtl" ? -physical : physical;
-  const to = step
-    ? at + step
-    : key === "ArrowDown"
-      ? at + 1
-      : key === "ArrowUp"
-        ? at - 1
-        : key === "Home"
-          ? 0
-          : key === "End"
-            ? count - 1
-            : undefined;
-  if (to === undefined || count <= 0) return undefined;
-  return wrap ? ((to % count) + count) % count : Math.max(0, Math.min(count - 1, to));
-}

package/src/lib/document-navigation.ts

@@ -1,17 +0,0 @@
-/**
- * The full-document navigations the kit makes, behind one object the tests can spy on.
- *
- * jsdom implements neither `location.reload` nor `location.replace`, and its
- * `window.location` is unforgeable: a test cannot stub it by redefining the property
- * once the suite runs each file in its own VM context (`pool: "vmThreads"`, which took
- * the suite from ~3 minutes to ~1). `vi.spyOn(documentNavigation, "reload")` works in
- * every pool. Internal, not part of the package's surface.
- */
-export const documentNavigation = {
-  reload(): void {
-    window.location.reload();
-  },
-  replace(href: string): void {
-    window.location.replace(href);
-  },
-};

package/src/lib/document-title.ts

@@ -1,41 +0,0 @@
-/**
- * The window's title from its parts (0.49 KIT-9): `{page}`, `{section}` and `{app}` in a
- * format, by default "{page} · {section} · {app}" — "Invoices · Finance · Kastlan".
- *
- * A part that is missing (undefined, null, empty or blank) is dropped WITH the separator
- * before it, so "Invoices · Kastlan" never reads "Invoices ·  · Kastlan". The text between
- * two parts is the separator; text before the first part and after the last is kept as
- * written ("[{page} – {app}]" → "[KS]"). No part at all gives "".
- */
-export const DEFAULT_DOCUMENT_TITLE_FORMAT = "{page} · {section} · {app}";
-
-/** The parts {@link formatDocumentTitle} fills in. */
-export interface DocumentTitleParts {
-  page?: string | null;
-  section?: string | null;
-  app?: string | null;
-}
-
-const PLACEHOLDER = /\{(page|section|app)\}/g;
-
-export function formatDocumentTitle(format: string, parts: DocumentTitleParts): string {
-  let prefix = "";
-  let out = "";
-  let pending = "";
-  let last = 0;
-  let seen = false;
-  for (const m of format.matchAll(PLACEHOLDER)) {
-    const literal = format.slice(last, m.index!);
-    last = m.index! + m[0].length;
-    if (!seen) prefix = literal;
-    else pending = out === "" ? "" : literal || pending;
-    seen = true;
-    const value = parts[m[1] as keyof DocumentTitleParts]?.trim();
-    if (!value) continue;
-    out += (out === "" ? "" : pending) + value;
-    pending = "";
-  }
-  if (!seen) return format;
-  if (out === "") return "";
-  return prefix + out + format.slice(last);
-}