@enigmax/primitives 0.11.1 → 0.13.0

package/src/core/notifications.ts

@@ -0,0 +1,250 @@
+/**
+ * Notification queue: ordering, timers, dedupe and pause. No rendering, no styles.
+ *
+ * The timer is the part that is always wrong when hand-rolled. A dismiss timer
+ * that keeps counting while the tab is hidden fires the moment the visitor comes
+ * back and they never see the message, so the remaining time is held, not run.
+ */
+
+export type NotificationTone = "info" | "success" | "warning" | "error" | "loading";
+
+/** One button on a notification. Anything more belongs on the page, not in a toast. */
+export interface NotificationAction {
+    label: string;
+    onSelect: () => void;
+    /** Dismiss once it has been pressed. On by default. */
+    dismiss?: boolean;
+}
+
+export interface NotificationInput {
+    /** Reuses the slot of a live notification with the same key instead of stacking. */
+    key?: string;
+    title: string;
+    body?: string;
+    tone?: NotificationTone;
+    /** ms before it dismisses itself. 0 or Infinity keeps it until dismissed. */
+    duration?: number;
+    action?: NotificationAction;
+    /** Arbitrary payload for the renderer: an href, an icon name. */
+    data?: unknown;
+}
+
+export interface Notification extends Required<Omit<NotificationInput, "body" | "data" | "key" | "action">> {
+    id: string;
+    key?: string;
+    body?: string;
+    action?: NotificationAction;
+    data?: unknown;
+    createdAt: number;
+}
+
+/** What `promise()` shows at each stage. A function receives the resolved value or the error. */
+export interface PromiseMessages<T> {
+    loading: string | NotificationInput;
+    success: string | ((value: T) => string | NotificationInput);
+    error: string | ((error: unknown) => string | NotificationInput);
+}
+
+export interface NotificationsOptions {
+    /** Live notifications kept at once. The oldest dismissable one makes room. */
+    max?: number;
+    /** Default ms before self-dismissal. */
+    duration?: number;
+    /** Errors default to staying until dismissed. */
+    stickyTones?: NotificationTone[];
+}
+
+export interface Notifications {
+    readonly items: readonly Notification[];
+    notify(input: NotificationInput): string;
+    /** Change a live notification in place, keeping its slot and restarting its timer. */
+    update(id: string, patch: Partial<NotificationInput>): void;
+    /**
+     * One notification that follows an async operation from loading to its outcome, in the
+     * same slot. The alternative is three toasts stacking up for one action.
+     */
+    promise<T>(work: Promise<T>, messages: PromiseMessages<T>): Promise<T>;
+    dismiss(id: string): void;
+    dismissAll(): void;
+    /** Hold every timer, e.g. while a pointer rests on the stack. */
+    pause(): void;
+    resume(): void;
+    subscribe(listener: (items: readonly Notification[]) => void): () => void;
+    destroy(): void;
+}
+
+const DEFAULT_MAX = 4;
+const DEFAULT_DURATION = 5000;
+
+export function createNotifications(options: NotificationsOptions = {}): Notifications {
+    // Null outside a browser: the queue has to survive a server render untouched.
+    const view = typeof document === "undefined" ? null : document;
+    const max = options.max ?? DEFAULT_MAX;
+    const defaultDuration = options.duration ?? DEFAULT_DURATION;
+    // `loading` is sticky by definition - it ends when the work does, not on a timer.
+    const sticky = new Set<NotificationTone>([...(options.stickyTones ?? ["error"]), "loading"]);
+
+    let items: Notification[] = [];
+    let paused = false;
+    let sequence = 0;
+    const listeners = new Set<(items: readonly Notification[]) => void>();
+    const timers = new Map<string, { handle: ReturnType<typeof setTimeout> | null; remaining: number; startedAt: number; }>();
+
+    function emit(): void {
+        const snapshot = Object.freeze([...items]);
+        for (const listener of listeners) listener(snapshot);
+    }
+
+    function clearTimer(id: string): void {
+        const timer = timers.get(id);
+        if (timer?.handle) clearTimeout(timer.handle);
+        timers.delete(id);
+    }
+
+    function startTimer(id: string, remaining: number): void {
+        if (!Number.isFinite(remaining) || remaining <= 0) return;
+        const handle = paused ? null : setTimeout(() => dismiss(id), remaining);
+        timers.set(id, { handle, remaining, startedAt: Date.now() });
+    }
+
+    function dismiss(id: string): void {
+        const next = items.filter(item => item.id !== id);
+        if (next.length === items.length) return;
+        items = next;
+        clearTimer(id);
+        emit();
+    }
+
+    function notify(input: NotificationInput): string {
+        const tone = input.tone ?? "info";
+        const duration = input.duration ?? (sticky.has(tone) ? Infinity : defaultDuration);
+
+        // A repeated key replaces in place, so a retry loop does not build a wall.
+        const existing = input.key ? items.find(item => item.key === input.key) : undefined;
+        const id = existing?.id ?? `n${++sequence}`;
+        const notification: Notification = {
+            id,
+            key: input.key,
+            title: input.title,
+            body: input.body,
+            tone,
+            duration,
+            action: input.action,
+            data: input.data,
+            createdAt: Date.now()
+        };
+
+        items = existing
+            ? items.map(item => (item.id === id ? notification : item))
+            : [...items, notification];
+
+        if (items.length > max) {
+            // Never silently drop something that has no timer of its own.
+            const evictable = items.find(item => Number.isFinite(item.duration) && item.id !== id);
+            if (evictable) {
+                items = items.filter(item => item.id !== evictable.id);
+                clearTimer(evictable.id);
+            } else {
+                items = items.slice(items.length - max);
+            }
+        }
+
+        clearTimer(id);
+        startTimer(id, duration);
+        emit();
+        return id;
+    }
+
+    const onVisibility = (): void => {
+        if (!view) return;
+        // A hidden tab must not burn a notification nobody could read.
+        if (view.hidden) instance.pause();
+        else instance.resume();
+    };
+
+    function update(id: string, patch: Partial<NotificationInput>): void {
+        const current = items.find(item => item.id === id);
+        if (!current) return;
+
+        // In place rather than through notify(): notify dedupes by KEY, and a notification
+        // raised without one would be appended as a second toast instead of replaced.
+        const tone = patch.tone ?? current.tone;
+        // A patch that changes the tone takes that tone's default duration unless it names
+        // one, so a loading toast turning into a success stops being sticky.
+        const duration = patch.duration ?? (patch.tone ? (sticky.has(tone) ? Infinity : defaultDuration) : current.duration);
+
+        items = items.map(item => (item.id === id ? { ...current, ...patch, tone, duration } : item));
+        clearTimer(id);
+        startTimer(id, duration);
+        emit();
+    }
+
+    function resolveMessage<T>(message: string | NotificationInput | ((value: T) => string | NotificationInput), value: T): NotificationInput {
+        const resolved = typeof message === "function" ? message(value) : message;
+        return typeof resolved === "string" ? { title: resolved } : resolved;
+    }
+
+    async function promise<T>(work: Promise<T>, messages: PromiseMessages<T>): Promise<T> {
+        const start = typeof messages.loading === "string" ? { title: messages.loading } : messages.loading;
+        // A key ties every stage to the same slot, so one action is one toast.
+        const key = start.key ?? `p${++sequence}`;
+        notify({ ...start, key, tone: "loading" });
+        try {
+            const value = await work;
+            notify({ ...resolveMessage(messages.success, value), key, tone: "success" });
+            return value;
+        } catch (error) {
+            notify({ ...resolveMessage(messages.error, error), key, tone: "error" });
+            // Rethrown: swallowing it here would turn a failed call into a silent success
+            // for everything downstream of the await.
+            throw error;
+        }
+    }
+
+    const instance: Notifications = {
+        get items() { return Object.freeze([...items]); },
+        notify,
+        update,
+        promise,
+        dismiss,
+        dismissAll(): void {
+            for (const item of items) clearTimer(item.id);
+            items = [];
+            emit();
+        },
+        pause(): void {
+            if (paused) return;
+            paused = true;
+            for (const [id, timer] of timers) {
+                if (!timer.handle) continue;
+                clearTimeout(timer.handle);
+                timers.set(id, {
+                    handle: null,
+                    remaining: Math.max(timer.remaining - (Date.now() - timer.startedAt), 0),
+                    startedAt: Date.now()
+                });
+            }
+        },
+        resume(): void {
+            if (!paused) return;
+            paused = false;
+            for (const [id, timer] of [...timers]) {
+                clearTimer(id);
+                startTimer(id, timer.remaining);
+            }
+        },
+        subscribe(listener): () => void {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        destroy(): void {
+            for (const item of items) clearTimer(item.id);
+            items = [];
+            listeners.clear();
+            view?.removeEventListener("visibilitychange", onVisibility);
+        }
+    };
+
+    view?.addEventListener("visibilitychange", onVisibility);
+    return instance;
+}

package/src/core/relative-time.ts

@@ -0,0 +1,213 @@
+/**
+ * Relative time: "3 hours ago", and everything that has to be right around it.
+ *
+ * The rendering itself is `<relative-time>` (@github/relative-time-element), which already
+ * owns the hard parts - Intl.RelativeTimeFormat per locale, and re-rendering on a schedule
+ * that gets slower as the date gets older. What is here is the part every wrapper
+ * re-implements and usually gets wrong: parsing a timestamp that does not declare its zone,
+ * knowing when the date has aged past the relative threshold, and producing an absolute
+ * label to show while the element is still loading, or forever if scripting is off.
+ *
+ * Nothing in this file touches the DOM, so it renders on a server.
+ */
+
+/** How the element should phrase it. `auto` is relative until the threshold, then a date. */
+export type RelativeTimeFormat = "auto" | "relative" | "duration" | "datetime" | "micro" | "elapsed";
+export type RelativeTimeTense = "auto" | "past" | "future";
+export type RelativeTimePrecision = "year" | "month" | "day" | "hour" | "minute" | "second";
+export type RelativeTimeStyle = "long" | "short" | "narrow";
+export type NumericStyle = "numeric" | "2-digit";
+
+export interface RelativeTimeOptions {
+    format?: RelativeTimeFormat;
+    tense?: RelativeTimeTense;
+    precision?: RelativeTimePrecision;
+    /** ISO 8601 duration. Past this age `auto` stops being relative. Default `P30D`. */
+    threshold?: string;
+    /** Word before an absolute date, e.g. "on 5 May". Empty string removes it. */
+    prefix?: string;
+    formatStyle?: RelativeTimeStyle;
+    /**
+     * BCP 47 tag. Left undefined the element reads the closest `lang` in the document,
+     * which is what a translated page wants - hardcoding one is how a Spanish page ends
+     * up saying "3 hours ago".
+     */
+    locale?: string;
+    /** IANA zone for the absolute rendering. Undefined means the reader's own. */
+    timeZone?: string;
+    second?: NumericStyle;
+    minute?: NumericStyle;
+    hour?: NumericStyle;
+    weekday?: RelativeTimeStyle;
+    day?: NumericStyle;
+    month?: NumericStyle | "short" | "long" | "narrow";
+    year?: NumericStyle;
+    timeZoneName?: "long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+    /** Drop the exact timestamp the element otherwise puts in `title`. */
+    noTitle?: boolean;
+    /**
+     * Once the date is older than `threshold`, render it as digits (05/05/2026) instead of
+     * a prefixed month name. The cutoff is the threshold itself, not a guess at it.
+     */
+    numericBeyondThreshold?: boolean;
+}
+
+/** Everything derived from a date, in one pass, for whichever adapter is rendering it. */
+export interface RelativeTimeView {
+    /** Null when the input could not be parsed - nothing else here is meaningful then. */
+    date: Date | null;
+    /** `datetime` attribute value: always UTC, always ISO. */
+    iso: string;
+    /** Absolute text. Shown until the element upgrades, and forever without scripting. */
+    label: string;
+    /** Full timestamp for `title` / `aria-label`. */
+    exact: string;
+    /** The date is older (or further ahead) than `threshold`. */
+    beyondThreshold: boolean;
+    /** Render `label` in a plain `<time>` and skip the element entirely. */
+    absoluteOnly: boolean;
+}
+
+const ZONED = /([zZ]|[+-]\d{2}:?\d{2})$/;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const HAS_TIME = /\d{2}:\d{2}/;
+const DURATION = /^([+-])?P(?:(\d+(?:\.\d+)?)Y)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+
+const SECOND = 1000, MINUTE = 60 * SECOND, HOUR = 60 * MINUTE, DAY = 24 * HOUR;
+/** Calendar-free approximations, matching what the element uses to compare an age. */
+const WEEK = 7 * DAY, MONTH = 30 * DAY, YEAR = 365 * DAY;
+
+/**
+ * A timestamp with no zone is UTC.
+ *
+ * This is the single most common defect in a date column: `2026-08-13 22:41:00` comes back
+ * from the database with no offset, `new Date()` reads it as LOCAL time, and every reader
+ * east or west of the server sees a time that is hours out - silently, because the wrong
+ * time is still a valid one.
+ *
+ * A date with no clock is left exactly as it is. The spec already reads a bare `YYYY-MM-DD`
+ * as UTC, so there is nothing to add - and `YYYY-MM-DDZ` is not in the spec's grammar at
+ * all, which drops it into each engine's own legacy parser. That is a portability coin
+ * flip on a value that was already correct.
+ */
+export function ensureZone(text: string): string {
+    const trimmed = text.trim();
+    if (!trimmed || DATE_ONLY.test(trimmed) || ZONED.test(trimmed)) return trimmed;
+    const iso = trimmed.replace(" ", "T");
+    return HAS_TIME.test(iso) ? `${iso}Z` : iso;
+}
+
+/** Parse anything a date column or an API hands over. Null rather than an Invalid Date. */
+export function normalizeDate(value: string | number | Date | null | undefined): Date | null {
+    if (value == null) return null;
+    if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+    // A bare number is epoch milliseconds; seconds would be 1970 and obviously wrong.
+    if (typeof value === "number") return Number.isFinite(value) ? new Date(value) : null;
+    const date = new Date(ensureZone(value));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * ISO 8601 duration to milliseconds, for comparing an age against `threshold`.
+ *
+ * Years and months are approximated the way the element approximates them, because the
+ * threshold is a rough "old enough to stop counting", not an anniversary.
+ */
+export function parseDuration(value: string): number {
+    const match = DURATION.exec(value.trim());
+    if (!match) return 0;
+    const [, sign, years, months, weeks, days, hours, minutes, seconds] = match;
+    const n = (part: string | undefined): number => (part ? Number(part) : 0);
+    const total =
+        n(years) * YEAR + n(months) * MONTH + n(weeks) * WEEK + n(days) * DAY +
+        n(hours) * HOUR + n(minutes) * MINUTE + n(seconds) * SECOND;
+    return sign === "-" ? -total : total;
+}
+
+function dateTimeOptions(options: RelativeTimeOptions): Intl.DateTimeFormatOptions {
+    const { second, minute, hour, weekday, day, month, year, timeZone, timeZoneName } = options;
+    const parts: Intl.DateTimeFormatOptions = { timeZone, timeZoneName, second, minute, hour, weekday, day, month, year };
+    // An explicit `undefined` is not the same as an absent key to Intl in every engine.
+    for (const key of Object.keys(parts) as (keyof Intl.DateTimeFormatOptions)[]) {
+        if (parts[key] === undefined) delete parts[key];
+    }
+    return parts;
+}
+
+function format(date: Date, locale: string | undefined, options: Intl.DateTimeFormatOptions): string {
+    try {
+        return new Intl.DateTimeFormat(locale, options).format(date);
+    } catch {
+        // An invalid locale tag or an unsupported time zone throws rather than degrading.
+        return date.toISOString();
+    }
+}
+
+/**
+ * Everything an adapter needs to render one date.
+ *
+ * `now` is a parameter so a test can pin it, and so a server render can pass the same
+ * instant it used elsewhere on the page.
+ */
+export function relativeTimeView(value: string | number | Date | null | undefined, options: RelativeTimeOptions = {}, now: Date = new Date()): RelativeTimeView {
+    const date = normalizeDate(value);
+    if (!date) return { date: null, iso: "", label: "", exact: "", beyondThreshold: false, absoluteOnly: false };
+
+    const { locale, threshold = "P30D", prefix = "on", numericBeyondThreshold = false } = options;
+    const age = Math.abs(date.getTime() - now.getTime());
+    const beyondThreshold = age > parseDuration(threshold);
+
+    // Beyond the threshold the element itself would render a date, so rendering it here
+    // costs nothing and skips a custom element that has no work left to do.
+    const absoluteOnly = numericBeyondThreshold && beyondThreshold;
+    const parts = absoluteOnly
+        ? { day: "numeric" as const, month: "numeric" as const, year: "numeric" as const, timeZone: options.timeZone }
+        : { day: "numeric" as const, month: "short" as const, year: "numeric" as const, ...dateTimeOptions(options) };
+
+    const label = format(date, locale, parts);
+    return {
+        date,
+        iso: date.toISOString(),
+        label: !absoluteOnly && prefix ? `${prefix} ${label}` : label,
+        exact: format(date, locale, { dateStyle: "full", timeStyle: "long", timeZone: options.timeZone }),
+        beyondThreshold,
+        absoluteOnly
+    };
+}
+
+/**
+ * The element's attributes, kebab-cased, with anything undefined left out.
+ *
+ * Written as attributes rather than properties because that is the half of a custom
+ * element's API that works before it is defined - the markup is already correct when the
+ * definition arrives late, or never.
+ */
+export function relativeTimeAttributes(view: RelativeTimeView, options: RelativeTimeOptions = {}): Record<string, string> {
+    const attributes: Record<string, string | undefined> = {
+        datetime: view.iso,
+        format: options.format,
+        tense: options.tense,
+        precision: options.precision,
+        threshold: options.threshold,
+        prefix: options.prefix,
+        "format-style": options.formatStyle,
+        second: options.second,
+        minute: options.minute,
+        hour: options.hour,
+        weekday: options.weekday,
+        day: options.day,
+        month: options.month,
+        year: options.year,
+        lang: options.locale,
+        "time-zone": options.timeZone,
+        "time-zone-name": options.timeZoneName,
+        // Boolean attributes are read by presence: "false" would still be true.
+        "no-title": options.noTitle ? "" : undefined
+    };
+
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value !== undefined) out[key] = value;
+    }
+    return out;
+}

