mirror of
https://github.com/outline/outline.git
synced 2026-11-21 05:24:03 +03:00
* feat: Add server-driven rows to useTableRequest and date range helpers - useTableRequest: `data` is now optional, when omitted the hook displays the rows returned by the server for the current params. Needed when server-side filtering cannot be reproduced against a client store. - Add `dateToTimestamp` and `dateRangeToReadable` localized date formatters. - Calendar: style the days between the start and end of a range. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Delete app/hooks/useTableRequest.test.tsx --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
604 lines
16 KiB
TypeScript
604 lines
16 KiB
TypeScript
import type { Locale } from "date-fns";
|
||
import {
|
||
addSeconds,
|
||
format,
|
||
formatDistanceToNow,
|
||
isSameYear,
|
||
isToday,
|
||
isTomorrow,
|
||
isYesterday,
|
||
parseISO,
|
||
subDays,
|
||
subMonths,
|
||
subWeeks,
|
||
subYears,
|
||
isValid,
|
||
parse,
|
||
} from "date-fns";
|
||
// Locales are imported from their individual modules rather than the
|
||
// "date-fns/locale" index, which would load every locale date-fns ships
|
||
// (~90) into memory rather than only those supported by the app.
|
||
import { ca } from "date-fns/locale/ca";
|
||
import { cs } from "date-fns/locale/cs";
|
||
import { da } from "date-fns/locale/da";
|
||
import { de } from "date-fns/locale/de";
|
||
import { enGB } from "date-fns/locale/en-GB";
|
||
import { enUS } from "date-fns/locale/en-US";
|
||
import { es } from "date-fns/locale/es";
|
||
import { faIR } from "date-fns/locale/fa-IR";
|
||
import { fr } from "date-fns/locale/fr";
|
||
import { he } from "date-fns/locale/he";
|
||
import { hu } from "date-fns/locale/hu";
|
||
import { id } from "date-fns/locale/id";
|
||
import { it } from "date-fns/locale/it";
|
||
import { ja } from "date-fns/locale/ja";
|
||
import { ko } from "date-fns/locale/ko";
|
||
import { nb } from "date-fns/locale/nb";
|
||
import { nl } from "date-fns/locale/nl";
|
||
import { ptBR } from "date-fns/locale/pt-BR";
|
||
import { pt } from "date-fns/locale/pt";
|
||
import { pl } from "date-fns/locale/pl";
|
||
import { sv } from "date-fns/locale/sv";
|
||
import { tr } from "date-fns/locale/tr";
|
||
import { vi } from "date-fns/locale/vi";
|
||
import { uk } from "date-fns/locale/uk";
|
||
import { zhCN } from "date-fns/locale/zh-CN";
|
||
import { zhTW } from "date-fns/locale/zh-TW";
|
||
import type { DateFilter } from "../types";
|
||
import { isBrowser } from "./browser";
|
||
|
||
/**
|
||
* Determines if the user's locale uses month-first date format (MM/dd).
|
||
*
|
||
* @returns true if locale uses MM/dd format, false for dd/MM format.
|
||
*/
|
||
export function usesMonthFirstFormat(): boolean {
|
||
if (!isBrowser || typeof Intl === "undefined") {
|
||
return false;
|
||
}
|
||
|
||
// Format a known date and check if month comes before day
|
||
const formatted = new Intl.DateTimeFormat(undefined, {
|
||
month: "2-digit",
|
||
day: "2-digit",
|
||
}).format(new Date(2000, 11, 25)); // Dec 25, 2000
|
||
|
||
// If it starts with "12", month comes first
|
||
return formatted.startsWith("12");
|
||
}
|
||
|
||
/**
|
||
* Attempts to parse a date string in various common formats.
|
||
*
|
||
* @param dateStr The date string to parse.
|
||
* @returns a Date object if parsing is successful, null otherwise.
|
||
*/
|
||
export function parseDate(dateStr: string): Date | null {
|
||
if (!dateStr) {
|
||
return null;
|
||
}
|
||
|
||
// Remove any trailing alphabetic text (e.g., "Uhr", "at", "o'clock", etc.)
|
||
const cleaned = dateStr.trim().replace(/\s*[a-zA-Z]+\s*$/, "");
|
||
|
||
const monthFirst = [
|
||
"MM/dd/yyyy HH:mm:ss",
|
||
"MM/dd/yyyy HH:mm",
|
||
"MM/dd/yyyy",
|
||
"MM/dd HH:mm:ss",
|
||
"MM/dd HH:mm",
|
||
"MM/dd",
|
||
];
|
||
|
||
const dayFirst = [
|
||
"dd/MM/yyyy HH:mm:ss",
|
||
"dd/MM/yyyy HH:mm",
|
||
"dd/MM/yyyy",
|
||
"dd/MM HH:mm:ss",
|
||
"dd/MM HH:mm",
|
||
"dd/MM",
|
||
];
|
||
|
||
// Ambiguous slash formats - order based on user's locale
|
||
const slashFormats = usesMonthFirstFormat()
|
||
? [...monthFirst, ...dayFirst]
|
||
: [...dayFirst, ...monthFirst];
|
||
|
||
// Common date formats used in tables (with and without time, with and without year)
|
||
const formats = [
|
||
// ISO formats
|
||
"yyyy-MM-dd HH:mm:ss",
|
||
"yyyy-MM-dd HH:mm",
|
||
"yyyy-MM-dd",
|
||
// European dot formats
|
||
"dd.MM.yyyy HH:mm:ss",
|
||
"dd.MM.yyyy HH:mm",
|
||
"dd.MM.yyyy",
|
||
"dd.MM. HH:mm:ss",
|
||
"dd.MM. HH:mm",
|
||
"dd.MM.",
|
||
"d.M.yyyy HH:mm:ss",
|
||
"d.M.yyyy HH:mm",
|
||
"d.M.yyyy",
|
||
"d.M. HH:mm:ss",
|
||
"d.M. HH:mm",
|
||
"d.M.",
|
||
// Locale-dependent slash formats
|
||
...slashFormats,
|
||
];
|
||
|
||
const referenceDate = new Date();
|
||
|
||
for (const format of formats) {
|
||
const date = parse(cleaned, format, referenceDate);
|
||
if (isValid(date)) {
|
||
return date;
|
||
}
|
||
}
|
||
|
||
return null;
|
||
}
|
||
|
||
const ISO8601_DURATION_RE =
|
||
/^-?P(?:(\d+W)|((?:\d+Y)?(?:\d+M)?(?:\d+D)?)(T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?)$/;
|
||
|
||
/**
|
||
* Validate a string against the ISO 8601 duration format.
|
||
*
|
||
* Supported subset: an optional leading `-`, then `P[nY][nM][nW][nD][T[nH][nM][nS]]`.
|
||
* The weeks form (`PnW`) is mutually exclusive with year/month/day units.
|
||
* Decimals are not supported.
|
||
*
|
||
* @param value the candidate string.
|
||
* @returns true if the string is a syntactically valid ISO 8601 duration.
|
||
*/
|
||
export function isISO8601Duration(value: string): boolean {
|
||
const m = ISO8601_DURATION_RE.exec(value);
|
||
if (!m) {
|
||
return false;
|
||
}
|
||
const [, weeks, date, time] = m;
|
||
if (weeks) {
|
||
return true;
|
||
}
|
||
// A bare `T` separator with no following time unit is invalid even if a date
|
||
// portion is present (e.g. `P1DT` should be rejected).
|
||
if (time === "T") {
|
||
return false;
|
||
}
|
||
const hasDate = !!date && date.length > 0;
|
||
const hasTime = !!time && time.length > 1;
|
||
return hasDate || hasTime;
|
||
}
|
||
|
||
export function subtractDate(date: Date, period: DateFilter) {
|
||
switch (period) {
|
||
case "day":
|
||
return subDays(date, 1);
|
||
|
||
case "week":
|
||
return subWeeks(date, 1);
|
||
|
||
case "month":
|
||
return subMonths(date, 1);
|
||
|
||
case "year":
|
||
return subYears(date, 1);
|
||
|
||
default:
|
||
return date;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Returns a humanized relative time string for the given date.
|
||
*
|
||
* @param date The date to convert
|
||
* @param options The options to pass to date-fns
|
||
* @returns The relative time string
|
||
*/
|
||
export function dateToRelative(
|
||
date: Date | number,
|
||
options?: {
|
||
includeSeconds?: boolean;
|
||
addSuffix?: boolean;
|
||
locale?: Locale | undefined;
|
||
shorten?: boolean;
|
||
}
|
||
) {
|
||
const now = new Date();
|
||
const parsedDateTime = new Date(date);
|
||
|
||
// Protect against "in less than a minute" when users computer clock is off.
|
||
const normalizedDateTime =
|
||
parsedDateTime > now && parsedDateTime < addSeconds(now, 60)
|
||
? now
|
||
: parsedDateTime;
|
||
|
||
const output = formatDistanceToNow(normalizedDateTime, options);
|
||
|
||
// Some tweaks to make english language shorter.
|
||
if (options?.shorten) {
|
||
return output
|
||
.replace("about", "")
|
||
.replace("less than a minute ago", "just now")
|
||
.replace("minute", "min");
|
||
}
|
||
|
||
return output;
|
||
}
|
||
|
||
/**
|
||
* Converts a locale string from Unicode CLDR format to BCP47 format.
|
||
*
|
||
* @param locale The locale string to convert
|
||
* @returns The converted locale string
|
||
*/
|
||
export function unicodeCLDRtoBCP47(locale: string) {
|
||
return locale.replace("_", "-").replace("root", "und");
|
||
}
|
||
|
||
/**
|
||
* Converts a locale string from BCP47 format to Unicode CLDR format.
|
||
*
|
||
* @param locale The locale string to convert
|
||
* @returns The converted locale string
|
||
*/
|
||
export function unicodeBCP47toCLDR(locale: string) {
|
||
return locale.replace("-", "_").replace("und", "root");
|
||
}
|
||
|
||
/**
|
||
* Converts a locale string from Unicode CLDR format to ISO 639 format.
|
||
*
|
||
* @param locale The locale string to convert
|
||
* @returns The converted locale string
|
||
*/
|
||
export function unicodeCLDRtoISO639(locale: string) {
|
||
return locale.split("_")[0];
|
||
}
|
||
|
||
/**
|
||
* Returns the current date as a string formatted depending on current locale.
|
||
*
|
||
* @returns The current date
|
||
*/
|
||
export function getCurrentDateAsString(locale?: Intl.LocalesArgument) {
|
||
return new Date().toLocaleDateString(locale, {
|
||
year: "numeric",
|
||
month: "long",
|
||
day: "numeric",
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Returns the current time as a string formatted depending on current locale.
|
||
*
|
||
* @returns The current time
|
||
*/
|
||
export function getCurrentTimeAsString(locale?: Intl.LocalesArgument) {
|
||
return new Date().toLocaleTimeString(locale, {
|
||
hour: "numeric",
|
||
minute: "numeric",
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Returns the current date and time as a string formatted depending on current
|
||
* locale.
|
||
*
|
||
* @returns The current date and time
|
||
*/
|
||
export function getCurrentDateTimeAsString(locale?: Intl.LocalesArgument) {
|
||
return new Date().toLocaleString(locale, {
|
||
year: "numeric",
|
||
month: "long",
|
||
day: "numeric",
|
||
hour: "numeric",
|
||
minute: "numeric",
|
||
});
|
||
}
|
||
|
||
const locales = {
|
||
ca_ES: ca,
|
||
cs_CZ: cs,
|
||
da_DK: da,
|
||
de_DE: de,
|
||
en_GB: enGB,
|
||
en_US: enUS,
|
||
es_ES: es,
|
||
fa_IR: faIR,
|
||
fr_FR: fr,
|
||
he_IL: he,
|
||
hu_HU: hu,
|
||
id_ID: id,
|
||
it_IT: it,
|
||
ja_JP: ja,
|
||
ko_KR: ko,
|
||
nb_NO: nb,
|
||
nl_NL: nl,
|
||
pt_BR: ptBR,
|
||
pt_PT: pt,
|
||
pl_PL: pl,
|
||
sv_SE: sv,
|
||
tr_TR: tr,
|
||
uk_UA: uk,
|
||
vi_VN: vi,
|
||
zh_CN: zhCN,
|
||
zh_TW: zhTW,
|
||
};
|
||
|
||
/**
|
||
* Returns the date-fns locale object for the given user language preference.
|
||
*
|
||
* @param language The user language
|
||
* @returns The date-fns locale.
|
||
*/
|
||
export function dateLocale(language: keyof typeof locales | undefined | null) {
|
||
return language ? locales[language] : undefined;
|
||
}
|
||
|
||
export { locales };
|
||
|
||
/**
|
||
* Formats a Date into a date-only ISO string (yyyy-MM-dd) in the local
|
||
* timezone. Used as the stored value for date mentions.
|
||
*
|
||
* @param date The date to format.
|
||
* @returns the date-only ISO string.
|
||
*/
|
||
export function toISODate(date: Date): string {
|
||
return format(date, "yyyy-MM-dd");
|
||
}
|
||
|
||
/**
|
||
* Formats a Date into a date and time ISO string (yyyy-MM-dd'T'HH:mm) in the
|
||
* local timezone. Used as the stored value for time-specific date mentions.
|
||
*
|
||
* @param date The date to format.
|
||
* @returns the date and time ISO string.
|
||
*/
|
||
export function toISODateTime(date: Date): string {
|
||
return format(date, "yyyy-MM-dd'T'HH:mm");
|
||
}
|
||
|
||
const isoDateRegex = /^\d{4}-\d{2}-\d{2}$/;
|
||
const isoDateTimeRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
|
||
|
||
/**
|
||
* Whether a date mention's stored ISO value carries a time component.
|
||
*
|
||
* @param iso The stored ISO string.
|
||
* @returns true when the value is time-specific.
|
||
*/
|
||
export function hasTimeComponent(iso: string): boolean {
|
||
return isoDateTimeRegex.test(iso);
|
||
}
|
||
|
||
/**
|
||
* Parses a date mention's stored ISO string into a Date in the local timezone.
|
||
* Accepts both the date-only (yyyy-MM-dd) and time-specific
|
||
* (yyyy-MM-dd'T'HH:mm) forms, the former resolving to local midnight. Any other
|
||
* shape – including values carrying seconds or a timezone offset – is rejected
|
||
* so the local, minute-granular contract cannot be violated.
|
||
*
|
||
* @param iso The stored ISO string.
|
||
* @returns the parsed Date, or null when the string is not a valid value.
|
||
*/
|
||
export function parseISODate(iso: string): Date | null {
|
||
if (!isoDateRegex.test(iso) && !isoDateTimeRegex.test(iso)) {
|
||
return null;
|
||
}
|
||
const date = parseISO(iso);
|
||
return isValid(date) ? date : null;
|
||
}
|
||
|
||
/**
|
||
* Converts a user language preference such as "en_US" into the BCP 47 tag
|
||
* understood by the platform's Intl formatters. Without a language the label
|
||
* falls back to English, matching the translation fallback.
|
||
*/
|
||
function languageTag(language?: keyof typeof locales | null): string {
|
||
return language ? unicodeCLDRtoBCP47(language) : "en-US";
|
||
}
|
||
|
||
const dateOptions: Intl.DateTimeFormatOptions = {
|
||
month: "long",
|
||
day: "numeric",
|
||
};
|
||
const yearOptions: Intl.DateTimeFormatOptions = {
|
||
...dateOptions,
|
||
year: "numeric",
|
||
};
|
||
const timeOptions: Intl.DateTimeFormatOptions = {
|
||
hour: "numeric",
|
||
minute: "2-digit",
|
||
};
|
||
|
||
const formatters = new Map<string, Intl.DateTimeFormat>();
|
||
|
||
/**
|
||
* Returns a cached Intl formatter for the language and options, as constructing
|
||
* one is comparatively expensive and mentions are formatted frequently.
|
||
*/
|
||
function dateFormatter(
|
||
tag: string,
|
||
options: Intl.DateTimeFormatOptions
|
||
): Intl.DateTimeFormat {
|
||
const key = `${tag}:${Object.keys(options).sort().join(",")}`;
|
||
let formatter = formatters.get(key);
|
||
if (!formatter) {
|
||
formatter = new Intl.DateTimeFormat(tag, options);
|
||
formatters.set(key, formatter);
|
||
}
|
||
return formatter;
|
||
}
|
||
|
||
const separators = new Map<string, string>();
|
||
|
||
/**
|
||
* Returns the separator a locale places between the date and time halves of a
|
||
* formatted datetime, e.g. " at " in English or " um " in German. It is read
|
||
* from the platform's own formatter so the label needs no translation.
|
||
*/
|
||
function dateTimeSeparator(tag: string): string {
|
||
let separator = separators.get(tag);
|
||
if (separator !== undefined) {
|
||
return separator;
|
||
}
|
||
|
||
separator = " ";
|
||
|
||
const sample = new Date(2000, 11, 25, 13, 0);
|
||
const parts = dateFormatter(tag, {
|
||
...yearOptions,
|
||
...timeOptions,
|
||
}).formatToParts(sample);
|
||
|
||
const timeIndex = parts.findIndex((part) =>
|
||
["hour", "minute", "dayPeriod"].includes(part.type)
|
||
);
|
||
const preceding = parts[timeIndex - 1];
|
||
if (preceding?.type === "literal") {
|
||
// The literal can begin with a suffix belonging to the date itself (the
|
||
// "日" in Japanese, the " р." in Ukrainian). It shows up as the trailing
|
||
// literal of the date-only format, so it can be stripped off.
|
||
const dateParts = dateFormatter(tag, yearOptions).formatToParts(sample);
|
||
const dateSuffix = dateParts[dateParts.length - 1];
|
||
|
||
let value = preceding.value;
|
||
if (dateSuffix?.type === "literal" && value.startsWith(dateSuffix.value)) {
|
||
value = value.slice(dateSuffix.value.length);
|
||
}
|
||
const whitespace = value.search(/\s/);
|
||
separator = whitespace === -1 ? " " : value.slice(whitespace);
|
||
}
|
||
|
||
separators.set(tag, separator);
|
||
return separator;
|
||
}
|
||
|
||
/**
|
||
* Formats a date mention's stored ISO value into an absolute, localized,
|
||
* human-readable label. The year is omitted within the current year (e.g.
|
||
* "January 2") and included otherwise (e.g. "February 3, 2024"). The time is
|
||
* appended when the value is time-specific (e.g. "January 2 at 1:00 PM"). The
|
||
* word order, numerals and connector all follow the locale. Suitable for
|
||
* plaintext and markdown serialization.
|
||
*
|
||
* @param iso The stored ISO string.
|
||
* @param language The user's language preference.
|
||
* @returns the absolute human-readable date, or the original string when invalid.
|
||
*/
|
||
export function dateToReadable(
|
||
iso: string,
|
||
language?: keyof typeof locales | null
|
||
): string {
|
||
const date = parseISODate(iso);
|
||
if (!date) {
|
||
return iso;
|
||
}
|
||
|
||
const tag = languageTag(language);
|
||
const options = isSameYear(date, new Date()) ? dateOptions : yearOptions;
|
||
|
||
if (!hasTimeComponent(iso)) {
|
||
return dateFormatter(tag, options).format(date);
|
||
}
|
||
return dateFormatter(tag, { ...options, ...timeOptions }).format(date);
|
||
}
|
||
|
||
/**
|
||
* Formats an ISO value into an exact, localized timestamp that always includes
|
||
* the year, seconds and time zone (e.g. "Nov 5, 2026, 7:48:12 PM EST"), for
|
||
* contexts such as audit trails where the moment must be unambiguous. The word
|
||
* order, numerals and hour cycle follow the language, the time zone is local.
|
||
*
|
||
* @param iso The ISO string.
|
||
* @param language The user's language preference.
|
||
* @returns the localized timestamp, or the original string when invalid.
|
||
*/
|
||
export function dateToTimestamp(
|
||
iso: string,
|
||
language?: keyof typeof locales | null
|
||
): string {
|
||
const date = new Date(iso);
|
||
if (isNaN(date.getTime())) {
|
||
return iso;
|
||
}
|
||
|
||
return dateFormatter(languageTag(language), {
|
||
dateStyle: "medium",
|
||
timeStyle: "long",
|
||
}).format(date);
|
||
}
|
||
|
||
/**
|
||
* Formats a range of days into a localized label, collapsing the parts that are
|
||
* shared between the two dates (e.g. "Nov 2 – 3, 2026"). A range that is only
|
||
* bounded on one side is labelled with its single date.
|
||
*
|
||
* @param start The first day of the range.
|
||
* @param end The last day of the range.
|
||
* @param language The user's language preference.
|
||
* @returns the localized label.
|
||
*/
|
||
export function dateRangeToReadable(
|
||
start: Date | null,
|
||
end: Date | null,
|
||
language?: keyof typeof locales | null
|
||
): string {
|
||
const formatter = dateFormatter(languageTag(language), {
|
||
dateStyle: "medium",
|
||
});
|
||
|
||
if (start && end) {
|
||
return formatter.formatRange(start, end);
|
||
}
|
||
|
||
const date = start ?? end;
|
||
return date ? formatter.format(date) : "";
|
||
}
|
||
|
||
/**
|
||
* Formats a date mention's stored ISO value into a relative, localized,
|
||
* human-readable label with increasing granularity. Returns "Today",
|
||
* "Tomorrow" or "Yesterday" where applicable, and otherwise the same absolute
|
||
* label as `dateToReadable`. The time is appended when the value is
|
||
* time-specific (e.g. "Tomorrow at 1:00 PM").
|
||
*
|
||
* @param iso The stored ISO string.
|
||
* @param t The translation function.
|
||
* @param language The user's language preference.
|
||
* @returns the relative human-readable date, or the original string when invalid.
|
||
*/
|
||
export function dateToRelativeReadable(
|
||
iso: string,
|
||
t: (key: string) => string,
|
||
language?: keyof typeof locales | null
|
||
): string {
|
||
const date = parseISODate(iso);
|
||
if (!date) {
|
||
return iso;
|
||
}
|
||
|
||
let relative;
|
||
if (isToday(date)) {
|
||
relative = t("Today");
|
||
} else if (isTomorrow(date)) {
|
||
relative = t("Tomorrow");
|
||
} else if (isYesterday(date)) {
|
||
relative = t("Yesterday");
|
||
} else {
|
||
return dateToReadable(iso, language);
|
||
}
|
||
|
||
if (!hasTimeComponent(iso)) {
|
||
return relative;
|
||
}
|
||
|
||
const tag = languageTag(language);
|
||
const time = dateFormatter(tag, timeOptions).format(date);
|
||
return `${relative}${dateTimeSeparator(tag)}${time}`;
|
||
}
|