@softr/sdk 0.0.58 → 0.0.59

package/dist/auth/context.d.ts

@@ -1,4 +1,5 @@
 import { User } from "./user.js";
+import { Formatting } from "../formatting.js";
 import { Permissions } from "./permissions.js";
 
 //#region src/auth/context.d.ts
@@ -10,9 +11,12 @@ type Session = {
   permissions: Permissions;
 };
 /**
- * The route context the root route publishes — see `getSoftrContext`. The same
- * session, under the name it carries in the public API.
+ * The route context the root route publishes — see `getSoftrContext`. The
+ * session, and how this request formats dates and numbers.
  */
-type SoftrContext = Session;
+type SoftrContext = Session & {
+  /** Read it with `useFormatting()`. */
+  formatting: Formatting;
+};
 //#endregion
-export { Session, SoftrContext };
+export { SoftrContext };

package/dist/auth/isomorphic.d.ts

@@ -1,16 +1,18 @@
 import { User } from "./user.js";
+import { Formatting } from "../formatting.js";
 import { Permissions } from "./permissions.js";
-import { Session, SoftrContext } from "./context.js";
+import { SoftrContext } from "./context.js";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 
 //#region src/auth/isomorphic.d.ts
 
 /**
- * Resolves the Softr visitor and their permissions for every request, so that
- * `getSoftrContext` and the route guards have something to read.
+ * Resolves the Softr visitor, their permissions and the app's formatting for
+ * every request, so that `getSoftrContext` and the route guards have something
+ * to read.
  *
  * Register it once, as a global request middleware in the app's `src/start.ts`.
- * It touches nothing but the session.
+ * It writes nothing but the session cookie.
  *
  * @example
  * export const startInstance = createStart(() => ({
@@ -20,6 +22,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
 declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
+  formatting: Formatting;
 }>;
 /**
  * Resolves the route context of the root route: the visitor and what they may
@@ -30,7 +33,7 @@ declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddleware
  *   beforeLoad: async () => await getSoftrContext(),
  * })
  */
-declare const getSoftrContext: _tanstack_react_start0.OptionalFetcher<undefined, undefined, Promise<Session>>;
+declare const getSoftrContext: _tanstack_react_start0.OptionalFetcher<undefined, undefined, Promise<SoftrContext>>;
 /**
  * The context to hand `createRouter`, before any request has resolved one.
  *

package/dist/auth/isomorphic.js

@@ -1,20 +1,23 @@
 import { assert, panic } from "../assertions.js";
-import { writeCookies } from "../cookies.js";
+import { readUserTimezone, writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
 import { makePlatform } from "./platform.js";
+import { defaultFormatting, readLocaleSettings, resolveFormatting } from "../formatting.js";
 import { bootErrorMiddleware } from "../boot-error.js";
 import { pwaMiddleware } from "../pwa.js";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
+import { getRequestHeader } from "@tanstack/react-start/server";
 import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 
 //#region src/auth/isomorphic.ts
 /**
-* Resolves the Softr visitor and their permissions for every request, so that
-* `getSoftrContext` and the route guards have something to read.
+* Resolves the Softr visitor, their permissions and the app's formatting for
+* every request, so that `getSoftrContext` and the route guards have something
+* to read.
 *
 * Register it once, as a global request middleware in the app's `src/start.ts`.
-* It touches nothing but the session.
+* It writes nothing but the session cookie.
 *
 * @example
 * export const startInstance = createStart(() => ({
@@ -37,10 +40,11 @@ function softrAuthMiddleware() {
 			writeCookies([makeSessionDataCookie(session, token)]);
 			return session;
 		}
-		const { user, permissions } = await getSession();
+		const [{ user, permissions }, settings] = await Promise.all([getSession(), readLocaleSettings()]);
 		return next({ context: {
 			user,
-			permissions
+			permissions,
+			formatting: resolveFormatting(settings, getRequestHeader("accept-language") ?? null, readUserTimezone())
 		} });
 	});
 }
@@ -55,7 +59,7 @@ function softrAuthMiddleware() {
 */
 const getSoftrContext = createServerFn({ method: "GET" }).handler(async () => {
 	const context = getGlobalStartContext();
-	assert(typeof context === "object" && context !== null && "user" in context && "permissions" in context, "softrAuthMiddleware has not run: the Start global context carries no session. Register it as a global request middleware, e.g. createStart(() => ({ requestMiddleware: [softrAuthMiddleware()] })).");
+	assert(typeof context === "object" && context !== null && "user" in context && "permissions" in context && "formatting" in context, "softrAuthMiddleware has not run: the Start global context carries no session. Register it as a global request middleware, e.g. createStart(() => ({ requestMiddleware: [softrAuthMiddleware()] })).");
 	return context;
 });
 /**
@@ -70,7 +74,8 @@ const getSoftrContext = createServerFn({ method: "GET" }).handler(async () => {
 function initialSoftrContext() {
 	return {
 		user: null,
-		permissions: { datasources: {} }
+		permissions: { datasources: {} },
+		formatting: defaultFormatting()
 	};
 }
 /**

package/dist/datasource/chart.d.ts

@@ -122,7 +122,7 @@ type ChartSeed<TShape extends ReadShape> = {
    * @example
    * ds.chart(sales).groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
    */
