@pyreon/toast 0.11.0

package/src/tests/toast.test.ts

@@ -0,0 +1,247 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { _reset, _toasts, toast } from "../toast"
+
+/** Helper — get toast at index with non-null assertion (tests verify length first). */
+function at(index: number) {
+  const t = _toasts()[index]
+  if (!t) throw new Error(`No toast at index ${index}`)
+  return t
+}
+
+beforeEach(() => {
+  _reset()
+})
+
+afterEach(() => {
+  _reset()
+})
+
+describe("toast()", () => {
+  it("adds a toast to the stack", () => {
+    toast("Hello")
+    expect(_toasts().length).toBe(1)
+    expect(at(0).message).toBe("Hello")
+  })
+
+  it("returns the toast id", () => {
+    const id = toast("Hello")
+    expect(typeof id).toBe("string")
+    expect(id).toMatch(/^pyreon-toast-/)
+  })
+
+  it("defaults to type info", () => {
+    toast("Hello")
+    expect(at(0).type).toBe("info")
+  })
+
+  it("defaults dismissible to true", () => {
+    toast("Hello")
+    expect(at(0).dismissible).toBe(true)
+  })
+
+  it("respects custom options", () => {
+    toast("Hello", { type: "error", duration: 0, dismissible: false })
+    const t = at(0)
+    expect(t.type).toBe("error")
+    expect(t.duration).toBe(0)
+    expect(t.dismissible).toBe(false)
+  })
+})
+
+describe("toast.success/error/warning/info", () => {
+  it("toast.success sets type to success", () => {
+    toast.success("Done")
+    expect(at(0).type).toBe("success")
+  })
+
+  it("toast.error sets type to error", () => {
+    toast.error("Failed")
+    expect(at(0).type).toBe("error")
+  })
+
+  it("toast.warning sets type to warning", () => {
+    toast.warning("Watch out")
+    expect(at(0).type).toBe("warning")
+  })
+
+  it("toast.info sets type to info", () => {
+    toast.info("FYI")
+    expect(at(0).type).toBe("info")
+  })
+})
+
+describe("toast.dismiss", () => {
+  it("removes a specific toast by id", () => {
+    const id1 = toast("First")
+    toast("Second")
+    expect(_toasts().length).toBe(2)
+
+    toast.dismiss(id1)
+    expect(_toasts().length).toBe(1)
+    expect(at(0).message).toBe("Second")
+  })
+
+  it("clears all toasts when no id is given", () => {
+    toast("First")
+    toast("Second")
+    toast("Third")
+    expect(_toasts().length).toBe(3)
+
+    toast.dismiss()
+    expect(_toasts().length).toBe(0)
+  })
+
+  it("is a no-op for unknown id", () => {
+    toast("Hello")
+    toast.dismiss("unknown-id")
+    expect(_toasts().length).toBe(1)
+  })
+
+  it("calls onDismiss callback when dismissing by id", () => {
+    const onDismiss = vi.fn()
+    const id = toast("Hello", { onDismiss })
+    toast.dismiss(id)
+    expect(onDismiss).toHaveBeenCalledOnce()
+  })
+
+  it("calls onDismiss for all toasts when dismissing all", () => {
+    const onDismiss1 = vi.fn()
+    const onDismiss2 = vi.fn()
+    toast("First", { onDismiss: onDismiss1 })
+    toast("Second", { onDismiss: onDismiss2 })
+    toast.dismiss()
+    expect(onDismiss1).toHaveBeenCalledOnce()
+    expect(onDismiss2).toHaveBeenCalledOnce()
+  })
+})
+
+describe("auto-dismiss", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("auto-dismisses after default duration (4000ms)", () => {
+    toast("Hello")
+    expect(_toasts().length).toBe(1)
+
+    vi.advanceTimersByTime(3999)
+    expect(_toasts().length).toBe(1)
+
+    vi.advanceTimersByTime(1)
+    expect(_toasts().length).toBe(0)
+  })
+
+  it("auto-dismisses after custom duration", () => {
+    toast("Hello", { duration: 2000 })
+
+    vi.advanceTimersByTime(1999)
+    expect(_toasts().length).toBe(1)
+
+    vi.advanceTimersByTime(1)
+    expect(_toasts().length).toBe(0)
+  })
+
+  it("does not auto-dismiss when duration is 0", () => {
+    toast("Persistent", { duration: 0 })
+
+    vi.advanceTimersByTime(10000)
+    expect(_toasts().length).toBe(1)
+  })
+})
+
+describe("toast.promise", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("creates a loading toast that updates on resolve", async () => {
+    const promise = Promise.resolve("data")
+
+    toast.promise(promise, {
+      loading: "Loading...",
+      success: "Done!",
+      error: "Failed",
+    })
+
+    expect(_toasts().length).toBe(1)
+    expect(at(0).message).toBe("Loading...")
+    expect(at(0).type).toBe("info")
+    expect(at(0).duration).toBe(0) // persistent while loading
+
+    await promise
+    // Flush microtasks
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(_toasts().length).toBe(1)
+    expect(at(0).message).toBe("Done!")
+    expect(at(0).type).toBe("success")
+  })
+
+  it("creates a loading toast that updates on reject", async () => {
+    const promise = Promise.reject(new Error("oops"))
+
+    // Prevent unhandled rejection
+    toast
+      .promise(promise, {
+        loading: "Loading...",
+        success: "Done!",
+        error: "Failed",
+      })
+      .catch(() => {})
+
+    expect(at(0).message).toBe("Loading...")
+
+    try {
+      await promise
+    } catch {
+      // expected
+    }
+
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(_toasts().length).toBe(1)
+    expect(at(0).message).toBe("Failed")
+    expect(at(0).type).toBe("error")
+  })
+
+  it("supports function form for success/error messages", async () => {
+    const promise = Promise.resolve(42)
+
+    toast.promise(promise, {
+      loading: "Calculating...",
+      success: (data) => `Result: ${data}`,
+      error: (err) => `Error: ${err}`,
+    })
+
+    await promise
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(at(0).message).toBe("Result: 42")
+  })
+
+  it("returns the original promise", async () => {
+    const promise = Promise.resolve("value")
+    const result = toast.promise(promise, {
+      loading: "Loading...",
+      success: "Done!",
+      error: "Failed",
+    })
+
+    expect(await result).toBe("value")
+  })
+})
+
+describe("Toaster renders", () => {
+  it("Toaster is a function component", async () => {
+    const { Toaster } = await import("../toaster")
+    expect(typeof Toaster).toBe("function")
+  })
+})