package/src/index.ts

@@ -12,3 +12,18 @@ export {
     type PasswordStrengthReport,
     type PasswordScore
 } from "@/core/password";
+export { createNotifications, type Notifications, type Notification, type NotificationInput, type NotificationTone, type NotificationAction, type NotificationsOptions, type PromiseMessages } from "@/core/notifications";
+export { createNetworkMonitor, SERVER_NETWORK_STATE, type NetworkState, type NetworkMonitor } from "@/core/network";
+export {
+    relativeTimeView,
+    relativeTimeAttributes,
+    normalizeDate,
+    ensureZone,
+    parseDuration,
+    type RelativeTimeView,
+    type RelativeTimeOptions,
+    type RelativeTimeFormat,
+    type RelativeTimeTense,
+    type RelativeTimePrecision,
+    type RelativeTimeStyle
+} from "@/core/relative-time";

package/src/react/index.ts

@@ -28,3 +28,8 @@ export {
     type PasswordStrengthReport,
     type PasswordScore
 } from "@/core/password";
+export { useNotifications, createNotificationQueue, defaultQueue, type UseNotificationsResult } from "@/react/use-notifications";
+export { Toaster, type ToasterProps, type ToastPosition, type ToastControls } from "@/react/toaster";
+export { useNetworkState } from "@/react/use-network-state";
+export { type NetworkState } from "@/core/network";
+export { RelativeTime, type RelativeTimeProps } from "@/react/relative-time";

