@cdx-ui/formatters 0.0.1-beta.132

package/README.md

@@ -0,0 +1,108 @@
+# @cdx-ui/formatters
+
+Pure formatters for Forge UI and FI apps — turn wire values into human-readable UI strings
+(and the reverse for date wire ids). No React dependency.
+
+Aligned in style with `@candescent/ui-formatters` (display helpers at package root; date helpers under
+`dates/`). Prefer named imports from `@cdx-ui/formatters` only — do not import `date-fns` or `Intl`
+wrappers from this package’s internals.
+
+## Wire vs display (dates)
+
+| Representation                               | Example                      | Use for                       |
+| -------------------------------------------- | ---------------------------- | ----------------------------- |
+| **Wire** `DateId` / `MonthId` / `DateTimeId` | `'2026-07-28'`               | Form state, APIs, pickers     |
+| **Display** string                           | `'7/28/26'` / `'28/07/2026'` | Labels, headers — never store |
+
+## Exports
+
+### Display (shared with banking UI formatters)
+
+| Import         | Purpose                                                |
+| -------------- | ------------------------------------------------------ |
+| `formatNumber` | Locale decimal formatting (cached `Intl.NumberFormat`) |
+
+### Date wire
+
+| Import                                                       | Purpose                  |
+| ------------------------------------------------------------ | ------------------------ |
+| `parseDateId` / `formatDateId` / `isValidDateId`             | `YYYY-MM-DD` round-trip  |
+| `parseMonthId` / `formatMonthId` / `isValidMonthId`          | `YYYY-MM-01` month ids   |
+| `parseDateTimeId` / `formatDateTimeId` / `isValidDateTimeId` | Local `YYYY-MM-DDTHH:mm` |
+| `todayDateId` / `todayMonthId` / `nowDateTimeId`             | Device-local “now”       |
+| `toMonthId` / `clampDateParts` / `clampMonthParts`           | Conversions / clamping   |
+
+### Date display
+
+| Import                      | Purpose                              |
+| --------------------------- | ------------------------------------ |
+| `formatDateForDisplay`      | Locale `dateStyle` short/medium/long |
+| `formatMonthForDisplay`     | Month + year label                   |
+| `formatDateTimeForDisplay`  | Date + time label                    |
+| `formatDateRangeForDisplay` | Inclusive range label                |
+
+### Ranges & segments
+
+| Import                                                              | Purpose                  |
+| ------------------------------------------------------------------- | ------------------------ |
+| `normalizeDateRange` / `compareDateIds` / `eachDateIdInRange`       | Range math               |
+| `dateRangeFromLastNDays` / `dateRangeAroundDay`                     | Presets                  |
+| `getDateFieldSegments` / `getDateTimeFieldSegments`                 | Segmented field metadata |
+| `parseDateSegment` / `formatDateSegment` / `applyDateSegmentChange` | Segment edits            |
+
+### Calendar / list copy
+
+| Import                                                     | Purpose               |
+| ---------------------------------------------------------- | --------------------- |
+| `formatCalendarMonthYear` / `getCalendarWeekdayLabels`     | Calendar chrome       |
+| `formatMonthCalendarMonth` / `formatMonthCalendarYear`     | Month grid            |
+| `formatDateTimeListDateRow` / `formatDateTimeListHour` / … | DateTime list columns |
+
+## Usage
+
+```ts
+import {
+  formatDateId,
+  formatDateForDisplay,
+  formatNumber,
+  normalizeDateRange,
+  type DateId,
+} from '@cdx-ui/formatters';
+
+formatNumber(3247.19); // '3,247.19'
+
+const id: DateId = formatDateId({ year: 2026, month: 7, day: 28 }); // '2026-07-28'
+formatDateForDisplay(id, { locale: 'en-US' }); // e.g. '7/28/26'
+
+normalizeDateRange({ startId: '2026-07-28', endId: '2026-07-01' });
+// → { startId: '2026-07-01', endId: '2026-07-28' }
+```
+
+```bash
+pnpm --filter @cdx-ui/formatters test
+```
+
+## File layout
+
+```
+src/
+  formatNumber.ts          # shared display helper (merge target with ui-formatters)
+  types.ts / utils.ts      # package-private (not barrel-exported)
+  __tests__/               # one test file per public helper
+  dates/
+    types.ts
+    index.ts               # date barrel (re-exported from package root)
+    wire/                  # DateId / MonthId parse, format, validate, today
+    display/               # locale-aware format*ForDisplay
+    ranges/                # compare, normalize, presets
+    segments/              # segmented field helpers
+    calendar/              # calendar + list row copy
+    datetime/              # DateTimeId + list hour/minute/period
+    internal/              # private adapters (not public API)
+```
+
+## Design notes
+
+- **date-fns** is used internally for wire parse/math; **Intl** for user-facing display and calendar labels.
+- Invalid / nullish inputs return `''` or `null` as documented per helper — never throw for bad display input.
+- Package internals under `dates/internal/` are not part of the public API.

