@obinexusltd/obix-component-toast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OBINexus Computing — Nnamdi Michael Okpala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @obinexusltd/obix-component-toast
+
+**The `ObixToast` feedback component** — a transient notification with `role="status"`, six screen positions, an auto-dismiss `duration`, and `pause-on-hover`.
+
+Split out of `@obinexusltd/obix-component-feedback` as an independent package.
+
+```bash
+npm install @obinexusltd/obix-component-toast
+```
+
+> **Zero dependencies.** Data-Oriented: `createX(config)` returns
+> `{ name, state, actions, render }`. Actions are pure
+> `(state, …args) => newState`; `render(state)` is deterministic, HTML-escaped
+> markup (an empty string while hidden). `renderX(config, overrides?)` renders
+> in one call.
+
+## API
+
+```ts
+import { createToast, renderToast } from "@obinexusltd/obix-component-toast";
+
+const el = createToast({ /* see docs/02-usage.md */ });
+el.render(el.state);
+renderToast({ /* config */ });   // one call
+```
+
+**Actions** — `show(state)` · `hide(state)` · `dismiss(state)` · `setMessage(state, message)` · `setDuration(state, ms)`
+
+## Documentation
+
+| # | Guide |
+|---|-------|
+| 01 | [Overview](docs/01-overview.md) |
+| 02 | [Usage & API](docs/02-usage.md) |
+| 03 | [Accessibility](docs/03-accessibility.md) |
+| 04 | [State & rendered HTML](docs/04-state-and-html.md) |
+
+## Related
+
+Part of the OBIX feedback set: `@obinexusltd/obix-component-``toast` · `alert` · `progress` · `loading`.
+
+## License
+
+MIT — OBINexus Computing

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { DOPComponent, ToastConfig, ToastState } from "./types.js";
+export type { Action, DOPComponent, ToastConfig, ToastPosition, ToastState, ToastType, } from "./types.js";
+export declare function createToast(config: ToastConfig): DOPComponent<ToastState>;
+export declare function renderToast(config: ToastConfig, overrides?: Partial<ToastState>): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExE,YAAY,EACV,MAAM,EACN,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAuBpB,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC,UAAU,CAAC,CAwBzE;AAGD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,MAAM,CAG5F"}

package/dist/index.js