package/src/react/relative-time.ts

@@ -0,0 +1,103 @@
+"use client";
+
+import { createElement, useEffect, type HTMLAttributes, type ReactNode } from "react";
+import { relativeTimeView, relativeTimeAttributes, type RelativeTimeOptions } from "@/core/relative-time";
+
+/**
+ * `<RelativeTime date={...} />` - a timestamp that reads as "3 hours ago" and keeps itself
+ * current, rendered by @github/relative-time-element.
+ *
+ * Two things this does that a bare element does not:
+ *
+ * The absolute date is rendered as the element's child, so a server render, a page whose
+ * JavaScript has not arrived yet, and a reader with scripting off all see a real date
+ * instead of an empty box. The element replaces it the moment it upgrades.
+ *
+ * The element is imported on the client only. It is a custom element, so its class extends
+ * HTMLElement at module scope - importing it where there is no DOM throws before any
+ * component of yours runs. A failed import is not fatal either: the absolute date is
+ * already in the markup.
+ */
+
+/** One import per page, however many timestamps are on it. */
+let loading: Promise<unknown> | null = null;
+
+function loadElement(): void {
+    if (loading || typeof window === "undefined") return;
+    loading = import("@github/relative-time-element").catch(() => {
+        // Not installed, or blocked. The absolute label stands in, so there is nothing to
+        // report to the reader and nothing to retry.
+        return null;
+    });
+}
+
+export interface RelativeTimeProps extends RelativeTimeOptions, Omit<HTMLAttributes<HTMLElement>, "prefix" | "children"> {
+    /** ISO string, epoch milliseconds, or a Date. A string with no zone is read as UTC. */
+    date: string | number | Date | null | undefined;
+    /** Rendered when the date cannot be parsed. Nothing, by default. */
+    fallback?: ReactNode;
+    /** Title Case The Whole Phrase. Rarely what you want; `capitalizeFirst` usually is. */
+    capitalize?: boolean;
+    /** Uppercase the first letter, so a standalone "yesterday" reads as "Yesterday". */
+    capitalizeFirst?: boolean;
+    /**
+     * Pin the instant the age is measured from. Pass the request's timestamp to make a
+     * server render and its hydration agree exactly.
+     */
+    now?: Date;
+}
+
+export function RelativeTime({
+    date,
+    fallback = null,
+    capitalize = false,
+    capitalizeFirst = true,
+    now,
+    format,
+    tense,
+    precision,
+    threshold,
+    prefix,
+    formatStyle,
+    locale,
+    timeZone,
+    second,
+    minute,
+    hour,
+    weekday,
+    day,
+    month,
+    year,
+    timeZoneName,
+    noTitle,
+    numericBeyondThreshold,
+    ...rest
+}: RelativeTimeProps): ReactNode {
+    useEffect(loadElement, []);
+
+    const options: RelativeTimeOptions = {
+        format, tense, precision, threshold, prefix, formatStyle, locale, timeZone,
+        second, minute, hour, weekday, day, month, year, timeZoneName, noTitle, numericBeyondThreshold
+    };
+    const view = relativeTimeView(date, options, now);
+    if (!view.date) return fallback;
+
+    const marks = {
+        "data-relative-time-capitalize": capitalize ? "true" : undefined,
+        "data-relative-time-capitalize-first-letter": capitalizeFirst ? "true" : undefined,
+        // The text differs between the server's instant and the browser's, which is the
+        // one hydration difference React has an escape hatch for rather than a bug.
+        suppressHydrationWarning: true
+    };
+
+    // Past the threshold there is no relative phrasing left to produce, so a plain <time>
+    // renders the same words without waiting for a custom element to define itself.
+    if (view.absoluteOnly) {
+        return createElement("time", { dateTime: view.iso, title: noTitle ? undefined : view.exact, ...marks, ...rest }, view.label);
+    }
+
+    // createElement rather than JSX: `<relative-time>` is not a known intrinsic element, and
+    // declaring it means augmenting React's JSX namespace from inside a published package -
+    // which collides with any consumer that declared it too, differently.
+    return createElement("relative-time", { ...relativeTimeAttributes(view, options), ...marks, ...rest }, view.label);
+}