package/lib/commonjs/dates/calendar/formatCalendarMonthYear.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatCalendarMonthYear = formatCalendarMonthYear;
+var _dateIdToNativeDate = require("../internal/dateIdToNativeDate");
+var _intlCache = require("../internal/intlCache");
+/**
+ * Formats a calendar header label, e.g. `July 2026`.
+ *
+ * Uses `Intl` so `options.locale` is respected (same pattern as display formatters).
+ *
+ * @param monthId - Wire month string (`YYYY-MM-01`).
+ * @param options - Locale and optional time zone.
+ * @returns Long month and year label.
+ */
+function formatCalendarMonthYear(monthId, options) {
+  const formatter = (0, _intlCache.getCachedDateFormatter)(options?.locale ?? 'en-US', {
+    month: 'long',
+    year: 'numeric',
+    ...(options?.timeZone ? {
+      timeZone: options.timeZone
+    } : {})
+  });
+  return formatter.format((0, _dateIdToNativeDate.dateIdToNativeDate)(monthId));
+}
+//# sourceMappingURL=formatCalendarMonthYear.js.map

package/lib/commonjs/dates/calendar/formatCalendarMonthYear.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_dateIdToNativeDate","require","_intlCache","formatCalendarMonthYear","monthId","options","formatter","getCachedDateFormatter","locale","month","year","timeZone","format","dateIdToNativeDate"],"sourceRoot":"../../../../src","sources":["dates/calendar/formatCalendarMonthYear.ts"],"mappings":";;;;;;AAAA,IAAAA,mBAAA,GAAAC,OAAA;AACA,IAAAC,UAAA,GAAAD,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,uBAAuBA,CAACC,OAAgB,EAAEC,OAA2B,EAAU;EAC7F,MAAMC,SAAS,GAAG,IAAAC,iCAAsB,EAACF,OAAO,EAAEG,MAAM,IAAI,OAAO,EAAE;IACnEC,KAAK,EAAE,MAAM;IACbC,IAAI,EAAE,SAAS;IACf,IAAIL,OAAO,EAAEM,QAAQ,GAAG;MAAEA,QAAQ,EAAEN,OAAO,CAACM;IAAS,CAAC,GAAG,CAAC,CAAC;EAC7D,CAAC,CAAC;EACF,OAAOL,SAAS,CAACM,MAAM,CAAC,IAAAC,sCAAkB,EAACT,OAAO,CAAC,CAAC;AACtD","ignoreList":[]}

package/lib/commonjs/dates/calendar/formatDateTimeListDateRow.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatDateTimeListDateRow = formatDateTimeListDateRow;
+var _dateIdToNativeDate = require("../internal/dateIdToNativeDate");
+var _intlCopy = require("../internal/intlCopy");
+var _intlCache = require("../internal/intlCache");
+/**
+ * Formats a row label for a scrollable date list. Returns a locale-aware "today" label when the
+ * id matches today (pass a precomputed `todayDateId` when comparing wire ids).
+ *
+ * @param dateId - Wire date string.
+ * @param options - Locale, optional `todayDateId` override, and time zone.
+ * @returns Relative today label or a short weekday/month/day label.
+ */
+function formatDateTimeListDateRow(dateId, options) {
+  const locale = options?.locale ?? 'en-US';
+  const todayId = options?.todayDateId;
+  if (todayId && dateId === todayId) {
+    return (0, _intlCopy.formatRelativeToday)(locale);
+  }
+  const date = (0, _dateIdToNativeDate.dateIdToNativeDate)(dateId);
+  const todayParts = new Date();
+  const isToday = date.getFullYear() === todayParts.getFullYear() && date.getMonth() === todayParts.getMonth() && date.getDate() === todayParts.getDate();
+  if (isToday) {
+    return (0, _intlCopy.formatRelativeToday)(locale);
+  }
+  const formatter = (0, _intlCache.getCachedDateFormatter)(locale, {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    ...(options?.timeZone ? {
+      timeZone: options.timeZone
+    } : {})
+  });
+  return formatter.format(date);
+}
+//# sourceMappingURL=formatDateTimeListDateRow.js.map

