@ailuracode/alpine-toast 0.1.1 → 2.0.0

package/README.md

@@ -1,26 +1,22 @@
 # @ailuracode/alpine-toast
 
-Headless in-app toast queue for Alpine.js via the `$toast` magic.
-
-**CSS-framework agnostic** — no markup, no styles. Only `default`, `bottom-right`, and `promise` are built into the API; you declare variants and positions your UI needs.
-
-**[Full documentation →](../../docs/toast.md)**
+Headless in-app toast queue for Alpine.js. Registers the `$toast` magic and an internal reactive store for UI integrators.
 
 ## Install
 
 ```bash
-npm install @ailuracode/alpine-toast alpinejs
+pnpm add @ailuracode/alpine-toast @ailuracode/alpine-core alpinejs
 ```
 
-## Quick example
+## Quick start
 
 ```js
 import Alpine from "alpinejs";
-import toast, { toastPositions, toastVariants } from "@ailuracode/alpine-toast";
+import toast, { toastOptions, toastPositions, toastVariants } from "@ailuracode/alpine-toast";
 
 Alpine.plugin(
-  toast({
-    variants: toastVariants(["success", "error", "loading"] as const),
+  toastOptions({
+    variants: toastVariants(["success", "info", "warning", "error", "loading"] as const),
     positions: toastPositions(["top-center", "bottom-right"] as const),
     defaultPosition: "bottom-right",
     promise: {
@@ -33,34 +29,295 @@ Alpine.plugin(
 Alpine.start();
 ```
 
