@open-mercato/ui 0.7.1-develop.7153.1.7145d295e6 → 0.7.1-develop.7170.1.d95074d7ba

package/src/primitives/__tests__/date-format.test.ts

@@ -1,9 +1,15 @@
+import { pl } from 'date-fns/locale/pl'
 import {
   deriveDateDisplayFormat,
+  formatDisplayDate,
+  formatDisplayDateTime,
   formatWithPublicDateFormat,
   normalizeDateFormatPattern,
+  resolveDisplayDateTimeFormat,
   resolvePublicDateFormat,
   resolvePublicDateTimeFormat,
+  toDateInputValue,
+  toUtcDateInputValue,
 } from '../date-format'
 
 const ORIGINAL_ENV = { ...process.env }
@@ -41,3 +47,182 @@ describe('date display format helpers', () => {
     expect(value).toBe('2026-05-09 10:30')
   })
 })
+
+describe('display value helpers', () => {
+  // Local midnight is `00:00` in every zone, so asserting the time pins the parse without the
+  // runner being in a particular zone. A UTC parse reads `02:00` in Europe/Warsaw.
+  it('parses a date-only value as local midnight, so the stored day survives the viewer timezone', () => {
+    expect(formatDisplayDateTime('2026-07-01', 'pl')).toBe('1 lip 2026, 00:00')
+    expect(formatDisplayDate('2026-07-01', 'pl')).toBe('1 lip 2026')
+  })
+
+  // With no env override the display pattern is the locale's own, and the month name comes from
+  // the resolved date-fns locale — so this agrees with `ReturnsSection` / `ShipmentsSection`,
+  // which render `9 cze 2026` beside it. A bare string locale is enough; callers hold one.
+  // Formatting through `Intl` rather than a derived pattern, because a two-branch "day first or
+  // not" heuristic cannot express either of these: `ko` writes the year first, `de` is numeric and
+  // dotted. Both are locales this repo ships, and this path feeds every backend table.
+  it.each([
+    ['en', 'Jul 1, 2026'],
+    ['pl', '1 lip 2026'],
+    ['es', '1 jul 2026'],
+    ['de', '01.07.2026'],
+    ['ko', '2026. 7. 1.'],
+  ])('renders %s correctly, including the locales a pattern heuristic gets wrong', (locale, expected) => {
+    expect(formatDisplayDate('2026-07-01', locale)).toBe(expected)
+  })
+
+  // `en` is `defaultLocale` (`packages/shared/src/lib/i18n/config.ts`), so this is what most
+  // deployments actually render. `timeStyle: 'short'` moves it from the locale-neutral
+  // `2026-07-01 00:00` to a 12-hour clock — the widest-reach consequence of this change, and the
+  // one a reader is most likely to mistake for a bug. Pinned so it is a decision, not a side effect.
+  // Operators who want the old shape set `NEXT_PUBLIC_OM_DATE_TIME_FORMAT=yyyy-MM-dd HH:mm`.
+  it('renders the default locale on a 12-hour clock, not the previous ISO-like shape', () => {
+    expect(formatDisplayDateTime('2026-07-01', 'en')).toBe('Jul 1, 2026, 12:00 AM')
+    expect(formatDisplayDate('2026-07-01', 'en')).toBe('Jul 1, 2026')
+  })
+
+  it('lets an env pattern override the locale, so a deployment can pin one shape', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'yyyy-MM-dd'
+    expect(formatDisplayDate('2026-07-01', 'ko')).toBe('2026-07-01')
+    expect(formatDisplayDate('2026-07-01', 'de')).toBe('2026-07-01')
+  })
+
+  it('keeps the instant for an offset-carrying value', () => {
+    expect(formatDisplayDateTime('2026-07-01T09:30:00Z', 'pl')).toBe(
+      new Intl.DateTimeFormat('pl', { dateStyle: 'medium', timeStyle: 'short' }).format(
+        new Date('2026-07-01T09:30:00Z'),
+      ),
+    )
+  })
+
+  it('accepts a Date as well as a string', () => {
+    expect(formatDisplayDate(new Date(2026, 6, 1), 'pl')).toBe('1 lip 2026')
+    expect(formatDisplayDateTime(new Date(2026, 6, 1, 9, 30), 'pl')).toBe('1 lip 2026, 09:30')
+    expect(formatDisplayDate(new Date('not-a-date'), 'pl')).toBeNull()
+  })
+
+  it('tolerates surrounding whitespace, as DataTable does', () => {
+    expect(formatDisplayDate(' 2026-07-01 ', 'pl')).toBe('1 lip 2026')
+    expect(formatDisplayDate('   ', 'pl')).toBeNull()
+  })
+
+  it('honours the configured env formats', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT = 'dd.MM.yyyy HH:mm'
+    expect(formatDisplayDate('2026-07-01')).toBe('01.07.2026')
+    // Compared against the formatter rather than a literal: `09:30Z` falls on 30 June at UTC-10
+    // and further west, so a hardcoded `01.07.2026` would fail there.
+    expect(formatDisplayDateTime('2026-07-01T09:30:00Z')).toBe(
+      formatWithPublicDateFormat(new Date('2026-07-01T09:30:00Z'), 'dd.MM.yyyy HH:mm'),
+    )
+  })
+
+  it('returns null on empty or unparsable input', () => {
+    expect(formatDisplayDate(null)).toBeNull()
+    expect(formatDisplayDate('')).toBeNull()
+    expect(formatDisplayDate('not-a-date')).toBeNull()
+    expect(formatDisplayDateTime(undefined)).toBeNull()
+    expect(formatDisplayDateTime('not-a-date')).toBeNull()
+  })
+})
+
+describe('resolveDisplayDateTimeFormat', () => {
+  // DataTable resolves its cells through this, so the date vars must stay in the chain and stay
+  // bare — appending `HH:mm` to a caller's date-only pattern would change every existing table.
+  it('falls back through the date vars, used bare', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    expect(resolveDisplayDateTimeFormat()).toBe('dd.MM.yyyy')
+  })
+
+  it('prefers the date-time vars', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT = 'dd.MM.yyyy HH:mm'
+    expect(resolveDisplayDateTimeFormat()).toBe('dd.MM.yyyy HH:mm')
+  })
+
+  it('reports no override when nothing is configured, so the caller falls to Intl', () => {
+    expect(resolveDisplayDateTimeFormat()).toBeNull()
+  })
+})
+
+describe('toDateInputValue', () => {
+  // `new Date(x).toISOString().slice(0, 10)` yields the UTC day, so a just-past-midnight timestamp
+  // east of UTC names the previous day. Asserted against the Date's own local getters rather than a
+  // literal, so the contract holds in every runner zone — including UTC, where the two coincide.
+  it('yields the local calendar day, not the UTC one', () => {
+    // Constructed from local components, so it is local July 2 in every zone — the
+    // zone-independence is in the construction, not in the assertion.
+    const justAfterLocalMidnight = new Date(2026, 6, 2, 0, 30)
+
+    expect(toDateInputValue(justAfterLocalMidnight)).toBe('2026-07-02')
+    expect(toDateInputValue('2026-07-01')).toBe('2026-07-01')
+  })
+
+  it('ignores the configured display format, since the input requires yyyy-MM-dd', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    expect(toDateInputValue('2026-07-01')).toBe('2026-07-01')
+  })
+
+  it('returns null when there is nothing to show', () => {
+    expect(toDateInputValue(null)).toBeNull()
+    expect(toDateInputValue('not-a-date')).toBeNull()
+  })
+})
+
+// `toDateInputValue` and `toUtcDateInputValue` differ by exactly one day for half the planet, so
+// which one a field gets is a correctness question, not a style one.
+//
+// In a UTC runner the two are the same function, so these cases cannot fail there — and CI runs
+// in UTC. `jest.config.base.cjs` therefore pins the whole suite to `America/New_York`, so the frame
+// decision is enforced everywhere rather than only on a runner that happens to sit west of UTC.
+// Setting `process.env.TZ` inside this file would NOT work: jest gives each test file a sandboxed
+// copy of `process.env`, so the assignment never reaches V8's timezone cache.
+describe('toUtcDateInputValue', () => {
+  // The shape that actually arrives from the API for a date-only column: the editor submits a bare
+  // `yyyy-MM-dd`, `z.coerce.date()` stores UTC midnight, the route returns it with a `Z`.
+  const STORED_DATE_ONLY = '2026-07-01T00:00:00.000Z'
+
+  it('round-trips a date-only value stored as UTC midnight', () => {
+    expect(toUtcDateInputValue(STORED_DATE_ONLY)).toBe('2026-07-01')
+  })
+
+  it('reads the frame the value was written in, whatever the viewer zone', () => {
+    expect(toUtcDateInputValue(STORED_DATE_ONLY)).toBe(
+      new Date(STORED_DATE_ONLY).toISOString().slice(0, 10),
+    )
+  })
+
+  // A bare day names itself. Parsing it into an instant first — by either reading — moves it in
+  // some zone, which is how the first version of this helper was wrong.
+  it('passes a bare date-only string through untouched', () => {
+    expect(toUtcDateInputValue('2026-07-01')).toBe('2026-07-01')
+    expect(toUtcDateInputValue(' 2026-07-01 ')).toBe('2026-07-01')
+  })
+
+  it('returns null when there is nothing to show', () => {
+    expect(toUtcDateInputValue(null)).toBeNull()
+    expect(toUtcDateInputValue('not-a-date')).toBeNull()
+  })
+})
+
+// A row that renders a stored date-only column and also seeds an editor from it must name one day.
+// `PaymentsSection` renders `receivedAt` while its Edit dialog seeds from `receivedAt.slice(0, 10)`
+// — the UTC day — so the rendered day has to be derived the same way, or one row contradicts itself.
+describe('rendering a stored date-only column', () => {
+  const STORED = '2026-07-01T00:00:00.000Z'
+
+  it('agrees with an editor that seeds from the UTC day', () => {
+    expect(toUtcDateInputValue(STORED)).toBe(STORED.slice(0, 10))
+    expect(formatDisplayDate(toUtcDateInputValue(STORED), 'pl')).toBe('1 lip 2026')
+  })
+
+  it('still honours the configured display format', () => {
+    process.env.NEXT_PUBLIC_OM_DATE_FORMAT = 'dd.MM.yyyy'
+    expect(formatDisplayDate(toUtcDateInputValue(STORED))).toBe('01.07.2026')
+  })
+
+  it('renders nothing when the column is empty', () => {
+    expect(formatDisplayDate(toUtcDateInputValue(null))).toBeNull()
+  })
+})

