# KRDS Vue

> 대한민국 정부 디자인 시스템(KRDS)을 Vue 3와 TypeScript로 구현한 컴포넌트 라이브러리(@krds.ui/vue) 문서입니다.

---

# 시작하기

KRDS Vue는 [KRDS(대한민국 정부 디자인 시스템)](https://www.krds.go.kr/html/site/index.html)를 Vue 3 + TypeScript 환경에서 사용할 수 있도록 구현한 컴포넌트 라이브러리입니다. 이 패키지는 **ESM 전용**이며 CommonJS `require()`는 지원하지 않습니다.

## 설치

```sh [pnpm]
pnpm add @krds.ui/vue
```

```sh [npm]
npm install @krds.ui/vue
```

```sh [yarn]
yarn add @krds.ui/vue
```

## 스타일

애플리케이션 엔트리에서 스타일을 한 번 import합니다. CSS 안의 아이콘 URL은 패키지의 `dist/img` 자산을 기준으로 상대 경로를 사용합니다.

```ts
import '@krds.ui/vue/style'
```

## 전역 플러그인 등록

```ts
import { createApp } from 'vue'
import KrdsVue from '@krds.ui/vue'
import '@krds.ui/vue/style'
import App from './App.vue'

createApp(App).use(KrdsVue).mount('#app')
```

특정 컴포넌트만 전역 등록할 수도 있습니다.

```ts
app.use(KrdsVue, {
  components: ['KrdsButton', 'KrdsInput', 'KrdsModal']
})
```

전역 등록한 컴포넌트의 템플릿 타입 검사·자동완성(Volar/vue-tsc)을 쓰려면 `tsconfig.json`에 전역 타입을 추가합니다. 전체 컴포넌트와 `v-sr-only`, `$krds`가 전역으로 선언되므로 일부만 등록했다면 등록하지 않은 컴포넌트 사용에 주의하세요.

```json
{
  "compilerOptions": {
    "types": ["@krds.ui/vue/global"]
  }
}
```

WebStorm 등 JetBrains IDE는 이 설정 대신 패키지에 든 `web-types.json`으로 전역 컴포넌트를 인식하므로 따로 설정할 것이 없습니다.

## 개별 컴포넌트 import

전역 등록이 필요 없다면 필요한 컴포넌트만 가져옵니다. 이 문서의 예제도 모두 이 방식으로 작성되어 있어 그대로 복사해 쓸 수 있습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsFormGroup, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'

  const name = ref('')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="name">이름</KrdsFormLabel>
    <KrdsInput id="name" v-model="name" placeholder="이름을 입력하세요" required />
  </KrdsFormGroup>

  <KrdsButton variant="primary" size="medium">확인</KrdsButton>
</template>
```

## Nuxt

서버 렌더링을 지원합니다. 스타일은 `nuxt.config.ts`에 추가하고, 플러그인에서 등록합니다.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  css: ['@krds.ui/vue/style']
})
```

```ts
// plugins/krds.ts (Nuxt 4 기본 구조에서는 app/plugins/krds.ts)
import KrdsVue from '@krds.ui/vue'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(KrdsVue)
})
```

Nuxt는 tsconfig를 자동 생성하므로, 전역 타입은 프로젝트의 `.d.ts` 파일에 참조를 추가합니다.

```ts
// types/krds.d.ts
/// <reference types="@krds.ui/vue/global" />
```

## 예제 프로젝트

이 문서의 설정(플러그인 등록, 스타일, 전역 타입)을 담은 Vite + Vue 3 + TypeScript 예제가 저장소의 [`examples/vite`](https://github.com/Initializer-org/krds-vue/tree/main/examples/vite)에 있습니다. [StackBlitz에서 바로 열어](https://stackblitz.com/github/Initializer-org/krds-vue/tree/main/examples/vite) 볼 수도 있습니다.

## TypeScript

컴포넌트 props와 공통 타입을 패키지 루트에서 가져올 수 있습니다.

```ts
import type { KrdsButtonProps, Size } from '@krds.ui/vue'

const size: Size = 'medium'

const buttonProps: KrdsButtonProps = {
  variant: 'primary',
  size,
  disabled: false
}
```

## 스타일과 테마

KRDS Vue 스타일은 CSS custom properties를 기반으로 합니다. 토큰 값을 조정해야 한다면 원본 CSS를 수정하지 말고 애플리케이션 CSS에서 필요한 변수만 재선언합니다.

```css
:root {
  --krds-color-light-primary-50: #256ef4;
}
```

컬러 모드는 루트 요소의 `data-krds-mode` 속성으로 전환합니다. 이 문서 사이트 상단의 화면 모드 버튼도 같은 방식으로 고대비 모드를 켭니다.

```ts
document.documentElement.setAttribute('data-krds-mode', 'high-contrast')
```

- `light`: 기본 라이트 모드 (KRDS 공식 사이트의 "기본 (밝은 배경)")
- `high-contrast`: 고대비 모드 (KRDS 공식 사이트의 "선명하게 (어두운 배경)")
- `theme`: 사용자 시스템 설정에 따라 라이트/고대비 스타일 적용 (KRDS 공식 사이트의 "시스템 설정")

## 브라우저 지원

| 브라우저          | 지원 버전 |
| ----------------- | --------- |
| Chrome, Edge      | 111 이상  |
| Firefox           | 114 이상  |
| Safari (iOS 포함) | 16.4 이상 |

산출물에 폴리필은 포함하지 않습니다. Internet Explorer는 지원하지 않습니다.

---

# 공식 배너 Masthead

공식 배너는 사용자가 대한민국 정부 조직 및 관련 기관에서 운영 및 관리하는 디지털 정부서비스임을 식별할 수 있도록 제공하는 정보 배너이다.

## 기본

```vue
<script setup lang="ts">
  import { KrdsMasthead } from '@krds.ui/vue'
</script>

<template>
  <KrdsMasthead>이 누리집은 대한민국 공식 전자정부 누리집입니다.</KrdsMasthead>
</template>
```

## API

## KrdsMasthead

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 공식 배너를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 공식 배너 문구 |

---

# 운영기관 식별자 Identifier

운영기관 식별자는 디지털 정부서비스에 대한 신뢰성을 위해 서비스 운영 및 관리 주체를 안내하는 요소로 공식 배너, 푸터와 함께 서비스의 일관성, 브랜드를 확인할 수 있는 핵심 요소이다.

## 기본

```vue
<script setup lang="ts">
  import { KrdsIdentifier } from '@krds.ui/vue'
</script>

<template>
  <KrdsIdentifier>이 누리집은 보건복지부 누리집입니다.</KrdsIdentifier>
</template>
```

## API

## KrdsIdentifier

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| logoLabel | string | 'KRDS - Korea Design System' | 로고 스크린리더 텍스트 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 운영기관 식별자를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 운영기관 안내 문구 |

---

# 헤더 Header

헤더는 웹사이트의 상단 헤더 영역을 구성하는 컴포넌트이다.
유틸리티 메뉴, 브랜딩 영역, 네비게이션 메뉴를 슬롯을 통해 유연하게 구성할 수 있다.
네비게이션 슬롯에는 KrdsMainMenu 등 완성된 메뉴 컴포넌트를 그대로 전달한다.

## 기본

`utility`, `branding` 슬롯에는 KRDS 헤더 마크업을, `navigation` 슬롯에는 `KrdsMainMenu`를, `mobileNavigation` 슬롯에는 `KrdsMainMenu`(`variant="mobile"`)를 전달합니다.

헤더는 화면 상단에 고정(sticky)되고 메인 메뉴를 열면 화면 전체에 배경 딤이 깔리므로 예제를 별도 화면(iframe)에 띄웁니다. 예제는 1024px 폭 화면을 축소해 PC 레이아웃으로 보여 줍니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsHeader, KrdsMainMenu, type MainMenuItem } from '@krds.ui/vue'

  const menuItems: MainMenuItem[] = [
    {
      text: '1Depth',
      subItems: [
        {
          text: '2Depth-menu',
          items: [
            { text: '3Depth-menu', href: '#' },
            { text: '3Depth-menu', href: '#' }
          ]
        },
        {
          text: '2Depth-menu',
          items: [
            { text: '3Depth-menu', href: '#' },
            { text: '3Depth-menu', href: '#' }
          ]
        }
      ]
    },
    {
      text: '1Depth',
      subItems: [
        {
          text: '2Depth-menu',
          items: [
            { text: '3Depth-menu', href: '#' },
            { text: '3Depth-menu', href: '#' }
          ]
        }
      ]
    },
    { text: '링크(anchor)', href: '#' }
  ]

  const mobileOpen = ref(false)
</script>

<template>
  <KrdsHeader>
    <template #utility>
      <ul class="utility-list">
        <li>
          <a href="#" class="krds-btn small text" target="_blank" title="새 창 열기"> 메뉴명 <i class="svg-icon ico-go"></i> </a>
        </li>
        <li>
          <div class="krds-drop-wrap">
            <button type="button" class="krds-btn small text drop-btn">메뉴명 <i class="svg-icon ico-toggle"></i></button>
            <div class="drop-menu">
              <div class="drop-in">
                <ul class="drop-list">
                  <li><a href="#" class="item-link">메뉴명</a></li>
                  <li><a href="#" class="item-link">메뉴명</a></li>
                </ul>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </template>

    <template #branding>
      <h2 class="logo">
        <a href="#">
          <span class="sr-only">KRDS - Korea Design System</span>
        </a>
      </h2>
      <div class="header-actions">
        <button type="button" class="btn-navi sch" title="통합검색 레이어">통합검색</button>
        <a href="#" class="btn-navi login">로그인</a>
        <button type="button" class="btn-navi join">회원가입</button>
        <button type="button" class="btn-navi all" aria-controls="mobile-nav" :aria-expanded="mobileOpen" @click="mobileOpen = true">
          전체메뉴
        </button>
      </div>
    </template>

    <template #navigation>
      <KrdsMainMenu :items="menuItems" />
    </template>

    <template #mobileNavigation>
      <KrdsMainMenu v-model:open="mobileOpen" variant="mobile" :items="menuItems" />
    </template>
  </KrdsHeader>
</template>
```

## 모바일

1024px 미만 화면에서는 유틸리티 메뉴와 PC 메인 메뉴가 숨겨지고 전체메뉴 버튼이 표시됩니다. 전체메뉴 버튼의 `aria-controls`를 모바일 드로어 id(`KrdsMainMenu`의 `mobileId`, 기본값 `mobile-nav`)에 연결하고 `v-model:open`으로 드로어를 엽니다. 아래는 같은 예제를 문서 폭(1024px 미만) 그대로 띄운 것으로, 전체메뉴 버튼으로 드로어를 확인할 수 있습니다.

## API

## KrdsHeader

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | 추가 CSS 클래스 |
| id | string | 'krds-header' | 헤더 ID |

### Slots

| 이름 | 설명 |
| --- | --- |
| utility | 유틸리티 메뉴 슬롯 |
| branding | 브랜딩 영역 슬롯 (로고, 액션 버튼) |
| navigation | 데스크탑 네비게이션 슬롯 — KrdsMainMenu 등 완성된 메뉴 요소를 그대로 전달 |
| mobileNavigation | 모바일 네비게이션 슬롯 — KrdsMainMenu(variant="mobile") 등 완성된 드로어 요소를 그대로 전달 |

## KrdsMainMenu

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| items | MainMenuItem[] | [] | 메뉴 아이템 배열 |
| variant | MainMenuVariant ('pc' \| 'mobile') | 'pc' | 렌더링 방식 |
| ariaLabel | string | '메인 메뉴' | 메뉴 영역 레이블 |
| open | boolean | false | 모바일 드로어 열림 상태 (v-model:open) |
| mobileId | string | 'mobile-nav' | 모바일 드로어 요소 id (외부 트리거의 `aria-controls` 대상) |
| backdrop | boolean | true | PC 메가 패널 배경 딤(backdrop) 사용 여부 |
| closeLabel | string | '전체메뉴 닫기' | 모바일 드로어 닫기 버튼 레이블 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:open | [value: boolean] | 모바일 메뉴가 열리거나 닫힐 때 (v-model:open) |
| menu-toggle | [index: number, expanded: boolean] | 1차 메뉴를 펼치거나 접을 때 (순서, 펼침 여부) |
| item-click | [item: MainMenuAnyItem, mouseEvent: MouseEvent] | 메뉴 항목을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| banner | PC 서브 패널 배너 영역 |
| header | 모바일 드로어 헤더 영역 (유틸리티, 로그인, 검색 등) |
| bottom | 모바일 드로어 하단 영역 |

---

# 푸터 Footer

푸터는 화면을 구성하는 가장 마지막 요소로 헤더와 본문에서 원하는 정보를 찾지 못하였거나 사이트 구조 탐색 중에 길을 잃은 사용자들이 대면하게 되는 정보이다. 따라서 푸터에는 사용자가 서비스를 탐색할 수 있는 추가적인 수단, 문제를 해결하는 데 참고할 수 있는 유용한 링크가 제공되어야 한다.

## 기본

`top`, `logo`, `content`, `bottom` 슬롯에 KRDS 푸터 마크업을 그대로 전달합니다. 하단에는 운영기관 식별자(`KrdsIdentifier`)를 함께 둡니다.

푸터 레이아웃은 화면 폭 기준으로 바뀌므로 예제를 별도 화면(iframe)에 띄웁니다. 예제는 1024px 폭 화면을 축소해 PC 레이아웃으로 보여 줍니다. 768px 미만 화면에서는 모바일 레이아웃으로 바뀝니다.

```vue
<script setup lang="ts">
  import { KrdsButton, KrdsFooter, KrdsIdentifier } from '@krds.ui/vue'
</script>

<template>
  <KrdsFooter>
    <template #top>
      <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
      <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
      <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
      <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
    </template>

    <template #logo>
      <span class="sr-only">KRDS - Korea Design System</span>
    </template>

    <template #content>
      <div class="f-info">
        <p class="info-addr">(26464) 강원특별자치도 원주시 건강로 32(반곡동) 국민건강보험공단</p>
        <ul class="info-cs">
          <li><strong class="strong">대표전화 1577-1000</strong><span class="span">(유료, 평일 09시~18시)</span></li>
          <li><strong class="strong">해외이용 82-33-811-2001</strong><span class="span">(유료, 평일 09시~18시)</span></li>
        </ul>
      </div>

      <div class="f-link">
        <div class="link-go">
          <KrdsButton text size="medium">찾아오시는 길 <i class="svg-icon ico-angle right"></i></KrdsButton>
          <KrdsButton text size="medium">이용안내 <i class="svg-icon ico-angle right"></i></KrdsButton>
          <KrdsButton text size="medium">직원검색 <i class="svg-icon ico-angle right"></i></KrdsButton>
        </div>
        <div class="link-sns">
          <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
            <span class="sr-only">인스타그램</span>
            <i class="svg-icon ico-instagram"></i>
          </a>
          <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
            <span class="sr-only">유튜브</span>
            <i class="svg-icon ico-youtube"></i>
          </a>
          <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
            <span class="sr-only">X</span>
            <i class="svg-icon ico-sns-x"></i>
          </a>
          <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
            <span class="sr-only">페이스북</span>
            <i class="svg-icon ico-facebook"></i>
          </a>
          <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
            <span class="sr-only">블로그</span>
            <i class="svg-icon ico-blog"></i>
          </a>
        </div>
      </div>
    </template>

    <template #bottom>
      <div class="f-btm-text">
        <div class="f-menu">
          <a href="#" class="point">개인정보처리방침</a>
          <a href="#">저작권 정책</a>
          <a href="#">웹 접근성 품질인증 마크 획득</a>
        </div>
        <p class="f-copy">© 2023 National Health Insurance Service. All rights reserved.</p>
      </div>
      <KrdsIdentifier>이 누리집은 보건복지부 누리집입니다.</KrdsIdentifier>
    </template>
  </KrdsFooter>
</template>
```

## API

## KrdsFooter

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| id | string | 'krds-footer' | Footer ID |

### Slots

| 이름 | 설명 |
| --- | --- |
| top | 푸터 위 빠른 링크 영역 |
| logo | 로고 |
| content | 기관 정보와 링크 |
| bottom | 하단 메뉴·저작권·운영기관 식별자 |

## KrdsIdentifier

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| logoLabel | string | 'KRDS - Korea Design System' | 로고 스크린리더 텍스트 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 운영기관 식별자를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 운영기관 안내 문구 |

---

# 건너뛰기 링크 Skip link

건너뛰기 링크는 웹사이트에서 웹 페이지의 주요 콘텐츠 섹션의 탐색을 도와주는 페이지 내부 링크이다. 키보드나 가상 초점을 이용하여 콘텐츠를 탐색하는 사용자는 건너뛰기 링크를 이용하여 대부분의 페이지에서 반복되는 콘텐츠 영역을 건너뛰고 주요 콘텐츠로 빠르게 이동할 수 있다.

## 기본

페이지 최상단에 배치합니다. 링크는 포커스를 받기 전까지 화면에서 숨겨져 있다가, 포커스를 받으면 화면 맨 위에 고정되어 표시되므로 예제를 별도 화면(iframe)에 띄웁니다. 미리보기 안으로 Tab 키를 눌러 포커스를 옮겨 확인하세요.

```vue
<script setup lang="ts">
  import { KrdsSkipLink } from '@krds.ui/vue'
</script>

<template>
  <div>
    <KrdsSkipLink href="#main-content">본문 바로가기</KrdsSkipLink>
    <div id="main-content" style="margin-top: 100px; padding: 20px; background: #f5f5f5">
      <h2>주요 콘텐츠 영역</h2>
      <p>이곳이 건너뛰기 링크의 대상이 되는 주요 콘텐츠 영역입니다.</p>
    </div>
  </div>
</template>
```

## 여러 링크

`links`로 여러 링크를 하나의 래퍼(`#krds-skip-link`) 안에 렌더링합니다. 컴포넌트를 여러 개 나란히 두면 `id`가 중복되므로 `links`를 사용합니다.

```vue
<script setup lang="ts">
  import { KrdsSkipLink } from '@krds.ui/vue'

  const links = [
    { href: '#main-content', label: '본문 바로가기' },
    { href: '#gnb', label: '메인메뉴 바로가기' }
  ]
</script>

<template>
  <div>
    <KrdsSkipLink :links="links" />
    <nav id="gnb" aria-label="메인메뉴" style="padding: 20px; border: 1px dashed #ccc">메인메뉴 영역</nav>
    <div id="main-content" style="margin-top: 20px; padding: 20px; background: #f5f5f5">
      <h2>주요 콘텐츠 영역</h2>
    </div>
  </div>
</template>
```

## API

## KrdsSkipLink

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | 추가 CSS 클래스 |
| id | string | 'krds-skip-link' | 요소 ID |
| href | string | - | 건너뛸 대상 요소의 ID |
| links | { href: string; label: string; }[] | - | 여러 건너뛰기 링크 (하나의 래퍼 안에 렌더링, 지정 시 href·기본 슬롯 대신 사용) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 링크 문구 (links를 쓰지 않을 때) |

---

# 메인 메뉴 Main menu

메인 메뉴는 서비스 전체의 구조를 보여주고 주요 화면으로 이동할 수 있게 하는 메뉴이다. 일반적으로 헤더 영역에 위치하며, 데스크탑에서는 메가 메뉴 형태로, 모바일에서는 드로어 형태로 제공된다.

`variant` 속성으로 두 형태를 전환합니다. PC 메가 메뉴는 원본 KRDS처럼 패널을 열면 페이지 전체에 배경 딤(`backdrop`)을 깝니다. 메뉴가 딤 위에 보이려면 헤더(`#krds-header`, `KrdsHeader`) 안에 두어야 하며, 헤더 밖에서 쓰면 `:backdrop="false"`로 끕니다.

## PC 메가 메뉴

PC 메가 메뉴는 1024px 이상 화면에서만 표시됩니다. 미리보기는 헤더 밖에 두므로 `:backdrop="false"`로 배경 딤을 끄고, PC 레이아웃 그대로 보이도록 1024px 폭으로 표시합니다(가로 스크롤). 헤더 안에서 쓰는 예는 [헤더](./header)를 참고하세요.

```vue
<script setup lang="ts">
  import { KrdsMainMenu, type MainMenuItem } from '@krds.ui/vue'

  const items: MainMenuItem[] = [
    {
      text: '정보서비스',
      subItems: [
        {
          text: '민원신청',
          title: '민원신청',
          titleLink: { href: '#', text: '바로가기' },
          layout: 'between',
          banner: true,
          items: [
            { text: '증명서 발급', href: '#' },
            { text: '전입신고', href: '#' },
            { text: '여권 재발급', href: '#' },
            { text: '주민등록 등본', href: '#', selected: true }
          ]
        },
        {
          text: '생활지원',
          title: '생활지원',
          items: [
            { text: '주거 지원', href: '#' },
            { text: '교육 지원', href: '#' },
            { text: '의료 지원', href: '#' }
          ]
        },
        {
          text: '고용정보',
          title: '고용정보',
          items: [
            {
              text: '채용 공고',
              href: '#',
              description: '메뉴명과 메뉴에 관한 간략한 설명이 표시되는 스타일입니다.',
              external: true
            },
            {
              text: '직업 훈련',
              href: '#',
              description: '메뉴명과 메뉴에 관한 간략한 설명이 표시되는 스타일입니다.',
              selected: true
            }
          ]
        },
        { text: '통합검색 바로가기', href: '#' },
        { text: '외부 서비스', href: 'https://www.krds.go.kr', external: true }
      ]
    },
    {
      text: '정책정보',
      subItems: [
        {
          text: '정책자료',
          title: '정책자료',
          layout: 'between',
          items: [
            { text: '보도자료', href: '#' },
            { text: '입법예고', href: '#' },
            { text: '연구보고서', href: '#' }
          ]
        },
        {
          text: '통계정보',
          title: '통계정보',
          items: [
            { text: '국가통계', href: '#' },
            { text: '지역통계', href: '#' }
          ]
        }
      ]
    },
    {
      text: '알림소식',
      title: '알림소식',
      layout: 'between',
      items: [
        { text: '공지사항', href: '#' },
        { text: '보도자료', href: '#' },
        { text: '행사안내', href: '#' },
        { text: '채용정보', href: '#' },
        { text: '입찰공고', href: '#' },
        { text: '고시공고', href: '#' }
      ]
    },
    { text: '기관소개', href: '#' }
  ]
</script>

<template>
  <KrdsMainMenu :items="items" :backdrop="false">
    <template #banner>
      <span class="krds-badge bg-secondary">신규 서비스</span>
      <button type="button" class="krds-btn medium text">메뉴명 <i class="svg-icon ico-angle right"></i></button>
    </template>
  </KrdsMainMenu>
</template>
```

## PC 2depth 없는 메뉴

2depth 목록 없이 마지막 뎁스 링크만 나열하는 경우 `single-list` 레이아웃으로 렌더링됩니다. `items`만 지정하면 됩니다.

```vue
<script setup lang="ts">
  import { KrdsMainMenu, type MainMenuItem } from '@krds.ui/vue'

  const items: MainMenuItem[] = [
    {
      text: '알림소식',
      title: '알림소식',
      layout: 'between',
      items: [
        { text: '공지사항', href: '#' },
        { text: '보도자료', href: '#' },
        { text: '행사안내', href: '#' },
        { text: '채용정보', href: '#' },
        { text: '입찰공고', href: '#' },
        { text: '고시공고', href: '#' }
      ]
    },
    { text: '기관소개', href: '#' }
  ]
</script>

<template>
  <KrdsMainMenu :items="items" :backdrop="false" aria-label="주요 메뉴" />
</template>
```

## 모바일 드로어 메뉴

모바일 드로어는 `v-model:open`으로 제어합니다. 외부 트리거 버튼에 `aria-controls`로 `mobileId`를 연결하고 `aria-expanded`를 함께 관리합니다. 2depth의 `items`는 3depth로, 3depth의 `items`는 전체 화면 4depth 패널로 렌더링됩니다.

드로어는 화면 전체를 덮는 고정 위치 요소이고 1024px 이상 화면에서는 표시되지 않으므로, 예제를 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsMainMenu, type MainMenuItem } from '@krds.ui/vue'

  const items: MainMenuItem[] = [
    {
      text: '정보서비스',
      subItems: [
        { text: '민원신청', href: '#' },
        { text: '생활지원', href: '#', selected: true },
        {
          text: '고용정보',
          items: [
            { text: '채용 공고', href: '#' },
            {
              text: '직업 훈련',
              href: '#',
              panelTitle: '직업 훈련',
              items: [
                { text: '국비 지원 과정', href: '#' },
                { text: '재직자 과정', href: '#' },
                { text: '온라인 과정', href: '#' }
              ]
            },
            { text: '고용 통계', href: '#' }
          ]
        }
      ]
    },
    {
      text: '정책정보',
      subItems: [
        { text: '정책자료', href: '#' },
        { text: '통계정보', href: '#' }
      ]
    },
    {
      text: '알림소식',
      subItems: [
        { text: '공지사항', href: '#' },
        { text: '보도자료', href: '#' }
      ]
    },
    {
      text: '기관소개',
      subItems: [
        { text: '인사말', href: '#' },
        { text: '조직도', href: '#' }
      ]
    }
  ]

  const isOpen = ref(false)
</script>

<template>
  <div>
    <button type="button" class="krds-btn medium primary" aria-controls="mobile-nav" :aria-expanded="isOpen" @click="isOpen = true">
      전체메뉴 열기
    </button>
    <KrdsMainMenu v-model:open="isOpen" variant="mobile" :items="items">
      <template #header>
        <div class="gnb-login">
          <button type="button" class="krds-btn large text">로그인을 해주세요</button>
        </div>
      </template>
      <template #bottom>
        <a href="#" class="krds-btn small text">개인정보처리방침</a>
      </template>
    </KrdsMainMenu>
  </div>