package/lib/commonjs/dates/calendar/formatDateTimeListDateRow.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_dateIdToNativeDate","require","_intlCopy","_intlCache","formatDateTimeListDateRow","dateId","options","locale","todayId","todayDateId","formatRelativeToday","date","dateIdToNativeDate","todayParts","Date","isToday","getFullYear","getMonth","getDate","formatter","getCachedDateFormatter","weekday","month","day","timeZone","format"],"sourceRoot":"../../../../src","sources":["dates/calendar/formatDateTimeListDateRow.ts"],"mappings":";;;;;;AAAA,IAAAA,mBAAA,GAAAC,OAAA;AACA,IAAAC,SAAA,GAAAD,OAAA;AACA,IAAAE,UAAA,GAAAF,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,yBAAyBA,CACvCC,MAAc,EACdC,OAAsD,EAC9C;EACR,MAAMC,MAAM,GAAGD,OAAO,EAAEC,MAAM,IAAI,OAAO;EACzC,MAAMC,OAAO,GAAGF,OAAO,EAAEG,WAAW;EACpC,IAAID,OAAO,IAAIH,MAAM,KAAKG,OAAO,EAAE;IACjC,OAAO,IAAAE,6BAAmB,EAACH,MAAM,CAAC;EACpC;EAEA,MAAMI,IAAI,GAAG,IAAAC,sCAAkB,EAACP,MAAM,CAAC;EACvC,MAAMQ,UAAU,GAAG,IAAIC,IAAI,CAAC,CAAC;EAC7B,MAAMC,OAAO,GACXJ,IAAI,CAACK,WAAW,CAAC,CAAC,KAAKH,UAAU,CAACG,WAAW,CAAC,CAAC,IAC/CL,IAAI,CAACM,QAAQ,CAAC,CAAC,KAAKJ,UAAU,CAACI,QAAQ,CAAC,CAAC,IACzCN,IAAI,CAACO,OAAO,CAAC,CAAC,KAAKL,UAAU,CAACK,OAAO,CAAC,CAAC;EACzC,IAAIH,OAAO,EAAE;IACX,OAAO,IAAAL,6BAAmB,EAACH,MAAM,CAAC;EACpC;EAEA,MAAMY,SAAS,GAAG,IAAAC,iCAAsB,EAACb,MAAM,EAAE;IAC/Cc,OAAO,EAAE,OAAO;IAChBC,KAAK,EAAE,OAAO;IACdC,GAAG,EAAE,SAAS;IACd,IAAIjB,OAAO,EAAEkB,QAAQ,GAAG;MAAEA,QAAQ,EAAElB,OAAO,CAACkB;IAAS,CAAC,GAAG,CAAC,CAAC;EAC7D,CAAC,CAAC;EACF,OAAOL,SAAS,CAACM,MAAM,CAACd,IAAI,CAAC;AAC/B","ignoreList":[]}

package/lib/commonjs/dates/calendar/formatMonthCalendarMonth.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatMonthCalendarMonth = formatMonthCalendarMonth;
+var _intlCache = require("../internal/intlCache");
+/**
+ * Formats a short month name for month-grid cells (1–12).
+ *
+ * @param month - Month number (1–12).
+ * @param options - Locale and optional time zone.
+ * @returns Short month name.
+ *
+ * @example
+ * formatMonthCalendarMonth(7, { locale: 'en-US' }) // 'Jul'
+ */
+function formatMonthCalendarMonth(month, options) {
+  const date = new Date(2024, month - 1, 1);
+  const formatter = (0, _intlCache.getCachedDateFormatter)(options?.locale ?? 'en-US', {
+    month: 'short',
+    ...(options?.timeZone ? {
+      timeZone: options.timeZone
+    } : {})
+  });
+  return formatter.format(date);
+}
+//# sourceMappingURL=formatMonthCalendarMonth.js.map

package/lib/commonjs/dates/calendar/formatMonthCalendarMonth.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_intlCache","require","formatMonthCalendarMonth","month","options","date","Date","formatter","getCachedDateFormatter","locale","timeZone","format"],"sourceRoot":"../../../../src","sources":["dates/calendar/formatMonthCalendarMonth.ts"],"mappings":";;;;;;AAAA,IAAAA,UAAA,GAAAC,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,wBAAwBA,CAACC,KAAa,EAAEC,OAA2B,EAAU;EAC3F,MAAMC,IAAI,GAAG,IAAIC,IAAI,CAAC,IAAI,EAAEH,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;EACzC,MAAMI,SAAS,GAAG,IAAAC,iCAAsB,EAACJ,OAAO,EAAEK,MAAM,IAAI,OAAO,EAAE;IACnEN,KAAK,EAAE,OAAO;IACd,IAAIC,OAAO,EAAEM,QAAQ,GAAG;MAAEA,QAAQ,EAAEN,OAAO,CAACM;IAAS,CAAC,GAAG,CAAC,CAAC;EAC7D,CAAC,CAAC;EACF,OAAOH,SAAS,CAACI,MAAM,CAACN,IAAI,CAAC;AAC/B","ignoreList":[]}

package/lib/commonjs/dates/calendar/formatMonthCalendarYear.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatMonthCalendarYear = formatMonthCalendarYear;
+/**
+ * Formats a year label for month-calendar decade/year pickers.
+ *
+ * @param year - Four-digit year.
+ * @returns Year as a string.
+ */
+function formatMonthCalendarYear(year) {
+  return String(year);
+}
+//# sourceMappingURL=formatMonthCalendarYear.js.map

package/lib/commonjs/dates/calendar/formatMonthCalendarYear.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["formatMonthCalendarYear","year","String"],"sourceRoot":"../../../../src","sources":["dates/calendar/formatMonthCalendarYear.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,uBAAuBA,CAACC,IAAY,EAAU;EAC5D,OAAOC,MAAM,CAACD,IAAI,CAAC;AACrB","ignoreList":[]}

package/lib/commonjs/dates/calendar/getCalendarWeekdayLabels.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getCalendarWeekdayLabels = getCalendarWeekdayLabels;
+var _calendarHelpers = require("../internal/calendarHelpers");
+/**
+ * Returns ordered weekday labels for a calendar week header.
+ *
+ * @param options - Locale, first day of week, and weekday width.
+ * @returns Array of seven weekday label strings.
+ */
+function getCalendarWeekdayLabels(options) {
+  const firstDayOfWeek = options?.firstDayOfWeek ?? 0;
+  const labels = [];
+  for (let i = 0; i < 7; i += 1) {
+    const index = (firstDayOfWeek + i) % 7;
+    labels.push((0, _calendarHelpers.formatCalendarWeekday)(index, options));
+  }
+  return labels;
+}
+//# sourceMappingURL=getCalendarWeekdayLabels.js.map

