@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/lib/iban.ts

@@ -0,0 +1,171 @@
+/**
+ * IBAN helpers — ISO 13616 — for kastlan (supplier and customer bank details, the
+ * Swiss QR-bill) and keksdose (the accounts behind a household's transfers).
+ *
+ * Both apps validated an IBAN the same partial way: a regex for the shape, sometimes a
+ * mod-97, never the per-country length — so a Swiss IBAN with a digit missing passed
+ * as long as the shorter string happened to sum right, and "CH" followed by 22
+ * characters (a German length) was accepted as Swiss. And kastlan's QR-bill needs a
+ * second distinction neither had: a **QR-IBAN** (the institution id at positions 5–9 is
+ * 30000–31999) is the only account a QR-bill with a QR reference can be paid to, and it
+ * cannot receive an ordinary transfer — so a regular IBAN typed where a QR-IBAN is
+ * needed, or the other way round, is a payment that bounces weeks later.
+ *
+ * Everything here works on the **electronic format** (no spaces, upper case), which is
+ * what to store; {@link formatIban} is the paper format, which is what to show.
+ *
+ * Validation is the registry's two rules, nothing more: the length for the country and
+ * the mod-97 check digits. It does not check each country's BBAN layout (which places
+ * hold letters), nor whether the bank exists — a checksum catches a typo, not a closed
+ * account.
+ */
+
+/**
+ * The IBAN length for each country in the SWIFT IBAN Registry (2025 edition) — the
+ * whole string, country code and check digits included.
+ *
+ * A country that is not in the table does not issue IBANs, so {@link isValidIban}
+ * refuses it ("XX" is a typo, not an exotic bank). Territories that use another
+ * country's code (Åland under FI, Guernsey under GB, the French overseas departments
+ * under FR) are covered by that code, as the registry lists them.
+ */
+export const IBAN_LENGTHS: Readonly<Record<string, number>> = Object.freeze({
+  AD: 24, AE: 23, AL: 28, AT: 20, AZ: 28, BA: 20, BE: 16, BG: 22, BH: 22, BI: 27,
+  BR: 29, BY: 28, CH: 21, CR: 22, CY: 28, CZ: 24, DE: 22, DJ: 27, DK: 18, DO: 28,
+  EE: 20, EG: 29, ES: 24, FI: 18, FK: 18, FO: 18, FR: 27, GB: 22, GE: 22, GI: 23,
+  GL: 18, GR: 27, GT: 28, HN: 28, HR: 21, HU: 28, IE: 22, IL: 23, IQ: 23, IS: 26,
+  IT: 27, JO: 30, KW: 30, KZ: 20, LB: 28, LC: 32, LI: 21, LT: 20, LU: 20, LV: 21,
+  LY: 25, MC: 27, MD: 24, ME: 22, MK: 19, MN: 20, MR: 27, MT: 31, MU: 30, NI: 28,
+  NL: 18, NO: 15, OM: 23, PK: 24, PL: 28, PS: 29, PT: 25, QA: 29, RO: 24, RS: 22,
+  RU: 33, SA: 24, SC: 31, SD: 18, SE: 24, SI: 19, SK: 24, SM: 27, SO: 23, ST: 25,
+  SV: 28, TL: 23, TN: 24, TR: 26, UA: 29, VA: 22, VG: 24, XK: 20, YE: 30,
+});
+
+/**
+ * Which kind of IBAN a field accepts. `"any"`: every valid IBAN. `"qr"`: only a
+ * QR-IBAN (a QR-bill with a QR reference — kastlan's payment slips). `"plain"`: every
+ * valid IBAN EXCEPT a QR-IBAN (an account for ordinary transfers, which a QR-IBAN
+ * cannot receive).
+ */
+export type IbanKind = "qr" | "plain" | "any";
+
+/**
+ * Why a value is not the IBAN a field wants, most fundamental first:
+ *
+ *  - `"format"` — it does not start with a two-letter country code and two digits;
+ *  - `"country"` — the first two letters are not a country in {@link IBAN_LENGTHS};
+ *  - `"length"` — the wrong number of characters for that country;
+ *  - `"checksum"` — the mod-97 check digits do not match (a typo, a swapped pair);
+ *  - `"qrRequired"` — a valid IBAN, but not a QR-IBAN where `kind="qr"` needs one;
+ *  - `"qrNotAllowed"` — a valid QR-IBAN where `kind="plain"` refuses one.
+ */
+export type IbanProblem = "format" | "country" | "length" | "checksum" | "qrRequired" | "qrNotAllowed";
+
+/**
+ * The electronic format: every character that is not a letter or a digit dropped, the
+ * letters in upper case. Spaces, non-breaking spaces, hyphens and dots — what a paste
+ * from an invoice, a PDF or an e-banking screen carries — all go.
+ *
+ * A leading `"IBAN"` (the paper format's label: "IBAN CH56 …") is dropped too, but only
+ * in front of a country code and check digits, so typing the word does not make it
+ * vanish under the caret.
+ */
+export function compactIban(value: string): string {
+  const compact = value.replace(/[^0-9A-Za-z]/g, "").toUpperCase();
+  return /^IBAN[A-Z]{2}\d{2}/.test(compact) ? compact.slice(4) : compact;
+}
+
+/**
+ * The paper format: {@link compactIban}, then groups of four separated by a single
+ * space ("CH09 0000 0000 0000 0000 1"). The last group is whatever is left over.
+ */
+export function formatIban(value: string): string {
+  return compactIban(value).replace(/(.{4})(?=.)/g, "$1 ");
+}
+
+/** The remainder of a long digit string modulo 97, a few digits at a time so it never
+ *  leaves the safe-integer range — ISO 7064 MOD 97-10 without a BigInt. */
+function mod97(digits: string): number {
+  let rest = 0;
+  for (let i = 0; i < digits.length; i += 7) {
+    rest = Number(`${rest}${digits.slice(i, i + 7)}`) % 97;
+  }
+  return rest;
+}
+
+/** Letters to their two-digit numbers (A = 10 … Z = 35), digits as they are. */
+function expandLetters(value: string): string {
+  return value.replace(/[A-Z]/g, (c) => String(c.charCodeAt(0) - 55));
+}
+
+/**
+ * The two check digits for a country code and a BBAN (the account part after them):
+ * `98 − ((BBAN + country + "00") mod 97)`, letters expanded A = 10 … Z = 35.
+ *
+ * What an app needs to BUILD an IBAN — a test fixture, a demo, a migration that
+ * assembles one from a clearing number and an account number — rather than to check
+ * one. Both arguments are compacted first.
+ */
+export function ibanCheckDigits(country: string, bban: string): string {
+  const rearranged = `${compactIban(bban)}${compactIban(country)}00`;
+  const check = 98 - mod97(expandLetters(rearranged));
+  return String(check).padStart(2, "0");
+}
+
+/**
+ * The first thing wrong with `value` as an IBAN of `kind`, or `null` when it is one.
+ * The value is compacted first, so the paper format is accepted. An empty value is
+ * `"format"`: whether a field may be left empty is the form's rule, not the IBAN's.
+ */
+export function ibanProblem(value: string, kind: IbanKind = "any"): IbanProblem | null {
+  const iban = compactIban(value);
+  if (!/^[A-Z]{2}\d{2}/.test(iban)) return "format";
+  const expected = IBAN_LENGTHS[iban.slice(0, 2)];
+  if (expected === undefined) return "country";
+  if (iban.length !== expected) return "length";
+  // 00, 01 and 99 are never computed (98 − r lies in 2…98), but 01 ≡ 98 mod 97 and
+  // would otherwise pass the remainder test below — ISO 7064 rules them out.
+  const check = iban.slice(2, 4);
+  if (check === "00" || check === "01" || check === "99") return "checksum";
+  if (mod97(expandLetters(`${iban.slice(4)}${iban.slice(0, 4)}`)) !== 1) return "checksum";
+  if (kind === "any") return null;
+  const qr = qrIid(iban);
+  if (kind === "qr" && !qr) return "qrRequired";
+  if (kind === "plain" && qr) return "qrNotAllowed";
+  return null;
+}
+
+/**
+ * Whether `value` is a valid IBAN: a registry country, that country's length, and
+ * matching mod-97 check digits. Spaces and lower case are fine (see
+ * {@link compactIban}); what to store is the compact form.
+ */
+export function isValidIban(value: string): boolean {
+  return ibanProblem(value) === null;
+}
+
+/** A CH/LI IBAN whose institution id (positions 5–9) is in the QR range. Structure
+ *  only — the caller has checked or will check the rest. */
+function qrIid(iban: string): boolean {
+  const country = iban.slice(0, 2);
+  if (country !== "CH" && country !== "LI") return false;
+  const iid = iban.slice(4, 9);
+  if (!/^\d{5}$/.test(iid)) return false;
+  const n = Number(iid);
+  return n >= 30000 && n <= 31999;
+}
+
+/**
+ * Whether `value` is a valid **QR-IBAN**: a valid Swiss or Liechtenstein IBAN whose
+ * institution id — positions 5 to 9, the QR-IID — lies in 30000–31999 (SIX, Swiss
+ * Implementation Guidelines for the QR-bill).
+ *
+ * The distinction is not cosmetic (kastlan): a QR-bill with a QR reference can only be
+ * paid to a QR-IBAN, and a QR-IBAN can receive nothing else — so an app that prints
+ * payment slips needs one, and an app that stores an account for ordinary transfers
+ * must not take one.
+ */
+export function isQrIban(value: string): boolean {
+  const iban = compactIban(value);
+  return ibanProblem(iban) === null && qrIid(iban);
+}