-  groupBy<TGroups extends Record<string, Dimension<unknown>>>(build: (q: DimensionSet<TShape>) => TGroups & GroupByBounds<TGroups>): ChartBuilder<TShape, TGroups, {}>;
+  groupBy<TGroups extends Record<string, Dimension<unknown>>>(build: (q: DimensionSet<TShape>) => TGroups & GroupByBounds<TGroups>): ChartBuilder<TShape, TGroups, Record<never, never>>;
   /**
    * Narrows which records the chart aggregates. Same filters as `ds.list`.
    */

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react1 from "react";
+import * as react5 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react1.JSX.Element;
+}: Props): react5.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/formatting.d.ts

@@ -0,0 +1,120 @@
+import * as react0 from "react";
+import { ReactNode } from "react";
+import { z } from "zod";
+
+//#region src/formatting.d.ts
+type FixedDateFormat = "FRIENDLY" | "DD-MM-YYYY" | "MM-DD-YYYY" | "YYYY-MM-DD";
+type DateSeparator = "-" | "/" | ".";
+/** ISO week day: 1 is Monday, 7 is Sunday. */
+type WeekDay = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** How this request formats dates and numbers. Read it with `useFormatting()`. */
+type Formatting = {
+  /** The locale for dates when the app uses the visitor's format. */
+  dateLocale: string;
+  /** The locale for numbers. */
+  numberLocale: string;
+  /**
+   * The IANA time zone for timestamps. `null` when the app uses the visitor's
+   * zone and the browser has not reported it yet, which is the first visit.
+   */
+  timeZone: string | null;
+  /** The app's fixed date format, or `null` to format in `dateLocale`. */
+  fixedDate: {
+    format: FixedDateFormat;
+    separator: DateSeparator;
+    hour12: boolean;
+  } | null;
+  /** The first day of the week, or `null` to use the locale's own. */
+  weekStart: WeekDay | null;
+  /** The app's language, for `<html lang>`. */
+  language: string;
+  /** Whether the app's language reads right to left, for `<html dir>`. */
+  rtl: boolean;
+};
+/** A date as a record field holds it: a `Date`, epoch milliseconds, or an ISO string. */
+type DateValue = Date | number | string;
+type DateOptions = {
+  /** How long the date reads when the app uses the visitor's format. A fixed format ignores it. */
+  dateStyle?: "short" | "medium" | "long" | "full";
+  /**
+   * The parts to show, such as `{ month: 'long', year: 'numeric' }` or `{ hour: 'numeric', minute:
+   * 'numeric', timeZoneName: 'short' }`. Wins over `dateStyle` and the app's fixed format.
+   */
+  parts?: DateParts;
+  /**
+   * The IANA zone for this value, such as `America/New_York`, when the builder names one. Wins over
+   * a `FormattingScope` and the app's settings. An unknown zone is ignored.
+   */
+  timeZone?: string;
+};
+type DateParts = Pick<Intl.DateTimeFormatOptions, "weekday" | "year" | "month" | "day" | "hour" | "minute" | "timeZoneName">;
+/**
+ * The day of a date, in the app's format. A timestamp reads in
+ * `formatting.timeZone`, or in UTC while that is unknown. Returns `""` for a
+ * value that is not a date.
+ */
+declare function formatDate(value: DateValue, formatting: Formatting, options?: DateOptions): string;
+/**
+ * The day and the time of a timestamp, in the app's format and zone. In JSX,
+ * prefer `<FormattedDate time />`: on a first visit it waits for the
+ * visitor's zone instead of showing UTC.
+ */
+declare function formatDateTime(value: DateValue, formatting: Formatting, options?: DateOptions): string;
+/** A number in the app's number locale. Returns `""` for a value that is not finite. */
+declare function formatNumber(value: number, formatting: Formatting, options?: Intl.NumberFormatOptions): string;
+/**
+ * The formatting of this request. On the server and during hydration it is
+ * the one the server resolved. After hydration, a zone the server did not know
+ * yet is filled in from the browser.
+ *
+ * Requires the root route to resolve `getSoftrContext`.
+ */
+declare function useFormatting(): Formatting;
+type Scope = {
+  timeZone?: string;
+  locale?: string;
+};
+/**
+ * Formats every date and number inside it in a zone or a locale the builder names, such as "show
+ * this page in New York time". A known zone renders on the server at once. An inner scope wins over
+ * an outer one. An unknown zone or locale is ignored, because it can come from a record.
+ *
+ * @example
+ * <FormattingScope timeZone="America/New_York">
+ *   <FormattedDate value={event.fields.starts} time />
+ * </FormattingScope>
+ */
+declare function FormattingScope({
+  timeZone,
+  locale,
+  children
+}: {
+  /** An IANA zone, such as `America/New_York`. */
+  timeZone?: string;
+  /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
+  locale?: string;
+  children?: ReactNode;
+}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
+/**
+ * A date in the app's format, safe to render on the server. A timestamp whose
+ * zone is not known yet renders `fallback` until the browser supplies it, so
+ * the visitor never sees a UTC time.
+ *
+ * @example
+ * <FormattedDate value={bug.fields.created} />
+ * <FormattedDate value={event.fields.starts} time />
+ */
+declare function FormattedDate({
+  value,
+  time,
+  fallback,
+  ...options
+}: DateOptions & {
+  value: DateValue;
+  /** Shows the time as well as the day. A calendar day such as `2026-10-06` has no time to show. */
+  time?: boolean;
+  /** What renders while the visitor's zone is unknown. */
+  fallback?: ReactNode;
+}): react0.FunctionComponentElement<react0.FragmentProps>;
+//#endregion
+export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/formatting.js

@@ -0,0 +1,379 @@
+import { logger } from "./logger.js";
+import { fetch } from "./fetch.js";
+import { readRequestCookies, serializeCookie, writeCookies } from "./cookies.js";
+import { sessionConfig } from "./auth/config.js";
+import { platformApiUrl } from "./auth/platform.js";
+import { Fragment, createContext, createElement, useContext, useMemo, useSyncExternalStore } from "react";
+import { getRequestProtocol } from "@tanstack/react-start/server";
+import { z } from "zod";
+import { rootRouteId, useRouteContext } from "@tanstack/react-router";
+
+//#region src/formatting.ts
+const DEFAULT_LOCALE = "en-US";
+/** The formatting before a request has resolved one. */
+function defaultFormatting() {
+	return {
+		dateLocale: DEFAULT_LOCALE,
+		numberLocale: DEFAULT_LOCALE,
+		timeZone: null,
+		fixedDate: null,
+		weekStart: null,
+		language: DEFAULT_LOCALE,
+		rtl: false
+	};
+}
+const localeSettingsSchema = z.object({
+	dateAndTimeSettings: z.object({
+		formatSettings: z.object({
+			type: z.enum(["LOCAL", "FIXED"]),
+			fixedSettings: z.object({
+				dateFormat: z.enum([
+					"FRIENDLY",
+					"DD-MM-YYYY",
+					"MM-DD-YYYY",
+					"YYYY-MM-DD"
+				]).nullish(),
+				dateFormatSeparator: z.enum([
+					"-",
+					"/",
+					"."
+				]).nullish(),
+				timeFormat: z.enum(["12", "24"]).nullish(),
+				weekStart: z.literal([
+					1,
+					2,
+					3,
+					4,
+					5,
+					6,
+					7
+				]).nullish()
+			}).nullish()
+		}),
+		timezoneSettings: z.object({
+			type: z.enum(["LOCAL", "FIXED"]),
+			fixedTimezone: z.string().nullish()
+		})
+	}),
+	numberFormattingSettings: z.object({
+		type: z.enum(["LOCAL", "FIXED"]),
+		fixedLocale: z.string().nullish()
+	}),
+	languageSettings: z.object({
+		language: z.string().nullish(),
+		rtl: z.boolean()
+	})
+});
+const LOCALE_SETTINGS = "locale_settings";
+const LOCALE_SETTINGS_TTL_SECONDS = 300;
+/**
+* The app's locale settings, or `null` when they cannot be read. Never
+* rejects: a failure formats with the visitor's locale and is not remembered,
+* so the next request tries again.
+*/
+async function readLocaleSettings() {
+	const cached = parseLocaleSettings(readRequestCookies()[LOCALE_SETTINGS]);
+	if (cached !== null) return cached;
+	try {
+		const settings = await fetchLocaleSettings();
+		writeCookies([serializeCookie(LOCALE_SETTINGS, JSON.stringify(settings), {
+			maxAge: LOCALE_SETTINGS_TTL_SECONDS,
+			secure: getRequestProtocol() === "https"
+		})]);
+		return settings;
+	} catch (error) {
+		logger.warn("Could not read the locale settings:", error);
+		return null;
+	}
+}
+/** The settings in `cookie`, or `null` for anything else. The cookie is visitor input. */
+function parseLocaleSettings(cookie) {
+	if (cookie === void 0) return null;
+	try {
+		return localeSettingsSchema.safeParse(JSON.parse(cookie)).data ?? null;
+	} catch {
+		return null;
+	}
+}
+async function fetchLocaleSettings() {
+	const { applicationId } = sessionConfig();
+	const response = await fetch(`${await platformApiUrl()}/v1/vibe/applications/${applicationId}/locale-settings`, { headers: { accept: "application/json" } });
+	if (!response.ok) throw new Error(`The platform answered ${response.status}`);
+	return localeSettingsSchema.parse(await response.json());
+}
+/**
+* Combines the app's settings with what the request says about the visitor.
+* A `FIXED` setting wins. A `LOCAL` one uses the request: `Accept-Language`
+* for the locale and the `user-timezone` cookie for the zone.
+*/
+function resolveFormatting(settings, acceptLanguage, timeZoneCookie) {
+	const language = supportedLocale(settings?.languageSettings.language) ?? DEFAULT_LOCALE;
+	const visitorLocale = firstSupportedLocale(acceptLanguage) ?? language;
+	const format = settings?.dateAndTimeSettings.formatSettings;
+	const fixed = format?.type === "FIXED" ? format.fixedSettings : null;
+	const zone = settings?.dateAndTimeSettings.timezoneSettings;
+	const fixedZone = zone?.type === "FIXED" ? validTimeZone(zone.fixedTimezone) : null;
+	const numbers = settings?.numberFormattingSettings;
+	return {
+		dateLocale: visitorLocale,
+		numberLocale: (numbers?.type === "FIXED" ? supportedLocale(numbers.fixedLocale) : null) ?? visitorLocale,
+		timeZone: fixedZone ?? validTimeZone(timeZoneCookie),
+		fixedDate: fixed?.dateFormat ? {
+			format: fixed.dateFormat,
+			separator: fixed.dateFormatSeparator ?? "-",
+			hour12: fixed.timeFormat === "12"
+		} : null,
+		weekStart: fixed?.dateFormat ? fixed.weekStart ?? 1 : null,
+		language,
+		rtl: settings?.languageSettings.rtl ?? false
+	};
+}
+/**
+* The day of a date, in the app's format. A timestamp reads in
+* `formatting.timeZone`, or in UTC while that is unknown. Returns `""` for a
+* value that is not a date.
+*/
+function formatDate(value, formatting, options = {}) {
+	return formatDateValue(value, formatting, false, options);
+}
+/**
+* The day and the time of a timestamp, in the app's format and zone. In JSX,
+* prefer `<FormattedDate time />`: on a first visit it waits for the
+* visitor's zone instead of showing UTC.
+*/
+function formatDateTime(value, formatting, options = {}) {
+	return formatDateValue(value, formatting, true, options);
+}
+/** A number in the app's number locale. Returns `""` for a value that is not finite. */
+function formatNumber(value, formatting, options) {
+	if (!Number.isFinite(value)) return "";
+	return new Intl.NumberFormat(formatting.numberLocale, options).format(value);
+}
+/**
+* The formatting of this request. On the server and during hydration it is
+* the one the server resolved. After hydration, a zone the server did not know
+* yet is filled in from the browser.
+*
+* Requires the root route to resolve `getSoftrContext`.
+*/
+function useFormatting() {
+	const resolved = useRouteContext({
+		from: rootRouteId,
+		select: (context) => context.formatting
+	});
+	const scope = useContext(ScopeContext);
+	const hydrated = useSyncExternalStore(subscribeNever, () => true, () => false);
+	return useMemo(() => {
+		const scoped = {
+			...resolved,
+			...scope.timeZone ? { timeZone: scope.timeZone } : {},
+			...scope.locale ? {
+				dateLocale: scope.locale,
+				numberLocale: scope.locale,
+				fixedDate: null
+			} : {}
+		};
+		return scoped.timeZone === null && hydrated ? {
+			...scoped,
+			timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone
+		} : scoped;
+	}, [
+		resolved,
+		scope,
+		hydrated
+	]);
+}
+const ScopeContext = createContext({});
+/**
+* Formats every date and number inside it in a zone or a locale the builder names, such as "show
+* this page in New York time". A known zone renders on the server at once. An inner scope wins over
+* an outer one. An unknown zone or locale is ignored, because it can come from a record.
+*
+* @example
+* <FormattingScope timeZone="America/New_York">
+*   <FormattedDate value={event.fields.starts} time />
+* </FormattingScope>
+*/
+function FormattingScope({ timeZone, locale, children }) {
+	const parent = useContext(ScopeContext);
+	const value = useMemo(() => {
+		const zone = checkedTimeZone(timeZone);
+		const tag = locale === void 0 ? null : supportedLocale(locale);
+		if (locale !== void 0 && tag === null) logger.warn(`FormattingScope ignores the unknown locale "${locale}".`);
+		return {
+			timeZone: zone ?? parent.timeZone,
+			locale: tag ?? parent.locale
+		};
+	}, [
+		parent,
+		timeZone,
+		locale
+	]);
+	return createElement(ScopeContext.Provider, { value }, children);
+}
+/**
+* A date in the app's format, safe to render on the server. A timestamp whose
+* zone is not known yet renders `fallback` until the browser supplies it, so
+* the visitor never sees a UTC time.
+*
+* @example
+* <FormattedDate value={bug.fields.created} />
+* <FormattedDate value={event.fields.starts} time />
+*/
+function FormattedDate({ value, time = false, fallback = null,...options }) {
+	const formatting = useFormatting();
+	if (!isCalendarDay(value) && zoneFor(formatting, options) === null) return createElement(Fragment, null, fallback);
+	return createElement(Fragment, null, (time ? formatDateTime : formatDate)(value, formatting, options));
+}
+function subscribeNever() {
+	return () => {};
+}
+const CALENDAR_DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** A calendar day such as `2026-10-06` names the same day in every zone, so it needs none. */
+function isCalendarDay(value) {
+	return typeof value === "string" && CALENDAR_DAY.test(value);
+}
+function formatDateValue(value, formatting, withTime, options) {
+	const day = isCalendarDay(value);
+	const date = day ? /* @__PURE__ */ new Date(`${value}T00:00:00Z`) : new Date(value);
+	if (Number.isNaN(date.getTime())) return "";
+	const timeZone = day ? "UTC" : zoneFor(formatting, options) ?? "UTC";
+	const showTime = withTime && !day;
+	if (options.parts) return new Intl.DateTimeFormat(formatting.dateLocale, {
+		...options.parts,
+		...formatting.fixedDate !== null ? { hour12: formatting.fixedDate.hour12 } : {},
+		timeZone
+	}).format(date);
+	if (formatting.fixedDate !== null) return formatFixed(date, timeZone, showTime, formatting.fixedDate);
+	if (options.dateStyle) return new Intl.DateTimeFormat(formatting.dateLocale, {
+		dateStyle: options.dateStyle,
+		...showTime ? { timeStyle: "short" } : {},
+		timeZone
+	}).format(date);
+	return new Intl.DateTimeFormat(formatting.dateLocale, {
+		year: "numeric",
+		month: "numeric",
+		day: "numeric",
+		...showTime ? {
+			hour: "numeric",
+			minute: "numeric"
+		} : {},
+		timeZone
+	}).format(date);
+}
+const MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec"
+];
+function formatFixed(date, timeZone, showTime, fixed) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "numeric",
+		day: "numeric",
+		hour: "numeric",
+		minute: "numeric",
+		hourCycle: "h23"
+	}).formatToParts(date);
+	const part = (type) => Number(parts.find((p) => p.type === type)?.value ?? NaN);
+	const [year, month, day, hour, minute] = [
+		part("year"),
+		part("month"),
+		part("day"),
+		part("hour"),
+		part("minute")
+	];
+	const sep = fixed.separator;
+	const text = {
+		FRIENDLY: `${MONTHS[month - 1]} ${ordinal(day)}, ${year}`,
+		"DD-MM-YYYY": [
+			pad(day),
+			pad(month),
+			year
+		].join(sep),
+		"MM-DD-YYYY": [
+			pad(month),
+			pad(day),
+			year
+		].join(sep),
+		"YYYY-MM-DD": [
+			year,
+			pad(month),
+			pad(day)
+		].join(sep)
+	}[fixed.format];
+	if (!showTime) return text;
+	if (!fixed.hour12) return `${text} ${pad(hour)}:${pad(minute)}`;
+	return `${text} ${pad(hour % 12 === 0 ? 12 : hour % 12)}:${pad(minute)} ${hour < 12 ? "AM" : "PM"}`;
+}
+function pad(value) {
+	return String(value).padStart(2, "0");
+}
+function ordinal(day) {
+	if (day % 100 >= 11 && day % 100 <= 13) return `${day}th`;
+	return `${day}${[
+		"th",
+		"st",
+		"nd",
+		"rd"
+	][day % 10] ?? "th"}`;
+}
+/** The first locale in an `Accept-Language` header that `Intl` supports, by weight. */
+function firstSupportedLocale(header) {
+	if (!header) return null;
+	const ranked = header.split(",").map((entry, index) => {
+		const [tag = "", ...params] = entry.trim().split(";");
+		const q = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+		const weight = q === void 0 ? 1 : Number(q.slice(2));
+		return {
+			tag: tag.trim(),
+			weight: Number.isNaN(weight) ? 0 : weight,
+			index
+		};
+	}).filter((entry) => entry.tag !== "" && entry.tag !== "*" && entry.weight > 0).sort((a, b) => b.weight - a.weight || a.index - b.index);
+	for (const { tag } of ranked) {
+		const locale = supportedLocale(tag);
+		if (locale !== null) return locale;
+	}
+	return null;
+}
+function supportedLocale(tag) {
+	if (!tag) return null;
+	try {
+		return Intl.DateTimeFormat.supportedLocalesOf(tag)[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/** The zone a value reads in: the one the call names, else the formatting's, else `null` while unknown. */
+function zoneFor(formatting, options) {
+	return checkedTimeZone(options.timeZone) ?? formatting.timeZone;
+}
+/** `validTimeZone` for a zone the app's code names. It warns, so a typo shows in the logs. */
+function checkedTimeZone(zone) {
+	if (zone === void 0) return null;
+	const valid = validTimeZone(zone);
+	if (valid === null) logger.warn(`Ignoring the unknown time zone "${zone}".`);
+	return valid;
+}
+function validTimeZone(zone) {
+	if (!zone) return null;
+	try {
+		return new Intl.DateTimeFormat("en-US", { timeZone: zone }).resolvedOptions().timeZone;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { FormattedDate, FormattingScope, defaultFormatting, formatDate, formatDateTime, formatNumber, readLocaleSettings, resolveFormatting, useFormatting };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
 import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
@@ -11,4 +12,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -2,6 +2,7 @@ import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { FormattedDate, FormattingScope, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
@@ -9,4 +10,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+export { Audience, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.58";
+var version = "0.0.59";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react3 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
+declare function SoftrPwaHead(): react3.FunctionComponentElement<react3.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
   visibility, the current user, reading records, charts and metrics, writing
-  records, or auth. Load this when unsure which sub-skill applies, or when
+  records, auth, or showing dates and numbers. Load this when unsure which sub-skill applies, or when
   touching the wiring; each sub-skill stands alone for its own task.
 metadata:
   type: core
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -49,6 +49,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
+| Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -86,6 +87,9 @@ Opening the app to an AI assistant over MCP?
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 
+Showing a date, a time or a number on a page?
+  load softr-sdk/formatting
+
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```

package/skills/softr-sdk/formatting/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: formatting
+description: >-
+  Show dates, times and numbers in the app's format without hydration
+  mismatches: FormattedDate in JSX, useFormatting with formatDate,
+  formatDateTime and formatNumber in code, FormattingScope and the timeZone
+  option for a zone or locale the user names, parts for a partial date, and
+  why toLocaleDateString, toLocaleString and Intl formatters with the
+  runtime's defaults must never run in render.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.58
+---
+
+# Dates, times and numbers
+
+Softr stores every date and time as UTC. The builder chooses in Studio how the app shows dates, times and numbers: in each visitor's own format and zone (the default), or in one fixed format or zone for everyone. The SDK resolves that choice once per request. The server and the browser then format with the same values, so the page the server renders and the page the browser hydrates show the same text.
+
+> **CRITICAL**: Never call `toLocaleDateString`, `toLocaleTimeString`, `toLocaleString` or `new Intl.DateTimeFormat` / `new Intl.NumberFormat` in code that renders. The server and the browser have different locales and time zones, so the text differs and React throws a hydration mismatch. A hard-coded `'en-US'` or `timeZone: 'UTC'` hides the error but ignores the builder's settings and shows the wrong format and day to most visitors.
+> **CRITICAL**: Format with the helpers below and nothing else. They follow the app's settings, and they are the only formatters that give the same text on the server and in the browser.
+
+## Setup
+
+```ts
+import { FormattedDate, FormattingScope, useFormatting, formatDate, formatDateTime, formatNumber } from '@softr/sdk'
+import type { Formatting, DateValue, DateOptions } from '@softr/sdk'
+```
+
+```ts
+type DateValue = Date | number | string   // a record's date field works as is
+
+type Formatting = {
+  dateLocale: string
+  numberLocale: string
+  timeZone: string | null            // null until the visitor's zone is known
+  fixedDate: { format: 'FRIENDLY' | 'DD-MM-YYYY' | 'MM-DD-YYYY' | 'YYYY-MM-DD'; separator: '-' | '/' | '.'; hour12: boolean } | null
+  weekStart: 1 | 2 | 3 | 4 | 5 | 6 | 7 | null   // 1 is Monday; null means the locale's own
+  language: string
+  rtl: boolean
+}
+
+type DateOptions = {
+  dateStyle?: 'short' | 'medium' | 'long' | 'full'
+  parts?: { weekday?, year?, month?, day?, hour?, minute?, timeZoneName? }   // Intl.DateTimeFormat options
+  timeZone?: string   // IANA, such as 'America/New_York'
+}
+```
+
+## Core Patterns
+
+### A date in JSX: `<FormattedDate />`
+
+```tsx
+<FormattedDate value={bug.fields.created} />
+<FormattedDate value={event.fields.starts} time />
+<FormattedDate value={task.fields.due} dateStyle="medium" />
+```
+
+A timestamp (`DATETIME`, `CREATED_AT`, `UPDATED_AT`) is a UTC instant and needs a time zone. On a visitor's first page load their zone can be unknown, and then `FormattedDate` renders its `fallback` (nothing by default) until the browser supplies it. A calendar day (`DATE`, such as `2026-10-06`) names the same day everywhere and always renders at once. `dateStyle` applies only when the app uses the visitor's format; a fixed format ignores it.
+
+### Part of a date: `parts`
+
+A list already filtered to this year needs only the month. A schedule needs only the time. `parts` takes the `Intl.DateTimeFormat` fields and wins over `dateStyle` and the app's fixed format. The locale and the zone still come from the app.
+
+```tsx
+<FormattedDate value={post.fields.published} parts={{ month: 'long', year: 'numeric' }} />   // October 2026
+<FormattedDate value={shift.fields.starts} parts={{ weekday: 'long' }} />                    // Monday
+<FormattedDate value={shift.fields.starts} parts={{ hour: 'numeric', minute: 'numeric' }} /> // 14:30
+```
+
+### A zone or a locale the user names
+
+"Show this page in New York time" or "use German formatting here" is a fixed value. It wins over the visitor's and the app's settings. A date in a named zone renders on the server at once, with no fallback.
+
+For a page or an area, wrap it in `FormattingScope`. Every `FormattedDate` and `useFormatting()` inside reads the scope. An inner scope wins over an outer one.
+
+```tsx
+<FormattingScope timeZone="America/New_York">
+  <EventList events={events} />
+</FormattingScope>
+```
+
+For one value, pass `timeZone`. It wins over a scope. Use it for an event that shows in its own zone, from a record field or a DATETIME field whose `options` in the datasource schema name a `timezone` and a `timezoneType` other than `LOCAL`.
+
+```tsx
+<FormattedDate value={event.fields.starts} time timeZone={event.fields.zone} />
+```
+
+Say which zone a fixed-zone time is in, so a visitor elsewhere does not read it as theirs: add `timeZoneName: 'short'` to `parts`, or write the zone next to it. An unknown zone or locale is ignored with a warning, so a bad record never breaks the page.
+
+### Text outside JSX: `useFormatting()` and the format functions
+
+Use these for a string prop, an `aria-label`, a chart axis, or a sort key shown to the visitor.
+
+```tsx
+function BugRow({ bug }: { bug: Bug }) {
+  const formatting = useFormatting()
+  return (
+    <li title={`Created ${formatDateTime(bug.fields.created, formatting)}`}>
+      {bug.fields.title}
+      <span>{formatNumber(bug.fields.votes, formatting)}</span>
+    </li>
+  )
+}
+```
+
+`formatNumber` takes the `Intl.NumberFormat` options, for percentages and currencies:
+
+```ts
+formatNumber(0.25, formatting, { style: 'percent' })
+formatNumber(99, formatting, { style: 'currency', currency: 'EUR' })
+```
+
+The currency comes from the field or from the user, never from the locale. A German visitor looking at a price in dollars still sees dollars.
+
+`formatDate` and `formatDateTime` show a timestamp in UTC while `formatting.timeZone` is `null`. In JSX, prefer `<FormattedDate />`, which waits instead.
+
+### Outside render: a server function or `beforeLoad`
+
+Not every date ends up in a component. A CSV or spreadsheet export, a text the server sends, or a value a loader prepares are formatted before React runs. There, `context.formatting` holds the same `Formatting` that `useFormatting()` returns. See [current-user](../current-user/SKILL.md) for how `context` reaches a handler.
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { formatDateTime } from '@softr/sdk'
+
+const exportBugs = createServerFn().handler(async ({ context }) => {
+  const bugs = await getBugs()
+  return bugs.map((bug) => `${bug.fields.title},${formatDateTime(bug.fields.created, context.formatting)}`).join('\n')
+})
+```
+
+On a visitor's first page load, `context.formatting.timeZone` is `null`, so a timestamp reads in UTC. Only the browser can fill in the zone.
+
+### A range, or any other `Intl` format
+
+For a shape the helpers do not give, such as a range (`Oct 6 – 8`), use `Intl` with the values from `useFormatting()` and never the runtime's defaults. Render it only when the zone is known:
+
+```tsx
+const formatting = useFormatting()
+const range = formatting.timeZone === null
+  ? null
+  : new Intl.DateTimeFormat(formatting.dateLocale, { month: 'short', day: 'numeric', timeZone: formatting.timeZone })
+      .formatRange(new Date(trip.fields.starts), new Date(trip.fields.ends))
+```
+
+### Relative time and now
+
+"3 hours ago" and the current time depend on the moment of rendering, which differs between the server and the browser. Render them only after mount, with `Intl.RelativeTimeFormat` and `formatting.dateLocale`.
+
+### Writing a date back
+
+A write takes an ISO string, never a `Date`. A timestamp is written as a UTC instant (`toISOString()`), a day as `YYYY-MM-DD`. See [record-mutations](../record-mutations/SKILL.md).
+
+### A calendar's first day
+
+Pass `formatting.weekStart` to a date picker or calendar when it is not `null`. Most take Sunday as `0`: use `formatting.weekStart % 7`.
+
+## Common Mistakes
+
+### CRITICAL: Formatting with the runtime's locale in render
+
+Wrong:
+
+```tsx
+<span>{new Date(bug.fields.created).toLocaleDateString()}</span>
+```
+
+Correct:
+
+```tsx
+<FormattedDate value={bug.fields.created} />
+```
+
+The server renders `10/6/2026` and a browser in Europe renders `06/10/2026`. React rejects the page, and the builder's date settings are ignored on both sides.
+
+### HIGH: Forcing one locale or zone to silence the mismatch
+
+Wrong:
+
+```tsx
+new Intl.DateTimeFormat('en-US', { dateStyle: 'medium', timeZone: 'UTC' }).format(new Date(value))
+```
+
+Correct:
+
+```tsx
+<FormattedDate value={value} dateStyle="medium" />
+```
+
+The mismatch goes away, but every visitor sees US dates in UTC. A timestamp late in the evening shows the next day. When the user names a zone or a locale, pass it with `timeZone` or `FormattingScope`.
+
+### HIGH: Raw `Intl` while the zone is unknown
+
+Wrong:
+
+```tsx
+const formatting = useFormatting()
+new Intl.DateTimeFormat(formatting.dateLocale, { timeZone: formatting.timeZone ?? undefined }).format(new Date(value))
+```
+
+Correct:
+
+```tsx
+<FormattedDate value={value} />
+```
+
+On a first visit `formatting.timeZone` is `null`. `undefined` makes the server use its own zone and the browser use the visitor's, so the text differs and hydration fails. Use the helpers, or render nothing until the zone is known.
+
+## References
+
+- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on