@zeno-lib/forms 0.1.0 → 0.2.1

package/src/lib/formatted-number.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "vitest"
+import {
+  formatNumber,
+  getNumberSeparators,
+  mapCaret,
+  parseLocaleNumber,
+  parseTypedNumber,
+  roundTo,
+} from "./formatted-number"
+
+// Swiss grouping is an apostrophe, but which one (’ or ') depends on the
+// runtime's CLDR data, so derive it instead of hard-coding it.
+const CH = getNumberSeparators("de-CH").group
+const ch = (text: string) => text.replaceAll("’", CH)
+
+describe("getNumberSeparators", () => {
+  test("reads the locale's separators", () => {
+    expect(getNumberSeparators("de-CH").decimal).toBe(".")
+    expect(["’", "'"]).toContain(CH)
+    expect(getNumberSeparators("de-DE")).toEqual({ decimal: ",", group: "." })
+    expect(getNumberSeparators("en-US")).toEqual({ decimal: ".", group: "," })
+  })
+})
+
+describe("formatNumber", () => {
+  test("groups thousands per locale", () => {
+    const options = { maximumFractionDigits: 2 }
+    expect(formatNumber(1_234_567.5, { ...options, locale: "de-CH" })).toBe(
+      ch("1’234’567.5")
+    )
+    expect(formatNumber(1_234_567.5, { ...options, locale: "de-DE" })).toBe(
+      "1.234.567,5"
+    )
+  })
+
+  test("pads with minimumFractionDigits, uses an ASCII minus, empties null", () => {
+    expect(
+      formatNumber(-12.5, {
+        locale: "de-CH",
+        maximumFractionDigits: 2,
+        minimumFractionDigits: 2,
+      })
+    ).toBe("-12.50")
+    expect(formatNumber(null, { maximumFractionDigits: 2 })).toBe("")
+    expect(formatNumber(Number.NaN, { maximumFractionDigits: 2 })).toBe("")
+  })
+
+  test("can skip grouping", () => {
+    expect(
+      formatNumber(2024, {
+        locale: "de-CH",
+        maximumFractionDigits: 0,
+        useGrouping: false,
+      })
+    ).toBe("2024")
+  })
+})
+
+describe("parseTypedNumber", () => {
+  const chf = { locale: "de-CH", maximumFractionDigits: 2 }
+
+  test("re-inserts group separators while typing", () => {
+    expect(parseTypedNumber("1234567", chf)).toEqual({
+      text: ch("1’234’567"),
+      value: 1_234_567,
+    })
+    expect(parseTypedNumber(ch("1’2345"), chf)).toEqual({
+      text: ch("12’345"),
+      value: 12_345,
+    })
+  })
+
+  test("keeps a trailing decimal separator and truncates extra fraction digits", () => {
+    expect(parseTypedNumber("12.", chf)).toEqual({ text: "12.", value: 12 })
+    expect(parseTypedNumber("12.345", chf)).toEqual({
+      text: "12.34",
+      value: 12.34,
+    })
+    expect(parseTypedNumber(".5", chf)).toEqual({ text: "0.5", value: 0.5 })
+  })
+
+  test("uses the locale's decimal separator only", () => {
+    const eur = { locale: "de-DE", maximumFractionDigits: 2 }
+    expect(parseTypedNumber("1.2345", eur)).toEqual({
+      text: "12.345",
+      value: 12_345,
+    })
+    expect(parseTypedNumber("12,5", eur)).toEqual({ text: "12,5", value: 12.5 })
+  })
+
+  test("handles empties, minus and leading zeros", () => {
+    expect(parseTypedNumber("", chf)).toEqual({ text: "", value: null })
+    expect(parseTypedNumber("abc", chf)).toEqual({ text: "", value: null })
+    expect(parseTypedNumber("-", chf)).toEqual({ text: "-", value: null })
+    expect(parseTypedNumber("-12", chf)).toEqual({ text: "-12", value: -12 })
+    expect(parseTypedNumber("-12", { ...chf, allowNegative: false })).toEqual({
+      text: "12",
+      value: 12,
+    })
+    expect(parseTypedNumber("007", chf)).toEqual({ text: "7", value: 7 })
+  })
+
+  test("integers only and a digit cap", () => {
+    expect(
+      parseTypedNumber("20245", {
+        maxIntegerDigits: 4,
+        maximumFractionDigits: 0,
+        useGrouping: false,
+      })
+    ).toEqual({ text: "2024", value: 2024 })
+    expect(
+      parseTypedNumber("12.5", { locale: "de-CH", maximumFractionDigits: 0 })
+    ).toEqual({ text: "125", value: 125 })
+  })
+})
+
+describe("parseLocaleNumber", () => {
+  test.each([
+    ["CHF 1'234.50", "de-CH", 1234.5],
+    ["1’234’567", "de-CH", 1_234_567],
+    ["1.234,50 €", "de-CH", 1234.5],
+    ["1,234.50", "de-DE", 1234.5],
+    ["1,234", "de-CH", 1234],
+    ["1,5", "de-CH", 1.5],
+    ["1.234", "de-DE", 1234],
+    ["1.5", "de-DE", 1.5],
+    ["1 234 567,89", "fr-FR", 1_234_567.89],
+    ["−42", "en-US", -42],
+    ["(42.10)", "en-US", -42.1],
+    ["1.234.567", "en-US", 1_234_567],
+  ])("%s (%s) → %d", (text, locale, expected) => {
+    expect(parseLocaleNumber(text, locale)).toBe(expected)
+  })
+
+  test("returns null without digits", () => {
+    expect(parseLocaleNumber("CHF", "de-CH")).toBeNull()
+    expect(parseLocaleNumber("", "de-CH")).toBeNull()
+  })
+})
+
+describe("mapCaret", () => {
+  test("keeps the caret after the same digit once separators move", () => {
+    // Typed "5" after "1234" with the caret at the end: "12345" → "12’345".
+    expect(mapCaret("12345", 5, ch("12’345"), "de-CH")).toBe(6)
+    // Caret after the "2" of "1’2|34": same digit in "1’234" is index 3.
+    expect(mapCaret(ch("1’234"), 3, ch("1’234"), "de-CH")).toBe(3)
+    expect(mapCaret("", 0, "", "de-CH")).toBe(0)
+  })
+})
+
+describe("roundTo", () => {
+  test("rounds half away from zero without float drift", () => {
+    expect(roundTo(1.005, 2)).toBe(1.01)
+    expect(roundTo(-1.005, 2)).toBe(-1.01)
+    expect(roundTo(0.07 * 100, 2)).toBe(7)
+  })
+})