package/lib/commonjs/dates/calendar/getCalendarWeekdayLabels.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_calendarHelpers","require","getCalendarWeekdayLabels","options","firstDayOfWeek","labels","i","index","push","formatCalendarWeekday"],"sourceRoot":"../../../../src","sources":["dates/calendar/getCalendarWeekdayLabels.ts"],"mappings":";;;;;;AAAA,IAAAA,gBAAA,GAAAC,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,wBAAwBA,CACtCC,OAGC,EACS;EACV,MAAMC,cAAc,GAAGD,OAAO,EAAEC,cAAc,IAAI,CAAC;EACnD,MAAMC,MAAgB,GAAG,EAAE;EAC3B,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAG,CAAC,EAAEA,CAAC,IAAI,CAAC,EAAE;IAC7B,MAAMC,KAAK,GAAG,CAACH,cAAc,GAAGE,CAAC,IAAI,CAAC;IACtCD,MAAM,CAACG,IAAI,CAAC,IAAAC,sCAAqB,EAACF,KAAK,EAAEJ,OAAO,CAAC,CAAC;EACpD;EACA,OAAOE,MAAM;AACf","ignoreList":[]}

package/lib/commonjs/dates/datetime/clampDateTimeId.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.clampDateTimeId = clampDateTimeId;
+var _compareDateTimeIds = require("./compareDateTimeIds");
+/**
+ * Clamps a wire date-time into the inclusive `[min, max]` range.
+ *
+ * Returns `min` when `value` is earlier than `min`, `max` when later than `max`,
+ * otherwise `value` unchanged. Omitted bounds are ignored.
+ *
+ * @param value - Wire date-time to clamp.
+ * @param bounds - Optional inclusive `min` / `max` wire date-times.
+ * @returns The clamped `DateTimeId`.
+ */
+function clampDateTimeId(value, bounds) {
+  if (bounds.min && (0, _compareDateTimeIds.compareDateTimeIds)(value, bounds.min) < 0) {
+    return bounds.min;
+  }
+  if (bounds.max && (0, _compareDateTimeIds.compareDateTimeIds)(value, bounds.max) > 0) {
+    return bounds.max;
+  }
+  return value;
+}
+//# sourceMappingURL=clampDateTimeId.js.map

package/lib/commonjs/dates/datetime/clampDateTimeId.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_compareDateTimeIds","require","clampDateTimeId","value","bounds","min","compareDateTimeIds","max"],"sourceRoot":"../../../../src","sources":["dates/datetime/clampDateTimeId.ts"],"mappings":";;;;;;AACA,IAAAA,mBAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,eAAeA,CAC7BC,KAAiB,EACjBC,MAA8C,EAClC;EACZ,IAAIA,MAAM,CAACC,GAAG,IAAI,IAAAC,sCAAkB,EAACH,KAAK,EAAEC,MAAM,CAACC,GAAG,CAAC,GAAG,CAAC,EAAE;IAC3D,OAAOD,MAAM,CAACC,GAAG;EACnB;EACA,IAAID,MAAM,CAACG,GAAG,IAAI,IAAAD,sCAAkB,EAACH,KAAK,EAAEC,MAAM,CAACG,GAAG,CAAC,GAAG,CAAC,EAAE;IAC3D,OAAOH,MAAM,CAACG,GAAG;EACnB;EACA,OAAOJ,KAAK;AACd","ignoreList":[]}

package/lib/commonjs/dates/datetime/compareDateTimeIds.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.compareDateTimeIds = compareDateTimeIds;
+var _dateFns = require("date-fns");
+/**
+ * Compares two wire date-times chronologically.
+ *
+ * Handles local (`YYYY-MM-DDTHH:MM`) and UTC (`…Z`) forms alike by parsing each
+ * to an absolute instant before comparing.
+ *
+ * @param a - First wire date-time.
+ * @param b - Second wire date-time.
+ * @returns `-1` if `a` is earlier, `1` if later, `0` if equal.
+ */
+function compareDateTimeIds(a, b) {
+  const result = (0, _dateFns.compareAsc)((0, _dateFns.parseISO)(a), (0, _dateFns.parseISO)(b));
+  if (result < 0) {
+    return -1;
+  }
+  if (result > 0) {
+    return 1;
+  }
+  return 0;
+}
+//# sourceMappingURL=compareDateTimeIds.js.map

package/lib/commonjs/dates/datetime/compareDateTimeIds.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_dateFns","require","compareDateTimeIds","a","b","result","compareAsc","parseISO"],"sourceRoot":"../../../../src","sources":["dates/datetime/compareDateTimeIds.ts"],"mappings":";;;;;;AAAA,IAAAA,QAAA,GAAAC,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,kBAAkBA,CAACC,CAAa,EAAEC,CAAa,EAAc;EAC3E,MAAMC,MAAM,GAAG,IAAAC,mBAAU,EAAC,IAAAC,iBAAQ,EAACJ,CAAC,CAAC,EAAE,IAAAI,iBAAQ,EAACH,CAAC,CAAC,CAAC;EACnD,IAAIC,MAAM,GAAG,CAAC,EAAE;IACd,OAAO,CAAC,CAAC;EACX;EACA,IAAIA,MAAM,GAAG,CAAC,EAAE;IACd,OAAO,CAAC;EACV;EACA,OAAO,CAAC;AACV","ignoreList":[]}

