@dorsk/tsumikit 0.2.5 → 0.2.7

package/dist/components/layouts/AutoGrid.svelte

@@ -7,30 +7,65 @@
 	// gutter. `maxCols` optionally caps how many columns the grid will ever show:
 	// it raises the effective per-column minimum to the width N columns would
 	// need, so auto-fit can never pack more than N across.
+	//
+	// `max` caps each column's width: instead of growing to fill the row (the
+	// default `1fr`), columns top out at `max` and the grid left-packs them
+	// (auto-fill + justify-content:start) so a 3-item and a 4-item section both
+	// show uniform fixed-width columns rather than stretching to fill. `align`
+	// controls cross-axis alignment of items within their row; it defaults to
+	// `start` so cards don't stretch to the tallest sibling.
 	import type { Snippet } from 'svelte';
 
 	let {
 		as = 'div',
 		min = '14rem',
+		max,
 		gap = 'var(--sp-4)',
 		maxCols,
+		align = 'start',
+		justify,
 		class: klass = '',
 		children,
 		...rest
 	}: {
 		as?: 'div' | 'section' | 'ul' | 'ol';
 		min?: string;
+		/** Maximum column width. When set, columns stop growing at this width and
+		 * the grid left-packs uniform tracks instead of stretching to fill. */
+		max?: string;
 		gap?: string;
 		maxCols?: number;
+		/** Cross-axis alignment of items in their row (align-items). Defaults to `start`. */
+		align?: 'start' | 'center' | 'end' | 'stretch';
+		/** Inline (main-axis) distribution of tracks (justify-content). Defaults to
+		 * `start` when `max` is set, otherwise the grid's natural `stretch`. */
+		justify?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
 		class?: string;
 		children?: Snippet;
 		[key: string]: unknown;
 	} = $props();
 
+	// Columns grow to fill (`1fr`) by default; when `max` is given they cap there.
+	let track = $derived(max != null ? max : '1fr');
+	// auto-fill keeps capped tracks from stretching to fill the row; auto-fit
+	// (the default) collapses empty tracks so columns expand to use the space.
+	let mode = $derived(max != null ? 'auto-fill' : 'auto-fit');
+	// Left-pack capped grids by default so columns don't drift to fill the row.
+	let justifyValue = $derived(justify ?? (max != null ? 'start' : null));
+
 	let style = $derived(
-		maxCols != null
-			? `--ag-min: ${min}; --ag-gap: ${gap}; --ag-cols: ${maxCols}; gap: ${gap}`
-			: `--ag-min: ${min}; gap: ${gap}`
+		[
+			`--ag-min: ${min}`,
+			`--ag-track: ${track}`,
+			`--ag-mode: ${mode}`,
+			maxCols != null ? `--ag-gap: ${gap}` : null,
+			maxCols != null ? `--ag-cols: ${maxCols}` : null,
+			`gap: ${gap}`,
+			`align-items: ${align}`,
+			justifyValue ? `justify-content: ${justifyValue}` : null
+		]
+			.filter(Boolean)
+			.join('; ')
 	);
 </script>
 
@@ -47,7 +82,7 @@
 <style>
 	.autogrid-c {
 		display: grid;
-		grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--ag-min)), 1fr));
+		grid-template-columns: repeat(var(--ag-mode), minmax(min(100%, var(--ag-min)), var(--ag-track)));
 	}
 
 	/* Cap at N columns: the per-column floor becomes the larger of `min` and the
@@ -56,10 +91,10 @@
 	   overflowing when the container is narrower than a single `min` track. */
 	.autogrid-c.capped {
 		grid-template-columns: repeat(
-			auto-fit,
+			var(--ag-mode),
 			minmax(
 				min(100%, max(var(--ag-min), (100% - (var(--ag-cols) - 1) * var(--ag-gap)) / var(--ag-cols))),
-				1fr
+				var(--ag-track)
 			)
 		);
 	}

package/dist/components/layouts/AutoGrid.svelte.d.ts

@@ -2,8 +2,16 @@ import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     as?: 'div' | 'section' | 'ul' | 'ol';
     min?: string;
+    /** Maximum column width. When set, columns stop growing at this width and
+     * the grid left-packs uniform tracks instead of stretching to fill. */
+    max?: string;
     gap?: string;
     maxCols?: number;
+    /** Cross-axis alignment of items in their row (align-items). Defaults to `start`. */
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /** Inline (main-axis) distribution of tracks (justify-content). Defaults to
+     * `start` when `max` is set, otherwise the grid's natural `stretch`. */
+    justify?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch';
     class?: string;
     children?: Snippet;
     [key: string]: unknown;

package/dist/components/layouts/Container.svelte

@@ -1,21 +1,27 @@
 <script lang="ts">
 	// Centered, max-width content column with token gutters that respect safe-area
 	// insets. `size` overrides the default --content-max; `pad` toggles vertical
-	// padding. Polymorphic via `as` so it can be a <main>, <section>, etc.
+	// padding. `fullWidth` releases the max-width constraint and lets the content
+	// bleed to the full viewport width even when nested inside a centered ancestor
+	// (the `margin-inline: calc(50% - 50vw)` trick), for edge-to-edge sections.
+	// Polymorphic via `as` so it can be a <main>, <section>, etc.
 	import type { Snippet } from 'svelte';
 
 	let {
 		as = 'div',
 		size,
 		pad = false,
+		fullWidth = false,
 		class: klass = '',
 		children,
 		...rest
 	}: {
 		as?: 'div' | 'main' | 'section' | 'article';
-		/** Max width (any CSS length). Defaults to --content-max. */
+		/** Max width (any CSS length). Defaults to --content-max. Ignored when `fullWidth`. */
 		size?: string;
 		pad?: boolean;
+		/** Break out to the full viewport width, ignoring `size`/--content-max. */
+		fullWidth?: boolean;
 		class?: string;
 		children?: Snippet;
 		[key: string]: unknown;
@@ -26,7 +32,8 @@
 	this={as}
 	class="container ct {klass}"
 	class:pad
-	style={size ? `max-width: ${size}` : undefined}
+	class:full={fullWidth}
+	style={!fullWidth && size ? `max-width: ${size}` : undefined}
 	{...rest}
 >
 	{@render children?.()}
@@ -37,4 +44,13 @@
 		padding-top: var(--sp-6);
 		padding-bottom: var(--sp-12);
 	}
+
+	/* Break out of any centered ancestor to span the full viewport width.
+	   `margin-inline: calc(50% - 50vw)` pulls each edge out to the viewport,
+	   keeping the element in normal flow (no transform/overflow side-effects). */
+	.ct.full {
+		max-width: none;
+		width: 100vw;
+		margin-inline: calc(50% - 50vw);
+	}
 </style>

package/dist/components/layouts/Container.svelte.d.ts

@@ -1,9 +1,11 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     as?: 'div' | 'main' | 'section' | 'article';
-    /** Max width (any CSS length). Defaults to --content-max. */
+    /** Max width (any CSS length). Defaults to --content-max. Ignored when `fullWidth`. */
     size?: string;
     pad?: boolean;
+    /** Break out to the full viewport width, ignoring `size`/--content-max. */
+    fullWidth?: boolean;
     class?: string;
     children?: Snippet;
     [key: string]: unknown;

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.7",
   "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",