@enigmax/primitives 0.11.1 → 0.13.0

package/recipes/toast/styles.css

@@ -0,0 +1,165 @@
+/*
+ * Ember - the default toast theme.
+ *
+ * Every colour, every distance and every curve is in this file. `<Toaster />` renders the
+ * structure and the state; nothing below is something the package decided for you, so
+ * editing this file is the supported way to make it yours.
+ *
+ * The custom properties at the top are the whole API. Override them on `:root` and you have
+ * a different theme without touching a selector.
+ */
+
+:root {
+    --enigma-toast-width: 22rem;
+    --enigma-toast-gap: 0.625rem;
+    --enigma-toast-edge: 1.25rem;
+    --enigma-toast-radius: 0.75rem;
+    --enigma-toast-exit: 200ms;
+
+    --enigma-toast-bg: #101010;
+    --enigma-toast-border: #2a2a2a;
+    --enigma-toast-text: #f5f5f5;
+    --enigma-toast-muted: #a3a3a3;
+    --enigma-toast-shadow: 0 8px 30px rgb(0 0 0 / 45%);
+
+    --enigma-toast-info: #60a5fa;
+    --enigma-toast-success: #4ade80;
+    --enigma-toast-warning: #fbbf24;
+    --enigma-toast-error: #f87171;
+    --enigma-toast-loading: var(--enigma-toast-muted);
+}
+
+@media (prefers-color-scheme: light) {
+    :root {
+        --enigma-toast-bg: #ffffff;
+        --enigma-toast-border: #e5e5e5;
+        --enigma-toast-text: #171717;
+        --enigma-toast-muted: #737373;
+        --enigma-toast-shadow: 0 8px 30px rgb(0 0 0 / 12%);
+    }
+}
+
+[data-enigma-toaster] {
+    position: fixed;
+    z-index: 9999;
+    display: flex;
+    flex-direction: column;
+    gap: var(--enigma-toast-gap);
+    width: min(var(--enigma-toast-width), calc(100vw - var(--enigma-toast-edge) * 2));
+    /* The region is a layout box, not a wall: clicks pass through the gaps between toasts. */
+    pointer-events: none;
+    margin: 0;
+    padding: 0;
+}
+
+[data-enigma-toaster][data-position^="top"] { top: var(--enigma-toast-edge); flex-direction: column-reverse; }
+[data-enigma-toaster][data-position^="bottom"] { bottom: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-left"] { left: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-right"] { right: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-center"] { left: 50%; transform: translateX(-50%); }
+
+[data-enigma-toast] {
+    pointer-events: auto;
+    position: relative;
+    display: grid;
+    grid-template-columns: 1fr auto;
+    align-items: center;
+    gap: 0.25rem 0.75rem;
+    padding: 0.875rem 1rem;
+    color: var(--enigma-toast-text);
+    background: var(--enigma-toast-bg);
+    border: 1px solid var(--enigma-toast-border);
+    border-radius: var(--enigma-toast-radius);
+    box-shadow: var(--enigma-toast-shadow);
+    /* The swipe offset the component publishes. Zero unless a finger is on it. */
+    translate: var(--enigma-toast-swipe, 0) 0;
+    transition: translate 180ms cubic-bezier(0.22, 1, 0.36, 1), opacity 180ms ease-out;
+    touch-action: pan-y;
+    outline: none;
+}
+
+[data-enigma-toaster][data-position$="-center"] [data-enigma-toast] { translate: 0 var(--enigma-toast-swipe, 0); }
+
+/* While a finger is down the toast tracks it exactly: a transition here would lag behind
+   the pointer, which reads as a broken gesture rather than a smooth one. */
+[data-enigma-toast][data-swiping] { transition: none; cursor: grabbing; user-select: none; }
+
+[data-enigma-toast]:focus-visible { box-shadow: var(--enigma-toast-shadow), 0 0 0 2px var(--enigma-toast-info); }
+
+/* A left border is the tone. It reads at a glance and survives any background. */
+[data-enigma-toast]::before {
+    content: "";
+    position: absolute;
+    inset: 0 auto 0 0;
+    width: 3px;
+    border-radius: var(--enigma-toast-radius) 0 0 var(--enigma-toast-radius);
+    background: var(--enigma-toast-tone, transparent);
+}
+
+[data-enigma-toast][data-tone="info"] { --enigma-toast-tone: var(--enigma-toast-info); }
+[data-enigma-toast][data-tone="success"] { --enigma-toast-tone: var(--enigma-toast-success); }
+[data-enigma-toast][data-tone="warning"] { --enigma-toast-tone: var(--enigma-toast-warning); }
+[data-enigma-toast][data-tone="error"] { --enigma-toast-tone: var(--enigma-toast-error); }
+[data-enigma-toast][data-tone="loading"] { --enigma-toast-tone: var(--enigma-toast-loading); }
+
+[data-enigma-toast-title] { grid-column: 1; margin: 0; font-size: 0.875rem; font-weight: 600; line-height: 1.35; }
+[data-enigma-toast-body] { grid-column: 1; margin: 0; font-size: 0.8125rem; color: var(--enigma-toast-muted); line-height: 1.45; }
+
+[data-enigma-toast-action] {
+    grid-column: 2;
+    grid-row: 1 / -1;
+    padding: 0.3125rem 0.625rem;
+    font: inherit;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--enigma-toast-bg);
+    background: var(--enigma-toast-text);
+    border: 0;
+    border-radius: 0.375rem;
+    cursor: pointer;
+}
+
+[data-enigma-toast-close] {
+    position: absolute;
+    top: 0.375rem;
+    right: 0.5rem;
+    padding: 0 0.25rem;
+    font-size: 0.875rem;
+    line-height: 1;
+    color: var(--enigma-toast-muted);
+    background: none;
+    border: 0;
+    cursor: pointer;
+    /* Shown on hover or focus, so it never covers the message while it is being read - but
+       always reachable by keyboard, which `display: none` would take away. */
+    opacity: 0;
+    transition: opacity 120ms ease-out;
+}
+
+[data-enigma-toast]:hover [data-enigma-toast-close],
+[data-enigma-toast-close]:focus-visible { opacity: 1; }
+
+/* Enter from the edge it is pinned to, leave the same way. */
+@keyframes enigma-toast-in-right { from { opacity: 0; translate: 100% 0; } to { opacity: 1; translate: 0 0; } }
+@keyframes enigma-toast-in-left { from { opacity: 0; translate: -100% 0; } to { opacity: 1; translate: 0 0; } }
+@keyframes enigma-toast-in-top { from { opacity: 0; translate: 0 -100%; } to { opacity: 1; translate: 0 0; } }
+@keyframes enigma-toast-in-bottom { from { opacity: 0; translate: 0 100%; } to { opacity: 1; translate: 0 0; } }
+@keyframes enigma-toast-out { to { opacity: 0; scale: 0.94; } }
+
+[data-position$="-right"] [data-enigma-toast][data-state="open"] { animation: enigma-toast-in-right 260ms cubic-bezier(0.22, 1, 0.36, 1); }
+[data-position$="-left"] [data-enigma-toast][data-state="open"] { animation: enigma-toast-in-left 260ms cubic-bezier(0.22, 1, 0.36, 1); }
+[data-position="top-center"] [data-enigma-toast][data-state="open"] { animation: enigma-toast-in-top 260ms cubic-bezier(0.22, 1, 0.36, 1); }
+[data-position="bottom-center"] [data-enigma-toast][data-state="open"] { animation: enigma-toast-in-bottom 260ms cubic-bezier(0.22, 1, 0.36, 1); }
+
+/* Matches the component's exitDuration: the node is held for exactly this long, so a
+   longer animation would be cut off mid-way. */
+[data-enigma-toast][data-state="leaving"] {
+    animation: enigma-toast-out var(--enigma-toast-exit) ease-in forwards;
+    pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    /* The movement goes, the state change stays: a toast still appears and still leaves. */
+    [data-enigma-toast] { animation: none !important; transition: opacity 120ms ease-out; }
+    [data-enigma-toast][data-state="leaving"] { opacity: 0; }
+}

