@dorsk/tsumikit 0.2.5 → 0.2.6

package/dist/components/molecules/Timestamp.svelte

@@ -1,9 +1,10 @@
 <script lang="ts">
-	// A timestamp you can read four ways and inspect in one place. Inline it
-	// renders in the chosen `mode` (ISO / local / clock / relative); by default
-	// clicking it opens a popover that lays out the same instant as ISO-UTC,
-	// local, relative, the IANA zone and the unix epoch — so the one value
-	// answers "when, exactly?" without leaving the row. The popover is read-only
+	// A timestamp you can read five ways and inspect in one place. Inline it
+	// renders in the chosen `mode` (date / time / datetime / relative / iso),
+	// in the viewer's zone or UTC via the `utc` flag; by default clicking it
+	// opens a popover that lays out the same instant as ISO-UTC, local, relative,
+	// the IANA zone and the unix epoch — so the one value answers "when,
+	// exactly?" without leaving the row. The popover is read-only
 	// unless you opt into `selectable`, which adds buttons to switch the inline
 	// display mode (handy in a demo / settings surface, rarely in a data row).
 	//
@@ -19,26 +20,35 @@
 		toDate,
 		toEpochSeconds,
 		toISO,
-		toLocal,
+		toLocale,
 		type TimeInput,
 		type TimestampMode
 	} from '../../timestamp';
 
 	type Tone = 'inherit' | 'default' | 'muted' | 'faint' | 'danger' | 'accent';
+	type Size = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | '2xl';
 
 	let {
 		value,
-		mode = 'iso',
+		mode = 'datetime',
+		utc = false,
 		details = true,
 		selectable = false,
 		mono = false,
 		tone = 'muted',
+		size,
 		tickMs = 30_000
 	}: {
-		/** The instant: a Date, epoch milliseconds, or an ISO/parseable string. */
-		value: TimeInput;
-		/** Inline display mode. Default 'iso'. */
+		/** The instant: a Date, epoch milliseconds, or an ISO/parseable string.
+		 *  null/undefined (or unparseable input) renders an inert "—". */
+		value: TimeInput | null | undefined;
+		/** Inline display mode. Default 'datetime'. */
 		mode?: TimestampMode;
+		/** Render the date/time/datetime modes in UTC rather than the viewer's
+		 *  zone. Default false. Ignored by 'iso' (always UTC) and 'relative'
+		 *  (zoneless). Handy for calendar-date fields, where a local midnight-UTC
+		 *  value would otherwise show the wrong day. */
+		utc?: boolean;
 		/** Click to open the details popover (UTC / local / relative / zone /
 		 *  epoch). Default true. When false, renders as a bare inline <time>. */
 		details?: boolean;
@@ -50,6 +60,9 @@
 		/** Text colour, mirroring <Text> tones. Default 'muted' — timestamps read
 		 *  as subdued metadata; pass 'inherit' to blend with surrounding copy. */
 		tone?: Tone;
+		/** Font size, mirroring <Text> sizes (maps to --fs-* tokens). Omit to
+		 *  inherit the surrounding size. */
+		size?: Size;
 		/** How often relative mode re-renders so "3m ago" stays fresh. */
 		tickMs?: number;
 	} = $props();
@@ -70,24 +83,28 @@
 	});
 
 	const date = $derived(toDate(value));
-	const label = $derived(formatTimestamp(value, current, now));
+	const label = $derived(formatTimestamp(value, current, now, utc));
 	// datetime= wants a valid ISO string; omit it entirely on bad input.
 	const machine = $derived(date ? toISO(date) : undefined);
 	const showPopover = $derived(details || selectable);
 	const cls = $derived(`ts tone-${tone}${mono ? ' mono' : ''}`);
