@vaam-apps/ui 0.1.0

package/src/lib/cn.ts

@@ -0,0 +1,168 @@
+import { type ClassValue, clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * `tailwind-merge` taught about (a) this design system's own theme scales
+ * and (b) daisyUI's component modifiers.
+ *
+ * Stock `twMerge` only knows Tailwind's *default* theme and Tailwind's own
+ * utilities. Both gaps produce the same failure shape — a class that still
+ * parses, still looks plausible in the source, and quietly does nothing —
+ * and both were found by probing real class strings from this package
+ * rather than by reading the docs:
+ *
+ * **1. Custom font sizes were being deleted.** `--text-caption` &c. are
+ * theme keys stock `twMerge` has never heard of, so it classified
+ * `text-caption` by its fallback rule — as a *colour* — and then treated
+ * it as conflicting with the actual colour beside it:
+ *
+ * ```text
+ * twMerge("text-caption text-state-danger-fg")  // → "text-state-danger-fg"
+ * twMerge("text-body text-foreground")          // → "text-foreground"
+ * twMerge("text-title-sm text-foreground")      // → "text-foreground"
+ * ```
+ *
+ * Those three strings are, verbatim, `FieldError`, `DetailList` and
+ * `CardHeader`. Every one of them has been rendering at the browser's
+ * default font size rather than its intended step, in both this package
+ * and any app consuming it, since `cn()` was written. Registering the
+ * scale under the `text` theme key is what separates the two groups again.
+ * This predates the tailwind-merge 3.x upgrade — v2.6.0 was checked
+ * directly and drops the same classes — so it is a latent bug being fixed
+ * here, not a regression being papered over.
+ *
+ * **2. Radius utilities did not conflict at all.** `rounded-field` /
+ * `rounded-box` / `rounded-selector` are daisyUI's own radius tiers, and
+ * stock `twMerge` left `rounded-sm rounded-field` as *both* classes, so
+ * the winner fell out of stylesheet order rather than call order — the
+ * opposite of what an override prop is for.
+ *
+ * **3. daisyUI component modifiers did not conflict either**, so
+ * `cn("btn btn-primary", "btn-ghost")` kept both. The group list below is
+ * adapted from the sibling `@vpay/ui` package, which had already derived
+ * it against daisyUI 5's compiled CSS; its central finding is preserved
+ * and worth restating, because it is counter-intuitive:
+ *
+ * > **Colour and style are two groups, not one, for `btn` and `badge`.**
+ * > `.btn-outline`/`.btn-dash` *read* the `--btn-color` variable that
+ * > `.btn-primary` sets, so `btn-primary btn-outline` is how daisyUI 5
+ * > spells "a primary outline button". Collapsed into one group,
+ * > `cn("btn-primary", "btn-outline")` returns `btn-outline` and the
+ * > colour silently vanishes.
+ *
+ * `ghost` and `link` stay with the *colours* rather than the styles,
+ * matching `@vpay/ui` and this package's own `buttonVariants`, where
+ * `ghost` is offered as an alternative to `primary` rather than a
+ * modifier on top of it.
+ *
+ * Scoped to what this package actually emits plus the daisyUI components a
+ * consumer is most likely to reach for directly. Add a group when a
+ * component gains a variant dimension, not ahead of one.
+ */
+type ExtraClassGroupId =
+  | "daisy-btn-variant"
+  | "daisy-btn-style"
+  | "daisy-btn-size"
+  | "daisy-badge-variant"
+  | "daisy-badge-style"
+  | "daisy-badge-size"
+  | "daisy-alert-variant"
+  | "daisy-alert-style"
+  | "daisy-input-variant"
+  | "daisy-select-variant"
+  | "daisy-select-size"
+  | "daisy-checkbox-variant"
+  | "daisy-checkbox-size"
+  | "daisy-radio-variant"
+  | "daisy-radio-size"
+  | "daisy-toggle-variant"
+  | "daisy-toggle-size"
+  | "daisy-card-size"
+  | "daisy-table-size"
+  | "daisy-tabs-style"
+  | "daisy-tabs-size"
+  | "daisy-progress-variant"
+  | "daisy-loading-type"
+  | "daisy-loading-size";
+
+/**
+ * The `--text-*` steps declared in `styles/theme.css`. Kept in sync with
+ * that file by `theme-tokens.test.ts`, which parses the stylesheet rather
+ * than trusting this list.
+ */
+const FONT_SIZES = [
+  "micro",
+  "caption",
+  "body",
+  "prose",
+  "title-sm",
+  "title",
+  "metric",
+  "metric-lg",
+] as const;
+
+/** daisyUI's radius tiers, which its own components read from. */
+const RADII = ["selector", "field", "box"] as const;
+
+const DAISY_COLOURS = [
+  "primary",
+  "secondary",
+  "accent",
+  "neutral",
+  "info",
+  "success",
+  "warning",
+  "error",
+] as const;
+
+const DAISY_SIZES = ["xs", "sm", "md", "lg", "xl"] as const;
+
+const twMerge = extendTailwindMerge<ExtraClassGroupId>({
+  extend: {
+    theme: {
+      // Registering these as *font sizes* is what stops `text-caption`
+      // being mistaken for a colour and dropped. See point 1 above.
+      text: [...FONT_SIZES],
+      radius: [...RADII],
+    },
+    classGroups: {
+      "daisy-btn-variant": [{ btn: [...DAISY_COLOURS, "ghost", "link"] }],
+      "daisy-btn-style": [{ btn: ["outline", "soft", "dash"] }],
+      "daisy-btn-size": [{ btn: [...DAISY_SIZES, "wide", "block", "square", "circle"] }],
+      "daisy-badge-variant": [{ badge: [...DAISY_COLOURS, "ghost"] }],
+      "daisy-badge-style": [{ badge: ["outline", "soft", "dash"] }],
+      "daisy-badge-size": [{ badge: [...DAISY_SIZES] }],
+      "daisy-alert-variant": [{ alert: ["info", "success", "warning", "error"] }],
+      "daisy-alert-style": [{ alert: ["outline", "soft", "dash"] }],
+      "daisy-input-variant": [{ input: [...DAISY_COLOURS, "ghost"] }],
+      "daisy-select-variant": [{ select: [...DAISY_COLOURS, "ghost"] }],
+      "daisy-select-size": [{ select: [...DAISY_SIZES] }],
+      "daisy-checkbox-variant": [{ checkbox: [...DAISY_COLOURS] }],
+      "daisy-checkbox-size": [{ checkbox: [...DAISY_SIZES] }],
+      "daisy-radio-variant": [{ radio: [...DAISY_COLOURS] }],
+      "daisy-radio-size": [{ radio: [...DAISY_SIZES] }],
+      "daisy-toggle-variant": [{ toggle: [...DAISY_COLOURS] }],
+      "daisy-toggle-size": [{ toggle: [...DAISY_SIZES] }],
+      "daisy-card-size": [{ card: [...DAISY_SIZES] }],
+      "daisy-table-size": [{ table: [...DAISY_SIZES] }],
+      "daisy-tabs-style": [{ tabs: ["box", "border", "lift"] }],
+      "daisy-tabs-size": [{ tabs: [...DAISY_SIZES] }],
+      "daisy-progress-variant": [{ progress: [...DAISY_COLOURS] }],
+      "daisy-loading-type": [{ loading: ["spinner", "dots", "ring", "ball", "bars", "infinity"] }],
+      "daisy-loading-size": [{ loading: [...DAISY_SIZES] }],
+    },
+  },
+});
+
+/**
+ * Merge class names, resolving conflicting utilities so the *last* one
+ * wins — Tailwind's own, this design system's custom scales, and daisyUI's
+ * component modifiers alike.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+/** The font-size steps this package registers with `tailwind-merge`. Exported
+ * for `theme-tokens.test.ts`, which checks them against `theme.css`. */
+export const REGISTERED_FONT_SIZES: readonly string[] = FONT_SIZES;

package/src/lib/money.ts

@@ -0,0 +1,164 @@
+/**
+ * Money formatting from minor units, without losing precision.
+ *
+ * # Why this exists
+ *
+ * Money is the single most duplicated formatter in every application that
+ * handles it. The sibling payments codebase this package was generalised
+ * for had **four** independent implementations at the time of writing, in
+ * four packages, with four different signatures and three different
+ * hard-coded tables of which currencies have no decimal places — and one
+ * of them divided by a power of ten in floating point, which silently
+ * corrupts any amount past 2^53 minor units. All four also got the
+ * three-decimal currencies wrong, because every hand-written table
+ * remembers `JPY` and `XAF` and forgets `KWD` and `BHD`.
+ *
+ * # Three decisions, each load-bearing
+ *
+ * **Minor units in, never a decimal number.** An amount is an integer
+ * count of the currency's smallest unit — that is how it is stored, how
+ * it is transmitted, and the only representation that cannot be wrong by
+ * a rounding error. `bigint` and a decimal-digit `string` are accepted
+ * alongside `number` so an `i64` from a Rust backend survives the trip;
+ * JSON gives it to you as a string precisely because `number` cannot hold
+ * it.
+ *
+ * **The exponent comes from `Intl`, not from a table here.** `Intl`
+ * already ships the ISO 4217 exponent for every currency, so there is no
+ * list to maintain and no currency this gets wrong. Verified rather than
+ * assumed: `XAF`/`XOF`/`JPY`/`CLP`/`VND` resolve to 0 and `KWD`/`BHD` to
+ * 3, which is exactly the set hand-written tables miss.
+ *
+ * **The scaling is string surgery, never division.** The minor-unit
+ * integer is split into whole and fractional parts by digit position and
+ * handed to `Intl.NumberFormat` as a string, which accepts arbitrary
+ * precision. No value is ever converted to a float, so an amount larger
+ * than `Number.MAX_SAFE_INTEGER` formats exactly.
+ */
+
+/** An integer count of a currency's smallest unit. */
+export type MinorUnits = number | bigint | string;
+
+export interface FormatMoneyOptions {
+  /** BCP 47 tag. Defaults to the runtime's own locale.
+   *
+   * Pass one explicitly anywhere the output must be stable — a test, a
+   * server-rendered page whose HTML must match the client's hydration, or
+   * a value a human will compare against a bank statement. */
+  locale?: string | undefined;
+  /** `symbol` → `FCFA 5,000`; `code` → `XAF 5,000`; `none` → `5,000`.
+   *
+   * `code` is the honest default for an operator console: currency
+   * symbols are ambiguous across locales ($ alone names at least a dozen
+   * currencies) and an operator reconciling against a ledger needs the
+   * ISO code. */
+  display?: "symbol" | "code" | "none";
+  /** Force a sign even when positive, e.g. for a ledger delta. */
+  signDisplay?: Intl.NumberFormatOptions["signDisplay"];
+}
+
+const DIGITS_ONLY = /^-?\d+$/;
+
+/** Cache: constructing an `Intl.NumberFormat` is the expensive part, and a
+ * table renders the same currency once per row. */
+const formatters = new Map<string, Intl.NumberFormat>();
+
+function formatter(key: string, options: Intl.NumberFormatOptions, locale?: string) {
+  const cacheKey = `${locale ?? ""}|${key}`;
+  let found = formatters.get(cacheKey);
+  if (found === undefined) {
+    found = new Intl.NumberFormat(locale, options);
+    formatters.set(cacheKey, found);
+  }
+  return found;
+}
+
+/**
+ * How many decimal places this currency has, per ISO 4217, as `Intl`
+ * knows it. `2` for a currency `Intl` has never heard of — the majority
+ * case, and the same fallback `Intl` itself uses.
+ */
+export function currencyExponent(currency: string, locale?: string): number {
+  return (
+    formatter(`exp:${currency}`, { style: "currency", currency }, locale).resolvedOptions()
+      .maximumFractionDigits ?? 2
+  );
+}
+
+/**
+ * Shifts a minor-unit integer right by `exponent` places, as a string.
+ *
+ * `"500"`, 2 → `"5.00"`; `"5"`, 2 → `"0.05"`; `"-5"`, 2 → `"-0.05"`;
+ * `"5000"`, 0 → `"5000"`.
+ */
+function shiftDecimal(digits: string, exponent: number): string {
+  const negative = digits.startsWith("-");
+  const abs = negative ? digits.slice(1) : digits;
+  const sign = negative ? "-" : "";
+  if (exponent === 0) return sign + abs;
+  const padded = abs.padStart(exponent + 1, "0");
+  const whole = padded.slice(0, padded.length - exponent);
+  const fraction = padded.slice(padded.length - exponent);
+  return `${sign}${whole}.${fraction}`;
+}
+
+/**
+ * `formatMoney(500000, "XAF")` → `"XAF 500,000"`.
+ * `formatMoney("1250", "USD")` → `"USD 12.50"`.
+ *
+ * @throws if `minorUnits` is not an integer. A non-integer minor-unit
+ * amount is always a bug — usually a caller that already divided — and
+ * silently rounding it here would hide the real error at the point where
+ * it is least visible.
+ */
+export function formatMoney(
+  minorUnits: MinorUnits,
+  currency: string,
+  options: FormatMoneyOptions = {},
+): string {
+  const { locale, display = "code", signDisplay } = options;
+
+  let digits: string;
+  if (typeof minorUnits === "bigint") {
+    digits = minorUnits.toString();
+  } else if (typeof minorUnits === "number") {
+    if (!Number.isInteger(minorUnits)) {
+      throw new TypeError(
+        `formatMoney expects an integer count of minor units, got ${minorUnits} (${currency}). ` +
+          "Pass 1250 for USD 12.50, not 12.5.",
+      );
+    }
+    digits = minorUnits.toFixed(0);
+  } else {
+    const trimmed = minorUnits.trim();
+    if (!DIGITS_ONLY.test(trimmed)) {
+      throw new TypeError(
+        `formatMoney expects an integer count of minor units, got ${JSON.stringify(minorUnits)} (${currency}).`,
+      );
+    }
+    digits = trimmed;
+  }
+
+  const exponent = currencyExponent(currency, locale);
+  const value = shiftDecimal(digits, exponent);
+
+  const intlOptions: Intl.NumberFormatOptions =
+    display === "none"
+      ? {
+          style: "decimal",
+          minimumFractionDigits: exponent,
+          maximumFractionDigits: exponent,
+        }
+      : {
+          style: "currency",
+          currency,
+          currencyDisplay: display,
+        };
+  if (signDisplay !== undefined) intlOptions.signDisplay = signDisplay;
+
+  return formatter(
+    `fmt:${currency}:${display}:${signDisplay ?? ""}:${exponent}`,
+    intlOptions,
+    locale,
+  ).format(value as unknown as number);
+}

package/src/lib/omit-undefined.ts

@@ -0,0 +1,25 @@
+/**
+ * Strips every key whose value is explicitly `undefined`, and narrows the
+ * return type to match: `exactOptionalPropertyTypes` (this workspace's own
+ * `tsconfig`) makes `{ disabled?: boolean }` reject a spread whose *type*
+ * is `{ disabled?: boolean | undefined }` even when the value at runtime is
+ * always defined for the keys that matter — every `React.*HTMLAttributes`
+ * type declares its optional fields as `T | undefined` explicitly, but
+ * Headless UI's own prop types (`ListboxProps`, `MenuItemProps`, `LabelProps`,
+ * …) declare theirs as plain `T`. Spreading `...props` from a native-element
+ * prop type onto a Headless UI component hits this every time (found
+ * porting `select.tsx`/`dropdown-menu.tsx`/`label.tsx` off Radix, D3) —
+ * this is the one general fix rather than a one-off cast at each call site.
+ */
+export function omitUndefined<T extends Record<string, unknown>>(
+  props: T,
+): { [K in keyof T]: Exclude<T[K], undefined> } {
+  const result = {} as { [K in keyof T]: Exclude<T[K], undefined> };
+  for (const key of Object.keys(props) as (keyof T)[]) {
+    const value = props[key];
+    if (value !== undefined) {
+      result[key] = value as Exclude<T[keyof T], undefined>;
+    }
+  }
+  return result;
+}