package/src/toast.ts

@@ -0,0 +1,210 @@
+import type { VNodeChild } from "@pyreon/core"
+import { signal } from "@pyreon/reactivity"
+import type { Toast, ToastOptions, ToastPromiseOptions, ToastType } from "./types"
+
+// ─── State ───────────────────────────────────────────────────────────────────
+
+let _idCounter = 0
+const DEFAULT_DURATION = 4000
+
+/**
+ * Module-level signal holding the active toast stack.
+ * Consumed by the `Toaster` component.
+ */
+export const _toasts = signal<Toast[]>([])
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function generateId(): string {
+  return `pyreon-toast-${++_idCounter}`
+}
+
+function startTimer(t: Toast): void {
+  if (t.duration <= 0) return
+  t.timerStart = Date.now()
+  t.remaining = t.duration
+  t.timer = setTimeout(() => dismiss(t.id), t.duration)
+}
+
+function addToast(message: string | VNodeChild, options: ToastOptions = {}): string {
+  const id = generateId()
+  const t: Toast = {
+    id,
+    message,
+    type: options.type ?? "info",
+    duration: options.duration ?? DEFAULT_DURATION,
+    dismissible: options.dismissible ?? true,
+    action: options.action,
+    onDismiss: options.onDismiss,
+    state: "entering",
+    timer: undefined,
+    remaining: 0,
+    timerStart: 0,
+  }
+
+  startTimer(t)
+  _toasts.set([..._toasts(), t])
+
+  return id
+}
+
+function dismiss(id?: string): void {
+  const current = _toasts()
+
+  if (id === undefined) {
+    // Clear all
+    for (const t of current) {
+      if (t.timer !== undefined) clearTimeout(t.timer)
+      t.onDismiss?.()
+    }
+    _toasts.set([])
+    return
+  }
+
+  const match = current.find((item) => item.id === id)
+  if (!match) return
+
+  if (match.timer !== undefined) clearTimeout(match.timer)
+  match.onDismiss?.()
+  _toasts.set(current.filter((item) => item.id !== id))
+}
+
+function updateToast(
+  id: string,
+  updates: Partial<Pick<Toast, "message" | "type" | "duration">>,
+): void {
+  const current = _toasts()
+  const idx = current.findIndex((item) => item.id === id)
+  if (idx === -1) return
+
+  const t = current[idx] as Toast
+  if (t.timer !== undefined) clearTimeout(t.timer)
+
+  const updated: Toast = {
+    ...t,
+    message: updates.message ?? t.message,
+    type: updates.type ?? t.type,
+    duration: updates.duration ?? t.duration,
+    timer: undefined,
+    remaining: 0,
+    timerStart: 0,
+  }
+
+  const duration = updates.duration ?? t.duration
+  updated.duration = duration
+  startTimer(updated)
+
+  const next = [...current]
+  next[idx] = updated
+  _toasts.set(next)
+}
+
+// ─── Pause / resume (for hover) ─────────────────────────────────────────────
+
+export function _pauseAll(): void {
+  for (const t of _toasts()) {
+    if (t.timer !== undefined) {
+      clearTimeout(t.timer)
+      t.remaining = Math.max(0, t.remaining - (Date.now() - t.timerStart))
+      t.timer = undefined
+    }
+  }
+}
+
+export function _resumeAll(): void {
+  for (const t of _toasts()) {
+    if (t.duration > 0 && t.timer === undefined && t.remaining > 0) {
+      t.timerStart = Date.now()
+      t.timer = setTimeout(() => dismiss(t.id), t.remaining)
+    }
+  }
+}
+
+// ─── Public imperative API ───────────────────────────────────────────────────
+
+/**
+ * Show a toast notification.
+ *
+ * @example
+ * toast("Saved!")
+ * toast("Error occurred", { type: "error", duration: 6000 })
+ *
+ * @returns The toast id — pass to `toast.dismiss(id)` to remove it.
+ */
+export function toast(message: string | VNodeChild, options?: ToastOptions): string {
+  return addToast(message, options)
+}
+
+function shortcut(type: ToastType) {
+  return (message: string | VNodeChild, options?: Omit<ToastOptions, "type">): string =>
+    addToast(message, { ...options, type })
+}
+
+/** Show a success toast. */
+toast.success = shortcut("success")
+
+/** Show an error toast. */
+toast.error = shortcut("error")
+
+/** Show a warning toast. */
+toast.warning = shortcut("warning")
+
+/** Show an info toast. */
+toast.info = shortcut("info")
+
+/** Show a persistent loading toast. Returns id for later update/dismiss. */
+toast.loading = (
+  message: string | VNodeChild,
+  options?: Omit<ToastOptions, "type" | "duration">,
+): string => addToast(message, { ...options, type: "info", duration: 0 })
+
+/** Update an existing toast (message, type, duration). */
+toast.update = (
+  id: string,
+  updates: Partial<Pick<ToastOptions, "type" | "duration">> & { message?: string | VNodeChild },
+): void => updateToast(id, updates)
+
+/** Dismiss a specific toast by id, or all toasts if no id is given. */
+toast.dismiss = dismiss
+
+/**
+ * Show a loading toast that updates on promise resolution or rejection.
+ *
+ * @example
+ * toast.promise(saveTodo(), {
+ *   loading: "Saving...",
+ *   success: "Saved!",
+ *   error: "Failed to save",
+ * })
+ */
+toast.promise = function toastPromise<T>(
+  promise: Promise<T>,
+  opts: ToastPromiseOptions<T>,
+): Promise<T> {
+  const id = addToast(opts.loading, { type: "info", duration: 0 })
+
+  promise.then(
+    (data) => {
+      const msg = typeof opts.success === "function" ? opts.success(data) : opts.success
+      updateToast(id, { message: msg, type: "success", duration: DEFAULT_DURATION })
+    },
+    (err: unknown) => {
+      const msg = typeof opts.error === "function" ? opts.error(err) : opts.error
+      updateToast(id, { message: msg, type: "error", duration: DEFAULT_DURATION })
+    },
+  )
+
+  return promise
+}
+
+// ─── Test utilities ──────────────────────────────────────────────────────────
+
+/** @internal Reset state for testing. */
+export function _reset(): void {
+  const current = _toasts()
+  for (const t of current) {
+    if (t.timer !== undefined) clearTimeout(t.timer)
+  }
+  _toasts.set([])
+  _idCounter = 0
+}