package/lib/commonjs/dates/datetime/dateTimeId.js

@@ -0,0 +1,38 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dateTimeId = dateTimeId;
+var _brand = require("../internal/brand");
+var _formatDateTimeId = require("./formatDateTimeId");
+var _isValidDateTimeId = require("./isValidDateTimeId");
+/**
+ * Validating smart constructor for a wire {@link DateTimeId} (local ISO-like,
+ * e.g. `YYYY-MM-DDTHH:mm`).
+ *
+ * Accepts either a wire string or {@link DateTimeParts}. Throws `RangeError` on
+ * input that does not parse to a valid date-time.
+ *
+ * @param input - A wire date-time string or {@link DateTimeParts}.
+ * @returns The branded `DateTimeId`.
+ * @throws RangeError when the input is not a valid `DateTimeId`.
+ *
+ * @example
+ * dateTimeId('2026-08-07T14:30'); // DateTimeId
+ * dateTimeId({ year: 2026, month: 8, day: 7, hour: 14, minute: 30 }); // DateTimeId
+ */
+function dateTimeId(input) {
+  if (typeof input === 'string') {
+    if (!(0, _isValidDateTimeId.isValidDateTimeId)(input)) {
+      throw new RangeError(`Invalid DateTimeId: "${input}". Expected a wire date-time such as "YYYY-MM-DDTHH:mm".`);
+    }
+    return input;
+  }
+  const built = (0, _formatDateTimeId.formatDateTimeId)(input);
+  if (!(0, _isValidDateTimeId.isValidDateTimeId)(built)) {
+    throw new RangeError(`Invalid DateTimeId parts: ${JSON.stringify(input)}.`);
+  }
+  return (0, _brand.asDateTimeId)(built);
+}
+//# sourceMappingURL=dateTimeId.js.map

package/lib/commonjs/dates/datetime/dateTimeId.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_brand","require","_formatDateTimeId","_isValidDateTimeId","dateTimeId","input","isValidDateTimeId","RangeError","built","formatDateTimeId","JSON","stringify","asDateTimeId"],"sourceRoot":"../../../../src","sources":["dates/datetime/dateTimeId.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,iBAAA,GAAAD,OAAA;AACA,IAAAE,kBAAA,GAAAF,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,UAAUA,CAACC,KAA6B,EAAc;EACpE,IAAI,OAAOA,KAAK,KAAK,QAAQ,EAAE;IAC7B,IAAI,CAAC,IAAAC,oCAAiB,EAACD,KAAK,CAAC,EAAE;MAC7B,MAAM,IAAIE,UAAU,CAClB,wBAAwBF,KAAK,0DAC/B,CAAC;IACH;IACA,OAAOA,KAAK;EACd;EAEA,MAAMG,KAAK,GAAG,IAAAC,kCAAgB,EAACJ,KAAK,CAAC;EACrC,IAAI,CAAC,IAAAC,oCAAiB,EAACE,KAAK,CAAC,EAAE;IAC7B,MAAM,IAAID,UAAU,CAAC,6BAA6BG,IAAI,CAACC,SAAS,CAACN,KAAK,CAAC,GAAG,CAAC;EAC7E;EACA,OAAO,IAAAO,mBAAY,EAACJ,KAAK,CAAC;AAC5B","ignoreList":[]}

package/lib/commonjs/dates/datetime/formatDateTimeId.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatDateTimeId = formatDateTimeId;
+var _brand = require("../internal/brand");
+var _formatDateId = require("../wire/formatDateId");
+/**
+ * Builds a wire `DateTimeId` from parts. Local by default; pass `{ utc: true }` for ISO UTC.
+ *
+ * @param parts - Date and time parts.
+ * @param options - When `utc` is true, returns an ISO UTC string ending in `Z`.
+ * @returns Wire `DateTimeId` string.
+ */
+function formatDateTimeId(parts, options) {
+  const date = options?.utc ? new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second ?? 0)) : new Date(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second ?? 0);
+  if (options?.utc) {
+    return (0, _brand.asDateTimeId)(date.toISOString());
+  }
+  const datePart = (0, _formatDateId.formatDateId)(parts);
+  const hour = String(parts.hour).padStart(2, '0');
+  const minute = String(parts.minute).padStart(2, '0');
+  const second = parts.second != null ? `:${String(parts.second).padStart(2, '0')}` : '';
+  return (0, _brand.asDateTimeId)(`${datePart}T${hour}:${minute}${second}`);
+}
+//# sourceMappingURL=formatDateTimeId.js.map

