@forthtilliath/ts-kit 0.12.0 → 0.14.0

package/README.md

@@ -57,6 +57,11 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `getMostRecentIds(rows, limit?)` — most recently occurring distinct ids
   (`{ id, occurredAt }[]`), most recent first, deduplicated, limited
   (default 5).
+- `indexById(items)` — `ReadonlyMap` from each item's `id` to the item (last
+  wins on duplicates), to build once instead of a `find` per rendered row.
+- `moveItem(items, from, offset)` — copy of `items` with the element at
+  `from` moved `offset` places (negative = towards the start); returns
+  `items` itself when nothing moves, so a state setter can skip the update.
 - `nextInCycle(ids, currentId)` — next id in a short list (e.g. cycling
   through recents on tap) — wraps to the first if `currentId` is at the end
   or no longer in the list.
@@ -114,16 +119,35 @@ Importing them is harmless anywhere: the DOM is only touched when called.
     rarely needed since `FArray` is already assignable to `T[]` anywhere a
     plain array is expected, but useful when the runtime type matters too.
 
+### `color`
+
+- `contrastRatio(a, b)` — WCAG 2 contrast ratio between two hex colours
+  (`#rgb`/`#rrggbb`), from 1 to 21; compare with `TEXT_CONTRAST` (4.5) or
+  `GRAPHIC_CONTRAST` (3). Throws a `TypeError` on an invalid colour.
+- `relativeLuminance(hex)` — WCAG 2 relative luminance, 0 (black) to 1.
+- `readableTextOn(background)` — `"#ffffff"` or `"#000000"`, whichever reads
+  best on that background.
+
 ### `csv`
 
+Every text cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage
+return is prefixed with `'` by `toCsv` and `escapeCsvField`, so Excel,
+LibreOffice or Sheets show it instead of running it as a formula (CSV
+injection: `=HYPERLINK(…)` typed as a name becomes a trapped link). Numbers,
+and numbers written as text (`"-3"`), are left as they are. Pass
+`{ neutralizeFormulas: false }` only for a file no spreadsheet opens.
+
 - `parseCsvLine(line, delimiter?)` — splits one CSV line into trimmed cells;
   quoted cells may contain the delimiter, `""` stands for a literal quote.
   Delimiter defaults to `","`.
-- `toCsv(rows, delimiter?)` — serializes whole rows to CSV, every cell quoted
-  and escaped, rows joined with `\n`. Delimiter defaults to `","`.
-- `escapeCsvField(value, delimiter?)` — escapes a single field (RFC 4180),
-  quoting it only if it contains a `"`, the delimiter or a line break — to
-  build rows cell by cell. Delimiter defaults to `";"` (French-locale Excel).
+- `toCsv(rows, delimiter?, { neutralizeFormulas? })` — serializes whole rows
+  to CSV, every cell quoted and escaped, rows joined with `\n`. Delimiter
+  defaults to `","`.
+- `escapeCsvField(value, delimiter?, { neutralizeFormulas? })` — escapes a
+  single field (RFC 4180), quoting it only if it contains a `"`, the
+  delimiter or a line break — to build rows cell by cell. Delimiter defaults
+  to `";"` (French-locale Excel).
+- `neutralizeCsvFormula(value)` — the formula guard above, on its own.
 - `formatCsvNumber(value, decimals?)` — formats a number with a comma decimal
   separator (French-locale spreadsheets) instead of JS's dot.
 - `downloadCsv(filename, content)` — browser download as `text/csv`, with a
@@ -144,7 +168,9 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `mondayFirstWeekday(date)` — weekday index with Monday = `0` … Sunday = `6`,
   from a `Date` or a `YYYY-MM-DD` string; offsets a Monday-first month grid.
 - `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
-  time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
+  time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`. Without it
+  (Hermes, React Native on Android), a built-in French/English fallback
+  ("il y a 3 heures"; other locales in English) instead of a crash.
 - `formatRecentDate(date, { now?, locale? })` — a past moment as a "last
   saved…" line reads best: `"aujourd'hui à 21:42"`, `"hier à 08:05"`, then
   `"le 11 octobre 2026"` (`locale: "en"`: `"today at…"`, `"on October 11, 2026"`).