@@ -0,0 +1,45 @@
+function esc(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function renderToastHtml(state) {
+    if (!state.visible)
+        return "";
+    return (`<div id="${state.toastId}"` +
+        ` class="obix-toast obix-toast--${state.type} obix-toast--${state.position}"` +
+        ` role="status" aria-live="polite" aria-atomic="true"` +
+        ` data-jfix-strategy="box-shadow" data-pause-on-hover="${state.pauseOnHover}">` +
+        `<span class="obix-toast__message">${esc(state.message)}</span>` +
+        `<button class="obix-toast__dismiss obix-button" type="button" aria-label="Dismiss notification">×</button>` +
+        `</div>`);
+}
+export function createToast(config) {
+    if (!config || typeof config.message !== "string") {
+        throw new TypeError("[obix-component-toast] createToast: `message` is required");
+    }
+    const state = {
+        message: config.message,
+        type: config.type ?? "info",
+        visible: true,
+        duration: config.duration ?? 5000,
+        position: config.position ?? "bottom-right",
+        toastId: config.id ?? "obix-toast",
+        pauseOnHover: config.pauseOnHover ?? true,
+    };
+    const actions = {
+        show: (s) => ({ ...s, visible: true }),
+        hide: (s) => ({ ...s, visible: false }),
+        dismiss: (s) => ({ ...s, visible: false }),
+        setMessage: (s, message) => ({ ...s, message: String(message) }),
+        setDuration: (s, duration) => ({ ...s, duration: Number(duration) }),
+    };
+    return { name: "ObixToast", state, actions, render: renderToastHtml };
+}
+export function renderToast(config, overrides = {}) {
+    const toast = createToast(config);
+    return toast.render({ ...toast.state, ...overrides });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,eAAe,CAAC,KAAiB;IACxC,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAC9B,OAAO,CACL,YAAY,KAAK,CAAC,OAAO,GAAG;QAC5B,kCAAkC,KAAK,CAAC,IAAI,gBAAgB,KAAK,CAAC,QAAQ,GAAG;QAC7E,sDAAsD;QACtD,yDAAyD,KAAK,CAAC,YAAY,IAAI;QAC/E,qCAAqC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS;QAChE,4GAA4G;QAC5G,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,KAAK,GAAe;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,MAAM;QAC3B,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc;QAC3C,OAAO,EAAE,MAAM,CAAC,EAAE,IAAI,YAAY;QAClC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;KAC1C,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,IAAI,EAAE,CAAC,CAAa,EAAc,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC9D,IAAI,EAAE,CAAC,CAAa,EAAc,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC/D,OAAO,EAAE,CAAC,CAAa,EAAc,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAClE,UAAU,EAAE,CAAC,CAAa,EAAE,OAAgB,EAAc,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACjG,WAAW,EAAE,CAAC,CAAa,EAAE,QAAiB,EAAc,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;KACtG,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AACxE,CAAC;AAGD,MAAM,UAAU,WAAW,CAAC,MAAmB,EAAE,YAAiC,EAAE;IAClF,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export type Action<S> = (state: S, ...args: any[]) => S;
+export interface DOPComponent<S> {
+    name: string;
+    state: S;
+    actions: Record<string, Action<S>>;
+    render: (state: S) => string;
+}
+export type ToastType = "info" | "warning" | "error" | "success";
+export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export interface ToastConfig {
+    message: string;
+    type?: ToastType;
+    duration?: number;
+    position?: ToastPosition;
+    pauseOnHover?: boolean;
+    id?: string;
+}
+export interface ToastState {
+    message: string;
+    type: ToastType;
+    visible: boolean;
+    duration: number;
+    position: ToastPosition;
+    toastId: string;
+    pauseOnHover: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAExD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjE,MAAM,MAAM,aAAa,GACrB,UAAU,GAAG,YAAY,GAAG,WAAW,GACvC,aAAa,GAAG,eAAe,GAAG,cAAc,CAAC;AAErD,MAAM,WAAW,WAAW;IAE1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;CACvB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/01-overview.md

@@ -0,0 +1,26 @@
+# ObixToast — Overview
+
+`@obinexusltd/obix-component-toast` is one feedback component from the OBIX component set, packaged
+on its own. It is **Data-Oriented** and has **zero runtime dependencies**.
+
+## The shape
+
+```ts
+const toast = createToast(config);
+toast.name      // "ObixToast"
+toast.state     // the full component state (see docs/04)
+toast.actions   // pure (state, …args) => state transitions
+toast.render    // (state) => string  — deterministic, HTML-escaped
+```
+
+- **No classes, no lifecycle, no DOM.** Data plus pure functions. You own
+  the timers, event wiring, and where the HTML string goes.
+- **Deterministic render.** `render(state)` returns the same markup for the
+  same state, and an **empty string** while the component is hidden.
+- **Pure actions.** `actions.foo(state, …)` returns a *new* state.
+
+## When to use it
+
+Use `@obinexusltd/obix-component-toast` when you want just this one piece of feedback UI without
+pulling the whole feedback bundle.
+

package/docs/02-usage.md

@@ -0,0 +1,48 @@
+# ObixToast — Usage & API
+
+```ts
+import { createToast, renderToast } from "@obinexusltd/obix-component-toast";
+```
+
+## `createToast(config)`
+
+Returns a `DOPComponent`: `{ name, state, actions, render }`. Throws
+`TypeError` when a required field is missing or the wrong type.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `message` | `string` | **required** | Notification text |
+| `type` | `info \| warning \| error \| success` | `"info"` | Visual variant (`obix-toast--<type>`) |
+| `duration` | `number` | `5000` | Auto-dismiss delay in ms — **you own the timer**; `duration` is carried in state |
+| `position` | `top-left \| top-center \| top-right \| bottom-left \| bottom-center \| bottom-right` | `"bottom-right"` | Anchor class `obix-toast--<position>` |
+| `pauseOnHover` | `boolean` | `true` | Emits `data-pause-on-hover` for your timer logic |
+| `id` | `string` | `"obix-toast"` | DOM id — **set a unique value per toast** |
+
+The full `Config` / `State` interfaces are in
+[`src/types.ts`](../src/types.ts), which ships in the package.
+
+## `renderToast(config, overrides?)`
+
+One-call render — `createToast(config).render({ ...state, ...overrides })`.
+Pass `{ visible: true }` as an override to render a normally-hidden state for
+snapshots / SSR:
+
+```ts
+renderToast(config, { visible: true });
+```
+
+## Actions
+
+`show(state)` · `hide(state)` · `dismiss(state)` · `setMessage(state, message)` · `setDuration(state, ms)`.
+
+Every action is `(state, …args) => newState` and **pure**. Thread state through
+them (directly or via your store) and re-render:
+
+```ts
+const t = createToast({ message: "File saved", type: "success", position: "top-right" });
+mount.innerHTML = t.render(t.state);          // visible
+setTimeout(() => { mount.innerHTML = t.render(t.actions.dismiss(t.state)); }, t.state.duration); // "" -> removed
+```
+
+`render(state)` returns `""` whenever the component is not visible — assigning
+it to `innerHTML` cleanly removes the element.

package/docs/03-accessibility.md

@@ -0,0 +1,17 @@
+# ObixToast — Accessibility
+
+The rendered HTML carries its ARIA inline — there is no separate a11y layer.
+
+- Live-region semantics are built in: `role` / `aria-live` / `aria-atomic`
+  are set from state (e.g. assertive for errors, polite for status).
+- All interpolated text (messages, labels) is HTML-escaped.
+- Dismiss controls are real `<button type="button">` with an `aria-label`.
+
+## Your responsibilities
+
+- Insert the rendered string into a container that already exists in the DOM
+  so the live region is announced when content changes.
+- Drive timers yourself (e.g. call `dismiss` after `state.duration` ms).
+- Manage focus: for a dismissible alert, return focus to the triggering
+  element (`returnFocusId` is carried in state for you to use).
+- Render one instance per container; give toasts a unique `id`.

package/docs/04-state-and-html.md

@@ -0,0 +1,22 @@
+# ObixToast — State & rendered HTML
+
+## State
+
+The full state object is defined by the `State` interface in
+[`src/types.ts`](../src/types.ts), built from `config` by
+`createToast`. Plain JSON-serialisable data.
+
+## Rendered HTML
+
+`render(state)` returns a single element as a string, or **`""`** when the
+component is not visible. Attribute order is fixed; only state-driven
+attributes/branches change between renders.
+
+Class names follow the `obix-*` convention
+(`obix-toast`, `obix-toast--<modifier>`).
+No CSS ships with the package.
+
+## Testing
+
+`test/*.test.mjs` (Node’s built-in runner) asserts the rendered string and
+action purity. Run `npm run build && npm test`.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@obinexusltd/obix-component-toast",
+  "version": "0.1.0",
+  "description": "OBIX ObixToast — a transient notification with role=\"status\", six screen positions, an auto-dismiss duration, and pause-on-hover. Data-Oriented, zero dependencies.",
+  "license": "MIT",
+  "author": "OBINexus Computing — Nnamdi Michael Okpala <okpalan@protonmail.com>",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "lib": "dist",
+    "doc": "docs",
+    "test": "test"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "obix",
+    "component",
+    "dop",
+    "accessibility",
+    "toast",
+    "notification",
+    "snackbar",
+    "feedback"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obinexusmk2/obix-component-toast.git"
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @obinexusltd/obix-component-toast
+ *
+ * The ObixToast feedback component — a transient notification with
+ * `role="status"`, six screen positions, an auto-dismiss `duration` (you own the
+ * timer), and `pause-on-hover`.
+ *
+ * Data-Oriented: `createToast(config)` returns `{ name, state, actions, render }`.
+ * Actions are pure `(state, …args) => ToastState`; `render(state)` is
+ * deterministic, HTML-escaped markup, or `""` while hidden. Zero dependencies.
+ *
+ * Split out of `@obinexusltd/obix-component-feedback`.
+ */
+import type { DOPComponent, ToastConfig, ToastState } from "./types.js";
+
+export type {
+  Action,
+  DOPComponent,
+  ToastConfig,
+  ToastPosition,
+  ToastState,
+  ToastType,
+} from "./types.js";
+
+function esc(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function renderToastHtml(state: ToastState): string {
+  if (!state.visible) return "";
+  return (
+    `<div id="${state.toastId}"` +
+    ` class="obix-toast obix-toast--${state.type} obix-toast--${state.position}"` +
+    ` role="status" aria-live="polite" aria-atomic="true"` +
+    ` data-jfix-strategy="box-shadow" data-pause-on-hover="${state.pauseOnHover}">` +
+    `<span class="obix-toast__message">${esc(state.message)}</span>` +
+    `<button class="obix-toast__dismiss obix-button" type="button" aria-label="Dismiss notification">×</button>` +
+    `</div>`
+  );
+}
+
+export function createToast(config: ToastConfig): DOPComponent<ToastState> {
+  if (!config || typeof config.message !== "string") {
+    throw new TypeError("[obix-component-toast] createToast: `message` is required");
+  }
+
+  const state: ToastState = {
+    message: config.message,
+    type: config.type ?? "info",
+    visible: true,
+    duration: config.duration ?? 5000,
+    position: config.position ?? "bottom-right",
+    toastId: config.id ?? "obix-toast",
+    pauseOnHover: config.pauseOnHover ?? true,
+  };
+
+  const actions = {
+    show: (s: ToastState): ToastState => ({ ...s, visible: true }),
+    hide: (s: ToastState): ToastState => ({ ...s, visible: false }),
+    dismiss: (s: ToastState): ToastState => ({ ...s, visible: false }),
+    setMessage: (s: ToastState, message: unknown): ToastState => ({ ...s, message: String(message) }),
+    setDuration: (s: ToastState, duration: unknown): ToastState => ({ ...s, duration: Number(duration) }),
+  };
+
+  return { name: "ObixToast", state, actions, render: renderToastHtml };
+}
+
+/** Render a toast's HTML in one call, optionally with state overrides. */
+export function renderToast(config: ToastConfig, overrides: Partial<ToastState> = {}): string {
+  const toast = createToast(config);
+  return toast.render({ ...toast.state, ...overrides });
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * @obinexusltd/obix-component-toast — types.
+ * Zero-dependency Data-Oriented component: { name, state, actions, render }.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export type Action<S> = (state: S, ...args: any[]) => S;
+
+export interface DOPComponent<S> {
+  name: string;
+  state: S;
+  actions: Record<string, Action<S>>;
+  render: (state: S) => string;
+}
+
+export type ToastType = "info" | "warning" | "error" | "success";
+
+export type ToastPosition =
+  | "top-left" | "top-center" | "top-right"
+  | "bottom-left" | "bottom-center" | "bottom-right";
+
+export interface ToastConfig {
+  /** Notification text. Required. */
+  message: string;
+  type?: ToastType;
+  /** Auto-dismiss delay in ms (you own the timer). Default `5000`. */
+  duration?: number;
+  position?: ToastPosition;
+  pauseOnHover?: boolean;
+  /** DOM id; a stable default is used when omitted — set a unique one per toast. */
+  id?: string;
+}
+
+export interface ToastState {
+  message: string;
+  type: ToastType;
+  visible: boolean;
+  duration: number;
+  position: ToastPosition;
+  toastId: string;
+  pauseOnHover: boolean;
+}

package/test/toast.test.mjs

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createToast, renderToast } from "../dist/index.js";
+
+test("factory returns a DOP component shape", () => {
+  const el = createToast({ message: "Hello & <world>" });
+  assert.equal(el.name, "ObixToast");
+  assert.equal(typeof el.render, "function");
+  assert.equal(typeof el.actions, "object");
+  assert.equal(typeof el.render(el.state), "string");
+});
+
+test("required config is validated", () => {
+  assert.throws(() => createToast(), TypeError);
+  assert.throws(() => createToast({}), TypeError);
+});
+
+test("render is deterministic", () => {
+  assert.equal(renderToast({ message: "Hello & <world>" }), renderToast({ message: "Hello & <world>" }));
+});
+
+test("text is escaped", () => {
+  const html = renderToast({ message: "a & b <x>" });
+  assert.match(html, /a &amp; b &lt;x&gt;/);
+  assert.doesNotMatch(html, /<x>/);
+});
+
+test("actions are pure — input state is untouched", () => {
+  const el = createToast({ message: "Hello & <world>" });
+  const before = JSON.stringify(el.state);
+  for (const k of Object.keys(el.actions)) el.actions[k](el.state, 1);
+  assert.equal(JSON.stringify(el.state), before);
+});