@ailuracode/alpine-toast 0.1.1 → 1.0.0

package/README.md

@@ -4,22 +4,22 @@ 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)**
+**[Full documentation →](../../docs/plugins/toast.md)**
 
 ## Install
 
 ```bash
-npm install @ailuracode/alpine-toast alpinejs
+pnpm add @ailuracode/alpine-toast alpinejs
 ```
 
 ## Quick example
 
-```js
+```ts
 import Alpine from "alpinejs";
-import toast, { toastPositions, toastVariants } from "@ailuracode/alpine-toast";
+import { toastPlugin, toastVariants, toastPositions } from "@ailuracode/alpine-toast";
 
 Alpine.plugin(
-  toast({
+  toastPlugin({
     variants: toastVariants(["success", "error", "loading"] as const),
     positions: toastPositions(["top-center", "bottom-right"] as const),
     defaultPosition: "bottom-right",
@@ -62,6 +62,53 @@ Also available on the store: `$store.toast.dismiss(id)`.
 | **Queue** | `maxToasts` / `maxVisible` per timed or persistent stack |
 | **UI** | Bring your own markup and CSS |
 
+## Standalone usage (no Alpine)
+
+```ts
+import { createToastController } from "@ailuracode/alpine-toast";
+
+const controller = createToastController({
+  maxToasts: 5,
+  maxVisible: 3,
+});
+
+controller.push({ content: "Hello!", variant: "default", position: "bottom-right" });
+controller.dismissAll();
+controller.destroy();
+```
+
+## Plugin options
+
+```ts
+toastPlugin({
+  variants?: string[],           // toastVariants([...])
+  positions?: string[],          // toastPositions([...])
+  defaultPosition?: string,      // default: "bottom-right"
+  defaultDuration?: number,      // default: 5000 (ms), false for persistent
+  maxToasts?: number,            // max toasts per position
+  maxVisible?: number,            // max visible per position
+  promise?: {
+    loadingVariant?: string,
+    successVariant?: string,
+    errorVariant?: string,
+    loadingMessages?: string[],
+  },
+  onDismiss?: (id: string) => void,
+  onChange?: (detail: ToastChangeDetail) => void,
+});
+```
+
+## Store API
+
+```ts
+$store.toast.items           // active toast items
+$store.toast.length          // total count
+$store.toast.push(payload)   // add a toast, returns id
+$store.toast.dismiss(id)     // remove by id
+$store.toast.dismissAt(position) // remove all at position
+$store.toast.dismissAll()    // remove all
+```
+
 ## License
 
 MIT

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 };