@enigmax/primitives 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -309,4 +309,216 @@ interface EstimateOptions {
  */
 declare function estimatePasswordStrength(password: string, options?: EstimateOptions): PasswordStrengthReport;
 
-export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type EstimateOptions, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup };
+/**
+ * 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.
+ */
+type NotificationTone = "info" | "success" | "warning" | "error" | "loading";
+/** One button on a notification. Anything more belongs on the page, not in a toast. */
+interface NotificationAction {
+    label: string;
+    onSelect: () => void;
+    /** Dismiss once it has been pressed. On by default. */
+    dismiss?: boolean;
+}
+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;
+}
+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. */
+interface PromiseMessages<T> {
+    loading: string | NotificationInput;
+    success: string | ((value: T) => string | NotificationInput);
+    error: string | ((error: unknown) => string | NotificationInput);
+}
+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[];
+}
+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;
+}
+declare function createNotifications(options?: NotificationsOptions): Notifications;
+
+/**
+ * Connection state: online/offline plus whatever the Network Information API will say.
+ *
+ * The part worth not rewriting is the TRANSITION. "You are back online" needs to know the
+ * connection had dropped, and every implementation of that ends up as a stray `wasOffline`
+ * boolean next to the effect, re-derived per screen and wrong the first time the page
+ * loads offline. It is tracked here instead.
+ */
+interface NetworkState {
+    online: boolean;
+    /** Estimated downlink in Mbps. Null where the browser does not report it. */
+    downlink: number | null;
+    downlinkMax: number | null;
+    /** "slow-2g" | "2g" | "3g" | "4g", or null. */
+    effectiveType: string | null;
+    /** Estimated round-trip time in ms. */
+    rtt: number | null;
+    /** The visitor asked for reduced data use. */
+    saveData: boolean | null;
+    /** "wifi" | "cellular" | "ethernet" | ..., or null. */
+    type: string | null;
+    /**
+     * The connection dropped earlier and is back. False on a first load, so a page that
+     * opens online never announces a recovery that did not happen.
+     */
+    recovered: boolean;
+    /** On a connection worth degrading for: 2g or slower, or data saver on. */
+    slow: boolean;
+}
+interface NetworkMonitor {
+    readonly state: NetworkState;
+    subscribe(listener: (state: NetworkState) => void): () => void;
+    destroy(): void;
+}
+/** What a server render sees. Assuming offline would flash a warning on every page. */
+declare const SERVER_NETWORK_STATE: NetworkState;
+declare function createNetworkMonitor(): NetworkMonitor;
+
+/**
+ * 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. */
+type RelativeTimeFormat = "auto" | "relative" | "duration" | "datetime" | "micro" | "elapsed";
+type RelativeTimeTense = "auto" | "past" | "future";
+type RelativeTimePrecision = "year" | "month" | "day" | "hour" | "minute" | "second";
+type RelativeTimeStyle = "long" | "short" | "narrow";
+type NumericStyle = "numeric" | "2-digit";
+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. */
+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;
+}
+/**
+ * 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.
+ */
+declare function ensureZone(text: string): string;
+/** Parse anything a date column or an API hands over. Null rather than an Invalid Date. */
+declare function normalizeDate(value: string | number | Date | null | undefined): Date | null;
+/**
+ * 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.
+ */
+declare function parseDuration(value: string): number;
+/**
+ * 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.
+ */
+declare function relativeTimeView(value: string | number | Date | null | undefined, options?: RelativeTimeOptions, now?: Date): RelativeTimeView;
+/**
+ * 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.
+ */
+declare function relativeTimeAttributes(view: RelativeTimeView, options?: RelativeTimeOptions): Record<string, string>;
+
+export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type EstimateOptions, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type NetworkMonitor, type NetworkState, type Notification, type NotificationAction, type NotificationInput, type NotificationTone, type Notifications, type NotificationsOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, type PromiseMessages, type RelativeTimeFormat, type RelativeTimeOptions, type RelativeTimePrecision, type RelativeTimeStyle, type RelativeTimeTense, type RelativeTimeView, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView };

package/dist/index.js

@@ -1,2 +1,2 @@
-export { INPUT_ICON_PATHS, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup } from './chunk-42Y7OOJM.js';
+export { INPUT_ICON_PATHS, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView } from './chunk-DD2X5B2J.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/next/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ButtonProps } from '../react/index.js';
-export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseSearchResult, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../react/index.js';
-export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
+export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
+export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
 export { F as FuseConstructor, b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 
 /**

package/dist/next/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-L4KA342C.js';
-export { Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../chunk-L4KA342C.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
+import { Button } from '../chunk-YFM2FWHQ.js';
+export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
 import '../chunk-UZFEEFMF.js';
 import Link from 'next/link';
 import { forwardRef, createElement } from 'react';

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ComponentPropsWithoutRef, ElementType, ReactNode, RefObject } from 'react';
-import { ButtonOptions, ButtonState, MarqueeOptions, InputOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from '../index.js';
+import { ComponentPropsWithoutRef, ElementType, ReactNode, RefObject, CSSProperties, HTMLAttributes } from 'react';
+import { ButtonOptions, ButtonState, MarqueeOptions, InputOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport, Notifications, Notification, NotificationsOptions, NetworkState, RelativeTimeOptions } from '../index.js';
 export { InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, estimatePasswordStrength, generatePassword } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
@@ -18,6 +18,16 @@ export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
  * ordinary one means writing the same six lines at every call site, which is how they drift.
  */
 interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRef<"button">, "onClick" | "onChange" | "children" | "type"> {
+    /**
+     * What to run when it is pressed. The same thing as `onPress`, under the name React
+     * already uses - write whichever reads better.
+     *
+     * It is an ALIAS, not a second handler: the component owns the element's real onClick,
+     * because that is where a press is refused while the button is loading, disabled or
+     * cooling down. Passing one through would replace that and silently take the behaviour
+     * with it. Returning a promise drives `loading` for its duration, same as `onPress`.
+     */
+    onClick?: ButtonOptions["onPress"];
     /**
      * Override what to render. You rarely need it: an href already renders whatever
      * `setLinkComponent` registered - your router's Link - and a button otherwise.
@@ -133,7 +143,7 @@ declare function useSearch<T>(options?: SearchOptions<T>): UseSearchResult<T>;
 interface UseButtonResult extends ButtonState {
     /** Spread onto the element named by `element`. */
     props: {
-        onClick: (event: {
+        onClick: (event: Event | {
             preventDefault(): void;
         }) => void;
         "aria-disabled": boolean;
@@ -279,4 +289,88 @@ interface PasswordStrengthProps extends Omit<ComponentPropsWithoutRef<"div">, "c
  */
 declare function PasswordStrength({ value, report, userInputs, segments, labels, showWarning, classNames, ...props }: PasswordStrengthProps): ReactNode;
 
-export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch };
+/** One queue per app by default; a second one would race the first for the corner. */
+declare const defaultQueue: Notifications;
+interface UseNotificationsResult extends Pick<Notifications, "notify" | "dismiss" | "dismissAll" | "pause" | "resume"> {
+    items: readonly Notification[];
+}
+/**
+ * Subscribe to a notification queue.
+ *
+ * Rendering is yours: this returns the list, the ordering and the timers, and
+ * nothing about how a notification looks.
+ */
+declare function useNotifications(queue?: Notifications): UseNotificationsResult;
+declare function createNotificationQueue(options?: NotificationsOptions): Notifications;
+
+/**
+ * `<Toaster />` - the stack, the movement and the gestures. No colours.
+ *
+ * The queue underneath already owns ordering, dedupe by key, sticky errors and timers that
+ * HOLD while the tab is hidden. What this adds is everything you cannot express in a queue:
+ * a toast that is on its way out is still on screen, a pointer resting on the stack must
+ * stop the clock, and a swipe has to follow the finger before it decides anything.
+ *
+ * Every part carries a data attribute, so the theme is a stylesheet you own. `enigma add
+ * toast --copy` writes one.
+ */
+type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+interface ToasterProps {
+    /** Which queue to render. The shared one by default. */
+    queue?: Notifications;
+    position?: ToastPosition;
+    /**
+     * How long the exit animation lasts, in ms. The node stays mounted for exactly this
+     * long after it leaves the queue - a toast that vanishes the instant it is dismissed
+     * cannot animate out, and that is the only reason this component keeps its own list.
+     */
+    exitDuration?: number;
+    /** Px a toast must travel before the release dismisses it. */
+    swipeThreshold?: number;
+    /** Render a toast yourself. The default renders title, body and the action. */
+    children?: (notification: Notification, controls: ToastControls) => ReactNode;
+    /** Accessible name for the region. */
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+interface ToastControls {
+    dismiss: () => void;
+}
+declare function Toaster({ queue, position, exitDuration, swipeThreshold, children, label, className, style }: ToasterProps): ReactNode;
+
+/**
+ * Connection state, kept in sync through useSyncExternalStore.
+ *
+ * ```tsx
+ * const { online, recovered, slow } = useNetworkState();
+ *
+ * useEffect(() => {
+ *     if (!online) notify({ key: "net", title: "No connection", tone: "error" });
+ *     else if (recovered) notify({ key: "net", title: "Back online", tone: "success" });
+ * }, [online, recovered]);
+ * ```
+ *
+ * `recovered` is false on a first load, so a page that opens online never announces a
+ * recovery that did not happen - the bug every hand-rolled `wasOffline` flag starts with.
+ */
+declare function useNetworkState(): NetworkState;
+
+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;
+}
+declare function RelativeTime({ date, fallback, capitalize, capitalizeFirst, now, format, tense, precision, threshold, prefix, formatStyle, locale, timeZone, second, minute, hour, weekday, day, month, year, timeZoneName, noTitle, numericBeyondThreshold, ...rest }: RelativeTimeProps): ReactNode;
+
+export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, NetworkState, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, RelativeTime, type RelativeTimeProps, SearchMatch, SearchOptions, type ToastControls, type ToastPosition, Toaster, type ToasterProps, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseNotificationsResult, type UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };

package/dist/react/index.js

@@ -1,4 +1,4 @@
 "use client";
-export { Button, Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../chunk-L4KA342C.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
+export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
 import '../chunk-UZFEEFMF.js';

package/dist/react-router/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ButtonProps } from '../react/index.js';
-export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseSearchResult, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../react/index.js';
-export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
+export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
+export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
 export { F as FuseConstructor, b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;

package/dist/react-router/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-L4KA342C.js';
-export { Input, PasswordStrength, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useSearch } from '../chunk-L4KA342C.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-42Y7OOJM.js';
+import { Button } from '../chunk-YFM2FWHQ.js';
+export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-YFM2FWHQ.js';
+export { estimatePasswordStrength, generatePassword } from '../chunk-DD2X5B2J.js';
 import '../chunk-UZFEEFMF.js';
 import { Link } from 'react-router';
 import { forwardRef, createElement } from 'react';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.11.0",
-  "description": "Headless interaction primitives: the behaviour, the timing and the accessibility of components like a draggable infinite marquee, with no styles of their own. Framework-agnostic core plus thin adapters.",
+  "version": "0.12.0",
+  "description": "Headless components: the behaviour, the timing and the accessibility, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,12 +26,14 @@
     "./react-router": {
       "types": "./dist/react-router/index.d.ts",
       "import": "./dist/react-router/index.js"
-    }
+    },
+    "./relative-time.css": "./recipes/relative-time/styles.css",
+    "./toast.css": "./recipes/toast/styles.css"
   },
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "npm run test:fixtures && playwright test",
+    "test": "npm run test:fixtures && node --test test/*.test.mjs && playwright test",
     "test:fixtures": "esbuild test/fixture/react.tsx --bundle --format=esm --jsx=automatic --outfile=test/fixture/build/react.js --tsconfig=tsconfig.json --alias:next/link=./test/fixture/next-link-stub.tsx --alias:react-router=./test/fixture/react-router-stub.tsx",
     "test:install": "playwright install chromium",
     "prepublishOnly": "npm run typecheck && npm run build"
@@ -45,6 +47,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
+    "@github/relative-time-element": ">=4",
     "fuse.js": ">=6",
     "next": ">=13",
     "react": ">=18",
@@ -62,9 +65,13 @@
     },
     "react-router": {
       "optional": true
+    },
+    "@github/relative-time-element": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@github/relative-time-element": "^4.5.1",
     "@playwright/test": "^1.48.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.4",
@@ -80,18 +87,22 @@
     "node": ">=18"
   },
   "keywords": [
-    "headless",
-    "primitives",
-    "marquee",
     "carousel",
-    "unstyled",
-    "react",
-    "vanilla",
     "enigma",
+    "fuse",
+    "headless",
     "input",
+    "marquee",
+    "network",
+    "notifications",
     "password",
+    "primitives",
+    "react",
+    "relative-time",
     "search",
-    "fuse"
+    "toast",
+    "unstyled",
+    "vanilla"
   ],
   "license": "Apache-2.0",
   "author": "FJRG2007 <fjrg2007@tpeoficial.com>",

