npm package: @lotte-innovate/lui
Description: Lotte UI Library
Latest version: 0.1.106

# LOTTE UI COMPONENT LIBRARY

<br />

## 목차

- [Introduction](#introduction)
- [Installation](#installation)
- [Setup](#setup)
- [Usage](#usage)
- [Components](#components)
- [Theme](#theme)
- [License](#license)

## Introduction

모든 L-UI 구성 요소를 내보내는 단일 패키지입니다.

일관되고 통일된 컴포넌트를 제공하며 사용자 정의 및 재사용 가능합니다.

이 라이브러리는 React로 구축된 프로젝트를 지원합니다.

## Installation

패키지를 설치하기 위해 아래 명령어를 사용합니다.

```bash
  npm i @lotte-innovate/lui
```

```bash
  yarn add @lotte-innovate/lui
```

## Setup

패키지를 설치한 후 css 스타일을 프로젝트로 가져옵니다.

프로젝트 App 진입 파일에 다음 줄을 추가해줍니다.

```javascript
import '@lotte-innovate/lui/dist/globals.css';
```

## Usage

React 프로젝트에서 컴포넌트를 사용하는 방법에 대한 예시입니다.

```tsx
import React from 'react';
import { Button } from '@lotte-innovate/lui';

const App = () => {
  return (
    <div>
      <Button onClick={() => alert('Button clicked!')}>Click Me</Button>
    </div>
  );
};

export default App;
```

컴포넌트에서 아이콘을 사용하려면, 다음과 같은 방법으로 아이콘을 가져올 수 있습니다.

```tsx
import React from 'react';
import { IconButton } from '@lotte-innovate/lui';
import { MagnifyingGlassIcon } from '@radix-ui/react-icons';

const App = () => {
  return (
    <div>
      <IconButton>
        <MagnifyingGlassIcon />
      </IconButton>
    </div>
  );
};

export default App;
```

## Components

<br />

<details>
  <summary>컴포넌트 목록</summary>

| 구분                | 종류                                                                                                                          |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Typography 컴포넌트 | Header, Text                                                                                                                  |
| 기본 컴포넌트       | Avatar, Badge, Button, IconButton, Label                                                                                      |
| 입력 컴포넌트       | DatePicker, DatetimePicker, Editor, Slider, TextArea, TextField                                                               |
| 선택 컴포넌트       | Checkbox, CheckboxCards, CheckboxGroup, Radio, RadioCards, RadioGroup, Select, Toggle, ToggleGroup, ToggleSwitch              |
| 네비게이션 컴포넌트 | Breadcrumb, DynamicTabs, GNB, Menubar, NavigationMenu, SNB, Tab Nav, Tabs                                                     |
| 레이아웃 컴포넌트   | AspectRatio, Box, Card, Collapsible, Container, Flex, Footer, Grid, GridLayout, Inset, ScrollArea, Separator, Table, Timeline |
| 피드백 컴포넌트     | AlertDialog, Dialog, HoverCard, Modal, Popover, Toast, Tooltip                                                                |
| 로딩 컴포넌트       | Progress, Skeleton, Spinner                                                                                                   |
| 메뉴 선택 컴포넌트  | ContextMenu, DropdownMenu, SegmentedControl                                                                                   |
| 그 외 컴포넌트      | Accordian, Callout, DataList, SearchBar                                                                                       |

</details>
<details>
	<summary>차트 목록</summary>

| 구분      | 종류          |
| --------- | ------------- |
| 비교 차트 | Bar, Line     |
| 구성 차트 | Pie, Doughnut |
| 분포 차트 | Bubble        |
| 관계 차트 | Radar         |

</details>

<details>
  <summary>공통 Props 목록</summary>

| name       | description                                       | 단계     | option                                        | 테마적용여부 |
| ---------- | ------------------------------------------------- | -------- | --------------------------------------------- | ------------ |
| Color      | 27가지 색상을 라이트/다크/알파/알파다크 모드 제공 | 1~12단계 | blue, crimson, teal, orange, purple, amber... | O            |
| Radius     | 컴포넌트의 둥글기 적용                            | 5단계    | none, small, medium, large, full              | O            |
| Scaling    | 컴포넌트의 비율                                   | 5단계    | 90%, 95%, 100%, 105%, 110%                    | O            |
| Weight     | 컴포넌트의 텍스트 굵기                            | 4단계    | regular, medium, semibold, bold               | O            |
| Appearance | 컴포넌트의 디자인 스타일                          | 6단계    | classic, ghost, outline, soft, solid, surface | X            |
| Size       | 컴포넌트의 크기                                   | 5단계    | x-small, small, medium, large, x-large        | X            |

</details>

<br />

## Theme

각 컴포넌트들은 공통 Props를 개별적으로 적용할 수도 있고, 테마를 통해 컴포넌트의 스타일을 한번에 변경할 수도 있습니다.

L-UI는 테마 컨텍스트를 제공하여 `Color`, `Radius`, `Scaling`, `Weight` 를 모든 컴포넌트에 동일한 스타일을 지정할 수 있습니다.

먼저 App 최상단에 `LuiThemeProvider`를 추가하여 테마 컨텍스트를 제공합니다.

> Next.js와 같은 프레임워크를 사용하는 프로젝트에서 사용 예시

```tsx
import { LuiThemeProvider } from '@lotte-innovate/lui';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" className="bg-white">
      <body>
        <LuiThemeProvider>{children}</LuiThemeProvider>
      </body>
    </html>
  );
}
```

> Next.js App router 에서 Layout.tsx 을 사용하는 예시 코드

`ThemeProvider`를 프로젝트의 가장 가까운 `layout.tsx` 파일에 추가해야 합니다.

이렇게 하면 `ThemeProvider`가 해당 레이아웃 내의 모든 컴포넌트에 테마 상태를 제공할 수 있습니다.

```tsx
import React from 'react';
import { LuiThemeProvider } from '@lotte-innovate/lui';

const Layout = ({ children }: { children: React.ReactNode }) => {
  return <LuiThemeProvider>{children}</LuiThemeProvider>;
};

export default Layout;
```

> 클라이언트 사이드 프로젝트에서 사용 예시

```tsx
import { LuiThemeProvider } from '@lotte-innovate/lui';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <LuiThemeProvider>
    <App />
  </LuiThemeProvider>,
);
```

테마를 변경하려면 `useTheme`훅을 사용합니다.

`useTheme`훅은 현재 테마와 테마를 업데이트할 수 있는 함수를 제공합니다.

```tsx
import { useTheme, Button } from '@lotte-innovate/lui';

const ThemeChanger = () => {
  const { theme, updateTheme } = useTheme();

  // 초기 값 설정 시
  theme.themeRadius = 'none';
  theme.themeColor = 'olive';
  theme.themeScaling = '90%';
  theme.themeWeight = 'regular';

  // 테마 변경 시
  useEffect(() => {
    updateTheme({ themeRadius: 'full', themeColor: 'amber', themeScaling: '110%' });
  }, []);

  return (
    <div>
      <Button>버튼</Button>
    </div>
  );
};
```

테마가 적용되었지만 일부 컴포넌트는 스타일을 다르게 하고 싶은 경우, 각 컴포넌트에 직접 Props를 전달하여 스타일을 재정의할 수 있습니다.

```tsx
import { useTheme, Button } from '@lotte-innovate/lui';

const ThemeChanger = () => {
  const { theme } = useTheme();

  theme.themeRadius: 'full';
  theme.themeColor: 'blue';

  return (
    <div>
      <Button>테마 적용 버튼</Button>
      <Button radius="none" color="crimson">테마 미적용 버튼</Button>
    </div>
  );
};
```

<br />

## License

@lotte-innovate