package/src/lib/isin.ts

@@ -0,0 +1,62 @@
+/**
+ * ISIN helpers — ISO 6166 — for keksdose, whose securities holdings are keyed by ISIN
+ * and whose import and edit forms checked only the shape (two letters, ten
+ * characters): a mistyped ISIN saved happily and then matched no price feed.
+ *
+ * An ISIN is twelve characters: a two-letter prefix (the issuing country, or a
+ * supranational code such as `XS`), nine letters or digits (the national number) and
+ * one check digit. The check digit is the Luhn digit of the first eleven characters
+ * with every letter expanded to two digits (A = 10 … Z = 35) — which is all that is
+ * checked here. Whether the prefix is an assigned code, and whether the security
+ * exists, is a lookup, not a checksum.
+ */
+
+/** Letters to their two-digit numbers (A = 10 … Z = 35), digits as they are. */
+function expandLetters(value: string): string {
+  return value.replace(/[A-Z]/g, (c) => String(c.charCodeAt(0) - 55));
+}
+
+/** The Luhn sum of `digits` with the RIGHTMOST digit doubled first — the shape of the
+ *  sum when a check digit is about to be appended. */
+function luhnSum(digits: string, doubleRightmost: boolean): number {
+  let sum = 0;
+  let double = doubleRightmost;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum;
+}
+
+/**
+ * The ISIN as it is printed: upper case, unbroken (ISO 6166 has no grouping), with
+ * the spaces and hyphens a paste from a broker's statement carries dropped.
+ */
+export function formatIsin(value: string): string {
+  return value.replace(/[\s-]/g, "").toUpperCase();
+}
+
+/**
+ * The check digit for the first eleven characters of an ISIN (prefix and national
+ * number). For BUILDING one — a test fixture, a demo — rather than checking it.
+ */
+export function isinCheckDigit(body: string): string {
+  const sum = luhnSum(expandLetters(formatIsin(body)), true);
+  return String((10 - (sum % 10)) % 10);
+}
+
+/**
+ * Whether `value` is a valid ISIN: two letters, nine letters or digits, one digit,
+ * and a matching Luhn check digit over the letter-expanded form. Spaces, hyphens and
+ * lower case are fine (see {@link formatIsin}).
+ */
+export function isValidIsin(value: string): boolean {
+  const isin = formatIsin(value);
+  if (!/^[A-Z]{2}[A-Z0-9]{9}\d$/.test(isin)) return false;
+  return luhnSum(expandLetters(isin), false) % 10 === 0;
+}