package/lib/commonjs/dates/datetime/formatDateTimeId.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_brand","require","_formatDateId","formatDateTimeId","parts","options","date","utc","Date","UTC","year","month","day","hour","minute","second","asDateTimeId","toISOString","datePart","formatDateId","String","padStart"],"sourceRoot":"../../../../src","sources":["dates/datetime/formatDateTimeId.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,aAAA,GAAAD,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,gBAAgBA,CAACC,KAAoB,EAAEC,OAA2B,EAAc;EAC9F,MAAMC,IAAI,GAAGD,OAAO,EAAEE,GAAG,GACrB,IAAIC,IAAI,CACNA,IAAI,CAACC,GAAG,CACNL,KAAK,CAACM,IAAI,EACVN,KAAK,CAACO,KAAK,GAAG,CAAC,EACfP,KAAK,CAACQ,GAAG,EACTR,KAAK,CAACS,IAAI,EACVT,KAAK,CAACU,MAAM,EACZV,KAAK,CAACW,MAAM,IAAI,CAClB,CACF,CAAC,GACD,IAAIP,IAAI,CAACJ,KAAK,CAACM,IAAI,EAAEN,KAAK,CAACO,KAAK,GAAG,CAAC,EAAEP,KAAK,CAACQ,GAAG,EAAER,KAAK,CAACS,IAAI,EAAET,KAAK,CAACU,MAAM,EAAEV,KAAK,CAACW,MAAM,IAAI,CAAC,CAAC;EAEjG,IAAIV,OAAO,EAAEE,GAAG,EAAE;IAChB,OAAO,IAAAS,mBAAY,EAACV,IAAI,CAACW,WAAW,CAAC,CAAC,CAAC;EACzC;EAEA,MAAMC,QAAQ,GAAG,IAAAC,0BAAY,EAACf,KAAK,CAAC;EACpC,MAAMS,IAAI,GAAGO,MAAM,CAAChB,KAAK,CAACS,IAAI,CAAC,CAACQ,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;EAChD,MAAMP,MAAM,GAAGM,MAAM,CAAChB,KAAK,CAACU,MAAM,CAAC,CAACO,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;EACpD,MAAMN,MAAM,GAAGX,KAAK,CAACW,MAAM,IAAI,IAAI,GAAG,IAAIK,MAAM,CAAChB,KAAK,CAACW,MAAM,CAAC,CAACM,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE;EACtF,OAAO,IAAAL,mBAAY,EAAC,GAAGE,QAAQ,IAAIL,IAAI,IAAIC,MAAM,GAAGC,MAAM,EAAE,CAAC;AAC/D","ignoreList":[]}

package/lib/commonjs/dates/datetime/formatDateTimeListHour.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatDateTimeListHour = formatDateTimeListHour;
+/**
+ * Formats the hour label for a date-time list column.
+ *
+ * @param hour - Hour value (0–23).
+ * @param options - When `hour12` is true, returns 1–12 without leading zero.
+ * @returns Hour label string.
+ */
+function formatDateTimeListHour(hour, options) {
+  if (options?.hour12) {
+    const h = hour % 12 || 12;
+    return String(h);
+  }
+  return String(hour).padStart(2, '0');
+}
+//# sourceMappingURL=formatDateTimeListHour.js.map

package/lib/commonjs/dates/datetime/formatDateTimeListHour.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["formatDateTimeListHour","hour","options","hour12","h","String","padStart"],"sourceRoot":"../../../../src","sources":["dates/datetime/formatDateTimeListHour.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,sBAAsBA,CAACC,IAAY,EAAEC,OAA8B,EAAU;EAC3F,IAAIA,OAAO,EAAEC,MAAM,EAAE;IACnB,MAAMC,CAAC,GAAGH,IAAI,GAAG,EAAE,IAAI,EAAE;IACzB,OAAOI,MAAM,CAACD,CAAC,CAAC;EAClB;EACA,OAAOC,MAAM,CAACJ,IAAI,CAAC,CAACK,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;AACtC","ignoreList":[]}

package/lib/commonjs/dates/datetime/formatDateTimeListMinute.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatDateTimeListMinute = formatDateTimeListMinute;
+/**
+ * Formats a zero-padded minute label for a date-time list column.
+ *
+ * @param minute - Minute value (0–59).
+ * @returns Two-digit minute string.
+ */
+function formatDateTimeListMinute(minute) {
+  return String(minute).padStart(2, '0');
+}
+//# sourceMappingURL=formatDateTimeListMinute.js.map

package/lib/commonjs/dates/datetime/formatDateTimeListMinute.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["formatDateTimeListMinute","minute","String","padStart"],"sourceRoot":"../../../../src","sources":["dates/datetime/formatDateTimeListMinute.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,wBAAwBA,CAACC,MAAc,EAAU;EAC/D,OAAOC,MAAM,CAACD,MAAM,CAAC,CAACE,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;AACxC","ignoreList":[]}

package/lib/commonjs/dates/datetime/formatDateTimeListPeriod.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formatDateTimeListPeriod = formatDateTimeListPeriod;
+var _intlCopy = require("../internal/intlCopy");
+/**
+ * Returns the day-period label (AM/PM or locale equivalent) derived from a 0–23 hour value.
+ *
+ * @param hour - Hour value (0–23).
+ * @param options - Locale for the day-period label.
+ */
+function formatDateTimeListPeriod(hour, options) {
+  return (0, _intlCopy.formatDayPeriodFromHour)(hour, options?.locale);
+}
+//# sourceMappingURL=formatDateTimeListPeriod.js.map

