@octane-xplat/ui 0.9.0 → 0.10.0

package/src/Timer.macos.tsrx

@@ -0,0 +1,62 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useEffect, useRef, useState } from 'octane';
+import type { TimerProps } from './props';
+import {
+	elapsedMilliseconds,
+	msUntilNextChange,
+	resolveTimerFormat,
+	timerPresentation,
+} from './timer-format';
+
+import { cx } from './cx';
+import { textRoleClasses } from './text-role';
+
+/** Timer — macOS leaf, same as the mobile leaf (label + ISO duration). */
+export function Timer(props: TimerProps) @{
+	const format = resolveTimerFormat(props.format);
+	const startRef = useRef<number>(0);
+	if (startRef.current === 0) {
+		startRef.current = props.startTime ?? Date.now();
+	}
+
+	const startTime = props.startTime ?? startRef.current;
+
+	const [now, setNow] = useState(() => Date.now());
+
+	useEffect(() => {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let cancelled = false;
+		const tick = () => {
+			if (cancelled) return;
+			const at = Date.now();
+			const elapsed = elapsedMilliseconds(at, startTime);
+			timer = setTimeout(() => {
+				setNow(Date.now());
+				tick();
+			}, msUntilNextChange(at, startTime, elapsed, format));
+		};
+
+		tick();
+		return () => {
+			cancelled = true;
+			if (timer !== undefined) clearTimeout(timer);
+		};
+	}, [startTime, format]);
+
+	const elapsed = elapsedMilliseconds(now, startTime);
+	const { dateTime, text } = timerPresentation(elapsed, format);
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	<label
+		id={props.id}
+		className={cx('vx-timer', roleClasses, props.className)}
+		style={props.style}
+		text={text}
+		accessibilityValue={dateTime}
+	/>
+}

package/src/Timer.tsrx

@@ -0,0 +1,66 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useRef, useState } from 'octane';
+import type { TimerProps } from './props';
+import {
+	elapsedMilliseconds,
+	msUntilNextChange,
+	resolveTimerFormat,
+	timerPresentation,
+} from './timer-format';
+
+import { cx } from './cx';
+import { applyEscapeProps } from './escape-props';
+import { textRoleClasses } from './text-role';
+
+/** Timer — live elapsed duration label since `startTime` (ms; defaults to
+ *  mount). Native has no `<time>` element — the ISO 8601 duration rides on
+ *  `accessibilityValue`. Tick cadence follows the displayed precision. */
+export function Timer(props: TimerProps) @{
+	const format = resolveTimerFormat(props.format);
+	const startRef = useRef<number>(0);
+	if (startRef.current === 0) {
+		startRef.current = props.startTime ?? Date.now();
+	}
+
+	const startTime = props.startTime ?? startRef.current;
+
+	const [now, setNow] = useState(() => Date.now());
+
+	useEffect(() => {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let cancelled = false;
+		const tick = () => {
+			if (cancelled) return;
+			const at = Date.now();
+			const elapsed = elapsedMilliseconds(at, startTime);
+			timer = setTimeout(() => {
+				setNow(Date.now());
+				tick();
+			}, msUntilNextChange(at, startTime, elapsed, format));
+		};
+
+		tick();
+		return () => {
+			cancelled = true;
+			if (timer !== undefined) clearTimeout(timer);
+		};
+	}, [startTime, format]);
+
+	const elapsed = elapsedMilliseconds(now, startTime);
+	const { dateTime, text } = timerPresentation(elapsed, format);
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	<label
+		ref={(v: any) => applyEscapeProps(v, props)}
+		id={props.id}
+		className={cx('vx-timer', roleClasses, props.className)}
+		style={props.style}
+		text={text}
+		accessibilityValue={dateTime}
+	/>
+}