package/recipes/toast/tailwind.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { Toaster, type ToastPosition } from "@enigmax/primitives/react";
+
+/**
+ * Ember, in Tailwind. Yours to edit.
+ *
+ * The stack, the gestures and the exit hold come from `<Toaster />`; everything below is a
+ * class. The one thing Tailwind cannot express is the swipe offset - it is a live number
+ * from the pointer, published as `--enigma-toast-swipe` - so the arbitrary translate below
+ * reads that variable rather than trying to enumerate positions.
+ */
+
+const TONE = {
+    info: "before:bg-blue-400",
+    success: "before:bg-green-400",
+    warning: "before:bg-amber-400",
+    error: "before:bg-red-400",
+    loading: "before:bg-neutral-500"
+} as const;
+
+export function AppToaster({ position = "bottom-right" }: { position?: ToastPosition; }) {
+    return (
+        <Toaster
+            position={position}
+            className="fixed z-[9999] flex w-[min(22rem,calc(100vw-2.5rem))] flex-col gap-2.5 data-[position^=top]:top-5 data-[position^=top]:flex-col-reverse data-[position^=bottom]:bottom-5 data-[position$=-left]:left-5 data-[position$=-right]:right-5 data-[position$=-center]:left-1/2 data-[position$=-center]:-translate-x-1/2 pointer-events-none"
+        >
+            {(notification, controls) => (
+                <div
+                    className={[
+                        "pointer-events-auto relative grid grid-cols-[1fr_auto] items-center gap-x-3 gap-y-1 rounded-xl border p-4",
+                        "border-neutral-800 bg-neutral-950 text-neutral-100 shadow-[0_8px_30px_rgb(0_0_0/45%)]",
+                        "before:absolute before:inset-y-0 before:left-0 before:w-[3px] before:rounded-l-xl",
+                        // Tracks the finger exactly while a swipe is in progress.
+                        "translate-x-[var(--enigma-toast-swipe,0)] transition-transform duration-200 ease-out data-[swiping]:transition-none",
+                        TONE[notification.tone]
+                    ].join(" ")}
+                >
+                    <p className="col-start-1 m-0 text-sm font-semibold leading-snug">{notification.title}</p>
+                    {notification.body && <p className="col-start-1 m-0 text-[13px] leading-relaxed text-neutral-400">{notification.body}</p>}
+
+                    {notification.action && (
+                        <button
+                            type="button"
+                            className="col-start-2 row-span-full rounded-md bg-neutral-100 px-2.5 py-1.5 text-xs font-semibold text-neutral-950"
+                            onClick={() => {
+                                notification.action?.onSelect();
+                                if (notification.action?.dismiss !== false) controls.dismiss();
+                            }}
+                        >{notification.action.label}</button>
+                    )}
+
+                    {/* Opacity rather than hidden: it must stay reachable by keyboard. */}
+                    <button
+                        type="button"
+                        aria-label="Dismiss"
+                        className="absolute right-2 top-1.5 px-1 text-sm leading-none text-neutral-400 opacity-0 transition-opacity focus-visible:opacity-100 group-hover:opacity-100"
+                        onClick={controls.dismiss}
+                    >&times;</button>
+                </div>
+            )}
+        </Toaster>
+    );
+}