package/src/lib/formatted-number.ts

@@ -0,0 +1,307 @@
+// Pure, locale-aware helpers behind `useFormattedNumber` (and therefore the
+// money / percentage / year fields). UI-free so they ship on npm and can be
+// unit-tested without a DOM.
+//
+// Display strings always use ASCII digits and an ASCII `-` for negatives, with
+// the locale's own group and decimal separators (e.g. `de-CH` → `1’234.5`,
+// `de-DE` → `1.234,5`, `fr-FR` → `1 234,5`).
+
+type NumberSeparators = {
+  /** Thousands separator, e.g. `’` for `de-CH`, `,` for `en-US`. */
+  group: string
+  /** Decimal separator, e.g. `.` for `de-CH`, `,` for `de-DE`. */
+  decimal: string
+}
+
+type FormatNumberOptions = {
+  locale?: string
+  /** Maximum digits after the decimal separator. `0` means integers only. */
+  maximumFractionDigits: number
+  /** Minimum digits after the decimal separator (pads with zeros). */
+  minimumFractionDigits?: number
+  /** Insert group (thousands) separators. Defaults to `true`. */
+  useGrouping?: boolean
+}
+
+type TypedNumber = {
+  /** The re-formatted text to show in the input. */
+  text: string
+  /** The parsed number, or `null` when the text holds no digits. */
+  value: number | null
+}
+
+type ParseTypedOptions = {
+  locale?: string
+  maximumFractionDigits: number
+  useGrouping?: boolean
+  allowNegative?: boolean
+  /** Drop integer digits beyond this count (e.g. `4` for a year). */
+  maxIntegerDigits?: number
+}
+
+const separatorCache = new Map<string, NumberSeparators>()
+
+// Minus signs a user may type or paste: ASCII hyphen-minus, U+2212 (what Intl
+// emits for some locales), and the en dash.
+const MINUS_SIGNS = /[-−–]/
+const LEADING_MINUS = /^[^\d]*[-−–]/
+const NON_DIGIT = /\D/g
+const LEADING_ZEROS = /^0+(?=\d)/
+const DIGIT = /\d/
+const DIGITS = /\d/g
+const PARENTHESIZED = /^\s*\(.*\)\s*$/
+const NOT_NUMERIC = /[^\d.,]/g
+const UNICODE_MINUS = /\u2212/g
+
+function getNumberSeparators(locale?: string): NumberSeparators {
+  const key = locale ?? ""
+  const cached = separatorCache.get(key)
+  if (cached) {
+    return cached
+  }
+  const parts = new Intl.NumberFormat(locale, {
+    numberingSystem: "latn",
+  }).formatToParts(1_234_567.5)
+  const separators = {
+    decimal: parts.find((p) => p.type === "decimal")?.value ?? ".",
+    group: parts.find((p) => p.type === "group")?.value ?? ",",
+  }
+  separatorCache.set(key, separators)
+  return separators
+}
+
+function normalizeMinus(text: string): string {
+  return text.replace(UNICODE_MINUS, "-")
+}
+
+/** Format a number for display (on blur, on reset, on first render). */
+function formatNumber(
+  value: number | null | undefined,
+  {
+    locale,
+    maximumFractionDigits,
+    minimumFractionDigits = 0,
+    useGrouping = true,
+  }: FormatNumberOptions
+): string {
+  if (value == null || !Number.isFinite(value)) {
+    return ""
+  }
+  return normalizeMinus(
+    new Intl.NumberFormat(locale, {
+      maximumFractionDigits,
+      minimumFractionDigits: Math.min(
+        minimumFractionDigits,
+        maximumFractionDigits
+      ),
+      numberingSystem: "latn",
+      useGrouping,
+    }).format(value)
+  )
+}
+
+function groupIntegerDigits(
+  digits: string,
+  locale: string | undefined,
+  useGrouping: boolean
+): string {
+  if (!useGrouping || digits.length <= 3) {
+    return digits
+  }
+  // BigInt keeps long digit strings exact while Intl inserts the separators.
+  return new Intl.NumberFormat(locale, {
+    numberingSystem: "latn",
+    useGrouping: true,
+  }).format(BigInt(digits))
+}
+
+function toNumber(
+  negative: boolean,
+  intDigits: string,
+  fracDigits: string
+): number | null {
+  if (intDigits === "" && fracDigits === "") {
+    return null
+  }
+  const value = Number(`${intDigits || "0"}.${fracDigits || "0"}`)
+  return negative && value !== 0 ? -value : value
+}
+
+/**
+ * Re-format what the user is typing. Only the locale's decimal separator
+ * starts the fraction; every other non-digit is dropped and group separators
+ * are re-inserted. Keeps a trailing decimal separator (`"12."`) so typing
+ * isn't fought, and truncates fraction digits beyond `maximumFractionDigits`.
+ */
+function parseTypedNumber(
+  raw: string,
+  {
+    locale,
+    maximumFractionDigits,
+    useGrouping = true,
+    allowNegative = true,
+    maxIntegerDigits,
+  }: ParseTypedOptions
+): TypedNumber {
+  const { decimal } = getNumberSeparators(locale)
+  const negative = allowNegative && LEADING_MINUS.test(raw)
+  const decimalIndex = maximumFractionDigits > 0 ? raw.indexOf(decimal) : -1
+  const intRaw = decimalIndex === -1 ? raw : raw.slice(0, decimalIndex)
+  const fracRaw = decimalIndex === -1 ? "" : raw.slice(decimalIndex + 1)
+
+  let intDigits = intRaw.replace(NON_DIGIT, "").replace(LEADING_ZEROS, "")
+  if (maxIntegerDigits !== undefined) {
+    intDigits = intDigits.slice(0, maxIntegerDigits)
+  }
+  const fracDigits = fracRaw
+    .replace(NON_DIGIT, "")
+    .slice(0, maximumFractionDigits)
+  const hasDecimal = decimalIndex !== -1
+
+  const sign = negative ? "-" : ""
+  const intText =
+    intDigits === "" && hasDecimal
+      ? "0"
+      : groupIntegerDigits(intDigits, locale, useGrouping)
+  const text = `${sign}${intText}${hasDecimal ? `${decimal}${fracDigits}` : ""}`
+
+  return { text, value: toNumber(negative, intDigits, fracDigits) }
+}
+
+// Decide which of `.` / `,` is the decimal separator in pasted text, which may
+// come from another locale than the input's (a spreadsheet, a bank statement).
+function detectDecimalSeparator(
+  text: string,
+  localeDecimal: string
+): string | null {
+  const lastDot = text.lastIndexOf(".")
+  const lastComma = text.lastIndexOf(",")
+  if (lastDot !== -1 && lastComma !== -1) {
+    // Both present: whichever comes last is the decimal separator.
+    return lastDot > lastComma ? "." : ","
+  }
+  let candidate: string | null = null
+  if (lastDot !== -1) {
+    candidate = "."
+  } else if (lastComma !== -1) {
+    candidate = ","
+  }
+  if (candidate === null) {
+    return null
+  }
+  const occurrences = text.split(candidate).length - 1
+  if (occurrences > 1) {
+    return null // repeated → a group separator
+  }
+  if (candidate === localeDecimal) {
+    return candidate
+  }
+  // A lone foreign separator followed by exactly three digits reads as a
+  // thousands group (`1,234` in a `de-CH` input); otherwise it's a decimal.
+  const after = text.slice(text.lastIndexOf(candidate) + 1)
+  const digitsAfter = after.match(DIGITS)?.length ?? 0
+  return digitsAfter === 3 ? null : candidate
+}
+
+/**
+ * Parse free-form text (pasted, or a value from another system) into a
+ * number. Tolerates currency codes and symbols, any whitespace or apostrophe
+ * as grouping, `.` or `,` as the decimal separator, and `−`/`-` for negatives.
+ * Returns `null` when no digits are found.
+ */
+function parseLocaleNumber(text: string, locale?: string): number | null {
+  if (!DIGIT.test(text)) {
+    return null
+  }
+  const { decimal } = getNumberSeparators(locale)
+  const negative = LEADING_MINUS.test(text) || PARENTHESIZED.test(text)
+  const kept = text.replace(NOT_NUMERIC, "")
+  const decimalSeparator = detectDecimalSeparator(kept, decimal)
+  let intPart = kept
+  let fracPart = ""
+  if (decimalSeparator) {
+    const index = kept.lastIndexOf(decimalSeparator)
+    intPart = kept.slice(0, index)
+    fracPart = kept.slice(index + 1)
+  }
+  return toNumber(
+    negative,
+    intPart.replace(NON_DIGIT, ""),
+    fracPart.replace(NON_DIGIT, "")
+  )
+}
+
+// Characters that survive re-formatting: digits, the decimal separator and a
+// leading minus. Counting them before the caret lets us put the caret back in
+// the same logical place after separators were inserted or removed.
+function countSignificant(text: string, end: number, decimal: string): number {
+  let count = 0
+  for (let i = 0; i < end && i < text.length; i++) {
+    const char = text[i] as string
+    if (DIGIT.test(char) || char === decimal || MINUS_SIGNS.test(char)) {
+      count++
+    }
+  }
+  return count
+}
+
+function caretForSignificant(
+  text: string,
+  significant: number,
+  decimal: string
+): number {
+  if (significant <= 0) {
+    return 0
+  }
+  let count = 0
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] as string
+    if (DIGIT.test(char) || char === decimal || char === "-") {
+      count++
+      if (count === significant) {
+        return i + 1
+      }
+    }
+  }
+  return text.length
+}
+
+/**
+ * Where the caret should land in `next` after the user edited `raw` with the
+ * caret at `caret`.
+ */
+function mapCaret(
+  raw: string,
+  caret: number,
+  next: string,
+  locale?: string
+): number {
+  const { decimal } = getNumberSeparators(locale)
+  return caretForSignificant(
+    next,
+    countSignificant(raw, caret, decimal),
+    decimal
+  )
+}
+
+/** Round to `digits` decimals without the `1.005 → 1.00` float surprise. */
+function roundTo(value: number, digits: number): number {
+  const factor = 10 ** digits
+  const rounded = Math.round((Math.abs(value) + Number.EPSILON) * factor)
+  return (Math.sign(value) * rounded) / factor
+}
+
+export type {
+  FormatNumberOptions,
+  NumberSeparators,
+  ParseTypedOptions,
+  TypedNumber,
+}
+export {
+  formatNumber,
+  getNumberSeparators,
+  mapCaret,
+  parseLocaleNumber,
+  parseTypedNumber,
+  roundTo,
+}

