@danxbot/ui 5.1.1 → 5.2.1

package/dist/types/lib/values/datetime.d.ts

@@ -0,0 +1,48 @@
+export interface FormatDateTimeOptions {
+    /**
+     * IANA zone to render in, e.g. `"America/New_York"`. Omit to use the
+     * reader's own zone — the right default for an instant, and the reason
+     * this is a parameter at all rather than always-local: a report emailed to
+     * someone in a different zone, or a server rendering a PDF, needs to say
+     * WHOSE clock the printed time is on.
+     */
+    zone?: string;
+}
+/**
+ * A stored instant → `"09/11/2026, 1:18 PM"` in `options.zone` (default: the
+ * reader's own).
+ *
+ * `null` / `undefined` / `""` render as the em dash. A non-empty value that
+ * does not parse as an instant is returned UNCHANGED — see `date.ts`'s
+ * docblock for why absence and corruption get different treatment.
+ */
+export declare function formatDateTime(value: string | number | null | undefined, options?: FormatDateTimeOptions): string;
+export interface ParseDateTimeOptions {
+    /**
+     * The zone a bare (no AM/PM-less midnight, no offset) typed value's
+     * wall-clock reading is IN. Omit to use the reader's own zone — matching
+     * `formatDateTime`'s default, so parsing a value typed against that display
+     * uses the same zone it was rendered in.
+     */
+    zone?: string;
+}
+/**
+ * A human-typed date-time → the stored ISO instant, or `null`.
+ *
+ * TWO PATHS, DELIBERATELY NOT ONE. An ISO string carrying its own offset or
+ * `Z` is unambiguous — `Date.parse` resolves it correctly regardless of what
+ * zone this function is running in, and is used directly. Everything else is
+ * a WALL-CLOCK reading with no zone of its own (`"09/11/2026, 1:18 PM"`), and
+ * `Date.parse`'s native handling of that shape resolves it against the
+ * HOST's zone — which is wrong the instant `options.zone` names a different
+ * one, e.g. a server in UTC parsing a value entered by a reader in
+ * `America/New_York`. So the wall-clock path is hand-parsed into fields and
+ * handed to `plainDateTimeToInstant`, which resolves it against the
+ * REQUESTED zone rather than whatever zone the code happens to be running in.
+ *
+ * A wall-clock reading that lands in a DST gap or overlap does not throw —
+ * `plainDateTimeToInstant`'s default (`"compatible"`) disambiguation applies,
+ * matching every other date library's default and `Temporal`'s own. See
+ * `time-dst.test.ts` for what that resolves to at a transition.
+ */
+export declare function parseDateTime(input: string, options?: ParseDateTimeOptions): string | null;

package/dist/types/lib/values/index.d.ts

@@ -0,0 +1,6 @@
+export { formatDate, parseDate } from "./date";
+export { formatDateTime, parseDateTime, type FormatDateTimeOptions, type ParseDateTimeOptions } from "./datetime";
+export { formatCurrency, parseCurrency } from "./currency";
+export { formatPhone, parsePhone } from "./phone";
+export { formatNumber, parseNumber, type FormatNumberOptions } from "./number";
+export { formatBoolean, parseBoolean, type FormatBooleanOptions } from "./boolean";

package/dist/types/lib/values/number.d.ts

@@ -0,0 +1,27 @@
+export interface FormatNumberOptions {
+    /**
+     * Fixed fraction digits, e.g. `1` for a percentage rendered as `"42.0"`.
+     * Omit to show the value's own precision, up to 6 fraction digits, with no
+     * trailing zeros invented.
+     */
+    decimals?: number;
+}
+/**
+ * `1234.5` → `"1,234.5"`. `null` / `undefined` → `"—"`.
+ *
+ * `NaN` / `Infinity` render as the em dash too, for the same reason
+ * `formatCurrency` groups them with absence rather than showing them back:
+ * the caller holds a `number`, not a string a person typed, so there is no
+ * original text to preserve.
+ */
+export declare function formatNumber(value: number | null | undefined, options?: FormatNumberOptions): string;
+/**
+ * A human-typed number → a `number`, or `null`.
+ *
+ * Strips thousands-separator commas (`"1,234.5"` → `1234.5`) before parsing,
+ * and accepts a leading `-` for a negative value. Rejects, rather than
+ * silently truncating, anything `parseFloat` would otherwise accept a PREFIX
+ * of — `"12abc"` is not twelve, it is a typo, and `parseFloat` alone would
+ * return `12` and hide that.
+ */
+export declare function parseNumber(input: string): number | null;