package/src/toaster.tsx

@@ -0,0 +1,155 @@
+import type { VNodeChild } from "@pyreon/core"
+import { For, Portal } from "@pyreon/core"
+import { computed, effect, onCleanup } from "@pyreon/reactivity"
+import { toastStyles } from "./styles"
+import { _pauseAll, _resumeAll, _toasts, toast } from "./toast"
+import type { Toast, ToasterProps, ToastPosition } from "./types"
+
+// ─── Style injection ─────────────────────────────────────────────────────────
+
+let _styleInjected = false
+
+function injectStyles(): void {
+  if (_styleInjected) return
+  _styleInjected = true
+
+  const style = document.createElement("style")
+  style.setAttribute("data-pyreon-toast", "")
+  style.textContent = toastStyles
+  document.head.appendChild(style)
+}
+
+// ─── Position helpers ────────────────────────────────────────────────────────
+
+function getContainerStyle(position: ToastPosition, gap: number, offset: number): string {
+  const [vertical, horizontal] = position.split("-") as [string, string]
+
+  let style = `gap: ${gap}px;`
+
+  if (vertical === "top") {
+    style += ` top: ${offset}px;`
+  } else {
+    style += ` bottom: ${offset}px;`
+    style += " flex-direction: column-reverse;"
+  }
+
+  if (horizontal === "left") {
+    style += ` left: ${offset}px;`
+  } else if (horizontal === "center") {
+    style += " left: 50%; transform: translateX(-50%);"
+  } else {
+    style += ` right: ${offset}px;`
+  }
+
+  return style
+}
+
+// ─── Toaster component ──────────────────────────────────────────────────────
+
+/**
+ * Render component for toast notifications. Place once at your app root.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <>
+ *       <Toaster position="bottom-right" />
+ *       <MyApp />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function Toaster(props?: ToasterProps): VNodeChild {
+  const position = props?.position ?? "top-right"
+  const max = props?.max ?? 5
+  const gap = props?.gap ?? 8
+  const offset = props?.offset ?? 16
+
+  injectStyles()
+
+  // Promote "entering" toasts to "visible" on next frame.
+  // Only runs when there are actually entering toasts (early return guard).
+  effect(() => {
+    const toasts = _toasts()
+    const hasEntering = toasts.some((t) => t.state === "entering")
+    if (!hasEntering) return
+
+    const raf = requestAnimationFrame(() => {
+      const current = _toasts()
+      let changed = false
+      const next = current.map((t) => {
+        if (t.state === "entering") {
+          changed = true
+          return { ...t, state: "visible" as const }
+        }
+        return t
+      })
+      if (changed) _toasts.set(next)
+    })
+
+    onCleanup(() => cancelAnimationFrame(raf))
+  })
+
+  // Computed visible toasts — only the most recent `max` items
+  const visibleToasts = computed(() => _toasts().slice(-max))
+
+  const containerStyle = getContainerStyle(position, gap, offset)
+
+  return (
+    <Portal target={document.body}>
+      <section
+        class="pyreon-toast-container"
+        style={containerStyle}
+        aria-label="Notifications"
+        aria-live="polite"
+        onMouseEnter={_pauseAll}
+        onMouseLeave={_resumeAll}
+      >
+        <For each={visibleToasts} by={(t: Toast) => t.id}>
+          {(t: Toast) => <ToastItem toast={t} />}
+        </For>
+      </section>
+    </Portal>
+  )
+}
+
+// ─── Toast item ─────────────────────────────────────────────────────────────
+
+function ToastItem({ toast: t }: { toast: Toast }): VNodeChild {
+  const stateClass =
+    t.state === "entering"
+      ? " pyreon-toast--entering"
+      : t.state === "exiting"
+        ? " pyreon-toast--exiting"
+        : ""
+
+  return (
+    <div
+      class={`pyreon-toast pyreon-toast--${t.type}${stateClass}`}
+      role="alert"
+      aria-atomic="true"
+      data-toast-id={t.id}
+    >
+      <div class="pyreon-toast__message">
+        {typeof t.message === "string" ? t.message : t.message}
+      </div>
+      {t.action && (
+        <button type="button" class="pyreon-toast__action" onClick={t.action.onClick}>
+          {t.action.label}
+        </button>
+      )}
+      {t.dismissible && (
+        <button
+          type="button"
+          class="pyreon-toast__dismiss"
+          onClick={() => toast.dismiss(t.id)}
+          aria-label="Dismiss"
+        >
+          ×
+        </button>
+      )}
+    </div>
+  )
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+import type { VNodeChild } from "@pyreon/core"
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export type ToastPosition =
+  | "top-left"
+  | "top-center"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-center"
+  | "bottom-right"
+
+export type ToastType = "info" | "success" | "warning" | "error"
+
+export interface ToastOptions {
+  /** Toast variant — controls styling. */
+  type?: ToastType
+  /** Auto-dismiss delay in ms. Default: 4000. Set 0 for persistent. */
+  duration?: number
+  /** Screen position. Default: inherited from Toaster. */
+  position?: ToastPosition
+  /** Whether the toast shows a dismiss button. Default: true. */
+  dismissible?: boolean
+  /** Optional action button. */
+  action?: { label: string; onClick: () => void }
+  /** Called when the toast is dismissed (manually or by timeout). */
+  onDismiss?: () => void
+}
+
+export interface ToasterProps {
+  /** Default position for all toasts. Default: "top-right". */
+  position?: ToastPosition
+  /** Maximum visible toasts. Default: 5. */
+  max?: number
+  /** Gap between toasts in px. Default: 8. */
+  gap?: number
+  /** Offset from viewport edge in px. Default: 16. */
+  offset?: number
+}
+
+export interface ToastPromiseOptions<T> {
+  loading: string | VNodeChild
+  success: string | VNodeChild | ((data: T) => string | VNodeChild)
+  error: string | VNodeChild | ((err: unknown) => string | VNodeChild)
+}
+
+// ─── Internal types ──────────────────────────────────────────────────────────
+
+export type ToastState = "entering" | "visible" | "exiting"
+
+export interface Toast {
+  id: string
+  message: string | VNodeChild
+  type: ToastType
+  duration: number
+  dismissible: boolean
+  action: { label: string; onClick: () => void } | undefined
+  onDismiss: (() => void) | undefined
+  state: ToastState
+  timer: ReturnType<typeof setTimeout> | undefined
+  /** Remaining ms when timer was paused (hover). */
+  remaining: number
+  /** Timestamp when current timer started. */
+  timerStart: number
+}