</template>
```

## API

## KrdsMainMenu

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| items | MainMenuItem[] | [] | 메뉴 아이템 배열 |
| variant | MainMenuVariant ('pc' \| 'mobile') | 'pc' | 렌더링 방식 |
| ariaLabel | string | '메인 메뉴' | 메뉴 영역 레이블 |
| open | boolean | false | 모바일 드로어 열림 상태 (v-model:open) |
| mobileId | string | 'mobile-nav' | 모바일 드로어 요소 id (외부 트리거의 `aria-controls` 대상) |
| backdrop | boolean | true | PC 메가 패널 배경 딤(backdrop) 사용 여부 |
| closeLabel | string | '전체메뉴 닫기' | 모바일 드로어 닫기 버튼 레이블 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:open | [value: boolean] | 모바일 메뉴가 열리거나 닫힐 때 (v-model:open) |
| menu-toggle | [index: number, expanded: boolean] | 1차 메뉴를 펼치거나 접을 때 (순서, 펼침 여부) |
| item-click | [item: MainMenuAnyItem, mouseEvent: MouseEvent] | 메뉴 항목을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| banner | PC 서브 패널 배너 영역 |
| header | 모바일 드로어 헤더 영역 (유틸리티, 로그인, 검색 등) |
| bottom | 모바일 드로어 하단 영역 |

---

# 브레드크럼 Breadcrumb

브레드크럼은 탐색 계층 구조를 표시하여 사용자가 현재 위치를 파악하고 계층 구조의 수준을 이동할 수 있게 해준다. 브레드크럼을 통해 사용자는 탐색 중인 화면의 상위 수준 화면으로 이동할 수 있다.

## 기본

`items`의 첫 항목은 홈 아이콘과 함께 표시되고(`showHomeIcon`), 마지막 항목은 현재 페이지(`aria-current="page"`)로 표시됩니다.

```vue
<script setup lang="ts">
  import { KrdsBreadcrumb, type BreadcrumbItem } from '@krds.ui/vue'

  const items: BreadcrumbItem[] = [
    { text: '홈', href: '#', onClick: e => e.preventDefault() },
    { text: '서비스 신청', href: '#', onClick: e => e.preventDefault() },
    { text: '서비스 신청2' }
  ]
</script>

<template>
  <KrdsBreadcrumb :items="items" />
</template>
```

## API

## KrdsBreadcrumb

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| id | string | - | 엘리먼트 ID |
| ariaLabel | string | '현재 경로' | 접근성 라벨 |
| showHomeIcon | boolean | true | 홈 아이콘 표시 여부 |
| items (필수) | BreadcrumbItem[] | - | 브레드크럼 아이템 배열 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| item-click | [item: BreadcrumbItem, event: MouseEvent] | 경로 항목을 클릭했을 때 |

---

# 사이드 메뉴 Side navigation

사이드 메뉴는 서브 화면 내에서의 이동을 위해 사용하는 메뉴이다. 일반적으로 본문 영역의 좌측에 사이드바 형태로 제공된다. 메인 메뉴보다 훨씬 좁고 깊은 페이지 구조 탐색에 사용되기 때문에 링크의 개수가 많고 복잡하게 표현되기 쉽다.

## 기본

`v-model`로 메뉴 아이템 배열을 전달합니다. 2Depth의 `subItems`는 펼침 목록으로, 3Depth의 `subItems`는 4Depth 팝업으로 렌더링되며 `expanded`로 초기 펼침 상태를 지정합니다.

4Depth 팝업을 열면 팝업 제목으로 초점이 옮겨 가고, 제목을 눌러 닫으면 팝업을 연 버튼으로 초점이 돌아옵니다. Tab으로 팝업을 벗어나거나 팝업 밖을 누르면 팝업이 닫히고, 초점은 옮겨 간 곳에 그대로 둡니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsSideNavigation, type SideNavItem } from '@krds.ui/vue'

  const menuItems = ref<SideNavItem[]>([
    {
      text: '2Depth-menu',
      expanded: true,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    },
    {
      text: '2Depth-menu',
      expanded: false,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    },
    {
      text: '2Depth-menu',
      expanded: false,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    }
  ])
</script>

<template>
  <KrdsSideNavigation v-model="menuItems" title="1Depth-title" />
</template>
```

## 2Depth 링크

`subItems`가 없는 2Depth 항목은 링크로 렌더링되고, `onClick`으로 클릭 동작을 지정할 수 있습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsSideNavigation, type SideNavItem } from '@krds.ui/vue'

  const menuItems = ref<SideNavItem[]>([
    { text: '2Depth-link', href: '#lnb-link' },
    { text: '2Depth-action', onClick: event => event.preventDefault() },
    {
      text: '2Depth-menu',
      expanded: false,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    }
  ])
</script>

<template>
  <KrdsSideNavigation v-model="menuItems" title="1Depth-title" aria-label="사이드 메뉴" />
</template>
```

## 여러 개 배치

한 페이지에 여러 개를 두어도 내부 id는 겹치지 않습니다. `aria-label`로 각 메뉴를 구분합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsSideNavigation, type SideNavItem } from '@krds.ui/vue'

  const createItems = (): SideNavItem[] => [
    {
      text: '2Depth-menu',
      expanded: true,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    },
    {
      text: '2Depth-menu',
      expanded: false,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    },
    {
      text: '2Depth-menu',
      expanded: false,
      subItems: [
        {
          text: '3Depth-menu',
          expanded: false,
          popupTitle: '3Depth-title',
          subItems: [
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' },
            { text: '4Depth', href: '#' }
          ]
        },
        { text: '3Depth-link', href: '#' },
        { text: '3Depth-link', href: '#' }
      ]
    }
  ]

  const first = ref(createItems())
  const second = ref(createItems())
</script>

<template>
  <div style="display: flex; gap: 2rem">
    <KrdsSideNavigation v-model="first" title="1Depth-title" aria-label="첫 번째 사이드 메뉴" style="flex: 1" />
    <KrdsSideNavigation v-model="second" title="1Depth-title" aria-label="두 번째 사이드 메뉴" style="flex: 1" />
  </div>
</template>
```

## API

## KrdsSideNavigation

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| modelValue | SideNavItem[] | [] | 메뉴 아이템 배열 |
| title (필수) | string | - | 네비게이션 제목 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: SideNavItem[]] | 메뉴를 펼치거나 접어 항목 상태가 바뀔 때 (v-model) |

---

# 콘텐츠 내 탐색 In-page navigation

콘텐츠 내 탐색은 사용자가 본문의 구조를 훑어보고 원하는 콘텐츠로 빠르게 이동할 수 있도록 하는 탐색 수단이다. 화면을 스크롤 할 때 특정 위치에 고정되어 콘텐츠의 목차 역할을 하는 동시에 사용자가 페이지 내 탐색에서 특정 항목을 클릭하면 연결된 섹션으로 스크롤 된다.

## 기본

화면에 고정되고 창 스크롤에 맞춰 현재 섹션을 표시하므로 예제를 별도 화면(iframe)에 띄웁니다. 768px 이상 화면에서는 본문 오른쪽에 고정되고 그보다 좁으면 본문 위에 표시됩니다. 이 예제는 800px 폭 화면을 축소해 보여 줍니다. KRDS 레이아웃(`#container.krds-in-page-navigation-type > .inner.in-between > .contents`) 안에 배치해야 합니다.

```vue
<script setup lang="ts">
  import { KrdsButton, KrdsInPageNavigation } from '@krds.ui/vue'

  const items = [
    { href: '#section_01', text: '서비스 개요' },
    { href: '#section_02', text: '서비스 상세' },
    { href: '#section_03', text: '신청 방법 및 절차' },
    { href: '#section_04', text: '제출 서류' },
    { href: '#section_05', text: '함께 신청할 수 있는 서비스' },
    { href: '#section_06', text: '부가정보' },
    { href: '#section_07', text: '정보 변경 내역' }
  ]
</script>

<template>
  <div id="wrap" class="g-wrap scroll-up">
    <div id="container" class="krds-in-page-navigation-type">
      <div class="inner in-between">
        <div class="contents">
          <KrdsInPageNavigation title="장애아동수당" caption="이 페이지의 구성" :items="items">
            <template #action>
              <KrdsButton size="medium">온라인 신청하기</KrdsButton>
              <p class="quick-info">장애아동수당 외 <strong>1건</strong></p>
            </template>
          </KrdsInPageNavigation>

          <div>
            <div id="section_01" style="min-height: 600px; background: #f8f9fa; padding: 2rem; margin-bottom: 2rem; border-radius: 8px">
              <h2>서비스 개요</h2>
              <p>장애아동수당은 장애로 인한 추가비용을 보전하여 장애아동 가정의 경제적 부담을 완화하고 생활안정을 지원하는 서비스입니다.</p>
              <ul>
                <li>지급대상: 만 18세 미만 등록 장애아동</li>
                <li>지급액: 중증 월 20만원, 경증 월 10만원</li>
                <li>지급방법: 매월 20일 계좌 입금</li>
              </ul>
            </div>

            <div id="section_02" style="min-height: 700px; background: #e9ecef; padding: 2rem; margin-bottom: 2rem; border-radius: 8px">
              <h2>서비스 상세</h2>
              <h3>지급 기준</h3>
              <p>장애아동수당은 장애 정도와 소득 수준에 따라 차등 지급됩니다.</p>
              <h4>중증 장애아동 (월 20만원)</h4>
              <ul>
                <li>장애의 정도가 심한 장애아동</li>
                <li>기초생활수급자, 차상위계층</li>
              </ul>
              <h4>경증 장애아동 (월 10만원)</h4>
              <ul>
                <li>장애의 정도가 심하지 않은 장애아동</li>
                <li>소득 기준을 충족하는 가구</li>
              </ul>
            </div>

            <div id="section_03" style="min-height: 650px; background: #dee2e6; padding: 2rem; margin-bottom: 2rem; border-radius: 8px">
              <h2>신청 방법 및 절차</h2>
              <h3>신청 방법</h3>
              <ol>
                <li>온라인 신청: 복지로 홈페이지 또는 모바일 앱</li>
                <li>방문 신청: 주민센터, 시·군·구청 사회복지과</li>
                <li>우편 신청: 신청서류를 우편으로 제출</li>
              </ol>
              <h3>처리 절차</h3>
              <ol>
                <li>신청서 접수 (1일)</li>
                <li>자격 조사 및 심사 (14일)</li>
                <li>결정 통지 (3일)</li>
                <li>급여 지급 (매월 20일)</li>
              </ol>
            </div>

            <div id="section_04" style="min-height: 500px; background: #ced4da; padding: 2rem; margin-bottom: 2rem; border-radius: 8px">
              <h2>제출 서류</h2>
              <h3>필수 서류</h3>
              <ul>
                <li>장애아동수당 신청서</li>
                <li>주민등록등본</li>
                <li>장애인등록증 사본</li>
                <li>통장 사본</li>
              </ul>
              <h3>소득 관련 서류</h3>
              <ul>
                <li>소득·재산 신고서</li>
                <li>급여명세서 또는 소득 증빙서류</li>
                <li>재산 관련 증빙서류</li>
              </ul>
            </div>

            <div id="section_05" style="min-height: 550px; background: #adb5bd; padding: 2rem; margin-bottom: 2rem; border-radius: 8px">
              <h2>함께 신청할 수 있는 서비스</h2>
              <h3>장애인 관련 급여</h3>
              <ul>
                <li>장애인연금</li>
                <li>장애수당</li>
                <li>장애인 의료비 지원</li>
              </ul>
              <h3>아동 관련 지원</h3>
              <ul>
                <li>아동수당</li>
                <li>한부모가족 지원</li>
                <li>보육료 지원</li>
              </ul>
              <p><strong>※ 동시 신청 시 처리 기간이 단축될 수 있습니다.</strong></p>
            </div>

            <div
              id="section_06"
              style="min-height: 450px; background: #6c757d; color: white; padding: 2rem; margin-bottom: 2rem; border-radius: 8px"
            >
              <h2>부가정보</h2>
              <h3>문의처</h3>
              <ul>
                <li>보건복지상담센터: 129</li>
                <li>온라인 문의: 복지로 홈페이지</li>
                <li>방문 상담: 거주지 주민센터</li>
              </ul>
              <h3>관련 법령</h3>
              <ul>
                <li>장애인복지법 제49조</li>
                <li>장애인복지법 시행령 제20조</li>
                <li>장애아동수당 지급 조례</li>
              </ul>
            </div>

            <div
              id="section_07"
              style="min-height: 400px; background: #495057; color: white; padding: 2rem; margin-bottom: 2rem; border-radius: 8px"
            >
              <h2>정보 변경 내역</h2>
              <h3>최근 변경사항</h3>
              <ul>
                <li>2024.01.01: 지급액 인상 (중증 20만원, 경증 10만원)</li>
                <li>2023.07.01: 온라인 신청 시스템 개편</li>
                <li>2023.01.01: 소득 기준 완화</li>
              </ul>
              <h3>예정 변경사항</h3>
              <ul>
                <li>2024.07.01: 모바일 앱 신청 기능 추가 예정</li>
                <li>2024.12.01: 지급 주기 단축 검토 중</li>
              </ul>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
```

## API

## KrdsInPageNavigation

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| caption | string | '이 페이지의 구성' | 네비게이션 캡션 |
| title | string | - | 네비게이션 제목 |
| items | NavigationItem[] | [] | 네비게이션 아이템 목록 |
| autoActive | boolean | true | 스크롤에 따른 자동 활성화 여부 |
| headerTopSelector | string | '#krds-masthead' | 헤더 상단 영역 선택자 (기본값: '#krds-masthead') |
| headerInnerSelector | string | '#krds-header .header-in' | 헤더 내부 영역 선택자 (기본값: '#krds-header .header-in') |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| itemClick | [item: NavigationItem, event: MouseEvent \| KeyboardEvent] | 탐색 항목을 클릭하거나 키보드로 선택했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| action | - |

---

# 페이지네이션 Pagination

페이지네이션은 많은 양의 콘텐츠를 탐색하기 쉽도록 여러 화면에 나누고, 분할된 화면을 탐색하는 데 사용되는 요소이다.

## 기본

`v-model`로 현재 페이지를, `max`로 전체 페이지 수를 지정합니다. `aria-label`(기본 '페이지 내비게이션')로 이름 붙인 내비게이션 영역(`nav`)이라, 한 페이지에 내비게이션이 여럿이어도 화면낭독기가 구분합니다. 페이지가 `pageRange`보다 많으면 첫 페이지와 마지막 페이지 사이를 생략 표시로 줄입니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsPagination } from '@krds.ui/vue'

  const currentPage = ref(4)
</script>

<template>
  <KrdsPagination v-model="currentPage" :max="99" :page-range="8" />
</template>
```

## API

## KrdsPagination

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| id | string | - | 엘리먼트 ID |
| ariaLabel | string | '페이지 내비게이션' | 내비게이션 영역 이름 (nav의 aria-label) |
| modelValue | number | 1 | 현재 페이지 번호 (v-model) |
| min | number | DEFAULT_MIN | 최소 페이지 번호 (기본값: 1, 최소값: 1) |
| pageRange | number | DEFAULT_PAGE_RANGE | 표시할 페이지 범위 |
| max (필수) | number | - | 최대 페이지 번호 (전체 페이지 수) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: number] | 페이지를 바꿀 때 (페이지 번호, v-model) |

---

# 구조화 목록 Structured list

구조화 목록은 유사하거나 관련된 콘텐츠 집합을 표현하기 위한 형식으로 목록에 제공된 데이터에 대한 상세 정보 탐색 수단 또는 관련 기능 실행 수단으로 활용된다. 사용자가 콘텐츠를 효율적으로 탐색하고 다음 행동을 빠르게 결정할 수 있도록 목록 내 정보는 상세 페이지에서 제공되는 복잡한 콘텐츠 중 핵심적이거나 흥미를 끌 수 있는 정보를 논리적 흐름에 따라 조직화하여 명확한 위계 구조를 반영해 제공해야 한다.

## 기본

`cardTop`, `cardBody`, `cardBtm`, `cardBtn` 슬롯으로 카드의 각 영역을 채웁니다. 내용을 넣은 슬롯의 영역만 렌더됩니다.

```vue
<script setup lang="ts">
  import { KrdsBadge, KrdsButton, KrdsIcon, KrdsStructuredList } from '@krds.ui/vue'
</script>

<template>
  <KrdsStructuredList>
    <template #cardTop>
      <KrdsBadge type="bg-light" color="primary">뱃지</KrdsBadge>
    </template>
    <template #cardBody>
      <a href="#" class="c-text">
        <p class="c-tit"><span class="span">타이틀 영역</span></p>
        <p class="c-txt">
          간단한 설명이 들어가는 영역입니다. 최대 3줄까지 작성합니다. 간단한 설명이 들어가는 영역입니다. 간단한 설명이 들어가는 영역입니다.
        </p>
        <p class="c-date">
          <strong class="key">신청 기간</strong>
          <span class="value">2023.00.00-2024.00.00</span>
        </p>
      </a>
      <div class="c-btn">
        <KrdsButton variant="secondary" size="medium">신청하기</KrdsButton>
      </div>
    </template>
    <template #cardBtm>
      <span class="tag">태그</span>
      <span class="tag">태그</span>
    </template>
    <template #cardBtn>
      <KrdsButton variant="tertiary" size="medium" class="text"> <KrdsIcon name="ico-share" /> 공유하기 </KrdsButton>
      <KrdsButton variant="tertiary" size="medium" class="text"> <KrdsIcon name="ico-like" /> 찜하기 </KrdsButton>
    </template>
  </KrdsStructuredList>
</template>
```

## 뱃지만 있는 구조

```vue
<script setup lang="ts">
  import { KrdsBadge, KrdsStructuredList } from '@krds.ui/vue'
</script>

<template>
  <KrdsStructuredList>
    <template #cardTop>
      <KrdsBadge type="bg-light" color="success">성공</KrdsBadge>
    </template>
    <template #cardBody>
      <div class="c-text">
        <p class="c-tit"><span class="span">간단한 제목</span></p>
      </div>
    </template>
  </KrdsStructuredList>
</template>
```

## 표형

같은 목록을 표로 보여 주는 형태입니다(원본 KRDS v1.1.0). 목록 위 도구 막대(`.search-list-top`)에 전체선택·일괄 작업 버튼과 목록 표시 개수·정렬 기준을 두고, 아래에 표와 페이지네이션을 둡니다. 정렬 기준은 PC에서 버튼, 모바일에서 셀렉트로 바뀝니다. 표는 `KrdsTable`의 [셀 슬롯](/components/table#셀-슬롯)으로 행마다 체크박스와 다운로드 버튼을 넣고, 도구 막대의 체크박스·버튼·셀렉트와 페이지네이션도 컴포넌트로 조합합니다. 전체선택은 지금 페이지의 행 기준입니다.

넓은 화면을 전제로 한 형태라 예제를 1200px 폭의 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { computed, ref, watch } from 'vue'
  import { KrdsButton, KrdsCheckArea, KrdsCheckbox, KrdsPagination, KrdsSelect, KrdsTable } from '@krds.ui/vue'

  const items = [
    {
      id: 1,
      type: '공지',
      title: '2026년 하반기 민원 서비스 개편 안내',
      summary: '민원 신청 화면이 새 디자인 시스템으로 바뀝니다.',
      date: '2026.10.02',
      views: 812
    },
    {
      id: 2,
      type: '보도자료',
      title: '디지털 정부 서비스 만족도 조사 결과',
      summary: '전년 대비 만족도가 4.2점 올랐습니다.',
      date: '2026.09.28',
      views: 1540
    },
    {
      id: 3,
      type: '고시',
      title: '전자문서 보존 기간 기준 개정 고시',
      summary: '보존 기간 산정 기준이 일부 바뀝니다.',
      date: '2026.09.15',
      views: 402
    },
    {
      id: 4,
      type: '공지',
      title: '추석 연휴 고객센터 운영 시간 안내',
      summary: '연휴 기간 전화 상담은 오전에만 운영합니다.',
      date: '2026.09.10',
      views: 2210
    },
    {
      id: 5,
      type: '보도자료',
      title: '공공 누리집 접근성 점검 결과 발표',
      summary: '점검 대상 누리집의 91%가 기준을 충족했습니다.',
      date: '2026.08.30',
      views: 967
    },
    {
      id: 6,
      type: '공지',
      title: '본인 인증 수단 추가 안내',
      summary: '간편 인증으로 민원을 신청할 수 있습니다.',
      date: '2026.08.21',
      views: 1325
    },
    {
      id: 7,
      type: '고시',
      title: '행정정보 공동이용 대상 정보 고시',
      summary: '공동이용 대상 정보 3종이 추가됩니다.',
      date: '2026.08.12',
      views: 288
    }
  ]

  const columns = [
    { name: 'select', label: '선택', headerStyle: 'width: 6%' },
    { name: 'type', label: '유형', field: 'type', headerStyle: 'width: 10%' },
    { name: 'title', label: '제목', field: 'title', headerStyle: 'width: 28%' },
    { name: 'summary', label: '내용', field: 'summary' },
    { name: 'download', label: '다운로드', headerStyle: 'width: 12%' },
    { name: 'date', label: '게시일', field: 'date', headerStyle: 'width: 12%' }
  ]
  const sortOptions = [
    { value: 'relevance', label: '관련도순' },
    { value: 'latest', label: '최신순' },
    { value: 'popular', label: '인기순' }
  ]
  const sizeOptions = [
    { value: 5, label: '5개' },
    { value: 10, label: '10개' }
  ]

  const sort = ref('relevance')
  const size = ref(5)
  const page = ref(1)
  const selected = ref<unknown[]>([])

  const sorted = computed(() => {
    if (sort.value === 'latest') return [...items].sort((a, b) => b.date.localeCompare(a.date))
    if (sort.value === 'popular') return [...items].sort((a, b) => b.views - a.views)
    return items
  })
  const maxPage = computed(() => Math.ceil(items.length / size.value))
  const rows = computed(() => sorted.value.slice((page.value - 1) * size.value, page.value * size.value))
  // 정렬·표시 개수를 바꾸면 첫 페이지로
  watch([sort, size], () => (page.value = 1))

  // 전체선택은 지금 페이지의 행 기준
  const allChecked = computed(() => rows.value.every(row => selected.value.includes(row.id)))
  const toggleAll = (checked: boolean) => {
    const ids: unknown[] = rows.value.map(row => row.id)
    selected.value = checked ? [...new Set([...selected.value, ...ids])] : selected.value.filter(id => !ids.includes(id))
  }
  const toggleRow = (id: unknown, checked: boolean) => {
    selected.value = checked ? [...selected.value, id] : selected.value.filter(item => item !== id)
  }
</script>

<template>
  <div class="krds-structured-list-table">
    <div class="search-list-top">
      <div class="sch-left">
        <KrdsCheckArea>
          <KrdsCheckbox id="list-chk-all" :model-value="allChecked" @update:model-value="toggleAll">전체선택</KrdsCheckbox>
        </KrdsCheckArea>
        <ul class="side-line-ul">
          <li>
            <KrdsButton text size="medium" :disabled="!selected.length"><i class="svg-icon ico-down"></i> 선택 다운로드</KrdsButton>
          </li>
          <li>
            <KrdsButton text size="medium"><i class="svg-icon ico-down"></i> 전체 다운로드</KrdsButton>
          </li>
        </ul>
      </div>
      <ul class="sch-sort">
        <li>
          <strong class="sort-label"><label for="list-size">목록 표시 개수</label></strong>
          <KrdsSelect id="list-size" v-model="size" sort :options="sizeOptions" />
        </li>
        <li>
          <strong class="sort-label"><label for="list-sort">정렬기준</label></strong>
          <!-- PC는 버튼, 모바일은 셀렉트로 정렬 기준을 고른다 -->
          <div class="w-sort-btn" role="group" aria-label="정렬기준">
            <button
              v-for="option in sortOptions"
              :key="option.value"
              type="button"
              :class="{ active: sort === option.value }"
              :aria-pressed="sort === option.value"
              @click="sort = option.value"
            >
              {{ option.label }}
            </button>
          </div>
          <div class="m-sort-btn">
            <KrdsSelect id="list-sort" v-model="sort" sort :options="sortOptions" />
          </div>
        </li>
      </ul>
    </div>

    <KrdsTable caption="게시물 목록: 선택, 유형, 제목, 내용, 다운로드, 게시일로 구성" class="col data" :columns="columns" :rows="rows">
      <template #cell-select="{ row }">
        <KrdsCheckbox
          :id="`list-chk-${row.id}`"
          :model-value="selected.includes(row.id)"
          @update:model-value="checked => toggleRow(row.id, checked)"
        >
          <span class="sr-only">{{ row.title }} 선택</span>
        </KrdsCheckbox>
      </template>
      <template #header-download><span class="sr-only">다운로드</span></template>
      <template #cell-download="{ row }">
        <KrdsButton text size="medium"
          ><i class="svg-icon ico-down"></i> 다운로드<span class="sr-only">: {{ row.title }}</span></KrdsButton
        >
      </template>
    </KrdsTable>

    <KrdsPagination v-model="page" :max="maxPage" aria-label="게시물 목록 페이지" />
  </div>
</template>
```

## API

## KrdsStructuredList

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| full | boolean | true | 전체 타입 여부 |

### Slots

| 이름 | 설명 |
| --- | --- |
| cardTop | - |
| cardBody | - |
| cardBtm | - |
| cardBtn | - |

---

# 긴급 공지 Critical alerts

긴급 공지는 본문 상단에 강조되어 표시되는 배너로 사용자에게 긴급하거나 중요한 정보를 전달하는 데 사용된다. 모든 공공 디지털 서비스에서 동일한 긴급 공지 컴포넌트를 사용함으로써 사용자는 긴급한 정보를 일관되고 예측 가능한 방식으로 찾고 이해할 수 있다.

## 기본

`link-href`를 지정하면 링크가 표시됩니다. 링크 텍스트(`link-text`)는 768px 미만 화면에서 숨겨지고 화살표 아이콘만 남습니다. 화면낭독기는 화면 폭과 관계없이 링크 텍스트를 링크 이름으로 읽습니다.

```vue
<script setup lang="ts">
  import { KrdsCriticalAlerts } from '@krds.ui/vue'
</script>

<template>
  <KrdsCriticalAlerts type="danger" message="긴급 공지 내용 표시" link-href="#" link-text="자세히 보기" />
</template>
```

## 타입

`type`에 따라 배지 문구가 `danger`는 긴급, `ok`는 안전, `info`는 안내로 표시됩니다.

```vue
<script setup lang="ts">
  import { KrdsCriticalAlerts } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 1rem">
    <KrdsCriticalAlerts type="danger" message="긴급 공지 내용 표시" link-href="#" />
    <KrdsCriticalAlerts type="ok" message="안전 공지 내용 표시" link-href="#" />
    <KrdsCriticalAlerts type="info" message="안내 공지 내용 표시" />
  </div>
</template>
```

## API

## KrdsCriticalAlerts

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| type | AlertType ('danger' \| 'ok' \| 'info') | 'info' | 알림 타입 |
| linkHref | string | - | 링크 URL |
| linkText | string | '자세히 보기' | 링크 텍스트 |
| message (필수) | string | - | 알림 메시지 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| link-click | [event: MouseEvent] | 공지 링크를 클릭했을 때 |

---

# 디스클로저 Disclosure

디스클로저는 특정한 정보/컨트롤/섹션에 관련된 부가적인 정보를 표시하거나 숨기는 데 사용되는 요소이다. 디스클로저 하위 콘텐츠 섹션은 기본으로 축소된 상태로 제공되며 사용자가 요청하는 경우에 확장되어 자세한 정보가 표시된다. 이는 사용자의 인지적 부담을 감소시키고 정보를 빠르게 훑어보는 데 도움이 된다.

## 기본

