@ilokesto/toast 1.0.0

package/README.ko.md

@@ -0,0 +1,209 @@
+# @ilokesto/toast
+
+[English](./README.md) | **한국어**
+
+실사용 기준으로 `react-hot-toast`를 대체할 수 있도록 만든 React toast 패키지입니다.
+
+`@ilokesto/toast`는 provider-scoped toast runtime, 익숙한 `toast.*` facade, 기본 렌더러, headless hook, 그리고 선택적인 top-layer transport를 제공합니다. 내부적으로는 `@ilokesto/overlay`를 presence lifecycle 용도로만 사용하고, toast 정책과 렌더링은 이 패키지 안에서 처리합니다.
+
+## Features
+
+- 익숙한 facade: `toast()`, `toast.success()`, `toast.error()`, `toast.loading()`, `toast.custom()`, `toast.promise()`
+- `toasterId` 기준으로 분리되는 provider-scoped runtime
+- 기본 `Toaster`에 포함된 카드 UI, 상태 아이콘, spinner, enter/exit motion
+- `style`, `className`, `icon`, `iconTheme`, `removeDelay`, `position`, `duration`, `ariaProps` 같은 per-toast 옵션
+- global → per-type → per-toast 순서의 `toastOptions` merge
+- 커스텀 렌더러를 위한 headless `useToaster()`
+- manual popover 기반의 선택적 `transport="top-layer"`
+
+## Installation
+
+```bash
+pnpm add @ilokesto/toast react react-dom
+```
+
+또는
+
+```bash
+npm install @ilokesto/toast react react-dom
+```
+
+## Basic Usage
+
+```tsx
+import { Toaster, toast } from '@ilokesto/toast';
+
+function App() {
+  return (
+    <>
+      <button onClick={() => toast.success('Saved successfully')}>Show toast</button>
+      <Toaster />
+    </>
+  );
+}
+```
+
+## Promise Toasts
+
+```tsx
+import { Toaster, toast } from '@ilokesto/toast';
+
+async function savePost() {
+  return fetch('/api/posts', { method: 'POST' });
+}
+
+toast.promise(savePost(), {
+  loading: 'Saving post…',
+  success: 'Post saved',
+  error: (error) => `Save failed: ${String(error)}`,
+});
+
+export function App() {
+  return <Toaster />;
+}
+```
+
+## Custom Rendering
+
+### `Toaster` children
+
+```tsx
+import { Toaster } from '@ilokesto/toast';
+
+export function App() {
+  return (
+    <Toaster>
+      {(toast, { dismiss }) => (
+        <button onClick={dismiss}>
+          {toast.message}
+        </button>
+      )}
+    </Toaster>
+  );
+}
+```
+
+### `ToastBar`
+
+```tsx
+import { ToastBar, Toaster } from '@ilokesto/toast';
+
+export function App() {
+  return (
+    <Toaster>
+      {(toast) => (
+        <ToastBar toast={toast}>
+          {({ icon, message }) => (
+            <>
+              {message}
+              {icon}
+            </>
+          )}
+        </ToastBar>
+      )}
+    </Toaster>
+  );
+}
+```
+
+## Top-Layer Transport
+
+`@ilokesto/toast`는 `react-hot-toast`에 없는 추가 렌더링 모드를 제공합니다.
+
+```tsx
+<Toaster transport="top-layer" />
+```
+
+브라우저가 지원하면 manual popover를 사용하고, 지원하지 않으면 inline 렌더링으로 자동 fallback합니다.
+
+## Headless Usage
+
+`useToaster()`는 visible toast 목록과 runtime helper를 노출합니다.
+
+```ts
+const { toasts, handlers } = useToaster();
+```
+
+사용 가능한 handler:
+
+- `updateHeight`
+- `startPause`
+- `endPause`
+- `calculateOffset`
+
+이 hook은 mounted `Toaster` context 아래에서 동작하는 고급 통합 시나리오를 위한 API입니다.
+
+## Source Layout
+
+```text
+src/
+  components/
+    ToastBar.tsx
+    ToastProvider.tsx
+    Toaster.tsx
+    icons.tsx
+  core/
+    createToastRuntime.ts
+    createToastStore.ts
+    registry.ts
+    toast.ts
+    utils.ts
+  hooks/
+    useToaster.ts
+    useToastItems.ts
+  types/
+    toast.ts
+  index.ts
+```
+
+## Responsibilities
+
+### `src/components`
+
+- `Toaster.tsx` → visible toast stack을 마운트하고 runtime view 옵션을 설정하며 기본 컨테이너를 제공합니다
+- `ToastBar.tsx` → 개별 toast row를 위한 기본 렌더러 primitive입니다
+- `icons.tsx` → 기본 spinner와 상태 아이콘 컴포넌트를 제공합니다
+- `ToastProvider.tsx` → `toasterId`별 provider-scoped runtime을 만들고 등록합니다
+
+### `src/core`
+
+- `toast.ts` → public `toast.*` facade
+- `createToastRuntime.ts` → id, timer, promise transition, dismiss/remove, visible-set 계산을 담당하는 toast policy 레이어
+- `createToastStore.ts` → raw toast state store
+- `registry.ts` → `toasterId` 기준 runtime 등록
+- `utils.ts` → 기본 duration, id, icon theme, helper 정의
+
+### `src/hooks`
+
+- `useToaster.ts` → `{ toasts, handlers }`를 반환하는 headless hook
+- `useToastItems.ts` → 현재 visible toast item 목록을 구독합니다
+
+### `src/types`
+
+- `toast.ts` → runtime API, props, item state, options에 대한 public contract
+
+### `src/index.ts`
+
+- public runtime, renderer, hook, type surface를 다시 export합니다
+
+## Exports
+
+- values → `toast`, `Toaster`, `ToastBar`, `ToastIcon`, `useToaster`, `useToastItems`, `createToastRuntime`
+- types → `ToastBarProps`, `ToastOptions`, `DefaultToastOptions`, `ToasterProps`, `UseToasterResult` 등 toast 관련 public 타입
+
+## Migration
+
+`react-hot-toast`에서 옮겨오는 경우 [MIGRATION_FROM_REACT_HOT_TOAST.ko.md](./MIGRATION_FROM_REACT_HOT_TOAST.ko.md)를 참고하세요.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+```
+
+빌드 결과물은 `dist` 디렉터리에 생성됩니다.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,209 @@
+# @ilokesto/toast
+
+**English** | [한국어](./README.ko.md)
+
+A React toast package built for practical `react-hot-toast` replacement quality.
+
+`@ilokesto/toast` provides a provider-scoped toast runtime, a familiar `toast.*` facade, a polished default renderer, headless hooks, and an optional top-layer transport. Internally it uses `@ilokesto/overlay` for presence lifecycle only, while toast policy and rendering stay inside this package.
+
+## Features
+
+- Familiar facade: `toast()`, `toast.success()`, `toast.error()`, `toast.loading()`, `toast.custom()`, `toast.promise()`
+- Provider-scoped runtimes separated by `toasterId`
+- Default `Toaster` with built-in card UI, animated status icons, spinner, and enter/exit motion
+- Per-toast options such as `style`, `className`, `icon`, `iconTheme`, `removeDelay`, `position`, `duration`, and `ariaProps`
+- `toastOptions` merge order of global → per-type → per-toast options
+- Headless `useToaster()` for custom renderers
+- Optional `transport="top-layer"` mode powered by manual popover
+
+## Installation
+
+```bash
+pnpm add @ilokesto/toast react react-dom
+```
+
+or
+
+```bash
+npm install @ilokesto/toast react react-dom
+```
+
+## Basic Usage
+
+```tsx
+import { Toaster, toast } from '@ilokesto/toast';
+
+function App() {
+  return (
+    <>
+      <button onClick={() => toast.success('Saved successfully')}>Show toast</button>
+      <Toaster />
+    </>
+  );
+}
+```
+
+## Promise Toasts
+
+```tsx
+import { Toaster, toast } from '@ilokesto/toast';
+
+async function savePost() {
+  return fetch('/api/posts', { method: 'POST' });
+}
+
+toast.promise(savePost(), {
+  loading: 'Saving post…',
+  success: 'Post saved',
+  error: (error) => `Save failed: ${String(error)}`,
+});
+
+export function App() {
+  return <Toaster />;
+}
+```
+
+## Custom Rendering
+
+### `Toaster` children
+
+```tsx
+import { Toaster } from '@ilokesto/toast';
+
+export function App() {
+  return (
+    <Toaster>
+      {(toast, { dismiss }) => (
+        <button onClick={dismiss}>
+          {toast.message}
+        </button>
+      )}
+    </Toaster>
+  );
+}
+```
+
+### `ToastBar`
+
+```tsx
+import { ToastBar, Toaster } from '@ilokesto/toast';
+
+export function App() {
+  return (
+    <Toaster>
+      {(toast) => (
+        <ToastBar toast={toast}>
+          {({ icon, message }) => (
+            <>
+              {message}
+              {icon}
+            </>
+          )}
+        </ToastBar>
+      )}
+    </Toaster>
+  );
+}
+```
+
+## Top-Layer Transport
+
+`@ilokesto/toast` adds an extra rendering mode that `react-hot-toast` does not provide:
+
+```tsx
+<Toaster transport="top-layer" />
+```
+
+This uses manual popover when the browser supports it and falls back to inline rendering when it does not.
+
+## Headless Usage
+
+`useToaster()` exposes the visible toast list and runtime helpers:
+
+```ts
+const { toasts, handlers } = useToaster();
+```
+
+Available handlers:
+
+- `updateHeight`
+- `startPause`
+- `endPause`
+- `calculateOffset`
+
+This hook is intended for advanced integrations that run under the mounted `Toaster` context.
+
+## Source Layout
+
+```text
+src/
+  components/
+    ToastBar.tsx
+    ToastProvider.tsx
+    Toaster.tsx
+    icons.tsx
+  core/
+    createToastRuntime.ts
+    createToastStore.ts
+    registry.ts
+    toast.ts
+    utils.ts
+  hooks/
+    useToaster.ts
+    useToastItems.ts
+  types/
+    toast.ts
+  index.ts
+```
+
+## Responsibilities
+
+### `src/components`
+
+- `Toaster.tsx` → mounts the visible toast stack, configures runtime view options, and provides the default container
+- `ToastBar.tsx` → composable default renderer primitive for a single toast row
+- `icons.tsx` → built-in spinner and status icon components used by the default renderer
+- `ToastProvider.tsx` → creates and registers provider-scoped runtimes by `toasterId`
+
+### `src/core`
+
+- `toast.ts` → the public `toast.*` facade
+- `createToastRuntime.ts` → toast policy layer for ids, timers, promise transitions, dismiss/remove behavior, and visible-set calculation
+- `createToastStore.ts` → raw toast state store
+- `registry.ts` → runtime registration by `toasterId`
+- `utils.ts` → default durations, ids, icon themes, and small helpers
+
+### `src/hooks`
+
+- `useToaster.ts` → headless hook returning `{ toasts, handlers }`
+- `useToastItems.ts` → subscribes to the current visible toast items
+
+### `src/types`
+
+- `toast.ts` → public contracts for runtime APIs, props, item state, and options
+
+### `src/index.ts`
+
+- re-exports the public runtime, renderer, hook, and type surface
+
+## Exports
+
+- values → `toast`, `Toaster`, `ToastBar`, `ToastIcon`, `useToaster`, `useToastItems`, `createToastRuntime`
+- types → `ToastBarProps`, `ToastOptions`, `DefaultToastOptions`, `ToasterProps`, `UseToasterResult`, and related toast contracts
+
+## Migration
+
+If you are moving from `react-hot-toast`, see [MIGRATION_FROM_REACT_HOT_TOAST.md](./MIGRATION_FROM_REACT_HOT_TOAST.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+```
+
+Build outputs are generated in the `dist` directory.
+
+## License
+
+MIT