package/registry.json

@@ -354,6 +354,273 @@
         "[aria-busy=true]"
       ],
       "docs": "docs/notes/primitives.md#button"
+    },
+    {
+      "name": "notifications",
+      "title": "Notification queue",
+      "description": "Ordering, dedupe by key, sticky errors and dismiss timers that hold instead of running while the tab is hidden. No rendering.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "createNotifications"
+        ],
+        "astro": [
+          "createNotifications"
+        ],
+        "react": [
+          "useNotifications"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/notifications.ts",
+          "dest": "notifications/notifications.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-notifications.ts",
+          "dest": "notifications/use-notifications.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/notifications": "./notifications"
+          },
+          "main": true
+        },
+        {
+          "path": "recipes/notifications/tailwind.tsx",
+          "dest": "notifications/Notifications.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind"
+        }
+      ],
+      "styles": false,
+      "docs": "docs/notes/primitives.md#notifications",
+      "recipes": [
+        "tailwind"
+      ]
+    },
+    {
+      "name": "toast",
+      "title": "Toast",
+      "description": "The notification queue with a renderer on top: stacking, swipe to dismiss, a pointer that stops the clock, and a toast that is still on screen while it animates out. Ships the Ember theme, which is a stylesheet you own.",
+      "targets": [
+        "react"
+      ],
+      "entry": {
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "react": [
+          "Toaster",
+          "useNotifications"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/notifications.ts",
+          "dest": "toast/notifications.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-notifications.ts",
+          "dest": "toast/use-notifications.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/notifications": "./notifications"
+          }
+        },
+        {
+          "path": "src/react/toaster.tsx",
+          "dest": "toast/index.tsx",
+          "main": true,
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/notifications": "./notifications",
+            "@/react/use-notifications": "./use-notifications"
+          }
+        },
+        {
+          "path": "recipes/toast/styles.css",
+          "dest": "toast/styles.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        },
+        {
+          "path": "recipes/toast/tailwind.tsx",
+          "dest": "toast/AppToaster.tsx",
+          "targets": [
+            "react"
+          ],
+          "style": "tailwind",
+          "rewrite": {
+            "@enigmax/utils/react": "./index"
+          }
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "[data-enigma-toaster]",
+        "[data-enigma-toaster][data-position]",
+        "[data-enigma-toast]",
+        "[data-enigma-toast][data-tone=error]",
+        "[data-enigma-toast][data-state=leaving]",
+        "[data-enigma-toast][data-swiping]",
+        "[data-enigma-toast][data-front]",
+        "[data-enigma-toast-title]",
+        "[data-enigma-toast-body]",
+        "[data-enigma-toast-action]",
+        "[data-enigma-toast-close]"
+      ],
+      "docs": "docs/notes/primitives.md#toast",
+      "recipes": [
+        "tailwind",
+        "css"
+      ]
+    },
+    {
+      "name": "network",
+      "title": "Connection state",
+      "description": "Online/offline plus what the Network Information API reports, and the recovery transition every hand-rolled version re-derives: `recovered` is false on a first load, so a page that opens online never announces a comeback that did not happen.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "createNetworkMonitor"
+        ],
+        "astro": [
+          "createNetworkMonitor"
+        ],
+        "react": [
+          "useNetworkState"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/network.ts",
+          "dest": "network/network.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/use-network-state.ts",
+          "dest": "network/use-network-state.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/network": "./network"
+          },
+          "main": true
+        }
+      ],
+      "styles": false,
+      "docs": "docs/notes/primitives.md#network"
+    },
+    {
+      "name": "relative-time",
+      "title": "Relative timestamps",
+      "description": "\"3 hours ago\", kept current, localised by the page's own language. A timestamp with no zone is read as UTC instead of as the server's local time, and the absolute date is rendered as the element's child so a server render and a reader without JavaScript still see a real date.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "relativeTimeView",
+          "relativeTimeAttributes",
+          "normalizeDate"
+        ],
+        "astro": [
+          "relativeTimeView",
+          "relativeTimeAttributes",
+          "normalizeDate"
+        ],
+        "react": [
+          "RelativeTime"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/relative-time.ts",
+          "dest": "relative-time/relative-time.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/relative-time.ts",
+          "dest": "relative-time/index.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/relative-time": "./relative-time"
+          }
+        },
+        {
+          "path": "recipes/relative-time/styles.css",
+          "dest": "relative-time/styles.css",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "relative-time",
+        "[data-relative-time-capitalize=true]",
+        "[data-relative-time-capitalize-first-letter=true]"
+      ],
+      "docs": "docs/notes/primitives.md#relative-time",
+      "dependencies": {
+        "@github/relative-time-element": "^4.4.0"
+      }
     }
   ]
 }