`v-model`로 펼침 상태를 제어합니다. 접혀 있는 동안 콘텐츠 영역은 `inert`로 포커스와 보조기기 대상에서 제외됩니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDisclosure } from '@krds.ui/vue'

  const expanded = ref(false)
</script>

<template>
  <KrdsDisclosure v-model="expanded" title="신청 서비스안내">
    <ul class="krds-info-list dash">
      <li>하나의 아이디로 안전하고 편리하게 여러 전자정부 서비스를 이용할 수 있는 서비스입니다.</li>
      <li>디지털원패스 이용문의 : 1533-3713 (평일9~18시, 공휴일제외)</li>
    </ul>
  </KrdsDisclosure>
</template>
```

## API

## KrdsDisclosure

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| modelValue | boolean | false | 확장 상태 (v-model) |
| title (필수) | string | - | 디스클로저 제목 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: boolean] | 펼침 상태가 바뀔 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 펼쳤을 때 보이는 내용 |

---

# 모달 Modal

모달은 대화창의 한 종류로 기본 창에 종속된 요소이다. 기본 창과 겹쳐져 가장 상단에 표시되며, 이때 기본 창은 비활성 상태로 전환되어 상호작용이 불가능하므로 사용자는 모달에서의 단일한 과업 또는 메시지에 집중할 수 있다.

## 기본

`v-model`로 열림 상태를 제어합니다. 열리면 모달 안으로 포커스가 이동하고 Tab 키 포커스가 모달 안에서 순환하며, Esc 키나 배경 클릭으로 닫으면 연 버튼으로 포커스가 돌아갑니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const isOpen = ref(false)
</script>

<template>
  <KrdsButton size="large" variant="secondary" @click="isOpen = true">모달 열기</KrdsButton>
  <KrdsModal v-model="isOpen" modal-id="modal_basic">
    <template #title>모달 제목</template>
    <p>대화 상자는 사용자에게 작업에 대해 알리고 중요한 정보를 포함하거나 결정이 필요하거나 여러 작업을 포함할 수 있습니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="tertiary" @click="isOpen = false">아니요</KrdsButton>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">예</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## 사이즈

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const size = ref<'small' | 'large'>('small')
  const isOpen = ref(false)

  const open = (value: 'small' | 'large') => {
    size.value = value
    isOpen.value = true
  }
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 1rem">
    <KrdsButton size="large" variant="secondary" @click="open('small')">Small 모달 열기</KrdsButton>
    <KrdsButton size="large" variant="secondary" @click="open('large')">Large 모달 열기</KrdsButton>
  </div>
  <KrdsModal v-model="isOpen" :size="size" modal-id="modal_sizes">
    <template #title>{{ size === 'small' ? 'Small' : 'Large' }} 모달</template>
    <p>{{ size === 'small' ? '작은' : '큰' }} 크기의 모달입니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">확인</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## 배경 없음

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const isOpen = ref(false)
</script>

<template>
  <KrdsButton size="large" variant="secondary" @click="isOpen = true">배경 없는 모달 열기</KrdsButton>
  <KrdsModal v-model="isOpen" :backdrop="false" modal-id="modal_no_backdrop">
    <template #title>배경 없는 모달</template>
    <p>배경 딤 처리 없이 모달만 표시됩니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">확인</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## 풀팝업

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const isOpen = ref(false)
</script>

<template>
  <KrdsButton size="large" variant="secondary" @click="isOpen = true">풀팝업 열기</KrdsButton>
  <KrdsModal v-model="isOpen" full modal-id="modal_full">
    <template #title>풀팝업</template>
    <p>전체 화면을 차지하는 풀팝업입니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">확인</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## 바텀시트

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const isOpen = ref(false)
</script>

<template>
  <KrdsButton size="large" variant="secondary" @click="isOpen = true">바텀시트 열기</KrdsButton>
  <KrdsModal v-model="isOpen" bottom-sheet modal-id="modal_bottom_sheet">
    <template #title>바텀시트</template>
    <p>하단에서 올라오는 바텀시트입니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">확인</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## Persistent

중요한 결정을 받아야 할 때 배경 클릭과 Esc 키로 닫히지 않게 합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsModal } from '@krds.ui/vue'

  const isOpen = ref(false)
</script>

<template>
  <KrdsButton size="large" variant="secondary" @click="isOpen = true">Persistent 모달 열기</KrdsButton>
  <KrdsModal v-model="isOpen" persistent modal-id="modal_persistent">
    <template #title>Persistent 모달</template>
    <p>배경을 클릭하거나 Esc 키를 눌러도 닫히지 않습니다. 버튼으로만 닫을 수 있습니다.</p>
    <template #footer>
      <KrdsButton size="medium" variant="primary" @click="isOpen = false">확인</KrdsButton>
    </template>
  </KrdsModal>
</template>
```

## API

## KrdsModal

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| backdrop | boolean | true | 배경 딤(backdrop) 표시 여부 |
| modelValue | boolean | false | 모달 표시 여부 (v-model) |
| full | boolean | false | 전체 화면 모달 여부 |
| modalId | string | - | 모달 엘리먼트 ID |
| size | KrdsModalSize ('small' \| 'medium' \| 'large') | 'medium' | 모달 크기 |
| bottomSheet | boolean | false | 하단 시트형 모달 여부 |
| persistent | boolean | false | 배경 클릭·Esc 키로 닫히지 않는 지속형 모달 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: boolean] | 모달이 열리거나 닫힐 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| title | - |
| default | - |
| footer | - |

---

# 배지 Badge

컴포넌트에 대한 빠른 인지와 탐색을 돕기 위해 컴포넌트 근처에 표시되는 작은 문자 또는 숫자 데이터이다. 컴포넌트의 분류 체계, 구조화된 정보, 상태 정보, 기타 메타 데이터를 표시할 수 있으며 사용자의 주의를 끌기 위해 색상을 활용할 수 있다.

## 기본

속성을 지정하지 않으면 `type="outline"`, `color="primary"`, `size="large"`로 표시됩니다.

```vue
<script setup lang="ts">
  import { KrdsBadge } from '@krds.ui/vue'
</script>

<template>
  <KrdsBadge>label</KrdsBadge>
</template>
```

## 기본 전체

`type`(`outline`, `bg`, `bg-light`)과 `color`의 조합입니다. 행마다 `size`를 `large`, `medium`, `small`로 달리했습니다.

```vue
<script setup lang="ts">
  import { KrdsBadge } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 1rem">
    <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center">
      <KrdsBadge type="outline" color="primary" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="secondary" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="gray" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="point" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="danger" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="warning" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="success" size="large">label</KrdsBadge>
      <KrdsBadge type="outline" color="information" size="large">label</KrdsBadge>
    </div>
    <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center">
      <KrdsBadge type="bg" color="primary" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="secondary" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="gray" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="point" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="danger" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="warning" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="success" size="medium">label</KrdsBadge>
      <KrdsBadge type="bg" color="information" size="medium">label</KrdsBadge>
    </div>
    <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center">
      <KrdsBadge type="bg-light" color="primary" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="secondary" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="gray" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="point" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="danger" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="warning" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="success" size="small">label</KrdsBadge>
      <KrdsBadge type="bg-light" color="information" size="small">label</KrdsBadge>
    </div>
  </div>
</template>
```

## 넘버 배지

```vue
<script setup lang="ts">
  import { KrdsBadge } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center">
    <KrdsBadge type="bg" color="primary" number>1234</KrdsBadge>
    <KrdsBadge type="bg" color="point" number>1234</KrdsBadge>
  </div>
</template>
```

## API

## KrdsBadge

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| number | boolean | false | 넘버 여부 |
| class | KrdsClassValue | - | CSS 클래스 |
| type | "outline" \| "bg" \| "bg-light" | 'outline' | 배지 타입 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | 'large' | 배지 크기 |
| color | ColorVariant ('primary' \| 'secondary' \| 'gray' \| 'point' \| 'danger' \| 'warning' \| 'success' \| 'information' \| 'disabled') | 'primary' | 배지 컬러 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 배지를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 배지 글자 |

---

# 아코디언 Accordion

아코디언은 한 페이지에서 관련 있는 여러 콘텐츠 섹션을 확인할 수 있도록 하는 컴포넌트로 콘텐츠 섹션의 헤더 목록이 수직으로 쌓여 있는 형태로 표현된다. 일반적으로 헤더 목록은 컨트롤 요소로 활용되며 사용자는 필요에 따라 헤더를 선택하여 하위 콘텐츠 섹션을 표시하거나 숨길 수 있다.

## 기본

`KrdsAccordionGroup` 안에 `KrdsAccordionItem`을 둡니다. 열린 항목의 `id`를 `open-item`으로 내려 주고 `toggle` 이벤트로 받은 `id`로 갱신합니다. 예제처럼 같은 `id`를 다시 받으면 닫도록 하면 한 번에 한 항목만 열립니다.

`id`는 항목 요소의 id와 `accordion-header-{id}`, `accordion-collapse-{id}`에 그대로 쓰이므로 페이지 안에서 고유해야 합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsAccordionGroup, KrdsAccordionItem } from '@krds.ui/vue'

  const openItem = ref<string>()
  const handleToggle = (id: string) => {
    openItem.value = openItem.value === id ? undefined : id
  }
</script>

<template>
  <KrdsAccordionGroup>
    <KrdsAccordionItem id="basic-1" :open-item="openItem" title="title1" content="content1" @toggle="handleToggle" />
    <KrdsAccordionItem id="basic-2" :open-item="openItem" title="title2" content="content2" @toggle="handleToggle" />
  </KrdsAccordionGroup>
</template>
```

## 라인

`type-line`을 지정하면 라인형으로 표시됩니다. 제목과 본문은 `title`, `content` 속성 대신 같은 이름의 슬롯으로도 넣을 수 있습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsAccordionGroup, KrdsAccordionItem } from '@krds.ui/vue'

  const openItem = ref<string>()
  const handleToggle = (id: string) => {
    openItem.value = openItem.value === id ? undefined : id
  }
</script>

<template>
  <KrdsAccordionGroup type-line>
    <KrdsAccordionItem id="line-1" :open-item="openItem" @toggle="handleToggle">
      <template #title>title1</template>
      <template #content>content1</template>
    </KrdsAccordionItem>
    <KrdsAccordionItem id="line-2" :open-item="openItem" @toggle="handleToggle">
      <template #title>title2</template>
      <template #content>content2</template>
    </KrdsAccordionItem>
  </KrdsAccordionGroup>
</template>
```

## API

## KrdsAccordionGroup

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| typeLine | boolean | false | 라인 타입 아코디언 여부 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 아코디언 항목 (KrdsAccordionItem) |

## KrdsAccordionItem

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| title | string | - | 헤더 텍스트 (title 슬롯으로 대체 가능) |
| content | string | - | 본문 텍스트 (content 슬롯으로 대체 가능) |
| openItem | string | - | 현재 열려 있는 아이템의 id |
| id (필수) | string | - | 아이템 고유 식별자 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| toggle | [id: string] | 펼침·접힘 버튼을 눌렀을 때 (항목 id) |

### Slots

| 이름 | 설명 |
| --- | --- |
| title | 제목 (title 속성 대신) |
| content | 펼쳤을 때 보이는 내용 (content 속성 대신) |

---

# 이미지 Image

이미지는 콘텐츠 양식 중 하나로 단일 이미지 또는 이미지 시퀀스로 표현될 수 있다. 이미지를 적절하게 사용하게 되면 사용자는 텍스트보다 효과적으로 정보를 인지할 수 있으며, 텍스트로 표현하기 어려운 정보를 전달할 수 있다.

## 기본

`alt`(대체 텍스트)는 필수입니다. 빠뜨리면 타입 검사(`vue-tsc`)에서 오류가 나고 개발 모드에서 경고가 뜹니다. 이미지가 전하는 정보를 구체적이고 간결하게 씁니다. 기본으로 `loading="lazy"`가 붙어 화면에 가까워질 때 불러오고, `width`·`height` 등 나머지 속성은 `<img>`에 그대로 전달됩니다. 화면 폭보다 크면 비율을 유지한 채 줄어듭니다.

```vue
<script setup lang="ts">
  import { KrdsImage } from '@krds.ui/vue'
</script>

<template>
  <KrdsImage src="/demo/floor-map.svg" alt="정문으로 들어와 복도에서 오른쪽으로 가면 첫 번째 방이 민원실" width="480" height="270" />
</template>
```

## 설명

`caption`을 주면 `<figure>`와 `<figcaption>`으로 감싸 이미지 아래에 설명을 표시합니다. 출처 링크처럼 마크업이 필요하면 `#caption` 슬롯을 씁니다. 촬영자·출처 정보는 대체 텍스트가 아니라 설명에 넣습니다.

```vue
<script setup lang="ts">
  import { KrdsImage } from '@krds.ui/vue'
</script>

<template>
  <KrdsImage
    src="/demo/floor-map.svg"
    alt="정문으로 들어와 복도에서 오른쪽으로 가면 첫 번째 방이 민원실"
    caption="본관 1층 안내도"
    width="480"
    height="270"
  />
</template>
```

## 장식 이미지

정보 없이 꾸밈용인 이미지는 `alt=""`로 비워 화면낭독기가 건너뛰게 합니다.

```vue
<script setup lang="ts">
  import { KrdsImage } from '@krds.ui/vue'
</script>

<template>
  <KrdsImage src="/demo/pattern.svg" alt="" width="640" height="120" />
</template>
```

## 접근성

- 앱이 개발 모드일 때 KRDS 이미지 접근성 가이드에 어긋나는 대체 텍스트를 콘솔에 경고합니다(Vue 경고, 배포 빌드에서는 출력하지 않음).
  - `'로고 이미지'`, `'강아지 사진'`처럼 끝에 이미지·사진·그림·그래픽 등 역할과 겹치는 말을 붙인 경우
  - 대체 텍스트가 `caption`과 같은 경우
- 컴포넌트는 내용이 적절한지까지 확인하지 못합니다. 이미지와 인접한 글과 같은 내용, 이미지에 없는 정보는 넣지 않습니다.
- 글자를 이미지로 만들지 말고 마크업 텍스트로 제공합니다.
- `KrdsImage` 대신 `<img>`를 직접 쓰는 곳까지 검사하려면 eslint-plugin-vuejs-accessibility의 [`alt-text` 규칙](https://vue-a11y.github.io/eslint-plugin-vuejs-accessibility/rules/alt-text.html)을 함께 씁니다.

## API

## KrdsImage

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| caption | string | - | 이미지 설명 (있으면 figure와 figcaption으로 감쌈) |
| src (필수) | string | - | 이미지 주소 |
| alt (필수) | string | - | 대체 텍스트 (필수, 장식용 이미지는 빈 문자열 '') |

### Slots

| 이름 | 설명 |
| --- | --- |
| caption | 이미지 설명 (출처 링크 등 마크업이 필요할 때, caption 대신) |

---

# 캐러셀 Carousel

캐러셀은 하나의 영역에서 여러 개의 콘텐츠를 순차적으로 번갈아 보여주는 컴포넌트이다. 한정된 공간에 여러 콘텐츠를 노출할 수 있으나 첫 번째 슬라이드 외에는 주목도가 크게 떨어지므로, 중요한 정보는 캐러셀에만 담지 않는 것이 좋다. 슬라이드는 기본 슬롯으로 전달하며 최상위 노드 하나가 슬라이드 한 장이 된다. 자동 재생 시에는 사용자가 즉시 정지할 수 있도록 재생/정지 버튼을 함께 노출한다.

## 기본 (비주얼 배너형)

```vue
<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="주요 서비스 안내" more-href="#">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>
```

## 배너형

배너형은 인디케이터 안에 분수형 페이지네이션과 이전/다음·더 보기 버튼을 배치합니다.

```vue
<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <KrdsCarousel variant="banner" aria-label="배너형 캐러셀 예제" more-href="#">
    <div v-for="index in 3" :key="index" class="in">
      <div class="text">
        <p class="cate">서브타이틀 {{ index }}</p>
        <p class="tit">타이틀 {{ index }}</p>
      </div>
      <div class="im">
        <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
          <rect width="243" height="178" fill="#E6E8EA" />
        </svg>
      </div>
    </div>
  </KrdsCarousel>
</template>
```

## 자동 재생

자동 재생 중에는 정지 버튼이 노출되며, 정지하면 재생 버튼으로 바뀝니다. 마우스 오버나 키보드 포커스가 캐러셀 안에 있는 동안에는 자동 재생이 멈춥니다.

```vue
<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <KrdsCarousel variant="banner" aria-label="자동 재생 캐러셀 예제" autoplay :autoplay-delay="3000" more-href="#">
    <div v-for="index in 3" :key="index" class="in">
      <div class="text">
        <p class="cate">서브타이틀 {{ index }}</p>
        <p class="tit">타이틀 {{ index }}</p>
      </div>
      <div class="im">
        <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
          <rect width="243" height="178" fill="#E6E8EA" />
        </svg>
      </div>
    </div>
  </KrdsCarousel>
</template>
```

## 순환 없음

`loop`를 끄면 처음과 마지막 슬라이드에서 이전/다음 버튼이 비활성화됩니다.

```vue
<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="순환 없는 캐러셀 예제" :loop="false">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>
```

## 분수형 페이지네이션

페이지네이션 방식은 형태와 무관하게 `pagination` 속성으로 바꿀 수 있습니다.

```vue
<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="분수형 페이지네이션 캐러셀 예제" pagination="fraction">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>
```

## API

## KrdsCarousel

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| id | string | - | 엘리먼트 ID |
| navigation | boolean | true | 이전/다음 버튼 표시 여부 (기본값: true) |
| variant | KrdsCarouselVariant ('visual' \| 'banner') | 'visual' | 캐러셀 형태 (기본값: visual) |
| ariaLabel | string | '캐러셀' | 캐러셀 영역 접근성 라벨 |
| activeIndex | number | - | 현재 슬라이드 인덱스 (v-model:activeIndex) |
| loop | boolean | true | 처음/마지막 슬라이드에서 순환 이동 여부 (기본값: true) |
| autoplay | boolean | false | 자동 재생 여부. true면 재생/정지 버튼을 노출하고 즉시 재생을 시작한다 (기본값: false) |
| autoplayDelay | number | DEFAULT_AUTOPLAY_DELAY | 자동 재생 간격 (ms, 기본값: 2500) |
| pauseOnHover | boolean | true | 마우스 오버 시 자동 재생 일시 정지 여부 (기본값: true). 포커스 진입 시에는 값과 무관하게 항상 정지한다 |
| speed | number | DEFAULT_SPEED | 슬라이드 전환 속도 (ms, 기본값: 400) |
| spaceBetween | number | - | 슬라이드 사이 간격 (px, 기본값: visual 0 / banner 16) |
| pagination | KrdsCarouselPaginationType ('bullets' \| 'fraction' \| 'none') | - | 페이지네이션 표시 방식 (기본값: visual bullets / banner fraction) |
| moreHref | string | - | 더 보기 링크 URL. 지정하면 더 보기 버튼을 표시한다 |
| prevLabel | string | '이전' | 이전 버튼 라벨 |
| nextLabel | string | '다음' | 다음 버튼 라벨 |
| playLabel | string | '슬라이드 재생' | 재생 버튼 라벨 |
| stopLabel | string | '슬라이드 멈춤' | 정지 버튼 라벨 |
| moreLabel | string | '더 보기' | 더 보기 버튼 라벨 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [value: number] | 슬라이드가 바뀌었을 때 (새 순서) |
| play | [] | 자동 재생을 시작했을 때 |
| update:activeIndex | [value: number] | 현재 슬라이드 순서가 바뀔 때 (v-model:active-index) |
| stop | [] | 자동 재생을 멈췄을 때 |
| more-click | [event: MouseEvent] | 더 보기 버튼을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 슬라이드 (자식 요소 하나가 한 장) |

---

# 탭 Tab

탭은 버튼을 눌러 상호배타적인 여러 개의 콘텐츠 섹션을 전환할 수 있는 컴포넌트이다. 탭 버튼 목록과 콘텐츠 패널이 수직으로 쌓여 있는 형태로 표현되며, 사용자는 탭을 선택하여 해당 콘텐츠 섹션을 표시할 수 있다.

## 기본

`tabs`의 각 항목 `id`와 같은 이름의 슬롯에 패널 내용을 넣습니다. 처음에는 비활성화되지 않은 첫 번째 탭이 선택되고, 선택된 탭에는 스크린 리더용 "선택됨" 텍스트(`selectedText`)가 붙습니다. 좌우 방향키로 탭 버튼 사이에서 포커스를 옮길 수 있습니다.

```vue
<script setup lang="ts">
  import { KrdsTabs } from '@krds.ui/vue'

  const tabs = [
    { id: 'tab1', label: '타이틀 1' },
    { id: 'tab2', label: '타이틀 2' },
    { id: 'tab3', label: '타이틀 3' }
  ]
</script>

<template>
  <KrdsTabs :tabs="tabs">
    <template #tab1>탭 1 영역</template>
    <template #tab2>탭 2 영역</template>
    <template #tab3>탭 3 영역</template>
  </KrdsTabs>
</template>
```

## 버튼형

```vue
<script setup lang="ts">
  import { KrdsTabs } from '@krds.ui/vue'

  const tabs = [
    { id: 'tab1', label: '타이틀 1' },
    { id: 'tab2', label: '타이틀 2' },
    { id: 'tab3', label: '타이틀 3' }
  ]
</script>

<template>
  <KrdsTabs :tabs="tabs" variant="fill">
    <template #tab1>탭 1 영역</template>
    <template #tab2>탭 2 영역</template>
    <template #tab3>탭 3 영역</template>
  </KrdsTabs>
</template>
```

## 풀사이즈

```vue
<script setup lang="ts">
  import { KrdsTabs } from '@krds.ui/vue'

  const tabs = [
    { id: 'tab1', label: '타이틀 1' },
    { id: 'tab2', label: '타이틀 2' }
  ]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 4rem">
    <KrdsTabs :tabs="tabs" full>
      <template #tab1>라인형 풀사이즈 탭 1 영역</template>
      <template #tab2>라인형 풀사이즈 탭 2 영역</template>
    </KrdsTabs>
    <KrdsTabs :tabs="tabs" variant="fill" full>
      <template #tab1>버튼형 풀사이즈 탭 1 영역</template>
      <template #tab2>버튼형 풀사이즈 탭 2 영역</template>
    </KrdsTabs>
  </div>
</template>
```

## 비활성화

항목에 `disabled: true`를 주면 해당 탭을 선택할 수 없습니다.

```vue
<script setup lang="ts">
  import { KrdsTabs } from '@krds.ui/vue'

  const tabs = [
    { id: 'tab1', label: '타이틀 1' },
    { id: 'tab2', label: '타이틀 2', disabled: true },
    { id: 'tab3', label: '타이틀 3' }
  ]
</script>

<template>
  <KrdsTabs :tabs="tabs">
    <template #tab1>탭 1 영역</template>
    <template #tab2>탭 2 영역</template>
    <template #tab3>탭 3 영역</template>
  </KrdsTabs>
</template>
```

## 외부 제어

`v-model`로 선택된 탭의 `id`를 제어합니다. 탭이 바뀌면 `change` 이벤트도 발생합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsTabs } from '@krds.ui/vue'

  const tabs = [
    { id: 'tab1', label: '타이틀 1' },
    { id: 'tab2', label: '타이틀 2' },
    { id: 'tab3', label: '타이틀 3' }
  ]
  const activeTab = ref('tab2')
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 2rem">
    <p>현재 탭: {{ activeTab }}</p>
    <KrdsTabs v-model="activeTab" :tabs="tabs">
      <template #tab1>탭 1 영역</template>
      <template #tab2>탭 2 영역</template>
      <template #tab3>탭 3 영역</template>
    </KrdsTabs>
  </div>
</template>
```

## API

## KrdsTabs

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| variant | KrdsTabsVariant ('line' \| 'fill') | 'line' | 탭 스타일 변형 |
| modelValue | string | - | 활성 탭 id (v-model) |
| full | boolean | false | 풀사이즈 레이아웃 여부 |
| selectedText | string | '선택됨' | 선택된 탭의 스크린 리더 대체 텍스트 |
| tabs (필수) | KrdsTabItem[] | - | 탭 아이템 목록 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [id: string] | 탭을 바꿨을 때 (탭 id) |
| update:modelValue | [id: string] | 선택한 탭 id가 바뀔 때 (v-model) |

---

# 표 Table

표는 데이터를 하나 이상의 행과 열로 조직화하여 표현하는 형식으로 사용자가 빠르게 많은 양의 정보를 확인하고 비교할 수 있도록 도와준다. 기본적으로 대화형 요소가 아니기 때문에 열 제목에 데이터를 정렬하기 위한 컨트롤 요소가 포함된 상황 외에 행 전체나 데이터 셀이 대화형으로 작동하지 않는다.

## 기본 테이블

`columns`로 열을, `rows`로 행 데이터를 정의합니다. 각 행의 첫 번째 셀은 행 제목(`th scope="row"`)으로 렌더되고, `headerStyle`의 `width`는 `colgroup`의 열 너비로도 쓰입니다. KRDS 표 스타일은 `class`에 `data`가 있을 때 적용되므로 원본 KRDS 마크업처럼 `col data`를 지정합니다. `caption`은 화면에 보이지 않고 스크린 리더로 읽히므로 표의 구성을 설명하는 문장으로 씁니다.

```vue
<script setup lang="ts">
  import { KrdsTable } from '@krds.ui/vue'

  const columns = [
    { name: 'title', label: '제목1', field: 'title', headerStyle: 'width: 30%' },
    { name: 'content', label: '제목2', field: 'content' }
  ]
  const rows = [
    {
      title: '제목1-1',
      content:
        '내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다.'
    },
    { title: '제목1-2', content: '내용이 들어갑니다.' },
    { title: '제목1-3', content: '내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다. 내용이 들어갑니다.' }
  ]
</script>

<template>
  <KrdsTable
    caption="000에 대한 표로 제목1,제목2에 대한 내용으로 구성되어 있으며 제목1은 제목1-1,제목1-2,제목1-3으로 구성되어있다."
    class="col data"
    :columns="columns"
    :rows="rows"
  />
</template>
```

## 행 클릭

`row-click` 리스너가 있을 때만 행이 포커스를 받고(`tabindex="0"`) 클릭이나 Enter·Space 키로 선택됩니다. 리스너가 없으면 행은 대화형으로 동작하지 않습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsTable, type TableRow } from '@krds.ui/vue'

  const columns = [
    { name: 'name', label: '이름', field: 'name' },
    { name: 'score', label: '점수', field: 'score' }
  ]
  const rows = [
    { name: '김철수', score: 95 },
    { name: '이영희', score: 78 },
    { name: '박민수', score: 88 }
  ]
  const selected = ref('없음')

  const onRowClick = (row: TableRow, index: number) => {
    selected.value = `${row.name} (${index})`
  }
</script>

<template>
  <KrdsTable
    caption="행을 클릭하거나 Enter·Space로 선택하는 테이블"
    class="col data"
    :columns="columns"
    :rows="rows"
    @row-click="onRowClick"
  />
  <p style="margin-top: 1.6rem">선택된 행: {{ selected }}</p>
</template>
```