package/src/Timer.web.tsrx

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from 'octane';
+import type { TimerProps } from './props';
+import {
+	elapsedMilliseconds,
+	msUntilNextChange,
+	resolveTimerFormat,
+	timerPresentation,
+} from './timer-format';
+
+import { applyEscapeProps } from './escape-props';
+import { textRoleClasses } from './text-role';
+
+/** Timer — live elapsed duration since `startTime` (ms; defaults to mount).
+ *  Renders a semantic `<time>` whose `dateTime` is the ISO 8601 duration.
+ *  The tick cadence follows the displayed precision — seconds under an hour
+ *  in 'elapsed' mode, minutes after. */
+export function Timer(props: TimerProps) @{
+	const format = resolveTimerFormat(props.format);
+	const startRef = useRef<number>(0);
+	if (startRef.current === 0) {
+		startRef.current = props.startTime ?? Date.now();
+	}
+
+	const startTime = props.startTime ?? startRef.current;
+
+	const [now, setNow] = useState(() => Date.now());
+
+	useEffect(() => {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let cancelled = false;
+		const tick = () => {
+			if (cancelled) return;
+			const at = Date.now();
+			const elapsed = elapsedMilliseconds(at, startTime);
+			timer = setTimeout(() => {
+				setNow(Date.now());
+				tick();
+			}, msUntilNextChange(at, startTime, elapsed, format));
+		};
+
+		tick();
+		return () => {
+			cancelled = true;
+			if (timer !== undefined) clearTimeout(timer);
+		};
+	}, [startTime, format]);
+
+	const elapsed = elapsedMilliseconds(now, startTime);
+	const { dateTime, text } = timerPresentation(elapsed, format);
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	<time
+		ref={(e: any) => applyEscapeProps(e, props)}
+		id={props.id}
+		className={['vx-timer', ...roleClasses, props.className]}
+		style={props.style}
+		dateTime={dateTime}
+	>
+		{text}
+	</time>
+}

package/src/Timestamp.macos.tsrx

@@ -0,0 +1,115 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useEffect, useState } from 'octane';
+import type { TimestampProps, TimestampFormat } from './props';
+import {
+	DEFAULT_AUTO_THRESHOLD,
+	formatInstant,
+	formatTimestampText,
+	formatTooltipLines,
+	getLiveInterval,
+	isRelativeFormat,
+	parseTimestampValue,
+	resolveTimestampFormat,
+} from './time-format';
+
+import { cx } from './cx';
+import { textRoleClasses } from './text-role';
+import { HoverCard } from './HoverCard';
+
+/** Timestamp — macOS leaf. The AppKit host's HoverCard carries the tooltip
+ *  card (labels + copyable values as plain rows; the copy affordance is
+ *  pointer-web only). */
+export function Timestamp(props: TimestampProps) @{
+	const format = props.format ?? 'auto';
+	const autoThreshold = props.autoThreshold ?? DEFAULT_AUTO_THRESHOLD;
+	const hasTooltip = props.hasTooltip ?? true;
+	const isLive = props.isLive ?? false;
+	const isTimezoneShown = props.isTimezoneShown ?? false;
+
+	const date = parseTimestampValue(props.value);
+	const invalid = Number.isNaN(date.getTime());
+
+	const [now, setNow] = useState(() => new Date());
+	const diffSeconds = invalid ? 0 : (now.getTime() - date.getTime()) / 1000;
+	const resolved = resolveTimestampFormat(format, diffSeconds, autoThreshold);
+	const relative = !invalid && isRelativeFormat(resolved);
+
+	useEffect(() => {
+		if (!isLive || invalid || !relative) {
+			return;
+		}
+
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let cancelled = false;
+		const tick = () => {
+			if (cancelled) return;
+			timer = setTimeout(
+				() => {
+					setNow(new Date());
+					tick();
+				},
+				getLiveInterval((Date.now() - date.getTime()) / 1000),
+			);
+		};
+
+		tick();
+		return () => {
+			cancelled = true;
+			if (timer !== undefined) clearTimeout(timer);
+		};
+	}, [isLive, invalid, relative, props.value]);
+
+	const text = invalid
+		? 'Invalid Date'
+		: formatTimestampText(date, resolved as Exclude<TimestampFormat, 'auto'>, now, undefined, isTimezoneShown);
+
+	const absoluteLabel = invalid ? undefined : formatInstant(date, 'full', undefined, {});
+
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	const lines =
+		!invalid && hasTooltip
+			? formatTooltipLines(
+					date,
+					props.tooltipEntries?.length ? props.tooltipEntries : [{ format: 'full' }],
+					undefined,
+				)
+			: [];
+
+	const labelNode = (
+		<label
+			id={props.id}
+			className={cx('vx-timestamp', roleClasses, props.className)}
+			style={props.style}
+			text={text}
+			accessibilityLabel={relative ? absoluteLabel : undefined}
+		/>
+	);
+
+	return lines.length > 0 ? (
+		<HoverCard
+			content={
+				<flexboxlayout flexDirection="column" style={{ padding: 8, gap: 4 }}>
+					{lines.map((line, i) => (
+						<flexboxlayout key={i} flexDirection="row" style={{ gap: 8 }}>
+							{line.label != null ? (
+								<label className="text-sm text-muted" text={line.label} />
+							) : null}
+							<label className="text-sm" text={line.value} />
+						</flexboxlayout>
+					))}
+				</flexboxlayout>
+			}
+			placement="top"
+		>
+			{labelNode}
+		</HoverCard>
+	) : (
+		labelNode
+	);
+}