+`toastOptions()`, `toastVariants()`, and `toastPositions()` preserve literal types for strongly typed payloads and `$toast.<variant>()` shortcuts.
+
+## CSS-framework agnostic
+
+This plugin ships **no HTML, no CSS, and no design tokens**. Variant and position names are **not hardcoded** — you declare the sets your UI needs. The only built-in concepts are:
+
+- **`default`** — `$toast('Message')` or `{ variant: 'default' }`
+- **`bottom-right`** — default `position` when omitted
+- **`promise`** — `$toast.promise(factoryOrPromise, messages?)`
+
+Map `toast.variant` and `toast.position` to layout/CSS in your own renderer (e.g. `data-position`, Tailwind classes, coordinates).
+
+## Magic API
+
+```js
+$toast("Hello")
+$toast({ title: "Saved", variant: "success", position: "top-center" })
+$toast.success("Saved") // only when "success" is in `variants`
+$toast.dismiss(id)
+$toast.dismissAt("top-center")
+$toast.dismissAll()
+$toast.fromPayload({ title: "Done", variant: "success" })
+await $toast.promise(() => save(), {
+  loading: "Saving...",
+  success: "Saved",
+  error: "Could not save",
+})
+```
+
+| Method | Description |
+|--------|-------------|
+| `$toast(title, options?)` | Push a `default` toast. Returns the toast id. |
+| `$toast(payload)` | Push with a full payload object. |
+| `$toast.<variant>(title, options?)` | One shortcut per entry in `variants`. |
+| `$toast.dismiss(id)` | Close one toast by id (returned from `$toast()`). |
+| `$toast.update(id, patch)` | Patch the same toast in place (variant, title, content, action, …). |
+| `$toast.dismissAt(position)` | Close every toast in one position stack. |
+| `$toast.dismissAll()` | Close every toast in every stack. |
+| `$toast.pushUnique(key, payload?)` | Dismiss active toasts with the same `key`, then push. |
+| `$toast.fromPayload(payload)` | Push from a plain payload (events, session flash, etc.). |
+| `$toast.promise(factoryOrPromise, messages?)` | `loading` → `success` / `error` on the same toast. |
+
+### Payload options
+
+| Field | Type | Default |
+|-------|------|---------|
+| `content` | `TContent \| null` | `null` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `variant` | `default \| …your variants` | `default` |
+| `position` | `bottom-right \| …your positions` | `bottom-right` (or `defaultPosition`) |
+| `duration` | `number` (ms) | `4000` (`false` or `0` = no auto-dismiss; stored as `false`) |
+| `action` | `{ label, onClick? }` | `null` |
+| `key` | `string \| null` | `null` — use with `pushUnique` for single-slot toasts |
+
+`title` / `description` are optional string shorthands. Use `content` for any shape your renderer understands (objects, arrays, HTML snippets, etc.). The plugin stores it as-is — rendering is up to your UI.
+
+```ts
+type AppToastContent = { user: { name: string; avatar: string } } | { html: string };
+
+type Item = ToastItem<typeof variants, typeof positions, AppToastContent>;
+
+$toast({
+  content: { user: { name: "Ada", avatar: "/ada.png" } },
+  variant: "success",
+});
+```
+
+```html
+<template x-for="toast in $store.toast.itemsAt(position)" :key="toast.id">
+  <div x-show="toast.content?.user">
+    <img :src="toast.content.user.avatar" alt="" />
+    <span x-text="toast.content.user.name"></span>
+  </div>
+  <p x-show="toast.title" x-text="toast.title"></p>
+</template>
+```
+
+For `$toast.promise`, optional `loadingContent`, `successContent`, and `errorContent` update the same toast item.
+
+## Custom variants
+
+```ts
+import toast, { toastOptions, toastVariants, type ToastMagic } from "@ailuracode/alpine-toast";
+
+const variants = toastVariants(["queued", "published", "failed"] as const);
+
+Alpine.plugin(toast({ variants }));
+
+type AppToast = ToastMagic<typeof variants>;
+// AppToast has .queued(), .published(), .failed()
+```
+
+Without `variants`, only `$toast()`, `$toast.promise()`, `$toast.dismiss()`, and `$toast.fromPayload()` are available.
+
+## Custom positions
+
+Each declared position gets its **own stack**. `maxToasts` and `maxVisible` apply **per position**, not globally.
+
+```ts
+import toast, { toastPositions, type ToastPosition } from "@ailuracode/alpine-toast";
+
+const positions = toastPositions(["top-center", "bottom-right"] as const);
+
+Alpine.plugin(
+  toast({
+    positions,
+    defaultPosition: "bottom-right",
+  })
+);
+
+type AppPosition = ToastPosition<typeof positions>;
+// "bottom-right" | "top-center"
+```
+
+The plugin stores the position id on each toast. Render one stack per position in your UI:
+
+```html
+<template x-for="position in $store.toast.stackPositions" :key="position">
+  <div
+    x-bind:data-position="position"
+    x-bind:class="{
+      'fixed top-4 left-1/2 -translate-x-1/2': position === 'top-center',
+      'fixed bottom-4 right-4': position === 'bottom-right',
+    }"
+  >
+    <template x-for="(toast, index) in $store.toast.itemsAt(position)" :key="toast.id">
+      <div x-show="!toast.removed && $store.toast.isVisibleAt(position, index)">
+        <p x-text="toast.title"></p>
+      </div>
+    </template>
+  </div>
+</template>
+```
+
+| Store API | Description |
+|-----------|-------------|
+| `stackPositions` | All stack keys (`defaultPosition` + `positions`) |
+| `itemsAt(position)` | Toasts in that stack, newest first (includes exiting `removed` items) |
+| `timedItemsAt(position)` | Auto-dismiss stack — same order, includes exiting items |
+| `persistentItemsAt(position)` | Persistent stack (`duration: false`) — includes exiting items |
+| `activeTimedItemsAt(position)` | Timed stack without `removed` items — preferred for simple `x-for` |
+| `activePersistentItemsAt(position)` | Persistent stack without `removed` items |
+| `isVisibleAt(position, index)` | Timed stack only — peek/limit visibility (`maxVisible`) |
+| `pushUnique(key, payload?)` | Same as `$toast.pushUnique` |
+| `destroy()` | Clear timers — call when tearing down the plugin |
+| `dismiss(id)` | Close one toast (same as `$toast.dismiss`) |
+| `dismissAt(position)` | Close one entire position (timed + persistent) |
+| `dismissAll()` | Close all stacks |
+
+## Promise flow
+
+Configure default promise variants in plugin options, or override per call:
+
+```js
+Alpine.plugin(
+  toast({
+    variants: toastVariants(["loading", "success", "error"] as const),
+    promise: {
+      loading: "Loading...",
+      error: "Something went wrong",
+      loadingVariant: "loading",
+      successVariant: "success",
+      errorVariant: "error",
+      duration: 4000,
+    },
+  })
+);
+```
+
+```js
+await $toast.promise(() => save(), {
+  loading: "Saving...",
+  success: (data) => `Saved ${data.id}`,
+  error: "Could not save",
+});
+```
+
+If a named variant is missing from `variants`, promise states fall back to `default`.
+
+On failure, the toast updates to the error state and the returned promise **rejects** with the original error so callers can still use `try/catch` or `.catch()`.
+
+The **loading** state uses a long timed duration (`PROMISE_LOADING_DURATION`) so it stays in the **timed stack** (not perpetual). The timer is replaced when the promise settles to success or error.
+
+Reserved variant names (`dismiss`, `update`, `dismissAt`, `dismissAll`, `fromPayload`, `promise`) cannot override core `$toast` methods.
+
+In Alpine templates, wrap multi-argument calls in an arrow function:
+
 ```html
-<button @click="$toast('Hello')">Default</button>
-<button @click="$toast.success('Saved')">Success</button>
-<button @click="$toast('Notice', { position: 'top-center' })">Top</button>
-<button @click="() => $toast.promise(save, { loading: 'Saving...', success: 'Saved!' })">
+<button
+  @click="() => $toast.promise(() => save(), { loading: 'Saving...', success: 'Saved!' })"
+>
   Save
 </button>
 ```
 