## 스타일 & 클래스 기능

열마다 헤더 셀에는 `headerStyle`·`headerClasses`를, 바디 셀에는 `style`·`classes`를 지정합니다. 바디 셀의 `style`·`classes`는 행 데이터를 받는 함수로도 줄 수 있습니다. `align`을 지정하면 헤더와 바디 셀에 `text-<align>` 클래스가 붙습니다. 클래스의 스타일은 앱의 CSS에서 정의합니다.

```vue
<script setup lang="ts">
  import { KrdsTable, type TableColumn, type TableRow } from '@krds.ui/vue'

  const columns: TableColumn[] = [
    {
      name: 'id',
      label: 'ID',
      field: 'id',
      headerStyle: 'width: 80px',
      headerClasses: 'bg-gray-100 text-center font-bold',
      style: 'width: 80px',
      classes: 'text-center',
      align: 'center'
    },
    {
      name: 'name',
      label: '이름',
      field: 'name',
      headerStyle: 'width: 150px; color: #333',
      classes: 'font-medium'
    },
    {
      name: 'score',
      label: '점수',
      field: 'score',
      headerStyle: 'width: 100px',
      headerClasses: 'text-right',
      classes: (row: TableRow) => ((row.score as number) >= 80 ? 'score-high text-right' : 'score-low text-right'),
      align: 'right'
    },
    {
      name: 'status',
      label: '상태',
      field: 'status',
      headerClasses: 'text-center',
      classes: (row: TableRow) => `status-${(row.status as string).toLowerCase()} text-center`,
      align: 'center'
    }
  ]
  const rows = [
    { id: 1, name: '김철수', score: 95, status: 'PASS' },
    { id: 2, name: '이영희', score: 78, status: 'FAIL' },
    { id: 3, name: '박민수', score: 88, status: 'PASS' },
    { id: 4, name: '정수진', score: 92, status: 'PASS' }
  ]
</script>

<template>
  <KrdsTable caption="헤더와 바디에 스타일/클래스가 적용된 테이블" class="col data" :columns="columns" :rows="rows" />
</template>
```

## 셀 슬롯

배지·버튼·체크박스처럼 글자가 아닌 내용은 열 이름(`name`)으로 슬롯을 받아 그립니다. `#cell-<name>`은 본문 셀 내용을 바꾸고 `{ row, column, value, index }`를 받습니다(`value`는 `field`로 꺼낸 값). `#header-<name>`은 헤더 셀 내용을 바꿔 화면에 숨긴 열 제목 등에 씁니다. 셀 태그(첫 열은 `th scope="row"`)와 `style`·`classes`는 그대로 유지되고, 슬롯으로만 그리는 열은 `field`를 생략합니다. 버튼처럼 같은 이름이 행마다 반복되면 숨김 텍스트로 어느 행의 버튼인지 알려 줍니다.

```vue
<script setup lang="ts">
  import { KrdsBadge, KrdsButton, KrdsTable } from '@krds.ui/vue'

  const columns = [
    { name: 'title', label: '민원명', field: 'title', headerStyle: 'width: 40%' },
    { name: 'status', label: '처리 상태', field: 'status' },
    { name: 'date', label: '신청일', field: 'date' },
    // 슬롯으로만 그리는 열은 field를 생략한다
    { name: 'action', label: '관리' }
  ]
  const rows = [
    { id: 1, title: '주민등록표 등본 발급', status: '완료', date: '2026.10.02' },
    { id: 2, title: '전입 신고', status: '처리 중', date: '2026.10.05' },
    { id: 3, title: '여권 재발급', status: '반려', date: '2026.10.07' }
  ]
  const badgeColor = { 완료: 'success', '처리 중': 'information', 반려: 'danger' } as const
</script>

<template>
  <KrdsTable caption="민원 신청 내역: 민원명, 처리 상태, 신청일, 관리로 구성" class="col data" :columns="columns" :rows="rows">
    <template #cell-status="{ value }">
      <KrdsBadge type="bg-light" :color="badgeColor[value as keyof typeof badgeColor]">{{ value }}</KrdsBadge>
    </template>
    <template #header-action><span class="sr-only">관리</span></template>
    <template #cell-action="{ row }">
      <KrdsButton text size="small"
        >상세 보기<span class="sr-only">: {{ row.title }}</span></KrdsButton
      >
    </template>
  </KrdsTable>
</template>
```

## 빈 데이터 (기본)

`rows`가 비어 있으면 모든 열을 합친 셀에 "데이터가 없습니다."를 표시합니다.

```vue
<script setup lang="ts">
  import { KrdsTable } from '@krds.ui/vue'

  const columns = [
    { name: 'id', label: 'ID', field: 'id' },
    { name: 'name', label: '이름', field: 'name' },
    { name: 'email', label: '이메일', field: 'email' }
  ]
</script>

<template>
  <KrdsTable caption="데이터가 없는 테이블" class="col data" :columns="columns" :rows="[]" />
</template>
```

## 빈 데이터 (커스텀 슬롯)

`no-data` 슬롯으로 빈 상태 내용을 바꿉니다.

```vue
<script setup lang="ts">
  import { KrdsTable } from '@krds.ui/vue'

  const columns = [
    { name: 'id', label: 'ID', field: 'id' },
    { name: 'name', label: '이름', field: 'name' },
    { name: 'email', label: '이메일', field: 'email' }
  ]
</script>

<template>
  <KrdsTable caption="커스텀 no-data 슬롯이 있는 테이블" class="col data" :columns="columns" :rows="[]">
    <template #no-data>
      <div style="padding: 2rem; text-align: center; color: #666">
        <div style="font-size: 1.2rem; margin-bottom: 0.5rem">데이터를 찾을 수 없습니다</div>
        <div style="font-size: 0.9rem">새로운 데이터를 추가해보세요</div>
      </div>
    </template>
  </KrdsTable>
</template>
```

## API

## KrdsTable

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| caption | string | - | 테이블 캡션 |
| columns (필수) | TableColumn[] | - | 테이블 열 정의 |
| rows (필수) | TableRow[] | - | 테이블 행 데이터 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| row-click | [row: TableRow, index: number] | 행을 클릭했을 때 (행, 순서) |

### Slots

| 이름 | 설명 |
| --- | --- |
| no-data | 행이 없을 때 표시할 내용 |

### 열 이름 슬롯

열 이름(`name`)마다 받는 슬롯입니다. 이름이 열 정의에 따라 정해져 위 Slots 표에는 나오지 않습니다.

| 이름            | 인자                                                                    | 설명                                             |
| --------------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
| `cell-<name>`   | `{ row: TableRow, column: TableColumn, value: unknown, index: number }` | 본문 셀 내용. 셀 태그와 `style`·`classes`는 유지 |
| `header-<name>` | `{ column: TableColumn }`                                               | 헤더 셀 내용 (예: 화면에 숨긴 열 제목)           |

---

# 텍스트 목록 Text list

텍스트 목록은 계층 구조가 있는 텍스트 블록을 읽기 쉽게 구성한 것이다.

## 기본 (대시)

`type`으로 `ul`·`ol` 요소를, `variant`로 글머리 스타일을 정합니다. 항목(`li`) 안에 `KrdsTextList`를 넣어 3단계까지 중첩합니다.

```vue
<script setup lang="ts">
  import { KrdsTextList } from '@krds.ui/vue'
</script>

<template>
  <KrdsTextList type="ul" variant="dash">
    <li>텍스트 목록 레벨1</li>
    <li>
      텍스트 목록 레벨1
      <KrdsTextList type="ul" variant="hollow">
        <li>텍스트 목록 레벨2</li>
        <li>텍스트 목록 레벨2</li>
      </KrdsTextList>
    </li>
    <li>텍스트 목록 레벨1</li>
  </KrdsTextList>
</template>
```

## 순서 있는 목록

`variant="ordered"`는 번호를 자동으로 붙이지 않으므로 항목마다 `<span class="num">`으로 번호를 직접 씁니다.

```vue
<script setup lang="ts">
  import { KrdsTextList } from '@krds.ui/vue'
</script>

<template>
  <KrdsTextList type="ol" variant="ordered">
    <li><span class="num">1. </span>텍스트 목록 레벨1</li>
    <li>
      <span class="num">2. </span>텍스트 목록 레벨1
      <KrdsTextList type="ol" variant="ordered">
        <li><span class="num">a. </span>텍스트 목록 레벨2</li>
        <li>
          <span class="num">b. </span>텍스트 목록 레벨2
          <KrdsTextList type="ol" variant="ordered">
            <li><span class="num">①</span>텍스트 목록 레벨3</li>
            <li><span class="num">②</span>텍스트 목록 레벨3</li>
          </KrdsTextList>
        </li>
        <li><span class="num">c. </span>텍스트 목록 레벨2</li>
      </KrdsTextList>
    </li>
    <li><span class="num">3. </span>텍스트 목록 레벨1</li>
  </KrdsTextList>
  <br />
  <KrdsTextList type="ul" variant="decimal">
    <li>
      텍스트 목록 레벨1
      <KrdsTextList type="ul" variant="dash">
        <li>
          텍스트 목록 레벨2
          <KrdsTextList type="ol" variant="ordered">
            <li><span class="num">①</span>텍스트 목록 레벨3</li>
            <li><span class="num">②</span>텍스트 목록 레벨3</li>
          </KrdsTextList>
        </li>
      </KrdsTextList>
    </li>
    <li>
      텍스트 목록 레벨1
      <KrdsTextList type="ol" variant="ordered">
        <li>
          <span class="num">a. </span>텍스트 목록 레벨2
          <KrdsTextList type="ul" variant="hollow">
            <li>텍스트 목록 레벨3</li>
            <li>텍스트 목록 레벨3</li>
          </KrdsTextList>
        </li>
      </KrdsTextList>
    </li>
  </KrdsTextList>
</template>
```

## API

## KrdsTextList

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| type | "ol" \| "ul" | 'ul' | 리스트 타입 |
| variant | "decimal" \| "dash" \| "hollow" \| "ordered" | 'dash' | 스타일 변형 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 목록 항목 |

---

# 링크 Link

링크는 다른 서비스/애플리케이션, 한 서비스 내의 다른 화면, 한 화면 내의 다른 섹션 등으로 이동하는 데 사용되는 탐색 요소이다.

## 기본

`target="_blank"`이면 `rel="noopener noreferrer"`가 자동으로 붙습니다. 새 창으로 열리는 링크는 `title`로 그 사실을 알립니다.

```vue
<script setup lang="ts">
  import { KrdsLink } from '@krds.ui/vue'
</script>

<template>
  <KrdsLink href="https://www.site_name.com/" size="small" target="_blank" title="새 창 열림">
    <span class="underline">기본 링크</span> <i class="svg-icon ico-go"></i>
  </KrdsLink>
</template>
```

## 모든 링크 변형

```vue
<script setup lang="ts">
  import { KrdsLink } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px">
    <KrdsLink href="#!" size="medium" pure>
      <span class="underline">가상클래스 상태 시 컬러 유지</span>
    </KrdsLink>

    <KrdsLink href="#!" size="large" basic target="_blank" title="새 창 열림">
      <span class="underline">본문 텍스트 컬러 링크</span> <i class="svg-icon ico-go"></i>
    </KrdsLink>

    <KrdsLink href="#!" size="large" basic>
      <span class="underline hidden-underline">가상클래스 상태 시 밑줄</span>
    </KrdsLink>

    <KrdsLink href="#!" size="large" basic>
      <span>밑줄 없음</span>
    </KrdsLink>
  </div>
</template>
```

## API

## KrdsLink

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| link | boolean | true | Link 클래스 적용 여부 |
| title | string | - | 링크 제목 (접근성) |
| href | string | '#!' | 링크 URL |
| size | KrdsLinkSize ('small' \| 'medium' \| 'large') | - | 링크 크기 |
| target | string | - | 링크 대상 (_blank, _self 등) |
| basic | boolean | false | Basic 링크 여부 (본문 텍스트 컬러) |
| pure | boolean | false | Pure 링크 여부 (가상클래스 상태 시 컬러 유지) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 링크를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 링크 내용 |

---

# 버튼 Button

버튼은 어떤 기능이나 동작을 실행하거나 기능을 사용하기 위한 상태로 변경하는 요소이다. 사용자가 서비스를 이용하는 과정에서 어떤 행동이 중요한지에 따라 관련된 버튼이 다양한 스타일로 표현된다.

## 계층

`variant`로 버튼의 중요도를 표현합니다. 화면의 주요 행동에는 `primary`를 한 번만 사용합니다.

```vue
<script setup lang="ts">
  import { KrdsButton } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton variant="primary">버튼 : primary</KrdsButton>
    <KrdsButton variant="secondary">버튼 : secondary</KrdsButton>
    <KrdsButton variant="tertiary">버튼 : tertiary</KrdsButton>
  </div>
</template>
```

## 사이즈

```vue
<script setup lang="ts">
  import { KrdsButton } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton size="xsmall">x-small 버튼</KrdsButton>
    <KrdsButton size="small">small 버튼</KrdsButton>
    <KrdsButton size="medium">medium 버튼</KrdsButton>
    <KrdsButton size="large">large 버튼</KrdsButton>
    <KrdsButton size="xlarge">x-large 버튼</KrdsButton>
  </div>
</template>
```

## 아이콘 버튼

텍스트 앞이나 뒤에 아이콘을 둘 수 있습니다. 아이콘 크기는 버튼 크기에 맞춰집니다.

```vue
<script setup lang="ts">
  import { KrdsButton } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton size="small">small 버튼 <i class="svg-icon ico-sch"></i></KrdsButton>
    <KrdsButton size="medium">medium 버튼 <i class="svg-icon ico-sch"></i></KrdsButton>
    <KrdsButton size="large"><i class="svg-icon ico-sch"></i> large 버튼</KrdsButton>
  </div>
</template>
```

## 텍스트 버튼

```vue
<script setup lang="ts">
  import { KrdsButton } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton size="small" text>텍스트 버튼</KrdsButton>
    <KrdsButton size="small" text>주민등록표초본 <i class="svg-icon ico-angle right"></i></KrdsButton>
    <KrdsButton size="medium" text>검색 <i class="svg-icon ico-sch"></i></KrdsButton>
    <KrdsButton text>파일다운로드 <i class="svg-icon ico-down"></i></KrdsButton>
    <KrdsButton text disabled>필터 <i class="svg-icon ico-filter"></i></KrdsButton>
  </div>
</template>
```

## 아이콘만 있는 버튼

보이는 텍스트가 없으므로 `sr-only` 텍스트로 버튼 이름을 반드시 제공합니다.

```vue
<script setup lang="ts">
  import { KrdsButton } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton icon>
      <span class="sr-only">검색</span>
      <i class="svg-icon ico-sch"></i>
    </KrdsButton>
    <KrdsButton icon size="medium">
      <span class="sr-only">입력한 비밀번호 보기</span>
      <i class="svg-icon ico-pw-visible"></i>
    </KrdsButton>
    <KrdsButton icon border size="large">
      <span class="sr-only">새로고침</span>
      <i class="svg-icon ico-refresh"></i>
    </KrdsButton>
    <KrdsButton icon border size="large" disabled>
      <span class="sr-only">열기</span>
      <i class="svg-icon ico-angle down"></i>
    </KrdsButton>
  </div>
</template>
```

## API

## KrdsButton

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| type | "button" \| "reset" \| "submit" | 'button' | 버튼 타입 |
| variant | Variant ('primary' \| 'secondary' \| 'tertiary') | 'primary' | 버튼 변형 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | - | 버튼 크기 |
| disabled | boolean | false | 비활성화 여부 |
| pure | boolean | false | Pure 버튼 여부 (가상클래스 상태 시 컬러 유지) |
| icon | boolean | false | 아이콘 전용 버튼 |
| border | boolean | false | 테두리 스타일 (아이콘 버튼용) |
| text | boolean | false | 텍스트 버튼 스타일 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 버튼을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 버튼 내용 |

---

# 플로팅 버튼 Floating action button

플로팅 버튼은 사용자가 화면에서 가장 자주 사용하고 중요한 작업에 단일 또는 다중으로 사용한다. 페이지가 스크롤될 때에도 화면 우측 하단에 계속 표현한다.

## 단일형

아이콘과 레이블로 하나의 주요 작업을 보여 줍니다. `href`를 주면 링크, 없으면 버튼으로 렌더링하고 `click` 이벤트를 보냅니다. `hide-label`을 주면 아이콘만 보이고 레이블은 화면낭독기용으로 남습니다. 화면 오른쪽 아래에 고정되므로 예제를 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFloatingButton } from '@krds.ui/vue'

  const count = ref(0)
</script>

<template>
  <div>
    <p>오른쪽 아래 버튼을 눌러 보세요. 누른 횟수: {{ count }}</p>
    <KrdsFloatingButton label="채팅 상담" icon="ico-faq" @click="count++" />
  </div>
</template>
```

## 확장형

`items`를 주면 확장형이 됩니다. + 버튼을 누르면 가림막과 함께 항목이 펼쳐지고, X 버튼·가림막·Esc 키로 닫습니다. 항목을 누르면 목록을 닫고 초점을 + 버튼으로 돌려준 뒤 `select` 이벤트(항목, 순서, 클릭 이벤트)를 보냅니다. 같은 페이지의 대상(`#id`)으로 이동하는 링크는 이동한 위치에서 키보드 탐색을 이어 가도록 초점을 놓습니다. 링크 항목은 `event.preventDefault()`로 라우터 이동에 쓸 수 있고, `external`을 주면 새 창으로 엽니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFloatingButton } from '@krds.ui/vue'
  import type { KrdsFloatingButtonItem } from '@krds.ui/vue'

  const items: KrdsFloatingButtonItem[] = [
    { label: '자주 묻는 질문', icon: 'ico-faq' },
    { label: '전화 상담', icon: 'ico-call', href: 'tel:1555-6365' },
    { label: '이메일 문의', icon: 'ico-email', href: 'mailto:krds@nia.or.kr' }
  ]
  const selected = ref('')
</script>

<template>
  <div>
    <p>오른쪽 아래 + 버튼으로 항목을 펼치세요. 선택한 항목: {{ selected || '없음' }}</p>
    <KrdsFloatingButton label="상담 메뉴" :items="items" @select="item => (selected = item.label)" />
  </div>
</template>
```

## 사용 지침

- 화면 오른쪽 아래에 배치하고, 화면의 모든 요소 위에 둡니다.
- 플로팅 버튼이 2개 이상 필요하면 확장형을 쓰고, 항목은 3개 이하로 구성합니다.
- 확장형의 깊이는 2수준 이하로만 사용합니다.
- 자주 쓰는 행동이 여러 개이거나 지도·캘린더처럼 제스처 조작이 많은 화면에는 쓰지 않습니다.

## API

## KrdsFloatingButton

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| items | KrdsFloatingButtonItem[] | - | 확장형 항목 (지정하면 확장형, 3개 이하 권장) |
| href | string | - | 단일형 버튼의 링크 주소 |
| icon | string | 'ico-plus' | 단일형 버튼의 아이콘 클래스 |
| external | boolean | false | 단일형 링크를 새 창으로 열기 ('새 창 열림' 안내 포함) |
| hideLabel | boolean | false | 단일형 레이블을 화면에서 숨김 (아이콘만 표시, 화면낭독기는 읽음) |
| label (필수) | string | - | 단일형 버튼의 레이블, 확장형은 확장 버튼의 이름 (화면에는 숨김) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 단일형 버튼 클릭 |
| select | [item: KrdsFloatingButtonItem, index: number, event: MouseEvent] | 확장형 항목 선택 (링크 항목은 event.preventDefault()로 라우터 이동 가능) |

---

# 라디오 버튼 Radio button

라디오 버튼은 사용자가 여러 개의 옵션 중 하나만 선택할 수 있도록 하는 경우에 사용한다. 즉, 라디오 버튼 옵션의 선택은 상호배타적이므로 한 개의 옵션을 선택하면 다른 옵션은 자동으로 선택 해제된다.

## 기본

같은 그룹의 라디오는 같은 `name`과 `v-model`을 쓰고, `modelValue`가 `value`와 같은 라디오가 선택됩니다. `description` 슬롯으로 부가 설명을 넣을 수 있고, `KrdsCheckArea`의 `column`으로 세로로 배치합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsCheckArea, KrdsRadio } from '@krds.ui/vue'

  const selectedValue = ref('option2')
  const selectedValue2 = ref('option4')
  const selectedWithDescription = ref('option1')
</script>

<template>
  <div>
    <div style="margin-bottom: 2rem">
      <KrdsCheckArea>
        <KrdsRadio v-model="selectedValue" value="option1" name="basic">기본</KrdsRadio>
        <KrdsRadio v-model="selectedValue" value="option2" name="basic">선택됨</KrdsRadio>
        <KrdsRadio v-model="selectedValue" value="option3" name="basic" disabled>비활성화</KrdsRadio>
        <KrdsRadio v-model="selectedValue2" value="option4" name="basic2" disabled>선택된 비활성화</KrdsRadio>
      </KrdsCheckArea>
    </div>

    <div>
      <KrdsCheckArea column>
        <KrdsRadio v-model="selectedWithDescription" value="option1" name="withDesc">
          라디오버튼
          <template #description>부가적인 설명이 들어갑니다.</template>
        </KrdsRadio>
        <KrdsRadio v-model="selectedWithDescription" value="option2" name="withDesc">
          라디오버튼
          <template #description>부가적인 설명이 들어갑니다.</template>
        </KrdsRadio>
      </KrdsCheckArea>
    </div>
  </div>
</template>
```

## API

## KrdsRadio

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| id | string | - | HTML ID |
| modelValue | string \| number \| boolean | - | 모델 값 |
| size | "medium" \| "large" | 'medium' | 크기 |
| disabled | boolean | false | 비활성화 여부 |
| chip | boolean | false | Chip 스타일 여부 |
| value (필수) | string \| number \| boolean | - | 라디오 값 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: string \| number \| boolean] | 이 항목을 선택할 때 (항목 value, v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | - |
| description | - |

## KrdsCheckArea

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | 추가 클래스 |
| column | boolean | false | 세로(컬럼) 배치 여부 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 체크박스·라디오 버튼 묶음 |

---

# 체크박스 Checkbox

체크박스는 사용자가 여러 개의 옵션 중 한 개 이상의 값을 선택할 수 있도록 하는 경우에 사용한다. 즉, 체크박스 옵션의 선택은 상호배타적이므로 한 개의 옵션을 선택하는 것은 다른 옵션의 선택에 영향을 미치지 않는다.

## 기본

`v-model`로 선택 상태(`boolean`)를 연결합니다. `description` 슬롯으로 부가 설명을 넣을 수 있고, `KrdsCheckArea`의 `column`으로 세로로 배치합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsCheckArea, KrdsCheckbox } from '@krds.ui/vue'

  const basic = ref(false)
  const selected = ref(true)
  const disabled = ref(false)
  const disabledSelected = ref(true)
  const description1 = ref(false)
  const description2 = ref(false)
</script>

<template>
  <div>
    <div style="margin-bottom: 2rem">
      <KrdsCheckArea>
        <KrdsCheckbox v-model="basic">기본</KrdsCheckbox>
        <KrdsCheckbox v-model="selected">선택됨</KrdsCheckbox>
        <KrdsCheckbox v-model="disabled" disabled>비활성화</KrdsCheckbox>
        <KrdsCheckbox v-model="disabledSelected" disabled>선택된 비활성화</KrdsCheckbox>
      </KrdsCheckArea>
    </div>

    <div>
      <KrdsCheckArea column>
        <KrdsCheckbox v-model="description1">
          체크박스
          <template #description>부가적인 설명이 들어갑니다.</template>
        </KrdsCheckbox>
        <KrdsCheckbox v-model="description2">
          체크박스
          <template #description>부가적인 설명이 들어갑니다.</template>
        </KrdsCheckbox>
      </KrdsCheckArea>
    </div>
  </div>
</template>
```

## 사이즈

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsCheckArea, KrdsCheckbox } from '@krds.ui/vue'

  const mediumChecked = ref(false)
  const largeChecked = ref(false)
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 1.5rem">
    <KrdsCheckArea>
      <KrdsCheckbox v-model="mediumChecked" size="medium">Medium 크기 체크박스</KrdsCheckbox>
    </KrdsCheckArea>

    <KrdsCheckArea>
      <KrdsCheckbox v-model="largeChecked" size="large">Large 크기 체크박스</KrdsCheckbox>
    </KrdsCheckArea>
  </div>
</template>
```

## Chip

`chip`을 지정하면 칩 모양으로 표시됩니다. 칩 스타일에서는 `description` 슬롯이 표시되지 않습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsCheckArea, KrdsCheckbox } from '@krds.ui/vue'

  const checked1 = ref(false)
  const checked2 = ref(true)
  const checked3 = ref(false)
</script>

<template>
  <KrdsCheckArea>
    <KrdsCheckbox v-model="checked1" chip>Chip 체크박스 1</KrdsCheckbox>
    <KrdsCheckbox v-model="checked2" chip>Chip 체크박스 2 (선택됨)</KrdsCheckbox>
    <KrdsCheckbox v-model="checked3" chip disabled>Chip 체크박스 3</KrdsCheckbox>
  </KrdsCheckArea>
