@uniai-fe/uds-primitives 0.5.6 → 0.6.1

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