@reykjavik/webtools 0.3.6 → 0.3.8

package/esm/alertsStore/index.js

@@ -0,0 +1,280 @@
+import { dumbId, ObjectFromEntries } from '@reykjavik/hanna-utils';
+import * as v from 'valibot';
+const messageSchema = v.union([
+    v.string(),
+    v.array(v.union([
+        // text nodes
+        v.string(),
+        // link elements
+        v.object({
+            tag: v.literal('a'),
+            text: v.string(),
+            href: v.string(),
+            target: v.optional(v.string()),
+            hrefLang: v.optional(v.string()),
+            lang: v.optional(v.string()),
+        }),
+        // strong/bold elements
+        v.object({
+            tag: v.literal('strong'),
+            text: v.string(),
+        }),
+    ])),
+]);
+// ---------------------------------------------------------------------------
+const defaultKey = 'app~alerts';
+const defaultAlertLevels = ['info', 'warning', 'success', 'error'];
+const defaultDurations = {
+    BLINK: 2000,
+    SHORT: 4000,
+    MEDIUM: 8000,
+    LONG: 16000,
+    XLONG: 32000,
+    INDEFINITE: 0,
+};
+const defaultDefaultDuration = 'SHORT';
+const storeKeys = {};
+/**
+ * Factory function that creates an alerter store singleton with optional
+ * configuration for the genarated alerts.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const createAlerterStore = (cfg = {}) => {
+    const STORE_KEY = cfg.key || defaultKey;
+    if (storeKeys[STORE_KEY]) {
+        throw new Error(`An alerter store with key "${STORE_KEY}" already exists.`);
+    }
+    storeKeys[STORE_KEY] = true;
+    const storgae = cfg.storage || (typeof sessionStorage !== 'undefined' ? sessionStorage : undefined);
+    const alertLevels = cfg.levels || defaultAlertLevels;
+    const durations = cfg.durations || defaultDurations;
+    const DEFAULT_DURATION = cfg.durations
+        ? cfg.defaultDuration
+        : defaultDefaultDuration;
+    const _notificationSchema = v.object({
+        level: v.picklist(alertLevels),
+        message: messageSchema,
+        type: v.optional(cfg.types ? v.picklist(cfg.types) : v.string()),
+        flags: v.optional(v.array(cfg.flags ? v.picklist(cfg.flags) : v.string())),
+        duration: v.optional(v.number()),
+        id: v.string(),
+    });
+    const alertsSchema = v.object({
+        active: v.array(_notificationSchema),
+        pending: v.array(v.intersect([_notificationSchema, v.object({ showAt: v.number() })])),
+    });
+    /** Global array of inflight alert notifications */
+    const alerts = {
+        active: [],
+        pending: [],
+    };
+    const _saveAlertsToStorage = storgae
+        ? () => storgae.setItem(STORE_KEY, JSON.stringify(alerts))
+        : () => undefined;
+    // ---------------------------------------------------------------------------
+    /** Array of callbacks to call whenever alerts are activated or cleared */
+    const subscriptions = [];
+    let isEmitting;
+    /** Calls all subscribed callbacks with the currently active alerts and the event type. */
+    const emitEvent = (meta, callback) => {
+        if (callback) {
+            setTimeout(() => callback(alerts.active, meta));
+            return;
+        }
+        _saveAlertsToStorage();
+        clearTimeout(isEmitting);
+        // For consistency, always delay pinging the subscribed callbacks until next tick.
+        isEmitting = setTimeout(() => {
+            subscriptions.forEach((callback) => {
+                callback(alerts.active, meta);
+            });
+        });
+    };
+    const clearAlert = (id) => {
+        let found = false;
+        alerts.active.some((alert, idx) => {
+            if (alert.id === id) {
+                alerts.active = alerts.active.toSpliced(idx, 1);
+                found = true;
+                return true;
+            }
+        });
+        alerts.pending.some((alert, idx) => {
+            if (alert.id === id) {
+                alerts.pending = alerts.pending.toSpliced(idx, 1);
+                found = true;
+                return true;
+            }
+        });
+        if (found) {
+            emitEvent({ type: 'clear', ids: [id] });
+        }
+    };
+    // ---------------------------------------------------------------------------
+    const _unsubscribe = (callback) => {
+        const idx = subscriptions.indexOf(callback);
+        if (idx > -1) {
+            subscriptions.splice(idx, 1);
+        }
+    };
+    const subscribe = (callback) => {
+        if (subscriptions.indexOf(callback) === -1) {
+            subscriptions.push(callback);
+            // Should we allow opting-out of immediate invocations via function param?
+            if (alerts.active.length) {
+                emitEvent({
+                    type: 'add',
+                    ids: alerts.active.map((t) => t.id),
+                }, callback);
+            }
+        }
+        return () => _unsubscribe(callback);
+    };
+    // ---------------------------------------------------------------------------
+    const buildNotification = (_payload, level) => {
+        // Strip away duration and delay (not part of the notification object)
+        const { duration, delay, ...payload } = _payload;
+        const durationMs = durations[(duration || DEFAULT_DURATION || '')] || 0;
+        return {
+            ...payload,
+            level,
+            id: dumbId(), // Make unique ID for the notification
+            ...(durationMs && { duration: durationMs }),
+            ...(delay && delay > 50 && { showAt: Date.now() + delay }),
+        };
+    };
+    // add dismiss and setFlags dispatcher functions
+    // this way they stay stable across updates to the same alert, which can be useful for UI components that want to update or dismiss an alert after it's been rendered.
+    const addMethodsToAlertInfo = (notification) => {
+        const id = notification.id;
+        return {
+            ...notification,
+            dismiss: () => clearAlert(id),
+            setFlags: (value) => {
+                const notification = alerts.active.find((t) => t.id === id);
+                if (!notification) {
+                    return;
+                }
+                const oldFlags = notification.flags;
+                const flags = typeof value === 'string'
+                    ? [value]
+                    : Array.isArray(value)
+                        ? [...value]
+                        : value(notification.flags);
+                if (flags === oldFlags) {
+                    return;
+                }
+                alerts.active = alerts.active.toSpliced(alerts.active.findIndex((t) => t.id === id), 1, { ...notification, flags });
+                emitEvent({ type: 'change', ids: [id] });
+            },
+        };
+    };
+    const preparePendingAlertActivation = ({ id, showAt }) => {
+        setTimeout(() => {
+            const idx = alerts.pending.findIndex((t) => t.id === id);
+            if (idx === -1) {
+                return;
+            }
+            // Find and remove the pending in alert in one fell swoop
+            const { showAt, ...clonedAsActive } = alerts.pending.splice(idx, 1)[0];
+            alerts.active = [...alerts.active, addMethodsToAlertInfo(clonedAsActive)];
+            emitEvent({ type: 'add', ids: [id] });
+        }, showAt - Date.now());
+    };
+    const _addAlert = (payload, level) => {
+        const notification = buildNotification(payload, level);
+        if (!notification.showAt) {
+            // Notification starts active. Clone the array.
+            alerts.active = [...alerts.active, addMethodsToAlertInfo(notification)];
+            emitEvent({ type: 'add', ids: [notification.id] });
+            return;
+        }
+        // Set up delayed dispatch of the notification
+        // Store it as pending
+        alerts.pending.push(notification);
+        // Persist the updated alerts state immediately
+        _saveAlertsToStorage();
+        // Set up a timer for make it active
+        preparePendingAlertActivation(notification);
+    };
+    const alerter = ObjectFromEntries(alertLevels.map((level) => [
+        level,
+        (payload) => _addAlert(payload, level),
+    ]));
+    // ---------------------------------------------------------------------------
+    // On module load, read saved alerts from the storage (def. `sessionStorage`),
+    // if available.
+    // This allows us to persist alerts across page reloads,
+    // but NOT across tabs or browser sessions.
+    storgae &&
+        (() => {
+            const storedAlerts = storgae.getItem(STORE_KEY);
+            if (!storedAlerts) {
+                return;
+            }
+            try {
+                // NOTE: This TypeAssertion is wrong rn and only becomes true after
+                // `addMethodsToAlertInfo` is called on the active alerts.
+                // Also TS has a hard time understanding the dynamically generated
+                // schema and that they're actually correct in terms of the configuration
+                // type params `Level`, `Type` and `Flag`.
+                const paesed = v.parse(alertsSchema, JSON.parse(storedAlerts));
+                alerts.pending = paesed.pending;
+                alerts.active = paesed.active.map(addMethodsToAlertInfo);
+            }
+            catch (e) {
+                console.error('Failed to parse stored alerts:', e);
+                return;
+            }
+            const now = Date.now();
+            const newActive = [];
+            // Check pending alerts and set up timers, unless they should already
+            // be active, in which case move them to active immediately.
+            alerts.pending = alerts.pending.filter((alert) => {
+                if (alert.showAt <= now) {
+                    // Remove pending alerts that should now be active. Store them in `newActive`
+                    newActive.push(alert);
+                    return false;
+                }
+                // Keep the rest, and set up timers to activate them later.
+                preparePendingAlertActivation(alert);
+                return true;
+            });
+            // Append `newActive` to the active alerts array
+            alerts.active.push(...newActive
+                // Make sure alerts with earlier `showAt` are shown first
+                .sort((a, b) => a.showAt - b.showAt)
+                // remove showAt, not part of active alerts
+                .map(({ showAt, ...rest }) => addMethodsToAlertInfo(rest)));
+            // Save the (possibly) cleaned up alerts back to the storage, because why not. :-D
+            _saveAlertsToStorage();
+        })();
+    return {
+        /**
+         * Singleton object with methods for showing alerts of different levels.
+         * Pass a payload object to the method of the level you want to dispatch,
+         * and the alert will be added to the store.
+         *
+         * Use `subscribeToAlerts` elsewhere in the app to subscribe to alert
+         * notifications and display them.
+         *
+         * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+         */
+        alerter,
+        /**
+         * Subscribes to alert events. The provided callback will be called whenever a
+         * alert is added or cleared.
+         *
+         * The callback is called immediately upon subscription if there are already
+         * active alerts.
+         *
+         * Returns an unsubscribe function that can be called to stop receiving alert
+         * events.
+         *
+         * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+         */
+        subscribe,
+    };
+};

