@barefootjs/client 0.24.1 → 0.26.0

package/dist/format-date.d.ts

@@ -1,14 +1,15 @@
 /**
  * `formatDate` — format a `Date` (or ISO-8601 string) with an explicit pattern
- * and an explicit UTC offset. The pure-function date formatter of #2324: every
+ * and an explicit timezone. The pure-function date formatter of #2324: every
  * input is explicit, so the output is a deterministic function of its
- * arguments — no host locale, no host timezone, no ICU/CLDR data. That is what
- * lets the SSR adapters lower a `formatDate(...)` call to their native
- * `format_date` runtime helper (spec/template-helpers.md) with byte-identical
- * output on every backend.
+ * arguments — no host locale, no *implicit* host timezone, no ICU/CLDR data.
+ * That is what lets the SSR adapters lower a `formatDate(...)` call to their
+ * native `format_date` runtime helper (spec/template-helpers.md) with
+ * byte-identical output on every backend.
  *
  * ```tsx
  * <time>{formatDate(createdAt, 'YYYY/M/D', '+09:00')}</time>
+ * <time>{formatDate(createdAt, 'YYYY/M/D', 'Asia/Tokyo')}</time>
  * <time>{formatDate(createdAt, 'MMMM D, YYYY', 'UTC', names)}</time>
  * ```
  *
@@ -27,11 +28,18 @@
  * same normative zero-value discipline as an unparseable date, byte-identical
  * on every backend.
  *
- * `timeZone` is `'UTC'` or a fixed offset `±HH:MM` (`'+09:00'`, `'-05:30'`).
- * The function is total: any other value — including IANA zone names, which
- * would drag host tzdata versions into the output — normalizes to `'UTC'`, so
- * every backend degrades identically instead of diverging. An unset or
- * unparseable `date` renders `''`.
+ * `timeZone` (#2344) is `'UTC'`, a fixed offset `±HH:MM` within ECMA-402's
+ * valid range (`'+09:00'`, `'-05:30'` — hours 00–23, minutes 00–59), or a
+ * **canonical IANA zone ID** (`'Asia/Tokyo'`) resolved through tzdata at the
+ * instant being formatted — DST-aware, historical-transition-aware, at up to
+ * seconds precision (pre-standard LMT offsets count). Any other value — an
+ * unknown zone, a non-canonical spelling (`'asia/tokyo'`, a link name the
+ * host canonicalizes away), an out-of-range offset (`'+25:00'`) — **throws a
+ * `RangeError`**, mirroring `Intl`: loud, never a silent fallback to UTC (a
+ * silently substituted timezone is the one failure mode this helper must not
+ * have — the pre-#2344 total-function normalization is gone). The receiver
+ * contract still comes first: an unset or unparseable `date` renders `''`
+ * before `timeZone` is ever inspected, on every backend identically.
  */
 export declare function formatDate(date: Date | string, pattern: string, timeZone?: string, names?: readonly string[]): string;
 //# sourceMappingURL=format-date.d.ts.map

package/dist/format-date.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-date.d.ts","sourceRoot":"","sources":["../src/format-date.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAeH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,SAAQ,EAChB,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CA4CR"}
+{"version":3,"file":"format-date.d.ts","sourceRoot":"","sources":["../src/format-date.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAoEH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,SAAQ,EAChB,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CAiDR"}

package/dist/index.js

@@ -163,12 +163,49 @@ function queryHref(base, params) {
   return qs ? `${base}?${qs}` : base;
 }
 // src/format-date.ts
-var OFFSET_RE = /^([+-])(\d{2}):(\d{2})$/;
+var OFFSET_RE = /^([+-])([01]\d|2[0-3]):([0-5]\d)$/;
 var TOKEN_RE = /YYYY|MMMM|MMM|MM|DD|dddd|ddd|M|D/g;
 var MONTHS_WIDE = 0;
 var MONTHS_ABBR = 12;
 var WEEKDAYS_WIDE = 24;
 var WEEKDAYS_ABBR = 31;
+var dtfCache = new Map;
+function invalidTimeZone(timeZone) {
+  return new RangeError(`formatDate: unresolvable timeZone ${JSON.stringify(timeZone)} — expected 'UTC', a fixed ±HH:MM offset, or a canonical IANA zone ID`);
+}
+function zoneOffsetMs(timeZone, t) {
+  let dtf = dtfCache.get(timeZone);
+  if (!dtf) {
+    try {
+      dtf = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        era: "short",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+    } catch {
+      throw invalidTimeZone(timeZone);
+    }
+    if (dtf.resolvedOptions().timeZone !== timeZone)
+      throw invalidTimeZone(timeZone);
+    dtfCache.set(timeZone, dtf);
+  }
+  const field = {};
+  for (const part of dtf.formatToParts(t))
+    field[part.type] = part.value;
+  let year = Number(field.year);
+  if (field.era && field.era.startsWith("B"))
+    year = 1 - year;
+  const wall = new Date(0);
+  wall.setUTCFullYear(year, Number(field.month) - 1, Number(field.day));
+  wall.setUTCHours(Number(field.hour), Number(field.minute), Number(field.second), 0);
+  return wall.getTime() - Math.floor(t / 1000) * 1000;
+}
 function pad2(n) {
   return String(n).padStart(2, "0");
 }
@@ -179,9 +216,12 @@ function formatDate(date, pattern, timeZone = "UTC", names = []) {
   const t = d.getTime();
   if (Number.isNaN(t))
     return "";
-  const m = OFFSET_RE.exec(timeZone);
-  const offsetMinutes = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) : 0;
-  const s = new Date(t + offsetMinutes * 60000);
+  let offsetMs = 0;
+  if (timeZone !== "UTC") {
+    const m = OFFSET_RE.exec(timeZone);
+    offsetMs = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) * 60000 : zoneOffsetMs(timeZone, t);
+  }
+  const s = new Date(t + offsetMs);
   const year = s.getUTCFullYear();
   const yyyy = (year < 0 ? "-" : "") + String(Math.abs(year)).padStart(4, "0");
   const month = s.getUTCMonth() + 1;

