지제이웍스 | Gjworks

import Button from "@components/button/Button";

<Button icon={<Settings size={14} />}>기본 버튼</Button>
<Button isLoading>저장 중</Button>
<Button fullWidth>전체 너비</Button>

Tab

`Tab`은 서로 관련된 화면을 같은 맥락 안에서 전환할 때 사용합니다. 회원 목록/회원 추가/그룹 관리, 설정 카테고리, 알림 필터처럼 현재 페이지 안에서 뷰만 바뀌는 구조에 적합합니다.

회원 목록 패널

목록 탭 예시입니다.

items

`value`, `label`, `content`를 기본으로 받고 `icon`, `badge`, `href`, `disabled`를 선택적으로 지원합니다.

value / defaultValue

`value`를 넘기면 controlled, `defaultValue`만 넘기면 uncontrolled로 동작합니다.

variant

`line`, `pill`, `boxed`를 지원합니다. 기본값은 `line`입니다.

renderPanel

링크형 탭처럼 패널이 필요 없으면 `false`로 둡니다.

keepMounted

탭 전환 후에도 각 패널의 내부 상태를 유지해야 할 때 사용합니다.

import Tab from "@components/tab/Tab";

<Tab
  defaultValue="members"
  variant="line"
  items={[
    { value: "members", label: "회원 목록", content: <MemberList /> },
    { value: "create", label: "회원 추가", content: <MemberCreate /> },
  ]}
/>

<Tab
  value="list"
  variant="pill"
  renderPanel={false}
  items={[
    { value: "list", label: "회원 목록", href: "/admin/user/list" },
    { value: "group", label: "그룹 관리", href: "/admin/user/groupList" },
  ]}
/>

Form Fields

`InputField`와 `SelectField`는 label, focus, disabled, error 상태를 같은 구조로 보여줍니다. 서버 액션에서 받은 `fieldErrors`는 Alert로 올리지 말고 해당 input의 `error`에 연결하는 것을 기본 규칙으로 둡니다.

이메일

비밀번호

비밀번호를 입력해주세요.

게시판 타입

검색어

inputTitle

label 텍스트입니다. 화면에 label이 필요 없을 때는 `hideLabel`과 함께 씁니다.

name / id

form 전송과 접근성 연결에 사용합니다. 가능하면 둘 중 하나는 꼭 넣습니다.

icon

입력 목적을 빠르게 구분해야 할 때 lucide 아이콘을 전달합니다.

error

fieldErrors의 첫 번째 메시지를 넘겨 input 아래에 표시합니다.

getData

간단한 값 콜백이 필요할 때 사용합니다. react-hook-form이면 일반 `onChange`나 register를 우선합니다.

<InputField
  inputTitle="이메일"
  name="email"
  placeholder="hello@example.com"
  icon={<Mail size={16} />}
  error={fieldErrors?.email?.[0]}
/>

<SelectField
  inputTitle="게시판 타입"
  name="boardType"
  options={[
    { id: "default", title: "기본 게시판" },
    { id: "issue", title: "이슈 트래커" },
  ]}
/>

Modal

`Modal`은 삭제 확인, 그룹 추가, 첨부파일 선택처럼 페이지 맥락을 유지한 채 짧은 결정을 받아야 할 때 사용합니다. 긴 문서나 화면 전환성 콘텐츠에는 `Bottom`이 더 적합합니다.

state / close

열림 상태와 닫기 함수를 부모가 관리합니다.

size

`sm`, `md`, `lg`, `xl`, `2xl` 중 선택합니다. 기본값은 `md`입니다.

position

`center`, `top`, `bottom`을 지원합니다.

escClose / overlayClose

작성 중인 form처럼 실수로 닫히면 안 되는 작업에서 false로 둡니다.

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Modal 열기</Button>
<Modal state={open} close={setOpen} size="md" position="center">
  <ModalContent />
</Modal>

Bottom

`Bottom`은 아래에서 올라오는 보조 화면입니다. 모바일 선택 UI, 긴 보조 작업, 임시 문서 패널처럼 현재 화면의 맥락을 유지한 채 별도 흐름을 열어야 할 때 사용합니다.

Bottom panel preview

실제 컴포넌트는 portal로 렌더링되며, 닫을 때 `closeHref`가 있으면 해당 주소로 이동합니다.

closeHref

닫을 때 특정 주소로 이동해야 하면 지정합니다. 없으면 `router.back()`을 사용합니다.

drag down

아래로 120px 이상 끌거나 빠르게 아래로 튕기면 닫힙니다.

animation

`bottom` 위치값 대신 `translateY` 기반으로 움직여 Windows와 큰 화면에서 부하를 줄입니다.

import Bottom from "@components/panel/Bottom";

const HelperPanel = ({ children }: { children: React.ReactNode }) => {
  return <Bottom closeHref="/">{children}</Bottom>;
};

Accordion / Dropdown

`Accordion`은 정보를 접어 읽기 부담을 줄일 때 사용합니다. `Dropdown`은 계정 메뉴, 빠른 액션, 필터 메뉴처럼 버튼 주변에 짧은 선택지를 띄울 때 사용합니다.

`allowMultiple`을 true로 주면 여러 항목을 동시에 열 수 있습니다. 설정 문서나 FAQ에 적합합니다.

<Accordion items={items} allowMultiple />

<div className="relative">
  <Button onClick={() => setOpen((prev) => !prev)}>메뉴</Button>
  <Dropdown state={open} close={setOpen} className="left-0 top-full mt-2">
    <div className="rounded-lg border bg-white p-2 shadow-xl">
      ...
    </div>
  </Dropdown>