</template>
```

## API

## KrdsCheckbox

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| id | string | - | HTML ID |
| modelValue | boolean | false | 모델 값 |
| size | "medium" \| "large" | 'medium' | 크기 |
| disabled | boolean | false | 비활성화 여부 |
| chip | boolean | false | Chip 스타일 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: boolean] | 체크 상태가 바뀔 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | - |
| description | - |

## KrdsCheckArea

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | 추가 클래스 |
| column | boolean | false | 세로(컬럼) 배치 여부 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 체크박스·라디오 버튼 묶음 |

---

# 셀렉트 Select

셀렉트는 사용자에게 여러 개의 옵션 목록을 팝업으로 제공하여 그 중 한 개의 값을 선택할 수 있도록 하는 경우에 사용한다.

## 기본

`KrdsFormGroup`·`KrdsFormLabel`·`KrdsFormHint`와 함께 써서 레이블과 도움말을 연결합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsSelect } from '@krds.ui/vue'

  const selected = ref('')
  const options = [
    { value: 'seoul', label: '서울특별시' },
    { value: 'busan', label: '부산광역시' },
    { value: 'daegu', label: '대구광역시' },
    { value: 'incheon', label: '인천광역시' },
    { value: 'gwangju', label: '광주광역시' },
    { value: 'daejeon', label: '대전광역시' },
    { value: 'ulsan', label: '울산광역시' },
    { value: 'sejong', label: '세종특별자치시' }
  ]
</script>

<template>
  <div style="max-width: 400px">
    <KrdsFormGroup>
      <KrdsFormLabel for="city-select">거주 지역</KrdsFormLabel>
      <KrdsSelect id="city-select" v-model="selected" :options="options" placeholder="선택" />
      <KrdsFormHint>현재 거주하고 있는 지역을 선택해 주세요</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## 사이즈

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormLabel, KrdsSelect } from '@krds.ui/vue'

  const large = ref('large')
  const medium = ref('medium')
  const small = ref('small')
  const options = [
    { value: 'large', label: 'large' },
    { value: 'medium', label: 'medium' },
    { value: 'small', label: 'small' }
  ]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 400px">
    <KrdsFormGroup>
      <KrdsFormLabel for="select-large">Large</KrdsFormLabel>
      <KrdsSelect id="select-large" v-model="large" size="large" :options="options" />
    </KrdsFormGroup>
    <KrdsFormGroup>
      <KrdsFormLabel for="select-medium">Medium</KrdsFormLabel>
      <KrdsSelect id="select-medium" v-model="medium" size="medium" :options="options" />
    </KrdsFormGroup>
    <KrdsFormGroup>
      <KrdsFormLabel for="select-small">Small</KrdsFormLabel>
      <KrdsSelect id="select-small" v-model="small" size="small" :options="options" />
    </KrdsFormGroup>
  </div>
</template>
```

## 정렬 스타일

목록의 정렬 기준처럼 보이는 레이블 없이 쓰는 셀렉트입니다. `title`로 이름을 제공합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsSelect } from '@krds.ui/vue'

  const sort = ref('latest')
  const options = [
    { value: 'latest', label: '최신순' },
    { value: 'popular', label: '인기순' },
    { value: 'name', label: '이름순' }
  ]
</script>

<template>
  <KrdsSelect id="select-sort" v-model="sort" sort :options="options" title="정렬 기준" />
</template>
```

## 에러 상태

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsSelect } from '@krds.ui/vue'

  const selected = ref('')
  const options = [
    { value: 'item1', label: '항목1' },
    { value: 'item2', label: '항목2' },
    { value: 'item3', label: '항목3' }
  ]
</script>

<template>
  <div style="max-width: 400px">
    <KrdsFormGroup>
      <KrdsFormLabel for="select-error">신청 유형</KrdsFormLabel>
      <KrdsSelect id="select-error" v-model="selected" state="error" :options="options" placeholder="선택" />
      <KrdsFormHint type="error">신청 유형을 선택해 주세요</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## API

## KrdsSelect

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| sort | boolean | false | 정렬 스타일 여부 |
| name | string | - | 폼 필드 이름 |
| title | string | - | 타이틀 |
| id | string | - | HTML ID |
| modelValue | string \| number \| null | null | 선택된 값 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | 'medium' | 선택 크기 |
| disabled | boolean | false | 비활성화 여부 |
| options | SelectOption[] | [] | 옵션 목록 |
| placeholder | string | '선택' | 플레이스홀더 |
| readonly | boolean | false | 읽기 전용 여부 |
| state | "default" \| "error" \| "success" \| "information" | 'default' | 입력 상태 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| blur | [event: FocusEvent] | 초점을 잃었을 때 |
| focus | [event: FocusEvent] | 초점을 받았을 때 |
| update:modelValue | [value: string \| number \| null] | 선택한 값이 바뀔 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 직접 넣는 option 요소 (options 속성과 함께 쓸 수 있음) |

---

# 태그 Tag

태그는 키워드 또는 레이블을 사용하여 콘텐츠를 분류하는 수단이다. 콘텐츠 항목에 직접 관련 분류 체계, 데이터 속성을 표시하거나, 목록에서 특정 분류 체계, 데이터 속성을 가진 항목이 선택되었음을 보여주기 위한 태그 그룹으로 사용된다.

## 기본

링크가 아닌 태그에는 삭제 버튼이 함께 표시되며, 누르면 `remove` 이벤트가 발생합니다.

```vue
<script setup lang="ts">
  import { KrdsTag, KrdsTagGroup } from '@krds.ui/vue'
</script>

<template>
  <KrdsTagGroup>
    <KrdsTag>버튼</KrdsTag>
  </KrdsTagGroup>
</template>
```

## 사이즈

크기는 `KrdsTagGroup`의 `size`로 지정합니다.

```vue
<script setup lang="ts">
  import { KrdsTag, KrdsTagGroup } from '@krds.ui/vue'
</script>

<template>
  <div>
    <KrdsTagGroup size="large" style="margin-bottom: 1rem">
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
    </KrdsTagGroup>

    <KrdsTagGroup size="medium" style="margin-bottom: 1rem">
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
    </KrdsTagGroup>

    <KrdsTagGroup size="small">
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
      <KrdsTag>태그</KrdsTag>
    </KrdsTagGroup>
  </div>
</template>
```

## 링크 태그

`link`를 지정하면 삭제 버튼 없이 `href`로 이동하는 링크로 렌더링됩니다.

```vue
<script setup lang="ts">
  import { KrdsTag, KrdsTagGroup } from '@krds.ui/vue'
</script>

<template>
  <div>
    <KrdsTagGroup size="large" style="margin-bottom: 1rem">
      <KrdsTag link href="#">카테고리</KrdsTag>
      <KrdsTag link href="https://example.com" target="_blank" rel="noopener">외부 링크</KrdsTag>
      <KrdsTag link href="#">필터 태그</KrdsTag>
    </KrdsTagGroup>

    <KrdsTagGroup size="medium" style="margin-bottom: 1rem">
      <KrdsTag link href="#">카테고리</KrdsTag>
      <KrdsTag link href="https://example.com" target="_blank" rel="noopener">외부 링크</KrdsTag>
      <KrdsTag link href="#">필터 태그</KrdsTag>
    </KrdsTagGroup>

    <KrdsTagGroup size="small">
      <KrdsTag link href="#">카테고리</KrdsTag>
      <KrdsTag link href="https://example.com" target="_blank" rel="noopener">외부 링크</KrdsTag>
      <KrdsTag link href="#">필터 태그</KrdsTag>
    </KrdsTagGroup>
  </div>
</template>
```

## 슬롯 사용

`remove` 이벤트에서 목록을 갱신해 태그를 삭제합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsTag, KrdsTagGroup } from '@krds.ui/vue'

  const tags = ref(['커스텀 내용 1', '커스텀 내용 2'])

  const handleRemove = (tag: string) => {
    tags.value = tags.value.filter(t => t !== tag)
  }
</script>

<template>
  <KrdsTagGroup size="medium">
    <KrdsTag v-for="tag in tags" :key="tag" @remove="handleRemove(tag)">{{ tag }}</KrdsTag>
    <KrdsTag link href="#">링크 태그</KrdsTag>
  </KrdsTagGroup>
</template>
```

## API

## KrdsTag

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| link | boolean | false | 링크 태그 여부 |
| href | string | '#' | 링크 URL (link가 true일 때 사용) |
| target | string | - | 링크 타겟 (link가 true일 때 사용) |
| rel | string | - | 링크 관계 (link가 true일 때 사용) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| remove | [event: MouseEvent] | 삭제 버튼을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 태그 글자 |

## KrdsTagGroup

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| size | KrdsTagGroupSize ('small' \| 'medium' \| 'large') | 'medium' | 태그 그룹 크기 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 태그 (KrdsTag) |

---

# 토글 스위치 Toggle switch

토글은 상호 배타적인 두 가지 상태를 전환하는 데 사용되는 요소이다.

## 기본

`v-model`로 켜짐 상태(`boolean`)를 연결하고, `label`로 스위치 이름을 표시합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsToggleSwitch } from '@krds.ui/vue'

  const checked = ref(false)
</script>

<template>
  <div>
    <KrdsToggleSwitch v-model="checked" label="switch : default" />
    <p style="margin-top: 1rem">현재 상태: {{ checked ? '켜짐' : '꺼짐' }}</p>
  </div>
</template>
```

## 크기

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsToggleSwitch } from '@krds.ui/vue'

  const mediumChecked = ref(false)
  const largeChecked = ref(false)
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 1.5rem">
    <KrdsToggleSwitch v-model="mediumChecked" size="medium" label="Medium 크기 스위치 (기본)" />
    <KrdsToggleSwitch v-model="largeChecked" size="large" label="Large 크기 스위치" />
  </div>
</template>
```

## API

## KrdsToggleSwitch

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| label | string | - | 스위치 라벨 |
| id | string | - | HTML ID |
| required | boolean | false | 필수 입력 여부 |
| modelValue | boolean | false | 모델 값 |
| size | "medium" \| "large" | 'medium' | 크기 |
| disabled | boolean | false | 비활성화 여부 |
| readonly | boolean | false | 읽기 전용 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [value: boolean] | 켜거나 껐을 때 |
| update:modelValue | [value: boolean] | 켜짐 상태가 바뀔 때 (v-model) |

---

# 단계 표시기 Step indicator

단계 표시기는 서비스 이용을 위해 사용자가 거쳐야 하는 일련의 단계를 시각화하여 표현한 것으로 진행 상태에 대한 피드백을 사용자에게 전달한다.

## 기본

`modelValue`에 현재 단계의 인덱스(0부터 시작)를 지정합니다. 그보다 앞의 단계는 완료(`done`), 뒤의 단계는 대기(`pending`) 상태로 표시됩니다. 단계 표시기는 진행 상태만 보여 주므로(단계를 눌러 이동하지 않음), 이전/다음 버튼 등에서 `modelValue`를 바꿔 단계를 옮깁니다. API 표의 `update:modelValue` 이벤트는 기존 코드 호환용으로 남아 있으며 보내지 않습니다.

```vue
<script setup lang="ts">
  import { KrdsStep, KrdsStepIndicator } from '@krds.ui/vue'
</script>

<template>
  <KrdsStepIndicator :model-value="3">
    <KrdsStep step="1단계" title="단계 레이블" />
    <KrdsStep step="2단계" title="단계 레이블" />
    <KrdsStep step="3단계" title="단계 레이블" />
    <KrdsStep step="4단계" title="단계 레이블" />
    <KrdsStep step="5단계" title="단계 레이블" />
  </KrdsStepIndicator>
</template>
```

## 상태 지정

`KrdsStep`의 `status`로 단계의 상태를 직접 지정합니다. `status`는 `modelValue`로 계산한 상태보다 우선합니다.

```vue
<script setup lang="ts">
  import { KrdsStep, KrdsStepIndicator } from '@krds.ui/vue'
</script>

<template>
  <KrdsStepIndicator>
    <KrdsStep step="1단계" title="약관 동의" status="done" />
    <KrdsStep step="2단계" title="정보 입력" status="active" />
    <KrdsStep step="3단계" title="신청 완료" status="pending" />
  </KrdsStepIndicator>
</template>
```

## 페이지 타이틀과 함께

```vue
<script setup lang="ts">
  import { KrdsStep, KrdsStepIndicator } from '@krds.ui/vue'
</script>

<template>
  <div class="page-title-wrap between">
    <h2 class="h-tit">타이틀</h2>
    <KrdsStepIndicator :model-value="2">
      <KrdsStep step="1단계" title="유의 사항 확인" />
      <KrdsStep step="2단계" title="신청인 정보" />
      <KrdsStep step="3단계" title="이사 전 살던 곳" />
      <KrdsStep step="4단계" title="이사 온 곳" />
    </KrdsStepIndicator>
  </div>
</template>
```

## API

## KrdsStepIndicator

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| modelValue | number | 0 | 현재 단계 인덱스 (0부터 시작). 앞 단계는 완료, 뒤 단계는 대기로 표시 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: number] | 보내지 않음: 단계 표시기는 진행 상태만 보여 주므로 v-model 값이 바뀌지 않습니다 (기존 코드 호환용, 다음 주요 버전에서 제거) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 단계 (KrdsStep) |

## KrdsStep

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| status | "done" \| "active" \| "pending" | - | 단계 상태 (지정하지 않으면 KrdsStepIndicator가 순서에 따라 정함) |
| title (필수) | string | - | 단계 제목 |
| step (필수) | string \| number | - | 단계 번호 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent, step: string \| number] | 단계를 클릭했을 때 (단계 번호) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 단계 제목 아래 추가 내용 |

---

# 스피너 Spinner

스피너는 화면이나 요소의 다양한 처리 상태를 시각적으로 표시한 것으로 화면 전체나 일부 요소에 접근하기 위해 일정 시간 동안 대기해야 함을 사용자에게 안내한다.

## 기본

스피너는 부모 요소의 너비와 높이를 채우고 가운데에 표시됩니다. `role="status"`와 화면 낭독기용 "로딩 중" 텍스트가 함께 렌더링됩니다.

```vue
<script setup lang="ts">
  import { KrdsSpinner } from '@krds.ui/vue'
</script>

<template>
  <div style="position: relative; height: 200px">
    <KrdsSpinner />
  </div>
</template>
```

## 라벨 포함

`label`로 스피너 옆에 안내 텍스트를 표시합니다.

```vue
<script setup lang="ts">
  import { KrdsSpinner } from '@krds.ui/vue'
</script>

<template>
  <div style="position: relative; height: 200px">
    <KrdsSpinner label="Loading data.." />
  </div>
</template>
```

## 입력 필드 로딩

입력 필드와 스피너를 `.form-spinner`로 감싸면 스피너가 입력 필드 오른쪽 안에 표시됩니다. `KrdsInput`의 `loading`을 지정해도 같은 구조로 렌더링됩니다.

```vue
<script setup lang="ts">
  import { KrdsSpinner } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 2rem">
    <div class="form-group">
      <div class="form-tit">
        <label for="loading_example1">Label</label>
      </div>
      <div class="form-conts">
        <div class="form-spinner">
          <input id="loading_example1" type="text" class="krds-input" placeholder="placeholder" />
          <KrdsSpinner />
        </div>
      </div>
    </div>

    <div class="form-group">
      <div class="form-tit">
        <label for="loading_example2">검증 중</label>
      </div>
      <div class="form-conts">
        <div class="form-spinner">
          <input id="loading_example2" type="text" class="krds-input" value="입력된 값" placeholder="placeholder" />
          <KrdsSpinner />
        </div>
      </div>
    </div>
  </div>
</template>
```

## API

## KrdsSpinner

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| label | string | - | 로딩 안내 텍스트 |

---

# 패널 Panel

패널은 본문 콘텐츠의 섹션이나 일부 요소에 대한 개념/용어 설명, 옵션의 구성, 이용 방법 등과 관련된 정보나 도움말, 따라하기 콘텐츠를 제공하는 사이드 패널이다.

## 기본

`v-model`로 펼침 상태를 제어합니다. 도움말 버튼과 패널이 화면 오른쪽에 고정(`position: fixed`)되므로 예제를 별도 화면(iframe)에 띄웁니다. 예제는 1024px 폭 화면을 축소해 보여 줍니다. 1024px 미만 화면에서는 패널이 화면 폭에서 3rem을 뺀 너비로 열리고 뒤 배경이 어두워집니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsPanel } from '@krds.ui/vue'

  const open = ref(false)
</script>

<template>
  <KrdsPanel v-model="open"></KrdsPanel>
</template>
```

## 도움 패널

기본 슬롯에 `KrdsTabs`를 넣어 도움 탭과 따라하기 탭을 구성합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsPanel, KrdsTabs } from '@krds.ui/vue'

  const open = ref(false)
  const tabs = [
    { id: 'help', label: '도움' },
    { id: 'tutorial', label: '따라하기' }
  ]
</script>

<template>
  <KrdsPanel v-model="open">
    <KrdsTabs :tabs="tabs">
      <template #help>
        <h3 class="sr-only">도움</h3>
        <div class="help-conts-area-inner">
          <!-- 도움말 -->
          <div class="conts-area help-conts">
            <div class="conts-wrap">
              <h4 class="help-title">
                전자문서지갑
                <span class="krds-btn medium icon">
                  <span class="sr-only">도움말</span>
                  <i class="svg-icon ico-help"></i>
                </span>
              </h4>
              <div class="conts-desc">
                <p>
                  전자문서지갑에서는 전자증명서 출력기능을 제공하지 않으며, 스마트폰 화면을 캡쳐하여 사용할 수 없습니다. 다만, 발급받은
                  전자증명서를 열람용으로 다운로드할 수는 있습니다.
                </p>
              </div>
              <ul class="link-list">
                <li>
                  <a href="#" target="_blank" title="새 창 열림" class="krds-btn xsmall link basic">
                    안드로이드 애플리케이션 다운로드
                    <i class="svg-icon ico-go"></i>
                  </a>
                </li>
                <li>
                  <a href="#" target="_blank" title="새 창 열림" class="krds-btn xsmall link basic">
                    iOS애플리케이션 다운로드
                    <i class="svg-icon ico-go"></i>
                  </a>
                </li>
              </ul>
            </div>
          </div>
          <div class="conts-area related-service">
            <div class="conts-wrap">
              <h4 class="help-title">관련서비스/민원</h4>
              <ul class="link-list">
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    영문 주민등록표등본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    영문 주민등록표초본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    주민등록표등본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
              </ul>
            </div>
            <div class="conts-wrap">
              <h4 class="help-title">기타 문의/도움말</h4>
              <ul class="link-list">
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    <i class="svg-icon ico-call"></i>
                    민원신청 관련 문의 전화 번호 찾기
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    <i class="svg-icon ico-faq"></i>
                    자주 묻는 질문 확인하기
                  </a>
                </li>
              </ul>
            </div>
          </div>
        </div>
      </template>
      <template #tutorial>
        <h3 class="sr-only">따라하기</h3>
        <div class="help-conts-area-inner">
          <div class="conts-area">
            <h4 class="help-title">
              <a href="#" title="이전으로 돌아가기"> 이사 전 살던 곳 정보 입력하기 </a>
            </h4>
            <ul class="coach-help-process">
              <li>
                <h4 class="tit current">Task 1: 이사 전에 살던 곳 주소 확인</h4>
                <div class="krds-disclosure conts-expand-area">
                  <button type="button" class="btn-conts-expand">전체 2단계</button>
                  <div class="expand-wrap">
                    <div class="expand-in">
                      <ul class="krds-info-list decimal">
                        <li>단계1 : 주소조회</li>
                        <li>단계2 : 조회 결과 확인</li>
                      </ul>
                    </div>
                  </div>
                </div>
              </li>
              <li>
                <h4 class="tit">Task 2: 이사 갈 가족 구성원 선택하기</h4>
                <div class="krds-disclosure conts-expand-area">
                  <button type="button" class="btn-conts-expand">전체 1단계</button>
                  <div class="expand-wrap">
                    <div class="expand-in">
                      <ul class="krds-info-list decimal">
                        <li>단계1 : 주소조회</li>
                      </ul>
                    </div>
                  </div>
                </div>
              </li>
            </ul>
          </div>
          <div class="help-panel-action">
            <button type="button" class="krds-btn medium secondary coach-btn-stop">그만 따라하기</button>
          </div>
        </div>
      </template>
    </KrdsTabs>
  </KrdsPanel>
</template>
```

## 따라하기 패널

`KrdsTabs`의 `v-model`을 `tutorial`로 지정해 따라하기 탭이 먼저 보이게 합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsPanel, KrdsTabs } from '@krds.ui/vue'

  const open = ref(false)
  const activeTab = ref('tutorial')
  const tabs = [
    { id: 'help', label: '도움' },
    { id: 'tutorial', label: '따라하기' }
  ]
</script>

<template>
  <KrdsPanel v-model="open">
    <KrdsTabs v-model="activeTab" :tabs="tabs">
      <template #help>
        <h3 class="sr-only">도움</h3>
        <div class="help-conts-area-inner">
          <!-- 도움말 -->
          <div class="conts-area help-conts">
            <div class="conts-wrap">
              <h4 class="help-title">
                전자문서지갑
                <span class="krds-btn medium icon">
                  <span class="sr-only">도움말</span>
                  <i class="svg-icon ico-help"></i>
                </span>
              </h4>
              <div class="conts-desc">
                <p>
                  전자문서지갑에서는 전자증명서 출력기능을 제공하지 않으며, 스마트폰 화면을 캡쳐하여 사용할 수 없습니다. 다만, 발급받은
                  전자증명서를 열람용으로 다운로드할 수는 있습니다.
                </p>
              </div>
              <ul class="link-list">
                <li>
                  <a href="#" target="_blank" title="새 창 열림" class="krds-btn xsmall link basic">
                    안드로이드 애플리케이션 다운로드
                    <i class="svg-icon ico-go"></i>
                  </a>
                </li>
                <li>
                  <a href="#" target="_blank" title="새 창 열림" class="krds-btn xsmall link basic">
                    iOS애플리케이션 다운로드
                    <i class="svg-icon ico-go"></i>
                  </a>
                </li>
              </ul>
            </div>
          </div>
          <div class="conts-area related-service">
            <div class="conts-wrap">
              <h4 class="help-title">관련서비스/민원</h4>
              <ul class="link-list">
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    영문 주민등록표등본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    영문 주민등록표초본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    주민등록표등본
                    <i class="svg-icon ico-angle right"></i>
                  </a>
                </li>
              </ul>
            </div>
            <div class="conts-wrap">
              <h4 class="help-title">기타 문의/도움말</h4>
              <ul class="link-list">
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    <i class="svg-icon ico-call"></i>
                    민원신청 관련 문의 전화 번호 찾기
                  </a>
                </li>
                <li>
                  <a href="#" class="krds-btn xsmall link basic">
                    <i class="svg-icon ico-faq"></i>
                    자주 묻는 질문 확인하기
                  </a>
                </li>
              </ul>
            </div>
          </div>
        </div>
      </template>
      <template #tutorial>
        <h3 class="sr-only">따라하기</h3>
        <div class="help-conts-area-inner">
          <div class="conts-area">
            <h4 class="help-title">
              <a href="#" title="이전으로 돌아가기"> 이사 전 살던 곳 정보 입력하기 </a>
            </h4>
            <ul class="coach-help-process">
              <li>
                <h4 class="tit current">Task 1: 이사 전에 살던 곳 주소 확인</h4>
                <div class="krds-disclosure conts-expand-area">
                  <button type="button" class="btn-conts-expand">전체 2단계</button>
                  <div class="expand-wrap">
                    <div class="expand-in">
                      <ul class="krds-info-list decimal">
                        <li>단계1 : 주소조회</li>
                        <li>단계2 : 조회 결과 확인</li>
                      </ul>
                    </div>
                  </div>
                </div>
              </li>
              <li>
                <h4 class="tit">Task 2: 이사 갈 가족 구성원 선택하기</h4>
                <div class="krds-disclosure conts-expand-area">
                  <button type="button" class="btn-conts-expand">전체 1단계</button>
                  <div class="expand-wrap">
                    <div class="expand-in">
                      <ul class="krds-info-list decimal">
                        <li>단계1 : 주소조회</li>
                      </ul>
                    </div>
                  </div>
                </div>
              </li>
            </ul>
          </div>
          <div class="help-panel-action">
            <button type="button" class="krds-btn medium secondary coach-btn-stop">그만 따라하기</button>
          </div>
        </div>
      </template>
    </KrdsTabs>
  </KrdsPanel>
</template>
```

## API

## KrdsPanel

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| modelValue | boolean | false | 도움말 패널 펼침 상태 (v-model) |
| headerTopSelector | string | '#krds-masthead' | 헤더 상단 영역 선택자 (기본값: '#krds-masthead', KrdsInPageNavigation과 같음) |
| headerInnerSelector | string | '#krds-header .header-in' | 헤더 내부 영역 선택자 (기본값: '#krds-header .header-in', KrdsInPageNavigation과 같음) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [value: boolean] | 도움 패널을 펼치거나 접을 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 도움 패널 내용 |

## KrdsTabs

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| variant | KrdsTabsVariant ('line' \| 'fill') | 'line' | 탭 스타일 변형 |
| modelValue | string | - | 활성 탭 id (v-model) |
| full | boolean | false | 풀사이즈 레이아웃 여부 |
| selectedText | string | '선택됨' | 선택된 탭의 스크린 리더 대체 텍스트 |
| tabs (필수) | KrdsTabItem[] | - | 탭 아이템 목록 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [id: string] | 탭을 바꿨을 때 (탭 id) |
| update:modelValue | [id: string] | 선택한 탭 id가 바뀔 때 (v-model) |

---

# 맥락적 도움말 Contextual help

컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움 아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.

## 기본

아이콘 버튼을 누르면 도움말이 열리고 그 안의 첫 번째 링크나 버튼으로 포커스가 이동합니다. 닫기 버튼, Esc 키, 바깥 클릭으로 닫고, 닫기 버튼과 Esc 키로 닫으면 포커스가 아이콘 버튼으로 돌아옵니다. 도움말은 제목으로 이름 붙인 대화 상자(`role="dialog"`)라 화면낭독기가 제목과 함께 읽습니다.

```vue
<script setup lang="ts">
  import { KrdsContextualHelp } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; justify-content: center; align-items: center; height: 500px">
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(상단 왼쪽)</p>
      <KrdsContextualHelp>
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
  </div>
</template>
```

## 위치

`position`으로 도움말이 열리는 위치를 지정합니다. 기본값은 `top left`입니다.

```vue
<script setup lang="ts">
  import { KrdsContextualHelp } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; justify-content: center; align-items: center; height: 800px">
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(상단 왼쪽)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(상단 중앙)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" position="top center">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(상단 오른쪽)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" position="top right">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(하단 왼쪽)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" position="bottom left">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(하단 중앙)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" position="bottom center">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(하단 오른쪽)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" position="bottom right">
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
  </div>
</template>
```

## 도움말 아이콘

`help-icon`을 지정하면 정보 아이콘 대신 도움(물음표) 아이콘을 표시합니다.

```vue
<script setup lang="ts">
  import { KrdsContextualHelp } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; justify-content: center; align-items: center; height: 500px">
    <div style="display: flex; align-items: center; gap: 8px">
      <p>예시이미지(상단 왼쪽)</p>
      <KrdsContextualHelp tooltip-title="도움말 제목" help-icon>
        <p>
          컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움
          아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
        </p>
        <div class="btn-wrap">
          <a href="#;" class="krds-btn xsmall link basic">바로가기 <i class="svg-icon ico-angle right"></i></a>
        </div>
      </KrdsContextualHelp>
    </div>
  </div>
