@sellmate/design-system-react

v1.23.0

Published

2 days ago

Design System - React Component Wrappers

0High
0Medium
0Low

kimeunjin

sellmate_ej

meijjing

react web-components design-system ui-library

Sellmate Design System - React

React component wrappers for Sellmate Design System built with Stencil web components.

Installation

npm install @sellmate/design-system-react

Project Setup

커스텀 엘리먼트는 패키지 import 시점에 자동 등록됩니다. defineCustomElements() 별도 호출이나 StencilProvider 설정은 불필요합니다.

React (Vite / CRA)

1. CSS 전역 import — src/main.tsx

import "@sellmate/design-system/styles.css";

2. SdModalContainer 최상단 배치 — src/App.tsx

sdModal은 sd-modal-container를 자동으로 생성하지만, z-index 제어 및 렌더 위치를 명시적으로 지정하려면 루트에 배치합니다.

import { SdModalContainer } from "@sellmate/design-system-react";

export default function App() {
  return (
    <>
      <SdModalContainer />
      {/* 라우터, 레이아웃 등 */}
    </>
  );
}

Next.js (App Router)

1. CSS 전역 import — app/layout.tsx

import "@sellmate/design-system/styles.css";

2. 'use client' 필수 — 컴포넌트를 사용하는 모든 파일에 선언 필요

"use client";

import { SdButton } from "@sellmate/design-system-react/next";

3. SdModalContainer 루트 배치 — app/layout.tsx

layout.tsx는 서버 컴포넌트이므로 클라이언트 전용 Provider를 별도 파일로 분리합니다.

// app/providers.tsx
"use client";

import { SdModalContainer } from "@sellmate/design-system-react/next";

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <>
      <SdModalContainer />
      {children}
    </>
  );
}

// app/layout.tsx
import "@sellmate/design-system/styles.css";
import Providers from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

4. 컴포넌트 import — dynamic({ ssr: false }) 패턴

"use client";

import dynamic from "next/dynamic";

const SdButton = dynamic(
  () =>
    import("@sellmate/design-system-react").then((mod) => ({
      default: mod.SdButton,
    })),
  { ssr: false, loading: () => <></> },
);

Utility Functions

`sdModal` — `@sellmate/design-system-react`

React 컴포넌트를 모달로 열 수 있는 React-aware 버전입니다.

import { sdModal } from "@sellmate/design-system-react";

// Confirm 모달
sdModal
  .confirm({
    type: "positive" | "negative" | "default",
    title: "제목",
    topMessage: ["메시지"],
    mainButtonLabel: "확인",
    subButtonLabel: "취소",
    persistent: false, // true 시 ESC/백드롭으로 닫기 불가
  })
  .onOk(() => {})
  .onCancel(() => {})
  .onClose(() => {});

// React 컴포넌트를 모달로 열기
sdModal.create({
  component: MyModalComponent,
  componentProps: { title: "제목" }, // 컴포넌트에 전달할 props
  persistent: true,
});

// Loading 모달
const dialog = sdModal.loading({ state: "loading" });
dialog.update({ state: "error", message: "오류 발생" });
dialog.close();

// 전역 설정
sdModal.configure({ zIndex: 1000 });

주의: sdModal.create에 React 컴포넌트를 전달하면 내부적으로 새로운 React 루트가 생성됩니다. 부모 트리의 Context(Redux, React Router, Theme 등)가 자동으로 상속되지 않으므로 모달 컴포넌트 내부에서 필요한 Provider를 직접 감싸야 합니다.

`sdToast` — `@sellmate/design-system/utils`

import { sdToast } from "@sellmate/design-system/utils";

// 토스트 생성
await sdToast.create("메시지", "success" | "error" | "warning" | "info");

// 개별/전체 닫기
await sdToast.dismiss(id);
await sdToast.dismissAll();

// 전역 설정
sdToast.configure({
  position: "top-right",
  maxVisible: 5,
  defaultDuration: 3000,
  zIndex: 9999,
});

sdToast는 sd-toast-container를 자동으로 생성하므로 별도의 Provider 배치가 불필요합니다.

`sdLoading` — `@sellmate/design-system-react`

import { sdLoading } from "@sellmate/design-system-react";

const hide = sdLoading.show(); // 전체화면 로딩 표시
hide(); // 로딩 숨김

sdLoading.show({ message: "처리 중..." });

Available Components

입력

| 컴포넌트 | 설명 | | ------------------- | -------------------------- | | SdInput | 텍스트 입력 | | SdNumberInput | 숫자 입력 | | SdTextarea | 멀티라인 텍스트 입력 | | SdBarcodeInput | 바코드 스캐너 입력 | | SdCheckbox | 체크박스 | | SdRadio | 라디오 버튼 | | SdRadioGroup | 라디오 그룹 | | SdRadioButton | 버튼형 라디오 | | SdSwitch | 스위치 토글 | | SdToggle | 토글 | | SdSelect | 단일/다중 선택 (그룹 지원) | | SdDatePicker | 날짜 선택 | | SdDateRangePicker | 날짜 범위 선택 | | SdFilePicker | 파일 선택 |

버튼

| 컴포넌트 | 설명 | | ------------------ | ---------------- | | SdButton | 기본 버튼 | | SdGhostButton | 고스트 버튼 | | SdDropdownButton | 드롭다운 버튼 | | SdTextLink | 텍스트 링크 버튼 |

표시

| 컴포넌트 | 설명 | | -------------------- | ---------------------- | | SdTag | 태그 | | SdBadge | 뱃지 | | SdIcon | 아이콘 | | SdTooltip | 툴팁 | | SdPopover | 팝오버 | | SdLinearProgress | 선형 진행 바 | | SdCircleProgress | 원형 진행 바 | | SdLoadingContainer | 로딩 오버레이 컨테이너 | | SdGuide | 가이드 텍스트 | | SdCard | 카드 |

레이아웃 / 구조

| 컴포넌트 | 설명 | | -------------- | ------------------------------------ | | SdField | 폼 필드 래퍼 (label + input + error) | | SdForm | 폼 유효성 검사 컨테이너 | | SdTabs | 탭 네비게이션 | | SdTable | 데이터 테이블 | | SdPagination | 페이지네이션 |

모달 / 알림

| 컴포넌트 | 설명 | | ------------------ | ------------------------------------ | | SdModalContainer | sdModal Provider (루트에 1회 배치) | | SdConfirmModal | Confirm 모달 (직접 렌더) | | SdActionModal | Action 모달 (직접 렌더) | | SdLoadingModal | Loading 모달 (직접 렌더) | | SdToastContainer | Toast 컨테이너 (sdToast가 자동 생성) | | SdToast | 개별 Toast |

Available Types

import type {
  // Table
  SdTableColumn,
  SdTableRow,
  // Select
  SelectOption,
  // Radio
  RadioValue,
  RadioOption,
  // Button
  ButtonName,
  DropdownButtonItem,
  // Form
  Rule,
  ValidatableField,
  // Checkbox
  CheckedType,
  // Tag
  TagName,
  // Toast
  ToastType,
  // DateBox
  DateBoxType,
  // Tabs
  TabOption,
  // sdModal
  SdModalCreateOption,
} from "@sellmate/design-system-react";

Hooks

`useSdTableVirtualScroll`

import { useSdTableVirtualScroll } from "@sellmate/design-system-react";

const { virtualRows, totalHeight, scrollToIndex } = useSdTableVirtualScroll({
  rowCount: data.length,
  rowHeight: 48,
  containerHeight: 400,
});

Requirements

React 16.8.0 or higher
React DOM 16.8.0 or higher

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme