@uniai-fe/uds-primitives 0.5.6 → 0.6.0

package/README.md

@@ -194,6 +194,15 @@ export default function Page() {
 - `TableRootProps`
 - `TableContainerProps`
 - `TableCellProps`
+- `Toast.Host`
+- `Toast.Item`
+- `ToastIcon`
+- `ToastItemData`
+- `ToastHostProps`
+- `ToastItemProps`
+- `ToastState`
+- `ToastHorizontal`
+- `ToastVertical`
 - `Button.Default`
 - `Button.Text`
 - `Button.Rounded`

package/dist/styles.css

@@ -779,6 +779,26 @@
   --table-td-text-size: 15px;
   --table-td-text-weight: var(--font-body-xsmall-weight);
   --table-td-text-line-height: var(--font-body-xsmall-line-height);
+  --toast-stack-margin: var(--spacing-padding-7);
+  --toast-stack-gap: var(--spacing-gap-3);
+  --toast-stack-z-index: 10000;
+  --toast-width: 361px;
+  --toast-background-color: var(--color-surface-heavy);
+  --toast-foreground-color: var(--color-common-100);
+  --toast-radius: var(--theme-radius-large-1);
+  --toast-padding-block: var(--spacing-padding-5);
+  --toast-padding-inline: var(--spacing-padding-7);
+  --toast-gap: var(--spacing-gap-5);
+  --toast-icon-size: 24px;
+  --toast-transition-duration: 0.6s;
+  --toast-transition-easing: cubic-bezier(0.16, 1, 0.3, 1);
+  --toast-transition-distance: -24%;
+  --toast-transition-x: 0;
+  --toast-transition-y: 0;
+  --toast-message-font-size: var(--font-body-xsmall-size);
+  --toast-message-line-height: var(--font-body-xsmall-line-height);
+  --toast-message-letter-spacing: var(--font-body-xsmall-letter-spacing);
+  --toast-message-font-weight: var(--font-body-xsmall-weight);
   --tooltip-message-background: var(--color-cool-gray-20);
   --tooltip-message-foreground: var(--color-common-100);
   --tooltip-message-radius: var(--theme-radius-medium-3);
@@ -5097,6 +5117,117 @@ figure.chip {
 
 
 
+.toast-stack {
+  --toast-stack-translate-x: 0;
+  --toast-stack-translate-y: 0;
+  position: fixed;
+  z-index: var(--toast-stack-z-index);
+  display: flex;
+  flex-direction: column;
+  gap: var(--toast-stack-gap);
+  pointer-events: none;
+  transform: translate(var(--toast-stack-translate-x), var(--toast-stack-translate-y));
+}
+
+.toast-stack:where([data-x=left]) {
+  left: var(--toast-stack-margin);
+  --toast-transition-x: calc(var(--toast-transition-distance) * -1);
+}
+
+.toast-stack:where([data-x=center]) {
+  left: 50%;
+  --toast-stack-translate-x: -50%;
+  --toast-transition-distance: -80%;
+}
+
+.toast-stack:where([data-x=right]) {
+  right: var(--toast-stack-margin);
+  --toast-transition-x: var(--toast-transition-distance);
+}
+
+.toast-stack:where([data-y=top]) {
+  top: var(--toast-stack-margin);
+}
+
+.toast-stack:where([data-y=center]) {
+  top: 50%;
+  --toast-stack-translate-y: -50%;
+}
+
+.toast-stack:where([data-y=bottom]) {
+  bottom: var(--toast-stack-margin);
+}
+
+.toast-stack:where([data-x=center][data-y=top]) {
+  --toast-transition-y: calc(var(--toast-transition-distance) * -1);
+}
+
+.toast-stack:where([data-x=center][data-y=bottom]) {
+  --toast-transition-y: var(--toast-transition-distance);
+}
+
+.toast {
+  display: flex;
+  align-items: center;
+  width: min(var(--toast-width), 100vw - var(--toast-stack-margin) * 2);
+  box-sizing: border-box;
+  gap: var(--toast-gap);
+  overflow: hidden;
+  padding: var(--toast-padding-block) var(--toast-padding-inline);
+  border-radius: var(--toast-radius);
+  background-color: var(--toast-background-color);
+  opacity: 0;
+  pointer-events: auto;
+  transform: translate(var(--toast-transition-x), var(--toast-transition-y));
+  transition: opacity var(--toast-transition-duration) var(--toast-transition-easing), transform var(--toast-transition-duration) var(--toast-transition-easing);
+}
+
+.toast:where([data-phase=open]) {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.toast-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: var(--toast-icon-size);
+  height: var(--toast-icon-size);
+  margin: 0;
+}
+
+.toast-icon svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.toast-content {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  flex-direction: column;
+}
+
+.toast-text {
+  overflow: hidden;
+  margin: 0;
+  color: var(--toast-foreground-color);
+  font-size: var(--toast-message-font-size);
+  line-height: var(--toast-message-line-height);
+  letter-spacing: var(--toast-message-letter-spacing);
+  font-weight: var(--toast-message-font-weight);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.toast-description {
+  opacity: 0.82;
+}
+
+
+
 .tooltip-trigger {
   display: inline-flex;
   align-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/toast/img/error.svg

@@ -0,0 +1,6 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="12" cy="12" r="10" fill="#313235"/>
+<circle cx="12" cy="12" r="10" fill="#DA1D0B"/>
+<path d="M12 15C12.5523 15 13 15.4477 13 16C13 16.5523 12.5523 17 12 17C11.4477 17 11 16.5523 11 16C11 15.4477 11.4477 15 12 15Z" fill="white"/>
+<path d="M12 7.2002C12.4418 7.2002 12.7998 7.55817 12.7998 8V13C12.7998 13.4418 12.4418 13.7998 12 13.7998C11.5582 13.7998 11.2002 13.4418 11.2002 13V8C11.2002 7.55817 11.5582 7.2002 12 7.2002Z" fill="white"/>
+</svg>

package/src/components/toast/img/success.svg

@@ -0,0 +1,5 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="12" cy="12" r="10" fill="#313235"/>
+<circle cx="12" cy="12" r="10" fill="#1AB24D"/>
+<path d="M7.19152 11.8688C6.8791 11.5564 6.8791 11.0501 7.19152 10.7377C7.50394 10.4253 8.0102 10.4253 8.32262 10.7377L10.9391 13.3541L15.6768 8.61636C15.9892 8.30394 16.4955 8.30394 16.8079 8.61636C17.1203 8.92877 17.1203 9.43503 16.8079 9.74745L11.5046 15.0508C11.1922 15.3632 10.6859 15.3632 10.3735 15.0508L7.19152 11.8688Z" fill="white"/>
+</svg>

package/src/components/toast/img/warning.svg

@@ -0,0 +1,5 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M2.6303 18.0362L10.2478 4.18631C11.0076 2.80476 12.9928 2.80476 13.7526 4.18631L21.3701 18.0362C22.1032 19.3691 21.1389 21.0001 19.6176 21.0001H4.38273C2.86153 21.0001 1.8972 19.3691 2.6303 18.0362Z" fill="#F2CC0D"/>
+<path d="M12 16C12.5523 16 13 16.4477 13 17C13 17.5523 12.5523 18 12 18C11.4477 18 11 17.5523 11 17C11 16.4477 11.4477 16 12 16Z" fill="#313235"/>
+<path d="M12 8.2002C12.4418 8.2002 12.7998 8.55817 12.7998 9V14C12.7998 14.4418 12.4418 14.7998 12 14.7998C11.5582 14.7998 11.2002 14.4418 11.2002 14V9C11.2002 8.55817 11.5582 8.2002 12 8.2002Z" fill="#313235"/>
+</svg>

package/src/components/toast/index.scss

@@ -0,0 +1 @@
+@use "./styles";

package/src/components/toast/index.tsx

@@ -0,0 +1,11 @@
+/**
+ * Toast; semantic feedback toast 카테고리 배럴
+ * @desc
+ * - `Toast.Host`: 트리거 로직이 만든 item data를 위치별 stack으로 렌더링한다.
+ * - `Toast.Item`: state icon/content/timer close를 담당하는 개별 toast다.
+ * - `ToastIcon`, `ToastItemData`, `ToastState`: public contract 도구다.
+ */
+import "./index.scss";
+
+export * from "./markup";
+export type * from "./types";

package/src/components/toast/markup/Host.tsx

@@ -0,0 +1,74 @@
+import { Fragment } from "react";
+
+import type { ToastHostProps, ToastItemData } from "../types";
+import type { ToastStackGroup, ToastStackStyle } from "../types/internal";
+import { ToastItem } from "./Item";
+
+/**
+ * Toast Host; x/y/margin 기준으로 Toast stack을 렌더링하는 Host
+ * @component
+ * @param {ToastHostProps} props
+ * @param {ToastItemData[]} props.items Toast item 데이터 목록
+ * @param {(toastKey: string) => void} props.onClose 닫힘 요청 핸들러
+ * @example
+ * <Toast.Host items={toastItems} onClose={onToastClose} />
+ */
+export function ToastHost({ items, onClose }: ToastHostProps) {
+  const stackGroups = items.reduce<ToastStackGroup[]>((groups, item) => {
+    const stackKey = `${item.y}-${item.x}-${String(item.margin)}`;
+    const nextGroup = groups.find(group => group.stackKey === stackKey);
+
+    if (nextGroup) {
+      nextGroup.items.push(item);
+      return groups;
+    }
+
+    groups.push({
+      stackKey,
+      x: item.x,
+      y: item.y,
+      margin: item.margin,
+      items: [item],
+    });
+
+    return groups;
+  }, []);
+
+  if (!stackGroups.length) {
+    return null;
+  }
+
+  return (
+    <Fragment>
+      {stackGroups.map(group => {
+        const stackMargin =
+          typeof group.margin === "number" ? `${group.margin}px` : group.margin;
+        const stackStyle: ToastStackStyle = {
+          "--toast-stack-margin": stackMargin,
+        };
+
+        return (
+          <div
+            key={group.stackKey}
+            className="toast-stack"
+            data-x={group.x}
+            data-y={group.y}
+            style={stackStyle}
+          >
+            {group.items.map((item: ToastItemData) => (
+              <ToastItem
+                key={item.toastKey}
+                toastKey={item.toastKey}
+                duration={item.duration}
+                state={item.state}
+                message={item.message}
+                description={item.description}
+                onClose={onClose}
+              />
+            ))}
+          </div>
+        );
+      })}
+    </Fragment>
+  );
+}

package/src/components/toast/markup/Icon.tsx

@@ -0,0 +1,15 @@
+import ErrorIcon from "../img/error.svg";
+import SuccessIcon from "../img/success.svg";
+import WarningIcon from "../img/warning.svg";
+
+/**
+ * Toast Icon Set; 상태별 아이콘 컴포넌트 맵
+ * @desc
+ * - standard는 Figma 기준 아이콘을 렌더링하지 않는다.
+ * - success/warning/error는 제공된 state SVG를 사용한다.
+ */
+export const ToastIcon = {
+  success: SuccessIcon,
+  warning: WarningIcon,
+  error: ErrorIcon,
+} as const;

package/src/components/toast/markup/Item.tsx

@@ -0,0 +1,100 @@
+import clsx from "clsx";
+import { createElement, forwardRef, useEffect, useState } from "react";
+
+import type { ToastItemProps } from "../types";
+import type { ToastItemStyle } from "../types/internal";
+import { ToastIcon } from "./Icon";
+import { ToastText } from "./Text";
+
+const TOAST_TRANSITION_MS = 600;
+
+/**
+ * Toast Item; 개별 Toast 메시지 렌더러
+ * @component
+ * @param {ToastItemProps} props
+ * @param {string} props.toastKey 트리거 지점을 드러내는 semantic key
+ * @param {number} props.duration 자동 닫힘까지의 시간(ms)
+ * @param {"standard" | "success" | "warning" | "error"} props.state Toast 피드백 성격
+ * @param {React.ReactNode} props.message 한 줄 메시지 콘텐츠
+ * @param {React.ReactNode} [props.description] 선택 보조 콘텐츠
+ * @param {(toastKey: string) => void} props.onClose 닫힘 요청 핸들러
+ * @example
+ * <Toast.Item toastKey="save-success" duration={3000} state="success" message="저장되었습니다." onClose={onClose} />
+ */
+const ToastItem = forwardRef<HTMLElementTagNameMap["section"], ToastItemProps>(
+  (
+    {
+      toastKey,
+      duration,
+      state,
+      message,
+      description,
+      onClose,
+      className,
+      role,
+      style,
+      ...restProps
+    },
+    ref,
+  ) => {
+    const [isVisible, setIsVisible] = useState(false);
+    const toastStyle: ToastItemStyle = {
+      ...style,
+      "--toast-transition-duration": `${TOAST_TRANSITION_MS}ms`,
+    };
+
+    useEffect(() => {
+      // 변경: mount 직후 open phase를 분리해 enter transition이 실제 렌더 프레임에서 실행되게 한다.
+      const enterFrameId = window.requestAnimationFrame(() => {
+        setIsVisible(true);
+      });
+      let exitTimerId: number | undefined;
+
+      // 변경: duration 만료 후 즉시 제거하지 않고 closed phase를 거쳐 exit transition을 보장한다.
+      const closeTimerId = window.setTimeout(() => {
+        setIsVisible(false);
+        exitTimerId = window.setTimeout(() => {
+          onClose(toastKey);
+        }, TOAST_TRANSITION_MS);
+      }, duration);
+
+      return () => {
+        window.cancelAnimationFrame(enterFrameId);
+        window.clearTimeout(closeTimerId);
+        if (typeof exitTimerId === "number") {
+          window.clearTimeout(exitTimerId);
+        }
+      };
+    }, [duration, onClose, toastKey]);
+
+    return (
+      <section
+        {...restProps}
+        ref={ref}
+        className={clsx("toast", className)}
+        data-phase={isVisible ? "open" : "closed"}
+        data-state={state}
+        data-toast-key={toastKey}
+        role={role ?? "status"}
+        aria-live="polite"
+        style={toastStyle}
+      >
+        {state === "standard" ? null : (
+          <figure className="toast-icon" aria-hidden="true">
+            {createElement(ToastIcon[state])}
+          </figure>
+        )}
+        <div className="toast-content">
+          <ToastText>{message}</ToastText>
+          {description ? (
+            <ToastText className="toast-description">{description}</ToastText>
+          ) : null}
+        </div>
+      </section>
+    );
+  },
+);
+
+ToastItem.displayName = "Toast.Item";
+
+export { ToastItem };

package/src/components/toast/markup/Text.tsx

@@ -0,0 +1,21 @@
+import clsx from "clsx";
+import { Slot } from "../../slot";
+import type { ToastTextProps } from "../types/internal";
+
+/**
+ * Toast Text; Toast 텍스트 className 계약을 고정하는 전용 마크업
+ * @component
+ * @param {object} props
+ * @param {React.ReactNode} [props.children] 문자열/숫자는 p 태그로 감싸고, ReactNode는 그대로 렌더링한다.
+ * @param {string} [props.className] 텍스트 className
+ * @example
+ * <ToastText>저장되었습니다.</ToastText>
+ */
+export function ToastText({ children, className }: ToastTextProps) {
+  // 변경: Toast 메시지 텍스트는 Slot.Text로 위임해 string | number 래핑 규칙을 유지한다.
+  return (
+    <Slot.Text as="p" className={clsx("toast-text", className)}>
+      {children}
+    </Slot.Text>
+  );
+}

package/src/components/toast/markup/index.tsx

@@ -0,0 +1,16 @@
+import { ToastHost } from "./Host";
+import { ToastItem } from "./Item";
+
+/**
+ * Toast; semantic feedback toast namespace
+ * @desc
+ * - `Toast.Host`: item data를 x/y/margin별 stack으로 렌더링한다.
+ * - `Toast.Item`: 개별 toast content와 timer close를 담당한다.
+ */
+export const Toast = {
+  Host: ToastHost,
+  Item: ToastItem,
+};
+
+export { ToastHost, ToastItem };
+export * from "./Icon";

package/src/components/toast/styles/index.scss

@@ -0,0 +1,2 @@
+@use "./variables";
+@use "./toast";

package/src/components/toast/styles/toast.scss

@@ -0,0 +1,113 @@
+.toast-stack {
+  --toast-stack-translate-x: 0;
+  --toast-stack-translate-y: 0;
+  position: fixed;
+  z-index: var(--toast-stack-z-index);
+  display: flex;
+  flex-direction: column;
+  gap: var(--toast-stack-gap);
+  pointer-events: none;
+  transform: translate(
+    var(--toast-stack-translate-x),
+    var(--toast-stack-translate-y)
+  );
+}
+
+.toast-stack:where([data-x="left"]) {
+  left: var(--toast-stack-margin);
+  --toast-transition-x: calc(var(--toast-transition-distance) * -1);
+}
+
+.toast-stack:where([data-x="center"]) {
+  left: 50%;
+  --toast-stack-translate-x: -50%;
+  --toast-transition-distance: -80%;
+}
+
+.toast-stack:where([data-x="right"]) {
+  right: var(--toast-stack-margin);
+  --toast-transition-x: var(--toast-transition-distance);
+}
+
+.toast-stack:where([data-y="top"]) {
+  top: var(--toast-stack-margin);
+}
+
+.toast-stack:where([data-y="center"]) {
+  top: 50%;
+  --toast-stack-translate-y: -50%;
+}
+
+.toast-stack:where([data-y="bottom"]) {
+  bottom: var(--toast-stack-margin);
+}
+
+.toast-stack:where([data-x="center"][data-y="top"]) {
+  --toast-transition-y: calc(var(--toast-transition-distance) * -1);
+}
+
+.toast-stack:where([data-x="center"][data-y="bottom"]) {
+  --toast-transition-y: var(--toast-transition-distance);
+}
+
+.toast {
+  display: flex;
+  align-items: center;
+  width: min(var(--toast-width), calc(100vw - (var(--toast-stack-margin) * 2)));
+  box-sizing: border-box;
+  gap: var(--toast-gap);
+  overflow: hidden;
+  padding: var(--toast-padding-block) var(--toast-padding-inline);
+  border-radius: var(--toast-radius);
+  background-color: var(--toast-background-color);
+  opacity: 0;
+  pointer-events: auto;
+  transform: translate(var(--toast-transition-x), var(--toast-transition-y));
+  transition:
+    opacity var(--toast-transition-duration) var(--toast-transition-easing),
+    transform var(--toast-transition-duration) var(--toast-transition-easing);
+}
+
+.toast:where([data-phase="open"]) {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.toast-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: var(--toast-icon-size);
+  height: var(--toast-icon-size);
+  margin: 0;
+}
+
+.toast-icon svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.toast-content {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  flex-direction: column;
+}
+
+.toast-text {
+  overflow: hidden;
+  margin: 0;
+  color: var(--toast-foreground-color);
+  font-size: var(--toast-message-font-size);
+  line-height: var(--toast-message-line-height);
+  letter-spacing: var(--toast-message-letter-spacing);
+  font-weight: var(--toast-message-font-weight);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.toast-description {
+  opacity: 0.82;
+}

package/src/components/toast/styles/variables.scss

@@ -0,0 +1,24 @@
+:root {
+  --toast-stack-margin: var(--spacing-padding-7);
+  --toast-stack-gap: var(--spacing-gap-3);
+  --toast-stack-z-index: 10000;
+
+  --toast-width: 361px;
+  --toast-background-color: var(--color-surface-heavy);
+  --toast-foreground-color: var(--color-common-100);
+  --toast-radius: var(--theme-radius-large-1);
+  --toast-padding-block: var(--spacing-padding-5);
+  --toast-padding-inline: var(--spacing-padding-7);
+  --toast-gap: var(--spacing-gap-5);
+  --toast-icon-size: 24px;
+  --toast-transition-duration: 0.6s;
+  --toast-transition-easing: cubic-bezier(0.16, 1, 0.3, 1);
+  --toast-transition-distance: -24%;
+  --toast-transition-x: 0;
+  --toast-transition-y: 0;
+
+  --toast-message-font-size: var(--font-body-xsmall-size);
+  --toast-message-line-height: var(--font-body-xsmall-line-height);
+  --toast-message-letter-spacing: var(--font-body-xsmall-letter-spacing);
+  --toast-message-font-weight: var(--font-body-xsmall-weight);
+}

package/src/components/toast/types/index.ts

@@ -0,0 +1 @@
+export type * from "./props";

package/src/components/toast/types/internal.ts

@@ -0,0 +1,71 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ToastHorizontal, ToastItemData, ToastVertical } from "./props";
+
+/**
+ * Toast text props; Toast 메시지 텍스트 렌더링 props
+ * @property {ReactNode} [children] 문자열/숫자는 p 태그로 감싸고, ReactNode는 그대로 렌더링한다.
+ * @property {string} [className] 텍스트 className
+ */
+export interface ToastTextProps {
+  /**
+   * 문자열/숫자는 p 태그로 감싸고, ReactNode는 그대로 렌더링한다.
+   */
+  children?: ReactNode;
+  /**
+   * 텍스트 className
+   */
+  className?: string;
+}
+
+/**
+ * Toast stack group; Host 내부 placement bucket
+ * @property {string} stackKey x/y/margin 조합으로 만든 stack key
+ * @property {"left" | "center" | "right"} x Toast stack 가로 위치
+ * @property {"top" | "center" | "bottom"} y Toast stack 세로 위치
+ * @property {number | string} margin page frame 기준 위치 간격
+ * @property {ToastItemData[]} items 같은 위치에 stack될 Toast 목록
+ */
+export interface ToastStackGroup {
+  /**
+   * x/y/margin 조합으로 만든 stack key
+   */
+  stackKey: string;
+  /**
+   * Toast stack 가로 위치
+   */
+  x: ToastHorizontal;
+  /**
+   * Toast stack 세로 위치
+   */
+  y: ToastVertical;
+  /**
+   * page frame 기준 위치 간격
+   */
+  margin: number | string;
+  /**
+   * 같은 위치에 stack될 Toast 목록
+   */
+  items: ToastItemData[];
+}
+
+/**
+ * Toast stack style; 런타임 margin CSS 변수 주입 타입
+ * @property {string} --toast-stack-margin page frame 기준 위치 간격 CSS 값
+ */
+export interface ToastStackStyle extends CSSProperties {
+  /**
+   * page frame 기준 위치 간격 CSS 값
+   */
+  ["--toast-stack-margin"]: string;
+}
+
+/**
+ * Toast item style; transition duration CSS 변수 주입 타입
+ * @property {string} --toast-transition-duration Toast enter/exit transition 시간 CSS 값
+ */
+export interface ToastItemStyle extends CSSProperties {
+  /**
+   * Toast enter/exit transition 시간 CSS 값
+   */
+  ["--toast-transition-duration"]: string;
+}

package/src/components/toast/types/props.ts

@@ -0,0 +1,128 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+
+/**
+ * Toast state; Toast 피드백 성격 축
+ * @typedef {"standard" | "success" | "warning" | "error"} ToastState
+ */
+export type ToastState = "standard" | "success" | "warning" | "error";
+
+/**
+ * Toast horizontal position; Toast stack 가로 위치 축
+ * @typedef {"left" | "center" | "right"} ToastHorizontal
+ */
+export type ToastHorizontal = "left" | "center" | "right";
+
+/**
+ * Toast vertical position; Toast stack 세로 위치 축
+ * @typedef {"top" | "center" | "bottom"} ToastVertical
+ */
+export type ToastVertical = "top" | "center" | "bottom";
+
+/**
+ * Toast item data; 트리거 로직이 생성하는 Toast 렌더링 데이터
+ * @property {string} toastKey 트리거 지점을 드러내는 semantic key
+ * @property {"left" | "center" | "right"} x Toast stack 가로 위치
+ * @property {"top" | "center" | "bottom"} y Toast stack 세로 위치
+ * @property {number | string} margin page frame 기준 위치 간격
+ * @property {number} duration 자동 닫힘까지의 시간(ms)
+ * @property {"standard" | "success" | "warning" | "error"} state Toast 피드백 성격
+ * @property {ReactNode} message 한 줄 메시지 콘텐츠
+ * @property {ReactNode} [description] 선택 보조 콘텐츠
+ */
+export interface ToastItemData {
+  /**
+   * 트리거 지점을 드러내는 semantic key
+   */
+  toastKey: string;
+  /**
+   * Toast stack 가로 위치
+   */
+  x: ToastHorizontal;
+  /**
+   * Toast stack 세로 위치
+   */
+  y: ToastVertical;
+  /**
+   * page frame 기준 위치 간격
+   */
+  margin: number | string;
+  /**
+   * 자동 닫힘까지의 시간(ms)
+   */
+  duration: number;
+  /**
+   * Toast 피드백 성격
+   */
+  state: ToastState;
+  /**
+   * 한 줄 메시지 콘텐츠
+   */
+  message: ReactNode;
+  /**
+   * 선택 보조 콘텐츠
+   */
+  description?: ReactNode;
+}
+
+type NativeToastItemProps = Omit<
+  ComponentPropsWithoutRef<"section">,
+  "children"
+>;
+
+/**
+ * Toast item props; 개별 Toast 렌더링 props
+ * @property {string} toastKey 트리거 지점을 드러내는 semantic key
+ * @property {number} duration 자동 닫힘까지의 시간(ms)
+ * @property {"standard" | "success" | "warning" | "error"} state Toast 피드백 성격
+ * @property {ReactNode} message 한 줄 메시지 콘텐츠
+ * @property {ReactNode} [description] 선택 보조 콘텐츠
+ * @property {(toastKey: string) => void} onClose 닫힘 요청 핸들러
+ * @property {string} [className] Toast item className
+ * @see React.ComponentPropsWithoutRef<"section">
+ */
+export interface ToastItemProps extends NativeToastItemProps {
+  /**
+   * 트리거 지점을 드러내는 semantic key
+   */
+  toastKey: string;
+  /**
+   * 자동 닫힘까지의 시간(ms)
+   */
+  duration: number;
+  /**
+   * Toast 피드백 성격
+   */
+  state: ToastState;
+  /**
+   * 한 줄 메시지 콘텐츠
+   */
+  message: ReactNode;
+  /**
+   * 선택 보조 콘텐츠
+   */
+  description?: ReactNode;
+  /**
+   * 닫힘 요청 핸들러
+   */
+  onClose: (toastKey: string) => void;
+  /**
+   * Toast item className
+   */
+  className?: string;
+}
+
+/**
+ * Toast host props; placement별 Toast stack 렌더링 props
+ * @property {ToastItemData[]} items Toast item 데이터 목록
+ * @property {(toastKey: string) => void} onClose 닫힘 요청 핸들러
+ */
+export interface ToastHostProps {
+  /**
+   * Toast item 데이터 목록
+   */
+  items: ToastItemData[];
+  /**
+   * 닫힘 요청 핸들러
+   */
+  onClose: (toastKey: string) => void;
+}

package/src/index.scss

@@ -22,4 +22,5 @@
 @use "./components/switch";
 @use "./components/tab";
 @use "./components/table";
+@use "./components/toast";
 @use "./components/tooltip";

package/src/index.tsx

@@ -28,5 +28,6 @@ export * from "./components/spinner";
 export * from "./components/switch";
 export * from "./components/tab";
 export * from "./components/table";
+export * from "./components/toast";
 export * from "./components/tooltip";
 export type * from "./types";