@@ -210,7 +236,7 @@ Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
 ### `markdown`
 
 - `parseChangelogNotes(notes)` — parses a small subset of Markdown
-  (`### heading`, `- item`, `**bold**`) commonly found in GitHub release
+  (`#` to `###### heading`, `- item`, `**bold**`) commonly found in GitHub release
   notes into a list of typed blocks (`heading` / `item` / `text`, each with
   `bold`-aware segments), ready for a UI layer to render without a full
   Markdown dependency.
@@ -250,7 +276,9 @@ Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
 - `pluralize(count, singular, plural? | { plural?, locale? })` — picks the
   singular or the plural form. Which counts take the singular follows the
   locale's rules (`Intl.PluralRules`, `"en"` by default): only ±1 in
-  English, 0 and 1.5 too in French. Without an explicit plural form, a naive
+  English, 0 and 1.5 too in French. Where `Intl.PluralRules` is missing
+  (Hermes, React Native on Android), French keeps the singular below 2 and
+  other languages only for ±1. Without an explicit plural form, a naive
   suffix: English `s`/`es`/`ies`, French `s` (nothing after `s`/`x`/`z`),
   `s` elsewhere.
 - `createPluralize(locale)` — `pluralize` bound to a locale, declared once per

package/dist/array/index.d.ts

@@ -2,6 +2,8 @@ export * from "./chunk.js";
 export * from "./createColumnStorage.js";
 export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
+export * from "./indexById.js";
+export * from "./moveItem.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";

package/dist/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -2,6 +2,8 @@ export * from "./chunk.js";
 export * from "./createColumnStorage.js";
 export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
+export * from "./indexById.js";
+export * from "./moveItem.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
 export * from "./shuffle.js";

package/dist/array/indexById.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Indexes items by their `id`, to build once (e.g. in a `useMemo`) and read
+ * in O(1) instead of a `find` per rendered element (games × their players).
+ * With duplicate ids, the last item wins.
+ *
+ * @param items - The items to index.
+ * @returns A read-only map from each `id` to its item.
+ * @example
+ * const players = indexById([{ id: "a", name: "Ann" }]);
+ * players.get("a")?.name; // => "Ann"
+ */
+export declare function indexById<T extends {
+    id: unknown;
+}>(items: readonly T[]): ReadonlyMap<T["id"], T>;
+//# sourceMappingURL=indexById.d.ts.map

package/dist/array/indexById.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexById.d.ts","sourceRoot":"","sources":["../../src/array/indexById.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,OAAO,CAAA;CAAE,EACjD,KAAK,EAAE,SAAS,CAAC,EAAE,GAClB,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAEzB"}

package/dist/array/indexById.js

@@ -0,0 +1,14 @@
+/**
+ * Indexes items by their `id`, to build once (e.g. in a `useMemo`) and read
+ * in O(1) instead of a `find` per rendered element (games × their players).
+ * With duplicate ids, the last item wins.
+ *
+ * @param items - The items to index.
+ * @returns A read-only map from each `id` to its item.
+ * @example
+ * const players = indexById([{ id: "a", name: "Ann" }]);
+ * players.get("a")?.name; // => "Ann"
+ */
+export function indexById(items) {
+    return new Map(items.map((item) => [item.id, item]));
+}

package/dist/array/moveItem.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Returns a copy of `items` with the element at `from` moved `offset` places
+ * (negative = towards the start), the others shifting to make room. When
+ * nothing moves (`from` or the destination out of bounds, `offset` 0), the
+ * very same array is returned, so a state setter can skip a useless update.
+ *
+ * @param items - The array to copy.
+ * @param from - The position of the element to move.
+ * @param offset - How many places to move it.
+ * @returns A new array with the element moved, or `items` itself.
+ * @example
+ * moveItem(["a", "b", "c", "d"], 0, 2); // => ["b", "c", "a", "d"]
+ * moveItem(["a", "b", "c"], 2, -1); // => ["a", "c", "b"]
+ * moveItem(list, 0, -1) === list; // => true
+ */
+export declare function moveItem<T>(items: T[], from: number, offset: number): T[];
+export declare function moveItem<T>(items: readonly T[], from: number, offset: number): readonly T[];
+//# sourceMappingURL=moveItem.d.ts.map

