@reykjavik/webtools 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.3.7
+
+_2026-03-16_
+
+- feat: Add `@reykjavik/webtools/alertsStore` for toasts and other global UI
+  feedback messages along with `@reykjavik/webtools/alertsStore/react` helpers
+
 ## 0.3.6
 
 _2026-02-24_

package/README.md

@@ -49,6 +49,13 @@ bun add @reykjavik/webtools
   - [`Result.throw`](#resultthrow)
   - [Type `Result.PayloadOf`](#type-resultpayloadof)
   - [Type `Result.ErrorOf`](#type-resulterrorof)
+- [`@reykjavik/webtools/alertsStore`](#reykjavikwebtoolsalertsstore)
+  - [`createAlerterStore`](#createalerterstore)
+    - [type `AlerterConfig`](#type-alerterconfig)
+  - [`@reykjavik/webtools/alertsStore/react`](#reykjavikwebtoolsalertsstorereact)
+    - [`makeReactSubscription`](#makereactsubscription)
+    - [`renderAlertMessage`](#renderalertmessage)
+    - [`renderAlertMessage.withLinkRenderer`](#renderalertmessagewithlinkrenderer)
 - [`@reykjavik/webtools/SiteImprove`](#reykjavikwebtoolssiteimprove)
   - [`SiteImprove` component](#siteimprove-component)
   - [`pingSiteImprove` helper](#pingsiteimprove-helper)
@@ -962,6 +969,274 @@ it's a subtype of `ResultTuple`.
 
 ---
 
+## `@reykjavik/webtools/alertsStore`
+
+A small JS alerts store for toasts and other global UI feedback messages.
+
+Persists alerts to `sessionStorage` to survive browser reloads, and provides a
+simple pub/sub API for components to subscribe to alert changes.
+
+### `createAlerterStore`
+
+**Syntax:**
+`createAlerterStore(cfg?: AlerterConfig): { alerter: Record<Level, (payload: AlertPayload>) => void, subscribe: (callback: (alerts: Array<AlertInfo>, meta: { type: EventType, ids: Array<string> }) => void) => unsubscribe() => void; }`
+
+Factory function that instantiates a new alerter store and returns a strongly
+typed object with the following properties:
+
+- `alerter`: A singleton object with methods for dispatching new 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.
+- `subscribe`: A function for subscribing to alert changes. It accepts a
+  callback that gets called with the current list of alerts and some metadata
+  whenever an alert is added or cleared.  
+  The callback is called immediately upon subscription if there are already
+  active alerts.  
+  It returns an unsubscribe function to stop receiving updates.
+
+Simple useage with default settings:
+
+```ts
+// ---------------------------------------------------------------------------
+// alerterStore.ts
+// ---------------------------------------------------------------------------
+
+import { createAlerterStore } from '@reykjavik/webtools/alertsStore';
+import type { InferSubscriberAlerts, InferAlerterPayload } from '@reykjavik/webtools/alertsStore';
+
+const { alerter, subscribe } = createAlerterStore();
+
+export { alerter, subscribe };
+export type AlertPayload = InferAlerterPayload(typeof alerter);
+export type AlertInfo = InferSubscriberAlerts<typeof subscribe>;
+
+// ---------------------------------------------------------------------------
+// appRoot.ts
+// ---------------------------------------------------------------------------
+
+import { subscribe } from '../alerterStore';
+
+const unsubscribe = subscribe((alerts, meta) => {
+  console.log('Current alerts:', alerts);
+  console.log('Change type:', meta.type);
+  console.log('Affected alert IDs:', meta.ids);
+});
+
+// Stop receiving updates after 1 hour
+setTimeout(unsubscribe, 3_600_000);
+
+// ---------------------------------------------------------------------------
+// someOtherModule.ts
+// ---------------------------------------------------------------------------
+
+import { alerter } from '../alerterStore';
+alerter.success({
+  message: 'All is good',
+  // type: 'something',
+  // flags: ['pristine'],
+  duration: 'MEDIUM',
+  delay: 500, // Optional delay
+});
+// after 500ms the above alert is added to the store, and all subscribers
+// are notified. The subscriber in `appRoot.ts` will log the following;
+/*
+  Current alerts: [
+    {
+      id: '_234566-27_', // autugenerated
+      level: 'success',
+      message: 'All is good',
+      duration: 5000, // ms
+      dismiss: <Function>,
+      setFalgs: <Function>,
+    }
+  ]
+  Change type: 'add'
+  Affected alert IDs: ['_234566-27_']
+*/
+```
+
+Note how the `AlertPayload` and `AlertInfo` types are inferred from the
+generated `alerter` and the `subscribe` functions, respectively, using the
+provided `InferAlerterPayload` and `InferSubscriberAlerts` utility types.
+
+#### type `AlerterConfig`
+
+The `createAlerter` function accepts an optional configuration object that
+allows the customization of all of the accepted alert values and durations.
+
+The configuration values affect the type signatures of the generated `alerter`
+and the `subscribe` functions. (See `InferAlerterPayload` and
+`InferSubscriberAlerts` below)
+
+The configuration options are as follows:
+
+- **`key?: string`**  
+  Identifier for the alerts store, used to create the key to persist alerts in
+  `sessionStorage` (or other provided storage).  
+  Required if you want to have multiple independent alert stores in the same
+  application.  
+  Default: `'app-alerts'`.
+
+- **`levels?: Array<string>`**  
+  The accepted alert levels. The returned `alerter` object has a named
+  dispatcher method for each level.  
+  Default: `['success', 'info', 'warning', 'error']`.
+
+- **`types?: Array<string>`**  
+  The allowed alert "types", which can be used to, for example, dispatch both
+  "toasts" vs. "static alert banners" via the same store.  
+  This can also be used for more basic styling or categorization purposes.  
+  Default: no restrictions, any string value is allowed.
+
+- **`flags?: Array<string>`**  
+  The allowed alert "flags", which can be changed during the lifetime of an
+  alert using the `setFlags` function on the `AlertInfo` object.  
+  This can be used for styling or any other purpose you like.  
+  Default: no restriction, any string value is allowed.
+
+- **`durations?: Record<string, number>`**  
+  The allowed alert "duration" names and their lengths in milliseconds.
+  Default:
+  `{ BLINK: 2_000, SHORT: 4_000, MEDIUM: 8_000, LONG: 16_000, XLONG: 32_000, INDEFINITE: 0 }`.
+
+- **`defaultDuration?: string`**  
+  The duration to use for alerts if no duration is specified when
+  dispatching.  
+  Default: `SHORT` if using the default durations, otherwise the default is
+  `0` (indefinite)
+
+- **`storage?: Pick<Storage, 'getItem' | 'setItem'>`**  
+  The storage object to use instead of `sessionStorage` (the default) for
+  persisting alerts across page reloads, etc.
+
+### `@reykjavik/webtools/alertsStore/react`
+
+#### `makeReactSubscription`
+
+**Syntax:**
+`makeReactSubscription(): { useAlerter: () => Array<AlertInfo>, AlertsContainer: (props: { children: (alerts: Array<alertInfo>) => ReactNode }) => ReactNode }`
+
+Factory function that creates a React subscription hook and a container
+component linked to a specific alerter store subscibe function.
+
+The returned `useAlerter` hook can be used in any React component to get the
+current list of alerts from the store
+
+Meanwhile the `AlertsContainer` is a sugar component that calls `useAlerter()`
+internally and provides the current alerts list to its child as a render prop.
+
+The returned list and its items and their properties are all immutable/stable
+so you can safely use them as dependencies in React hooks, etc.
+
+```ts
+// ---------------------------------------------------------------------------
+// alerterStore.ts
+// ---------------------------------------------------------------------------
+
+import { createAlerterStore } from '@reykjavik/webtools/alertsStore';
+import { makeReactSubscription } from '@reykjavik/webtools/alertsStore/react';
+
+const { alerter, subscribe } = createAlerterStore();
+
+export { alerter };
+export const { useAlerter, AlertsContainer } =
+  makeReactSubscription(subscribe);
+
+// ---------------------------------------------------------------------------
+// app.tsx
+// ---------------------------------------------------------------------------
+
+import { AlertsContainer } from '../alerterStore';
+import { Toast } from '../components/Toast';
+
+// In your App JSX
+<AlertsContainer>
+  {(alerts) => (
+    <div class="toastcontainer">
+      {alerts.map((alert) => (
+        <Toast key={alert.id} {...alert} />
+      ))}
+    </div>
+  )}
+</AlertsContainer>;
+```
+
+#### `renderAlertMessage`
+
+**Syntax:**
+`renderAlertMessage(message: AlertInfo['message'], linkComponent?: renderAlertMessage.LinkRenderer): 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.
+
+It renders link objects as simple `<a href="" />` elements, by default, but
+you can optionally provide a custom `linkComponent` as a second parameter.
+
+Third
+
+```ts
+import { renderAlertMessage } from '@reykjavik/webtools/alertsStore/react';
+import Link from 'next/link';
+
+import { AlertInfo } from '../alertsStore';
+
+export const Toast = (props: AlertInfo) => {
+  const dismissOnLinkClick = (e: React.MouseEvent) => {
+    if ((e.target as HTMLElement).closest('a')) {
+      props.dismiss(); // Dismiss the alert when a link is clicked
+    }
+  };
+  return (
+    <div class="toast" onClick={dismissOnLinkClick}>
+      {renderAlertMessage(props.message, Link)}
+    </div>
+  );
+};
+```
+
+To build your own custom `LinkComponent`, you can use the
+`renderAlertMessage.LinkRenderer` type for the function signature.
+
+```ts
+import { renderAlertMessage } from '@reykjavik/webtools/alertsStore/react';
+import { Link } from 'react-router';
+
+const MyWrappedLink: renderAlertMessage.LinkRenderer = (props) => {
+  const { href, ...linkProps } = props;
+  return <Link to={href} {...linkProps} />;
+};
+
+// Then elsewhere in your Alert/Toast component
+<div class="toast__message">
+  {renderAlertMessage(props.message, MyWrappedLink)};
+</div>;
+```
+
+Alternatively, if you want to avoid passing the `LinkComponent` every time you
+call `renderAlertMessage`, you can use the
+`renderAlertMessage.withLinkRenderer` helper
+
+#### `renderAlertMessage.withLinkRenderer`
+
+**Syntax:**
+`renderAlertMessage.withLinkRenderer(LinkComponent: renderAlertMessage.LinkRenderer): (message: AlertInfo['message']):ReactNode`
+
+It returns a curried version of [`renderAlertMessage`](#renderAlertMessage)
+that uses the passed `LinkComponent` for rendering links in alert messages.
+
+```ts
+const curriedRenderAlertMessage =
+  renderAlertMessage.withLinkRenderer(MyWrappedLink);
+
+// Then elsewhere in your Alert/Toast component
+<div class="toast__message">
+  {renderAlertMessage(props.message, MyWrappedLink)};
+</div>;
+```
+
+---
+
 ## `@reykjavik/webtools/SiteImprove`
 
 Contains React helpers for loading SiteImprove's analytics scripts, and

package/alertsStore/index.d.ts

@@ -0,0 +1,201 @@
+import * as v from 'valibot';
+declare const messageSchema: v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly tag: v.LiteralSchema<"a", undefined>;
+    readonly text: v.StringSchema<undefined>;
+    readonly href: v.StringSchema<undefined>;
+    readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly hrefLang: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly lang: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly tag: v.LiteralSchema<"strong", undefined>;
+    readonly text: v.StringSchema<undefined>;
+}, undefined>], undefined>, undefined>], undefined>;
+export type AlertMessage = v.InferOutput<typeof messageSchema>;
+type _AlertNotification<Level, Type, Flag> = {
+    level: Level;
+    message: AlertMessage;
+    type?: Type;
+    flags?: Array<Flag>;
+    duration?: number;
+    id: string;
+};
+declare const defaultAlertLevels: readonly ["info", "warning", "success", "error"];
+declare const defaultDurations: {
+    BLINK: number;
+    SHORT: number;
+    MEDIUM: number;
+    LONG: number;
+    XLONG: number;
+    INDEFINITE: number;
+};
+/**
+ * A configuration object for the `createAlerter` factory function, that allows
+ * the customization of all of the accepted alert values and durations.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#type-alerterconfig
+ */
+export type AlerterConfig<Level extends string = (typeof defaultAlertLevels)[number], Type extends string = string, Flag extends string = string, Duration extends string = keyof typeof defaultDurations, Durations extends Record<Duration, number> = Record<Duration, number>> = {
+    /**
+     * Identifier for the alerts store, used to create the key to persist alerts
+     * in `sessionStorage` (or other provided storage).
+     *
+     * Only required if you need to create multiple independent alert stores in
+     * the same app.
+     *
+     * Default: `"app~alerts"`
+     */
+    key?: string;
+    /**
+     * The allowed alert "levels". The returned `alerter` object will have a
+     * named dispatcher method for each level.
+     *
+     * Default: `['info', 'warning', 'success', 'error']`
+     */
+    levels?: Array<Level>;
+    /**
+     * The allowed alert "types", which can be used to, for example, to dispatch
+     * both "toasts" vs. "static alert banners" via the same store.
+     *
+     * This can also be used for more basic styling or categorization purposes.
+     *
+     * Default: no restrictions, any string value is allowed.
+     */
+    types?: Array<Type>;
+    /**
+     * The allowed alert "flags", which can be changed during the lifetime of
+     * an alert using the `setFlags` function on the `AlertInfo` object.
+     *
+     * This can be used for styling or any other purpose you like.
+     *
+     * Default: no restriction, any string value is allowed.
+     */
+    flags?: Array<Flag>;
+    /**
+     * Optionally controls the allowed alert "duration" names and their lengths
+     * in milliseconds.
+     *
+     * Default:
+     * ```ts
+     *  {
+          BLINK: 2_000,
+          SHORT: 4_000,
+          MEDIUM: 8_000,
+          LONG: 16_000,
+          XLONG: 32_000,
+          INDEFINITE: 0,
+        }
+      * ```
+      */
+    durations?: Durations;
+    /**
+     * Default duration to use for alerts if no duration is specified when
+     * dispatching.
+     *
+     * Default: `SHORT` if using the default durations, otherwise the default
+     * is `0` (indefinite)
+     */
+    defaultDuration?: Durations extends Record<infer D, number> ? D : never;
+    /**
+     * Optional custom storage object to use instead of `sessionStorage` (the
+     * default) for persisting alerts across page reloads, etc.
+     */
+    storage?: {
+        getItem: (key: string) => string | undefined | null;
+        setItem: (key: string, value: string) => void;
+    };
+};
+/**
+ * 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
+ */
+export declare const createAlerterStore: <Level extends string = (typeof defaultAlertLevels)[number], Type extends string = string, Flag extends string = string, Duration extends string = keyof typeof defaultDurations>(cfg?: AlerterConfig<Level, Type, Flag, Duration>) => {
+    /**
+     * 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: Record<Level, (payload: {
+        /**
+         * A simple string containing the alert message.
+         *
+         * For sightly more complex alert messages pass an array of strings
+         * (representing text nodes), objects with `tag: 'a'` and hyperlink-related
+         * props, or `tag: 'strong'` objects for minimal rich formatting.
+         *
+         * (Assume that such array itmes will be rendered with whitespace between
+         * them.)
+         */
+        message: AlertMessage;
+        /**
+         * Allows distinguishing between different "types" of alerts, for example,
+         * to dispatch both "toasts" vs. "static alert banners" via the same store.
+         *
+         * May also be used for more basic styling or categorization purposes.
+         */
+        type?: Type;
+        /**
+         * Flag values can be changed during the lifetime of
+         * an alert using the `setFlags` function on each `AlertInfo` object.
+         *
+         * Flags may be used for styling or any other purpose you like.
+         */
+        flags?: Array<Flag>;
+        /**
+         * Hint for how long the notification should remain displayed before
+         * auto-dismissing.
+         *
+         * **NOTE:** The alerter store does not implement auto-dismissing. However,
+         * this value can be used by UI component that actually render the alert,
+         * by calling each `AlertInfo`'s `dismiss` method.
+         */
+        duration?: Duration;
+        delay?: number;
+    }) => void>;
+    /**
+     * 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: (callback: (notifications: Array<_AlertNotification<Level, Type, Flag> & {
+        /** Dispatcher function that dismisses/hides/removes the callback */
+        dismiss: () => void;
+        /**
+         * Dispatcher function that can be used to set a simple "flag" on the alert,
+         * which can be used for styling or other purposes.
+         */
+        setFlags: (value: Flag | Array<Flag> | ((flags: Array<Flag> | undefined) => Array<Flag> | undefined)) => void;
+    }>, meta: {
+        type: "clear" | "add" | "change";
+        /** IDs of the alerts that were added or cleared in this event. */
+        ids: Array<string>;
+    }) => void) => () => void;
+};
+/**
+ * Utility type for inferring the payload shape of the dispatching methods of a
+ * specific `alerter` singleton.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+export type InferAlerterPayload<F extends Record<string, (...args: Array<any>) => void>> = F extends Record<string, (payload: infer P) => void> ? P : never;
+/**
+ * Utility type for inferring the alert info object shape received by the
+ * callbacks of a specific alerter `subscribe` function.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.3/README.md#createalerterstore
+ */
+export type InferSubscriberAlerts<F extends (callback: (alerts: Array<unknown>, meta: unknown) => void) => () => void> = F extends (callback: (alerts: Array<infer A>) => void) => () => void ? A : never;
+export {};