@operato/utils 10.16.2 → 10.29.1

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [10.29.1](https://github.com/hatiolab/operato/compare/v11.0.0...v10.29.1) (2026-09-26)
+
+
+### :mega: Other
+
+* **release:** return the version to 10.29.0 -- 11.0.0 was a mistaken major bump ([6ef39c1](https://github.com/hatiolab/operato/commit/6ef39c1107f0a6614ac78255fdb700e3eecfd0f7))
+
+
+
+## [11.0.0](https://github.com/hatiolab/operato/compare/v10.29.0...v11.0.0) (2026-09-26)
+
+**Note:** Version bump only for package @operato/utils
+
+
+
+
+
+## [10.22.0](https://github.com/hatiolab/operato/compare/v10.21.0...v10.22.0) (2026-09-24)
+
+
+### :rocket: New Features
+
+* **utils:** when - a moment drawn in the screen's language and a chosen zone ([1f36cdb](https://github.com/hatiolab/operato/commit/1f36cdb0467c09c3d47748a305deedec63ddc5be))
+
+
+
 ### [10.16.2](https://github.com/hatiolab/operato/compare/v10.16.1...v10.16.2) (2026-09-18)
 
 **Note:** Version bump only for package @operato/utils

package/coverage/lcov-report/index.html

@@ -23,30 +23,30 @@
         <div class='clearfix'>
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">92.67% </span>
+                <span class="strong">95.06% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>329/355</span>
+                <span class='fraction'>501/527</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">82.6% </span>
+                <span class="strong">86.29% </span>
                 <span class="quiet">Branches</span>
-                <span class='fraction'>57/69</span>
+                <span class='fraction'>107/124</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">92.85% </span>
+                <span class="strong">95.23% </span>
                 <span class="quiet">Functions</span>
-                <span class='fraction'>13/14</span>
+                <span class='fraction'>20/21</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">92.67% </span>
+                <span class="strong">95.06% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>329/355</span>
+                <span class='fraction'>501/527</span>
             </div>
         
             
@@ -80,17 +80,17 @@
 </thead>
 <tbody><tr>
 	<td class="file high" data-value="src"><a href="src/index.html">src</a></td>
-	<td data-value="97.18" class="pic high">
-	<div class="chart"><div class="cover-fill" style="width: 97%"></div><div class="cover-empty" style="width: 3%"></div></div>
+	<td data-value="98.72" class="pic high">
+	<div class="chart"><div class="cover-fill" style="width: 98%"></div><div class="cover-empty" style="width: 2%"></div></div>
 	</td>
-	<td data-value="97.18" class="pct high">97.18%</td>
-	<td data-value="142" class="abs high">138/142</td>
-	<td data-value="95.55" class="pct high">95.55%</td>
-	<td data-value="45" class="abs high">43/45</td>
+	<td data-value="98.72" class="pct high">98.72%</td>
+	<td data-value="314" class="abs high">310/314</td>
+	<td data-value="93" class="pct high">93%</td>
+	<td data-value="100" class="abs high">93/100</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="6" class="abs high">6/6</td>
-	<td data-value="97.18" class="pct high">97.18%</td>
-	<td data-value="142" class="abs high">138/142</td>
+	<td data-value="13" class="abs high">13/13</td>
+	<td data-value="98.72" class="pct high">98.72%</td>
+	<td data-value="314" class="abs high">310/314</td>
 	</tr>
 
 <tr>
@@ -116,7 +116,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-09-17T16:05:34.844Z
+                at 2026-09-24T03:02:49.729Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov.info

@@ -216,6 +216,256 @@ BRF:37
 BRH:37
 end_of_record
 TN:
+SF:src/when.ts
+FN:31,availableZones
+FN:36,nextZone
+FN:50,resolveZone
+FN:57,msOf
+FN:113,formatWhen
+FN:139,zoneAbbr
+FN:164,dayHeadings
+FNF:7
+FNH:7
+FNDA:8,availableZones
+FNDA:5,nextZone
+FNDA:5,resolveZone
+FNDA:24,msOf
+FNDA:15,formatWhen
+FNDA:5,zoneAbbr
+FNDA:5,dayHeadings
+DA:1,1
+DA:2,1
+DA:3,1
+DA:4,1
+DA:5,1
+DA:6,1
+DA:7,1
+DA:8,1
+DA:9,1
+DA:10,1
+DA:11,1
+DA:12,1
+DA:13,1
+DA:14,1
+DA:15,1
+DA:16,1
+DA:17,1
+DA:18,1
+DA:19,1
+DA:20,1
+DA:21,1
+DA:22,1
+DA:23,1
+DA:24,1
+DA:25,1
+DA:26,1
+DA:27,1
+DA:28,1
+DA:29,1
+DA:30,1
+DA:31,1
+DA:32,8
+DA:33,8
+DA:34,1
+DA:35,1
+DA:36,1
+DA:37,5
+DA:38,5
+DA:39,5
+DA:40,5
+DA:41,5
+DA:42,1
+DA:43,1
+DA:44,1
+DA:45,1
+DA:46,1
+DA:47,1
+DA:48,1
+DA:49,1
+DA:50,1
+DA:51,5
+DA:52,5
+DA:53,5
+DA:54,5
+DA:55,1
+DA:56,1
+DA:57,1
+DA:58,24
+DA:59,24
+DA:60,24
+DA:61,3
+DA:62,3
+DA:63,3
+DA:64,3
+DA:65,3
+DA:66,1
+DA:67,1
+DA:68,1
+DA:69,1
+DA:70,1
+DA:71,1
+DA:72,1
+DA:73,1
+DA:74,1
+DA:75,1
+DA:76,1
+DA:77,1
+DA:78,1
+DA:79,1
+DA:80,1
+DA:81,1
+DA:82,1
+DA:83,1
+DA:84,1
+DA:85,1
+DA:86,1
+DA:87,1
+DA:88,1
+DA:89,1
+DA:90,1
+DA:91,1
+DA:92,1
+DA:93,1
+DA:94,1
+DA:95,1
+DA:96,1
+DA:97,1
+DA:98,1
+DA:99,1
+DA:100,1
+DA:101,1
+DA:102,1
+DA:103,1
+DA:104,1
+DA:105,1
+DA:106,1
+DA:107,1
+DA:108,1
+DA:109,1
+DA:110,1
+DA:111,1
+DA:112,1
+DA:113,1
+DA:114,15
+DA:115,15
+DA:116,15
+DA:117,15
+DA:118,15
+DA:119,15
+DA:120,15
+DA:121,15
+DA:122,15
+DA:123,15
+DA:124,15
+DA:125,15
+DA:126,15
+DA:127,1
+DA:128,1
+DA:129,1
+DA:130,1
+DA:131,15
+DA:132,1
+DA:133,1
+DA:134,1
+DA:135,1
+DA:136,1
+DA:137,1
+DA:138,1
+DA:139,1
+DA:140,5
+DA:141,4
+DA:142,5
+DA:143,5
+DA:144,5
+DA:145,5
+DA:146,5
+DA:147,5
+DA:148,1
+DA:149,1
+DA:150,5
+DA:151,1
+DA:152,1
+DA:153,1
+DA:154,1
+DA:155,1
+DA:156,1
+DA:157,1
+DA:158,1
+DA:159,1
+DA:160,1
+DA:161,1
+DA:162,1
+DA:163,1
+DA:164,1
+DA:165,5
+DA:166,5
+DA:167,5
+DA:168,15
+DA:169,15
+DA:170,15
+DA:171,5
+DA:172,5
+LF:172
+LH:172
+BRDA:31,0,0,8
+BRDA:32,1,0,24
+BRDA:32,2,0,24
+BRDA:36,3,0,5
+BRDA:40,4,0,1
+BRDA:40,5,0,4
+BRDA:50,6,0,5
+BRDA:51,7,0,1
+BRDA:52,8,0,4
+BRDA:52,9,0,1
+BRDA:53,10,0,3
+BRDA:53,11,0,2
+BRDA:57,12,0,24
+BRDA:58,13,0,2
+BRDA:58,14,0,2
+BRDA:58,15,0,2
+BRDA:59,16,0,22
+BRDA:59,17,0,16
+BRDA:59,18,0,16
+BRDA:59,19,0,16
+BRDA:60,20,0,6
+BRDA:60,21,0,4
+BRDA:60,22,0,3
+BRDA:62,23,0,1
+BRDA:62,24,0,2
+BRDA:64,25,0,3
+BRDA:113,26,0,15
+BRDA:118,27,0,1
+BRDA:119,28,0,14
+BRDA:119,29,0,1
+BRDA:120,30,0,13
+BRDA:120,31,0,13
+BRDA:120,32,0,10
+BRDA:122,33,0,0
+BRDA:124,34,0,13
+BRDA:124,35,0,0
+BRDA:126,36,0,1
+BRDA:139,37,0,5
+BRDA:140,38,0,1
+BRDA:141,39,0,4
+BRDA:142,40,0,0
+BRDA:144,41,0,4
+BRDA:144,42,0,0
+BRDA:146,43,0,3
+BRDA:146,44,0,3
+BRDA:146,45,0,3
+BRDA:146,46,0,0
+BRDA:147,47,0,1
+BRDA:146,48,0,21
+BRDA:164,49,0,5
+BRDA:167,50,0,15
+BRDA:168,51,0,14
+BRDA:168,52,0,9
+BRDA:168,53,0,6
+BRDA:169,54,0,14
+BRF:55
+BRH:50
+end_of_record
+TN:
 SF:src/reactive-controllers/tooltip-reactive-controller.ts
 FN:32,TooltipReactiveController
 FN:116,TooltipReactiveController.handleMouseOver

package/dist/src/when.d.ts

@@ -0,0 +1,84 @@
+/**
+ * A moment as the screen says it - pure: no lit, no i18n, no DOM. A value comes in, text goes out.
+ *
+ * Screens called `toLocaleString()` with no language, so a date followed the browser's setting instead
+ * of the screen's language: a Korean screen showed `8/22/2026, 5:23:33 PM` (operato-twin, 2026-08-25,
+ * fifteen places). The language is therefore always passed in here.
+ *
+ * The time zone is chosen per display, not per screen (user decision). A setting that followed you
+ * from screen to screen would be undone on the next one and leave you unsure which clock you were
+ * reading; a display that names its own zone cannot be mixed up with the one beside it.
+ *
+ * Nothing absent is made up. Some deployments set no domain time zone; that choice is then left out,
+ * visibly - the caller can tell what is missing and say so where it is drawn.
+ *
+ * Moved from operato-twin (client/when-core.ts) with its cases, ADR-0060 decision 3. plant wrote a
+ * language-only copy and was waiting for this one because it also carries the zone.
+ */
+/** Which clock to read a moment on. */
+export type ZoneChoice = 'local' | 'utc' | 'domain';
+/** The order a display steps through - your own clock first, then UTC, then the domain's. */
+export declare const ZONE_ORDER: readonly ZoneChoice[];
+/**
+ * The choices open right now - two when no domain time zone is set.
+ *
+ * What was left out shows in the length of the list (compare with `ZONE_ORDER`), so a caller can say
+ * why there are only two.
+ */
+export declare function availableZones(domainZone: string | null | undefined): ZoneChoice[];
+/** The next choice, wrapping from the last to the first and skipping any that cannot be chosen. */
+export declare function nextZone(current: ZoneChoice, domainZone: string | null | undefined): ZoneChoice;
+/**
+ * The zone name to hand `Intl` - `undefined` means the viewer's own zone.
+ *
+ * A domain choice with no domain zone does not fall back to `undefined`: that would show another
+ * zone's time as the domain's. It answers `null`, "cannot be drawn". Callers use `availableZones`
+ * so they never pass it.
+ */
+export declare function resolveZone(choice: ZoneChoice, domainZone: string | null | undefined): string | undefined | null;
+/** Milliseconds from a number, an ISO string or a `Date`. Unreadable is `null` - never "Invalid Date". */
+export declare function msOf(value: unknown): number | null;
+/** How much to write. */
+export type WhenStyle = 
+/** Date and hour:minute - the default for lists and details. */
+'datetime'
+/** The date only. */
+ | 'date'
+/** Hour:minute only - for something within today. */
+ | 'time'
+/** Down to the second - for following a flow as it happens. */
+ | 'precise';
+/**
+ * One moment, drawn in the language and the zone it is given.
+ *
+ * Leaving the language out follows the browser, which is why this module exists - so the caller always
+ * passes `lang`. An empty one is passed on as `undefined`, and that is the only place it happens.
+ *
+ * `null` when it cannot be drawn: no readable value (`msOf` is `null`) or no zone to read it on
+ * (`resolveZone` is `null`). The screen gets nothing false to show.
+ */
+export declare function formatWhen(value: unknown, opts: {
+    lang?: string;
+    zone?: string | null;
+    style?: WhenStyle;
+}): string | null;
+/**
+ * A zone's short name - `KST`, `UTC`.
+ *
+ * Where there is summer time the name changes with the date (`PST`/`PDT`), so it is taken at that
+ * moment. `null` when there is none.
+ */
+export declare function zoneAbbr(zone: string | null | undefined, lang: string | undefined, at: number): string | null;
+/**
+ * Where the date changes in a list - a date heading goes only there.
+ *
+ * A date on every row widens the time column and pushes what is beside it. The date needs saying once,
+ * where it changes, and on the first row too, so a list of one day still shows its date (operato-twin,
+ * 2026-08-27: a history of `16:04` rows gave no way to tell the day).
+ *
+ * It takes dates **already drawn**, so the day changes in the zone the person chose. Cutting the first
+ * ten characters of an ISO string would read UTC and go wrong near midnight.
+ *
+ * A row with no date (empty string) gets no heading and does not clear the one before it.
+ */
+export declare function dayHeadings(days: readonly string[]): string[];

package/dist/src/when.js

@@ -0,0 +1,158 @@
+/**
+ * A moment as the screen says it - pure: no lit, no i18n, no DOM. A value comes in, text goes out.
+ *
+ * Screens called `toLocaleString()` with no language, so a date followed the browser's setting instead
+ * of the screen's language: a Korean screen showed `8/22/2026, 5:23:33 PM` (operato-twin, 2026-08-25,
+ * fifteen places). The language is therefore always passed in here.
+ *
+ * The time zone is chosen per display, not per screen (user decision). A setting that followed you
+ * from screen to screen would be undone on the next one and leave you unsure which clock you were
+ * reading; a display that names its own zone cannot be mixed up with the one beside it.
+ *
+ * Nothing absent is made up. Some deployments set no domain time zone; that choice is then left out,
+ * visibly - the caller can tell what is missing and say so where it is drawn.
+ *
+ * Moved from operato-twin (client/when-core.ts) with its cases, ADR-0060 decision 3. plant wrote a
+ * language-only copy and was waiting for this one because it also carries the zone.
+ */
+/** The order a display steps through - your own clock first, then UTC, then the domain's. */
+export const ZONE_ORDER = ['local', 'utc', 'domain'];
+/**
+ * The choices open right now - two when no domain time zone is set.
+ *
+ * What was left out shows in the length of the list (compare with `ZONE_ORDER`), so a caller can say
+ * why there are only two.
+ */
+export function availableZones(domainZone) {
+    return ZONE_ORDER.filter(z => z !== 'domain' || !!domainZone);
+}
+/** The next choice, wrapping from the last to the first and skipping any that cannot be chosen. */
+export function nextZone(current, domainZone) {
+    const zones = availableZones(domainZone);
+    const at = zones.indexOf(current);
+    /* A current choice that is no longer open (the domain zone went away) starts over. */
+    return zones[at < 0 ? 0 : (at + 1) % zones.length];
+}
+/**
+ * The zone name to hand `Intl` - `undefined` means the viewer's own zone.
+ *
+ * A domain choice with no domain zone does not fall back to `undefined`: that would show another
+ * zone's time as the domain's. It answers `null`, "cannot be drawn". Callers use `availableZones`
+ * so they never pass it.
+ */
+export function resolveZone(choice, domainZone) {
+    if (choice === 'local')
+        return undefined;
+    if (choice === 'utc')
+        return 'UTC';
+    return domainZone || null;
+}
+/** Milliseconds from a number, an ISO string or a `Date`. Unreadable is `null` - never "Invalid Date". */
+export function msOf(value) {
+    if (value instanceof Date)
+        return Number.isFinite(value.getTime()) ? value.getTime() : null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && value.trim()) {
+        const t = Date.parse(value);
+        return Number.isFinite(t) ? t : null;
+    }
+    return null;
+}
+/*
+ * A 24-hour clock in every language.
+ *
+ * These are screens where times are compared (when it came in, when it left, which came first), and a
+ * 12-hour clock makes you read morning or afternoon each time. Japanese, Chinese and Spanish already
+ * default to 24 hours; only Korean and English differed, so the five are made one.
+ *
+ * The order of the date and the month names stay the language's own (`2026년 8월 22일` ·
+ * `Aug 22, 2026` · `22 ago 2026`). Only the hour:minute form is ours.
+ */
+const HOUR_CYCLE = { hourCycle: 'h23' };
+const FIELDS = {
+    datetime: { year: 'numeric', month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', ...HOUR_CYCLE },
+    date: { year: 'numeric', month: 'short', day: 'numeric' },
+    time: { hour: '2-digit', minute: '2-digit', ...HOUR_CYCLE },
+    precise: {
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        ...HOUR_CYCLE
+    }
+};
+/**
+ * One moment, drawn in the language and the zone it is given.
+ *
+ * Leaving the language out follows the browser, which is why this module exists - so the caller always
+ * passes `lang`. An empty one is passed on as `undefined`, and that is the only place it happens.
+ *
+ * `null` when it cannot be drawn: no readable value (`msOf` is `null`) or no zone to read it on
+ * (`resolveZone` is `null`). The screen gets nothing false to show.
+ */
+export function formatWhen(value, opts) {
+    var _a;
+    const ms = msOf(value);
+    if (ms === null)
+        return null;
+    if (opts.zone === null)
+        return null;
+    const fields = FIELDS[(_a = opts.style) !== null && _a !== void 0 ? _a : 'datetime'];
+    try {
+        return new Intl.DateTimeFormat(opts.lang || undefined, {
+            ...fields,
+            ...(opts.zone ? { timeZone: opts.zone } : {})
+        }).format(new Date(ms));
+    }
+    catch (_b) {
+        /* An unknown zone name (a typo in a deployment's setting) throws. It is not drawn on another clock
+           instead: the caller has to know it could not be drawn so the screen can say that. */
+        return null;
+    }
+}
+/**
+ * A zone's short name - `KST`, `UTC`.
+ *
+ * Where there is summer time the name changes with the date (`PST`/`PDT`), so it is taken at that
+ * moment. `null` when there is none.
+ */
+export function zoneAbbr(zone, lang, at) {
+    var _a, _b;
+    if (zone === null)
+        return null;
+    try {
+        const parts = new Intl.DateTimeFormat(lang || undefined, {
+            timeZoneName: 'short',
+            ...(zone ? { timeZone: zone } : {})
+        }).formatToParts(new Date(at));
+        return (_b = (_a = parts.find(p => p.type === 'timeZoneName')) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : null;
+    }
+    catch (_c) {
+        return null;
+    }
+}
+/**
+ * Where the date changes in a list - a date heading goes only there.
+ *
+ * A date on every row widens the time column and pushes what is beside it. The date needs saying once,
+ * where it changes, and on the first row too, so a list of one day still shows its date (operato-twin,
+ * 2026-08-27: a history of `16:04` rows gave no way to tell the day).
+ *
+ * It takes dates **already drawn**, so the day changes in the zone the person chose. Cutting the first
+ * ten characters of an ISO string would read UTC and go wrong near midnight.
+ *
+ * A row with no date (empty string) gets no heading and does not clear the one before it.
+ */
+export function dayHeadings(days) {
+    const heads = [];
+    let prev = '';
+    for (const day of days) {
+        heads.push(day && day !== prev ? day : '');
+        if (day)
+            prev = day;
+    }
+    return heads;
+}
+//# sourceMappingURL=when.js.map

package/dist/src/when.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"when.js","sourceRoot":"","sources":["../../src/when.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A moment as the screen says it - pure: no lit, no i18n, no DOM. A value comes in, text goes out.\n *\n * Screens called `toLocaleString()` with no language, so a date followed the browser's setting instead\n * of the screen's language: a Korean screen showed `8/22/2026, 5:23:33 PM` (operato-twin, 2026-08-25,\n * fifteen places). The language is therefore always passed in here.\n *\n * The time zone is chosen per display, not per screen (user decision). A setting that followed you\n * from screen to screen would be undone on the next one and leave you unsure which clock you were\n * reading; a display that names its own zone cannot be mixed up with the one beside it.\n *\n * Nothing absent is made up. Some deployments set no domain time zone; that choice is then left out,\n * visibly - the caller can tell what is missing and say so where it is drawn.\n *\n * Moved from operato-twin (client/when-core.ts) with its cases, ADR-0060 decision 3. plant wrote a\n * language-only copy and was waiting for this one because it also carries the zone.\n */\n\n/** Which clock to read a moment on. */\nexport type ZoneChoice = 'local' | 'utc' | 'domain'\n\n/** The order a display steps through - your own clock first, then UTC, then the domain's. */\nexport const ZONE_ORDER: readonly ZoneChoice[] = ['local', 'utc', 'domain']\n\n/**\n * The choices open right now - two when no domain time zone is set.\n *\n * What was left out shows in the length of the list (compare with `ZONE_ORDER`), so a caller can say\n * why there are only two.\n */\nexport function availableZones(domainZone: string | null | undefined): ZoneChoice[] {\n  return ZONE_ORDER.filter(z => z !== 'domain' || !!domainZone)\n}\n\n/** The next choice, wrapping from the last to the first and skipping any that cannot be chosen. */\nexport function nextZone(current: ZoneChoice, domainZone: string | null | undefined): ZoneChoice {\n  const zones = availableZones(domainZone)\n  const at = zones.indexOf(current)\n  /* A current choice that is no longer open (the domain zone went away) starts over. */\n  return zones[at < 0 ? 0 : (at + 1) % zones.length]\n}\n\n/**\n * The zone name to hand `Intl` - `undefined` means the viewer's own zone.\n *\n * A domain choice with no domain zone does not fall back to `undefined`: that would show another\n * zone's time as the domain's. It answers `null`, \"cannot be drawn\". Callers use `availableZones`\n * so they never pass it.\n */\nexport function resolveZone(choice: ZoneChoice, domainZone: string | null | undefined): string | undefined | null {\n  if (choice === 'local') return undefined\n  if (choice === 'utc') return 'UTC'\n  return domainZone || null\n}\n\n/** Milliseconds from a number, an ISO string or a `Date`. Unreadable is `null` - never \"Invalid Date\". */\nexport function msOf(value: unknown): number | null {\n  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null\n  if (typeof value === 'number') return Number.isFinite(value) ? value : null\n  if (typeof value === 'string' && value.trim()) {\n    const t = Date.parse(value)\n    return Number.isFinite(t) ? t : null\n  }\n  return null\n}\n\n/** How much to write. */\nexport type WhenStyle =\n  /** Date and hour:minute - the default for lists and details. */\n  | 'datetime'\n  /** The date only. */\n  | 'date'\n  /** Hour:minute only - for something within today. */\n  | 'time'\n  /** Down to the second - for following a flow as it happens. */\n  | 'precise'\n\n/*\n * A 24-hour clock in every language.\n *\n * These are screens where times are compared (when it came in, when it left, which came first), and a\n * 12-hour clock makes you read morning or afternoon each time. Japanese, Chinese and Spanish already\n * default to 24 hours; only Korean and English differed, so the five are made one.\n *\n * The order of the date and the month names stay the language's own (`2026년 8월 22일` ·\n * `Aug 22, 2026` · `22 ago 2026`). Only the hour:minute form is ours.\n */\nconst HOUR_CYCLE: Intl.DateTimeFormatOptions = { hourCycle: 'h23' }\n\nconst FIELDS: Record<WhenStyle, Intl.DateTimeFormatOptions> = {\n  datetime: { year: 'numeric', month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', ...HOUR_CYCLE },\n  date: { year: 'numeric', month: 'short', day: 'numeric' },\n  time: { hour: '2-digit', minute: '2-digit', ...HOUR_CYCLE },\n  precise: {\n    month: 'short',\n    day: 'numeric',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n    ...HOUR_CYCLE\n  }\n}\n\n/**\n * One moment, drawn in the language and the zone it is given.\n *\n * Leaving the language out follows the browser, which is why this module exists - so the caller always\n * passes `lang`. An empty one is passed on as `undefined`, and that is the only place it happens.\n *\n * `null` when it cannot be drawn: no readable value (`msOf` is `null`) or no zone to read it on\n * (`resolveZone` is `null`). The screen gets nothing false to show.\n */\nexport function formatWhen(\n  value: unknown,\n  opts: { lang?: string; zone?: string | null; style?: WhenStyle }\n): string | null {\n  const ms = msOf(value)\n  if (ms === null) return null\n  if (opts.zone === null) return null\n  const fields = FIELDS[opts.style ?? 'datetime']\n  try {\n    return new Intl.DateTimeFormat(opts.lang || undefined, {\n      ...fields,\n      ...(opts.zone ? { timeZone: opts.zone } : {})\n    }).format(new Date(ms))\n  } catch {\n    /* An unknown zone name (a typo in a deployment's setting) throws. It is not drawn on another clock\n       instead: the caller has to know it could not be drawn so the screen can say that. */\n    return null\n  }\n}\n\n/**\n * A zone's short name - `KST`, `UTC`.\n *\n * Where there is summer time the name changes with the date (`PST`/`PDT`), so it is taken at that\n * moment. `null` when there is none.\n */\nexport function zoneAbbr(zone: string | null | undefined, lang: string | undefined, at: number): string | null {\n  if (zone === null) return null\n  try {\n    const parts = new Intl.DateTimeFormat(lang || undefined, {\n      timeZoneName: 'short',\n      ...(zone ? { timeZone: zone } : {})\n    }).formatToParts(new Date(at))\n    return parts.find(p => p.type === 'timeZoneName')?.value ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Where the date changes in a list - a date heading goes only there.\n *\n * A date on every row widens the time column and pushes what is beside it. The date needs saying once,\n * where it changes, and on the first row too, so a list of one day still shows its date (operato-twin,\n * 2026-08-27: a history of `16:04` rows gave no way to tell the day).\n *\n * It takes dates **already drawn**, so the day changes in the zone the person chose. Cutting the first\n * ten characters of an ISO string would read UTC and go wrong near midnight.\n *\n * A row with no date (empty string) gets no heading and does not clear the one before it.\n */\nexport function dayHeadings(days: readonly string[]): string[] {\n  const heads: string[] = []\n  let prev = ''\n  for (const day of days) {\n    heads.push(day && day !== prev ? day : '')\n    if (day) prev = day\n  }\n  return heads\n}\n"]}

package/dist/test/when.test.d.ts

@@ -0,0 +1 @@
+export {};