@jsenv/humanize 1.7.7 → 1.8.0

package/README.md

@@ -48,3 +48,116 @@ import { humanizeDuration } from "@jsenv/humanize";
 
 humanizeDuration(61_421); // "1 minute and 1 second"
 ```
+
+## format\* — text for the reader of an app
+
+Everything above writes English for a developer reading a terminal. The
+`format*` family writes for the person using the app, in their language,
+through `Intl`.
+
+| what you are writing                          | reach for                                          |
+| --------------------------------------------- | -------------------------------------------------- |
+| a message in a terminal, a log, a test report | `humanize`, `humanizeDuration`, `humanizeFileSize` |
+| a date, a delay or a number someone will read | `format*`                                          |
+
+It lives in this package, which has no frontend of its own, so that a server
+and a browser word the same instant identically: these are the functions
+behind `@jsenv/navi`'s `<Time>` components, so a notification row written by a
+backend and the card it points at read the same date the same way — and a REST
+service does not install a frontend framework to print a month name. Nothing
+here touches the DOM.
+
+```js
+import {
+  formatDatetime,
+  formatDay,
+  formatDuration,
+  formatHourDuration,
+  formatMinuteDuration,
+  formatMonth,
+  formatNumber,
+  formatSecondDuration,
+  formatTimeOfDay,
+  formatTimeRange,
+  formatTimeRelative,
+} from "@jsenv/humanize";
+
+const start = new Date("2026-05-11T14:05:00");
+const end = new Date("2026-05-11T16:00:00");
+const lang = "fr";
+
+// a date
+formatDay(start, { lang }); // "lundi 11 mai"
+formatDay(start, { lang, format: "numeric" }); // "11/05/2026"
+formatMonth(start, { lang }); // "mai 2026"
+formatDatetime(start, { lang }); // "lun. 11 mai à 14:05"
+
+// a time of day, a span
+formatTimeOfDay(start, { lang, format: "compact" }); // "14h05"
+formatTimeRange(start, end, { lang, format: "compact" }); // "14h05–16h00"
+
+// a duration, from the unit you happen to hold
+formatMinuteDuration(90, { lang, format: "compact" }); // "1h30"
+formatHourDuration(2.5, { lang }); // "2 heures et 30 minutes"
+formatSecondDuration(90, { lang }); // "1 minute et 30 secondes"
+formatDuration("PT1H30M", { lang }); // "1 heure et 30 minutes"
+
+// a moment, relative to now (second argument is how long it lasts)
+formatTimeRelative(start, 30 * 60_000, { lang });
+// "dans 1 heure et 30 minutes", "En cours" or "il y a 2 heures"
+
+// a number
+formatNumber(1_234_567.5, { lang }); // "1 234 567,5"
+```
+
+Each takes more than `lang` — how a part is spelled, precision, padding, time
+zone, whether the year is written. Those options live in the function's own
+JSDoc, which the published bundle keeps: hover the import in an editor rather
+than looking for a page listing them.
+
+Two more, for a date field with nothing in it yet: `formatDatePlaceholder()`
+writes `"jj/mm/aaaa"`, and `formatMonthPlaceholder()`, `formatWeekPlaceholder()`
+and `formatDatetimePlaceholder()` do the same for their own shape.
+
+### Which language
+
+With no `lang`, a call uses the runtime language source: by default the
+runtime's own locale, exactly what `Intl` would pick on its own. A frontend
+replaces that source once, with a live one:
+
+```js
+import { setRuntimeLangSource } from "@jsenv/humanize";
+
+setRuntimeLangSource(() => languagesSignal.value);
+```
+
+`@jsenv/navi` already does this, pointing it at the user's language
+preference; because the source is read on every call, a component formatting a
+date re-renders when that preference changes.
+
+On a server the default is the process locale, which is nobody's in
+particular — **pass `lang` explicitly whenever the text is for someone else**,
+and `timeZone` too when the instant must be worded in the reader's zone rather
+than the machine's.
+
+### Changing a word
+
+The words around the numbers — `"time.ongoing"`, the compact unit symbols, the
+placeholder tokens — live in `humanizeI18n`, and every one of them can be
+replaced or translated into a language that is not shipped:
+
+```js
+import { humanizeI18n } from "@jsenv/humanize";
+
+humanizeI18n.add("time.ongoing", { fr: "En cours…" });
+humanizeI18n.addLangKeys("ja", { "time.midnight": "真夜中" });
+```
+
+`src/i18n/humanize_i18n.js` is the exhaustive list of keys and defaults, and is
+meant to be read. It is the same registry `@jsenv/navi` exposes as `naviI18n`,
+so one call reaches both.
+
+`createI18n()` (an app's own text registry) and `interpolateText()` (one
+sentence with values in it) are exported here too; `@jsenv/navi`'s
+[docs/i18n.md](../../frontend/navi/docs/i18n.md) explains when to use which,
+and why a library's keys are opaque while an app's are not.