+	// Size maps straight onto the --fs-* scale; null leaves font-size unset so the
+	// timestamp inherits its surrounding run.
+	const sizeVar = $derived(size ? `var(--fs-${size})` : null);
 
 	const MODES: { id: TimestampMode; name: string }[] = [
-		{ id: 'iso', name: 'ISO' },
-		{ id: 'local', name: 'Local' },
+		{ id: 'date', name: 'Date' },
 		{ id: 'time', name: 'Time' },
-		{ id: 'relative', name: 'Relative' }
+		{ id: 'datetime', name: 'Date+time' },
+		{ id: 'relative', name: 'Relative' },
+		{ id: 'iso', name: 'ISO' }
 	];
 
 	const rows = $derived(
 		date
 			? [
 					{ k: 'UTC', v: toISO(date) },
-					{ k: 'Local', v: toLocal(date) },
+					{ k: 'Local', v: toLocale(date, 'datetime') },
 					{ k: 'Relative', v: relativeTime(date, now) },
 					{ k: 'Time zone', v: localTimeZone() },
 					{ k: 'Unix', v: String(toEpochSeconds(date)) }
@@ -98,11 +115,11 @@
 
 {#if !date}
 	<!-- Unparseable input: degrade to an inert dash rather than empty text. -->
-	<time class="{cls} ts-invalid">—</time>
+	<time class="{cls} ts-invalid" style:font-size={sizeVar}>—</time>
 {:else if showPopover}
 	<Popover label="Timestamp details" placement="bottom-start" bare>
 		{#snippet trigger()}
-			<time class="{cls} ts-trigger" datetime={machine}>{label}</time>
+			<time class="{cls} ts-trigger" style:font-size={sizeVar} datetime={machine}>{label}</time>
 		{/snippet}
 		<div class="ts-panel">
 			{#if selectable}
@@ -129,7 +146,7 @@
 		</div>
 	</Popover>
 {:else}
-	<time class={cls} datetime={machine}>{label}</time>
+	<time class={cls} style:font-size={sizeVar} datetime={machine}>{label}</time>
 {/if}
 
 <style>

package/dist/components/molecules/Timestamp.svelte.d.ts

@@ -1,10 +1,17 @@
 import { type TimeInput, type TimestampMode } from '../../timestamp';
 type Tone = 'inherit' | 'default' | 'muted' | 'faint' | 'danger' | 'accent';
+type Size = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | '2xl';
 type $$ComponentProps = {
-    /** The instant: a Date, epoch milliseconds, or an ISO/parseable string. */
-    value: TimeInput;
-    /** Inline display mode. Default 'iso'. */
+    /** The instant: a Date, epoch milliseconds, or an ISO/parseable string.
+     *  null/undefined (or unparseable input) renders an inert "—". */
+    value: TimeInput | null | undefined;
+    /** Inline display mode. Default 'datetime'. */
     mode?: TimestampMode;
+    /** Render the date/time/datetime modes in UTC rather than the viewer's
+     *  zone. Default false. Ignored by 'iso' (always UTC) and 'relative'
+     *  (zoneless). Handy for calendar-date fields, where a local midnight-UTC
+     *  value would otherwise show the wrong day. */
+    utc?: boolean;
     /** Click to open the details popover (UTC / local / relative / zone /
      *  epoch). Default true. When false, renders as a bare inline <time>. */
     details?: boolean;
@@ -16,6 +23,9 @@ type $$ComponentProps = {
     /** Text colour, mirroring <Text> tones. Default 'muted' — timestamps read
      *  as subdued metadata; pass 'inherit' to blend with surrounding copy. */
     tone?: Tone;
+    /** Font size, mirroring <Text> sizes (maps to --fs-* tokens). Omit to
+     *  inherit the surrounding size. */
+    size?: Size;
     /** How often relative mode re-renders so "3m ago" stays fresh. */
     tickMs?: number;
 };

package/dist/timestamp.d.ts

@@ -1,14 +1,25 @@
 export type TimeInput = Date | number | string;
-/** How the timestamp text renders inline. */
-export type TimestampMode = 'iso' | 'local' | 'time' | 'relative';
-/** Coerce a loose input to a Date, or null when it can't be parsed. */
-export declare function toDate(value: TimeInput): Date | null;
+/**
+ * Which slice of the instant the inline text shows. Orthogonal to the zone:
+ * `date`/`time`/`datetime` honour the `utc` flag, while `iso` is always UTC
+ * (by definition) and `relative` is zoneless.
+ */
+export type TimestampMode = 'date' | 'time' | 'datetime' | 'relative' | 'iso';
+/**
+ * Coerce a loose input to a Date, or null when it's missing or can't be parsed.
+ * Accepting null/undefined lets callers pass an optional field straight through
+ * — the empty case lands on the same "no date" path as bad input.
+ */
+export declare function toDate(value: TimeInput | null | undefined): Date | null;
 /** Full ISO 8601, UTC — `2026-06-14T07:30:00.000Z`. */
 export declare function toISO(d: Date): string;
-/** Locale date+time in the viewer's zone — `6/14/2026, 4:30:00 PM`. */
-export declare function toLocal(d: Date): string;
-/** Clock only, zero-padded `HH:MM:SS`, in the viewer's local zone. */
-export declare function toClock(d: Date): string;
+/**
+ * Locale-formatted date and/or time, in the viewer's zone or UTC. The single
+ * `Intl`-backed formatter behind the `date`/`time`/`datetime` modes — splitting
+ * the slice (what) from the zone (where) so a date-only field can render `utc`
+ * without the off-by-one a local midnight-UTC value otherwise shows.
+ */
+export declare function toLocale(d: Date, parts?: 'date' | 'time' | 'datetime', utc?: boolean): string;
 /** Unix epoch in whole seconds. */
 export declare function toEpochSeconds(d: Date): number;
 /** The viewer's IANA time zone — `Asia/Tokyo`, `UTC`, … */
@@ -18,6 +29,10 @@ export declare function localTimeZone(): string;
  * falling back to a locale date once past ~30 days. Future instants read
  * "in 3m" etc. `now` is injectable so callers (and tests) control the clock.
  */
-export declare function relativeTime(value: TimeInput, now?: number): string;
-/** Render a date in the chosen inline mode. Returns '' for unparseable input. */
-export declare function formatTimestamp(value: TimeInput, mode: TimestampMode, now?: number): string;
+export declare function relativeTime(value: TimeInput | null | undefined, now?: number): string;
+/**
+ * Render a date in the chosen inline mode. `utc` selects UTC over the viewer's
+ * zone for the date/time/datetime modes (ignored by `iso`, always UTC, and
+ * `relative`, zoneless). Returns '' for unparseable input.
+ */
+export declare function formatTimestamp(value: TimeInput | null | undefined, mode: TimestampMode, now?: number, utc?: boolean): string;

package/dist/timestamp.js

@@ -4,8 +4,14 @@
 // `TimeInput` (Date | epoch ms | ISO string) and tolerates bad input by
 // returning '' rather than throwing, so a single malformed value never takes
 // down a table row.
-/** Coerce a loose input to a Date, or null when it can't be parsed. */
+/**
+ * Coerce a loose input to a Date, or null when it's missing or can't be parsed.
+ * Accepting null/undefined lets callers pass an optional field straight through
+ * — the empty case lands on the same "no date" path as bad input.
+ */
 export function toDate(value) {
+    if (value == null)
+        return null;
     const d = value instanceof Date ? value : new Date(value);
     return Number.isNaN(d.getTime()) ? null : d;
 }
@@ -13,14 +19,27 @@ export function toDate(value) {
 export function toISO(d) {
     return d.toISOString();
 }
-/** Locale date+time in the viewer's zone — `6/14/2026, 4:30:00 PM`. */
-export function toLocal(d) {
-    return d.toLocaleString();
-}
-/** Clock only, zero-padded `HH:MM:SS`, in the viewer's local zone. */
-export function toClock(d) {
-    const p = (n) => String(n).padStart(2, '0');
-    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+/**
+ * Locale-formatted date and/or time, in the viewer's zone or UTC. The single
+ * `Intl`-backed formatter behind the `date`/`time`/`datetime` modes — splitting
+ * the slice (what) from the zone (where) so a date-only field can render `utc`
+ * without the off-by-one a local midnight-UTC value otherwise shows.
+ */
+export function toLocale(d, parts = 'datetime', utc = false) {
+    const opts = {};
+    if (utc)
+        opts.timeZone = 'UTC';
+    if (parts !== 'time') {
+        opts.year = 'numeric';
+        opts.month = 'numeric';
+        opts.day = 'numeric';
+    }
+    if (parts !== 'date') {
+        opts.hour = '2-digit';
+        opts.minute = '2-digit';
+        opts.second = '2-digit';
+    }
+    return new Intl.DateTimeFormat(undefined, opts).format(d);
 }
 /** Unix epoch in whole seconds. */
 export function toEpochSeconds(d) {
@@ -56,18 +75,22 @@ export function relativeTime(value, now = Date.now()) {
         return suffix(`${days}d`);
     return d.toLocaleDateString();
 }
-/** Render a date in the chosen inline mode. Returns '' for unparseable input. */
-export function formatTimestamp(value, mode, now) {
+/**
+ * Render a date in the chosen inline mode. `utc` selects UTC over the viewer's
+ * zone for the date/time/datetime modes (ignored by `iso`, always UTC, and
+ * `relative`, zoneless). Returns '' for unparseable input.
+ */
+export function formatTimestamp(value, mode, now, utc = false) {
     const d = toDate(value);
     if (!d)
         return '';
     switch (mode) {
         case 'iso':
             return toISO(d);
-        case 'local':
-            return toLocal(d);
+        case 'date':
         case 'time':
-            return toClock(d);
+        case 'datetime':
+            return toLocale(d, mode, utc);
         case 'relative':
             return relativeTime(d, now);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",