@galaxy-io/dls 2.9.0 → 2.10.0

package/dist/table/useInfiniteScrollSentinel.d.ts

@@ -1,17 +1,14 @@
 /**
- * @internal Shared by the table components; apps use InfiniteTable, VirtualizedInfiniteTable or
- * InfiniteSpreadsheet.
- *
- * The `onEndReached` sentinel: a 1px element after the table, observed with an
- * `IntersectionObserver` whose bottom margin is `marginPx` (`TABLE_END_REACHED_MARGIN_PX`). The root is the
- * scroll container when it overflows, otherwise the viewport, so a table in an unbounded parent
- * pages on page scroll. Armed only while enabled (not loading, no error), re-armed when the row
- * count changes, and calls `onEndReached` at most once per row count: an app with no next page
- * adds no rows, so it is not called again. Without `IntersectionObserver` it falls back to a
- * passive `scroll` listener. Nothing runs at module scope.
+ * @internal
+ * @deprecated Use `@galaxy-io/dls/hooks/useEndReached`, which this wraps (the same observer, with
+ * `rowCount` named `itemCount` and `scrollRef` and `marginPx` optional). Kept so the published
+ * subpath keeps working; it goes in 3.0.
+ */
+import type { RefObject } from "react";
+/**
+ * @internal Options for `useInfiniteScrollSentinel`.
+ * @deprecated Use `UseEndReachedOptions` from `@galaxy-io/dls/hooks/useEndReached`.
  */
-import { type RefObject } from "react";
-/** @internal Options for `useInfiniteScrollSentinel`. */
 export interface UseInfiniteScrollSentinelOptions {
     /** The table's scroll container. */
     scrollRef: RefObject<HTMLElement | null>;
@@ -24,5 +21,8 @@ export interface UseInfiniteScrollSentinelOptions {
     /** How far below the visible area the end counts as reached, in pixels. */
     marginPx: number;
 }
-/** @internal Observes the sentinel and calls `onEndReached`; returns the sentinel's ref. */
+/**
+ * @internal Observes the zero-size sentinel and calls `onEndReached`; returns the sentinel's ref.
+ * @deprecated Use `useEndReached` from `@galaxy-io/dls/hooks/useEndReached`.
+ */
 export declare function useInfiniteScrollSentinel({ scrollRef, onEndReached, isEnabled, rowCount, marginPx, }: UseInfiniteScrollSentinelOptions): RefObject<HTMLDivElement | null>;

package/dist/table/useInfiniteScrollSentinel.js

@@ -1,61 +1,17 @@
-import { useEffect, useRef } from "react";
+import { useEndReached } from "../hooks/useEndReached.js";
 //#region src/table/useInfiniteScrollSentinel.ts
 /**
-* @internal Shared by the table components; apps use InfiniteTable, VirtualizedInfiniteTable or
-* InfiniteSpreadsheet.
-*
-* The `onEndReached` sentinel: a 1px element after the table, observed with an
-* `IntersectionObserver` whose bottom margin is `marginPx` (`TABLE_END_REACHED_MARGIN_PX`). The root is the
-* scroll container when it overflows, otherwise the viewport, so a table in an unbounded parent
-* pages on page scroll. Armed only while enabled (not loading, no error), re-armed when the row
-* count changes, and calls `onEndReached` at most once per row count: an app with no next page
-* adds no rows, so it is not called again. Without `IntersectionObserver` it falls back to a
-* passive `scroll` listener. Nothing runs at module scope.
+* @internal Observes the zero-size sentinel and calls `onEndReached`; returns the sentinel's ref.
+* @deprecated Use `useEndReached` from `@galaxy-io/dls/hooks/useEndReached`.
 */
-/** @internal Observes the sentinel and calls `onEndReached`; returns the sentinel's ref. */
 function useInfiniteScrollSentinel({ scrollRef, onEndReached, isEnabled, rowCount, marginPx }) {
-	const sentinelRef = useRef(null);
-	const onEndReachedRef = useRef(onEndReached);
-	onEndReachedRef.current = onEndReached;
-	const calledForCountRef = useRef(null);
-	const hasHandler = onEndReached !== void 0;
-	useEffect(() => {
-		const scroll = scrollRef.current;
-		const sentinel = sentinelRef.current;
-		if (!hasHandler || !isEnabled || scroll === null || sentinel === null) return;
-		if (calledForCountRef.current === rowCount) return;
-		const reach = () => {
-			if (calledForCountRef.current === rowCount) return;
-			calledForCountRef.current = rowCount;
-			onEndReachedRef.current?.();
-		};
-		const isScrollRoot = scroll.scrollHeight > scroll.clientHeight;
-		if (typeof IntersectionObserver === "undefined") {
-			const target = isScrollRoot ? scroll : window;
-			const check = () => {
-				const bottom = isScrollRoot ? scroll.getBoundingClientRect().bottom : window.innerHeight;
-				if (sentinel.getBoundingClientRect().top - bottom < marginPx) reach();
-			};
-			check();
-			target.addEventListener("scroll", check, { passive: true });
-			return () => target.removeEventListener("scroll", check);
-		}
-		const observer = new IntersectionObserver((entries) => {
-			if (entries.some((entry) => entry.isIntersecting)) reach();
-		}, {
-			root: isScrollRoot ? scroll : null,
-			rootMargin: `0px 0px ${marginPx}px 0px`
-		});
-		observer.observe(sentinel);
-		return () => observer.disconnect();
-	}, [
+	return useEndReached({
 		scrollRef,
-		hasHandler,
+		onEndReached,
 		isEnabled,
-		rowCount,
+		itemCount: rowCount,
 		marginPx
-	]);
-	return sentinelRef;
+	});
 }
 //#endregion
 export { useInfiniteScrollSentinel };

package/dist/theme/tokens/dark.js

@@ -3,7 +3,7 @@ import { TYPE_SCALE } from "./scales.js";
 /**
 * Dark theme, resolved hex. Everything is Galaxy monochrome: `solid.primary` is `text.primary`
 * with `background.base` on it, `background.selected` is `text.primary` at 12% over
-* `background.base`.
+* `background.base` (Light uses 10%).
 *
 * Families (`<family>` below is any of the 17; the palette steps are `PALETTE`):
 * - `text`: brighter and more vivid than Tailwind's 400: OKLCH lightness ~0.03 above it, at the

package/dist/theme/tokens/light.js

@@ -2,8 +2,9 @@ import { TYPE_SCALE } from "./scales.js";
 //#region src/theme/tokens/light.ts
 /**
 * Light theme, resolved hex. Everything is Galaxy monochrome: `solid.primary` is `text.primary`
-* with `background.base` on it, `background.selected` is `text.primary` at 12% over
-* `background.base`.
+* with `background.base` on it, `background.selected` is `text.primary` at 10% over
+* `background.base` (Dark uses 12%: a lift off near-black reads quieter than a darkening of white,
+* and at 12% Light's selected row jumped well past `pressed`).
 *
 * Families (`<family>` below is any of the 17; the palette steps are `PALETTE`):
 * - `text`: the lightest OKLCH lightness, at the largest in-gamut chroma for the hue, that reaches
@@ -37,7 +38,7 @@ var LIGHT_THEME = {
 			tertiary: "#efeff0",
 			hovered: "#f5f5f5",
 			pressed: "#eeeeee",
-			selected: "#e2e2e2",
+			selected: "#e7e7e7",
 			disabled: "#f3f3f4",
 			success: "#ecfcf0",
 			warning: "#fff8eb",

package/dist/theme/tokens/types.d.ts

@@ -42,7 +42,7 @@ export type SolidColor = {
     /** The fill while pressed. */
     pressed: string;
 };