+## Queue limits
+
+Each **position** has two independent stacks:
+
+1. **Timed** — auto-dismiss toasts (`duration > 0`). `maxVisible` applies here (peek/stack UI).
+2. **Persistent** — `duration: false` (or `0` in payloads; normalized to `false`). Always fully visible in your UI.
+
+`maxToasts` applies **per stack per position** (not globally). Example: `maxToasts: 5` allows up to 5 timed + 5 persistent toasts at `bottom-right`.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxToasts` | `5` | Maximum active toasts **per stack per position**. `0` = unlimited. |
+| `maxVisible` | `maxToasts` | Maximum timed toasts shown at once per position (`isVisibleAt`). |
+
+Use `activeTimedItemsAt` / `activePersistentItemsAt` when your renderer does not need exiting (`removed`) items. Keep `timedItemsAt` / `persistentItemsAt` when you animate dismiss (Sonner-style).
+
+## Window events
+
+```js
+window.dispatchEvent(
+  new CustomEvent("toast", {
+    detail: { title: "From anywhere", variant: "success", position: "top-center" },
+  })
+);
+```
+
+Disable with `toast({ listenToWindowEvents: false })`.
+
+## Rendering UI
+
 ```html
-<button @click="$toast.dismiss(toast.id)" aria-label="Close">✕</button>
+<template x-for="position in $store.toast.stackPositions" :key="position">
+  <div
+    role="region"
+    x-bind:aria-label="'Toasts ' + position"
+    x-bind:data-position="position"
+  >
+    <template x-for="(toast, index) in $store.toast.itemsAt(position)" :key="toast.id">
+      <div
+        role="status"
+        x-show="!toast.removed && $store.toast.isVisibleAt(position, index)"
+        x-bind:data-variant="toast.variant"
+      >
+        <p x-text="toast.title"></p>
+      </div>
+    </template>
+  </div>
+</template>
 ```
 
-Also available on the store: `$store.toast.dismiss(id)`.
-
-## API summary
-
-| | |
-|-|-|
-| **Content** | `content` on each toast — any type your UI renders |
-| **Magic** | `$toast(title, options?)` → toast id (`default` variant, `bottom-right` position) |
-| **Close** | `$toast.dismiss(id)`, `$toast.dismissAt(position)`, `$toast.dismissAll()` |
-| **Dedupe** | `$toast.pushUnique(key, payload)` — one active toast per key (undo flows) |
-| **Promise** | `$toast.promise(factoryOrPromise, messages?)` |
-| **Variants** | `variants: toastVariants([...])` → `$toast.<name>()` |
-| **Positions** | `positions: toastPositions([...])` → one stack per position |
-| **Queue** | `maxToasts` / `maxVisible` per timed or persistent stack |
-| **UI** | Bring your own markup and CSS |
+Style `[data-variant="…"]` and `[data-position="…"]` in your own CSS or component library.
+
+## Plugin options
+
+```js
+Alpine.plugin(
+  toast({
+    variants: toastVariants(["success", "error"] as const),
+    positions: toastPositions(["top-center", "bottom-right"] as const),
+    defaultPosition: "bottom-right",
+    defaultDuration: 5000,
+    maxToasts: 5,
+    maxVisible: 3,
+    listenToWindowEvents: true,
+    storeKey: "toast",
+    magicKey: "toast",
+    promise: {
+      loadingVariant: "success",
+      successVariant: "success",
+      errorVariant: "error",
+    },
+  })
+);
+```
+
+### Avoiding name collisions
+
+If your application already owns a `$toast` store or magic — or another toolkit plugin registers on that name — rename the integration surface without touching the controller:
+
+```ts
+Alpine.plugin(
+  toast({
+    storeKey: "alerts", // → $store.alerts
+    magicKey: "snack", // → $snack
+  }),
+);
+```
+
+The exposed constants `TOAST_STORE_KEY` and `TOAST_MAGIC_KEY` keep the renames discoverable from TypeScript.
+
+## Related packages
+
+- [`@ailuracode/alpine-notify`](./notify.md) — OS-level Web Notifications (`$notify`)
 
 ## License
 

package/dist/global.d.ts

@@ -1,266 +1,20 @@
-/// <reference types="@types/alpinejs" />
-
-export declare const TOAST_STORE_KEY: "toast";
-
-export type ToastStoreKey = typeof TOAST_STORE_KEY;
-
-export type DefaultToastPosition = "bottom-right";
-
-export type ToastPosition<TPositions extends readonly string[] = readonly []> =
-  | DefaultToastPosition
-  | TPositions[number];
-
-export type DefaultToastVariant = "default";
-
-/** Milliseconds before auto-dismiss, or `false` / `0` to keep the toast open. */
-export type ToastDuration = number | false;
-
-export type ToastVariant<TVariants extends readonly string[] = readonly []> =
-  | DefaultToastVariant
-  | TVariants[number];
-
-export interface ToastAction {
-  label: string;
-  onClick?: () => void;
-}
-
-export interface ToastPayload<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> {
-  content?: TContent | null;
-  title?: string | null;
-  description?: string | null;
-  variant?: ToastVariant<TVariants>;
-  position?: ToastPosition<TPositions>;
-  duration?: ToastDuration;
-  action?: ToastAction | null;
-  key?: string | null;
-}
-
-export interface ToastItem<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> {
-  id: string;
-  key: string | null;
-  content: TContent | null;
-  title: string | null;
-  description: string | null;
-  variant: ToastVariant<TVariants>;
-  position: ToastPosition<TPositions>;
-  duration: ToastDuration;
-  action: ToastAction | null;
-  removed: boolean;
-}
-
-export type ToastPayloadWithoutVariant<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> = Omit<ToastPayload<TVariants, TPositions, TContent>, "variant">;
-
-export interface ToastPromiseOptions<TVariants extends readonly string[] = readonly []> {
-  loading?: string;
-  error?: string;
-  duration?: ToastDuration;
-  loadingVariant?: ToastVariant<TVariants>;
-  successVariant?: ToastVariant<TVariants>;
-  errorVariant?: ToastVariant<TVariants>;
-}
-
-export interface ToastPluginOptions<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  _TContent = unknown,
-> {
-  variants?: TVariants;
-  positions?: TPositions;
-  defaultPosition?: ToastPosition<TPositions>;
-  defaultDuration?: number;
-  promise?: ToastPromiseOptions<TVariants>;
-  maxToasts?: number;
-  maxVisible?: number;
-  listenToWindowEvents?: boolean;
-  storeKey?: ToastStoreKey;
-}
-
-export interface ToastPromiseMessages<
-  T = unknown,
-  TVariant extends string = string,
-  TContent = unknown,
-> {
-  loading?: string;
-  success?: string | ((data: T) => string);
-  error?: string;
-  loadingContent?: TContent;
-  successContent?: TContent | ((data: T) => TContent);
-  errorContent?: TContent;
-  loadingVariant?: TVariant;
-  successVariant?: TVariant;
-  errorVariant?: TVariant;
-  duration?: ToastDuration;
-}
-
-export type ToastPromiseInput<T> = (() => Promise<T> | T) | Promise<T>;
+/**
+ * Ambient type surface for `@ailuracode/alpine-toast`.
+ *
+ * Re-exports the {@link ToastStore} shape so consumers can include
+ * this file via the global.d.ts triple-slash directive and
+ * typecheck `$store.toast` / `$toast` references without pulling
+ * the runtime entrypoint.
+ *
+ * Per core's `global.d.ts` convention, this package does NOT
+ * augment external modules. The `Alpine.Stores` / `Alpine.Magics<T>`
+ * augmentation that earlier drafts proposed has been removed —
+ * consumers that need typed `$store.toast` access should declare
+ * the augmentation in their own `*.d.ts` (or use the typed
+ * `Alpine<{ toast: ToastStore }>` view from
+ * `@ailuracode/alpine-core` directly).
+ */
 
-export type ToastEventPayload<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> = ToastPayload<TVariants, TPositions, TContent>;
-
-export interface ToastStore<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> {
-  defaultPosition: ToastPosition<TPositions>;
-  stackPositions: readonly ToastPosition<TPositions>[];
-  maxToasts: number;
-  maxVisible: number;
-  items: ToastItem<TVariants, TPositions, TContent>[];
-  push(payload?: ToastPayload<TVariants, TPositions, TContent>): string;
-  pushUnique(key: string, payload?: ToastPayload<TVariants, TPositions, TContent>): string;
-  update(id: string, payload?: Partial<ToastPayload<TVariants, TPositions, TContent>>): void;
-  dismiss(id: string): void;
-  dismissAt(position: ToastPosition<TPositions>): void;
-  dismissAll(): void;
-  destroy(): void;
-  itemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
-  timedItemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
-  persistentItemsAt(
-    position: ToastPosition<TPositions>
-  ): ToastItem<TVariants, TPositions, TContent>[];
-  activeTimedItemsAt(
-    position: ToastPosition<TPositions>
-  ): ToastItem<TVariants, TPositions, TContent>[];
-  activePersistentItemsAt(
-    position: ToastPosition<TPositions>
-  ): ToastItem<TVariants, TPositions, TContent>[];
-  isVisibleAt(position: ToastPosition<TPositions>, index: number): boolean;
-}
-
-export type ToastVariantMethods<
-  TVariants extends readonly string[],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> = {
-  [K in TVariants[number]]: (
-    titleOrPayload: string | ToastPayloadWithoutVariant<TVariants, TPositions, TContent>,
-    options?: Omit<ToastPayloadWithoutVariant<TVariants, TPositions, TContent>, "title" | "content">
-  ) => string;
-};
-
-export type ToastMagic<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
-> = {
-  (title: string, options?: Omit<ToastPayload<TVariants, TPositions, TContent>, "title">): string;
-  (payload: ToastPayload<TVariants, TPositions, TContent>): string;
-  promise<T>(
-    factoryOrPromise: ToastPromiseInput<T>,
-    messages?: ToastPromiseMessages<T, ToastVariant<TVariants>, TContent>
-  ): Promise<T>;
-  dismiss(id: string): void;
-  update(id: string, payload?: Partial<ToastPayload<TVariants, TPositions, TContent>>): void;
-  dismissAt(position: ToastPosition<TPositions>): void;
-  dismissAll(): void;
-  pushUnique(key: string, payload?: ToastPayload<TVariants, TPositions, TContent>): string;
-  fromPayload(payload?: ToastEventPayload<TVariants, TPositions, TContent>): string;
-} & ToastVariantMethods<TVariants, TPositions, TContent>;
-
-export type ResolvedPromiseConfig<TVariants extends readonly string[] = readonly []> = {
-  loading: string;
-  error: string;
-  duration: ToastDuration;
-  loadingVariant: ToastVariant<TVariants>;
-  successVariant: ToastVariant<TVariants>;
-  errorVariant: ToastVariant<TVariants>;
-};
-
-export type ResolvedToastPluginConfig<
-  TVariants extends readonly string[] = readonly [],
-  TPositions extends readonly string[] = readonly [],
-> = {
-  defaultPosition: ToastPosition<TPositions>;
-  defaultDuration: number;
-  maxToasts: number;
-  maxVisible: number;
-  listenToWindowEvents: boolean;
-  storeKey: ToastStoreKey;
-  variants: TVariants;
-  positions: TPositions;
-  promise: ResolvedPromiseConfig<TVariants>;
-};
-
-export declare function resolveToastPluginConfig<
-  const TVariants extends readonly string[] = readonly [],
-  const TPositions extends readonly string[] = readonly [],
->(
-  options?: ToastPluginOptions<TVariants, TPositions>
-): ResolvedToastPluginConfig<TVariants, TPositions>;
-
-export declare function toastOptions<
-  const TVariants extends readonly string[] = readonly [],
-  const TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
->(
-  options: ToastPluginOptions<TVariants, TPositions, TContent>
-): ToastPluginOptions<TVariants, TPositions, TContent>;
-
-export declare function toastVariants<const T extends readonly string[]>(variants: T): T;
-
-export declare function toastPositions<const T extends readonly string[]>(positions: T): T;
-
-export interface CreateToastStoreOptions<TPositions extends readonly string[] = readonly []> {
-  defaultPosition?: ToastPosition<TPositions>;
-  positions?: TPositions;
-  defaultDuration?: number;
-  maxToasts?: number;
-  maxVisible?: number;
-}
-
-export declare function resolveStackPositions<TPositions extends readonly string[]>(
-  defaultPosition: ToastPosition<TPositions>,
-  positions?: TPositions
-): readonly ToastPosition<TPositions>[];
-
-export declare function createToastStore<
-  const TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
->(options?: CreateToastStoreOptions<TPositions>): ToastStore<readonly [], TPositions, TContent>;
-
-export declare function createToastMagic<
-  const TVariants extends readonly string[],
-  const TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
->(
-  config: ResolvedToastPluginConfig<TVariants, TPositions>,
-  getStore: () => ToastStore<TVariants, TPositions, TContent>
-): ToastMagic<TVariants, TPositions, TContent>;
-
-declare function toastPlugin<
-  const TVariants extends readonly string[] = readonly [],
-  const TPositions extends readonly string[] = readonly [],
-  TContent = unknown,
->(
-  options?: ToastPluginOptions<TVariants, TPositions, TContent>
-): (Alpine: import("alpinejs").Alpine) => void;
-declare function toastPlugin(Alpine: import("alpinejs").Alpine): void;
-
-export default toastPlugin;
+/// <reference types="@types/alpinejs" />
 
-declare global {
-  namespace Alpine {
-    interface Stores {
-      toast: ToastStore;
-    }
-    interface Magics<T> {
-      $toast: ToastMagic;
-    }
-  }
-}
+export type { ToastStore };