package/dist/runtime/index.js

@@ -163,12 +163,49 @@ function queryHref(base, params) {
   return qs ? `${base}?${qs}` : base;
 }
 // src/format-date.ts
-var OFFSET_RE = /^([+-])(\d{2}):(\d{2})$/;
+var OFFSET_RE = /^([+-])([01]\d|2[0-3]):([0-5]\d)$/;
 var TOKEN_RE = /YYYY|MMMM|MMM|MM|DD|dddd|ddd|M|D/g;
 var MONTHS_WIDE = 0;
 var MONTHS_ABBR = 12;
 var WEEKDAYS_WIDE = 24;
 var WEEKDAYS_ABBR = 31;
+var dtfCache = new Map;
+function invalidTimeZone(timeZone) {
+  return new RangeError(`formatDate: unresolvable timeZone ${JSON.stringify(timeZone)} — expected 'UTC', a fixed ±HH:MM offset, or a canonical IANA zone ID`);
+}
+function zoneOffsetMs(timeZone, t) {
+  let dtf = dtfCache.get(timeZone);
+  if (!dtf) {
+    try {
+      dtf = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        era: "short",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+    } catch {
+      throw invalidTimeZone(timeZone);
+    }
+    if (dtf.resolvedOptions().timeZone !== timeZone)
+      throw invalidTimeZone(timeZone);
+    dtfCache.set(timeZone, dtf);
+  }
+  const field = {};
+  for (const part of dtf.formatToParts(t))
+    field[part.type] = part.value;
+  let year = Number(field.year);
+  if (field.era && field.era.startsWith("B"))
+    year = 1 - year;
+  const wall = new Date(0);
+  wall.setUTCFullYear(year, Number(field.month) - 1, Number(field.day));
+  wall.setUTCHours(Number(field.hour), Number(field.minute), Number(field.second), 0);
+  return wall.getTime() - Math.floor(t / 1000) * 1000;
+}
 function pad2(n) {
   return String(n).padStart(2, "0");
 }
@@ -179,9 +216,12 @@ function formatDate(date, pattern, timeZone = "UTC", names = []) {
   const t = d.getTime();
   if (Number.isNaN(t))
     return "";
-  const m = OFFSET_RE.exec(timeZone);
-  const offsetMinutes = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) : 0;
-  const s = new Date(t + offsetMinutes * 60000);
+  let offsetMs = 0;
+  if (timeZone !== "UTC") {
+    const m = OFFSET_RE.exec(timeZone);
+    offsetMs = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) * 60000 : zoneOffsetMs(timeZone, t);
+  }
+  const s = new Date(t + offsetMs);
   const year = s.getUTCFullYear();
   const yyyy = (year < 0 ? "-" : "") + String(Math.abs(year)).padStart(4, "0");
   const month = s.getUTCMonth() + 1;

package/dist/runtime/standalone.js

@@ -816,12 +816,49 @@ function queryHref(base, params) {
   return qs ? `${base}?${qs}` : base;
 }
 // src/format-date.ts