package/src/primitives/date-format.ts

@@ -1,4 +1,5 @@
 import { format as formatDateFns } from 'date-fns/format'
+import { parseISO } from 'date-fns/parseISO'
 import type { Locale } from 'date-fns/locale'
 
 type LocaleLike = Locale | string | null | undefined
@@ -58,3 +59,147 @@ export function formatWithPublicDateFormat(date: Date, format: string, locale?:
     return null
   }
 }
+
+/**
+ * The configured pattern for a date rendered as static text, or `null` when none is set.
+ *
+ * `null` is the interesting case: with no override the format comes from `Intl`, which knows the
+ * ordering and month naming of every locale. A pattern heuristic does not — it can only ask
+ * "day first or not", which is wrong for `ko` (year first) and for `de` (numeric, dotted). Those
+ * are two of the five locales this repo ships, and this resolver feeds every backend table.
+ *
+ * ISO stays the contract for machine-facing values — `toDateInputValue`, storage, serialization —
+ * never for a label.
+ *
+ * A pattern is a deliberate operator pin: it wins over the locale entirely, and month tokens render
+ * in English on that path — `NEXT_PUBLIC_OM_DATE_FORMAT=d MMM yyyy` gives `1 Jul 2026` to a `pl`
+ * tenant, not `1 lip 2026`. Set a numeric pattern, or leave it unset and let `Intl` localize.
+ */
+export function resolveDisplayDateFormat(): string | null {
+  return (
+    normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_FORMAT)
+  )
+}
+
+/**
+ * As `resolveDisplayDateFormat`, for a value that carries a real time of day.
+ *
+ * The date vars are in the chain, and used bare, because a caller that sets only a date pattern has
+ * said how a date should look and said nothing about time — appending `HH:mm` would invent a
+ * requirement. This is the precedence `resolvePublicDateTimeFormat` already uses.
+ */
+export function resolveDisplayDateTimeFormat(): string | null {
+  return (
+    normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_TIME_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_OM_DATE_FORMAT)
+    ?? normalizeDateFormatPattern(process.env.NEXT_PUBLIC_DATE_FORMAT)
+  )
+}
+
+/**
+ * **ISO-8601 input only.** `parseISO` rejects shapes `new Date` would have accepted — `'July 1, 2026'`,
+ * `'2026/07/01'` — so those now return `null` and the caller renders its empty label. Every in-repo
+ * caller passes ISO; `DataTable.tryParseDate` keeps a `new Date` fallback because its input is
+ * arbitrary column data, while these helpers' is not.
+ *
+ * `parseISO`, not `new Date`: a bare `yyyy-MM-dd` names a calendar day, and `new Date` reads it as
+ * UTC midnight — which `format` then renders as the PREVIOUS day in every zone west of UTC. On a
+ * date-only string `parseISO` returns local midnight of the stored day, so the day survives; a value
+ * carrying a time or an offset keeps its instant either way.
+ */
+function parseDisplayValue(value: string | Date | null | undefined): Date | null {
+  if (value == null) return null
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = parseISO(trimmed)
+  return Number.isNaN(parsed.getTime()) ? null : parsed
+}
+
+function intlLocale(locale?: LocaleLike): string | undefined {
+  if (!locale) return undefined
+  return typeof locale === 'string' ? locale : locale.code
+}
+
+const DISPLAY_STYLES = {
+  date: { dateStyle: 'medium' },
+  datetime: { dateStyle: 'medium', timeStyle: 'short' },
+} as const satisfies Record<string, Intl.DateTimeFormatOptions>
+
+// Constructing an `Intl.DateTimeFormat` costs ~40x using one (Node 24: ~31 µs vs ~0.8 µs), and these
+// helpers render every date cell AND its tooltip in `DataTable` — two constructions per cell, so a
+// 100-row page with two date columns would pay 400 of them on every sort, filter and keystroke.
+// A formatter is immutable and the key space is the locales a deployment ships, so one instance per
+// (locale, style) is kept for the process. The style name is the key, so the two cannot desync.
+const formatterCache = new Map<string, Intl.DateTimeFormat>()
+
+function getFormatter(locale: string | undefined, style: keyof typeof DISPLAY_STYLES): Intl.DateTimeFormat {
+  const key = `${locale ?? ''}|${style}`
+  const cached = formatterCache.get(key)
+  if (cached) return cached
+  const created = new Intl.DateTimeFormat(locale, DISPLAY_STYLES[style])
+  formatterCache.set(key, created)
+  return created
+}
+
+/** Render a date for display, or `null` when there is nothing valid to show. */
+export function formatDisplayDate(value: string | Date | null | undefined, locale?: LocaleLike): string | null {
+  const parsed = parseDisplayValue(value)
+  if (!parsed) return null
+  const pattern = resolveDisplayDateFormat()
+  if (pattern) return formatWithPublicDateFormat(parsed, pattern)
+  return getFormatter(intlLocale(locale), 'date').format(parsed)
+}
+
+/** Render a timestamp for display, or `null` when there is nothing valid to show. */
+export function formatDisplayDateTime(value: string | Date | null | undefined, locale?: LocaleLike): string | null {
+  const parsed = parseDisplayValue(value)
+  if (!parsed) return null
+  const pattern = resolveDisplayDateTimeFormat()
+  if (pattern) return formatWithPublicDateFormat(parsed, pattern)
+  return getFormatter(intlLocale(locale), 'datetime').format(parsed)
+}
+
+/**
+ * The **local** calendar day of a real instant, as the `yyyy-MM-dd` an `<input type="date">` requires.
+ *
+ * Not `new Date(value).toISOString().slice(0, 10)`: `toISOString` converts to UTC first, so east of
+ * UTC an evening timestamp yields the previous day. Rendering that through `formatDisplayDate` is
+ * faithful to a day that was already wrong.
+ *
+ * **Precondition: `value` must be a real instant** — a moment that happened, whose local day is the
+ * one a human would name. It must NOT be a date-only value that some write path stored as UTC
+ * midnight: reading that back locally names the PREVIOUS day west of UTC, which is the mirror image
+ * of the bug above. Use `toUtcDateInputValue` for those; see its note for how to tell them apart.
+ */
+export function toDateInputValue(value: string | Date | null | undefined): string | null {
+  const parsed = parseDisplayValue(value)
+  return parsed ? formatWithPublicDateFormat(parsed, 'yyyy-MM-dd') : null
+}
+
+/**
+ * The **UTC** calendar day of a value, as the `yyyy-MM-dd` an `<input type="date">` requires.
+ *
+ * For a column that stores a date-only value as UTC midnight — a bare `yyyy-MM-dd` submitted by a
+ * date input, coerced with `z.coerce.date()` and returned as `…T00:00:00.000Z`. The stored instant
+ * carries no local meaning, so the round trip only closes if it is read back in the same frame it
+ * was written in: UTC.
+ *
+ * Which helper a field needs is decided by its WRITE path, not by its type. If the value can be set
+ * from a date input, it is a UTC day; if it is only ever stamped from a clock, it is an instant.
+ */
+export function toUtcDateInputValue(value: string | Date | null | undefined): string | null {
+  if (value == null) return null
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!trimmed) return null
+    // A bare calendar day is already the answer. Parsing it into an instant first — by either
+    // reading — can only move it, since there is no zone in which it was meant.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return trimmed
+    const parsed = new Date(trimmed)
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString().slice(0, 10)
+  }
+  return Number.isNaN(value.getTime()) ? null : value.toISOString().slice(0, 10)
+}