package/dist/array/moveItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveItem.d.ts","sourceRoot":"","sources":["../../src/array/moveItem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;AAC3E,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,SAAS,CAAC,EAAE,CAAC"}

package/dist/array/moveItem.js

@@ -0,0 +1,9 @@
+export function moveItem(items, from, offset) {
+    const to = from + offset;
+    const inBounds = (i) => Number.isInteger(i) && i >= 0 && i < items.length;
+    if (!inBounds(from) || !inBounds(to) || to === from)
+        return items;
+    const next = [...items];
+    next.splice(to, 0, ...next.splice(from, 1));
+    return next;
+}

package/dist/color/contrastRatio.d.ts

@@ -0,0 +1,40 @@
+/** WCAG 2 AA minimum for body text. */
+export declare const TEXT_CONTRAST = 4.5;
+/** WCAG 2 AA minimum for large text and graphical objects (icons, bars). */
+export declare const GRAPHIC_CONTRAST = 3;
+/**
+ * The WCAG 2 relative luminance of a colour, from 0 (black) to 1 (white).
+ *
+ * @param hex - A `#rgb` or `#rrggbb` colour (`#` optional).
+ * @returns Its relative luminance.
+ * @throws {TypeError} If `hex` is not a 3- or 6-digit hex colour.
+ * @example
+ * relativeLuminance("#ffffff"); // => 1
+ */
+export declare function relativeLuminance(hex: string): number;
+/**
+ * The WCAG 2 contrast ratio between two colours, from 1 (identical) to 21
+ * (black on white), whatever their order. Compare it with `TEXT_CONTRAST`
+ * (4.5) or `GRAPHIC_CONTRAST` (3).
+ *
+ * @param a - A `#rgb` or `#rrggbb` colour.
+ * @param b - Another one.
+ * @returns The contrast ratio.
+ * @throws {TypeError} If either colour is not a 3- or 6-digit hex colour.
+ * @example
+ * contrastRatio("#000", "#fff"); // => 21
+ * contrastRatio("#767676", "#ffffff") >= TEXT_CONTRAST; // => true
+ */
+export declare function contrastRatio(a: string, b: string): number;
+/**
+ * Black or white, whichever reads best on `background` (pure black or white
+ * always reaches at least 4.58:1 on some side).
+ *
+ * @param background - A `#rgb` or `#rrggbb` colour.
+ * @returns `"#ffffff"` or `"#000000"`.
+ * @example
+ * readableTextOn("#16283d"); // => "#ffffff"
+ * readableTextOn("#84cc16"); // => "#000000"
+ */
+export declare function readableTextOn(background: string): "#ffffff" | "#000000";
+//# sourceMappingURL=contrastRatio.d.ts.map

package/dist/color/contrastRatio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrastRatio.d.ts","sourceRoot":"","sources":["../../src/color/contrastRatio.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAgBlC;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAKxE"}

package/dist/color/contrastRatio.js