-var OFFSET_RE = /^([+-])(\d{2}):(\d{2})$/;
+var OFFSET_RE = /^([+-])([01]\d|2[0-3]):([0-5]\d)$/;
 var TOKEN_RE = /YYYY|MMMM|MMM|MM|DD|dddd|ddd|M|D/g;
 var MONTHS_WIDE = 0;
 var MONTHS_ABBR = 12;
 var WEEKDAYS_WIDE = 24;
 var WEEKDAYS_ABBR = 31;
+var dtfCache = new Map;
+function invalidTimeZone(timeZone) {
+  return new RangeError(`formatDate: unresolvable timeZone ${JSON.stringify(timeZone)} — expected 'UTC', a fixed ±HH:MM offset, or a canonical IANA zone ID`);
+}
+function zoneOffsetMs(timeZone, t) {
+  let dtf = dtfCache.get(timeZone);
+  if (!dtf) {
+    try {
+      dtf = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        era: "short",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+    } catch {
+      throw invalidTimeZone(timeZone);
+    }
+    if (dtf.resolvedOptions().timeZone !== timeZone)
+      throw invalidTimeZone(timeZone);
+    dtfCache.set(timeZone, dtf);
+  }
+  const field = {};
+  for (const part of dtf.formatToParts(t))
+    field[part.type] = part.value;
+  let year = Number(field.year);
+  if (field.era && field.era.startsWith("B"))
+    year = 1 - year;
+  const wall = new Date(0);
+  wall.setUTCFullYear(year, Number(field.month) - 1, Number(field.day));
+  wall.setUTCHours(Number(field.hour), Number(field.minute), Number(field.second), 0);
+  return wall.getTime() - Math.floor(t / 1000) * 1000;
+}
 function pad2(n) {
   return String(n).padStart(2, "0");
 }
@@ -832,9 +869,12 @@ function formatDate(date, pattern, timeZone = "UTC", names = []) {
   const t = d.getTime();
   if (Number.isNaN(t))
     return "";
-  const m = OFFSET_RE.exec(timeZone);
-  const offsetMinutes = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) : 0;
-  const s = new Date(t + offsetMinutes * 60000);
+  let offsetMs = 0;
+  if (timeZone !== "UTC") {
+    const m = OFFSET_RE.exec(timeZone);
+    offsetMs = m ? (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) * 60000 : zoneOffsetMs(timeZone, t);
+  }
+  const s = new Date(t + offsetMs);
   const year = s.getUTCFullYear();
   const yyyy = (year < 0 ? "-" : "") + String(Math.abs(year)).padStart(4, "0");
   const month = s.getUTCMonth() + 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/client",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "BarefootJS client package: reactive primitives (SSR-safe) plus browser runtime under the `/runtime` subpath (compiler target)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "directory": "packages/client"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.24.1"
+    "@barefootjs/shared": "0.26.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"

package/src/format-date.ts

@@ -1,14 +1,15 @@
 /**
  * `formatDate` — format a `Date` (or ISO-8601 string) with an explicit pattern
- * and an explicit UTC offset. The pure-function date formatter of #2324: every
+ * and an explicit timezone. The pure-function date formatter of #2324: every
  * input is explicit, so the output is a deterministic function of its
- * arguments — no host locale, no host timezone, no ICU/CLDR data. That is what
- * lets the SSR adapters lower a `formatDate(...)` call to their native
- * `format_date` runtime helper (spec/template-helpers.md) with byte-identical
- * output on every backend.
+ * arguments — no host locale, no *implicit* host timezone, no ICU/CLDR data.
+ * That is what lets the SSR adapters lower a `formatDate(...)` call to their
+ * native `format_date` runtime helper (spec/template-helpers.md) with
+ * byte-identical output on every backend.
  *
  * ```tsx
  * <time>{formatDate(createdAt, 'YYYY/M/D', '+09:00')}</time>
+ * <time>{formatDate(createdAt, 'YYYY/M/D', 'Asia/Tokyo')}</time>
  * <time>{formatDate(createdAt, 'MMMM D, YYYY', 'UTC', names)}</time>
  * ```
  *
@@ -27,14 +28,21 @@
  * same normative zero-value discipline as an unparseable date, byte-identical
  * on every backend.
  *
- * `timeZone` is `'UTC'` or a fixed offset `±HH:MM` (`'+09:00'`, `'-05:30'`).
- * The function is total: any other value — including IANA zone names, which
- * would drag host tzdata versions into the output — normalizes to `'UTC'`, so
- * every backend degrades identically instead of diverging. An unset or
- * unparseable `date` renders `''`.
+ * `timeZone` (#2344) is `'UTC'`, a fixed offset `±HH:MM` within ECMA-402's
+ * valid range (`'+09:00'`, `'-05:30'` — hours 00–23, minutes 00–59), or a
+ * **canonical IANA zone ID** (`'Asia/Tokyo'`) resolved through tzdata at the
+ * instant being formatted — DST-aware, historical-transition-aware, at up to
+ * seconds precision (pre-standard LMT offsets count). Any other value — an
+ * unknown zone, a non-canonical spelling (`'asia/tokyo'`, a link name the
+ * host canonicalizes away), an out-of-range offset (`'+25:00'`) — **throws a
+ * `RangeError`**, mirroring `Intl`: loud, never a silent fallback to UTC (a
+ * silently substituted timezone is the one failure mode this helper must not
+ * have — the pre-#2344 total-function normalization is gone). The receiver
+ * contract still comes first: an unset or unparseable `date` renders `''`
+ * before `timeZone` is ever inspected, on every backend identically.
  */
 