</template>
```

## API

## KrdsContextualHelp

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| tooltipTitle | string | '도움말 제목' | 툴팁 제목 |
| helpIcon | boolean | false | 도움말 아이콘 사용 여부 (false 면 툴팁 아이콘) |
| position | ContextualHelpPosition ('top left' \| 'top center' \| 'top right' \| 'bottom left' \| 'bottom center' \| 'bottom right') | 'top left' | 툴팁 노출 위치 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 도움말 내용 |

---

# 코치마크 Coach mark

코치마크는 사용자에게 새로 도입된 기능을 안내하거나, 여러 단계를 거쳐 수행해야 하는 복잡한 과업을 사용자가 보다 쉽게 완료할 수 있도록 세부 수행 단계별로 고맥락적 도움말을 제공하는 컴포넌트이다.

## 기본

단계마다 `KrdsCoachMark`를 두고 같은 `v-model`을 연결합니다. `v-model` 값이 `active-step`과 같은 코치마크에만 말풍선이 표시되며, 다음으로·이전으로 버튼이 `v-model`을 바꾸고 그만보기 버튼은 `close` 이벤트를 보냅니다. 말풍선은 대상 요소 위쪽에 표시되므로 위에 여백을 둡니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsCoachMark, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'

  const currentStep = ref<number | null>(null)
  const stepsData = [
    { id: 1, title: '첫번째 단계', description: '첫번째 단계의 내용임' },
    { id: 2, title: '두번째 단계', description: '두번째 단계의 내용임' },
    { id: 3, title: '세번째 단계', description: '세번째 단계의 내용임' }
  ]
</script>

<template>
  <KrdsButton variant="tertiary" size="xsmall" @click="currentStep = 1">코치마크 보기</KrdsButton>
  <div style="display: flex; flex-direction: column; gap: 40px; padding: 150px 40px 40px">
    <KrdsCoachMark
      v-model="currentStep"
      :active-step="1"
      :steps-data="stepsData"
      :coach-mark-class="[currentStep === 1 ? 'txt-box' : '']"
      style="max-width: 500px"
      @close="currentStep = null"
    >
      <template #coach-mark-content>
        <div style="display: flex; flex-direction: column; gap: 20px">
          <h3>1. 이전 살던 곳 작성</h3>
          <div style="display: flex; flex-direction: column; gap: 8px">
            <KrdsFormLabel for="coach-prev-address">이전 살던 곳</KrdsFormLabel>
            <div style="display: flex; gap: 8px">
              <KrdsInput id="coach-prev-address" style="width: 100%" />
              <KrdsButton variant="secondary">주소 조회</KrdsButton>
            </div>
          </div>
        </div>
      </template>
    </KrdsCoachMark>
    <div style="border-top: 1px solid lightgray" />
    <KrdsCoachMark
      v-model="currentStep"
      :active-step="2"
      :steps-data="stepsData"
      style="max-width: 500px"
      :coach-mark-class="[currentStep === 2 ? 'txt-box' : '']"
      @close="currentStep = null"
    >
      <template #coach-mark-content>
        <div style="display: flex; flex-direction: column; gap: 20px">
          <h3>2. 현재 사는 곳 작성</h3>
          <div style="display: flex; flex-direction: column; gap: 8px">
            <KrdsFormLabel for="coach-current-address">현재 사는 곳</KrdsFormLabel>
            <div style="display: flex; gap: 8px">
              <KrdsInput id="coach-current-address" style="width: 100%" />
              <KrdsButton variant="secondary">주소 조회</KrdsButton>
            </div>
          </div>
        </div>
      </template>
    </KrdsCoachMark>
    <div style="border-top: 1px solid lightgray" />
    <KrdsCoachMark
      v-model="currentStep"
      :active-step="3"
      :steps-data="stepsData"
      style="display: flex; justify-content: flex-end"
      @close="currentStep = null"
    >
      <template #coach-mark-content>
        <KrdsButton :class="[currentStep === 3 ? 'coach-btn' : '']">주소 이전 신청 완료</KrdsButton>
      </template>
    </KrdsCoachMark>
  </div>
</template>
```

## API

## KrdsCoachMark

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| style | string \| Record<string, string \| number> | - | 인라인 스타일 |
| modelValue | number \| null | null | 현재 노출 중인 단계 (v-model) |
| coachMarkClass | string \| string[] | '' | 코치마크 래퍼에 추가할 클래스 |
| stepsData (필수) | StepsData[] | - | 전체 단계 데이터 |
| activeStep (필수) | number | - | 이 코치마크가 담당하는 단계 번호 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| close | [] | 닫기 버튼으로 닫을 때 |
| update:modelValue | [value: number \| null] | 이전·다음 버튼으로 단계가 바뀔 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| coach-mark-content | 코치마크 말풍선 아래에 함께 보여 줄 내용 |

---

# 툴팁 Tooltip

툴팁은 요소나 본문 텍스트에 제공되는 짧은 부가 설명이다. 설명이 필요한 대상 또는 별도의 활성화 버튼에 마우스를 올리거나 초점을 이동했을 때 설명 텍스트가 표시된다.

## 기본

`type`으로 트리거 버튼 모양(`default`, `icon`, `button`)을 정합니다. 툴팁은 버튼 옆에 표시되고 Esc 키나 창 스크롤로 닫힙니다.

```vue
<script setup lang="ts">
  import { KrdsTooltip } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; align-items: flex-start; gap: 10px">
    <KrdsTooltip tooltip-content="툴팁의 기본 설정입니다"> tooltip-horizontal <i class="svg-icon ico-angle right"></i> </KrdsTooltip>
    <KrdsTooltip type="icon" tooltip-content="아이콘 버튼에 제공되는 툴팁">
      <span class="sr-only">도움말</span>
      <i class="svg-icon ico-help"></i>
    </KrdsTooltip>
    <KrdsTooltip type="button" tooltip-content="버튼에 제공되는 툴팁"> 도움말 </KrdsTooltip>
  </div>
</template>
```

## 세로 배치 (vertical)

`vertical`을 지정하면 툴팁이 버튼 위나 아래에 표시됩니다.

```vue
<script setup lang="ts">
  import { KrdsTooltip } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; align-items: flex-start; gap: 10px">
    <KrdsTooltip vertical tooltip-content="툴팁의 기본 설정입니다">
      tooltip-horizontal <i class="svg-icon ico-angle right"></i>
    </KrdsTooltip>
    <KrdsTooltip vertical type="icon" tooltip-content="아이콘 버튼에 제공되는 툴팁">
      <span class="sr-only">도움말</span>
      <i class="svg-icon ico-help"></i>
    </KrdsTooltip>
    <KrdsTooltip vertical type="button" tooltip-content="버튼에 제공되는 툴팁"> 도움말 </KrdsTooltip>
  </div>
</template>
```

## 박스형 (box)

`box`를 지정하면 여러 줄 설명에 맞는 박스형 툴팁이 버튼 위나 아래에 표시됩니다.

```vue
<script setup lang="ts">
  import { KrdsTooltip } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; align-items: flex-start; gap: 10px">
    <KrdsTooltip box tooltip-content="툴팁의 기본 설정입니다"> tooltip-horizontal <i class="svg-icon ico-angle right"></i> </KrdsTooltip>
    <KrdsTooltip box type="icon" tooltip-content="아이콘 버튼에 제공되는 툴팁">
      <span class="sr-only">도움말</span>
      <i class="svg-icon ico-help"></i>
    </KrdsTooltip>
    <KrdsTooltip box type="button" tooltip-content="버튼에 제공되는 툴팁"> 도움말 </KrdsTooltip>
  </div>
</template>
```

## API

## KrdsTooltip

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| type | TooltipType ('default' \| 'icon' \| 'button') | 'default' | 트리거 버튼 타입 |
| disabled | boolean | false | 비활성화 여부 |
| vertical | boolean | false | 세로 방향 배치 여부 |
| box | boolean | false | 박스형 여부 |
| tooltipContent (필수) | string | - | 툴팁 본문 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 툴팁을 여는 버튼 내용 |

---

# 음성 지원 TTS

TTS(Text-to-Speech)는 텍스트를 음성으로 변환하여 읽어주는 기능을 제공하는 버튼 컴포넌트이다. Web Speech API를 사용하며, 볼륨 아이콘과 재생 아이콘 두 가지 타입을 지원한다.

## 기본

버튼을 누르면 `text`를 한국어(`ko-KR`)로 읽고, 읽는 동안 정지 아이콘으로 바뀌어 다시 누르면 멈춥니다.

```vue
<script setup lang="ts">
  import { KrdsTts } from '@krds.ui/vue'
</script>

<template>
  <KrdsTts
    text="대한민국 정부 디자인 시스템 KRDS는 정부 서비스의 일관된 사용자 경험을 제공합니다."
    label="듣기"
    size="medium"
    icon="volume"
  />
</template>
```

## 아이콘만

`label`이 없으면 아이콘만 표시되므로 `aria-label`로 버튼 이름을 제공합니다.

```vue
<script setup lang="ts">
  import { KrdsTts } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center">
    <KrdsTts text="볼륨 아이콘 타입입니다." icon="volume" aria-label="듣기" />
    <KrdsTts text="재생 아이콘 타입입니다." icon="play" aria-label="듣기" />
  </div>
</template>
```

## 크기

```vue
<script setup lang="ts">
  import { KrdsTts } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 1.5rem">
    <div style="display: flex; gap: 1rem; align-items: center">
      <KrdsTts text="xsmall 크기입니다." label="듣기" size="xsmall" />
      <KrdsTts text="small 크기입니다." label="듣기" size="small" />
      <KrdsTts text="medium 크기입니다." label="듣기" size="medium" />
    </div>
    <div style="display: flex; gap: 1rem; align-items: center">
      <KrdsTts text="xsmall 크기입니다." size="xsmall" aria-label="듣기" />
      <KrdsTts text="small 크기입니다." size="small" aria-label="듣기" />
      <KrdsTts text="medium 크기입니다." size="medium" aria-label="듣기" />
    </div>
  </div>
</template>
```

## 아이콘 타입

```vue
<script setup lang="ts">
  import { KrdsTts } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center">
    <KrdsTts text="볼륨 아이콘 타입입니다." label="듣기" icon="volume" />
    <KrdsTts text="재생 아이콘 타입입니다." label="듣기" icon="play" />
  </div>
</template>
```

## 비활성화

```vue
<script setup lang="ts">
  import { KrdsTts } from '@krds.ui/vue'
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center">
    <KrdsTts text="비활성화 상태입니다." label="듣기" disabled />
    <KrdsTts text="비활성화 상태입니다." aria-label="듣기" disabled />
    <KrdsTts text="비활성화 상태입니다." label="듣기" icon="play" disabled />
  </div>
</template>
```

## API

## KrdsTts

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| label | string | - | 레이블 텍스트 (미지정 시 아이콘만 표시) |
| size | TtsSize ('xsmall' \| 'small' \| 'medium') | 'medium' | 버튼 크기 |
| disabled | boolean | false | 비활성화 여부 |
| icon | TtsIcon ('volume' \| 'play') | 'volume' | 아이콘 타입 |
| text (필수) | string | - | 읽어줄 텍스트 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| error | [error: Error] | 음성 합성을 지원하지 않거나 읽기에 실패했을 때 |
| pause | [] | 일시 정지했을 때 |
| play | [text: string] | 읽기를 시작했을 때 (읽는 문장) |
| end | [] | 읽기가 끝났을 때 |

---

# 날짜 입력 필드 Date input

날짜 입력 필드는 사용자가 특정 날짜 또는 기간을 입력하거나 선택하는 데 사용되는 요소이다.

## 기본

달력 버튼을 누르면 달력이 열리고 초점이 달력으로 이동합니다. 원본 KRDS처럼 입력 필드 위쪽에 여는 것이 기본이고, 화면에서 위쪽 공간이 달력 높이보다 좁고 아래쪽이 더 넓으면 아래쪽에 엽니다. 날짜를 고른 뒤 **확인**을 누르면 `YYYY.MM.DD` 형식으로 입력되고, 두 날짜를 차례로 고르면 `YYYY.MM.DD ~ YYYY.MM.DD` 기간으로 입력됩니다. <kbd>Esc</kbd>나 **취소**, 달력 바깥 클릭으로 닫힙니다. <kbd>Esc</kbd>·**취소**·**확인**으로 닫으면 초점이 달력 버튼으로 돌아오고, 바깥을 누르면 누른 곳으로 간 초점을 그대로 둡니다. 연·월 목록을 <kbd>Esc</kbd>로 닫으면 초점이 연·월 버튼으로 돌아옵니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormHint, KrdsFormLabel } from '@krds.ui/vue'

  const dateValue = ref('')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="date-input">날짜 선택</KrdsFormLabel>
    <KrdsDateInput id="date-input" v-model="dateValue" placeholder="YYYY.MM.DD" />
    <KrdsFormHint>도움말</KrdsFormHint>
  </KrdsFormGroup>
</template>
```

## 비활성화

입력과 달력 열기가 모두 막힙니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormLabel } from '@krds.ui/vue'

  const dateValue = ref('2025.03.10')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="date-input-disabled">날짜 선택</KrdsFormLabel>
    <KrdsDateInput id="date-input-disabled" v-model="dateValue" disabled />
  </KrdsFormGroup>
</template>
```

## 읽기 전용

직접 입력은 막히지만 달력 버튼은 그대로 사용할 수 있습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormLabel } from '@krds.ui/vue'

  const dateValue = ref('2025.03.10')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="date-input-readonly">날짜 선택</KrdsFormLabel>
    <KrdsDateInput id="date-input-readonly" v-model="dateValue" readonly />
  </KrdsFormGroup>
</template>
```

## 일정·휴일 표시

`initialYear`·`initialMonth`로 달력을 처음 열 때 보여 줄 달을 정합니다. `holidays`의 날짜는 일요일처럼 휴일로, `eventDates`의 날짜는 일정이 있는 날로 표시됩니다. 날짜는 `YYYY.MM.DD` 형식으로 지정합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormLabel } from '@krds.ui/vue'

  const dateValue = ref('')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="date-input-events">날짜 선택</KrdsFormLabel>
    <KrdsDateInput
      id="date-input-events"
      v-model="dateValue"
      :initial-year="2025"
      :initial-month="5"
      :holidays="['2025.05.05', '2025.05.06']"
      :event-dates="['2025.05.15']"
    />
  </KrdsFormGroup>
</template>
```

## 여러 개 배치

달력을 열면 열려 있던 다른 달력은 닫힙니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormLabel } from '@krds.ui/vue'

  const start = ref('')
  const end = ref('')
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="date-input-start">시작일</KrdsFormLabel>
      <KrdsDateInput id="date-input-start" v-model="start" />
    </KrdsFormGroup>
    <KrdsFormGroup>
      <KrdsFormLabel for="date-input-end">종료일</KrdsFormLabel>
      <KrdsDateInput id="date-input-end" v-model="end" />
    </KrdsFormGroup>
  </div>
</template>
```

## body에 렌더 (teleport)

달력은 원본 KRDS처럼 입력 필드 바로 뒤에 렌더되므로, `overflow`로 잘리는 컨테이너(스크롤 영역, 표 등) 안에서는 달력이 잘립니다. `teleport`를 지정하면 달력을 `body`에 렌더하고 입력 필드 자리에 맞춰 위치를 잡으며, 스크롤·화면 크기가 바뀌면 위치를 다시 계산합니다.

- 달력이 문서 끝에 렌더되므로 달력 안에서 <kbd>Tab</kbd>으로 빠져나가면 입력 필드 다음 요소가 아니라 문서 끝으로 이동합니다.
- 모달(`KrdsModal`) 안에서는 쓰지 마세요. 모달은 `aria-modal`이라 모달 밖으로 렌더된 달력에 스크린리더가 접근할 수 없고, 달력이 모달 아래에 깔립니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsDateInput, KrdsFormGroup, KrdsFormLabel } from '@krds.ui/vue'

  const dateValue = ref('')
</script>

<template>
  <div style="height: 120px; overflow: auto; padding: 1.6rem; border: 1px dashed #b1b8be">
    <KrdsFormGroup>
      <KrdsFormLabel for="date-input-teleport">날짜 선택</KrdsFormLabel>
      <KrdsDateInput id="date-input-teleport" v-model="dateValue" teleport />
    </KrdsFormGroup>
  </div>
</template>
```

## API

## KrdsDateInput

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| id | string | - | HTML ID |
| required | boolean | false | 필수 입력 여부 |
| modelValue | string | - | 선택된 날짜 값 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | 'medium' | 입력 크기 |
| disabled | boolean | false | 비활성화 여부 |
| placeholder | string | 'YYYY.MM.DD' | 플레이스홀더 |
| readonly | boolean | false | 읽기 전용 여부 |
| autofocus | boolean | false | 자동 포커스 |
| eventDates | string[] | [] | 일정이 있는 날짜 배열 (YYYY.MM.DD 형식) |
| holidays | string[] | [] | 휴일 날짜 배열 (YYYY.MM.DD 형식) |
| initialYear | number | - | 초기 표시 년도 (기본: 현재 년도) |
| initialMonth | number | - | 초기 표시 월 (기본: 현재 월) |
| teleport | boolean | false | 달력을 body에 렌더 (overflow로 잘리는 컨테이너 안에서 사용. 모달 안에서는 쓰지 않음) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| input | [event: Event] | 입력할 때 (네이티브 input) |
| blur | [event: FocusEvent] | 초점을 잃었을 때 |
| change | [event: Event] | 값이 확정됐을 때 (네이티브 change) |
| focus | [event: FocusEvent] | 초점을 받았을 때 |
| update:modelValue | [value: string] | 날짜를 입력하거나 달력에서 고를 때 (v-model) |

---

# 텍스트 영역 Textarea

텍스트 영역은 사용자가 키보드로 글자, 숫자, 기호 등이 조합된 여러 줄의 텍스트를 입력하는 경우에 사용하는 요소이다.

## 기본

입력한 글자 수가 오른쪽 아래에 표시됩니다(`showCount`, 기본값 `true`). `maxlength`를 지정하면 최대 글자 수도 함께 표시됩니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormLabel, KrdsTextarea } from '@krds.ui/vue'

  const content = ref('')
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="textarea1">레이블</KrdsFormLabel>
      <KrdsTextarea id="textarea1" v-model="content" placeholder="내용을 입력하세요" />
    </KrdsFormGroup>
  </div>
</template>
```

## API

## KrdsTextarea

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| resize | "none" \| "vertical" \| "both" \| "horizontal" | 'vertical' | 리사이즈 가능 여부 |
| id | string | - | HTML ID |
| required | boolean | false | 필수 입력 여부 |
| modelValue | string | '' | 입력값 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | - | 입력 크기 |
| disabled | boolean | false | 비활성화 여부 |
| rows | number | 4 | 행 수 |
| placeholder | string | - | 플레이스홀더 |
| readonly | boolean | false | 읽기 전용 여부 |
| autofocus | boolean | false | 자동 포커스 |
| maxlength | number | - | 최대 글자 수 |
| minlength | number | - | 최소 글자 수 |
| cols | number | - | 열 수 |
| showCount | boolean | true | 글자 수 표시 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| input | [event: Event] | 입력할 때 (네이티브 input) |
| blur | [event: FocusEvent] | 초점을 잃었을 때 |
| change | [event: Event] | 값이 확정됐을 때 (네이티브 change) |
| focus | [event: FocusEvent] | 초점을 받았을 때 |
| keydown | [event: KeyboardEvent] | 키를 눌렀을 때 |
| keyup | [event: KeyboardEvent] | 키를 뗐을 때 |
| update:modelValue | [value: string] | 입력값이 바뀔 때 (v-model) |

---

# 텍스트 입력 필드 Text input

텍스트 입력 필드는 사용자가 키보드로 글자, 숫자, 기호 등이 조합된 한 줄의 짧은 텍스트를 입력하는 경우에 사용하는 요소이다.

## 기본

`KrdsFormGroup`·`KrdsFormLabel`·`KrdsFormHint`와 함께 써서 레이블과 도움말을 붙입니다. `readonly`·`disabled`로 읽기 전용과 비활성화 상태를 만듭니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'

  const name = ref('')
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name" v-model="name" placeholder="플레이스홀더" />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name2">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name2" placeholder="플레이스홀더" model-value="readonly" readonly />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name3">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name3" placeholder="플레이스홀더" model-value="disabled" disabled />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## 상태

`state`를 `error`·`success`·`information`으로 지정하고 아래 `KrdsFormHint`의 `type`도 같은 값으로 맞춥니다. `error`일 때는 입력 필드 테두리도 에러 색으로 바뀝니다.

```vue
<script setup lang="ts">
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name21">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name21" placeholder="플레이스홀더" model-value="에러" state="error" />
      <KrdsFormHint type="error">에러 메시지</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name22">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name22" placeholder="플레이스홀더" model-value="성공" state="success" />
      <KrdsFormHint type="success">성공 메시지</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name23">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name23" placeholder="플레이스홀더" model-value="정보" state="information" />
      <KrdsFormHint type="information">정보 메시지</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## 사이즈

```vue
<script setup lang="ts">
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name31">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name31" placeholder="플레이스홀더" size="small" />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name32">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name32" placeholder="플레이스홀더" size="medium" />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="consult_name33">레이블</KrdsFormLabel>
      <KrdsInput id="consult_name33" placeholder="플레이스홀더" size="large" />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## 로딩

`loading`을 지정하면 입력 필드 안에 스피너가 표시됩니다. 이때 기본 슬롯(아이콘 버튼)은 렌더링되지 않습니다.

```vue
<script setup lang="ts">
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="loading_input">레이블</KrdsFormLabel>
      <KrdsInput id="loading_input" placeholder="플레이스홀더" loading />
      <KrdsFormHint>데이터를 불러오는 중입니다</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="loading_input2">레이블</KrdsFormLabel>
      <KrdsInput id="loading_input2" placeholder="플레이스홀더" model-value="입력된 값" loading />
      <KrdsFormHint>검증 중입니다</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## 아이콘 버튼

`icon`을 지정하고 기본 슬롯에 버튼을 넣으면 입력 필드 안쪽에 버튼이 배치됩니다. 보이는 텍스트가 없으므로 `sr-only` 텍스트로 버튼 이름을 제공합니다. 비밀번호 보기 전환이나 내용 삭제 같은 버튼 동작은 컴포넌트가 처리하지 않으므로 직접 구현합니다. 버튼이 여러 개면 `KrdsButtonGroup`으로 묶습니다 (KRDS `.btn-group`, 입력 필드 안 전용).

```vue
<script setup lang="ts">
  import { KrdsButton, KrdsButtonGroup, KrdsFormGroup, KrdsFormLabel, KrdsIcon, KrdsInput } from '@krds.ui/vue'
</script>

<template>
  <div class="fieldset">
    <!-- 패스워드 보기 버튼 (숨김) -->
    <KrdsFormGroup>
      <KrdsFormLabel for="login_pw">레이블</KrdsFormLabel>
      <KrdsInput id="login_pw" type="password" placeholder="8-12자의 영문자, 숫자, 특수문자 조합" model-value="1234567890" icon>
        <KrdsButton type="button" size="medium" icon>
          <span class="sr-only">입력한 비밀번호 보기</span>
          <KrdsIcon name="ico-pw-visible" />
        </KrdsButton>
      </KrdsInput>
    </KrdsFormGroup>

    <!-- 패스워드 보기 버튼 (보임) -->
    <KrdsFormGroup>
      <KrdsFormLabel for="login_pw2">레이블</KrdsFormLabel>
      <KrdsInput id="login_pw2" type="text" placeholder="8-12자의 영문자, 숫자, 특수문자 조합" model-value="1234567890" icon>
        <KrdsButton type="button" size="medium" icon>
          <span class="sr-only">입력한 비밀번호 가리기</span>
          <KrdsIcon name="ico-pw-visible-on" />
        </KrdsButton>
      </KrdsInput>
    </KrdsFormGroup>

    <!-- 삭제 버튼 -->
    <KrdsFormGroup>
      <KrdsFormLabel for="form_delete">레이블</KrdsFormLabel>
      <KrdsInput id="form_delete" placeholder="내용을 입력하세요" icon data-delete="true">
        <KrdsButton type="button" size="medium" icon pure class="btn-delete-input">
          <span class="sr-only">내용 삭제</span>
          <KrdsIcon name="ico-delete-fill" />
        </KrdsButton>
      </KrdsInput>
    </KrdsFormGroup>

    <!-- 다중 버튼 -->
    <KrdsFormGroup>
      <KrdsFormLabel for="form_btn_multiple">레이블</KrdsFormLabel>
      <KrdsInput
        id="form_btn_multiple"
        type="password"
        placeholder="8-12자의 영문자, 숫자, 특수문자 조합"
        model-value="1234567890"
        icon
        data-delete="true"
      >
        <KrdsButtonGroup>
          <KrdsButton type="button" size="medium" icon pure class="btn-delete-input">
            <span class="sr-only">내용 삭제</span>
            <KrdsIcon name="ico-delete-fill" />
          </KrdsButton>
          <KrdsButton type="button" size="medium" icon>
            <span class="sr-only">입력한 비밀번호 보기</span>
            <KrdsIcon name="ico-pw-visible" />
          </KrdsButton>
        </KrdsButtonGroup>
      </KrdsInput>
    </KrdsFormGroup>
  </div>
</template>
```

## API

