Feat: Add formatDuration (#348)

Author: jlukic

CHANGELOG.md

@@ -120,6 +120,7 @@ xx.xx.xxxx
 * **Feature** - Added a bytes module — [`toBase64`](https://next.semantic-ui.com/docs/api/utils/bytes#tobase64) and [`fromBase64`](https://next.semantic-ui.com/docs/api/utils/bytes#frombase64) — unicode-safe base64 encode/decode, the pair `btoa`/`atob` never were. A string round-trips through its UTF-8 bytes (emoji and accents survive), `toBase64` also takes an `ArrayBuffer`, typed array, or array of byte values and a `{ urlSafe }` option, and `fromBase64` decodes both alphabets, strips MIME/PEM line wrapping, and returns a string or `Uint8Array` — or `null` on malformed input, never a throw
 * **Feature** - Added [`toByteSize`](https://next.semantic-ui.com/docs/api/utils/coercion#tobytesize) and [`toBytes`](https://next.semantic-ui.com/docs/api/utils/coercion#tobytes) to the coercion suite, with `coerceByteSize`/`coerceBytes` aliases. `toByteSize` reads a size expression as a whole number of bytes, so `'10mb'`, `'1.5 KB'`, and `'2 gigabytes'` all become the number an upload limit or quota compares against. Same grammar as `toDuration` (one number, one optional unit, case-insensitive, space optional), abbreviations only like the ecosystem's `bytes()` where `toDuration` reads words like `ms()`, since every importer pays per spelling and a word is one `toByteSize.config.units` line. `b`, `kb` through `pb` scale by 1024, what every config that accepts `'10mb'` already means, or by 1000 per call with `{ base: 1000 }` or once at boot via `toByteSize.config.base`. The IEC spellings `kib` through `pib` are 1024 by definition and never move. Bits, compound forms, and durations return `null`. `toBytes` is the `Uint8Array` coercion: a string reads as its UTF-8 text (never as an encoding, that is `fromBase64`'s job), a buffer, typed array, or `DataView` becomes a view over the same memory with no copy, an array of byte values is copied, and a bare number or an array holding a non-byte returns `null` rather than reading as a length or wrapping
 * **Feature** - Added [`byteLength`](https://next.semantic-ui.com/docs/api/utils/bytes#bytelength) and [`formatByteSize`](https://next.semantic-ui.com/docs/api/utils/bytes#formatbytesize) to the bytes module. `byteLength` counts the bytes a value holds (a string by its UTF-8 bytes, not its characters), `null` when it holds none. `formatByteSize` prints a count in the largest unit it fills (`'1.5 KB'`, `'10 MB'`), accepts anything `toByteSize` reads at the same base so `'10mb'` prints back as `'10 MB'`, and takes `decimals` (a maximum, trailing zeros drop), `unit` to hold one unit down a column, `iec` for `KiB`/`MiB` labels, `base: 1000` for SI, and `locale`. Labels and defaults are editable at boot via `formatByteSize.config`
+* **Feature** - Added [`formatDuration`](https://next.semantic-ui.com/docs/api/utils/dates#formatduration), the inverse of `toDuration`. Prints milliseconds in the largest unit filled (`300000` as `'5m'`, `90000` as `'1.5m'`), reads anything `toDuration` reads, and every string it prints reads back through `toDuration`, so a config can take `'5m'` on the way in and show `'5m'` on the way out. `decimals` is a maximum, `unit` holds one unit down a column, `separator` goes between the number and the unit (`'1.5 minutes'`), and `lossless` picks the largest unit that reads back to exactly the same value (`100000` is `'100s'`, not `'1.7m'`), the print a config or debug view wants. The unit ladder is editable at boot via `formatDuration.config.units`, spelled in `toDuration`'s vocabulary
 * **Feature** - Added [`configured`](https://next.semantic-ui.com/docs/api/utils/functions#configured) — attaches an editable `fn.config` to a function as one tree-shakable expression. All configured utilities (`humanize`, `toTitleCase`, `getArticle`, `toBoolean`, `formatDate`) use it, so a bundle only pays for the vocabularies it imports — the attribute-codec path that pulls in string casing no longer carries any of them
 * **Feature** - Arbitrary vocabularies now live in editable configs, set once at app boot: [`toTitleCase.config.stopWords`](https://next.semantic-ui.com/docs/api/utils/strings#totitlecase) (style guides disagree on the list, `humanize`'s `titleCase` reads the same one), [`getArticle.config.exceptions`](https://next.semantic-ui.com/docs/api/utils/strings#getarticle) for sound-contradicts-spelling words (`an hour`, `a university` now correct out of the box), and [`formatDate.config.timezones`](https://next.semantic-ui.com/docs/api/utils/dates#formatdate) for remapping an ambiguous shorthand like `IST`. `toDate` reads unix-second timestamps (a JWT `exp`) via `{ epoch: 'seconds' }`
 * **Feature** - Added `unescapeHTML()` for converting HTML entities back to characters — the inverse of `escapeHTML`

ai/skills/authoring/utility-functions.md

@@ -1,7 +1,7 @@
 ---
 title: Utility Functions Reference
 description: Complete reference for @semantic-ui/utils — a standalone utility library providing functions for arrays, objects, strings, type checking, colors, dates, and more. Use this before reimplementing common operations.
-keywords: [utilities, arrays, objects, strings, type checking, functions, debounce, throttle, memoize, clone, equality, formatDate, each, range, sequence, remove, noop, isDate, isRegExp]
+keywords: [utilities, arrays, objects, strings, type checking, functions, debounce, throttle, memoize, clone, equality, formatDate, formatDuration, each, range, sequence, remove, noop, isDate, isRegExp]
 audience: authoring
 skill: utility-functions
 type: skill
@@ -911,6 +911,31 @@ formatDate.config.timezones.IST = 'Asia/Jerusalem'; // shorthand aliases are edi
 
 **Preset formats:** `LT`, `LTS`, `L`, `l`, `LL`, `ll`, `LLL`, `lll`, `LLLL`, `llll`
 
+```javascript
+import { formatDuration, toDuration } from '@semantic-ui/utils';
+
+// formatDuration is the inverse of toDuration: one grammar, both directions.
+// it prints one quantity in the largest unit filled, never a compound '1h 30m'
+formatDuration(300000);               // '5m'
+formatDuration(90000);                // '1.5m' (decimals is a maximum, never '5.0m')
+formatDuration(3598200);              // '1h' (a value that rounds up to a whole unit promotes)
+formatDuration(-90000);               // '-1.5m'
+formatDuration('90s');                // '1.5m' (reads anything toDuration reads)
+formatDuration(90000, { unit: 's' }); // '90s' (hold one unit down a column, printed as spelled)
+formatDuration(90000, { unit: 'minutes', separator: ' ' }); // '1.5 minutes' (a space reads back, toDuration allows one there)
+formatDuration('banana');             // null
+
+// the default rounds, so 100000 prints '1.7m' and reads back as 102000. lossless picks the
+// largest unit that reads back exactly, the print a config or debug view wants
+formatDuration(100000);                       // '1.7m'
+formatDuration(100000, { lossless: true });   // '100s'
+toDuration(formatDuration(100000, { lossless: true })); // 100000
+
+// the ladder is spelled in toDuration's vocabulary, so a unit is added to both
+toDuration.config.units.y = 365.25 * 86400000;
+formatDuration.config.units.unshift('y');
+```
+
 ---
 
 ## Number Utilities (numbers.js)

docs/src/content/examples/utils-formatduration.mdx

@@ -0,0 +1,11 @@
+---
+title: 'formatDuration'
+id: 'utils-formatduration'
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'Dates'
+description: 'Format milliseconds for display in the largest unit filled, like 5m or 1.5h, the inverse of toDuration'
+tags: ['utils', 'dates', 'formatduration', 'duration', 'time', 'format', 'display', 'config']
+selectedFile: 'index.js'
+tip: 'Every string it prints reads back through toDuration. The default rounds, so 100000 is 1.7m. Pass lossless to pick the largest unit that reads back exactly (100s), the print a config view wants'
+---

docs/src/examples/utils/dates/utils-formatduration/index.js

@@ -0,0 +1,27 @@
+import { formatDuration, toDuration } from '@semantic-ui/utils';
+
+console.log(formatDuration(500));
+console.log(formatDuration(5000));
+console.log(formatDuration(300000));
+console.log(formatDuration(90000));
+console.log(formatDuration(5400000));
+console.log(formatDuration(-90000));
+
+// decimals is a maximum, a value that rounds up to a whole unit promotes
+console.log(formatDuration(1234567, { decimals: 3 }));
+console.log(formatDuration(3598200));
+
+// hold one unit down a column, printed as spelled
+console.log(formatDuration(90000, { unit: 's' }));
+console.log(formatDuration(90000, { unit: 'minutes', separator: ' ' }));
+
+// reads anything toDuration reads, and everything it prints reads back
+console.log(formatDuration('90s'));
+console.log(toDuration(formatDuration(300000)));
+
+// the default rounds. lossless picks the largest unit that reads back exactly
+console.log(formatDuration(100000));
+console.log(formatDuration(100000, { lossless: true }));
+console.log(toDuration(formatDuration(100000, { lossless: true })));
+
+console.log(formatDuration('banana'));

docs/src/pages/docs/api/utils/coercion.mdx

@@ -202,6 +202,8 @@ Coerces a duration expression to milliseconds, or `null` when it reads as no dur
 
 The sign is kept, so `'-1.5h'` is `-5400000`. Compound expressions like `'1h 30m'` are a different grammar and return `null` rather than a partial reading, as do unknown units, bare numbers with trailing junk, and exponent notation.
 
+[`formatDuration`](/docs/api/utils/dates#formatduration) is the inverse, printing milliseconds back in this grammar (`300000` as `'5m'`), so a config can read `'5m'` on the way in and show `'5m'` on the way out.
+
 #### Units
 
 | Unit | Accepted spellings |

docs/src/pages/docs/api/utils/dates.mdx

@@ -3,12 +3,12 @@ layout: '@layouts/Guide.astro'
 pageType: 'API Reference'
 title: Date Utilities
 package: "@semantic-ui/utils"
-methods: [formatDate]
+methods: [formatDate, formatDuration]
 icon: calendar
-description: API reference for date manipulation and formatting functions
+description: API reference for date and duration formatting functions
 ---
 
-The Date utilities provide functions for formatting and manipulating dates in JavaScript.
+The Date utilities format dates and durations for display. `formatDate` prints a `Date` through a token string, `formatDuration` prints a millisecond count in the largest unit it fills, the inverse of [`toDuration`](/docs/api/utils/coercion#toduration).
 
 ## Functions
 
@@ -148,3 +148,75 @@ console.log(formatDate(date, 'hh:mm a', { hour12: false })); // "14:30 "
 // Escaped literal text
 console.log(formatDate(date, '[Today is] dddd, MMMM Do, YYYY')); // "Today is Monday, May 15th, 2023"
 ```
+
+### formatDuration
+
+```javascript
+function formatDuration(value, { decimals, unit, lossless, separator } = {})
+```
+
+Formats a duration for display in the largest unit it fills, or `null` when there is no duration to format. `300000` prints as `'5m'`, `90000` as `'1.5m'`, `500` as `'500ms'`, and the sign is kept. Accepts anything `toDuration` reads, so `'90s'` prints as `'1.5m'` with no conversion in between.
+
+This is the inverse of `toDuration` and the two share one grammar: every string `formatDuration` prints reads back through `toDuration`, and the unit ladder is spelled in `toDuration`'s vocabulary. It prints one quantity, never a compound `'1h 30m'`, because `toDuration` reads one quantity.
+
+`decimals` is a maximum, so `'5m'` never prints as `'5.0m'`, and a value that rounds up to a whole unit promotes (`3598200` is `'1h'` at one decimal, not `'60m'`). `unit` holds one unit so a column reads down in the same scale, printed as spelled. `separator` goes between the number and the unit, so `{ unit: 'minutes', separator: ' ' }` gives `'1.5 minutes'`. A space is the one separator `toDuration` reads back, since its grammar allows one there and nothing else.
+
+`lossless` is for a config view. The default picks the largest unit the value fills and rounds, so `100000` prints as `'1.7m'`, which reads back as `102000`. Under `lossless` the walk continues to the largest unit whose print reads back to exactly the same value, `'100s'`, where the check is the very product `toDuration` computes. A value with no short exact form prints in a small unit (`93784000` is `'93784s'`), which is the honest answer for a value nobody configured by hand.
+
+#### Parameters
+
+| Name     | Type    | Description |
+|----------|---------|-------------|
+| value    | unknown | The milliseconds, or a duration expression |
+| settings | object  | Optional configuration |
+
+##### Options
+
+| Name     | Type    | Default | Description |
+|----------|---------|---------|-------------|
+| decimals | number  | `formatDuration.config.decimals` (1) | Maximum decimal places, trailing zeros drop |
+| unit     | string  | largest unit filled | Hold one unit, printed as spelled, any spelling `toDuration` reads (`'s'`, `'minutes'`, `'hr'`) |
+| lossless | boolean | `formatDuration.config.lossless` (false) | Pick the largest unit that reads back through `toDuration` to the same value |
+| separator | string | `formatDuration.config.separator` (`''`) | Text between the number and the unit, `' '` for `'1.5 minutes'` |
+
+#### Returns
+
+The formatted duration, or `null` if there is no duration to format.
+
+#### Example
+
+```javascript
+import { formatDuration, toDuration } from '@semantic-ui/utils';
+
+console.log(formatDuration(500)); // '500ms'
+console.log(formatDuration(300000)); // '5m'
+console.log(formatDuration(90000)); // '1.5m'
+console.log(formatDuration(5400000)); // '1.5h'
+console.log(formatDuration(-90000)); // '-1.5m'
+console.log(formatDuration(1234567, { decimals: 3 })); // '20.576m'
+console.log(formatDuration(3598200)); // '1h'
+console.log(formatDuration(90000, { unit: 's' })); // '90s'
+console.log(formatDuration(90000, { unit: 'minutes', separator: ' ' })); // '1.5 minutes'
+console.log(formatDuration('90s')); // '1.5m'
+console.log(formatDuration(100000)); // '1.7m'
+console.log(formatDuration(100000, { lossless: true })); // '100s'
+console.log(formatDuration('banana')); // null
+
+// a config accepts '5m' on the way in and shows '5m' on the way out
+const reuseAfter = toDuration(config.reuseAfter) ?? 300000;
+console.log(formatDuration(reuseAfter, { lossless: true })); // '5m'
+```
+
+#### formatDuration.config
+
+`formatDuration.config` holds the defaults for `decimals`, `lossless`, and `separator`, plus `units`, the ladder walked largest first. Each entry is a spelling `toDuration.config.units` holds, which is where the span comes from, so a unit is added to both. Edit it once at app boot and every call inherits it. Per-call settings still win.
+
+```javascript
+import { formatDuration, toDuration } from '@semantic-ui/utils';
+
+toDuration.config.units.y = 365.25 * 24 * 60 * 60 * 1000;
+formatDuration.config.units.unshift('y');
+
+console.log(formatDuration(63115200000)); // '2y'
+console.log(toDuration('2y')); // 63115200000
+```

packages/utils/src/dates.js

@@ -1,4 +1,6 @@
+import { toDuration } from './coercion.js';
 import { configured } from './functions.js';
+import { roundDecimal } from './numbers.js';
 
 /*-------------------
         Dates
@@ -150,3 +152,49 @@ export const formatDate = /* @__PURE__ */ configured((date, format = 'LLL', {
     SGT: 'Asia/Singapore',
   },
 });
+
+// the ladder is spelled in toDuration's vocabulary and reads its spans from there, so every string
+// this prints reads back through toDuration. a unit is added to both: toDuration.config.units.y for
+// the span, formatDuration.config.units.unshift('y') for its place in the walk
+export const formatDuration = /* @__PURE__ */ configured(
+  (value, options = {}) => {
+    const config = formatDuration.config;
+    const decimals = options.decimals ?? config.decimals;
+    const lossless = options.lossless ?? config.lossless;
+    const separator = options.separator ?? config.separator;
+    const spans = toDuration.config.units;
+    const ms = toDuration(value);
+    if (ms === null) { return null; }
+    const magnitude = Math.abs(ms);
+    let unit;
+    if (options.unit != null) {
+      unit = String(options.unit).toLowerCase();
+      if (!Object.hasOwn(spans, unit)) { return null; }
+    }
+    else {
+      const ladder = config.units;
+      let index = 0;
+      let span = spans[ladder[0]];
+      // walk largest first to the first unit the value fills. lossless walks on to the first one
+      // whose rounded print reads back to the same value, the product toDuration itself computes
+      while (
+        index < ladder.length - 1
+        && (magnitude < span || (lossless && roundDecimal(magnitude / span, decimals) * span !== magnitude))
+      ) {
+        span = spans[ladder[++index]];
+      }
+      // 59.97m rounds to 60m, which is a whole hour. a lossless pick is exact and never promotes
+      if (
+        !lossless && index > 0 && roundDecimal(magnitude / span, decimals) * span >= spans[ladder[index - 1]]
+      ) { index--; }
+      unit = ladder[index];
+    }
+    return (ms < 0 ? '-' : '') + roundDecimal(magnitude / spans[unit], decimals) + separator + unit;
+  },
+  {
+    decimals: 1,
+    lossless: false,
+    separator: '',
+    units: ['w', 'd', 'h', 'm', 's', 'ms'],
+  },
+);