-const OFFSET_RE = /^([+-])(\d{2}):(\d{2})$/
+const OFFSET_RE = /^([+-])([01]\d|2[0-3]):([0-5]\d)$/
 const TOKEN_RE = /YYYY|MMMM|MMM|MM|DD|dddd|ddd|M|D/g
 
 /** `names`-table section offsets (spec/template-helpers.md "format_date"). */
@@ -43,6 +51,59 @@ const MONTHS_ABBR = 12
 const WEEKDAYS_WIDE = 24
 const WEEKDAYS_ABBR = 31
 
+/** Probe formatter per named zone — construction is the expensive step. */
+const dtfCache = new Map<string, Intl.DateTimeFormat>()
+
+function invalidTimeZone(timeZone: string): RangeError {
+  return new RangeError(
+    `formatDate: unresolvable timeZone ${JSON.stringify(timeZone)} — expected 'UTC', a fixed ±HH:MM offset, or a canonical IANA zone ID`,
+  )
+}
+
+/**
+ * Resolve a canonical IANA zone ID's UTC offset (in ms, always a whole
+ * multiple of 1000 — tz offsets are second-granular) at instant `t`, via the
+ * environment's own tzdata as ECMA-402 exposes it. The wall-clock fields the
+ * zone formats for `t` are re-encoded as-if-UTC and diffed against `t` — no
+ * dependency on `timeZoneName: 'longOffset'` support, and seconds-precision
+ * LMT offsets fall out naturally. Non-canonical spellings and link names
+ * (anything `resolvedOptions().timeZone` does not echo verbatim) throw: the
+ * canonical primary ID is the only spelling every backend's tzdata resolves
+ * identically, so the portable contract admits exactly that.
+ */
+function zoneOffsetMs(timeZone: string, t: number): number {
+  let dtf = dtfCache.get(timeZone)
+  if (!dtf) {
+    try {
+      dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        era: 'short',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      })
+    } catch {
+      throw invalidTimeZone(timeZone)
+    }
+    if (dtf.resolvedOptions().timeZone !== timeZone) throw invalidTimeZone(timeZone)
+    dtfCache.set(timeZone, dtf)
+  }
+  const field: Record<string, string> = {}
+  for (const part of dtf.formatToParts(t)) field[part.type] = part.value
+  // era 'BC' marks proleptic years <= 0: ISO year = 1 - displayed year.
+  let year = Number(field.year)
+  if (field.era && field.era.startsWith('B')) year = 1 - year
+  // setUTCFullYear, not Date.UTC — Date.UTC maps years 0..99 to 1900+y.
+  const wall = new Date(0)
+  wall.setUTCFullYear(year, Number(field.month) - 1, Number(field.day))
+  wall.setUTCHours(Number(field.hour), Number(field.minute), Number(field.second), 0)
+  return wall.getTime() - Math.floor(t / 1000) * 1000
+}
+
 function pad2(n: number): string {
   return String(n).padStart(2, '0')
 }
@@ -61,11 +122,16 @@ export function formatDate(
   const d = date instanceof Date ? date : new Date(date)
   const t = d.getTime()
   if (Number.isNaN(t)) return ''
-  const m = OFFSET_RE.exec(timeZone)
-  const offsetMinutes = m ? (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) : 0
+  let offsetMs = 0
+  if (timeZone !== 'UTC') {
+    const m = OFFSET_RE.exec(timeZone)
+    offsetMs = m
+      ? (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3])) * 60_000
+      : zoneOffsetMs(timeZone, t)
+  }
   // Shift the instant by the offset, then read UTC fields: the shifted UTC
-  // clock face IS the local clock face at that offset.
-  const s = new Date(t + offsetMinutes * 60_000)
+  // clock face IS the local clock face in that zone at that instant.
+  const s = new Date(t + offsetMs)
   const year = s.getUTCFullYear()
   const yyyy = (year < 0 ? '-' : '') + String(Math.abs(year)).padStart(4, '0')
   const month = s.getUTCMonth() + 1