package/lib/commonjs/dates/datetime/formatDateTimeListPeriod.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_intlCopy","require","formatDateTimeListPeriod","hour","options","formatDayPeriodFromHour","locale"],"sourceRoot":"../../../../src","sources":["dates/datetime/formatDateTimeListPeriod.ts"],"mappings":";;;;;;AAAA,IAAAA,SAAA,GAAAC,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,wBAAwBA,CAACC,IAAY,EAAEC,OAA2B,EAAU;EAC1F,OAAO,IAAAC,iCAAuB,EAACF,IAAI,EAAEC,OAAO,EAAEE,MAAM,CAAC;AACvD","ignoreList":[]}

package/lib/commonjs/dates/datetime/isLocaleHour12.js

@@ -0,0 +1,30 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isLocaleHour12 = isLocaleHour12;
+/**
+ * Whether the given locale conventionally uses a 12-hour clock (AM/PM).
+ *
+ * Derived from the locale's resolved hour cycle so date-time components can
+ * default their clock to the locale instead of hardcoding 12-hour. Pass an
+ * explicit `hour12` to override.
+ *
+ * @param locale - BCP-47 locale. Defaults to `en-US`.
+ * @returns `true` when the locale uses a 12-hour clock.
+ */
+function isLocaleHour12(locale) {
+  try {
+    const resolved = new Intl.DateTimeFormat(locale ?? 'en-US', {
+      hour: 'numeric'
+    }).resolvedOptions();
+    if (typeof resolved.hour12 === 'boolean') {
+      return resolved.hour12;
+    }
+    return resolved.hourCycle === 'h11' || resolved.hourCycle === 'h12';
+  } catch {
+    return true;
+  }
+}
+//# sourceMappingURL=isLocaleHour12.js.map

package/lib/commonjs/dates/datetime/isLocaleHour12.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isLocaleHour12","locale","resolved","Intl","DateTimeFormat","hour","resolvedOptions","hour12","hourCycle"],"sourceRoot":"../../../../src","sources":["dates/datetime/isLocaleHour12.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,cAAcA,CAACC,MAAe,EAAW;EACvD,IAAI;IACF,MAAMC,QAAQ,GAAG,IAAIC,IAAI,CAACC,cAAc,CAACH,MAAM,IAAI,OAAO,EAAE;MAC1DI,IAAI,EAAE;IACR,CAAC,CAAC,CAACC,eAAe,CAAC,CAA6C;IAChE,IAAI,OAAOJ,QAAQ,CAACK,MAAM,KAAK,SAAS,EAAE;MACxC,OAAOL,QAAQ,CAACK,MAAM;IACxB;IACA,OAAOL,QAAQ,CAACM,SAAS,KAAK,KAAK,IAAIN,QAAQ,CAACM,SAAS,KAAK,KAAK;EACrE,CAAC,CAAC,MAAM;IACN,OAAO,IAAI;EACb;AACF","ignoreList":[]}

package/lib/commonjs/dates/datetime/isValidDateTimeId.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isValidDateTimeId = isValidDateTimeId;
+var _dateFns = require("date-fns");
+const LOCAL_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/;
+
+/**
+ * Type guard for local `DateTimeId` (`YYYY-MM-DDTHH:mm` or with seconds) and UTC `…Z` strings.
+ *
+ * @param dateTimeId - Candidate wire date-time string.
+ * @returns `true` when `dateTimeId` is a valid `DateTimeId`.
+ */
+function isValidDateTimeId(dateTimeId) {
+  if (!LOCAL_DATE_TIME_PATTERN.test(dateTimeId) && !dateTimeId.endsWith('Z')) {
+    return false;
+  }
+  const parsed = (0, _dateFns.parseISO)(dateTimeId);
+  return (0, _dateFns.isValid)(parsed);
+}
+//# sourceMappingURL=isValidDateTimeId.js.map

package/lib/commonjs/dates/datetime/isValidDateTimeId.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_dateFns","require","LOCAL_DATE_TIME_PATTERN","isValidDateTimeId","dateTimeId","test","endsWith","parsed","parseISO","isValid"],"sourceRoot":"../../../../src","sources":["dates/datetime/isValidDateTimeId.ts"],"mappings":";;;;;;AAAA,IAAAA,QAAA,GAAAC,OAAA;AAGA,MAAMC,uBAAuB,GAAG,0CAA0C;;AAE1E;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,UAAkB,EAA4B;EAC9E,IAAI,CAACF,uBAAuB,CAACG,IAAI,CAACD,UAAU,CAAC,IAAI,CAACA,UAAU,CAACE,QAAQ,CAAC,GAAG,CAAC,EAAE;IAC1E,OAAO,KAAK;EACd;EACA,MAAMC,MAAM,GAAG,IAAAC,iBAAQ,EAACJ,UAAU,CAAC;EACnC,OAAO,IAAAK,gBAAO,EAACF,MAAM,CAAC;AACxB","ignoreList":[]}