package/src/lib/submit-action.test-d.ts

@@ -0,0 +1,83 @@
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import { useForm } from "../create-form"
+import type { ActionResult } from "./action-result"
+import { submitAction } from "./submit-action"
+
+const schema = z.object({
+  name: z.string(),
+  percentage: z.string().transform(Number),
+})
+type Values = z.input<typeof schema>
+
+// What `defineFormAction` in `@zeno-lib/db/next` produces, restated here so
+// the structural contract is pinned without depending on that package.
+type ServerActionError = {
+  readonly fieldErrors: Record<string, string[]>
+  readonly formErrors: string[]
+}
+type ServerActionResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ServerActionError }
+
+declare function saveShare(input: {
+  name: string
+  percentage: number
+}): Promise<ServerActionResult<{ id: number }>>
+declare function saveRaw(input: Values): Promise<ServerActionResult<Values>>
+
+test("infers the data type from the action, with no explicit generics", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: async (submit) => {
+      const result = await submitAction(submit, saveShare, { schema })
+      expectTypeOf(result).toEqualTypeOf<ActionResult<{ id: number }>>()
+      if (result.ok) {
+        expectTypeOf(result.data).toEqualTypeOf<{ id: number }>()
+      }
+    },
+  })
+})
+
+test("without a schema the action must accept the form values", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) => submitAction(submit, saveRaw, { reset: true }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    // @ts-expect-error: the action wants `percentage: number`; pass `schema` to transform.
+    onSubmit: (submit) => submitAction(submit, saveShare),
+  })
+})
+
+test("with a schema the action receives the schema output", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      // @ts-expect-error: the schema outputs `percentage: number`, the action wants a string.
+      submitAction(submit, saveRaw, { schema }),
+  })
+})
+
+test("reset: true is only offered when the data has the form's shape", () => {
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      // @ts-expect-error: `{ id: number }` is not the form's values.
+      submitAction(submit, saveShare, { reset: true, schema }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      submitAction(submit, saveShare, { reset: "values", schema }),
+  })
+  useForm({
+    defaultValues: { name: "", percentage: "" },
+    onSubmit: (submit) =>
+      submitAction(submit, saveShare, {
+        reset: (data) => ({ name: String(data.id), percentage: "" }),
+        schema,
+      }),
+  })
+})