package/esm/alertsStore/react.d.ts

@@ -0,0 +1,39 @@
+import React, { ReactNode } from 'react';
+import { AlertMessage } from './index.js';
+type SubsScriber<AlertInfo> = (callback: (alerts: Array<AlertInfo>, meta: {
+    type: string;
+    ids: Array<string>;
+}) => void) => () => void;
+/**
+ * Factory function that creates a React subscription hook and a container
+ * component linked to a specific alerter store subscibe function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#makereactsubscription
+ */
+export declare const makeReactSubscription: <AlertInfo>(subscribe: SubsScriber<AlertInfo>) => {
+    useAlerter: () => AlertInfo[];
+    AlertsContainer: (props: {
+        children: (alerts: Array<AlertInfo>) => ReactNode;
+    }) => React.ReactNode;
+};
+/**
+ * Helper to render an alerter alert message, which can be a simple string or a
+ * more complex array of strings and objects representing links and rich (bold)
+ * text formatting.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessage
+ */
+export declare const renderAlertMessage: {
+    (message: AlertMessage, linkComponent?: renderAlertMessage.LinkRenderer): ReactNode;
+    withLinkRenderer(LinkCompnent: renderAlertMessage.LinkRenderer): (message: AlertMessage) => React.ReactNode;
+};
+export declare namespace renderAlertMessage {
+    type LinkRendererProps = Omit<Extract<AlertMessage[number], {
+        tag: 'a';
+    }>, 'tag' | 'text'> & {
+        children: ReactNode;
+    };
+    export type LinkRenderer = (props: LinkRendererProps) => ReactNode;
+    export {};
+}
+export {};

