@octane-xplat/ui 0.7.3 → 0.10.0

package/src/time-format.ts

@@ -0,0 +1,435 @@
+// Shared instant/relative formatting for Timestamp — ported from Astryx's
+// formatInstant.ts, formatRelativeTime.ts, and tooltipEntries.ts. Intl is a
+// universal-runtime API (platform-notes i18n row), so the module is identical
+// on web and native.
+import type { TimestampFormat, TimestampTooltipEntry, TimestampTooltipFormat } from './props'
+export type { TimestampTooltipEntry, TimestampTooltipFormat } from './props'
+
+/** A rendered tooltip line for the Timestamp hover card. */
+export interface TimestampTooltipLine {
+	label?: string
+	value: string
+	isCopyable: boolean
+}
+
+type Locale = string | string[] | undefined
+
+const FULL_OPTIONS: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'long',
+	day: 'numeric',
+	hour: 'numeric',
+	minute: '2-digit',
+	second: '2-digit',
+	timeZoneName: 'short',
+}
+
+const TIME_OPTIONS: Intl.DateTimeFormatOptions = {
+	hour: 'numeric',
+	minute: '2-digit',
+}
+
+const DATE_OPTIONS: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'short',
+	day: 'numeric',
+}
+
+const DATE_LONG_OPTIONS: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'long',
+	day: 'numeric',
+}
+
+const DATE_WEEKDAY_OPTIONS: Intl.DateTimeFormatOptions = {
+	weekday: 'short',
+	month: 'short',
+	day: 'numeric',
+	year: 'numeric',
+}
+
+// The date part here is spelled out rather than shared with a date-only
+// field preset: the two agree today but are not the same decision.
+const DATE_TIME_OPTIONS: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'short',
+	day: 'numeric',
+	...TIME_OPTIONS,
+}
+
+function pad(n: number): string {
+	return String(n).padStart(2, '0')
+}
+
+interface WallClock {
+	year: number
+	month: number
+	day: number
+	hour: number
+	minute: number
+	second: number
+}
+
+/** Wall-clock fields for an instant in a named zone via Intl parts. */
+function getTimeZoneParts(instant: number, timezoneID: string): WallClock {
+	const parts = new Intl.DateTimeFormat('en-US', {
+		timeZone: timezoneID,
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+		hourCycle: 'h23',
+		calendar: 'gregory',
+	}).formatToParts(new Date(instant))
+
+	const lookup = Object.fromEntries(
+		parts.filter((part) => part.type !== 'literal').map((part) => [part.type, Number(part.value)]),
+	)
+
+	return {
+		year: lookup.year,
+		month: lookup.month,
+		day: lookup.day,
+		hour: lookup.hour,
+		minute: lookup.minute,
+		second: lookup.second,
+	}
+}
+
+function getWallClock(date: Date, timeZone: string | undefined): WallClock {
+	return timeZone === undefined
+		? {
+				year: date.getFullYear(),
+				month: date.getMonth() + 1,
+				day: date.getDate(),
+				hour: date.getHours(),
+				minute: date.getMinutes(),
+				second: date.getSeconds(),
+			}
+		: getTimeZoneParts(date.getTime(), timeZone)
+}
+
+export interface FormatInstantOptions {
+	/** IANA zone id; omit for the viewer's own zone. */
+	timeZone?: string
+	/** Append the short zone abbreviation (`date_time`/`time`/`full` only). */
+	isTimezoneShown?: boolean
+	/** 'short' ("PST") or 'long' ("Pacific Standard Time") — `full` only. */
+	timeZoneNameStyle?: 'short' | 'long'
+}
+
+/** Render one instant in one absolute format. Pure in its arguments. */
+export function formatInstant(
+	date: Date,
+	format: TimestampTooltipFormat,
+	locale?: Locale,
+	{ timeZone, isTimezoneShown = false, timeZoneNameStyle = 'short' }: FormatInstantOptions = {},
+): string {
+	const zone = timeZone === undefined ? {} : { timeZone }
+	const zoneName = isTimezoneShown ? { timeZoneName: 'short' as const } : {}
+
+	switch (format) {
+		case 'full':
+			return new Intl.DateTimeFormat(locale, {
+				...FULL_OPTIONS,
+				timeZoneName: timeZoneNameStyle,
+				...zone,
+				calendar: 'gregory',
+			}).format(date)
+
+		case 'date':
+			return new Intl.DateTimeFormat(locale, {
+				...DATE_OPTIONS,
+				...zone,
+				calendar: 'gregory',
+			}).format(date)
+
+		case 'date_long':
+			return new Intl.DateTimeFormat(locale, {
+				...DATE_LONG_OPTIONS,
+				...zone,
+				calendar: 'gregory',
+			}).format(date)
+
+		case 'date_weekday':
+			return new Intl.DateTimeFormat(locale, {
+				...DATE_WEEKDAY_OPTIONS,
+				...zone,
+				calendar: 'gregory',
+			}).format(date)
+
+		case 'date_time':
+			return new Intl.DateTimeFormat(locale, {
+				...DATE_TIME_OPTIONS,
+				...zoneName,
+				...zone,
+				calendar: 'gregory',
+			}).format(date)
+
+		case 'time':
+			return new Intl.DateTimeFormat(locale, {
+				...TIME_OPTIONS,
+				...zoneName,
+				...zone,
+			}).format(date)
+
+		case 'system_date': {
+			const w = getWallClock(date, timeZone)
+			return `${w.year}-${pad(w.month)}-${pad(w.day)}`
+		}
+
+		case 'system_date_time': {
+			const w = getWallClock(date, timeZone)
+			return `${w.year}-${pad(w.month)}-${pad(w.day)} ${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`
+		}
+
+		case 'system_time': {
+			const w = getWallClock(date, timeZone)
+			return `${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`
+		}
+
+		case 'unix_seconds':
+			// Absolute — a wall-clock zone can't change elapsed seconds.
+			return String(Math.floor(date.getTime() / 1000))
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Relative time
+// ---------------------------------------------------------------------------
+
+const MINUTE = 60
+const HOUR = 3600
+const DAY = 86400
+const MONTH = 30 * DAY
+const YEAR = 365 * DAY
+
+/** Values this close to now are usually clock skew, not a future instant. */
+const FUTURE_SKEW_TOLERANCE = 30
+
+type RelativeTimeStyle = 'long' | 'narrow'
+type RelativeTimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year'
+
+const formatters = new Map<string, Intl.RelativeTimeFormat>()
+
+function getFormatter(
+	locale: Locale,
+	style: RelativeTimeStyle,
+	numeric: Intl.RelativeTimeFormatNumeric,
+): Intl.RelativeTimeFormat {
+	const key = JSON.stringify([locale, style, numeric])
+	let formatter = formatters.get(key)
+	if (formatter == null) {
+		formatter = new Intl.RelativeTimeFormat(locale, { numeric, style })
+		formatters.set(key, formatter)
+	}
+
+	return formatter
+}
+
+/**
+ * Locale-correct relative time: the fixed tier selection is ours, wording,
+ * plural rules, and word order belong to the CLDR-backed formatter.
+ */
+export function formatRelativeTime(
+	date: Date,
+	now: Date,
+	locale?: Locale,
+	style: RelativeTimeStyle = 'long',
+): string {
+	const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000)
+	const absDiff = Math.abs(diffSeconds)
+
+	if (absDiff < 10 || (diffSeconds < 0 && absDiff <= FUTURE_SKEW_TOLERANCE)) {
+		return getFormatter(locale, style, 'auto').format(0, 'second')
+	}
+
+	let count: number
+	let unit: RelativeTimeUnit
+	if (absDiff < MINUTE) {
+		count = absDiff
+		unit = 'second'
+	} else if (absDiff < HOUR) {
+		count = Math.floor(absDiff / MINUTE)
+		unit = 'minute'
+	} else if (absDiff < DAY) {
+		count = Math.floor(absDiff / HOUR)
+		unit = 'hour'
+	} else if (absDiff < MONTH) {
+		count = Math.floor(absDiff / DAY)
+		unit = 'day'
+	} else if (absDiff < YEAR) {
+		count = Math.floor(absDiff / MONTH)
+		unit = 'month'
+	} else {
+		count = Math.floor(absDiff / YEAR)
+		unit = 'year'
+	}
+
+	const value = diffSeconds < 0 ? count : -count
+	// The long form keeps the "yesterday" idiom; the narrow form stays numeric
+	// ("1d ago", not "yesterday").
+	const numeric = style === 'long' && unit === 'day' && value === -1 ? 'auto' : 'always'
+	return getFormatter(locale, style, numeric).format(value, unit)
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip lines
+// ---------------------------------------------------------------------------
+
+/** Spelling that means "the viewer's own zone" without naming it. */
+const LOCAL_ZONE_ALIAS = 'local'
+
+const warnedTimezoneIDs = new Set<string>()
+
+function resolveTimezoneID(timezoneID: string | undefined): string | undefined {
+	if (timezoneID === undefined || timezoneID.toLowerCase() === LOCAL_ZONE_ALIAS) {
+		return undefined
+	}
+
+	// An unrecognized identifier makes every Intl.DateTimeFormat constructor
+	// throw a RangeError — degrade to the viewer's zone and say so once.
+	try {
+		new Intl.DateTimeFormat('en-US', { timeZone: timezoneID })
+	} catch {
+		if (!warnedTimezoneIDs.has(timezoneID)) {
+			warnedTimezoneIDs.add(timezoneID)
+			console.warn(
+				`[octane-xplat] Timestamp: unknown time zone ${JSON.stringify(timezoneID)} in tooltipEntries. Falling back to the viewer's time zone.`,
+			)
+		}
+
+		return undefined
+	}
+
+	return timezoneID
+}
+
+// Keyed on the *requested* zone, not the resolved offset: two named zones
+// stay distinguishable even when the viewer sits inside one of them.
+function zoneKey(resolved: string | undefined): string {
+	return resolved === undefined ? LOCAL_ZONE_ALIAS : resolved.toLowerCase()
+}
+
+function shouldShowZoneName(
+	format: TimestampTooltipFormat,
+	hasMultipleZones: boolean,
+	isNamedZone: boolean,
+): boolean {
+	if (format === 'full') {
+		return true
+	}
+
+	if (format === 'date_time' || format === 'time') {
+		return hasMultipleZones || isNamedZone
+	}
+
+	return false
+}
+
+/** Render one tooltip line per entry, in the order given. Pure. */
+export function formatTooltipLines(
+	date: Date,
+	entries: readonly TimestampTooltipEntry[],
+	locale?: Locale,
+): TimestampTooltipLine[] {
+	const resolved = entries.map((entry) => resolveTimezoneID(entry.timezoneID))
+	const hasMultipleZones = new Set(resolved.map(zoneKey)).size > 1
+
+	return entries.map((entry, index) => {
+		const format = entry.format ?? 'full'
+		const timeZone = resolved[index]
+
+		return {
+			...(entry.label === undefined ? {} : { label: entry.label }),
+			isCopyable: entry.isCopyable ?? false,
+			value: formatInstant(date, format, locale, {
+				timeZone,
+				isTimezoneShown: shouldShowZoneName(format, hasMultipleZones, timeZone !== undefined),
+			}),
+		}
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Component-side helpers
+// ---------------------------------------------------------------------------
+
+/** Seconds threshold for 'auto' format: below this, relative; else date_time. */
+export const DEFAULT_AUTO_THRESHOLD = 7 * DAY
+
+/** Parse the `Timestamp.value` contract: number < 1e12 = Unix seconds,
+ *  larger = ms; strings parse as dates (ISO 8601 recommended). */
+export function parseTimestampValue(value: string | number): Date {
+	if (typeof value === 'number') {
+		return new Date(value < 1e12 ? value * 1000 : value)
+	}
+
+	return new Date(value)
+}
+
+/** Interval (ms) for a live relative timestamp's next update. */
+export function getLiveInterval(diffSeconds: number): number {
+	const absDiff = Math.abs(diffSeconds)
+	if (absDiff < MINUTE) {
+		return 1000
+	}
+
+	if (absDiff < HOUR) {
+		return 30_000
+	}
+
+	if (absDiff < DAY) {
+		return 60_000
+	}
+
+	return 300_000
+}
+
+export function isRelativeFormat(format: TimestampFormat): boolean {
+	return format === 'relative' || format === 'relative_short'
+}
+
+export function isAbsoluteFormat(
+	format: TimestampFormat,
+): format is Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> {
+	return format !== 'relative' && format !== 'relative_short' && format !== 'auto'
+}
+
+/** Resolve the 'auto' alias to the concrete format for a given diff. */
+export function resolveTimestampFormat(
+	format: TimestampFormat,
+	diffSeconds: number,
+	autoThreshold: number,
+): TimestampFormat {
+	return format === 'auto'
+		? Math.abs(diffSeconds) <= autoThreshold
+			? 'relative'
+			: 'date_time'
+		: format
+}
+
+/** The visible text for one instant in the effective (resolved) format. */
+export function formatTimestampText(
+	date: Date,
+	format: Exclude<TimestampFormat, 'auto'>,
+	now: Date,
+	locale: Locale,
+	isTimezoneShown: boolean,
+): string {
+	if (format === 'relative') {
+		return formatRelativeTime(date, now, locale, 'long')
+	}
+
+	if (format === 'relative_short') {
+		return formatRelativeTime(date, now, locale, 'narrow')
+	}
+
+	if (isAbsoluteFormat(format)) {
+		return formatInstant(date, format, locale, { isTimezoneShown })
+	}
+
+	return ''
+}

package/src/timer-format.ts

@@ -0,0 +1,85 @@
+// Timer presentation math — ported from Astryx's Timer.tsx so the duration
+// text and the ISO 8601 `PT…S` value agree on every target.
+import type { TimerFormat } from './props'
+
+const ONE_SECOND_MS = 1000
+const ONE_MINUTE_MS = 60 * ONE_SECOND_MS
+const ONE_HOUR_SECONDS = 60 * 60
+const MAX_TIMEOUT_MS = 2_147_483_647
+
+export interface TimerPresentation {
+	/** ISO 8601 duration, e.g. 'PT95S' — the `dateTime` value on web. */
+	dateTime: string
+	text: string
+}
+
+function pad(value: number): string {
+	return String(value).padStart(2, '0')
+}
+
+export function resolveTimerFormat(format: TimerFormat | undefined): TimerFormat {
+	return format === 'clock' ? 'clock' : 'elapsed'
+}
+
+export function elapsedMilliseconds(now: number, startTime: number): number {
+	return Math.max(0, now - startTime)
+}
+
+export function timerPresentation(elapsedMs: number, format: TimerFormat): TimerPresentation {
+	const elapsedSeconds = Math.floor(elapsedMs / ONE_SECOND_MS)
+
+	if (format === 'clock') {
+		const hours = Math.floor(elapsedSeconds / ONE_HOUR_SECONDS)
+		const minutes = Math.floor((elapsedSeconds % ONE_HOUR_SECONDS) / 60)
+		const seconds = elapsedSeconds % 60
+		return {
+			dateTime: `PT${elapsedSeconds}S`,
+			text:
+				hours > 0
+					? `${String(hours)}:${pad(minutes)}:${pad(seconds)}`
+					: `${String(minutes)}:${pad(seconds)}`,
+		}
+	}
+
+	if (elapsedSeconds < 60) {
+		return {
+			dateTime: `PT${elapsedSeconds}S`,
+			text: `${String(elapsedSeconds)}s`,
+		}
+	}
+
+	const totalMinutes = Math.floor(elapsedSeconds / 60)
+	if (totalMinutes < 60) {
+		return {
+			dateTime: `PT${elapsedSeconds}S`,
+			text: `${String(totalMinutes)}m ${pad(elapsedSeconds % 60)}s`,
+		}
+	}
+
+	const representedSeconds = totalMinutes * 60
+	return {
+		dateTime: `PT${representedSeconds}S`,
+		text: `${String(Math.floor(totalMinutes / 60))}h ${pad(totalMinutes % 60)}m`,
+	}
+}
+
+/** Ms until the next visible change — also the cadence the tick loop uses.
+ *  Elapsed mode relaxes to once a minute past the hour mark; a future
+ *  startTime schedules the first tick for the start boundary. */
+export function msUntilNextChange(
+	now: number,
+	startTime: number,
+	elapsedMs: number,
+	format: TimerFormat,
+): number {
+	if (now < startTime) {
+		return Math.min(startTime - now + ONE_SECOND_MS, MAX_TIMEOUT_MS)
+	}
+
+	const precision =
+		format === 'elapsed' && elapsedMs >= ONE_HOUR_SECONDS * ONE_SECOND_MS
+			? ONE_MINUTE_MS
+			: ONE_SECOND_MS
+
+	return precision - (elapsedMs % precision)
+}

package/src/toast-context.ts

@@ -0,0 +1,18 @@
+import { createContext } from 'octane'
+import type { ToastPosition } from './props'
+
+/** The nearest `ToastViewport`'s routing identity + defaults. `useToast`
+ *  reads this in the declaring tree; the pushed entry carries the id so
+ *  the right stack renders it — context never has to cross the overlay
+ *  root boundary on native. */
+export interface ToastViewportContextValue {
+	id: string
+	position: ToastPosition
+	maxVisible: number
+}
+
+export const ToastViewportContext = createContext<ToastViewportContextValue | null>(null)
+
+/** JSX-provider form — universal-renderer contexts are callables, not
+ *  `.Provider` members (same aliasing as DialogProvider). */
+export const ToastViewportProvider: any = ToastViewportContext

package/src/toast-service.macos.tsrx

@@ -0,0 +1,43 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useCallback, useContext } from 'octane'
+import type { ShowToastFn, ToastOptions } from './props'
+import { ToastViewportContext } from './toast-context'
+import { FALLBACK_TOAST_VIEWPORT, dismissToast, pushToast, registerToastViewport, toastOnViewport, toastStore } from './toast-store'
+import { ToastViewportSurface } from './toast-viewport.macos.tsrx'
+
+let fallback: any = null
+
+function ensureFallbackViewport(): void {
+	if (fallback && !fallback.closed) return
+	const present = (globalThis as any).__xplatAppKit?.presentSurface
+	if (!present) throw new Error('AppKit host has no toast presenter')
+	const unregister = registerToastViewport(FALLBACK_TOAST_VIEWPORT)
+	try {
+		// A zero-size coordinator root owns the four edge stacks and anchored
+		// popovers; it closes with its window, releasing subscriptions/timers.
+		const host = present({ kind: 'toast', modal: false, width: 0, maxHeight: 0,
+			component: ToastViewportSurface, props: { viewportId: FALLBACK_TOAST_VIEWPORT } })
+
+		fallback = host
+		void host.closedPromise.then(() => {
+			unregister()
+			if (fallback === host) fallback = null
+			for (const entry of toastStore.get()) if (toastOnViewport(entry, FALLBACK_TOAST_VIEWPORT)) dismissToast(entry.id, 'manual')
+		})
+	} catch (error) { unregister(); throw error }
+}
+
+export const showToast: ShowToastFn = (options: ToastOptions) => {
+	ensureFallbackViewport()
+	const id = pushToast(options, FALLBACK_TOAST_VIEWPORT)
+	return () => dismissToast(id, 'manual')
+}
+
+export function useToast(): ShowToastFn @{
+	const ctx = useContext(ToastViewportContext)
+	return useCallback((options: ToastOptions) => {
+		ensureFallbackViewport()
+		const id = pushToast(options, ctx?.id ?? FALLBACK_TOAST_VIEWPORT)
+		return () => dismissToast(id, 'manual')
+	}, [ctx?.id])
+}