package/src/lib/phone.ts

@@ -0,0 +1,211 @@
+/**
+ * Phone numbers — E.164 in, grouped out — for kastlan's contacts, without a
+ * libphonenumber dependency.
+ *
+ * kastlan stored whatever was typed ("079 …", "+41 (0)79 …", "0041 79 …") and could
+ * neither dial nor de-duplicate it. What it needs is one canonical form to store —
+ * E.164, "+41210000001" — and a readable one to show. libphonenumber gets both right
+ * for every country, at ~150 kB of metadata in every app's bundle; the kit's apps are
+ * Swiss and their neighbours, so this is **light per-country rules** for the six that
+ * matter and a generic shape check for the rest:
+ *
+ *  - **CH, LI, DE, AT, FR, IT**: the national trunk prefix is dropped (a leading 0 —
+ *    but NOT for Italy, whose fixed-line numbers keep their 0 after +39, and not for
+ *    Liechtenstein, which has none), and the remaining national number has to be a
+ *    plausible length for the country.
+ *  - **Anything else** typed with its own "+" (or "00"): the digits, 8 to 15 in all,
+ *    are taken as an E.164 number as they stand.
+ *
+ * **The limitation:** a plausible length is not a valid number. There is no check of
+ * area codes or number ranges, so a well-formed number that does not exist passes, and
+ * a German or Austrian number (whose area codes run from one to five digits) is
+ * grouped only where the split is known (mobile prefixes, the largest cities) and
+ * otherwise shown in one block. A number these rules cannot read is not an error —
+ * {@link parsePhone} returns `null` and the field keeps the text as typed.
+ */
+
+/** The countries with their own rules. */
+export type PhoneCountryCode = "CH" | "LI" | "DE" | "AT" | "FR" | "IT";
+
+/** A country with rules, or `"other"`: a number typed with its own "+". */
+export type PhoneCountry = PhoneCountryCode | "other";
+
+interface CountryRule {
+  /** The country calling code, without the "+". */
+  dial: string;
+  /** A national number starts with a trunk 0 that is dropped after the country code. */
+  trunk: boolean;
+  /** The national significant number itself may start with 0 (Italy's fixed lines). */
+  zeroStart?: boolean;
+  /** The national significant number's length, inclusive. */
+  min: number;
+  max: number;
+  /** Groups for display, given the national significant number. */
+  group: (nsn: string) => string[];
+}
+
+/** `nsn` cut into the given sizes; whatever is left is one last group. */
+function cut(nsn: string, sizes: number[]): string[] {
+  const out: string[] = [];
+  let at = 0;
+  for (const size of sizes) {
+    if (at >= nsn.length) break;
+    out.push(nsn.slice(at, at + size));
+    at += size;
+  }
+  if (at < nsn.length) out.push(nsn.slice(at));
+  return out;
+}
+
+const RULES: Record<PhoneCountryCode, CountryRule> = {
+  // 9 digits, 2-3-2-2 ("21 000 00 01"); the 08xx/09xx service numbers 3-3-3.
+  CH: {
+    dial: "41",
+    trunk: true,
+    min: 9,
+    max: 9,
+    group: (n) => (/^[89]/.test(n) ? cut(n, [3, 3, 3]) : cut(n, [2, 3, 2, 2])),
+  },
+  // 7 digits, 3-2-2 ("100 00 01"), and 9 for some mobile ranges (3-3-3). No trunk prefix.
+  LI: {
+    dial: "423",
+    trunk: false,
+    min: 7,
+    max: 9,
+    group: (n) => (n.length === 7 ? cut(n, [3, 2, 2]) : n.length === 9 ? cut(n, [3, 3, 3]) : [n]),
+  },
+  // Area codes of two to five digits: only the mobile prefixes and the four
+  // two-digit cities are split; anything else is one block rather than a wrong split.
+  DE: {
+    dial: "49",
+    trunk: true,
+    min: 6,
+    max: 13,
+    group: (n) =>
+      /^15/.test(n)
+        ? cut(n, [4])
+        : /^1[67]/.test(n)
+          ? cut(n, [3])
+          : /^(30|40|69|89)/.test(n)
+            ? cut(n, [2])
+            : [n],
+  },
+  // Vienna is "1"; mobile numbers start 6xx; other area codes vary, so one block.
+  AT: {
+    dial: "43",
+    trunk: true,
+    min: 6,
+    max: 13,
+    group: (n) => (/^6/.test(n) ? cut(n, [3]) : /^1/.test(n) ? cut(n, [1]) : [n]),
+  },
+  // 9 digits, 1-2-2-2-2 ("1 99 00 00 01").
+  FR: { dial: "33", trunk: true, min: 9, max: 9, group: (n) => cut(n, [1, 2, 2, 2, 2]) },
+  // The 0 of a fixed line is part of the number ("+39 06 …"); mobiles start with 3.
+  IT: {
+    dial: "39",
+    trunk: false,
+    zeroStart: true,
+    min: 6,
+    max: 11,
+    group: (n) => (/^3/.test(n) ? cut(n, [3, 3]) : /^0[26]/.test(n) ? cut(n, [2, 4]) : [n]),
+  },
+};
+
+/** The country calling codes with rules, "+" left off: `{ CH: "41", … }`. */
+export const PHONE_DIAL_CODES: Readonly<Record<PhoneCountryCode, string>> = Object.freeze({
+  CH: RULES.CH.dial,
+  LI: RULES.LI.dial,
+  DE: RULES.DE.dial,
+  AT: RULES.AT.dial,
+  FR: RULES.FR.dial,
+  IT: RULES.IT.dial,
+});
+
+/** The countries with rules, in the order a picker offers them by default. */
+export const PHONE_COUNTRIES: readonly PhoneCountryCode[] = Object.freeze(["CH", "LI", "DE", "AT", "FR", "IT"]);
+
+/** Longest dial code first, so "+423" is Liechtenstein before anything shorter. */
+const BY_DIAL = [...PHONE_COUNTRIES].sort((a, b) => RULES[b].dial.length - RULES[a].dial.length);
+
+/** What {@link parsePhone} reads out of a number. */
+export interface ParsedPhone {
+  /** The number in E.164: "+", the country code, the national number. */
+  e164: string;
+  /** The country whose rules read it, or `null` for a generic "+…" number. */
+  country: PhoneCountryCode | null;
+  /** The national significant number — the digits after the country code. For a
+   *  generic number, every digit after the "+" (the country code is not split off). */
+  national: string;
+}
+
+/** A national significant number that passes `rule`, or `null`. */
+function national(digits: string, rule: CountryRule): string | null {
+  const nsn = rule.trunk && digits.startsWith("0") ? digits.slice(1) : digits;
+  // A national number starts with 0 only where 0 is part of it (Italy's fixed lines).
+  if (nsn.startsWith("0") && !rule.zeroStart) return null;
+  if (nsn.length < rule.min || nsn.length > rule.max) return null;
+  return nsn;
+}
+
+/**
+ * Read a typed number. With a leading "+" or "00" the number carries its own country
+ * code — one of the six with rules, or any other (8–15 digits in all, the E.164
+ * limit). Without one it is a national number of `country` (default `"CH"`), its
+ * trunk 0 optional; with `country="other"` a number without "+" cannot be read.
+ *
+ * Spaces, hyphens, dots, slashes and parentheses are ignored ("(030) 1234567"), and
+ * so is the "(0)" of "+41 (0)21 …". Anything else — a letter, an extension ("ext. 12"), a note —
+ * and the result is `null`: the text is not a number these rules can read, and a field
+ * keeps it as it is rather than guess.
+ */
+export function parsePhone(input: string, country: PhoneCountry = "CH"): ParsedPhone | null {
+  const text = input.trim();
+  if (text === "" || !/^\+?[\d\s().\-/]+$/.test(text)) return null;
+  let digits = text.replace(/\D/g, "");
+  let international = text.startsWith("+");
+  if (!international && digits.startsWith("00")) {
+    international = true;
+    digits = digits.slice(2);
+  }
+  if (international) {
+    // "+41 (0)21 …": the bracketed trunk prefix written for callers inside the country.
+    digits = text.replace(/\(\s*0\s*\)/g, "").replace(/\D/g, "").replace(/^00/, "");
+    if (digits.startsWith("0")) return null;
+    const known = BY_DIAL.find((c) => digits.startsWith(RULES[c].dial));
+    if (known) {
+      const rule = RULES[known];
+      const nsn = national(digits.slice(rule.dial.length), rule);
+      return nsn === null ? null : { e164: `+${rule.dial}${nsn}`, country: known, national: nsn };
+    }
+    if (digits.length < 8 || digits.length > 15) return null;
+    return { e164: `+${digits}`, country: null, national: digits };
+  }
+  if (country === "other") return null;
+  const rule = RULES[country];
+  const nsn = national(digits, rule);
+  return nsn === null ? null : { e164: `+${rule.dial}${nsn}`, country, national: nsn };
+}
+
+/** The national number grouped by its country's rules ("21 000 00 01"). */
+export function formatNationalPhone(nsn: string, country: PhoneCountryCode): string {
+  return RULES[country].group(nsn).join(" ");
+}
+
+/**
+ * A number for display: an E.164 number (or anything {@link parsePhone} reads with a
+ * "+") grouped by its country's rules — "+41 21 000 00 01" — and a generic one as
+ * "+" and its digits. Anything it cannot read comes back exactly as it went in, so a
+ * list of contacts can format every row without first sorting out the free text.
+ */
+export function formatPhone(value: string): string {
+  const parsed = value.trim().startsWith("+") ? parsePhone(value, "other") : null;
+  if (!parsed) return value;
+  if (!parsed.country) return parsed.e164;
+  return `+${RULES[parsed.country].dial} ${formatNationalPhone(parsed.national, parsed.country)}`;
+}
+
+/** Whether `value` is in E.164 shape: "+" and 8–15 digits, nothing else. Shape only —
+ *  what {@link PhoneInput} emits for every number it could read. */
+export function isE164(value: string): boolean {
+  return /^\+[1-9]\d{7,14}$/.test(value);
+}