@@ -0,0 +1,62 @@
+/** WCAG 2 AA minimum for body text. */
+export const TEXT_CONTRAST = 4.5;
+/** WCAG 2 AA minimum for large text and graphical objects (icons, bars). */
+export const GRAPHIC_CONTRAST = 3;
+const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
+function channels(hex) {
+    const match = HEX.exec(hex.trim());
+    if (!match?.[1])
+        throw new TypeError(`Invalid hex colour: "${hex}"`);
+    const digits = match[1].length === 3 ? match[1].replace(/./g, "$&$&") : match[1];
+    return [0, 2, 4].map((i) => Number.parseInt(digits.slice(i, i + 2), 16));
+}
+/**
+ * The WCAG 2 relative luminance of a colour, from 0 (black) to 1 (white).
+ *
+ * @param hex - A `#rgb` or `#rrggbb` colour (`#` optional).
+ * @returns Its relative luminance.
+ * @throws {TypeError} If `hex` is not a 3- or 6-digit hex colour.
+ * @example
+ * relativeLuminance("#ffffff"); // => 1
+ */
+export function relativeLuminance(hex) {
+    const [r, g, b] = channels(hex).map((channel) => {
+        const c = channel / 255;
+        return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/**
+ * The WCAG 2 contrast ratio between two colours, from 1 (identical) to 21
+ * (black on white), whatever their order. Compare it with `TEXT_CONTRAST`
+ * (4.5) or `GRAPHIC_CONTRAST` (3).
+ *
+ * @param a - A `#rgb` or `#rrggbb` colour.
+ * @param b - Another one.
+ * @returns The contrast ratio.
+ * @throws {TypeError} If either colour is not a 3- or 6-digit hex colour.
+ * @example
+ * contrastRatio("#000", "#fff"); // => 21
+ * contrastRatio("#767676", "#ffffff") >= TEXT_CONTRAST; // => true
+ */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+/**
+ * Black or white, whichever reads best on `background` (pure black or white
+ * always reaches at least 4.58:1 on some side).
+ *
+ * @param background - A `#rgb` or `#rrggbb` colour.
+ * @returns `"#ffffff"` or `"#000000"`.
+ * @example
+ * readableTextOn("#16283d"); // => "#ffffff"
+ * readableTextOn("#84cc16"); // => "#000000"
+ */
+export function readableTextOn(background) {
+    return contrastRatio("#ffffff", background) >=
+        contrastRatio("#000000", background)
+        ? "#ffffff"
+        : "#000000";
+}

package/dist/color/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./contrastRatio.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/color/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/color/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}

package/dist/color/index.js

@@ -0,0 +1 @@
+export * from "./contrastRatio.js";

package/dist/csv/escapeCsvField.d.ts

@@ -1,8 +1,10 @@
+import { type CsvFormulaOptions } from "./neutralizeCsvFormula.js";
 /**
  * Escapes a single CSV field per RFC 4180, quoting it only when needed: if it
  * contains a double quote, the delimiter or a line break, it's wrapped in
  * double quotes with any internal double quote doubled; otherwise it's
- * returned as-is.
+ * returned as-is. A field that would run as a spreadsheet formula (`=`, `+`,
+ * `-`, `@`…) is first prefixed with `'` (see `neutralizeCsvFormula`).
  *
  * Builds rows cell by cell. To serialize whole rows at once, see `toCsv`
  * (which always quotes, and defaults to `,`).
@@ -10,12 +12,14 @@
  * @param value - The raw field value.
  * @param delimiter - The cell separator the field will be joined with.
  *   Defaults to `";"`, what French-locale Excel expects.
+ * @param options - `{ neutralizeFormulas }`, `true` by default.
  * @returns The value, quoted and escaped only if needed.
  * @example
  * escapeCsvField("Apple"); // => "Apple"
  * escapeCsvField("a;b"); // => '"a;b"'
  * escapeCsvField("a,b", ","); // => '"a,b"'
  * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ * escapeCsvField("=1+1"); // => "'=1+1"
  */
-export declare function escapeCsvField(value: string, delimiter?: string): string;
+export declare function escapeCsvField(value: string, delimiter?: string, { neutralizeFormulas }?: CsvFormulaOptions): string;
 //# sourceMappingURL=escapeCsvField.d.ts.map

package/dist/csv/escapeCsvField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/csv/escapeCsvField.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAQrE"}
+{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/csv/escapeCsvField.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,SAAS,SAAM,EACf,EAAE,kBAAyB,EAAE,GAAE,iBAAsB,GACpD,MAAM,CASR"}

package/dist/csv/escapeCsvField.js

@@ -1,8 +1,10 @@
+import { neutralizeCsvFormula, } from "./neutralizeCsvFormula.js";
 /**
  * Escapes a single CSV field per RFC 4180, quoting it only when needed: if it
  * contains a double quote, the delimiter or a line break, it's wrapped in
  * double quotes with any internal double quote doubled; otherwise it's
- * returned as-is.
+ * returned as-is. A field that would run as a spreadsheet formula (`=`, `+`,
+ * `-`, `@`…) is first prefixed with `'` (see `neutralizeCsvFormula`).
  *
  * Builds rows cell by cell. To serialize whole rows at once, see `toCsv`
  * (which always quotes, and defaults to `,`).
@@ -10,19 +12,22 @@
  * @param value - The raw field value.
  * @param delimiter - The cell separator the field will be joined with.
  *   Defaults to `";"`, what French-locale Excel expects.
+ * @param options - `{ neutralizeFormulas }`, `true` by default.
  * @returns The value, quoted and escaped only if needed.
  * @example
  * escapeCsvField("Apple"); // => "Apple"
  * escapeCsvField("a;b"); // => '"a;b"'
  * escapeCsvField("a,b", ","); // => '"a,b"'
  * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ * escapeCsvField("=1+1"); // => "'=1+1"
  */
-export function escapeCsvField(value, delimiter = ";") {
-    const needsQuoting = value.includes('"') ||
-        value.includes(delimiter) ||
-        value.includes("\n") ||
-        value.includes("\r");
+export function escapeCsvField(value, delimiter = ";", { neutralizeFormulas = true } = {}) {
+    const safe = neutralizeFormulas ? neutralizeCsvFormula(value) : value;
+    const needsQuoting = safe.includes('"') ||
+        safe.includes(delimiter) ||
+        safe.includes("\n") ||
+        safe.includes("\r");
     if (!needsQuoting)
-        return value;
-    return `"${value.replace(/"/g, '""')}"`;
+        return safe;
+    return `"${safe.replace(/"/g, '""')}"`;
 }

package/dist/csv/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./downloadCsv.js";
 export * from "./escapeCsvField.js";
 export * from "./formatCsvNumber.js";
+export * from "./neutralizeCsvFormula.js";
 export * from "./parseCsvLine.js";
 export * from "./toCsv.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/csv/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/csv/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/csv/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/csv/index.js

@@ -1,5 +1,6 @@
 export * from "./downloadCsv.js";
 export * from "./escapeCsvField.js";
 export * from "./formatCsvNumber.js";
+export * from "./neutralizeCsvFormula.js";
 export * from "./parseCsvLine.js";
 export * from "./toCsv.js";

package/dist/csv/neutralizeCsvFormula.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Defuses CSV/formula injection: a text cell that starts with `=`, `+`, `-`,
+ * `@`, a tab or a carriage return is run as a formula by Excel, LibreOffice
+ * or Sheets (`=HYPERLINK("http://…","click")` becomes a trapped link). Such a
+ * cell is prefixed with an apostrophe so the spreadsheet shows it as text.
+ * Numbers written as text (`"-3"`, `"+1,5"`) are left untouched.
+ *
+ * `toCsv` and `escapeCsvField` already call it by default.
+ *
+ * @param value - The raw cell value.
+ * @returns The value, prefixed with `'` if it would run as a formula.
+ * @example
+ * neutralizeCsvFormula("=1+1"); // => "'=1+1"
+ * neutralizeCsvFormula("@SUM(A1)"); // => "'@SUM(A1)"
+ * neutralizeCsvFormula("-3"); // => "-3"
+ * neutralizeCsvFormula("Ann"); // => "Ann"
+ */
+export declare function neutralizeCsvFormula(value: string): string;
+export interface CsvFormulaOptions {
+    /**
+     * Prefixes with `'` the text cells a spreadsheet would run as formulas (see
+     * `neutralizeCsvFormula`). Defaults to `true`; turn it off only for a file
+     * no spreadsheet will open, or whose cells are not user input.
+     */
+    neutralizeFormulas?: boolean;
+}
+//# sourceMappingURL=neutralizeCsvFormula.d.ts.map

package/dist/csv/neutralizeCsvFormula.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neutralizeCsvFormula.d.ts","sourceRoot":"","sources":["../../src/csv/neutralizeCsvFormula.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/csv/neutralizeCsvFormula.js

@@ -0,0 +1,25 @@
+// A number written as text ("-3", "+33 6", "1,5", "2e-3") stays a number.
+const NUMERIC = /^[+-]?(\d+([.,]\d*)?|[.,]\d+)([eE][+-]?\d+)?$/;
+const FORMULA_START = /^[=+\-@\t\r]/;
+/**
+ * Defuses CSV/formula injection: a text cell that starts with `=`, `+`, `-`,
+ * `@`, a tab or a carriage return is run as a formula by Excel, LibreOffice
+ * or Sheets (`=HYPERLINK("http://…","click")` becomes a trapped link). Such a
+ * cell is prefixed with an apostrophe so the spreadsheet shows it as text.
+ * Numbers written as text (`"-3"`, `"+1,5"`) are left untouched.
+ *
+ * `toCsv` and `escapeCsvField` already call it by default.
+ *
+ * @param value - The raw cell value.
+ * @returns The value, prefixed with `'` if it would run as a formula.
+ * @example
+ * neutralizeCsvFormula("=1+1"); // => "'=1+1"
+ * neutralizeCsvFormula("@SUM(A1)"); // => "'@SUM(A1)"
+ * neutralizeCsvFormula("-3"); // => "-3"
+ * neutralizeCsvFormula("Ann"); // => "Ann"
+ */
+export function neutralizeCsvFormula(value) {
+    if (!FORMULA_START.test(value) || NUMERIC.test(value))
+        return value;
+    return `'${value}`;
+}

package/dist/csv/toCsv.d.ts

@@ -1,14 +1,19 @@
+import { type CsvFormulaOptions } from "./neutralizeCsvFormula.js";
 /**
  * Serializes rows to CSV. Every cell is wrapped in double quotes (any internal
  * double quote doubled), so delimiters and line breaks inside a cell are safe.
+ * A text cell that would run as a spreadsheet formula (`=`, `+`, `-`, `@`…) is
+ * prefixed with `'` (see `neutralizeCsvFormula`); number cells never are.
  * Rows are joined with `\n`.
  *
  * @param rows - The rows to serialize, header row included if any.
  * @param delimiter - The cell separator. Defaults to `","`.
+ * @param options - `{ neutralizeFormulas }`, `true` by default.
  * @returns The CSV content.
  * @example
  * toCsv([["name", "age"], ["Ann", 32]]); // => '"name","age"\n"Ann","32"'
  * toCsv([['say "hi"']]); // => '"say ""hi"""'
+ * toCsv([["=1+1", -3]]); // => `"'=1+1","-3"`
  */
-export declare function toCsv(rows: readonly (readonly (string | number)[])[], delimiter?: string): string;
+export declare function toCsv(rows: readonly (readonly (string | number)[])[], delimiter?: string, { neutralizeFormulas }?: CsvFormulaOptions): string;
 //# sourceMappingURL=toCsv.d.ts.map

package/dist/csv/toCsv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toCsv.d.ts","sourceRoot":"","sources":["../../src/csv/toCsv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,EAC/C,SAAS,SAAM,GACd,MAAM,CAQR"}
+{"version":3,"file":"toCsv.d.ts","sourceRoot":"","sources":["../../src/csv/toCsv.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,EAC/C,SAAS,SAAM,EACf,EAAE,kBAAyB,EAAE,GAAE,iBAAsB,GACpD,MAAM,CAUR"}

package/dist/csv/toCsv.js

@@ -1,19 +1,25 @@
+import { neutralizeCsvFormula, } from "./neutralizeCsvFormula.js";
 /**
  * Serializes rows to CSV. Every cell is wrapped in double quotes (any internal
  * double quote doubled), so delimiters and line breaks inside a cell are safe.
+ * A text cell that would run as a spreadsheet formula (`=`, `+`, `-`, `@`…) is
+ * prefixed with `'` (see `neutralizeCsvFormula`); number cells never are.
  * Rows are joined with `\n`.
  *
  * @param rows - The rows to serialize, header row included if any.
  * @param delimiter - The cell separator. Defaults to `","`.
+ * @param options - `{ neutralizeFormulas }`, `true` by default.
  * @returns The CSV content.
  * @example
  * toCsv([["name", "age"], ["Ann", 32]]); // => '"name","age"\n"Ann","32"'
  * toCsv([['say "hi"']]); // => '"say ""hi"""'
+ * toCsv([["=1+1", -3]]); // => `"'=1+1","-3"`
  */
-export function toCsv(rows, delimiter = ",") {
+export function toCsv(rows, delimiter = ",", { neutralizeFormulas = true } = {}) {
+    const text = (cell) => typeof cell === "string" && neutralizeFormulas
+        ? neutralizeCsvFormula(cell)
+        : String(cell);
     return rows
-        .map((row) => row
-        .map((cell) => `"${String(cell).replace(/"/g, '""')}"`)
-        .join(delimiter))
+        .map((row) => row.map((cell) => `"${text(cell).replace(/"/g, '""')}"`).join(delimiter))
         .join("\n");
 }

package/dist/date/formatRelativeTime.d.ts

@@ -1,6 +1,8 @@
 /**
  * Formats the difference between two dates as a human-readable relative
  * string ("3 hours ago", "in 2 days"), backed by `Intl.RelativeTimeFormat`.
+ * Where the engine lacks it (Hermes on Android), a built-in fallback covers
+ * French and English, and formats any other locale in English.
  *
  * @param date - The date to describe.
  * @param baseDate - The reference date to compare against (defaults to now).

package/dist/date/formatRelativeTime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatRelativeTime.d.ts","sourceRoot":"","sources":["../../src/date/formatRelativeTime.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,IAAiB,EAC3B,MAAM,SAAO,GACZ,MAAM,CAWR"}
+{"version":3,"file":"formatRelativeTime.d.ts","sourceRoot":"","sources":["../../src/date/formatRelativeTime.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,IAAiB,EAC3B,MAAM,SAAO,GACZ,MAAM,CAmBR"}

package/dist/date/formatRelativeTime.js

@@ -7,9 +7,40 @@ const UNITS = [
     { unit: "minute", ms: 60 * 1000 },
     { unit: "second", ms: 1000 },
 ];
+const FRENCH_UNITS = {
+    year: ["an", "ans"],
+    month: ["mois", "mois"],
+    week: ["semaine", "semaines"],
+    day: ["jour", "jours"],
+    hour: ["heure", "heures"],
+    minute: ["minute", "minutes"],
+    second: ["seconde", "secondes"],
+};
+// Hermes (React Native on Android) ships no `Intl.RelativeTimeFormat`: this
+// covers French and English (any other locale gets English).
+function formatWithoutIntl(value, unit, locale) {
+    const abs = Math.abs(value);
+    if (locale.split("-")[0]?.toLowerCase() === "fr") {
+        if (value === 0)
+            return "maintenant";
+        if (unit === "day" && abs === 1)
+            return value < 0 ? "hier" : "demain";
+        const [one, many] = FRENCH_UNITS[unit];
+        const text = `${abs} ${abs < 2 ? one : many}`;
+        return value < 0 ? `il y a ${text}` : `dans ${text}`;
+    }
+    if (value === 0)
+        return "now";
+    if (unit === "day" && abs === 1)
+        return value < 0 ? "yesterday" : "tomorrow";
+    const text = `${abs} ${unit}${abs === 1 ? "" : "s"}`;
+    return value < 0 ? `${text} ago` : `in ${text}`;
+}
 /**
  * Formats the difference between two dates as a human-readable relative
  * string ("3 hours ago", "in 2 days"), backed by `Intl.RelativeTimeFormat`.
+ * Where the engine lacks it (Hermes on Android), a built-in fallback covers
+ * French and English, and formats any other locale in English.
  *
  * @param date - The date to describe.
  * @param baseDate - The reference date to compare against (defaults to now).
@@ -20,11 +51,14 @@ const UNITS = [
  */
 export function formatRelativeTime(date, baseDate = new Date(), locale = "en") {
     const diffMs = date.getTime() - baseDate.getTime();
-    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    const format = typeof Intl !== "undefined" && typeof Intl.RelativeTimeFormat === "function"
+        ? (value, unit) => new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(value, unit)
+        : (value, unit) => formatWithoutIntl(value, unit, locale);
     for (const { unit, ms } of UNITS) {
         if (Math.abs(diffMs) >= ms || unit === "second") {
-            return rtf.format(Math.round(diffMs / ms), unit);
+            // `+ 0` turns a rounded -0 into 0.
+            return format(Math.round(diffMs / ms) + 0, unit);
         }
     }
-    return rtf.format(0, "second");
+    return format(0, "second");
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./array/index.js";
 export * from "./async/index.js";
 export * from "./classes/index.js";
+export * from "./color/index.js";
 export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@
 export * from "./array/index.js";
 export * from "./async/index.js";
 export * from "./classes/index.js";
+export * from "./color/index.js";
 export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";

package/dist/markdown/parseChangelogNotes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseChangelogNotes.d.ts","sourceRoot":"","sources":["../../src/markdown/parseChangelogNotes.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAsBnD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAiBnE"}
+{"version":3,"file":"parseChangelogNotes.d.ts","sourceRoot":"","sources":["../../src/markdown/parseChangelogNotes.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AA0BnD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAqBnE"}

package/dist/markdown/parseChangelogNotes.js

@@ -23,14 +23,21 @@ function parseInlineSegments(text) {
     }
     return segments;
 }
+// Any ATX heading level ("# " to "###### ") — release notes are not always
+// written with "###" (e.g. "## What's new" on a hand-written GitHub release).
+const headingPattern = /^#{1,6}\s+/;
 export function parseChangelogNotes(notes) {
     return notes
         .split("\n")
         .map((line) => line.trim())
         .filter((line) => line.length > 0)
         .map((line) => {
-        if (line.startsWith("### ")) {
-            return { type: "heading", text: line.slice(4).trim() };
+        const heading = headingPattern.exec(line);
+        if (heading) {
+            return {
+                type: "heading",
+                text: line.slice(heading[0].length).trim(),
+            };
         }
         if (line.startsWith("- ")) {
             return {

package/dist/string/pluralize.d.ts

@@ -9,7 +9,9 @@ export interface PluralizeOptions {
 }
 /**
  * Pluralizes a word based on a count. Which counts take the singular follows
- * the locale's plural rules (`Intl.PluralRules`). Without an explicit plural
+ * the locale's plural rules (`Intl.PluralRules`); where the engine lacks it
+ * (Hermes on Android), French keeps the singular below 2 and other languages
+ * only for ±1. Without an explicit plural
  * form, the default suffix is naive: in English `s`, `y` → `ies`, `es` after
  * `s`/`x`/`z`/`sh`/`ch`; in French `s`, nothing after `s`/`x`/`z`; `s` in
  * any other language.

package/dist/string/pluralize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pluralize.d.ts","sourceRoot":"","sources":["../../src/string/pluralize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAClC,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,IACpC,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAElE"}
+{"version":3,"file":"pluralize.d.ts","sourceRoot":"","sources":["../../src/string/pluralize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAClC,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,IACpC,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAElE"}

package/dist/string/pluralize.js

@@ -1,5 +1,18 @@
 const pluralRules = new Map();
+function languageOf(locale) {
+    return locale.split("-")[0]?.toLowerCase();
+}
+// Hermes (React Native on Android) ships no `Intl.PluralRules`: without it,
+// French keeps the singular below 2, every other language only for ±1.
+function fallbackTakesSingular(count, locale) {
+    return languageOf(locale) === "fr"
+        ? Math.abs(count) < 2
+        : Math.abs(count) === 1;
+}
 function takesSingular(count, locale) {
+    if (typeof Intl === "undefined" || typeof Intl.PluralRules !== "function") {
+        return fallbackTakesSingular(count, locale);
+    }
     let rules = pluralRules.get(locale);
     if (!rules) {
         rules = new Intl.PluralRules(locale);
@@ -8,7 +21,7 @@ function takesSingular(count, locale) {
     return rules.select(count) === "one";
 }
 function defaultPlural(singular, locale) {
-    const language = locale.split("-")[0]?.toLowerCase();
+    const language = languageOf(locale);
     if (language === "fr") {
         return /[sxz]$/i.test(singular) ? singular : `${singular}s`;
     }
@@ -22,7 +35,9 @@ function defaultPlural(singular, locale) {
 }
 /**
  * Pluralizes a word based on a count. Which counts take the singular follows
- * the locale's plural rules (`Intl.PluralRules`). Without an explicit plural
+ * the locale's plural rules (`Intl.PluralRules`); where the engine lacks it
+ * (Hermes on Android), French keeps the singular below 2 and other languages
+ * only for ±1. Without an explicit plural
  * form, the default suffix is naive: in English `s`, `y` → `ies`, `es` after
  * `s`/`x`/`z`/`sh`/`ch`; in French `s`, nothing after `s`/`x`/`z`; `s` in
  * any other language.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -27,8 +27,8 @@
     "jsdom": "^30.1.1",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2",
-    "@forthtilliath/eslint-config": "0.9.0",
-    "@forthtilliath/typescript-config": "0.1.1"
+    "@forthtilliath/typescript-config": "0.1.1",
+    "@forthtilliath/eslint-config": "0.9.0"
   },
   "scripts": {
     "dev": "tsc --watch -p tsconfig.build.json",