</div>

Feedback

`Alert`는 반드시 필요한 전역성 안내에만 씁니다. 입력값 오류는 `InputField`의 `error`로 내려보내고, 작업 전체가 실패했거나 권한/시스템 문제처럼 특정 필드에 붙일 수 없는 경우에 Alert를 사용합니다.

저장되었습니다.

일부 설정은 서버 재시작 후 반영됩니다.

권한이 없거나 요청을 처리할 수 없습니다.

<Alert type="success" message="저장되었습니다." />
<Alert type="warning" message="일부 설정은 서버 재시작 후 반영됩니다." />
<Alert type="error" message="권한이 없거나 요청을 처리할 수 없습니다." />

Button

import Button from "@components/button/Button";

<Button icon={<Settings size={14} />}>기본 버튼</Button>
<Button isLoading>저장 중</Button>
<Button fullWidth>전체 너비</Button>

Tab

회원 목록 패널

목록 탭 예시입니다.

items

`value`, `label`, `content`를 기본으로 받고 `icon`, `badge`, `href`, `disabled`를 선택적으로 지원합니다.

value / defaultValue

`value`를 넘기면 controlled, `defaultValue`만 넘기면 uncontrolled로 동작합니다.

variant

`line`, `pill`, `boxed`를 지원합니다. 기본값은 `line`입니다.

renderPanel

링크형 탭처럼 패널이 필요 없으면 `false`로 둡니다.

keepMounted

탭 전환 후에도 각 패널의 내부 상태를 유지해야 할 때 사용합니다.

import Tab from "@components/tab/Tab";

<Tab
  defaultValue="members"
  variant="line"
  items={[
    { value: "members", label: "회원 목록", content: <MemberList /> },
    { value: "create", label: "회원 추가", content: <MemberCreate /> },
  ]}
/>

<Tab
  value="list"
  variant="pill"
  renderPanel={false}
  items={[
    { value: "list", label: "회원 목록", href: "/admin/user/list" },
    { value: "group", label: "그룹 관리", href: "/admin/user/groupList" },
  ]}
/>

Form Fields

이메일

비밀번호

비밀번호를 입력해주세요.

게시판 타입

검색어

inputTitle

label 텍스트입니다. 화면에 label이 필요 없을 때는 `hideLabel`과 함께 씁니다.

name / id

form 전송과 접근성 연결에 사용합니다. 가능하면 둘 중 하나는 꼭 넣습니다.

icon

입력 목적을 빠르게 구분해야 할 때 lucide 아이콘을 전달합니다.

error

fieldErrors의 첫 번째 메시지를 넘겨 input 아래에 표시합니다.

getData

간단한 값 콜백이 필요할 때 사용합니다. react-hook-form이면 일반 `onChange`나 register를 우선합니다.

<InputField
  inputTitle="이메일"
  name="email"
  placeholder="hello@example.com"
  icon={<Mail size={16} />}
  error={fieldErrors?.email?.[0]}
/>

<SelectField
  inputTitle="게시판 타입"
  name="boardType"
  options={[
    { id: "default", title: "기본 게시판" },
    { id: "issue", title: "이슈 트래커" },
  ]}
/>

Modal

state / close

열림 상태와 닫기 함수를 부모가 관리합니다.

size

`sm`, `md`, `lg`, `xl`, `2xl` 중 선택합니다. 기본값은 `md`입니다.

position

`center`, `top`, `bottom`을 지원합니다.

escClose / overlayClose

작성 중인 form처럼 실수로 닫히면 안 되는 작업에서 false로 둡니다.

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Modal 열기</Button>
<Modal state={open} close={setOpen} size="md" position="center">
  <ModalContent />
</Modal>

Bottom

Bottom panel preview

실제 컴포넌트는 portal로 렌더링되며, 닫을 때 `closeHref`가 있으면 해당 주소로 이동합니다.

closeHref

닫을 때 특정 주소로 이동해야 하면 지정합니다. 없으면 `router.back()`을 사용합니다.

drag down

아래로 120px 이상 끌거나 빠르게 아래로 튕기면 닫힙니다.

animation

`bottom` 위치값 대신 `translateY` 기반으로 움직여 Windows와 큰 화면에서 부하를 줄입니다.

import Bottom from "@components/panel/Bottom";

const HelperPanel = ({ children }: { children: React.ReactNode }) => {
  return <Bottom closeHref="/">{children}</Bottom>;
};

Accordion / Dropdown

`allowMultiple`을 true로 주면 여러 항목을 동시에 열 수 있습니다. 설정 문서나 FAQ에 적합합니다.

<Accordion items={items} allowMultiple />

<div className="relative">
  <Button onClick={() => setOpen((prev) => !prev)}>메뉴</Button>
  <Dropdown state={open} close={setOpen} className="left-0 top-full mt-2">
    <div className="rounded-lg border bg-white p-2 shadow-xl">
      ...
    </div>
  </Dropdown>
</div>

Feedback

저장되었습니다.

일부 설정은 서버 재시작 후 반영됩니다.

권한이 없거나 요청을 처리할 수 없습니다.

<Alert type="success" message="저장되었습니다." />
<Alert type="warning" message="일부 설정은 서버 재시작 후 반영됩니다." />
<Alert type="error" message="권한이 없거나 요청을 처리할 수 없습니다." />

Components

사용 원칙

Button

Tab

Form Fields

Modal

Bottom

Accordion / Dropdown

Feedback

Components

사용 원칙

Button

Tab

Form Fields

Modal

Bottom

Accordion / Dropdown

Feedback