-/** Type-scale steps (Constitution III-A.1). */
+/** Type-scale steps (AGENTS.md "Type scale"). */
 export type TypeStep = "caption" | "body_sm" | "body_md" | "body_lg" | "heading_sm" | "heading_md" | "heading_lg" | "display_sm" | "display_lg";
 /** Serif (Cardo) is editorial only: it has no `caption`, `body_sm` or `body_md` step. */
 type SerifStep = Exclude<TypeStep, "caption" | "body_sm" | "body_md">;
@@ -50,7 +50,7 @@ type SerifStep = Exclude<TypeStep, "caption" | "body_sm" | "body_md">;
 export type FontScale<S extends TypeStep = TypeStep> = {
     /** CSS `font-family` stack. */
     family: string;
-    /** The only two weights (Constitution II.4). */
+    /** The only two weights (AGENTS.md "Type"). */
     weight: {
         regular: number;
         medium: number;
@@ -82,7 +82,7 @@ export type Theme = {
             hovered: string;
             /** A neutral row or control while pressed. */
             pressed: string;
-            /** The chosen item (menus, trees, tabs, nav, tables): `text.primary` at 12% over `base`. */
+            /** The chosen item (menus, trees, tabs, nav, tables): `text.primary` over `base`, 12% in Dark and 10% in Light. */
             selected: string;
             /** Disabled controls. */
             disabled: string;
@@ -161,16 +161,16 @@ export type Theme = {
 };
 /** Theme-independent scales, emitted once on `:root`. */
 export type Scales = {
-    /** Gap and padding (Constitution II.5). */
+    /** Gap and padding (AGENTS.md "Spacing"). */
     space: Record<Space, string>;
-    /** Corner radii (Constitution II.6). */
+    /** Corner radii (AGENTS.md "Radius"). */
     radius: {
         sm: string;
         md: string;
         lg: string;
         pill: string;
     };
-    /** Transition durations (Constitution II.7). */
+    /** Transition durations (AGENTS.md "Motion"). */
     duration: {
         fast: string;
         base: string;
@@ -183,7 +183,7 @@ export type Scales = {
         toast: number;
         tooltip: number;
     };
-    /** Control heights: the canonical size rungs (Constitution III-A.4). */
+    /** Control heights: the canonical size rungs (AGENTS.md "Control rungs"). */
     size: {
         control: {
             xSmall: string;

package/dist/timeline/Timeline.d.ts

@@ -19,7 +19,7 @@ export declare enum TimelineMarkerShape {
     /** No box: the dot or icon sits on the rail, 4px clear of the line above and below it. */
     NONE = "NONE"
 }
-/** Marker color of one item (Constitution V-A color set; the Timeline item is listed in that column). */
+/** Marker color of one item (AGENTS.md "Variant": color set). */
 export declare enum TimelineVariant {
     /** `text.primary` marker in a `border.primary` box. */
     PRIMARY = "PRIMARY",

package/dist/timeline/Timeline.js

@@ -1,4 +1,5 @@
 import Text, { TextSize, TextVariant } from "../text/Text.js";
+import { ROLE_COLOR_TO_CSS_MAP } from "../styles/internal/roleColor.js";
 import Beacon, { BeaconSize, BeaconVariant } from "../beacons/Beacon.js";
 import Icon, { IconVariant } from "../icons/Icon.js";
 /* empty css                   */
@@ -41,7 +42,7 @@ var TimelineMarkerShape = /* @__PURE__ */ function(TimelineMarkerShape) {
 	TimelineMarkerShape["NONE"] = "NONE";
 	return TimelineMarkerShape;
 }({});
-/** Marker color of one item (Constitution V-A color set; the Timeline item is listed in that column). */
+/** Marker color of one item (AGENTS.md "Variant": color set). */
 var TimelineVariant = /* @__PURE__ */ function(TimelineVariant) {
 	/** `text.primary` marker in a `border.primary` box. */
 	TimelineVariant["PRIMARY"] = "PRIMARY";
@@ -211,29 +212,10 @@ var TIMELINE_VARIANT_TO_CSS_MAP = {
 /**
 * Categorical `color` on the marker: `text.<family>`, which an icon marker (`IconVariant.INHERIT`)
 * takes, and `border.<family>` and the `background.<family>` fill on the box.
+* Reads the shared `--gx-role-*` variables that `ROLE_COLOR_TO_CSS_MAP` sets per family, so the
+* twenty families are written once (`styles/internal/roleColor`).
 */
-var TIMELINE_COLOR_TO_CSS_MAP = {
-	success: "gx-Timeline-success-s1khc5e9",
-	warning: "gx-Timeline-warning-wob0jun",
-	error: "gx-Timeline-error-ecpz10x",
-	red: "gx-Timeline-red-r1arc1uv",
-	orange: "gx-Timeline-orange-o1x7dvj6",
-	amber: "gx-Timeline-amber-a1fx1m3c",
-	yellow: "gx-Timeline-yellow-y1gy5gqm",
-	lime: "gx-Timeline-lime-ltyv4re",
-	green: "gx-Timeline-green-g1506u15",
-	emerald: "gx-Timeline-emerald-e2f8n55",
-	teal: "gx-Timeline-teal-t1bza0tc",
-	cyan: "gx-Timeline-cyan-c1vbt6lr",
-	sky: "gx-Timeline-sky-sjtm0e",
-	blue: "gx-Timeline-blue-bek3kdh",
-	indigo: "gx-Timeline-indigo-i13hn3pe",
-	violet: "gx-Timeline-violet-vdf3rdi",
-	purple: "gx-Timeline-purple-pjv99mk",
-	fuchsia: "gx-Timeline-fuchsia-f4wvpbo",
-	pink: "gx-Timeline-pink-p1qqjpue",
-	rose: "gx-Timeline-rose-r183jhdd"
-};
+var TIMELINE_COLOR_CSS = "gx-Timeline-TIMELINE_COLOR_CSS-t1khc5e9";
 /** A vertical list of events with dot or icon markers (boxed or bare) on a hairline rail. */
 var Timeline = forwardRef(function Timeline({ items, size = "MEDIUM", markerShape = "SQUARE", isFilled = false, className, style, ...rest }, ref) {
 	const textSize = TIMELINE_SIZE_TO_TEXT_SIZE_MAP[size];
@@ -252,7 +234,7 @@ var Timeline = forwardRef(function Timeline({ items, size = "MEDIUM", markerShap
 				children: [/* @__PURE__ */ jsxs(Rail, {
 					"aria-hidden": true,
 					children: [/* @__PURE__ */ jsx(Marker, {
-						className: cx(color !== void 0 ? TIMELINE_COLOR_TO_CSS_MAP[color] : TIMELINE_VARIANT_TO_CSS_MAP[variant], TIMELINE_MARKER_SHAPE_TO_CSS_MAP[markerShape], isFilled && markerShape !== "NONE" && FILLED_CSS),
+						className: cx(color !== void 0 ? cx(ROLE_COLOR_TO_CSS_MAP[color], TIMELINE_COLOR_CSS) : TIMELINE_VARIANT_TO_CSS_MAP[variant], TIMELINE_MARKER_SHAPE_TO_CSS_MAP[markerShape], isFilled && markerShape !== "NONE" && FILLED_CSS),
 						children: item.icon === void 0 ? /* @__PURE__ */ jsx(Beacon, {
 							size: TIMELINE_SIZE_TO_BEACON_SIZE_MAP[size],
 							...color !== void 0 ? { color } : { variant: TIMELINE_VARIANT_TO_BEACON_VARIANT_MAP[variant] },

package/dist/tokens.css

@@ -410,7 +410,7 @@
   --gx-color-background-tertiary: #efeff0;
   --gx-color-background-hovered: #f5f5f5;
   --gx-color-background-pressed: #eeeeee;
-  --gx-color-background-selected: #e2e2e2;
+  --gx-color-background-selected: #e7e7e7;
   --gx-color-background-disabled: #f3f3f4;
   --gx-color-background-success: #ecfcf0;
   --gx-color-background-warning: #fff8eb;

package/dist/utils/format.d.ts

@@ -1,19 +1,31 @@
 /**
- * Display formatting for numbers, byte sizes, durations, relative times and percentages
- * (Constitution VIII-A.2). Pure functions on `Intl`, no dependencies, safe at module scope and
- * under SSR. Number parts default to the `en-US` locale (not the runtime's) so server and client
- * render the same string.
+ * Display formatting for numbers, byte sizes, durations, relative times, dates and percentages
+ * (`docs/components.md`, Hooks and utils). Pure functions on `Intl`, no dependencies, safe at
+ * module scope and under SSR. Number parts default to the `en-US` locale (not the runtime's) so
+ * server and client render the same string.
  *
  * `precision` is always the maximum number of fraction digits; trailing zeros are dropped
  * (`formatPercent(0.5)` → `"50%"`, not `"50.0%"`). Non-finite input (`NaN`, `±Infinity`) is
  * returned as `formatNumber` prints it (`"NaN"`, `"∞"`, `"-∞"`).
+ *
+ * Every formatter also takes a `bigint` (a database count, a unix-millisecond timestamp), so call
+ * sites never wrap one in `Number()`. `formatNumber` prints a bigint exactly (`Intl` formats it
+ * natively); compact numbers, byte sizes, durations and relative times scale and round anyway, so
+ * they convert it to a number first (exact up to 2^53).
+ */
+/**
+ * What a missing value prints as: an em dash, in a table cell, a description list or a chart
+ * tooltip. One constant so every "no value" in an app reads the same. Render it in
+ * `TextVariant.TERTIARY`.
  */
+export declare const EMPTY_VALUE = "\u2014";
 /**
  * Formats a number with grouping. `1234` → `"1,234"`; `{ compact: true }` → `"1.2k"`
  * (suffixes `k M B T`). `precision` is the maximum fraction digits (default `1` when compact,
- * otherwise the `Intl` default of `3`). `locale` defaults to `"en-US"`.
+ * otherwise the `Intl` default of `3`). `locale` defaults to `"en-US"`. A `bigint` prints exactly
+ * (`12345678901234567890n` → `"12,345,678,901,234,567,890"`).
  */
-export declare function formatNumber(n: number, opts?: {
+export declare function formatNumber(input: number | bigint, opts?: {
     compact?: boolean;
     precision?: number;
     locale?: string;
@@ -23,7 +35,7 @@ export declare function formatNumber(n: number, opts?: {
  * `{ binary: true }` uses IEC units (`KiB`, base 1024). Whole bytes have no fraction digits.
  * `precision` is the maximum fraction digits (default `1`).
  */
-export declare function formatBytes(bytes: number, opts?: {
+export declare function formatBytes(input: number | bigint, opts?: {
     precision?: number;
     binary?: boolean;
 }): string;
@@ -34,21 +46,34 @@ export declare function formatBytes(bytes: number, opts?: {
  * finite); zero units are omitted and the
  * remainder is truncated. Zero is `"0s"` / `"0 seconds"`. `style` defaults to `"compact"`.
  */
-export declare function formatDuration(ms: number, opts?: {
+export declare function formatDuration(input: number | bigint, opts?: {
     style?: "compact" | "long";
     maxUnits?: number;
 }): string;
 /**
- * Formats a date relative to `now` (default: the current time, read at call time).
+ * Formats a date (or a unix-millisecond timestamp, `number` or `bigint`) relative to `now`
+ * (default: the current time, read at call time).
  * `{ style: "short" }` (default) → `"3m ago"`, `"in 2d"`, `"now"` (units `s m h d w mo y`);
  * `{ style: "long" }` → `Intl.RelativeTimeFormat` with `numeric: "auto"` (`"3 minutes ago"`,
  * `"in 2 days"`, `"yesterday"`, `"now"`). Uses the largest unit that fits, truncated;
  * months are 30 days, years 365 days. Under 1 second is `"now"`.
  */
-export declare function formatRelativeTime(date: Date | number, opts?: {
+export declare function formatRelativeTime(date: Date | number | bigint, opts?: {
     now?: Date;
     style?: "short" | "long";
 }): string;
+/**
+ * Formats a date (or a unix-millisecond timestamp, `number` or `bigint`). `{ style: "date" }`
+ * (default) → `"Oct 3, 2026"`, the DateInput and table default; `{ style: "dateTime" }` →
+ * `"Oct 10, 3:04:05 PM"`, an event in the recent past. `locale` defaults to `"en-US"`;
+ * `timeZone` defaults to the runtime's (pass `"UTC"` when server and client must agree). An
+ * invalid date is returned as `formatNumber` prints `NaN`.
+ */
+export declare function formatDate(date: Date | number | bigint, opts?: {
+    style?: "date" | "dateTime";
+    locale?: string;
+    timeZone?: string;
+}): string;
 /**
  * Formats a ratio as a percentage. `0.1234` → `"12.3%"`. `precision` is the maximum fraction
  * digits (default `1`).

package/dist/utils/format.js

@@ -1,15 +1,26 @@
 //#region src/utils/format.ts
 /**
-* Display formatting for numbers, byte sizes, durations, relative times and percentages
-* (Constitution VIII-A.2). Pure functions on `Intl`, no dependencies, safe at module scope and
-* under SSR. Number parts default to the `en-US` locale (not the runtime's) so server and client
-* render the same string.
+* Display formatting for numbers, byte sizes, durations, relative times, dates and percentages
+* (`docs/components.md`, Hooks and utils). Pure functions on `Intl`, no dependencies, safe at
+* module scope and under SSR. Number parts default to the `en-US` locale (not the runtime's) so
+* server and client render the same string.
 *
 * `precision` is always the maximum number of fraction digits; trailing zeros are dropped
 * (`formatPercent(0.5)` → `"50%"`, not `"50.0%"`). Non-finite input (`NaN`, `±Infinity`) is
 * returned as `formatNumber` prints it (`"NaN"`, `"∞"`, `"-∞"`).
+*
+* Every formatter also takes a `bigint` (a database count, a unix-millisecond timestamp), so call
+* sites never wrap one in `Number()`. `formatNumber` prints a bigint exactly (`Intl` formats it
+* natively); compact numbers, byte sizes, durations and relative times scale and round anyway, so
+* they convert it to a number first (exact up to 2^53).
 */
 var DEFAULT_LOCALE = "en-US";
+/**
+* What a missing value prints as: an em dash, in a table cell, a description list or a chart
+* tooltip. One constant so every "no value" in an app reads the same. Render it in
+* `TextVariant.TERTIARY`.
+*/
+var EMPTY_VALUE = "—";
 var COMPACT_SUFFIXES = [
 	"",
 	"k",
@@ -111,6 +122,8 @@ var RELATIVE_UNITS = [
 		intl: "second"
 	}
 ];
+/** A bigint as a number, for the formatters that scale or round (exact up to 2^53). */
+var toNumber = (value) => typeof value === "bigint" ? Number(value) : value;
 var decimal = (value, maxFractionDigits, locale = DEFAULT_LOCALE) => new Intl.NumberFormat(locale, {
 	signDisplay: "negative",
 	...maxFractionDigits === void 0 ? {} : { maximumFractionDigits: maxFractionDigits }
@@ -136,11 +149,13 @@ function scale(abs, base, steps, precisionAt) {
 /**
 * Formats a number with grouping. `1234` → `"1,234"`; `{ compact: true }` → `"1.2k"`
 * (suffixes `k M B T`). `precision` is the maximum fraction digits (default `1` when compact,
-* otherwise the `Intl` default of `3`). `locale` defaults to `"en-US"`.
+* otherwise the `Intl` default of `3`). `locale` defaults to `"en-US"`. A `bigint` prints exactly
+* (`12345678901234567890n` → `"12,345,678,901,234,567,890"`).
 */
-function formatNumber(n, opts) {
+function formatNumber(input, opts) {
 	const locale = opts?.locale ?? DEFAULT_LOCALE;
-	if (!opts?.compact || !Number.isFinite(n)) return decimal(n, opts?.precision, locale);
+	if (!opts?.compact || typeof input === "number" && !Number.isFinite(input)) return decimal(input, opts?.precision, locale);
+	const n = toNumber(input);
 	const precision = opts.precision ?? 1;
 	const [value, step] = scale(Math.abs(n), 1e3, COMPACT_SUFFIXES.length, () => precision);
 	return `${n < 0 && decimal(value, precision, locale) !== "0" ? "-" : ""}${decimal(value, precision, locale)}${COMPACT_SUFFIXES[step] ?? ""}`;
@@ -150,7 +165,8 @@ function formatNumber(n, opts) {
 * `{ binary: true }` uses IEC units (`KiB`, base 1024). Whole bytes have no fraction digits.
 * `precision` is the maximum fraction digits (default `1`).
 */
-function formatBytes(bytes, opts) {
+function formatBytes(input, opts) {
+	const bytes = toNumber(input);
 	if (!Number.isFinite(bytes)) return formatNumber(bytes);
 	const precision = opts?.precision ?? 1;
 	const units = opts?.binary ? BINARY_BYTE_UNITS : DECIMAL_BYTE_UNITS;
@@ -166,7 +182,8 @@ function formatBytes(bytes, opts) {
 * finite); zero units are omitted and the
 * remainder is truncated. Zero is `"0s"` / `"0 seconds"`. `style` defaults to `"compact"`.
 */
-function formatDuration(ms, opts) {
+function formatDuration(input, opts) {
+	const ms = toNumber(input);
 	if (!Number.isFinite(ms)) return formatNumber(ms);
 	const isLong = opts?.style === "long";
 	const requestedUnits = opts?.maxUnits ?? 2;
@@ -186,7 +203,8 @@ function formatDuration(ms, opts) {
 	return `${ms < 0 ? "-" : ""}${parts.join(" ")}`;
 }
 /**
-* Formats a date relative to `now` (default: the current time, read at call time).
+* Formats a date (or a unix-millisecond timestamp, `number` or `bigint`) relative to `now`
+* (default: the current time, read at call time).
 * `{ style: "short" }` (default) → `"3m ago"`, `"in 2d"`, `"now"` (units `s m h d w mo y`);
 * `{ style: "long" }` → `Intl.RelativeTimeFormat` with `numeric: "auto"` (`"3 minutes ago"`,
 * `"in 2 days"`, `"yesterday"`, `"now"`). Uses the largest unit that fits, truncated;
@@ -194,7 +212,7 @@ function formatDuration(ms, opts) {
 */
 function formatRelativeTime(date, opts) {
 	const now = opts?.now ?? /* @__PURE__ */ new Date();
-	const diff = (typeof date === "number" ? date : date.getTime()) - now.getTime();
+	const diff = (date instanceof Date ? date.getTime() : toNumber(date)) - now.getTime();
 	if (!Number.isFinite(diff)) return formatNumber(diff);
 	const isLong = opts?.style === "long";
 	const unit = RELATIVE_UNITS.find((candidate) => Math.abs(diff) >= candidate.ms);
@@ -204,6 +222,36 @@ function formatRelativeTime(date, opts) {
 	const amount = `${decimal(count, 0)}${unit.short}`;
 	return diff < 0 ? `${amount} ago` : `in ${amount}`;
 }
+/** The `Intl` fields of each `formatDate` style. */
+var DATE_STYLE_TO_FORMAT_OPTIONS_MAP = {
+	date: {
+		month: "short",
+		day: "numeric",
+		year: "numeric"
+	},
+	dateTime: {
+		month: "short",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		second: "2-digit"
+	}
+};
+/**
+* Formats a date (or a unix-millisecond timestamp, `number` or `bigint`). `{ style: "date" }`
+* (default) → `"Oct 3, 2026"`, the DateInput and table default; `{ style: "dateTime" }` →
+* `"Oct 10, 3:04:05 PM"`, an event in the recent past. `locale` defaults to `"en-US"`;
+* `timeZone` defaults to the runtime's (pass `"UTC"` when server and client must agree). An
+* invalid date is returned as `formatNumber` prints `NaN`.
+*/
+function formatDate(date, opts) {
+	const time = date instanceof Date ? date.getTime() : toNumber(date);
+	if (!Number.isFinite(time)) return formatNumber(time);
+	return new Intl.DateTimeFormat(opts?.locale ?? DEFAULT_LOCALE, {
+		...DATE_STYLE_TO_FORMAT_OPTIONS_MAP[opts?.style ?? "date"],
+		...opts?.timeZone === void 0 ? {} : { timeZone: opts.timeZone }
+	}).format(time);
+}
 /**
 * Formats a ratio as a percentage. `0.1234` → `"12.3%"`. `precision` is the maximum fraction
 * digits (default `1`).
@@ -217,4 +265,4 @@ function formatPercent(ratio, opts) {
 	}).format(ratio);
 }
 //#endregion
-export { formatBytes, formatDuration, formatNumber, formatPercent, formatRelativeTime };
+export { EMPTY_VALUE, formatBytes, formatDate, formatDuration, formatNumber, formatPercent, formatRelativeTime };

package/dist/utils/search.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Text search for lists that filter as the user types: CommandPalette, Menu, SelectInput,
+ * MultiSelectInput and JsonViewer use it, so one term matches the same rows everywhere. The rule:
+ * trim the term, lower-case it with `toLocaleLowerCase`, and match when any field contains it (an
+ * empty term matches everything). Pure functions, safe at module scope and under SSR.
+ */
+/** The term as it is compared: trimmed and lower-cased (`"  Orders "` → `"orders"`). */
+export declare function normalizeSearchTerm(term: string): string;
+/**
+ * Whether any field contains the term, case-insensitively. An empty (or blank) term matches;
+ * `null` and `undefined` fields are skipped, so optional fields pass straight through:
+ * `isSearchMatch(term, item.label, item.description, ...item.keywords)`. The term may already be
+ * normalized (normalizing is idempotent).
+ */
+export declare function isSearchMatch(term: string, ...fields: readonly (string | null | undefined)[]): boolean;

package/dist/utils/search.js

@@ -0,0 +1,24 @@
+//#region src/utils/search.ts
+/**
+* Text search for lists that filter as the user types: CommandPalette, Menu, SelectInput,
+* MultiSelectInput and JsonViewer use it, so one term matches the same rows everywhere. The rule:
+* trim the term, lower-case it with `toLocaleLowerCase`, and match when any field contains it (an
+* empty term matches everything). Pure functions, safe at module scope and under SSR.
+*/
+/** The term as it is compared: trimmed and lower-cased (`"  Orders "` → `"orders"`). */
+function normalizeSearchTerm(term) {
+	return term.trim().toLocaleLowerCase();
+}
+/**
+* Whether any field contains the term, case-insensitively. An empty (or blank) term matches;
+* `null` and `undefined` fields are skipped, so optional fields pass straight through:
+* `isSearchMatch(term, item.label, item.description, ...item.keywords)`. The term may already be
+* normalized (normalizing is idempotent).
+*/
+function isSearchMatch(term, ...fields) {
+	const normalized = normalizeSearchTerm(term);
+	if (normalized === "") return true;
+	return fields.some((field) => field?.toLocaleLowerCase().includes(normalized) ?? false);
+}
+//#endregion
+export { isSearchMatch, normalizeSearchTerm };

package/dist/vite/index.d.ts

@@ -1,4 +1,5 @@
 import { type Plugin } from "@wyw-in-js/vite";
+import { GalaxyTheme } from "../theme/enums.js";
 /** Options for {@link galaxyDls}. */
 export type GalaxyDlsOptions = {
     /**
@@ -7,10 +8,23 @@ export type GalaxyDlsOptions = {
      * @default "gx"
      */
     prefix?: string;
+    /**
+     * The theme the page boots in before `GalaxyProvider` mounts. Pass the provider's own `theme`; a
+     * choice stored under `storageKey` still wins, as it does in the provider.
+     * @default GalaxyTheme.SYSTEM
+     */
+    theme?: GalaxyTheme;
+    /**
+     * Where the provider stores the user's choice; the boot script reads it and never writes it.
+     * Pass the provider's `storageKey` if you changed it.
+     * @default "galaxy:theme"
+     */
+    storageKey?: string;
 };
 /**
  * Returns the configured `@wyw-in-js/vite` plugin: the DLS Babel presets (React automatic
- * runtime + TypeScript), `include`/`exclude`, React `importOverrides`, and the DLS
- * `classNameSlug` (`gx-<Component>-<Part>-<hash>`) with `gx` replaced by `prefix`.
+ * runtime + TypeScript), `include`/`exclude`, and the DLS's own class-name config (the slug
+ * `gx-<Component>-<Part>-<hash>` with `gx` replaced by `prefix`, no vendor prefixes, React
+ * `importOverrides`), so app CSS is named and emitted like DLS CSS.
  */
 export declare function galaxyDls(options?: GalaxyDlsOptions): Plugin;

package/dist/vite/index.js

@@ -1,3 +1,6 @@
+import { GalaxyTheme } from "../theme/enums.js";
+import { BOOT_THEMES, DEFAULT_THEME_STORAGE_KEY, themeBackgroundStyle, themeBootScript } from "./internal/themeBoot.js";
+import { sharedWywOptions } from "./internal/wywOptions.js";
 import { createRequire } from "node:module";
 import wyw from "@wyw-in-js/vite";
 //#region src/vite/index.ts
@@ -12,41 +15,47 @@ import wyw from "@wyw-in-js/vite";
 *
 * The DLS itself ships pre-extracted CSS (`@galaxy-io/dls/styles.css`); this preset only
 * compiles the app's own `styled` / `css` code, which reads DLS tokens through `t`.
+*
+* It also boots the theme in `index.html`: one inline script sets `data-gx-theme` on `<html>`
+* before the first paint (the stored choice, else `theme`, resolving `SYSTEM` from the OS), and one
+* `<style>` paints the canvas per theme, so a page never flashes the wrong theme before
+* `GalaxyProvider` mounts. Pass the same `theme` and `storageKey` as the app's provider. A strict
+* Content Security Policy needs the script's hash.
 */
-/** The DLS class prefix; also the default app prefix. */
-var DEFAULT_PREFIX = "gx";
 /** A valid start for a CSS class name: a letter, then letters, digits or `-`. */
 var PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9-]*$/;
-/** The styled root is named `Root`; its class drops the part segment. */
-var ROOT_PART = "Root";
 /** Files the plugin compiles. The DLS (and every other package) ships already compiled. */
 var INCLUDE = ["**/*.{js,jsx,ts,tsx}"];
 var EXCLUDE = ["**/node_modules/**"];
 /**
-* React is reached while wyw evaluates `styled` components at build time; loading it as-is is
-* expected, so the "unknown import reached during eval" warning is silenced for it.
-*/
-var IMPORT_OVERRIDES = {
-	react: { unknown: "allow" },
-	"react/jsx-runtime": { unknown: "allow" },
-	"react/jsx-dev-runtime": { unknown: "allow" }
-};
-/**
 * Returns the configured `@wyw-in-js/vite` plugin: the DLS Babel presets (React automatic
-* runtime + TypeScript), `include`/`exclude`, React `importOverrides`, and the DLS
-* `classNameSlug` (`gx-<Component>-<Part>-<hash>`) with `gx` replaced by `prefix`.
+* runtime + TypeScript), `include`/`exclude`, and the DLS's own class-name config (the slug
+* `gx-<Component>-<Part>-<hash>` with `gx` replaced by `prefix`, no vendor prefixes, React
+* `importOverrides`), so app CSS is named and emitted like DLS CSS.
 */
 function galaxyDls(options = {}) {
-	const { prefix = DEFAULT_PREFIX } = options;
+	const { prefix = "gx", theme = GalaxyTheme.SYSTEM, storageKey = DEFAULT_THEME_STORAGE_KEY } = options;
 	if (!PREFIX_PATTERN.test(prefix)) throw new Error(`[@galaxy-io/dls/vite] prefix "${prefix}" is not a valid class-name start: use letters, digits and "-", starting with a letter.`);
+	if (!BOOT_THEMES.includes(theme)) throw new Error(`[@galaxy-io/dls/vite] theme "${theme}" is not a GalaxyTheme: use GalaxyTheme.SYSTEM, DARK or LIGHT.`);
 	const require = createRequire(import.meta.url);
-	return wyw({
+	const plugin = wyw({
 		include: INCLUDE,
 		exclude: EXCLUDE,
 		babelOptions: { presets: [[require.resolve("@babel/preset-react"), { runtime: "automatic" }], require.resolve("@babel/preset-typescript")] },
-		importOverrides: IMPORT_OVERRIDES,
-		classNameSlug: (hash, title, { name }) => `${prefix}-${name}${title === ROOT_PART ? "" : `-${title}`}-${hash}`
+		...sharedWywOptions(prefix)
 	});
+	const bootScript = themeBootScript(theme, storageKey);
+	const backgroundStyle = themeBackgroundStyle();
+	plugin.transformIndexHtml = () => [{
+		tag: "script",
+		children: bootScript,
+		injectTo: "head-prepend"
+	}, {
+		tag: "style",
+		children: backgroundStyle,
+		injectTo: "head-prepend"
+	}];
+	return plugin;
 }
 //#endregion
 export { galaxyDls };