package/recipes/notifications/tailwind.tsx

@@ -0,0 +1,60 @@
+import { useNotifications } from "@enigmax/primitives/react";
+
+/**
+ * A styled notification stack, yours to edit.
+ *
+ * Ordering, dedupe by key, sticky errors and the dismiss timers all come from the
+ * queue. Hovering pauses those timers, which is the whole reason `pause`/`resume` are
+ * wired to the pointer here.
+ *
+ * Fire one from anywhere:
+ *   import { defaultQueue } from "@enigmax/primitives/react";
+ *   defaultQueue.notify({ title: "Saved", tone: "success" });
+ */
+const TONE = {
+    info: "border-l-neutral-500",
+    success: "border-l-emerald-500",
+    warning: "border-l-amber-500",
+    error: "border-l-red-500"
+} as const;
+
+export function Notifications() {
+    const { items, dismiss, pause, resume } = useNotifications();
+
+    if (!items.length) return null;
+
+    return (
+        <div
+            className="fixed bottom-4 right-4 z-50 grid w-[min(22rem,calc(100vw-2rem))] gap-2"
+            role="region"
+            aria-label="Notifications"
+            onPointerEnter={pause}
+            onPointerLeave={resume}
+        >
+            {items.map((item) => (
+                <div
+                    key={item.id}
+                    role={item.tone === "error" ? "alert" : "status"}
+                    className={`
+                        flex items-start gap-3 rounded-xl border border-l-[3px] border-neutral-800
+                        bg-neutral-900 px-3.5 py-3 shadow-lg ${TONE[item.tone]}
+                    `}
+                >
+                    <div className="min-w-0 flex-1">
+                        <p className="text-sm text-neutral-100">{item.title}</p>
+                        {item.body && <p className="mt-0.5 text-xs text-neutral-400">{item.body}</p>}
+                    </div>
+                    <button
+                        type="button"
+                        onClick={() => dismiss(item.id)}
+                        aria-label={`Dismiss ${item.title}`}
+                        title="Dismiss"
+                        className="rounded-md px-1 text-neutral-500 hover:text-neutral-100"
+                    >
+                        &times;
+                    </button>
+                </div>
+            ))}
+        </div>
+    );
+}

package/recipes/relative-time/styles.css

@@ -0,0 +1,24 @@
+/*
+ * The two hooks <RelativeTime> exposes. Import this once, anywhere:
+ *
+ *     import "@enigmax/utils/relative-time.css";
+ *
+ * Both are opt-in per timestamp - the attributes only appear when you ask for them - and
+ * both are marked !important on purpose: the element writes its own text content, so a
+ * `text-transform` from a reset or a typography plugin lands on the same node and would
+ * otherwise win on cascade order alone.
+ */
+
+/* Title Case Every Word. Reads oddly on "2 Days Ago"; usually you want the rule below. */
+[data-relative-time-capitalize="true"],
+[data-relative-time-capitalize="true"] * {
+    text-transform: capitalize !important;
+}
+
+/* Just the first letter, so a standalone "yesterday" starts a line properly. The nested
+   selectors cover the element wrapping its text in a child, which it does for some formats. */
+[data-relative-time-capitalize-first-letter="true"]::first-letter,
+[data-relative-time-capitalize-first-letter="true"] *::first-letter,
+[data-relative-time-capitalize-first-letter="true"] * *::first-letter {
+    text-transform: uppercase !important;
+}