package/dist/types/lib/values/phone.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ten stored digits → `"(555) 123-4567"`. `null` / `undefined` / `""` → `"—"`.
+ *
+ * A non-empty value that is not exactly ten digits after parsing is returned
+ * UNCHANGED — the same "show the corruption, don't hide it behind absence"
+ * rule `formatDate` documents. A stored value should already be `parsePhone`'s
+ * output; if it is not, that is a data problem worth seeing in the row, not
+ * a blank field that looks like nobody ever entered a number.
+ */
+export declare function formatPhone(value: string | null | undefined): string;
+/**
+ * A human-typed phone number → ten stored digits, or `null`.
+ *
+ * Strips everything but digits, so `"(555) 123-4567"`, `"555.123.4567"`,
+ * `"555-123-4567 "` and `"5551234567"` all normalise the same way. A leading
+ * US country code (`"1"`, making 11 digits total) is dropped — `"+1 (555)
+ * 123-4567"` is the same number as `"(555) 123-4567"` and should be stored
+ * identically. Anything that is not exactly 10 digits after that — too few,
+ * too many, or an 11-digit number NOT starting with `1` (a foreign number
+ * mis-typed into a US field, not a US number with an extra digit) — returns
+ * `null` rather than truncating or padding a guess into place.
+ */
+export declare function parsePhone(input: string): string | null;

package/dist/types/pure.d.ts

@@ -24,13 +24,19 @@
  *
  * WHAT BELONGS HERE. Decisions about how a value READS, with no dependencies:
  * precision, units, the point at which a rounded figure stops telling the
- * truth. Deliberately NOT the calendar and time layers — `formatDateRange`,
- * `hoursInDay` and the rest are equally pure and would drag the whole `Intl`
- * time layer behind them, which is a bigger entry answering a question nobody
- * has asked yet. That is a separate decision, to be made when a consumer needs
- * it and not before.
+ * truth. Deliberately NOT the whole calendar layer — `formatDateRange`,
+ * `hoursInDay`, `monthGridDays` and the rest of `lib/time`'s CALENDAR-UI
+ * surface are equally pure but answer a question this entry's consumers do
+ * not have: they are grid-layout and scheduling math, not "turn a stored
+ * value into a string." `lib/values/date.ts` and `datetime.ts` are the
+ * question that WAS asked (a consumer's data grid duplicating this exact
+ * display/parse logic locally, instead of sourcing it from one place) and are
+ * exported below. They reuse `lib/time`'s zone arithmetic internally — that
+ * module has no React in it either, so pulling it in transitively costs real
+ * bytes but not the one thing this entry actually guards against.
  *
  * Everything exported here is ALSO exported from the main entry, so nothing
  * about this is a migration and no existing import has to change.
  */
-export { formatBytes, formatTokens } from "./lib/format";
+export { formatBytes, formatTokens, formatCompactNumber } from "./lib/format";
+export { formatDate, parseDate, formatDateTime, parseDateTime, type FormatDateTimeOptions, type ParseDateTimeOptions, formatCurrency, parseCurrency, formatPhone, parsePhone, formatNumber, parseNumber, type FormatNumberOptions, formatBoolean, parseBoolean, type FormatBooleanOptions, } from "./lib/values";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "5.1.1",
+  "version": "5.2.1",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",