package/dist/components/ToastBar.d.ts

@@ -0,0 +1,12 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ToastItem, ToastPosition } from "../types/toast";
+export interface ToastBarProps {
+    readonly toast: ToastItem;
+    readonly position?: ToastPosition;
+    readonly style?: CSSProperties;
+    readonly children?: (components: {
+        icon: ReactNode;
+        message: ReactNode;
+    }) => ReactNode;
+}
+export declare const ToastBar: ({ toast, position, style, children }: ToastBarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/ToastBar.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ToastIcon } from "./icons";
+const getMotionStyle = (toast, position) => {
+    const isClosing = toast.status === "closing";
+    const factor = position.startsWith("top") ? -1 : 1;
+    const isCenter = position.endsWith("center");
+    const enterAnimation = `toast-enter 0.35s cubic-bezier(0.21, 1.02, 0.73, 1) forwards`;
+    const exitAnimation = `toast-exit 0.4s forwards cubic-bezier(0.06, 0.71, 0.55, 1)`;
+    return {
+        animation: isClosing ? exitAnimation : enterAnimation,
+        "--toast-enter-y": `${factor * 20}px`,
+        "--toast-exit-y": `${factor * -20}px`,
+        "--toast-enter-x": isCenter ? "0px" : position.endsWith("left") ? "-20px" : "20px",
+        "--toast-exit-x": isCenter ? "0px" : position.endsWith("left") ? "-20px" : "20px",
+    };
+};
+export const ToastBar = ({ toast, position, style, children }) => {
+    const isCustom = toast.type === "custom";
+    const defaultStyle = {
+        display: "flex",
+        alignItems: "center",
+        gap: 8,
+        background: "#fff",
+        color: "#363636",
+        lineHeight: 1.3,
+        willChange: "transform, opacity",
+        boxShadow: "0 3px 10px rgba(0, 0, 0, 0.1), 0 3px 3px rgba(0, 0, 0, 0.05)",
+        maxWidth: 350,
+        pointerEvents: "auto",
+        padding: "8px 10px",
+        borderRadius: 8,
+        ...getMotionStyle(toast, position ?? toast.position ?? "top-center"),
+        ...toast.style,
+        ...style,
+    };
+    const icon = _jsx(ToastIcon, { type: toast.type, icon: toast.icon, iconTheme: toast.iconTheme });
+    const message = (_jsx("div", { style: { display: "flex", justifyContent: "center", margin: "4px 10px", color: "inherit", flex: 1 }, children: toast.message }));
+    return (_jsx("div", { className: toast.className, style: defaultStyle, role: toast.ariaProps.role, "aria-live": toast.ariaProps["aria-live"], "aria-atomic": toast.ariaProps["aria-atomic"], children: isCustom ? (toast.message) : typeof children === "function" ? (children({ icon, message })) : (_jsxs(_Fragment, { children: [icon, message] })) }));
+};

