@beyondwork/docx-react-component 1.0.50 → 1.0.51

package/src/ui-tailwind/chart/render/number-format.ts

@@ -0,0 +1,287 @@
+/**
+ * Excel-style number-format engine for chart tick labels + data labels
+ * (Stage 3A, pure math).
+ *
+ * Supports the top ~20 real-world format codes:
+ *   - Digit placeholders: `0` (required digit), `#` (optional digit).
+ *   - Decimal point: `.`.
+ *   - Thousands separator: `,` between digit placeholders.
+ *   - Percent: `%` — scales value by 100 and appends `%`.
+ *   - Currency: `$` and quoted literals like `"$"`.
+ *   - Scientific: `0.00E+00` style.
+ *   - Date tokens: `yyyy` `yy` `mm` `m` `mmm` `mmmm` `dd` `d`.
+ *   - Time tokens: `hh` `h` `mm` (contextual) `ss`.
+ *   - `General`: fall back to JavaScript's default `toString()`.
+ *   - `@`: text placeholder — returns the value verbatim (stringified).
+ *
+ * Out of scope (deferred post-v1):
+ *   - Conditional formats (`[>100]...;...`).
+ *   - Locale-specific formats (`[$-409]`).
+ *   - Color tokens (`[Red]`, `[Blue]`).
+ *   - Fraction formats (`# ?/?`).
+ *
+ * Unknown / malformed codes fall through to `String(value)` so the
+ * renderer never produces `NaN` or an exception at render time.
+ */
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function formatNumber(value: number, code: string | undefined): string {
+  if (code === undefined || code === "" || code.toLowerCase() === "general") {
+    return Number.isFinite(value) ? String(value) : "";
+  }
+  if (code === "@") return String(value);
+
+  if (!Number.isFinite(value)) return "";
+
+  // Date/time codes contain y/m/d/h/s letter tokens outside literals.
+  // Detect and route to the date formatter.
+  if (isDateFormatCode(code)) {
+    return formatDate(value, code);
+  }
+
+  // Scientific: "0.00E+00" / "0E+0"
+  if (/E[+-]?0/iu.test(code)) {
+    return formatScientific(value, code);
+  }
+
+  return formatDecimal(value, code);
+}
+
+// ---------------------------------------------------------------------------
+// Decimal formatter
+// ---------------------------------------------------------------------------
+
+function formatDecimal(value: number, code: string): string {
+  // Extract percent, currency prefix, thousands separator, and decimal
+  // precision from the format code. We scan for digit placeholders
+  // (0, #) and the decimal point.
+  let working = value;
+  const tokens = tokenizeLiterals(code);
+
+  // Find a sample of the digit-placeholder substring to measure precision.
+  const digitRun = tokens
+    .filter((t) => t.kind === "digits")
+    .map((t) => t.value)
+    .join("");
+
+  // Percent is a separate token from the tokenizer; scale accordingly.
+  const hasPercent = tokens.some((t) => t.kind === "percent");
+  if (hasPercent) working *= 100;
+
+  const decimalIdx = digitRun.indexOf(".");
+  const fractionDigits = decimalIdx >= 0 ? digitRun.length - decimalIdx - 1 : 0;
+  const useThousands = /,(?=[0#])/.test(digitRun);
+  const absWorking = Math.abs(working);
+
+  const [intPart, fracPart] = absWorking
+    .toFixed(Math.max(0, fractionDigits))
+    .split(".");
+
+  const intGrouped = useThousands ? groupThousands(intPart!) : intPart!;
+  const formatted =
+    fracPart !== undefined && fracPart.length > 0
+      ? `${intGrouped}.${fracPart}`
+      : intGrouped;
+  const signed = working < 0 ? `-${formatted}` : formatted;
+
+  // Stitch back prefix/suffix literals around the numeric body. We
+  // replace the first run of digit placeholders with the formatted
+  // number; other literals (currency symbols, spaces, "%") stay.
+  let produced = false;
+  const parts: string[] = [];
+  for (const t of tokens) {
+    if (t.kind === "digits") {
+      if (!produced) {
+        parts.push(signed);
+        produced = true;
+      }
+      // drop subsequent digit runs — they were part of the numeric
+      // template we already substituted.
+    } else if (t.kind === "literal") {
+      parts.push(t.value);
+    } else if (t.kind === "percent") {
+      parts.push("%");
+    } else if (t.kind === "currency") {
+      parts.push(t.value);
+    }
+  }
+  if (!produced) parts.push(signed);
+  return parts.join("");
+}
+
+function groupThousands(intPart: string): string {
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+// ---------------------------------------------------------------------------
+// Scientific formatter
+// ---------------------------------------------------------------------------
+
+function formatScientific(value: number, code: string): string {
+  const match = /(0+)(\.0+)?[eE]([+-]?)(0+)/u.exec(code);
+  if (!match) return value.toExponential();
+  const mantissaInt = match[1]!.length;
+  const mantissaFrac = match[2] ? match[2].length - 1 : 0;
+  const signToken = match[3] ?? "";
+  const fracDigits = mantissaInt + mantissaFrac - 1;
+  const exp = value === 0 ? 0 : Math.floor(Math.log10(Math.abs(value)));
+  const mantissa = value / Math.pow(10, exp);
+  const mantissaStr = mantissa.toFixed(Math.max(0, fracDigits));
+  const sign = signToken === "+" ? (exp >= 0 ? "+" : "-") : exp < 0 ? "-" : "";
+  const expStr = String(Math.abs(exp)).padStart(match[4]!.length, "0");
+  return `${mantissaStr}E${sign}${expStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Date formatter
+// ---------------------------------------------------------------------------
+
+const DATE_CODE_PATTERN = /\b(yyyy|yy|mmmm|mmm|mm|m|dd|d|hh|h|ss)\b/iu;
+
+function isDateFormatCode(code: string): boolean {
+  // Strip quoted literals to avoid false positives on quoted text.
+  const stripped = code.replace(/"[^"]*"/g, "");
+  return DATE_CODE_PATTERN.test(stripped);
+}
+
+function formatDate(serial: number, code: string): string {
+  // Excel serial → Date. Epoch 1899-12-30.
+  const ms = (serial - 25569) * 86_400_000;
+  const date = new Date(ms);
+  const y = date.getUTCFullYear();
+  const m = date.getUTCMonth() + 1;
+  const d = date.getUTCDate();
+  const hh = date.getUTCHours();
+  const mi = date.getUTCMinutes();
+  const ss = date.getUTCSeconds();
+
+  const MONTHS_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const MONTHS_LONG = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+  // Parse the format by splitting on literal-vs-token boundaries.
+  // Process longest tokens first (yyyy before yy, mmmm before mmm/mm, etc.).
+  let out = "";
+  let i = 0;
+  let sawTime = false; // `mm` after h/hh means minutes
+  const lowered = code.toLowerCase();
+  while (i < code.length) {
+    const ch = code[i]!;
+    if (ch === '"') {
+      const end = code.indexOf('"', i + 1);
+      if (end === -1) { out += code.slice(i + 1); break; }
+      out += code.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    // Try 4/3/2/1-char tokens at this position.
+    const tok4 = lowered.slice(i, i + 4);
+    const tok3 = lowered.slice(i, i + 3);
+    const tok2 = lowered.slice(i, i + 2);
+    const tok1 = lowered.slice(i, i + 1);
+    if (tok4 === "yyyy") { out += String(y).padStart(4, "0"); i += 4; continue; }
+    if (tok4 === "mmmm") { out += MONTHS_LONG[m - 1]!; i += 4; continue; }
+    if (tok3 === "mmm") { out += MONTHS_SHORT[m - 1]!; i += 3; continue; }
+    if (tok2 === "yy") { out += String(y).slice(-2); i += 2; continue; }
+    if (tok2 === "hh") { out += pad2(hh); sawTime = true; i += 2; continue; }
+    if (tok2 === "mm") {
+      if (sawTime) {
+        out += pad2(mi);
+        sawTime = false;
+      } else {
+        out += pad2(m);
+      }
+      i += 2;
+      continue;
+    }
+    if (tok2 === "ss") { out += pad2(ss); i += 2; continue; }
+    if (tok2 === "dd") { out += pad2(d); i += 2; continue; }
+    if (tok1 === "h") { out += String(hh); sawTime = true; i += 1; continue; }
+    if (tok1 === "m") { out += sawTime ? String(mi) : String(m); if (sawTime) sawTime = false; i += 1; continue; }
+    if (tok1 === "d") { out += String(d); i += 1; continue; }
+    if (tok1 === "y") { out += String(y); i += 1; continue; }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+// ---------------------------------------------------------------------------
+// Literal tokenization for decimal format codes
+// ---------------------------------------------------------------------------
+
+interface FormatToken {
+  kind: "digits" | "literal" | "percent" | "currency";
+  value: string;
+}
+
+/**
+ * Split a decimal format code into a stream of tokens so the formatter
+ * can re-stitch prefix/suffix literals around the formatted number.
+ *
+ * Examples:
+ *   `"$#,##0.00"` → [{currency "$"}, {digits "#,##0.00"}]
+ *   `"0.00%"`     → [{digits "0.00"}, {percent}]
+ *   `"\"Total: \"0"` → [{literal "Total: "}, {digits "0"}]
+ */
+function tokenizeLiterals(code: string): FormatToken[] {
+  const out: FormatToken[] = [];
+  let i = 0;
+  let digitBuf = "";
+  const flushDigits = () => {
+    if (digitBuf) {
+      out.push({ kind: "digits", value: digitBuf });
+      digitBuf = "";
+    }
+  };
+  while (i < code.length) {
+    const ch = code[i]!;
+    if (ch === '"') {
+      flushDigits();
+      const end = code.indexOf('"', i + 1);
+      const lit = end === -1 ? code.slice(i + 1) : code.slice(i + 1, end);
+      out.push({ kind: "literal", value: lit });
+      i = end === -1 ? code.length : end + 1;
+      continue;
+    }
+    if (ch === "\\") {
+      flushDigits();
+      if (i + 1 < code.length) {
+        out.push({ kind: "literal", value: code[i + 1]! });
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === "$") {
+      flushDigits();
+      out.push({ kind: "currency", value: "$" });
+      i += 1;
+      continue;
+    }
+    if (ch === "%") {
+      flushDigits();
+      out.push({ kind: "percent", value: "%" });
+      i += 1;
+      continue;
+    }
+    if (ch === "0" || ch === "#" || ch === "." || ch === "," || ch === " ") {
+      digitBuf += ch;
+      i += 1;
+      continue;
+    }
+    // Unknown char — treat as literal.
+    flushDigits();
+    out.push({ kind: "literal", value: ch });
+    i += 1;
+  }
+  flushDigits();
+  return out;
+}