@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/date-display.d.ts

@@ -0,0 +1,346 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Declare the zone instants render in — the host's half of objectui#11693.
+ *
+ * ## Why the zone enters HERE and nowhere else
+ *
+ * Every date and datetime face in the console is a function of this module
+ * (see the header), and each caller threads only its `locale`. The zone the
+ * signed-in workspace configures (`localization.timezone`, served by
+ * `GET /api/v1/auth/me/localization`) is the same for every face on the
+ * page, so it is set once, here, and every face reads it — rather than
+ * threaded through each call site, where one forgotten caller renders the
+ * same instant in a second zone beside the first (objectui#4272 is that
+ * defect for the locale). `LocalizationProvider` (`@object-ui/i18n`) is the
+ * host that calls this; a renderer never does.
+ *
+ * `undefined` (or an empty string) clears it: instants render in the
+ * viewer's zone again. A name this runtime's `Intl` does not know — a zone
+ * newer than the browser's time-zone data, say — clears it too, with a
+ * warning, rather than make every face throw the `RangeError` `Intl` raises
+ * for it.
+ *
+ * ⛔ A date-only value never takes the zone; see {@link toDisplayDate}.
+ */
+export declare function setDisplayTimeZone(timeZone: string | undefined): void;
+/** The zone {@link setDisplayTimeZone} declared, or `undefined` for the viewer's own. */
+export declare function getDisplayTimeZone(): string | undefined;
+/**
+ * Be told when the display zone changes; returns the unsubscribe. The shape is
+ * React's `useSyncExternalStore` contract, which is how `LocalizationProvider`
+ * re-renders its consumers once the zone they format in has moved.
+ */
+export declare function subscribeDisplayTimeZone(listener: () => void): () => void;
+/**
+ * Options shared by {@link formatDate} / {@link formatRelativeDate} /
+ * {@link formatDateTime}. One bag, and each function reads the keys it needs:
+ * `dueLike` and `t` only matter on the relative path, `style` is read by
+ * `formatDateTime` and by `formatDate` (see below).
+ */
+export interface DateDisplayOptions {
+    dueLike?: boolean;
+    /** BCP-47 display locale (ADR-0053 tenant default); falls back to the runtime locale. */
+    locale?: string;
+    /** i18n translate fn for phrases `Intl` can't produce (the "Overdue Nd" wording). */
+    t?: (key: string, params?: Record<string, unknown>) => string;
+    /**
+     * Named face, read by {@link formatDateTime} and {@link formatDate}. Each
+     * reads its own vocabulary: `'compact'` is `formatDateTime`'s dense grid
+     * cell face (objectui#7443), `'short'` and `'relative'` are `formatDate`'s;
+     * anything else, or absent, is that function's default face.
+     *
+     * It rides here rather than in a second positional parameter because
+     * `formatDateTime(value, options?)` is a PUBLISHED signature with `options`
+     * in position two (objectui#4272). A positional `style` would have displaced
+     * it: TypeScript would reject the old call, but a JavaScript caller would
+     * silently hand its options bag to the style slot and lose its locale —
+     * the #4272 defect again.
+     *
+     * ⚠️ On {@link formatDate} this key COLLIDES with a positional parameter of
+     * the same name, so the precedence is PINNED, not left to implementation
+     * order: **the positional argument wins**, and this key is consulted only
+     * when the positional slot is `undefined` (objectui#7745). See
+     * {@link formatDate}'s own note for why that direction and not the other.
+     *
+     * ⚠️ {@link formatRelativeDate} still does NOT read this key — the
+     * maintainer's long-run ruling on objectui#7443 names `formatDate` only, and
+     * whether the relative path's out-of-window fallback should honour it is a
+     * separate, deliberate call (objectui#7745's report).
+     */
+    style?: string;
+}
+/**
+ * A date that exists — the pattern alone would accept `2024-02-31`.
+ *
+ * `true` only for a date-only ISO string (`YYYY-MM-DD`, the shape
+ * {@link ISO_DATE_ONLY_RE} names) whose year, month and day read back
+ * unchanged from the calendar. Anything else — another shape, a time part, an
+ * out-of-range month, or a day its month does not have — is `false`.
+ *
+ * ## Why this lives here (objectui#10026)
+ *
+ * It used to be module-private in `@object-ui/components`' filter builder,
+ * which refused `2026-02-30` at the AUTHORING boundary, while this module — a
+ * package below it, unable to import it — ROLLED the same value into March 2nd
+ * on every display face. One concept, two answers. It moved down, exactly as
+ * `formatDate` itself moved into this package (see the header), so the filter
+ * builder and {@link toDisplayDate} now ask the one function. ⛔ A move, not a
+ * copy: `@object-ui/components` imports it from here.
+ *
+ * ## Why the engine cannot answer this on its own
+ *
+ * ECMAScript's date-string parse accepts a DAY of `01`-`31` for every month
+ * and rolls the surplus forward: `Date.parse('2026-02-30')` is March 2nd, not
+ * `NaN`. It rejects an out-of-range MONTH (`2026-13-01`), which is why a
+ * bad month was always a dash on the display path and a bad day never was.
+ * So the day is read back instead: build the date in UTC (no zone, so no DST
+ * gap can move it) and require all three parts to survive.
+ *
+ * `setUTCFullYear` rather than `Date.UTC(year, …)`: the latter maps years
+ * 0-99 onto 1900+y, so it answered `false` for `0026-08-01` — a real day,
+ * and one {@link toDisplayDate} renders (it undoes the same legacy mapping for
+ * the same reason). The move had to fix that, or refusing through this
+ * function would have dashed every year below 100.
+ */
+export declare function isRealCalendarDate(dateOnly: string): boolean;
+/**
+ * The ONE `value -> Date` step behind every function below.
+ *
+ * ## The defect (objectui#10110)
+ *
+ * ECMAScript parses the two ISO shapes into two different zones: a DATE-ONLY
+ * form is UTC, while a date-TIME form without an offset is local. So
+ * `new Date('2026-08-01')` is UTC midnight, and every getter this module then
+ * uses — `getFullYear`, `getMonth`, `getDate`, and `toLocaleDateString`'s own
+ * internal ones — reads it back in the VIEWER's zone. West of UTC that lands
+ * on the previous calendar day: `2026-08-01` rendered `Jul 31` for a UTC-7
+ * viewer while the stored value, the API response and a UTC+8 viewer all said
+ * August 1st. The relative branch shifted with it, one day per day
+ * (`2026-08-31` read `4 days ago` on the 3rd instead of `3 days ago`),
+ * because it compares two LOCAL start-of-days.
+ *
+ * ## The repair, and why it is not an offset
+ *
+ * A date-only value names a CALENDAR DAY and carries no instant, so there is
+ * no conversion to perform: this rebuilds it at LOCAL midnight of the day it
+ * names, and every local getter downstream then reports that same day in
+ * every zone. ⛔ Nothing here adds or subtracts hours. An offset that
+ * cancels the shift would be wrong again at the next DST boundary and wrong
+ * in the opposite direction for a viewer EAST of UTC, where the UTC-midnight
+ * parse already lands on the right day — the co-located suite drives both.
+ * `GridField`'s sub-grid cell already parsed its own date-only values this
+ * way before reaching `formatDate`; this is that treatment, moved to the one
+ * place every caller passes through (the sub-grid reads it from here since
+ * objectui#10301).
+ *
+ * A value with a time part is not rebuilt, in both spellings: it HAS an
+ * instant, and rendering an instant in the viewer's zone is the whole point
+ * of a `datetime`. The regex is what separates them, so the split is the
+ * VALUE's shape and never the field's declared type, which this module (pure,
+ * no schema) cannot see.
+ *
+ * ## What it refuses (objectui#10026)
+ *
+ * The engine's own parse still decides what is a date at all (`2026-13-01`
+ * is an Invalid Date, and so every face below renders `—`), with ONE
+ * addition: a date-only value naming a day its month does not have. The
+ * engine accepts `2026-02-30` and rolls it into March 2nd, so before this
+ * card every date face showed a real day nobody wrote, with nothing to say
+ * so. This step hands back an Invalid Date for it instead — the same answer
+ * the engine gives a bad month — so every caller renders the face it already
+ * renders for an unparsable value: `—` from the functions below, `EmptyValue`
+ * from the field carriers that read validity here, the raw stored string from
+ * a caller whose unparsable face is the raw string. ⛔ No new marker.
+ *
+ * The maintainer's ruling on objectui#10026 (option A) placed the refusal on
+ * the SHARED path, in this step and not in any one consumer: refusing in a
+ * single face would re-create the list-cell-versus-measure split
+ * objectui#4576 recorded. {@link isRealCalendarDate} is the one judgement,
+ * shared with the filter builder's authoring boundary.
+ *
+ * A value that carries a TIME is refused the same way when the day it is
+ * written on does not exist (objectui#10301): `2026-02-30T10:00:00Z` parses
+ * too, and rendered `Mar 2, 2026, 10:00 AM` on every datetime face. Triage
+ * graded that an inherited branch of the same ruling. The judgement reads the
+ * value's leading `YYYY-MM-DD` AS WRITTEN, never the day its instant lands on
+ * in some zone: a parsed `Date` always names a real day, so a check made after
+ * any conversion could only miss the refusal, and a real day written with an
+ * offset (`2026-02-28T23:30:00-05:00`, March 1st in UTC) is kept. A real
+ * date-time is otherwise untouched — no rebuild, the engine's instant.
+ *
+ * ## Why it is exported (objectui#10183)
+ *
+ * A caller that formats with its own `Intl` options — a face none of the
+ * functions below produce, such as the record summary chip's
+ * `dateStyle: 'medium'` — or that compares a value against "today" needs the
+ * `Date` itself, not a string. Such callers used to parse the value on their
+ * own (`new Date(value)`, or `Date.parse` and then a `Date` handed to
+ * `formatDate`, which this step then leaves alone), so the objectui#10110
+ * repair never reached them and each still read a date-only value one day
+ * early west of UTC. They take the `Date` from here instead.
+ *
+ * ⛔ Read the result with LOCAL getters or local-zone `Intl` formatting only.
+ * For a date-only value it is local midnight of the named day, so its
+ * `toISOString()` / UTC getters name the previous day east of UTC — hand
+ * those the stored value, never this. The faces in this module know such a
+ * `Date` when they are handed one and keep it out of the display zone
+ * (objectui#11693, see `calendarDays`).
+ */
+export declare function toDisplayDate(value: string | Date | number): Date;
+/**
+ * THE ONE READ of a stored END, where a bar or span is drawn to
+ * (objectui#11141): {@link toDisplayDate}'s read, and then, for a date-only
+ * value only, the next day's local midnight.
+ *
+ * ## The rule (objectui#11112's ruling, one home since objectui#11141)
+ *
+ * A date-only end is INCLUSIVE: `2024-01-01` to `2024-01-15` runs through
+ * January 15th, so the span is drawn to the start of the 16th, and a
+ * successor starting `2024-01-16` begins exactly where it ends. A span whose
+ * date-only start and end name the same day is one day long, across a DST
+ * change too: the step is a calendar day (`setDate`), never 24 hours, so it
+ * lands on the next local midnight, or on that day's first hour where its
+ * midnight does not exist. That is how a project plan and the schema
+ * catalog's gantt plans author an end.
+ *
+ * The result is the EXCLUSIVE end instant of a half-open span `[start, end)`,
+ * the form every gantt surface draws and schedules with. Date-only is decided
+ * by the value's own shape, with {@link isRealCalendarDate}, exactly as
+ * {@link toDisplayDate} decides it, so an end reads its day as a start does and
+ * then runs to that day's end. A value with a time part, a number or a `Date`
+ * is an instant: the span ends at it, and it is handed back as
+ * {@link toDisplayDate} hands it back.
+ *
+ * {@link toInclusiveEndDay} is the exact inverse: it names the day a span
+ * ending here runs through, so a read and a write of a date-only end agree.
+ *
+ * ⛔ One rule, one place: `plugin-timeline`'s gantt variant and
+ * `plugin-gantt` both read their ends here. A second copy of the step in a
+ * consumer is how the two gantt surfaces came to draw one plan a day apart.
+ * ⛔ Read the result with LOCAL getters only, as {@link toDisplayDate}'s is.
+ */
+export declare function toDisplayEndDate(value: string | Date | number): Date;
+/**
+ * The day a span ending at `end` runs through: local midnight of the day that
+ * holds the last instant before `end` (objectui#11141).
+ *
+ * This is the exact inverse of {@link toDisplayEndDate} on a date-only end:
+ * the instant it reads `2024-01-15` as, local midnight of the 16th, names the
+ * 15th here, so a read, a drag and a write of a stored date-only end leave it
+ * the day it was, and a bar dragged to end at a day's local midnight names the
+ * day BEFORE it. An end inside a day (a `datetime` end, or a shift band's
+ * edge) names that day, the last one the span reaches into.
+ *
+ * It names a day for display and for a date-only write. ⛔ It is not a read of
+ * a stored value, and a `datetime` end still keeps its own instant: hand this
+ * only to a face that names a day, or to a field that stores one. Read the
+ * result with LOCAL getters only; an Invalid Date stays invalid.
+ */
+export declare function toInclusiveEndDay(end: Date): Date;
+/**
+ * Format date as relative time (e.g., "3 days ago", "Today", "Overdue 3d"),
+ * localized via `Intl.RelativeTimeFormat` (objectstack-ai/objectstack#3040).
+ *
+ * `dueLike` gates the "Overdue" wording — a past `start_date`/`created_at`
+ * isn't overdue, only a past due/deadline-semantic field is. Non-due-like
+ * past dates render as plain "N days ago" instead. The overdue phrase has no
+ * `Intl` equivalent, so it resolves through `options.t` (key
+ * `fields.relativeDate.overdue`) with an English fallback.
+ *
+ * Days are counted in the display zone (objectui#11693): "today" is the
+ * display zone's today, and an instant falls on its day there. A date-only
+ * value keeps the day it names and is counted from that same today, so an
+ * instant and a date-only value on one day read one phrase.
+ */
+export declare function formatRelativeDate(value: string | Date | number, options?: DateDisplayOptions): string;
+/**
+ * Format date value.
+ *
+ * The named face comes from EITHER spelling — the positional `style`
+ * parameter or `options.style` — and the precedence between them is pinned
+ * (objectui#7745):
+ *
+ * > **The positional argument wins. `options.style` is consulted only when the
+ * > positional slot is `undefined`.**
+ *
+ * Before #7745 only the positional spelling was read here, while
+ * {@link formatDateTime} read only the `options` one — one shared bag, two
+ * spellings for one concept, and on THIS function the options spelling did
+ * nothing at all: `formatDate(v, undefined, { style: 'short' })` silently
+ * rendered the default face with no diagnostic. Reading the key is the
+ * additive half of the maintainer's long-run ruling on objectui#7443.
+ *
+ * Why the positional wins, and not the newer key:
+ *
+ *   - It is the ONLY direction that is purely additive. It fires exactly on
+ *     the input that is a silent no-op today (positional absent, key present);
+ *     every call that renders a face today renders the same face after.
+ *   - The bag is SHARED across three functions, so it can legitimately carry a
+ *     key meant for a sibling — that is this module's convention (`dueLike`
+ *     and `t` are read by `formatRelativeDate` alone). A caller that built
+ *     `{ style: 'compact', locale }` for `formatDateTime` and reused the bag
+ *     for `formatDate(v, 'short', bag)` must keep its short face. A key aimed
+ *     at a sibling function must not outrank an argument written for THIS
+ *     call — that is objectui#7694's shape (an alias overwriting the canonical
+ *     key), and the silent-override half of objectui#4272.
+ *
+ * `??`, not `||`, is what "absent" means here: `formatDate(v, '', bag)`
+ * renders the default face today and must keep doing so, so an empty string
+ * counts as GIVEN and does not fall through to the key.
+ */
+export declare function formatDate(value: string | Date | number, style?: string, options?: DateDisplayOptions): string;
+/**
+ * The `'compact'` datetime face as the two halves a grid cell paints
+ * separately — `7/4/2024` and `7:00 am` for `2024-07-04T07:00:00Z` in `en-US`.
+ *
+ * `formatDateTime(value, { style: 'compact', ...options })` is exactly
+ * `date + ' ' + time` of what this returns, so a caller that wants the face
+ * as ONE string and a caller that wants to style the halves differently
+ * cannot drift apart. That drift is what objectui#7443 recorded:
+ * `DateTimeCellRenderer` inlined these two option bags and never called this
+ * module, so `datetime` had two display conventions while `date` had one —
+ * the same shape as objectui#4576, which this repo has already paid for once.
+ *
+ * `null` for a value this module renders as `'—'`; the cell renders its own
+ * empty state for those, so it never sees the dash.
+ */
+export declare function formatDateTimeCompactParts(value: string | Date | number, options?: DateDisplayOptions): {
+    date: string;
+    time: string;
+} | null;
+/**
+ * Format datetime value.
+ *
+ * `options.style` selects a named face:
+ *
+ *   - `'compact'` — the dense grid face, `7/4/2024 7:00 am` in `en-US`. It is
+ *     what every `datetime` CELL renders, and what `DateTimeCellRenderer`
+ *     used to build from its own inlined `Intl` bags (objectui#7443).
+ *   - anything else, including absent — the verbose default,
+ *     `Jul 4, 2024, 07:00 AM` in `en-US`. Unchanged, and still what a
+ *     non-cell caller (dataset measure, gantt tooltip, data-table) gets.
+ *
+ * The signature is `(value, options?)`, unchanged: `style` is a key of
+ * `options`, not a positional parameter, so every existing call —
+ * `formatDateTime(v, { locale })` included — keeps meaning exactly what it
+ * meant (see the note on `DateDisplayOptions.style` for why the positional
+ * shape `formatDate` uses was refused here).
+ *
+ * `options` is optional, so a caller that passes nothing keeps the exact
+ * runtime-default behavior it had. Before objectui#4272 the parameter did not
+ * exist at all, which meant no caller could localize this function however
+ * hard it tried — it always handed `Intl` an `undefined` tag, i.e. the
+ * MACHINE's locale, which is neither of the repo's two locale channels.
+ * Callers should pass the tag from `useDisplayLocale()`.
+ *
+ * The zone is NOT an option: an instant renders in the display zone the host
+ * declared with {@link setDisplayTimeZone}, else the viewer's, on every face
+ * this module produces (objectui#11693).
+ */
+export declare function formatDateTime(value: string | Date | number, options?: DateDisplayOptions): string;