## KrdsInput

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| id | string | - | HTML ID |
| type | InputType ('text' \| 'password' \| 'email' \| 'number' \| 'tel' \| 'url' \| 'search') | 'text' | 입력 타입 |
| required | boolean | false | 필수 입력 여부 |
| modelValue | string \| number | - | 입력값 |
| min | number | - | 최소값 (number 타입용) |
| max | number | - | 최대값 (number 타입용) |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | - | 입력 크기 |
| disabled | boolean | false | 비활성화 여부 |
| loading | boolean | false | 로딩 상태 |
| icon | boolean | false | 아이콘 (있을 때 btn-ico-wrap 클래스 적용) |
| placeholder | string | - | 플레이스홀더 |
| readonly | boolean | false | 읽기 전용 여부 |
| state | "default" \| "error" \| "success" \| "information" | 'default' | 입력 상태 |
| step | number | - | 단계값 (number 타입용) |
| autofocus | boolean | false | 자동 포커스 |
| maxlength | number | - | 최대 글자 수 |
| minlength | number | - | 최소 글자 수 |
| autocomplete | string | - | 자동완성 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| input | [event: Event] | 입력할 때 (네이티브 input) |
| blur | [event: FocusEvent] | 초점을 잃었을 때 |
| change | [event: Event] | 값이 확정됐을 때 (네이티브 change) |
| focus | [event: FocusEvent] | 초점을 받았을 때 |
| keydown | [event: KeyboardEvent] | 키를 눌렀을 때 |
| keyup | [event: KeyboardEvent] | 키를 뗐을 때 |
| update:modelValue | [value: string \| number] | 입력값이 바뀔 때 (v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 입력 필드 안쪽 버튼 (icon 속성과 함께, 여러 개면 KrdsButtonGroup) |

## KrdsButtonGroup

### Props

없음

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 입력 필드 안에 넣을 버튼들 |

---

# 파일 업로드 File upload

파일 업로드는 하나 이상의 디바이스의 로컬 파일을 선택하고 첨부하는 데 사용하는 입력 컴포넌트이다.

## 기본

`v-model`에 파일 목록(`FileInfo[]`)을 바인딩합니다. 컴포넌트는 파일을 서버로 보내지 않습니다. 추가된 파일은 `pending` 상태로 목록에 들어가므로 실제 업로드와 상태 변경은 직접 처리합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([])
</script>

<template>
  <KrdsFileUpload v-model="files" title="타이틀영역" description="컨텐츠 영역" />
</template>
```

## 파일 상태별 표시

`FileInfo`의 `status`에 따라 표시가 달라집니다. `uploading`은 스피너, `completed`는 완료 아이콘, `pending`은 삭제 버튼, `error`는 `errorMessage`를 표시합니다. `downloadUrl`이 있으면 다운로드·바로보기 버튼이 표시되고, 누르면 `download`·`preview` 이벤트가 발생합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([
    {
      id: '1',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'uploading'
    },
    {
      id: '2',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'completed'
    },
    {
      id: '3',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'pending'
    },
    {
      id: '4',
      file: new File([''], '전입재등록신고서 [주민등록법 시행령 별지서식 15, 15호의2호].hwp'),
      name: '전입재등록신고서 [주민등록법 시행령 별지서식 15, 15호의2호].hwp',
      size: 25 * 1024 * 1024,
      type: 'application/x-hwp',
      status: 'error',
      errorMessage: '등록 가능한 파일 용량을 초과하였습니다.\n20MB 미만의 파일만 등록할 수 있습니다.'
    },
    {
      id: '5',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'completed',
      downloadUrl: '/files/sample.hwp'
    }
  ])
</script>

<template>
  <KrdsFileUpload v-model="files" title="타이틀영역" description="컨텐츠 영역" />
</template>
```

## 파일 선택 동작

**파일선택** 버튼이나 업로드 영역으로 끌어다 놓아 파일을 추가합니다. `maxFileSize`(기본 20MB) 이상인 파일은 `error` 상태로 추가되고 개수에서 빠집니다. `maxFiles`(기본 10개)에 이르면 더 추가되지 않습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([])
</script>

<template>
  <KrdsFileUpload
    v-model="files"
    title="파일 업로드"
    description="파일을 선택하거나 드래그하여 업로드하세요."
    :max-file-size="20 * 1024 * 1024"
  />
</template>
```

## 단일 파일

`multiple`을 `false`로 지정하면 새로 선택한 파일이 기존 파일을 대신합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([])
</script>

<template>
  <KrdsFileUpload v-model="files" :multiple="false" title="단일 파일 업로드" description="하나의 파일만 업로드할 수 있습니다." />
</template>
```

## 이미지 파일만

`accept`에 허용할 확장자나 MIME 타입을 지정합니다. 끌어다 놓은 파일이 형식에 맞지 않으면 `error` 상태로 추가됩니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([])
</script>

<template>
  <KrdsFileUpload
    v-model="files"
    accept=".jpg,.jpeg,.png,.gif"
    :max-files="5"
    title="이미지 파일 업로드"
    description="JPG, PNG, GIF 파일만 업로드할 수 있습니다."
  />
</template>
```

## 비활성화

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([
    {
      id: '3',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'pending'
    }
  ])
</script>

<template>
  <KrdsFileUpload v-model="files" disabled title="비활성화 상태" description="파일 업로드가 비활성화된 상태입니다." />
</template>
```

## 읽기 전용

업로드 영역과 삭제 버튼 없이 파일 목록만 표시합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFileUpload } from '@krds.ui/vue'
  import type { FileInfo } from '@krds.ui/vue'

  const files = ref<FileInfo[]>([
    {
      id: '5',
      file: new File([''], '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'),
      name: '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp',
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'completed',
      downloadUrl: '/files/sample.hwp'
    }
  ])
</script>

<template>
  <KrdsFileUpload v-model="files" readonly title="읽기 전용" description="업로드된 파일만 확인할 수 있습니다." />
</template>
```

## API

## KrdsFileUpload

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name | string | - | 폼 필드 이름 |
| style | string \| Record<string, any> | - | 인라인 스타일 |
| title | string | '타이틀영역' | 제목 |
| id | string | - | HTML ID |
| required | boolean | false | 필수 입력 여부 |
| modelValue | FileInfo[] | [] | 파일 목록 |
| size | Size ('xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge') | 'medium' | 입력 크기 |
| disabled | boolean | false | 비활성화 여부 |
| description | string | '컨텐츠 영역' | 설명 텍스트 |
| placeholder | string | '첨부할 파일을 여기에 끌어다 놓거나, 파일 선택 버튼을 눌러 파일을 직접 선택해주세요.' | 플레이스홀더 텍스트 |
| readonly | boolean | false | 읽기 전용 여부 |
| accept | string | - | 허용되는 파일 타입 (예: '.jpg,.png,.pdf') |
| maxFiles | number | 10 | 최대 파일 개수 |
| maxFileSize | number | 20 * 1024 * 1024 // 20MB  | 최대 파일 크기 (bytes) |
| multiple | boolean | true | 다중 파일 선택 여부 |
| dragAndDrop | boolean | true | 드래그 앤 드롭 활성화 여부 |
| showPreview | boolean | true | 미리보기 표시 여부 |
| showDownload | boolean | true | 다운로드 버튼 표시 여부 |
| showPreviewButton | boolean | true | 바로보기 버튼 표시 여부 |
| showClearAll | boolean | true | 전체 삭제 버튼 표시 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| update:modelValue | [files: FileInfo[]] | 파일을 추가·삭제해 목록이 바뀔 때 (v-model) |
| file-added | [file: FileInfo] | 파일을 추가했을 때 |
| file-removed | [fileId: string] | 파일을 삭제했을 때 (파일 id) |
| file-error | [file: FileInfo, error: string] | 추가한 파일이 검사(크기·형식 등)에 실패했을 때 (오류 메시지) |
| upload-start | [file: FileInfo] | 보내지 않음 (기존 코드 호환용 선언), 업로드는 사용하는 쪽에서 처리 |
| upload-progress | [file: FileInfo, progress: number] | 보내지 않음 (기존 코드 호환용 선언), 업로드는 사용하는 쪽에서 처리 |
| upload-complete | [file: FileInfo] | 보내지 않음 (기존 코드 호환용 선언), 업로드는 사용하는 쪽에서 처리 |
| upload-error | [file: FileInfo, error: string] | 보내지 않음 (기존 코드 호환용 선언), 업로드는 사용하는 쪽에서 처리 |
| clear-all | [] | 전체 삭제 버튼을 눌렀을 때 |
| download | [file: FileInfo] | 파일의 다운로드 버튼을 눌렀을 때 |
| preview | [file: FileInfo] | 파일의 미리보기 버튼을 눌렀을 때 |

---

# 언어 변경 Language switcher

언어 변경은 서비스의 콘텐츠를 표시할 언어를 변경하거나 별도의 외국어 서비스로 이동하는 데 사용되는 요소이다. 한국어가 익숙하지 않은 사용자가 콘텐츠 표시 언어를 변경할 수 있는 수단을 발견하지 못한다면 서비스를 이용할 수 없게 되므로, 디지털 정부서비스로 직관적이고 일관된 방식으로 언어 변경을 제공하는 것이 매우 중요하다.

## 기본

선택한 언어 코드가 `v-model`에 담깁니다. `prev-item` 슬롯으로 목록 위에 현재 언어를 표시할 수 있습니다.

```vue
<script setup lang="ts">
  import { computed, ref } from 'vue'
  import { KrdsLanguageSwitcher } from '@krds.ui/vue'

  const languages = [
    { code: 'ko', name: '한국어' },
    { code: 'en', name: 'English (영어)' },
    { code: 'zh', name: '中文 (중국어)' },
    { code: 'ja', name: '日本語 (일본어)' },
    { code: 'fr', name: 'français (프랑스어)' }
  ]

  const selectedLanguage = ref('')
  const currentLanguageName = computed(() => languages.find(lang => lang.code === selectedLanguage.value)?.name || '선택해주세요')
</script>

<template>
  <div style="height: 400px; padding: 50px">
    <KrdsLanguageSwitcher v-model="selectedLanguage" :language-list="languages">
      언어변경
      <template #prev-item>
        <p class="current-laguage">
          <span>현재 언어</span>
          <strong>{{ currentLanguageName }}</strong>
        </p>
      </template>
    </KrdsLanguageSwitcher>
    <p style="margin-top: 20px">선택된 언어: {{ selectedLanguage }}</p>
  </div>
</template>
```

## 외부 페이지 이동

`type="external"`이면 각 언어가 `url`로 새 창에서 이동하는 링크가 됩니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsLanguageSwitcher } from '@krds.ui/vue'

  const languages = [
    { code: 'ko', name: '한국어', url: 'https://example.com/ko' },
    { code: 'en', name: 'English (영어)', url: 'https://example.com/en' },
    { code: 'zh', name: '中文 (중국어)', url: 'https://example.com/zh' },
    { code: 'ja', name: '日本語 (일본어)', url: 'https://example.com/ja' },
    { code: 'fr', name: 'français (프랑스어)', url: 'https://example.com/fr' }
  ]

  const selectedLanguage = ref('')
</script>

<template>
  <div style="height: 400px; padding: 50px">
    <KrdsLanguageSwitcher v-model="selectedLanguage" :language-list="languages" type="external"> 언어변경 </KrdsLanguageSwitcher>
  </div>
</template>
```

## API

## KrdsLanguageSwitcher

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| type | "default" \| "external" | 'default' | 동작 타입 (default: 언어 선택, external: 외부 페이지 이동) |
| modelValue | string | '' | 선택된 언어 코드 (v-model) |
| dropPosition | DropdownPosition ('left' \| 'center' \| 'right') | 'center' | 드롭다운 정렬 위치 |
| languageList (필수) | LanguageData[] | - | 언어 목록 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| close | [] | 언어 목록이 닫힐 때 |
| update:modelValue | [value: string] | 언어를 골랐을 때 (언어 코드, v-model) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 언어 버튼 문구 (예: Language) |
| prev-item | 언어 목록 위에 넣을 내용 |

---

# 화면 크기 조정 Resize

화면 크기 조정은 텍스트를 포함하여 화면에 표시되는 정보를 확대하거나 축소하는 데 사용되는 요소이다. 사용자에 따라 읽을 수 있는 텍스트의 크기, 조작할 수 있는 요소의 크기는 다르다. 디바이스나 사용자 에이전트가 지원하는 여러 가지 설정 기능을 활용하면 사용자가 선호하는 방식으로 콘텐츠의 표시 방식을 수정할 수 있다. 그러나 화면 크기 조정 기능을 필요로 하는 사용자는 관련 기능을 찾아 설정하는 데 어려움을 겪을 가능성이 높으므로 서비스 자체적으로 화면 크기 조정 기능을 제공하고 접근하기 쉽게 만드는 것이 중요하다.

## 기본

크기를 고르면 `document.body.style.zoom`을 0.9~1.5배로 바꿔 화면 전체를 확대·축소하므로 예제를 별도 화면(iframe)에 띄웁니다. 초기화 버튼은 보통(1배)으로 되돌립니다.

```vue
<script setup lang="ts">
  import { KrdsResize } from '@krds.ui/vue'
</script>

<template>
  <div style="height: 400px; padding: 20px">
    <KrdsResize />
  </div>
</template>
```

## v-model

`v-model`로 고른 크기(`sm` 작게 · `md` 보통 · `lg` 조금 크게 · `xlg` 크게 · `xxlg` 가장 크게)를 주고받습니다. 처음 값을 주면 그 크기로 시작하고, 고른 값을 저장해 두었다가 다음 방문 때 다시 넘기면 사용자가 고른 크기를 유지할 수 있습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsResize } from '@krds.ui/vue'
  import type { KrdsResizeScale } from '@krds.ui/vue'

  // '조금 크게'로 시작한다. 고른 값을 저장해 두었다가 다음 방문 때 넘기면 사용자가 고른 크기를 유지할 수 있다
  const size = ref<KrdsResizeScale>('lg')
</script>

<template>
  <div style="height: 400px; padding: 20px">
    <KrdsResize v-model="size" />
    <p>선택한 크기: {{ size }}</p>
  </div>
</template>
```

## API

## KrdsResize

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| modelValue | KrdsResizeScale ('sm' \| 'md' \| 'lg' \| 'xlg' \| 'xxlg') | - | 선택한 화면 크기 (v-model). 지정하면 그 크기로 화면을 확대·축소한다 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| close | [] | 크기 목록이 닫힐 때 |
| update:modelValue | [value: KrdsResizeScale] | 화면 크기를 골랐을 때 (v-model) |

---

# 접근 가능한 미디어 Accessible multimedia

미디어 콘텐츠에 설명이 필요한 경우에 사용하는 컴포넌트이다. 정지된 이미지에 설명을 제공할 때에는 숨김 콘텐츠를, 오디오/비디오/멀티미디어 콘텐츠에 설명을 제공할 때는 접근 가능한 미디어 컴포넌트를 사용한다.

## 동영상

`src`·`title`(필수)을 주면 브라우저 기본 재생기(`<video controls>`)로 재생합니다. `captions`에 WebVTT 자막 주소를 주면 한국어 자막이 기본으로 켜지고, `#transcript` 슬롯에 원고를 넣으면 재생기 아래 **원고 보기**로 펼칠 수 있습니다. `poster`·`width` 등 나머지 속성은 `<video>`에 그대로 전달되고, 다른 언어 자막은 기본 슬롯에 `<track>`으로 넣습니다.

```vue
<script setup lang="ts">
  import { KrdsMedia } from '@krds.ui/vue'
</script>

<template>
  <KrdsMedia
    src="/demo/steps.mp4"
    title="단계 진행 표시 예시 영상"
    captions="/demo/steps.ko.vtt"
    poster="/demo/steps-poster.jpg"
    width="640"
    height="360"
  >
    <template #transcript>
      <p>연한 회색 화면 가운데에 회색 테두리의 네모 칸 세 개가 가로로 놓여 있습니다.</p>
      <p>[알림음] 왼쪽 칸이 파란색으로 채워집니다.</p>
      <p>[알림음] 가운데 칸이 파란색으로 채워집니다.</p>
      <p>[알림음] 오른쪽 칸이 파란색으로 채워집니다.</p>
      <p>[완료 알림음 두 번] 세 칸 아래에 초록색 막대가 나타납니다.</p>
    </template>
  </KrdsMedia>
</template>
```

## 오디오

`audio`를 주면 `<audio controls>`로 재생합니다. 오디오는 자막이 화면에 보이지 않으므로 원고를 제공합니다.

```vue
<script setup lang="ts">
  import { KrdsMedia } from '@krds.ui/vue'
</script>

<template>
  <KrdsMedia src="/demo/steps.m4a" title="알림음 예시 음성" audio>
    <template #transcript>
      <p>[알림음] 세 번이 약 3초 간격으로 울린 뒤, [더 높은 완료 알림음] 두 번이 짧게 이어집니다.</p>
    </template>
  </KrdsMedia>
</template>
```

## 외부 재생기

유튜브처럼 외부 재생기를 쓸 때는 `src` 없이 기본 슬롯에 `<iframe>`을 넣습니다. 제목과 원고 영역이 붙고, `<iframe>`은 폭에 맞춰 16:9로 표시됩니다. 자막은 외부 재생기에서 관리하고, `<iframe>`에는 `title`을 꼭 답니다.

```vue
<KrdsMedia title="민원 신청 안내 영상">
  <iframe src="https://www.youtube-nocookie.com/embed/영상ID" title="민원 신청 안내 영상" allowfullscreen></iframe>
  <template #transcript>
    <p>민원 신청은 세 단계로 진행됩니다. …</p>
  </template>
</KrdsMedia>
```

## 사용 지침

- 미디어를 만들 때 대체 정보(자막·원고·화면 해설·수어)를 함께 계획합니다. 녹화용 대본을 활용하면 원고를 만들기 쉽습니다.
- 여러 대체 정보를 제공하기 어렵다면 가장 많은 사용자가 쓸 수 있는 원고(설명적 원고)를 제공합니다.
- 대체 정보에는 미디어의 모든 정보를 담습니다. 화면에 보이는 배열·움직임과, 화면에 없는 박수 소리 같은 효과음도 적습니다.
- 자막은 오디오와 시간을 맞추고(WebVTT), 영상 속 중요한 시각 요소와 겹치지 않게 합니다.
- 영상 속 정보를 전하는 글자·도형은 배경과 4.5:1 이상의 명도 대비를 갖게 합니다.
- 화면 해설 버전이나 수어 영상이 있으면 원고 안에 링크로 안내합니다.
- 미디어를 바꾸면 대체 정보도 함께 고칩니다.

## 접근성

- 브라우저 기본 재생기라 재생·탐색·음량·전체 화면·자막 켜기를 키보드와 화면낭독기로 조작하고, 자막은 운영체제의 자막 크기·색 설정을 따릅니다. 자막 기본 모양은 KRDS 가이드대로 반투명 검은 배경에 흰 글자입니다.
- 제목은 미디어 영역(`figure`)의 이름이 됩니다. 화면에서 숨겨야 하면 `hide-title`을 지정합니다.
- 앱이 개발 모드일 때 자막과 원고가 모두 없거나(오디오는 원고가 없으면), 자동 재생(`autoplay`)을 켜면 콘솔에 경고합니다(Vue 경고, 배포 빌드에서는 출력하지 않음).

## API

## KrdsMedia

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| audio | boolean | false | 오디오 콘텐츠 (audio 요소로 재생) |
| src | string | - | 미디어 파일 주소 (없으면 기본 슬롯의 재생기를 씀, 예: 유튜브 iframe) |
| hideTitle | boolean | false | 제목을 화면에서 숨김 (화면낭독기는 읽음) |
| captions | string | - | 한국어 자막(WebVTT) 주소 |
| title (필수) | string | - | 미디어 제목 (재생기 위에 표시, 화면낭독기가 미디어 영역 이름으로 읽음) |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | src가 있으면 video·audio 안에 넣을 source·track(다른 언어 자막 등), 없으면 재생기 자체(유튜브 iframe 등) |
| transcript | 원고(설명적 원고): 화면과 소리의 정보를 글로 옮긴 내용, '원고 보기'로 펼침 |

---

# 숨긴 콘텐츠 v-sr-only

v-sr-only 디렉티브는 스크린 리더 전용 텍스트를 위한 최소 구현 디렉티브이다.

## 기본

`v-sr-only`를 단 요소에 KRDS `.sr-only` 클래스가 붙어 화면에서는 보이지 않고 스크린 리더로만 읽힙니다. 아래 예제의 가운데 문장은 화면에 표시되지 않습니다.

```vue
<template>
  <div>
    <p>일반 텍스트입니다.</p>
    <span v-sr-only>스크린 리더 전용 텍스트입니다.</span>
    <p>다시 일반 텍스트입니다.</p>
  </div>
</template>
```

## 사용법

플러그인을 등록(`app.use(KrdsVue)`)하면 `v-sr-only`가 전역 디렉티브로 등록됩니다. 패키지에서 `vSrOnly`를 따로 export하지 않으므로, 플러그인 없이 컴포넌트만 개별 import해 쓸 때는 요소에 `class="sr-only"`를 직접 지정합니다.

| 사용                | 동작                                   |
| ------------------- | -------------------------------------- |
| `v-sr-only`         | 요소에 `.sr-only` 클래스를 추가합니다. |
| `v-sr-only="true"`  | `v-sr-only`와 같습니다.                |
| `v-sr-only="false"` | 클래스를 추가하지 않습니다.            |

바인딩 값이 바뀌면 그에 맞춰 클래스를 추가하거나 제거하고, 요소가 언마운트되면 클래스를 제거합니다.

---

# 범위슬라이드 Range slider

범위 슬라이더는 사용자가 연속된 옵션 범위에서 값을 선택할 수 있도록 하는 경우 사용한다. 사용자가 선택한 값은 선택하는 동안 계속 보이도록 표시하여야 한다.

## 기본

`v-model`로 값(`number`)을 연결하고 `label`로 어떤 값을 고르는지 안내합니다. `min`(기본 0)·`max`(기본 100)·`step`(기본 1)으로 범위와 단계를 정하고, `value-text`로 값을 글자로 바꿉니다. 바꾼 글자는 핸들 위 말풍선, 트랙 아래 범위 값, 화면낭독기가 읽는 값(`aria-valuetext`)에 함께 쓰입니다. 단계가 20개 이하이면 트랙에 단계 눈금이 표시됩니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsRangeSlider } from '@krds.ui/vue'

  const sizes = ['작게', '보통', '조금 크게', '크게', '아주 크게']
  const size = ref(2)
</script>

<template>
  <KrdsRangeSlider v-model="size" label="글자 크기" :max="sizes.length - 1" :value-text="v => sizes[v]" />
</template>
```

## 슬라이더 끝에 선택 값

`value-position="end"`를 주면 선택 값을 말풍선 대신 슬라이더 오른쪽 끝에 표시합니다. 손가락으로 끄는 동안에도 값이 가려지지 않습니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsRangeSlider } from '@krds.ui/vue'

  const volume = ref(50)
</script>

<template>
  <KrdsRangeSlider v-model="volume" label="음량" :step="10" :value-text="v => `${v}%`" value-position="end" />
</template>
```

## 사용 지침

- 볼륨·밝기·글자 크기처럼 정확한 값보다 상대적인 값이 중요할 때 씁니다. 정확한 수치를 입력해야 하면 [텍스트 입력 필드](./input)를, 단계가 몇 개뿐이면 [라디오 버튼](./radio)을 씁니다.
- 단계는 전체 범위의 10~20%로 정합니다. 너무 세밀하면 고르기 어렵습니다.
- 말풍선은 항상 핸들 위 가운데에 표시되어, 값 글자가 길면 양 끝에서 슬라이더 밖으로 조금 나갈 수 있습니다. 화면 끝에 붙여 쓸 때는 양옆에 여백을 둡니다.
- 레이블은 생략하지 않습니다. 화면에서 숨겨야 하면 `hide-label`을 지정합니다(화면낭독기는 읽음).

## 접근성

- 기본 `<input type="range">`라 핸들을 끌거나 트랙을 눌러 값을 바꾸고, 키보드로는 <kbd>←</kbd>/<kbd>→</kbd>(또는 <kbd>↓</kbd>/<kbd>↑</kbd>)로 한 단계씩, <kbd>Home</kbd>/<kbd>End</kbd>로 최솟값/최댓값을 고릅니다.
- `value-text`를 주면 화면낭독기가 숫자 대신 바꾼 글자(예: `조금 크게`, `50%`)를 읽습니다.
- 키보드 초점은 핸들 둘레에 표시됩니다.

## API

## KrdsRangeSlider

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| id | string | - | 슬라이더(input) 요소 ID |
| modelValue | number | - | 선택 값 (없으면 최솟값) |
| min | number | 0 | 최솟값 |
| max | number | 100 | 최댓값 |
| hideLabel | boolean | false | 레이블을 화면에서 숨김 (화면낭독기는 읽음) |
| step | number | 1 | 단계 (KRDS 가이드: 전체 범위의 10~20%) |
| valueText | ((value: number) => string) | - | 값을 글자로 바꾸는 함수 (선택 값·범위 값 표시와 화면낭독기 aria-valuetext에 사용) |
| valuePosition | KrdsRangeSliderValuePosition ('handle' \| 'end') | 'handle' | 선택 값 위치: 핸들 위 말풍선(handle) 또는 슬라이더 끝(end) |
| label (필수) | string | - | 레이블 (어떤 값을 고르는지 안내) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [value: number] | 값을 정했을 때 (핸들을 놓거나 키보드로 바꾼 뒤) |
| update:modelValue | [value: number] | 값이 바뀔 때 (끄는 동안 계속, v-model) |

---

# 수량 토글 Quantity toggle

수량 토글은 사용자가 수량 옵션을 늘리거나 줄이는 데 사용되며, 한정된 범위 내에서 수량 선택을 위해 사용한다.

## 기본

`v-model`로 수량(`number`)을 연결하고 `label`로 어떤 수량인지 안내합니다. 최솟값(`min`, 기본 0)이나 최댓값(`max`, 기본 10)에 닿으면 해당 버튼이 비활성화됩니다. KRDS 가이드에 따라 선택 범위는 기준값을 포함해 11단계 이내로 정하고, 그보다 넓으면 [텍스트 입력 필드](./input)를 씁니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsQuantityToggle } from '@krds.ui/vue'

  const count = ref(1)
</script>

<template>
  <KrdsQuantityToggle v-model="count" label="관람 인원" :min="1" :max="4" />
</template>
```

## 세로형

`vertical`을 지정하면 + 버튼이 위, − 버튼이 아래에 놓입니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsQuantityToggle } from '@krds.ui/vue'

  const count = ref(0)
</script>

<template>
  <KrdsQuantityToggle v-model="count" label="증명서 발급 수" :max="5" vertical />
</template>
```

## 접근성

- 수량 값은 [WAI-ARIA spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/)입니다. <kbd>Tab</kbd>으로 수량 값에 초점을 옮긴 뒤 <kbd>↑</kbd>/<kbd>↓</kbd>로 1씩, <kbd>Home</kbd>/<kbd>End</kbd>로 최솟값/최댓값을 고릅니다.
- −/+ 버튼은 키보드 조작과 기능이 겹쳐 탭 순서에서 빠지고, 누르면 초점이 수량 값으로 옮겨져 화면낭독기가 바뀐 값을 읽습니다.
- 레이블은 생략하지 않습니다. 화면에서 숨겨야 하면 `hide-label`을 지정합니다(화면낭독기는 읽음).

## API

## KrdsQuantityToggle

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| id | string | - | 수량 값(spinbutton) 요소 ID |
| modelValue | number | - | 수량 (없으면 최솟값) |
| min | number | 0 | 최솟값 |
| max | number | 10 | 최댓값 (KRDS 가이드: 기준값 포함 11단계 이내) |
| disabled | boolean | false | 비활성화 여부 |
| hideLabel | boolean | false | 레이블을 화면에서 숨김 (화면낭독기는 읽음) |
| vertical | boolean | false | 세로형 (+ 버튼이 위) |
| label (필수) | string | - | 레이블 (어떤 수량을 고르는지 안내) |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| change | [value: number] | 버튼·키보드로 수량을 바꿨을 때 |
| update:modelValue | [value: number] | 수량이 바뀔 때 (v-model) |

---

# 토스트 Toast

토스트는 사용자 행동에 대한 결과를 일시적으로 표시했다 사라지는 알림 메시지를 표시하는데 사용한다. 알림 메시지는 사용자가 인지할 수 있는 시간만큼 충분히 표시되어야 한다.

## 기본