package/dist/components/ToastProvider.d.ts

@@ -0,0 +1,3 @@
+import type { ToasterId, ToastRuntimeApi } from "../types/toast";
+export declare const ToasterContext: import("react").Context<ToastRuntimeApi | null>;
+export declare function useToasterRuntime(toasterId?: ToasterId): ToastRuntimeApi;

package/dist/components/ToastProvider.js

@@ -0,0 +1,16 @@
+import { createContext, useEffect, useMemo } from "react";
+import { createToastRuntime } from "../core/createToastRuntime";
+import { registerRuntime, unregisterRuntime } from "../core/registry";
+import { DEFAULT_TOASTER_ID } from "../core/utils";
+export const ToasterContext = createContext(null);
+export function useToasterRuntime(toasterId = DEFAULT_TOASTER_ID) {
+    const runtime = useMemo(() => createToastRuntime(toasterId), [toasterId]);
+    useEffect(() => {
+        registerRuntime(runtime);
+        return () => {
+            runtime.clear();
+            unregisterRuntime(runtime.toasterId);
+        };
+    }, [runtime]);
+    return runtime;
+}

package/dist/components/Toaster.d.ts

@@ -0,0 +1,2 @@
+import type { ToasterProps } from "../types/toast";
+export declare function Toaster({ toasterId, position, transport, limit, reverseOrder, gutter, containerStyle, containerClassName, toastOptions, children: renderRow, }: ToasterProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Toaster.js

@@ -0,0 +1,175 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, } from "react";
+import { DEFAULT_GUTTER, DEFAULT_LIMIT, DEFAULT_POSITION } from "../core/utils";
+import { useToastItems } from "../hooks/useToastItems";
+import { ToastBar } from "./ToastBar";
+import { ToasterContext, useToasterRuntime } from "./ToastProvider";
+function supportsPopover() {
+    if (typeof HTMLElement === "undefined") {
+        return false;
+    }
+    return typeof HTMLElement.prototype.showPopover === "function";
+}
+function getContainerStyle(position) {
+    const style = {
+        position: "fixed",
+        zIndex: 9999,
+        display: "flex",
+        flexDirection: "column",
+        pointerEvents: "none",
+        padding: 16,
+    };
+    if (position.startsWith("top")) {
+        style.top = 0;
+    }
+    else {
+        style.bottom = 0;
+    }
+    if (position.endsWith("left")) {
+        style.left = 0;
+        style.alignItems = "flex-start";
+    }
+    else if (position.endsWith("right")) {
+        style.right = 0;
+        style.alignItems = "flex-end";
+    }
+    else {
+        style.left = "50%";
+        style.transform = "translateX(-50%)";
+        style.alignItems = "center";
+    }
+    return style;
+}
+function getStackOffset(items, index, gutter) {
+    return items.slice(0, index).reduce((offset, item) => {
+        return offset + (item.height ?? 0) + gutter;
+    }, 0);
+}
+function getToastStyle(position, offset) {
+    const translateY = position.startsWith("top") ? offset : -offset;
+    return {
+        pointerEvents: "auto",
+        transform: `translateY(${translateY}px)`,
+        transition: "transform 200ms ease, opacity 200ms ease",
+    };
+}
+function ToastMeasure({ item, offset, position, onHeight, children, }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        const element = ref.current;
+        if (element === null) {
+            return;
+        }
+        const nextHeight = element.offsetHeight;
+        onHeight(item.id, nextHeight);
+    }, [item.id, item.message, item.status, onHeight]);
+    return (_jsx("div", { ref: ref, style: getToastStyle(position, offset), children: children }));
+}
+function TopLayerContainer({ style, className, children, }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        const element = ref.current;
+        if (element === null || !supportsPopover()) {
+            return;
+        }
+        try {
+            element.showPopover();
+        }
+        catch (error) {
+            console.error("Failed to show top-layer toast popover", error);
+        }
+        return () => {
+            if (typeof element.hidePopover !== "function") {
+                return;
+            }
+            try {
+                element.hidePopover();
+            }
+            catch (error) {
+                console.error("Failed to hide top-layer toast popover", error);
+            }
+        };
+    }, []);
+    if (!supportsPopover()) {
+        return (_jsx("div", { className: className, style: style, children: children }));
+    }
+    return (_jsx("div", { ref: ref, popover: "manual", className: className, style: {
+            ...style,
+            border: "none",
+            background: "transparent",
+            margin: 0,
+            overflow: "visible",
+            inset: "unset",
+        }, children: children }));
+}
+function InlineContainer({ style, className, children, }) {
+    return (_jsx("div", { className: className, style: style, children: children }));
+}
+export function Toaster({ toasterId, position = DEFAULT_POSITION, transport = "inline", limit = DEFAULT_LIMIT, reverseOrder = false, gutter = DEFAULT_GUTTER, containerStyle, containerClassName, toastOptions, children: renderRow, }) {
+    const runtime = useToasterRuntime(toasterId);
+    const items = useToastItems(runtime);
+    const activePosition = toastOptions?.position ?? position;
+    useEffect(() => {
+        runtime.configureView({
+            limit,
+            position: activePosition,
+            toastOptions,
+        });
+    }, [activePosition, limit, runtime, toastOptions]);
+    const orderedItems = useMemo(() => {
+        return reverseOrder ? [...items].reverse() : items;
+    }, [items, reverseOrder]);
+    const containerStyleValue = useMemo(() => ({
+        ...getContainerStyle(position),
+        ...containerStyle,
+    }), [containerStyle, position]);
+    const createHelpers = useCallback((item) => ({
+        dismiss: () => runtime.dismiss(item.id),
+        remove: () => runtime.remove(item.id),
+    }), [runtime]);
+    const handleMouseEnter = useCallback(() => {
+        runtime.startPause();
+    }, [runtime]);
+    const handleMouseLeave = useCallback(() => {
+        runtime.endPause();
+    }, [runtime]);
+    const rows = orderedItems.map((item, index) => {
+        const helpers = createHelpers(item);
+        const offset = getStackOffset(orderedItems, index, gutter);
+        const content = renderRow === undefined
+            ? _jsx(ToastBar, { toast: item, position: position })
+            : renderRow(item, helpers);
+        return (_jsx(ToastMeasure, { item: item, offset: offset, position: position, onHeight: runtime.updateHeight, children: content }, item.id));
+    });
+    const Container = transport === "top-layer" ? TopLayerContainer : InlineContainer;
+    return (_jsxs(ToasterContext.Provider, { value: runtime, children: [_jsx("style", { children: `
+          @keyframes toast-enter {
+            0% { transform: translate3d(var(--toast-enter-x, 0), var(--toast-enter-y, -200%), 0) scale(0.6); opacity: 0.5; }
+            100% { transform: translate3d(0, 0, 0) scale(1); opacity: 1; }
+          }
+          @keyframes toast-exit {
+            0% { transform: translate3d(0, 0, -1px) scale(1); opacity: 1; }
+            100% { transform: translate3d(var(--toast-exit-x, 0), var(--toast-exit-y, -150%), -1px) scale(0.6); opacity: 0; }
+          }
+          @keyframes toast-spin {
+            from { transform: rotate(0deg); }
+            to { transform: rotate(360deg); }
+          }
+          @keyframes toast-scale {
+            from { transform: scale(0); opacity: 0; }
+            to { transform: scale(1); opacity: 1; }
+          }
+          @media (prefers-reduced-motion: reduce) {
+            @keyframes toast-enter {
+              0% { opacity: 0; }
+              100% { opacity: 1; }
+            }
+            @keyframes toast-exit {
+              0% { opacity: 1; }
+              100% { opacity: 0; }
+            }
+            .toast-motion-spin { animation: none !important; }
+            .toast-motion-scale { animation: none !important; }
+          }
+        ` }), _jsx(Container, { className: containerClassName, style: containerStyleValue, children: _jsx("div", { role: "region", "aria-label": "Notifications", onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: rows }) })] }));
+}

package/dist/components/icons.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { ToastType, IconTheme } from "../types/toast";
+export declare const DefaultSpinner: () => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultSuccess: ({ theme }: {
+    theme?: IconTheme;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultError: ({ theme }: {
+    theme?: IconTheme;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const ToastIcon: ({ type, icon, iconTheme, }: {
+    type: ToastType;
+    icon?: ReactNode;
+    iconTheme?: IconTheme;
+}) => import("react/jsx-runtime").JSX.Element | null;