package/lib/commonjs/dates/datetime/nowDateTimeId.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.nowDateTimeId = nowDateTimeId;
+var _formatDateTimeId = require("./formatDateTimeId");
+/**
+ * Returns the local device date/time as a `DateTimeId`, truncated to the requested granularity.
+ *
+ * @param options - Optional granularity; defaults to `'minute'`.
+ * @returns Wire `DateTimeId` for the current local time.
+ *
+ * @example
+ * nowDateTimeId({ granularity: 'minute' }) // '2026-07-28T14:30'
+ */
+function nowDateTimeId(options) {
+  const now = new Date();
+  const parts = {
+    year: now.getFullYear(),
+    month: now.getMonth() + 1,
+    day: now.getDate(),
+    hour: now.getHours(),
+    minute: now.getMinutes(),
+    second: now.getSeconds()
+  };
+  switch (options?.granularity ?? 'minute') {
+    case 'day':
+      return (0, _formatDateTimeId.formatDateTimeId)({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: 0,
+        minute: 0
+      });
+    case 'hour':
+      return (0, _formatDateTimeId.formatDateTimeId)({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: 0
+      });
+    case 'minute':
+      return (0, _formatDateTimeId.formatDateTimeId)({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: parts.minute
+      });
+    case 'second':
+    default:
+      return (0, _formatDateTimeId.formatDateTimeId)(parts);
+  }
+}
+//# sourceMappingURL=nowDateTimeId.js.map

package/lib/commonjs/dates/datetime/nowDateTimeId.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_formatDateTimeId","require","nowDateTimeId","options","now","Date","parts","year","getFullYear","month","getMonth","day","getDate","hour","getHours","minute","getMinutes","second","getSeconds","granularity","formatDateTimeId"],"sourceRoot":"../../../../src","sources":["dates/datetime/nowDateTimeId.ts"],"mappings":";;;;;;AACA,IAAAA,iBAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,aAAaA,CAACC,OAA+C,EAAc;EACzF,MAAMC,GAAG,GAAG,IAAIC,IAAI,CAAC,CAAC;EACtB,MAAMC,KAAoB,GAAG;IAC3BC,IAAI,EAAEH,GAAG,CAACI,WAAW,CAAC,CAAC;IACvBC,KAAK,EAAEL,GAAG,CAACM,QAAQ,CAAC,CAAC,GAAG,CAAC;IACzBC,GAAG,EAAEP,GAAG,CAACQ,OAAO,CAAC,CAAC;IAClBC,IAAI,EAAET,GAAG,CAACU,QAAQ,CAAC,CAAC;IACpBC,MAAM,EAAEX,GAAG,CAACY,UAAU,CAAC,CAAC;IACxBC,MAAM,EAAEb,GAAG,CAACc,UAAU,CAAC;EACzB,CAAC;EAED,QAAQf,OAAO,EAAEgB,WAAW,IAAI,QAAQ;IACtC,KAAK,KAAK;MACR,OAAO,IAAAC,kCAAgB,EAAC;QACtBb,IAAI,EAAED,KAAK,CAACC,IAAI;QAChBE,KAAK,EAAEH,KAAK,CAACG,KAAK;QAClBE,GAAG,EAAEL,KAAK,CAACK,GAAG;QACdE,IAAI,EAAE,CAAC;QACPE,MAAM,EAAE;MACV,CAAC,CAAC;IACJ,KAAK,MAAM;MACT,OAAO,IAAAK,kCAAgB,EAAC;QACtBb,IAAI,EAAED,KAAK,CAACC,IAAI;QAChBE,KAAK,EAAEH,KAAK,CAACG,KAAK;QAClBE,GAAG,EAAEL,KAAK,CAACK,GAAG;QACdE,IAAI,EAAEP,KAAK,CAACO,IAAI;QAChBE,MAAM,EAAE;MACV,CAAC,CAAC;IACJ,KAAK,QAAQ;MACX,OAAO,IAAAK,kCAAgB,EAAC;QACtBb,IAAI,EAAED,KAAK,CAACC,IAAI;QAChBE,KAAK,EAAEH,KAAK,CAACG,KAAK;QAClBE,GAAG,EAAEL,KAAK,CAACK,GAAG;QACdE,IAAI,EAAEP,KAAK,CAACO,IAAI;QAChBE,MAAM,EAAET,KAAK,CAACS;MAChB,CAAC,CAAC;IACJ,KAAK,QAAQ;IACb;MACE,OAAO,IAAAK,kCAAgB,EAACd,KAAK,CAAC;EAClC;AACF","ignoreList":[]}

package/lib/commonjs/dates/datetime/parseDateTimeId.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parseDateTimeId = parseDateTimeId;
+var _dateFns = require("date-fns");
+var _isValidDateTimeId = require("./isValidDateTimeId");
+/**
+ * Parses a wire `DateTimeId` into numeric parts, or `null` when invalid.
+ *
+ * @param dateTimeId - Wire date-time string.
+ * @returns Parsed parts, or `null` when `dateTimeId` is invalid.
+ */
+function parseDateTimeId(dateTimeId) {
+  if (!(0, _isValidDateTimeId.isValidDateTimeId)(dateTimeId)) {
+    return null;
+  }
+  const date = (0, _dateFns.parseISO)(dateTimeId);
+  return {
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds()
+  };
+}
+//# sourceMappingURL=parseDateTimeId.js.map