package/src/Timestamp.tsrx

@@ -0,0 +1,82 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useState } from 'octane';
+import type { TimestampProps, TimestampFormat } from './props';
+import {
+	DEFAULT_AUTO_THRESHOLD,
+	formatInstant,
+	formatTimestampText,
+	getLiveInterval,
+	isRelativeFormat,
+	parseTimestampValue,
+	resolveTimestampFormat,
+} from './time-format';
+
+import { cx } from './cx';
+import { applyEscapeProps } from './escape-props';
+import { textRoleClasses } from './text-role';
+
+/** Timestamp — human-readable instant on native. A label carrying the
+ *  formatted text; relative formats set the absolute `full` form as the
+ *  accessible label. `isLive` re-renders on the relative cadence. There is
+ *  no pointer-hover surface on touch targets, so `hasTooltip`/`tooltipEntries`
+ *  are accepted for API parity but inert (the absolute instant stays
+ *  reachable via the accessible label — see docs/app/components.md). */
+export function Timestamp(props: TimestampProps) @{
+	const format = props.format ?? 'auto';
+	const autoThreshold = props.autoThreshold ?? DEFAULT_AUTO_THRESHOLD;
+	const isLive = props.isLive ?? false;
+	const isTimezoneShown = props.isTimezoneShown ?? false;
+
+	const date = parseTimestampValue(props.value);
+	const invalid = Number.isNaN(date.getTime());
+
+	const [now, setNow] = useState(() => new Date());
+	const diffSeconds = invalid ? 0 : (now.getTime() - date.getTime()) / 1000;
+	const resolved = resolveTimestampFormat(format, diffSeconds, autoThreshold);
+	const relative = !invalid && isRelativeFormat(resolved);
+
+	useEffect(() => {
+		if (!isLive || invalid || !relative) {
+			return;
+		}
+
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let cancelled = false;
+		const tick = () => {
+			if (cancelled) return;
+			const interval = getLiveInterval((Date.now() - date.getTime()) / 1000);
+			timer = setTimeout(() => {
+				setNow(new Date());
+				tick();
+			}, interval);
+		};
+
+		tick();
+		return () => {
+			cancelled = true;
+			if (timer !== undefined) clearTimeout(timer);
+		};
+	}, [isLive, invalid, relative, props.value]);
+
+	const text = invalid
+		? 'Invalid Date'
+		: formatTimestampText(date, resolved as Exclude<TimestampFormat, 'auto'>, now, undefined, isTimezoneShown);
+
+	const absoluteLabel = invalid ? undefined : formatInstant(date, 'full', undefined, {});
+
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	<label
+		ref={(v: any) => applyEscapeProps(v, props)}
+		id={props.id}
+		className={cx('vx-timestamp', roleClasses, props.className)}
+		style={props.style}
+		text={text}
+		accessibilityLabel={relative ? absoluteLabel : undefined}
+	/>
+}

package/src/Timestamp.web.tsrx