package/esm/alertsStore/react.js

@@ -0,0 +1,58 @@
+import React, { useEffect, useState } from 'react';
+/**
+ * Factory function that creates a React subscription hook and a container
+ * component linked to a specific alerter store subscibe function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#makereactsubscription
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const makeReactSubscription = (subscribe) => {
+    const useAlerter = () => {
+        const [alerts, setAlerts] = useState([]);
+        useEffect(() => subscribe((alerts) => setAlerts(alerts)), []);
+        return alerts;
+    };
+    const AlertsContainer = (props) => {
+        const alerts = useAlerter();
+        return props.children(alerts);
+    };
+    return {
+        useAlerter,
+        AlertsContainer,
+    };
+};
+/**
+ * Helper to render an alerter alert message, which can be a simple string or a
+ * more complex array of strings and objects representing links and rich (bold)
+ * text formatting.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessage
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export const renderAlertMessage = (message, linkComponent) => {
+    const Link = linkComponent || 'a';
+    return typeof message === 'string'
+        ? message
+        : message.flatMap((part, i) => {
+            if (typeof part === 'string') {
+                return ` ${part}`;
+            }
+            if (part.tag === 'a') {
+                const { text, tag, ...linkProps } = part;
+                return [
+                    ' ',
+                    React.createElement(Link, { key: i, ...linkProps }, text),
+                ];
+            }
+            return [' ', React.createElement(part.tag, { key: i }, part.text)];
+        });
+};
+/**
+ * Retrns a curried version of `renderAlertMessage` that uses the provided
+ * `LinkComponent` for rendering links in alert messages.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#renderalertmessagewithlinkrenderer
+ */
+/*#__NO_SIDE_EFFECTS__*/
+renderAlertMessage.withLinkRenderer =
+    (LinkCompnent) => (message) => renderAlertMessage(message, LinkCompnent);

