@data-club/ai-hub 0.0.2 → 0.0.3

package/src/util/relativeTime.ts

@@ -0,0 +1,90 @@
+/**
+ * Locale-aware relative-time / date helpers.
+ *
+ * These replace the three hand-rolled English `"N min ago"` / `"yesterday"`
+ * formatters (sessions panel, admin sessions overview, admin settings). They
+ * delegate to the platform `Intl.RelativeTimeFormat` / `Intl.DateTimeFormat`,
+ * which know each language's CLDR plural rules for free — important for
+ * Czech / Slovak where the count word changes between 1, 2–4 and 5+ ("1
+ * minúta" / "2 minúty" / "5 minút"), something a flat `"{n} min ago"`
+ * template can't express.
+ *
+ * @see ../auth/texts.ts — `AIHubLanguage`
+ */
+
+import type { AIHubLanguage } from "../auth/texts.js";
+
+/**
+ * Formats an ISO-8601 timestamp as a short relative string in `language`,
+ * e.g. `"now"` / `"5 minutes ago"` / `"yesterday"` / `"3 days ago"` (and the
+ * Czech / Slovak equivalents).
+ *
+ * @param iso - ISO timestamp. Returns `""` for an unparseable value.
+ * @param language - the active UI language.
+ * @param opts.absoluteAfterDays - when set and the timestamp is at least this
+ *   many days old, returns a short absolute date instead (used by the admin
+ *   sessions overview, which falls back to a date after a week).
+ * @returns the localized relative-time string.
+ */
+export function formatRelativeTime(
+  iso: string,
+  language: AIHubLanguage,
+  opts: { absoluteAfterDays?: number } = {},
+): string {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return "";
+  const diffMs = Date.now() - then;
+  const rtf = new Intl.RelativeTimeFormat(language, { numeric: "auto" });
+  const minutes = Math.round(diffMs / 60_000);
+  if (minutes < 1) return rtf.format(0, "second"); // locale "now"
+  if (minutes < 60) return rtf.format(-minutes, "minute");
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return rtf.format(-hours, "hour");
+  const days = Math.round(hours / 24);
+  if (
+    opts.absoluteAfterDays !== undefined &&
+    days >= opts.absoluteAfterDays
+  ) {
+    return formatAbsoluteDate(iso, language);
+  }
+  return rtf.format(-days, "day");
+}
+
+/**
+ * Formats an ISO timestamp as a short, locale-formatted absolute date
+ * (e.g. `2026-06-08` → `08/06/2026` in en-GB style, `8. 6. 2026` in cs).
+ *
+ * @param iso - ISO timestamp. Returns the raw input for an unparseable value.
+ * @param language - the active UI language.
+ * @returns the localized date string.
+ */
+export function formatAbsoluteDate(
+  iso: string,
+  language: AIHubLanguage,
+): string {
+  const ts = Date.parse(iso);
+  if (Number.isNaN(ts)) return iso;
+  return new Intl.DateTimeFormat(language, { dateStyle: "short" }).format(
+    new Date(ts),
+  );
+}
+
+/**
+ * Day-granular relative label — `"today"` / `"yesterday"` / `"N days ago"`
+ * (localized). Used for the admin settings rotation stamp, which pairs an
+ * absolute date with this parenthetical.
+ *
+ * @param iso - ISO timestamp.
+ * @param language - the active UI language.
+ * @returns the localized day-relative label, or `""` when unparseable.
+ */
+export function formatRelativeDay(
+  iso: string,
+  language: AIHubLanguage,
+): string {
+  const ts = Date.parse(iso);
+  if (Number.isNaN(ts)) return "";
+  const diffDays = Math.floor((Date.now() - ts) / (24 * 60 * 60 * 1000));
+  const rtf = new Intl.RelativeTimeFormat(language, { numeric: "auto" });
+  return rtf.format(-Math.max(0, diffDays), "day");
+}