`<KrdsToast />`를 App.vue에 한 번만 두고, 어느 컴포넌트에서든 `useToast().show(message, options)` 또는 단축형 `info(message)`·`warning(message)`로 띄웁니다. 노출 시간은 KRDS 가이드대로 정보형 3초, 주의·경고형(`type: 'warning'`) 4초이며 `duration`(ms)으로 바꿀 수 있습니다(0이면 닫지 않음). 떠 있는 동안 다시 `show()`하면 메시지를 바꾸고 노출 시간을 다시 세고, `hide()`로 바로 닫습니다. 화면낭독기가 읽도록 `role="status"` 영역은 항상 두고 표시할 때만 메시지를 넣습니다. 화면 하단에 고정되므로 예제를 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { KrdsButton, KrdsToast, useToast } from '@krds.ui/vue'

  // 실제 앱에서는 <KrdsToast />를 App.vue에 한 번만 두고 각 화면에서 useToast()로 띄웁니다
  const toast = useToast()
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton variant="primary" @click="toast.show('저장되었습니다.')">저장</KrdsButton>
    <KrdsButton variant="secondary" @click="toast.warning('파일 업로드에 실패했습니다.')">업로드 실패</KrdsButton>
    <KrdsToast />
  </div>
</template>
```

## 사용 지침

- 사용자 행동에 대한 즉각적인 피드백(저장 완료, 업로드 완료 등)을 한 줄로 알릴 때 씁니다.
- 중요하거나 긴급한 메시지는 긴급 공지나 모달을, 되돌리기 같은 추가 행동이 필요하면 [스낵바](/components/snackbar)를 씁니다.
- 개별 입력 항목의 오류·성공 메시지는 토스트 대신 입력 필드 옆의 `KrdsFormHint`로 알립니다.
- 하단 탭바나 플로팅 버튼과 겹치지 않게 앱 CSS에서 `.krds-toast { --krds-toast--bottom: 8rem }`처럼 위치를 조정합니다.
- 원본 KRDS에 구현이 없는 컴포넌트로, 가이드의 구조·위치·노출 시간과 디자인 토큰으로 만들었습니다.

## API

## KrdsToast

전역 토스트를 그리는 자리입니다. App에 한 번만 두며 props·events가 없습니다.

## useToast()

| 이름                          | 설명                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| `show(message, options?)`     | 토스트 표시. `options.type`(`'info'` \| `'warning'`, 기본 `'info'`), `options.duration`(ms, 0이면 유지) |
| `info(message, duration?)`    | 정보형 토스트 (3초). 인증·저장·업로드 완료 등                                                           |
| `warning(message, duration?)` | 주의·경고형 토스트 (4초). 인증·저장·업로드 실패 등                                                      |
| `hide()`                      | 토스트 닫기                                                                                             |

---

# 스낵바 Snackbar

스낵바는 사용자 행동에 대한 결과나 서비스 이용 중 발생한 중요도 낮은 메시지를 추가 행동과 함께 제공하는데 사용한다. 사용자의 주요 흐름을 방해하지 않으면서, 되돌리기 또는 다시 시도 등과 같이 간단한 조치를 포함한다.

## 기본

`<KrdsSnackbar />`를 App.vue에 한 번만 두고, 어느 컴포넌트에서든 `useSnackbar().show({ title, message, icon, action, onAction })`로 띄웁니다. `action`에 버튼 이름을 주면 텍스트 작업 버튼이 생기고, 누르면 스낵바를 닫고 `onAction`을 부릅니다(`onAction`에서 다시 `show()`하면 새 스낵바가 뜹니다). 닫기 버튼이나 `hide()`로 닫으며, 기본으로는 자동으로 사라지지 않고 `duration`(ms)을 주면 그 시간 뒤 닫힙니다. `icon`은 메시지 뜻을 강조할 때만 씁니다(`ico-success-fill`, `ico-information-fill`, `ico-error-fill`). 화면낭독기가 읽도록 `role="status"` 영역은 항상 두고 표시할 때만 내용을 넣습니다. 화면 하단에 고정되므로 예제를 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsButton, KrdsSnackbar, useSnackbar } from '@krds.ui/vue'

  // 실제 앱에서는 <KrdsSnackbar />를 App.vue에 한 번만 두고, 각 화면에서 useSnackbar()로 띄웁니다
  const snackbar = useSnackbar()
  const sent = ref(0)

  const send = () => {
    sent.value++
    snackbar.show({
      title: '전송 완료',
      message: `신청서를 ${sent.value}건 보냈습니다.`,
      action: '목록으로',
      onAction: () => alert('목록으로 이동')
    })
  }
  const fail = () =>
    snackbar.show({
      icon: 'ico-error-fill',
      title: '전송 실패',
      message: '네트워크 오류로 보내지 못했습니다.',
      action: '다시 시도',
      onAction: send
    })
</script>

<template>
  <div style="display: flex; gap: 1rem; align-items: center; flex-wrap: wrap">
    <KrdsButton variant="primary" @click="send">신청서 보내기</KrdsButton>
    <KrdsButton variant="secondary" @click="fail">실패 상황</KrdsButton>
    <KrdsSnackbar />
  </div>
</template>
```

## 사용 지침

- 되돌리기, 다시 시도, 목록 이동처럼 사용자가 즉시 할 수 있는 간단한 조치를 메시지와 함께 줄 때 씁니다. 작업 버튼은 1개만 둡니다.
- 작업 버튼이 있으면 `duration`을 주지 않습니다. 시간이 지나 닫히면 키보드·화면낭독기 사용자가 작업 버튼에 닿기 전에 사라질 수 있습니다.
- 중요하거나 긴급한 메시지, 두 문장 이상의 설명은 긴급 공지나 모달을 씁니다. 추가 행동이 없는 한 줄 알림은 [토스트](/components/toast)를 씁니다.
- 한 페이지에 스낵바를 하나만 표시하고, 여러 개를 겹치거나 쌓지 않습니다. 떠 있는 동안 다시 `show()`하면 내용이 바뀝니다. 토스트와 같은 자리에 뜨므로 토스트와 함께 띄우지 않습니다.
- 하단 탭바나 플로팅 버튼과 겹치지 않게 앱 CSS에서 `.krds-snackbar { --krds-snackbar--bottom: 8rem }`처럼 위치를 조정합니다.
- 원본 KRDS에 구현이 없는 컴포넌트로, 가이드의 구조·위치와 디자인 토큰으로 만들었습니다.

## API

## KrdsSnackbar

전역 스낵바를 그리는 자리입니다. App에 한 번만 두며 props·events가 없습니다.

## useSnackbar()

| 이름            | 설명                                                                                                                                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `show(options)` | 스낵바 표시. `title`(필수), `message`, `icon`(아이콘 클래스), `action`(작업 버튼 이름), `onAction`(작업 버튼을 눌렀을 때, 스낵바를 닫은 뒤 부름), `duration`(ms, 기본 0으로 닫기 버튼까지 유지) |
| `hide()`        | 스낵바 닫기                                                                                                                                                                                     |

---

# 탭바 Tab bar

탭바는 화면 하단에 고정하여 제공하는 탐색 수단으로 작은 디바이스나 좁은 화면에서 서비스의 핵심 화면으로 빠르게 접근할 수 있도록 도와준다.

## 기본

`items`에 메뉴 이름(`text`)과 아이콘(`icon`)을 넣습니다. `href`가 있으면 링크, 없으면 버튼(전체 메뉴 열기 등)으로 렌더링하고, 현재 화면에는 `selected`를 줘서 위쪽 인디케이터와 배경으로 표시합니다. 링크 항목의 `onClick`에서 `event.preventDefault()`를 호출하면 라우터 이동에 쓸 수 있습니다. 화면 하단에 고정되므로 예제를 별도 화면(iframe)에 띄웁니다.

```vue
<script setup lang="ts">
  import { computed, ref } from 'vue'
  import { KrdsTabBar } from '@krds.ui/vue'

  const current = ref('home')
  // 라우터를 쓴다면 selected는 현재 경로로 정하고, 링크 이동은 router-link나 router.push로 처리한다
  const go = (key: string) => (event: MouseEvent) => {
    event.preventDefault()
    current.value = key
  }

  const items = computed(() => [
    { text: '홈', icon: 'ico-bread-home', href: '#home', selected: current.value === 'home', onClick: go('home') },
    { text: '내정보', icon: 'ico-my', href: '#my', selected: current.value === 'my', onClick: go('my') },
    { text: '즐겨찾기', icon: 'ico-scrap', href: '#bookmark', selected: current.value === 'bookmark', onClick: go('bookmark') },
    { text: '전체', icon: 'ico-all', selected: current.value === 'all', onClick: () => (current.value = 'all') }
  ])
</script>

<template>
  <KrdsTabBar :items="items" />
</template>
```

## 사용 지침

- 메인 메뉴가 보이는 넓은 화면(1024px 이상)에서는 탭바가 숨겨집니다. 좁은 화면용 내비게이션으로만 씁니다.
- 탭바가 있는 동안 페이지 아래에 탭바 높이만큼 여백이 생겨 푸터 등 마지막 내용이 가려지지 않고, [플로팅 버튼](./floating-button)은 탭바 위로 올라갑니다.
- 메뉴는 5개 이하로 두고, 홈은 맨 왼쪽, 전체 메뉴는 맨 오른쪽에 둡니다.
- 아이콘과 레이블을 함께 쓰고, 레이블은 잘리지 않도록 1~2단어로 짧게 씁니다.
- 스크롤할 때 숨기거나 위치를 바꾸지 않습니다. 하위 화면에서는 탭바를 빼도 됩니다.

## 접근성

- `<nav>`에 `label`(기본 `하단 메뉴`)로 이름을 붙여 화면낭독기가 내비게이션 영역으로 인식합니다.
- 선택된 메뉴에는 `aria-current="page"`가 붙어 현재 화면임을 전달합니다.

## API

## KrdsTabBar

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| label | string | '하단 메뉴' | 내비게이션 이름 (화면낭독기용) |
| items (필수) | KrdsTabBarItem[] | - | 메뉴 항목 (5개 이하, 홈은 맨 왼쪽·전체 메뉴는 맨 오른쪽) |

---

# 스플래시 스크린 Splash screen

스플래시 스크린은 응용 프로그램이 실행되기 전에 사용자에게 짧은 시간 동안 제공되는 화면으로 모바일 애플리케이션 전용 컴포넌트이다.

## 기본

스플래시 스크린 컴포넌트는 현재 제공하지 않습니다. 모바일 앱 시작 시 표시되는 화면으로 각 플랫폼의 네이티브 기능을 통해 구현할 예정입니다.

---

# 폼 그룹 Form group

`KrdsFormGroup`은 입력 컴포넌트 하나와 그 레이블·도움말을 묶는 `.form-group` 영역입니다. `KrdsFormLabel`은 레이블(`.form-tit` 안의 `<label>`), `KrdsFormHint`는 입력 필드 아래의 도움말(`<p>`)을 만듭니다. 텍스트 입력 필드, 텍스트 영역, 셀렉트, 날짜 입력 필드 등과 함께 씁니다.

## 기본

`KrdsFormLabel`의 `for`에 입력 컴포넌트의 `id`를 지정해 레이블을 연결합니다.

```vue
<script setup lang="ts">
  import { ref } from 'vue'
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'

  const email = ref('')
</script>

<template>
  <KrdsFormGroup>
    <KrdsFormLabel for="form-group-email">이메일</KrdsFormLabel>
    <KrdsInput id="form-group-email" v-model="email" type="email" placeholder="example@korea.kr" />
    <KrdsFormHint>알림을 받을 이메일 주소를 입력해 주세요</KrdsFormHint>
  </KrdsFormGroup>
</template>
```

## 도움말 유형

`KrdsFormHint`의 `type`을 `error`·`success`·`information`으로 지정하면 각각 에러·성공·정보 메시지 스타일로 표시됩니다(기본값 `hint`). 입력 컴포넌트의 상태(`state`)와 같은 값으로 맞춥니다.

```vue
<script setup lang="ts">
  import { KrdsFormGroup, KrdsFormHint, KrdsFormLabel, KrdsInput } from '@krds.ui/vue'
</script>

<template>
  <div class="fieldset">
    <KrdsFormGroup>
      <KrdsFormLabel for="form-group-hint">레이블</KrdsFormLabel>
      <KrdsInput id="form-group-hint" placeholder="플레이스홀더" />
      <KrdsFormHint>도움말</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="form-group-error">레이블</KrdsFormLabel>
      <KrdsInput id="form-group-error" model-value="에러" state="error" />
      <KrdsFormHint type="error">에러 메시지</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="form-group-success">레이블</KrdsFormLabel>
      <KrdsInput id="form-group-success" model-value="성공" state="success" />
      <KrdsFormHint type="success">성공 메시지</KrdsFormHint>
    </KrdsFormGroup>

    <KrdsFormGroup>
      <KrdsFormLabel for="form-group-information">레이블</KrdsFormLabel>
      <KrdsInput id="form-group-information" model-value="정보" state="information" />
      <KrdsFormHint type="information">정보 메시지</KrdsFormHint>
    </KrdsFormGroup>
  </div>
</template>
```

## API

## KrdsFormGroup

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| style | string \| Record<string, any> | - | 인라인 스타일 |
| id | string | - | HTML ID |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 레이블·입력 요소·도움말 |

## KrdsFormLabel

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| style | string \| Record<string, any> | - | 인라인 스타일 |
| id | string | - | HTML ID |
| for | string | - | label의 for 속성 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 레이블을 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 레이블 문구 |

## KrdsFormHint

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| style | string \| Record<string, any> | - | 인라인 스타일 |
| id | string | - | HTML ID |
| type | "error" \| "success" \| "information" \| "hint" | 'hint' | 힌트 타입 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| click | [event: MouseEvent] | 도움말 문구를 클릭했을 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 도움말 문구 |

---

# 아이콘 Icon

KRDS SVG 아이콘을 표시하는 컴포넌트이다. name 속성에 아이콘 클래스명(ico-\*)을 지정하며, 실제 그래픽은 스타일 시트의 svg-icon 마스크로 렌더링된다.

## 기본

`<i class="svg-icon ico-help">`로 렌더링됩니다. 아이콘에는 대체 텍스트가 없으므로 아이콘만으로 의미를 전달할 때는 `sr-only` 텍스트를 함께 제공합니다.

```vue
<script setup lang="ts">
  import { KrdsIcon } from '@krds.ui/vue'
</script>

<template>
  <KrdsIcon name="ico-help" />
</template>
```

## 아이콘 목록

```vue
<script setup lang="ts">
  import { KrdsIcon } from '@krds.ui/vue'

  const icons = [
    'ico-angle',
    'ico-calendar',
    'ico-call',
    'ico-del',
    'ico-email',
    'ico-faq',
    'ico-file',
    'ico-filter',
    'ico-global',
    'ico-go',
    'ico-help',
    'ico-like'
  ]
</script>

<template>
  <ul style="display: flex; flex-wrap: wrap; gap: 1.6rem; list-style: none; padding: 0">
    <li v-for="icon in icons" :key="icon" style="display: flex; flex-direction: column; align-items: center; gap: 0.4rem; width: 8rem">
      <KrdsIcon :name="icon" />
      <code style="font-size: 1.2rem">{{ icon }}</code>
    </li>
  </ul>
</template>
```

## API

## KrdsIcon

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| name (필수) | string | - | 아이콘 이름 |

---

# 레이아웃 Layout

웹사이트의 전체 레이아웃 구조를 제공하는 컴포넌트이다. 스크롤 방향에 따라 자동으로 scroll-up/scroll-down 클래스를 추가한다.

## 기본

`#wrap` 요소를 만들고 창 스크롤 방향에 따라 `scroll-up`/`scroll-down` 클래스를 붙여 헤더를 숨기거나 다시 보여 줍니다. 창 스크롤에 의존하므로 예제를 별도 화면(iframe)에 띄웁니다. 스크롤 위치를 `#container` 요소 기준으로 판단하므로 본문은 `id="container"` 요소에 넣습니다. 예제는 1024px 폭 화면을 축소해 PC 레이아웃으로 보여 줍니다. 1024px 미만 화면에서는 헤더 유틸리티 메뉴, 주 메뉴, 사이드 메뉴가 숨겨지고 전체메뉴 버튼이 표시됩니다.

```vue
<script setup lang="ts">
  import {
    KrdsBreadcrumb,
    KrdsButton,
    KrdsFooter,
    KrdsHeader,
    KrdsIdentifier,
    KrdsLayout,
    KrdsMainMenu,
    KrdsMasthead,
    KrdsSkipLink
  } from '@krds.ui/vue'
</script>

<template>
  <KrdsLayout class="custom-layout">
    <KrdsSkipLink href="#container">본문 바로가기</KrdsSkipLink>
    <KrdsMasthead>이 누리집은 대한민국 공식 전자정부 누리집입니다.</KrdsMasthead>
    <KrdsHeader>
      <template #utility>
        <ul class="utility-list">
          <li>
            <a href="#" class="krds-btn small text" target="_blank" title="새 창 열기"> 메뉴명 <i class="svg-icon ico-go"></i> </a>
          </li>
          <li>
            <div class="krds-drop-wrap">
              <button type="button" class="krds-btn small text drop-btn">메뉴명 <i class="svg-icon ico-toggle"></i></button>
              <div class="drop-menu">
                <div class="drop-in">
                  <ul class="drop-list">
                    <li><a href="#" class="item-link">메뉴명</a></li>
                    <li><a href="#" class="item-link">메뉴명</a></li>
                  </ul>
                </div>
              </div>
            </div>
          </li>
        </ul>
      </template>

      <template #branding>
        <h2 class="logo">
          <a href="#">
            <span class="sr-only">KRDS - Korea Design System</span>
          </a>
        </h2>
        <div class="header-actions">
          <button type="button" class="btn-navi sch" title="통합검색 레이어">통합검색</button>
          <a href="#" class="btn-navi login">로그인</a>
          <button type="button" class="btn-navi join">회원가입</button>
          <button type="button" class="btn-navi all" aria-controls="mobile-nav">전체메뉴</button>
        </div>
      </template>

      <template #navigation>
        <KrdsMainMenu
          :items="[
            { text: '1Depth', subItems: [{ text: '2Depth-menu', items: [{ text: '3Depth-menu', href: '#' }] }] },
            { text: '1Depth', subItems: [{ text: '2Depth-menu', items: [{ text: '3Depth-menu', href: '#' }] }] },
            { text: '링크(anchor)', href: '#' }
          ]"
        />
      </template>
    </KrdsHeader>
    <div id="container">
      <div class="inner in-between">
        <nav class="krds-side-navigation">
          <h2 class="lnb-tit">1Depth-title</h2>
          <!-- lnb-list -->
          <ul class="lnb-list">
            <li class="lnb-item">
              <button type="button" class="lnb-btn lnb-toggle" aria-controls="lnbmenu-e7xeix1" aria-expanded="false">2Depth-menu</button>
              <!-- lnb-submenu -->
              <div class="lnb-submenu">
                <ul id="lnbmenu-e7xeix1">
                  <li class="lnb-subitem">
                    <button
                      type="button"
                      class="lnb-btn lnb-toggle-popup"
                      aria-controls="lnbmenu-o4g3re9"
                      aria-expanded="false"
                      aria-haspopup="true"
                    >
                      3Depth-menu
                    </button>
                    <!-- lnb-submenu-lv2 -->
                    <div class="lnb-submenu-lv2" id="lnbmenu-o4g3re9">
                      <button type="button" class="lnb-btn-tit">3Depth-title</button>
                      <ul>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                      </ul>
                    </div>
                    <!-- //lnb-submenu-lv2 -->
                  </li>
                  <li class="lnb-subitem"><a href="#" class="lnb-btn lnb-link">3Depth-link</a></li>
                  <li class="lnb-subitem"><a href="./sample_sub_02.html" class="lnb-btn lnb-link">3Depth-link</a></li>
                </ul>
              </div>
              <!-- //lnb-submenu -->
            </li>
            <li class="lnb-item">
              <button type="button" class="lnb-btn lnb-toggle" aria-controls="lnbmenu-jxx21y4" aria-expanded="false">2Depth-menu</button>
              <!-- lnb-submenu -->
              <div class="lnb-submenu">
                <ul id="lnbmenu-jxx21y4">
                  <li class="lnb-subitem">
                    <button
                      type="button"
                      class="lnb-btn lnb-toggle-popup"
                      aria-controls="lnbmenu-j6hmfzo"
                      aria-expanded="false"
                      aria-haspopup="true"
                    >
                      3Depth-menu
                    </button>
                    <!-- lnb-submenu-lv2 -->
                    <div class="lnb-submenu-lv2" id="lnbmenu-j6hmfzo">
                      <button type="button" class="lnb-btn-tit">3Depth-title</button>
                      <ul>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                      </ul>
                    </div>
                    <!-- //lnb-submenu-lv2 -->
                  </li>
                  <li class="lnb-subitem"><a href="#" class="lnb-btn lnb-link">3Depth-link</a></li>
                  <li class="lnb-subitem"><a href="#" class="lnb-btn lnb-link">3Depth-link</a></li>
                </ul>
              </div>
              <!-- //lnb-submenu -->
            </li>
            <li class="lnb-item">
              <button type="button" class="lnb-btn lnb-toggle" aria-controls="lnbmenu-7fsvaio" aria-expanded="false">2Depth-menu</button>
              <!-- lnb-submenu -->
              <div class="lnb-submenu">
                <ul id="lnbmenu-7fsvaio">
                  <li class="lnb-subitem">
                    <button
                      type="button"
                      class="lnb-btn lnb-toggle-popup"
                      aria-controls="lnbmenu-uk7pakf"
                      aria-expanded="false"
                      aria-haspopup="true"
                    >
                      3Depth-menu
                    </button>
                    <!-- lnb-submenu-lv2 -->
                    <div class="lnb-submenu-lv2" id="lnbmenu-uk7pakf">
                      <button type="button" class="lnb-btn-tit">3Depth-title</button>
                      <ul>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                        <li><a href="#" class="lnb-btn">4Depth</a></li>
                      </ul>
                    </div>
                    <!-- //lnb-submenu-lv2 -->
                  </li>
                  <li class="lnb-subitem"><a href="#" class="lnb-btn lnb-link">3Depth-link</a></li>
                  <li class="lnb-subitem"><a href="#" class="lnb-btn lnb-link">3Depth-link</a></li>
                </ul>
              </div>
              <!-- //lnb-submenu -->
            </li>
          </ul>
          <!-- //lnb-list -->
        </nav>
        <div class="contents">
          <KrdsBreadcrumb :items="[{ text: '홈' }, { text: '컴포넌트' }]" />
          <div class="page-title-wrap" data-type="responsive">
            <h1 class="h-tit">page title</h1>
            <div class="krds-drop-wrap h-tit-drop">
              <button type="button" class="h-tit drop-btn" aria-expanded="false">page title</button>
              <div class="drop-menu" style="display: none">
                <div class="drop-in">
                  <ul class="drop-list">
                    <li>
                      <a href="#" class="item-link">서비스 소개<span class="sr-only"></span></a>
                    </li>
                    <li>
                      <a href="#" class="item-link">국내에서 외국발간자료 신청<span class="sr-only"></span></a>
                    </li>
                    <li>
                      <a href="#" class="item-link">해외에서 국내발간자료 신청<span class="sr-only"></span></a>
                    </li>
                  </ul>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
    <KrdsFooter>
      <template #top>
        <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
        <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
        <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
        <button type="button" class="link" title="관련 사이트 레이어">related_site</button>
      </template>

      <template #logo>
        <span v-sr-only>KRDS - Korea Design System</span>
      </template>

      <template #content>
        <div class="f-info">
          <p class="info-addr">(26464) 강원특별자치도 원주시 건강로 32(반곡동) 국민건강보험공단</p>
          <ul class="info-cs">
            <li><strong class="strong">대표전화 1577-1000</strong><span class="span">(유료, 평일 09시~18시)</span></li>
            <li><strong class="strong">해외이용 82-33-811-2001</strong><span class="span">(유료, 평일 09시~18시)</span></li>
          </ul>
        </div>

        <div class="f-link">
          <div class="link-go">
            <KrdsButton text size="medium">찾아오시는 길 <i class="svg-icon ico-angle right"></i></KrdsButton>
            <KrdsButton text size="medium">이용안내 <i class="svg-icon ico-angle right"></i></KrdsButton>
            <KrdsButton text size="medium">직원검색 <i class="svg-icon ico-angle right"></i></KrdsButton>
          </div>
          <div class="link-sns">
            <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
              <span class="sr-only">인스타그램</span>
              <i class="svg-icon ico-instagram"></i>
            </a>
            <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
              <span class="sr-only">유튜브</span>
              <i class="svg-icon ico-youtube"></i>
            </a>
            <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
              <span class="sr-only">X</span>
              <i class="svg-icon ico-sns-x"></i>
            </a>
            <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
              <span class="sr-only">페이스북</span>
              <i class="svg-icon ico-facebook"></i>
            </a>
            <a href="#" class="krds-btn xlarge icon border" target="_blank" title="새 창 열기">
              <span class="sr-only">블로그</span>
              <i class="svg-icon ico-blog"></i>
            </a>
          </div>
        </div>
      </template>

      <template #bottom>
        <div class="f-btm-text">
          <div class="f-menu">
            <a href="#" class="point">개인정보처리방침</a>
            <a href="#">저작권 정책</a>
            <a href="#">웹 접근성 품질인증 마크 획득</a>
          </div>
          <p class="f-copy">© 2023 National Health Insurance Service. All rights reserved.</p>
        </div>
        <KrdsIdentifier>이 누리집은 보건복지부 누리집입니다.</KrdsIdentifier>
      </template>
    </KrdsFooter>
  </KrdsLayout>
</template>
```

## 스크롤 감지 비활성화

`enableScrollDetection`을 `false`로 지정하면 스크롤 클래스를 붙이지 않습니다.

```vue
<script setup lang="ts">
  import { KrdsLayout } from '@krds.ui/vue'
</script>

<template>
  <KrdsLayout :enable-scroll-detection="false">
    <div id="container" style="height: 200px; padding: 2rem">
      <p>스크롤 감지가 비활성화된 레이아웃</p>
    </div>
  </KrdsLayout>
</template>
```

## API

## KrdsLayout

### Props

| 이름 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| class | KrdsClassValue | - | CSS 클래스 |
| id | string | 'wrap' | 레이아웃 ID |
| enableScrollDetection | boolean | true | 스크롤 감지 활성화 여부 |

### Events

| 이름 | 인자 | 설명 |
| --- | --- | --- |
| resize | [size: LayoutSize] | 창 크기가 바뀔 때 (레이아웃 크기) |
| scroll | [details: ScrollDetails] | 스크롤할 때 (위치·방향) |
| scroll-height | [height: number] | 문서 스크롤 높이가 바뀔 때 |

### Slots

| 이름 | 설명 |
| --- | --- |
| default | 페이지 내용 (공식 배너·헤더·본문·푸터) |