@@ -0,0 +1,163 @@
+import { useEffect, useState } from 'octane';
+import type { TimestampProps } from './props';
+import type { TimestampTooltipLine } from './time-format';
+import {
+	DEFAULT_AUTO_THRESHOLD,
+	formatInstant,
+	formatTimestampText,
+	formatTooltipLines,
+	getLiveInterval,
+	isAbsoluteFormat,
+	isRelativeFormat,
+	parseTimestampValue,
+	resolveTimestampFormat,
+} from './time-format';
+
+import type { TimestampFormat } from './props';
+import { applyEscapeProps } from './escape-props';
+import { HoverCard } from './HoverCard.web.tsrx';
+import { Icon } from './Icon.web.tsrx';
+import { copyText } from './clipboard-write';
+import { textRoleClasses } from './text-role';
+
+const COPY_FEEDBACK_MS = 1500;
+
+function CopyButton(props: { value: string; label?: string }) @{
+	const [copied, setCopied] = useState(false);
+	useEffect(() => {
+		if (!copied) return;
+		const t = setTimeout(() => setCopied(false), COPY_FEEDBACK_MS);
+		return () => clearTimeout(t);
+	}, [copied]);
+
+	<button
+		type="button"
+		className="vx-timestamp-copy"
+		aria-label={copied ? 'Copied' : `Copy ${props.value}`}
+		title={copied ? 'Copied' : 'Copy'}
+		onClick={() => {
+			void copyText(props.value).then((ok) => {
+				if (ok) setCopied(true);
+			});
+		}}
+	>
+		<Icon name={copied ? 'xplat-check' : 'xplat-copy'} size={12} />
+	</button>
+}
+
+function TimestampCard(props: { lines: readonly TimestampTooltipLine[] }) @{
+	const hasLabelColumn = props.lines.some((l) => l.label != null);
+	const hasActionColumn = props.lines.some((l) => l.isCopyable);
+	const template = hasLabelColumn
+		? hasActionColumn
+			? 'auto 1fr auto'
+			: 'auto 1fr'
+		: hasActionColumn
+			? '1fr auto'
+			: '1fr';
+
+	<div className="vx-timestamp-card">
+		<div className="vx-timestamp-card-grid" style={{ gridTemplateColumns: template }}>
+			{props.lines.map((line, i) => (
+				<div key={i} className="vx-timestamp-card-row">
+					{hasLabelColumn ? <div className="vx-timestamp-card-label">{line.label ?? ''}</div> : null}
+					<div className="vx-timestamp-card-value">{line.value}</div>
+					{hasActionColumn ? (
+						<div className="vx-timestamp-card-action">
+							{line.isCopyable ? <CopyButton value={line.value} /> : null}
+						</div>
+					) : null}
+				</div>
+			))}
+		</div>
+	</div>
+}
+
+/** Timestamp — human-readable instant. `<time dateTime>` carries the ISO
+ *  instant; relative formats announce the absolute `full` form via
+ *  aria-label. 'auto' is relative below `autoThreshold` seconds, else
+ *  `date_time`. `isLive` re-renders on the relative cadence. `hasTooltip`
+ *  opens the HoverCard with one row per tooltip entry. */
+export function Timestamp(props: TimestampProps) @{
+	const format = props.format ?? 'auto';
+	const autoThreshold = props.autoThreshold ?? DEFAULT_AUTO_THRESHOLD;
+	const hasTooltip = props.hasTooltip ?? true;
+	const isLive = props.isLive ?? false;
+	const isTimezoneShown = props.isTimezoneShown ?? false;
+
+	const date = parseTimestampValue(props.value);
+	const invalid = Number.isNaN(date.getTime());
+
+	const [now, setNow] = useState(() => new Date());
+	const relative = !invalid && isRelativeFormat(resolveTimestampFormat(format, (now.getTime() - date.getTime()) / 1000, autoThreshold));
+
+	useEffect(() => {
+		if (!isLive || invalid || !relative) {
+			return;
+		}
+
+		const tick = () => {
+			const interval = getLiveInterval((Date.now() - date.getTime()) / 1000);
+			const t = setTimeout(() => {
+				setNow(new Date());
+				tick();
+			}, interval);
+
+			return t;
+		};
+
+		const interval = getLiveInterval((Date.now() - date.getTime()) / 1000);
+		const t = setTimeout(() => {
+			setNow(new Date());
+			tick();
+		}, interval);
+
+		return () => clearTimeout(t);
+	}, [isLive, invalid, relative, props.value]);
+
+	const diffSeconds = invalid ? 0 : (now.getTime() - date.getTime()) / 1000;
+	const resolved = resolveTimestampFormat(format, diffSeconds, autoThreshold);
+	const text = invalid
+		? 'Invalid Date'
+		: formatTimestampText(date, resolved as Exclude<TimestampFormat, 'auto'>, now, undefined, isTimezoneShown);
+
+	const absoluteLabel = invalid ? undefined : formatInstant(date, 'full', undefined, {});
+	const iso = invalid ? undefined : date.toISOString();
+
+	const lines =
+		!invalid && hasTooltip
+			? formatTooltipLines(
+					date,
+					props.tooltipEntries?.length ? props.tooltipEntries : [{ format: 'full' }],
+					undefined,
+				)
+			: [];
+
+	const roleClasses = textRoleClasses({
+		type: props.type ?? 'supporting',
+		size: props.size,
+		color: props.color ?? 'secondary',
+		weight: props.weight,
+	});
+
+	const time = (
+		<time
+			ref={(e: any) => applyEscapeProps(e, props)}
+			id={props.id}
+			className={['vx-timestamp', ...roleClasses, props.className]}
+			style={props.style}
+			dateTime={iso}
+			aria-label={isRelativeFormat(resolved) ? absoluteLabel : undefined}
+		>
+			{text}
+		</time>
+	);
+
+	return hasTooltip && lines.length > 0 ? (
+		<HoverCard content={<TimestampCard lines={lines} />} placement="above" label={absoluteLabel}>
+			{time}
+		</HoverCard>
+	) : (
+		time
+	);
+}