package/src/core/network.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+export 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;
+}
+
+export 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. */
+export const SERVER_NETWORK_STATE: NetworkState = {
+    online: true,
+    downlink: null,
+    downlinkMax: null,
+    effectiveType: null,
+    rtt: null,
+    saveData: null,
+    type: null,
+    recovered: false,
+    slow: false
+};
+
+interface ConnectionLike extends EventTarget {
+    downlink?: number;
+    downlinkMax?: number;
+    effectiveType?: string;
+    rtt?: number;
+    saveData?: boolean;
+    type?: string;
+}
+
+/** Still prefixed in some browsers, and absent entirely in Safari. */
+function connection(): ConnectionLike | null {
+    if (typeof navigator === "undefined") return null;
+    const nav = navigator as Navigator & {
+        connection?: ConnectionLike;
+        mozConnection?: ConnectionLike;
+        webkitConnection?: ConnectionLike;
+    };
+    return nav.connection ?? nav.mozConnection ?? nav.webkitConnection ?? null;
+}
+
+function shallowEqual(left: NetworkState, right: NetworkState): boolean {
+    for (const key of Object.keys(left) as (keyof NetworkState)[]) {
+        if (left[key] !== right[key]) return false;
+    }
+    return true;
+}
+
+export function createNetworkMonitor(): NetworkMonitor {
+    // Nothing to observe during a server render; the snapshot stands in.
+    if (typeof window === "undefined") {
+        return {
+            get state() { return SERVER_NETWORK_STATE; },
+            subscribe() { return () => { /* nothing changes */ }; },
+            destroy() { /* nothing to release */ }
+        };
+    }
+
+    const listeners = new Set<(state: NetworkState) => void>();
+    let hasBeenOffline = false;
+    let state = read();
+
+    function read(): NetworkState {
+        const link = connection();
+        const online = navigator.onLine;
+        const effectiveType = link?.effectiveType ?? null;
+        const saveData = link?.saveData ?? null;
+        return {
+            online,
+            downlink: link?.downlink ?? null,
+            downlinkMax: link?.downlinkMax ?? null,
+            effectiveType,
+            rtt: link?.rtt ?? null,
+            saveData,
+            type: link?.type ?? null,
+            recovered: online && hasBeenOffline,
+            slow: saveData === true || effectiveType === "2g" || effectiveType === "slow-2g"
+        };
+    }
+
+    function update(): void {
+        if (!navigator.onLine) hasBeenOffline = true;
+        const next = read();
+        // The connection object fires `change` for readings that did not change; an
+        // identical object would re-render every subscriber for nothing.
+        if (shallowEqual(state, next)) return;
+        state = next;
+        for (const listener of listeners) listener(state);
+    }
+
+    const link = connection();
+    window.addEventListener("online", update, { passive: true });
+    window.addEventListener("offline", update, { passive: true });
+    link?.addEventListener("change", update, { passive: true });
+
+    return {
+        get state() { return state; },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        destroy() {
+            listeners.clear();
+            window.removeEventListener("online", update);
+            window.removeEventListener("offline", update);
+            link?.removeEventListener("change", update);
+        }
+    };
+}