package/esm/async.d.ts

@@ -102,7 +102,7 @@ export declare const cachifyAsync: <R, F extends (...args: Array<any>) => Promis
      * Function to optionally set a custom TTL on success and/or error results,
      * when the promise resolves.
      *
-     * If `undefined` is returned, the default `ttlMs` and` `throttleMs` settings
+     * If `undefined` is returned, the default `ttl` and` `throttle` settings
      * are used.
      */
     customTtl?: (args: Parameters<F>, result: Result.TupleObj<R>) => TTL | undefined;

package/esm/async.js

@@ -190,6 +190,7 @@ const DEFAULT_THROTTLING_MS = '30s';
  *
  * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#cachifyasync
  */
+/*#__NO_SIDE_EFFECTS__*/
 export const cachifyAsync = (opts) => {
     const { fn, getKey = (...args) => JSON.stringify(args), customTtl, returnStale } = opts;
     // Set up the cache object

package/esm/index.d.ts

@@ -5,9 +5,11 @@
 /// <reference path="./fixIcelandicLocale.d.ts" />
 /// <reference path="./errorhandling.d.ts" />
 /// <reference path="./react-router/http.d.ts" />
+/// <reference path="./alertsStore/index.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />
 /// <reference path="./react-router/Wait.d.tsx" />
+/// <reference path="./alertsStore/react.d.tsx" />
 /// <reference path="./next/http.d.tsx" />
 
 export {};

package/index.d.ts

@@ -5,9 +5,11 @@
 /// <reference path="./fixIcelandicLocale.d.ts" />
 /// <reference path="./errorhandling.d.ts" />
 /// <reference path="./react-router/http.d.ts" />
+/// <reference path="./alertsStore/index.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />
 /// <reference path="./react-router/Wait.d.tsx" />
+/// <reference path="./alertsStore/react.d.tsx" />
 /// <reference path="./next/http.d.tsx" />
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.3.6",
+	"version": "0.3.8",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",
@@ -11,7 +11,8 @@
 	],
 	"license": "MIT",
 	"dependencies": {
-		"@reykjavik/hanna-utils": "^0.2.20"
+		"@reykjavik/hanna-utils": "^0.2.22",
+		"valibot": "^1.2.0"
 	},
 	"peerDependencies": {
 		"@vanilla-extract/css": "^1.14.1",
@@ -76,6 +77,10 @@
 			"import": "./esm/react-router/http.js",
 			"require": "./react-router/http.js"
 		},
+		"./alertsStore": {
+			"import": "./esm/alertsStore/index.js",
+			"require": "./alertsStore/index.js"
+		},
 		"./SiteImprove": {
 			"import": "./esm/SiteImprove.js",
 			"require": "./SiteImprove.js"
@@ -88,6 +93,10 @@
 			"import": "./esm/react-router/Wait.js",
 			"require": "./react-router/Wait.js"
 		},
+		"./alertsStore/react": {
+			"import": "./esm/alertsStore/react.js",
+			"require": "./alertsStore/react.js"
+		},
 		"./next/http": {
 			"import": "./esm/next/http.js",
 			"require": "./next/http.js"