package/src/Toast.macos.tsrx

@@ -0,0 +1,72 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useCallback, useEffect, useRef } from 'octane'
+import type { ToastProps, ToastContentRenderProps } from './props'
+import { cx } from './cx'
+import { Button } from './controls.macos.tsrx'
+import { toastTiming } from './toast-store'
+
+/** Timed notification card shared by inline and presented stacks. */
+export function Toast(props: ToastProps) @{
+	const timing = toastTiming(props)
+	const onDismiss = useRef(props.onDismiss)
+	onDismiss.current = props.onDismiss
+	const view = useRef<any>(null)
+	const dismissed = useRef(false)
+	const dismiss = useCallback((reason: 'auto' | 'manual') => {
+		if (dismissed.current) return
+		dismissed.current = true
+		onDismiss.current?.(reason)
+	}, [])
+
+	useEffect(() => {
+		if (!timing.isAutoHide || props.isExiting) return
+		let remaining = timing.autoHideDuration
+		let last = Date.now()
+		let hovered = false
+		let timer: ReturnType<typeof setTimeout>
+		const focused = () => {
+			const responder = view.current?.window?.firstResponder
+			for (const start of [responder, responder?.delegate]) {
+				for (let current = start; current; current = current.superview) {
+					if (current === view.current || current.isEqual?.(view.current)) return true
+				}
+			}
+
+			return false
+		}
+
+		let paused = false
+		const tick = () => {
+			const now = Date.now()
+			if (!paused) remaining -= now - last
+			last = now
+			paused = hovered || focused()
+			if (remaining <= 0 && !paused) { dismiss('auto'); return }
+			timer = setTimeout(tick, paused ? 100 : Math.min(100, Math.max(0, remaining)))
+		}
+
+		const detach = (globalThis as any).__xplatAppKit?.observeHover?.(view.current, {
+			enter: () => { hovered = true }, exit: () => { hovered = false },
+		})
+
+		timer = setTimeout(tick, Math.min(100, remaining))
+		return () => { clearTimeout(timer); detach?.() }
+	}, [timing.isAutoHide, timing.autoHideDuration, props.isExiting, dismiss])
+
+	const content: ToastContentRenderProps = {
+		body: props.body, endContent: props.endContent, type: props.type ?? 'info', ...timing,
+		dismiss: () => dismiss('manual'),
+	}
+
+	<flexboxlayout flexDirection="row" alignItems="center" id={props.id} ref={view}
+		className={cx('vx-toast', props.type === 'error' && 'vx-toast--error', props.className)}
+		style={{ opacity: props.isExiting ? 0 : 1, ...props.style }}>
+		{props.renderContent ? props.renderContent(content) : (
+			<flexboxlayout flexDirection="column" flexGrow={1} className="vx-toast-content">
+				{typeof props.body === 'string' ? <label whiteSpace="normal">{props.body}</label> : props.body}
+				{props.endContent}
+			</flexboxlayout>
+		)}
+		{props.onDismiss != null && <Button accessibilityLabel="Dismiss notification" onPress={() => dismiss('manual')}>×</Button>}
+	</flexboxlayout>
+}