@nurihaus/web-design-system 3.3.0 → 3.5.0

package/README.md

@@ -118,6 +118,42 @@ npm run tokens   # figma.json → tokens/generated/{tokens.css, *.ts}
 
 새 서비스가 다른 의미 토큰 값(버튼 색 등)을 써야 하면 `tokens/figma.json` 에 `semantic_{이름}` 세트를 추가하고 `npm run tokens` 를 돌린다. `<html data-ds-theme="{이름}">` 로 고르는 테마가 생긴다. 자세한 규칙은 `docs/tokens.md`.
 
+## 사용 로그
+
+컴포넌트가 사용자 상호작용을 이벤트로 내보내고, 어디로 보낼지는 앱이 정한다. 디자인시스템은 로그 수집기를 모른다.
+
+앱 루트에 `LogProvider` 를 한 번 둔다. `onEvent` 가 받은 이벤트를 앱의 로그 수집기로 보낸다.
+
+```tsx
+import { LogProvider } from '@nurihaus/web-design-system/logging';
+
+export default function App({ children }) {
+  return <LogProvider onEvent={(event) => console.log(event)}>{children}</LogProvider>;
+}
+```
+
+컴포넌트에 `track` 을 준다. 누르면 `{ component: 'CTAButton', action: 'click', track: 'report/download', props: { format: 'csv' }, timestamp }` 가 `onEvent` 로 간다.
+
+```tsx
+<CTAButton text='리포트 받기' track='report/download' trackProps={{ format: 'csv' }} />
+```
+
+`track` 을 받는 컴포넌트는 CTAButton · DataTable(`click`), Modal · Drawer(`open` · `close`), Tabs · DropDown · ChipGroup · Radio · Checkbox · Switch · Pagination · TextField · TextArea(`change`), BottomNav · Breadcrumb · CollapsibleMenu(`navigate`), Toast · Tooltip(`show`) 다. `value` 에는 탭 id · 칩 id · 옵션 value 처럼 개발자가 정한 id 만 들어간다. TextField · TextArea 는 포커스가 빠질 때 값이 바뀌었으면 값 없이 `change` 를 한 번 보낸다. `LogProvider` 가 없거나 `track` 을 주지 않으면 아무것도 보내지 않는다.
+
+컴포넌트 밖의 로그는 `useLog` 로 남긴다.
+
+```tsx
+import { useEffect } from 'react';
+
+import { useLog } from '@nurihaus/web-design-system/logging';
+
+const ReportPage = () => {
+  const log = useLog();
+  useEffect(() => log({ component: 'ReportPage', action: 'view', track: 'report/view' }), [log]);
+  // …
+};
+```
+
 ## AI 설명서
 
 배포물의 `dist/ai/` 에 쓰는 쪽 AI 가 읽는 설명서가 들어 있다.

package/dist/ai/components.md

@@ -30,12 +30,33 @@ import '@nurihaus/web-design-system/components.css';
 
 **Tooltip 이 여러 개면 `TooltipProvider` 로 감싼다.** 앱 루트에 한 번 두면 된다. 조건이 맞을 때만 띄우려면 `open` 을 제어하지 말고 `disabled` 를 쓴다.
 
+**사용 로그는 `track` 으로 남긴다.** 앱 루트에 `LogProvider` 를 한 번 두고 `onEvent` 에서 로그 수집기로 보낸다. 컴포넌트에 `track="report/download"` 처럼 개발자가 정한 이름을 주면 아래 상호작용이 이벤트로 나간다. `component` 는 컴포넌트의 displayName 이다(Checkbox 는 `'CheckBox'`).
+
+| 컴포넌트 | 보내는 때 | action | value |
+| --- | --- | --- | --- |
+| CTAButton | 누를 때 | `click` | 없음 |
+| DataTable | `onClickRow` 가 있는 헤더 칸을 누를 때 | `click` | 그 칸의 `id` |
+| Modal · Drawer | 열고 닫을 때 | `open` · `close` | 없음 |
+| Tabs · DropDown · ChipGroup · Radio | 고를 때 | `change` | 탭 id · 옵션 value · 칩 id · 선택지 id |
+| Checkbox · Switch | 켜고 끌 때 | `change` | `'on'` · `'off'` |
+| Pagination | 페이지가 바뀔 때 | `change` | 페이지 번호(문자열) |
+| TextField · TextArea | 포커스가 빠질 때, 포커스를 받을 때와 값이 다르면 한 번 | `change` | 없음 |
+| BottomNav | 탭을 누를 때 | `navigate` | 탭 id |
+| Breadcrumb | 현재 위치가 아닌 링크를 누를 때 | `navigate` | 항목 `id` |
+| CollapsibleMenu | 링크·버튼 항목을 고를 때. 그룹 여닫기는 보내지 않는다 | `navigate` | 항목 `key` |
+| Toast · Tooltip | 뜰 때 | `show` | 없음 |
+
+`value` 에는 개발자가 정한 id 만 들어가고 사용자가 입력한 글자는 들어가지 않는다. TextField · TextArea 가 값을 싣지 않는 것도 그래서다. 더 붙일 값은 `trackProps` 로 준다. `LogProvider` 가 없거나 `track` 이 없으면 아무것도 보내지 않는다. 컴포넌트 밖의 로그(화면 진입 등)는 `useLog` 를 쓴다.
+
+Avatar · OptionBadge · IconTextBadge · IconTextOptionBadge · Skeleton · Text · Icon · StepProgress · Spinner · InlineLoading · OverlayLoading 은 상호작용 핸들러가 없어 `track` 을 받지 않는다. ModalWithDoubleButton 은 `left` · `right` 가 CTAButton props 라 거기에 `track` 을 준다.
+
 **없는 것은 지어내지 않는다.** 이 문서 끝의 "아직 없는 것" 표에 있는 컴포넌트는 없다. 없는 prop · variant · 토큰 이름도 만들지 않는다. 틀린 variant 나 size 값은 타입 오류가 난다.
 
 ## 목록
 
 - [Avatar](#avatar)
 - [CTAButton](#ctabutton)
+- [Callout](#callout)
 - [OptionBadge](#optionbadge)
 - [IconTextBadge](#icontextbadge)
 - [IconTextOptionBadge](#icontextoptionbadge)
@@ -66,6 +87,7 @@ import '@nurihaus/web-design-system/components.css';
 - [BottomNav](#bottomnav)
 - [StepProgress](#stepprogress)
 - [ChipGroup](#chipgroup)
+- [LogProvider](#logprovider)
 
 ## Avatar
 
@@ -102,12 +124,21 @@ import { CTAButton } from '@nurihaus/web-design-system/cta-button';   // 이 컴
 import { CTAButton } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
 ```
 
-**언제 쓴다.** 저장, 확인, 다음 단계처럼 사용자가 실행하는 동작 버튼에 쓴다. `variant`로 강조 단계를 고르고, `loading`이 true면 `text` 대신 Spinner가 표시된다.
+**언제 쓴다.** 저장, 확인, 다음 단계처럼 사용자가 실행하는 동작 버튼에 쓴다. `variant`로 강조 단계를 고르고, `loading`이 true면 `text` 대신 Spinner가 표시된다. Google·Apple·Facebook 로그인 버튼은 `variant="social"`(흰 바탕·검정 글자, 공급자 가이드)에 공급자 로고를 `leftIcon`으로 준다. `callout`을 주면 버튼 오른쪽 위 모서리에 말풍선(Callout)을 끼운다(예: "최근 사용") — 버튼 글자는 움직이지 않고 자리는 DS 가 잡는다. 말풍선 글자도 버튼 안이라 버튼의 접근 가능한 이름에 이어진다(스크린 리더도 "최근 사용"을 듣는다).
 
 **쓰지 않는다.** 확인과 취소 두 버튼을 가진 대화상자는 버튼을 직접 배치하지 말고 ModalWithDoubleButton을 쓴다. 화면 안의 패널 전환은 Tabs, 사이드 메뉴 항목은 CollapsibleMenu를 쓴다.
 
 ```tsx
-<CTAButton variant="primary" size="m" text="저장" onClick={() => {}} />
+<>
+  <CTAButton variant="primary" size="m" text="저장" onClick={() => {}} />
+  <CTAButton
+    variant="social"
+    size="l"
+    text="Google로 계속하기"
+    leftIcon={<img src="/icons/google.svg" alt="" />}
+    callout="최근 사용"
+  />
+</>
 ```
 
 ### props
@@ -115,14 +146,45 @@ import { CTAButton } from '@nurihaus/web-design-system';             // 루트.
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` |  | `'m'` |
+| `track` | `string` |  |  |
 | `text` | `ReactNode` | 예 |  |
-| `variant` | `'neutral' \| 'primary' \| 'outlined' \| 'secondary' \| 'ghost' \| 'confirm'` |  | `'primary'` |
+| `variant` | `'neutral' \| 'primary' \| 'outlined' \| 'secondary' \| 'ghost' \| 'confirm' \| 'social'` |  | `'primary'` |
 | `leftIcon` | `ReactNode` |  |  |
 | `rightIcon` | `ReactNode` |  |  |
+| `callout` | `ReactNode` |  |  |
 | `loading` | `boolean` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 276개를 받는다.
 
+## Callout
+
+```ts
+import { Callout } from '@nurihaus/web-design-system/callout';   // 이 컴포넌트만 싣는다 (권장)
+import { Callout } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 버튼 같은 대상에 붙어 늘 떠 있는 짧은 라벨 말풍선에 쓴다(예: 로그인 버튼의 "최근 사용"). 꼬리 자리는 `tail`(`bottom-start` 기본·`bottom-end`·`top-start`·`top-end`)로 고른다. 버튼에 붙일 때는 Callout 을 직접 놓지 말고 CTAButton 의 `callout` prop 을 쓴다 — 모서리 자리를 DS 가 잡는다. 그 밖의 대상에 놓을 때는 자리(`position: absolute`·위치)를 쓰는 쪽이 `className` 으로 정한다. `.base-callout` 이 꼬리 기준으로 `position: relative` 를 가지므로 한 단계 구체적인 선택자(`.slot > .x`)로 덮는다.
+
+**쓰지 않는다.** 마우스를 올리거나 포커스했을 때만 설명을 보여 주려면 Tooltip 을 쓴다. 상태값·분류 라벨은 OptionBadge 를 쓴다.
+
+```tsx
+<>
+  <Callout text="최근 사용" />
+  <Callout text="새 기능" tail="top-end" />
+  <CTAButton variant="social" size="l" text="Google로 계속하기" callout="최근 사용" />
+</>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `text` | `ReactNode` | 예 |  |
+| `tail` | `'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'` |  | `'bottom-start'` |
+
+이 밖에 React·HTML 기본 속성 265개를 받는다.
+
 ## OptionBadge
 
 ```ts
@@ -130,7 +192,7 @@ import { OptionBadge } from '@nurihaus/web-design-system/option-badge';   // 이
 import { OptionBadge } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
 ```
 
-**언제 쓴다.** 상태값이나 분류처럼 짧은 값 하나(`option`)를 라벨로 보여줄 때 쓴다. `variant`로 색을 고른다(`neutral`·`primary`·`danger`·`outlined`). 색 prop 은 없다. `tooltip`을 주면 마우스를 올렸을 때 설명이 뜬다.
+**언제 쓴다.** 상태값이나 분류처럼 짧은 값 하나(`option`)를 라벨로 보여줄 때 쓴다. `variant`로 색을 고른다(`neutral`·`primary`·`danger`·`outlined`). 색 prop 은 없다. `tooltip`을 주면 마우스를 올렸을 때 설명이 뜬다. 대상에 붙어 늘 떠 있는 말풍선은 Callout 을 쓴다.
 
 **쓰지 않는다.** 아이콘이 함께 필요하면 IconTextBadge를, 아이콘과 텍스트 오른쪽에 수치 같은 부가 값까지 붙여야 하면 IconTextOptionBadge를 쓴다. 클릭 동작이 필요한 요소에는 CTAButton을 쓴다.
 
@@ -235,6 +297,8 @@ import { DataTable } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 여러 레코드를 열 단위로 나열하는 목록 화면에 쓴다. 이름과 달리 `rows`는 헤더 열 정의(`id`, 헤더 내용)이고 `columns`는 데이터 행 배열이며, 각 데이터 행은 `rows`의 모든 `id`를 키로 가진다. 열 너비는 셀 내용의 너비를 따르므로 같은 열의 헤더와 셀 내용에 같은 너비를 준다.
 
+`track`을 주면 `onClickRow`가 있는 `rows` 항목(헤더 칸)을 누를 때 `click`과 그 `id`를 `value`에 담아 사용 로그로 보낸다. `onClickRow`가 없는 칸과 본문 셀은 보내지 않는다.
+
 **쓰지 않는다.** 정렬, 페이지네이션, 행 선택, 빈 상태 표시는 내장되어 있지 않으므로 데이터를 바깥에서 가공해 넘기고 빈 목록은 따로 그린다. 헤더는 위에 고정되고 `fixedRowsIndex`로 왼쪽 열을 고정할 수 있지만, 그 외의 표 동작이 필요하면 직접 만든다.
 
 ```tsx
@@ -264,6 +328,8 @@ import { DataTable } from '@nurihaus/web-design-system';             // 루트.
 | `rowHeight` | `number` |  | `60` |
 | `cellHeight` | `number` |  |  |
 | `className` | `string` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -276,6 +342,8 @@ import { TextField } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 한 줄 텍스트를 입력받을 때 쓴다. 위 라벨(`title`), 아래 안내 문구(`helperText`), 좌우 아이콘을 함께 붙일 수 있고, `isError`가 true면 `helperText`가 오류 스타일로 바뀐다.
 
+`track`을 주면 포커스가 빠질 때 값이 포커스를 받을 때와 다르면 `change`를 한 번 사용 로그로 보낸다. 값은 싣지 않는다. 사용자가 입력한 글자는 로그에 들어가지 않는다.
+
 **쓰지 않는다.** 여러 줄 입력은 지원하지 않는다(`<input>`만 렌더한다). 정해진 값 중에서 고르는 입력은 DropDown이나 Radio를 쓴다.
 
 ```tsx
@@ -297,11 +365,13 @@ import { TextField } from '@nurihaus/web-design-system';             // 루트.
 | `className` | `string` |  |  |
 | `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` | 예 | `'s'` |
 | `title` | `ReactNode` |  |  |
+| `track` | `string` |  |  |
 | `name` | `string` | 예 |  |
 | `value` | `string` |  |  |
 | `defaultValue` | `string` |  |  |
 | `leftIcon` | `ReactNode` |  |  |
 | `rightIcon` | `ReactNode` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `width` | `string \| number` | 예 | `'100%'` |
 | `helperText` | `ReactNode` |  |  |
 | `isError` | `boolean` |  |  |
@@ -317,6 +387,8 @@ import { Radio } from '@nurihaus/web-design-system';             // 루트. 첫
 
 **언제 쓴다.** 몇 개의 선택지를 모두 펼쳐 보여주고 그중 하나만 고르게 할 때 쓴다. 선택 상태는 항상 부모가 가지므로 `onChange`에서 받은 id로 `selected`를 갱신해야 선택이 바뀐다.
 
+`track`을 주면 선택지를 누를 때 `change`와 그 선택지 `id`를 `value`에 담아 사용 로그로 보낸다.
+
 **쓰지 않는다.** 여러 개를 동시에 고르면 Checkbox를 쓴다. 선택지가 많아 모두 펼치기 어려우면 DropDown을 쓴다.
 
 ```tsx
@@ -338,6 +410,8 @@ import { Radio } from '@nurihaus/web-design-system';             // 루트. 첫
 | `options` | `{ id: string; label: ReactNode; disabled?: boolean \| undefined; }[]` | 예 |  |
 | `selected` | `string \| null` |  |  |
 | `onChange` | `((id: string \| null) => void)` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -350,6 +424,8 @@ import { Checkbox } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 동의 여부처럼 켜고 끄는 값 하나를 받거나, 목록의 항목을 각각 독립적으로 선택할 때 쓴다. `onChange`는 바뀐 체크 상태(boolean)를 받는다.
 
+`track`을 주면 체크 상태가 바뀔 때마다 `change`와 `'on'`·`'off'`를 `value`에 담아 사용 로그로 보낸다. 이벤트의 `component`는 displayName 인 `'CheckBox'`다.
+
 **쓰지 않는다.** 여러 선택지 중 하나만 골라야 하면 Radio를, 목록에서 값 하나를 고르면 DropDown을 쓴다.
 
 ```tsx
@@ -368,6 +444,8 @@ import { Checkbox } from '@nurihaus/web-design-system';             // 루트.
 | `onChange` | `((checked: boolean) => void)` |  |  |
 | `id` | `string` | 예 |  |
 | `disabled` | `boolean` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -380,6 +458,8 @@ import { Switch } from '@nurihaus/web-design-system';             // 루트. 첫
 
 **언제 쓴다.** 알림 켜기처럼 켜고 끄는 설정 하나를 바로 반영할 때 쓴다. `onChange`는 바뀐 켜짐 상태(boolean)를 받는다. `className`·`style`은 루트 버튼에 붙는다. `label`을 주지 않으면 `aria-label`로 이름을 준다.
 
+`track`을 주면 켜짐 상태가 바뀔 때마다 `change`와 `'on'`·`'off'`를 `value`에 담아 사용 로그로 보낸다.
+
 **쓰지 않는다.** 제출 버튼을 눌러야 반영되는 폼 항목이나 동의 여부는 Checkbox를, 여러 선택지 중 하나는 Radio를 쓴다.
 
 ```tsx
@@ -393,10 +473,12 @@ import { Switch } from '@nurihaus/web-design-system';             // 루트. 첫
 | `className` | `string` |  |  |
 | `size` | `'s' \| 'm' \| 'l'` |  | `'m'` |
 | `label` | `ReactNode` |  |  |
+| `track` | `string` |  |  |
 | `disabled` | `boolean` |  |  |
 | `defaultChecked` | `boolean` |  |  |
 | `id` | `string` | 예 |  |
 | `onChange` | `((checked: boolean) => void)` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `checked` | `boolean` |  |  |
 
 이 밖에 React·HTML 기본 속성 270개를 받는다.
@@ -410,6 +492,8 @@ import { TextArea } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 메모·설명처럼 여러 줄 텍스트를 입력받을 때 쓴다. 위 라벨(`title`), 아래 안내 문구(`helperText`)를 함께 붙일 수 있고, `isError`가 true면 `helperText`가 오류 스타일로 바뀐다. 높이는 `rows`가 정하고 `size`는 글자 크기와 안쪽 여백만 바꾼다. `resize`는 `'vertical'`(기본)·`'none'` 중 고른다. `className`·`style`은 textarea를 감싸는 테두리 요소에 붙고, `ref`는 textarea 요소를 가리킨다.
 
+`track`을 주면 포커스가 빠질 때 값이 포커스를 받을 때와 다르면 `change`를 한 번 사용 로그로 보낸다. 값은 싣지 않는다. 사용자가 입력한 글자는 로그에 들어가지 않는다.
+
 **쓰지 않는다.** 한 줄 입력은 TextField를 쓴다. 정해진 값 중에서 고르는 입력은 DropDown이나 Radio를 쓴다.
 
 ```tsx
@@ -423,9 +507,11 @@ import { TextArea } from '@nurihaus/web-design-system';             // 루트.
 | `className` | `string` |  |  |
 | `size` | `'s' \| 'm'` |  | `'s'` |
 | `title` | `ReactNode` |  |  |
+| `track` | `string` |  |  |
 | `name` | `string` | 예 |  |
 | `value` | `string` |  |  |
 | `defaultValue` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `width` | `string \| number` |  | `'100%'` |
 | `resize` | `'none' \| 'vertical'` |  | `'vertical'` |
 | `helperText` | `ReactNode` |  |  |
@@ -455,8 +541,10 @@ import { Toast } from '@nurihaus/web-design-system';             // 루트. 첫
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
 | `title` | `ReactNode` | 예 |  |
+| `track` | `string` |  |  |
 | `onPause` | `(() => void)` |  |  |
 | `variant` | `'secondary' \| 'default' \| 'success' \| 'warning' \| 'error'` |  | `'default'` |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `onResume` | `(() => void)` |  |  |
 | `open` | `boolean` |  |  |
 | `defaultOpen` | `boolean` |  |  |
@@ -503,6 +591,8 @@ import { Pagination } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 목록이나 검색 결과가 여러 페이지로 나뉘어 있고 사용자가 번호로 페이지를 고를 때 쓴다. `totalPages`는 필수다. 현재 페이지는 `page`(controlled)·`defaultPage`(uncontrolled)로 주고, `onPageChange`는 새 페이지 번호(1부터)를 받는다. 1과 마지막 페이지는 항상 보이고, 현재 페이지 양옆 `siblingCount`(기본 1)개를 보이며 사이가 벌어지면 `…`를 넣는다. `className`·`style`은 루트 `nav`에 붙는다. `aria-label`을 주면 nav 이름을 바꾼다(기본 "페이지 탐색").
 
+`track`을 주면 페이지가 바뀔 때 `change`와 새 페이지 번호(문자열)를 `value`에 담아 사용 로그로 보낸다. 현재 페이지를 다시 누르면 보내지 않는다.
+
 **쓰지 않는다.** 스크롤로 계속 불러오는 목록이나 "더 보기" 버튼으로 이어 붙이는 목록에는 쓰지 않는다. 화면 안의 내용 영역을 바꾸는 탭 전환은 Tabs를 쓴다.
 
 ```tsx
@@ -514,7 +604,9 @@ import { Pagination } from '@nurihaus/web-design-system';             // 루트.
 | prop | 타입 | 필수 | 기본값 |
 | --- | --- | --- | --- |
 | `size` | `'s' \| 'm'` |  | `'m'` |
+| `track` | `string` |  |  |
 | `disabled` | `boolean` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 | `page` | `number` |  |  |
 | `totalPages` | `number` | 예 |  |
 | `defaultPage` | `number` |  |  |
@@ -562,6 +654,8 @@ import { Modal } from '@nurihaus/web-design-system';             // 루트. 첫
 | `onOpenChange` | `((open: boolean) => void)` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -599,6 +693,8 @@ import { Drawer } from '@nurihaus/web-design-system';             // 루트. 첫
 | `onOpenChange` | `((open: boolean) => void)` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -638,6 +734,8 @@ import { Breadcrumb } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 계층이 있는 화면에서 현재 위치와 상위 경로를 한 줄로 보여 줄 때 쓴다. `items`의 마지막 항목이 현재 위치라 링크가 아니고 `aria-current="page"`가 붙는다. `href`가 있는 항목은 `<a>` 링크로, `onItemClick`은 클릭한 항목의 `id`를 받는다. Next.js 나 React Router 안에서는 `linkComponent={Link}`를 넘겨 라우터 링크로 그린다. 넘기지 않으면 일반 `<a>`라 페이지가 새로 고쳐진다. `className`·`style`은 `nav` 루트에 붙는다.
 
+`track`을 주면 링크 항목을 누를 때 `navigate`와 그 항목의 `id`를 `value`에 담아 사용 로그로 보낸다. 마지막(현재 위치) 항목은 링크가 아니라 보내지 않는다.
+
 **쓰지 않는다.** 같은 깊이의 화면을 오가는 데는 Tabs를, 사이드바 메뉴에는 CollapsibleMenu를 쓴다. 계층이 한 단계뿐이면 쓰지 않는다.
 
 ```tsx
@@ -661,6 +759,8 @@ import { Breadcrumb } from '@nurihaus/web-design-system';             // 루트.
 | `linkComponent` | `ElementType` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -714,6 +814,8 @@ import { DropDown } from '@nurihaus/web-design-system';             // 루트.
 | `position` | `'popper' \| 'item-aligned'` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -726,6 +828,8 @@ import { CollapsibleMenu } from '@nurihaus/web-design-system';             //
 
 **언제 쓴다.** 사이드바 같은 세로 내비게이션 메뉴에 쓴다. `children`이 있는 항목은 펼치고 접는 그룹이 되고, 없는 항목은 `href`가 있으면 링크, 없으면 버튼으로 렌더되며, `activeKey` 항목과 그 상위 그룹이 강조된다. 링크는 기본으로 `<a>`다. 라우터의 링크로 바꾸려면 `linkComponent`에 넘긴다. 받는 props는 `href`·`className`·`children`·`onClick`·`aria-current`·`aria-disabled`이고, 그대로 링크에 전달하면 된다.
 
+`track`을 주면 링크·버튼 항목을 고를 때 `navigate`와 그 항목의 `key`를 `value`에 담아 사용 로그로 보낸다. 그룹을 펼치고 접는 것은 보내지 않는다.
+
 **쓰지 않는다.** 같은 화면 안에서 패널을 바꾸는 용도는 Tabs를 쓴다. 본문 콘텐츠를 접고 펼치는 아코디언 용도로는 쓰지 않는다(`<nav>`로 렌더된다). 값을 고르는 폼 입력은 DropDown을 쓴다.
 
 Next.js 에서는 `next/link` 의 `Link` 를 그대로 넘긴다.
@@ -770,6 +874,8 @@ import Link from 'next/link';
 | `linkComponent` | `ComponentType<CollapsibleMenuLinkProps>` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -813,6 +919,8 @@ import { Tooltip } from '@nurihaus/web-design-system';             // 루트.
 
 **언제 쓴다.** 아이콘이나 짧은 라벨에 마우스를 올렸을 때 짧은 설명을 띄울 때 쓴다. `trigger`에는 DOM 요소 하나(예: `<span>`)를 넘기고 `direction`으로 뜨는 방향을 고른다. 조건이 맞을 때만 띄우려면 `open`을 제어하지 말고 `disabled`를 쓴다(예: 사이드바가 접혔을 때만 `disabled={!collapsed}`). `disabled`이면 `trigger`만 그려 툴팁이 열린 채 남지 않는다.
 
+`track`을 주면 툴팁이 열릴 때 `show`를 사용 로그로 보낸다. 닫힐 때와 `disabled`일 때는 보내지 않는다.
+
 **쓰지 않는다.** 툴팁 안에 링크나 버튼처럼 클릭할 내용을 넣지 않는다. 툴팁 위로 마우스를 옮기면 닫힌다. 배지에 설명을 붙일 때는 OptionBadge, IconTextBadge의 `tooltip` prop을 쓴다.
 
 ```tsx
@@ -832,6 +940,8 @@ import { Tooltip } from '@nurihaus/web-design-system';             // 루트.
 | `onOpenChange` | `((open: boolean) => void)` |  |  |
 | `delayDuration` | `number` |  |  |
 | `disableHoverableContent` | `boolean` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -895,6 +1005,8 @@ import { Tabs } from '@nurihaus/web-design-system';             // 루트. 첫
 | `onValueChange` | `((id: TabsValue) => void)` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -1077,7 +1189,7 @@ import { BottomNav } from '@nurihaus/web-design-system';             // 루트.
 
 화면 아래에 고정(`position: fixed`)되고 내용 위에 떠 있다. 화면 본문은 아래를 `calc(var(--bottom-nav-space) + env(safe-area-inset-bottom))` 만큼 비워 마지막 내용이 가려지지 않게 한다. `className`·`style` 은 `<nav>` 에 붙는다.
 
-링크는 기본으로 `<a>` 다. 라우터의 링크로 바꾸려면 `linkComponent` 에 넘긴다. 받는 props 는 `href`·`className`·`children`·`aria-current` 이고, 그대로 링크에 전달하면 된다.
+링크는 기본으로 `<a>` 다. 라우터의 링크로 바꾸려면 `linkComponent` 에 넘긴다. 받는 props 는 `href`·`className`·`children`·`aria-current`·`onClick` 이고, 그대로 링크에 전달하면 된다. `onClick` 을 빠뜨리면 `track` 로그가 나가지 않는다.
 
 배지는 `badge` 로 단다. `count` 가 없으면 점, 있으면 숫자(99 넘으면 99+)다. `label` 은 화면 낭독기가 읽는 말이다.
 
@@ -1114,6 +1226,8 @@ import Link from 'next/link';
 | `linkComponent` | `ComponentType<BottomNavLinkProps>` |  |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
@@ -1186,9 +1300,38 @@ import { ChipGroup } from '@nurihaus/web-design-system';             // 루트.
 | `label` | `string` | 예 |  |
 | `className` | `string` |  |  |
 | `style` | `CSSProperties` |  |  |
+| `track` | `string` |  |  |
+| `trackProps` | `Record<string, string \| number \| boolean>` |  |  |
 
 이 밖에 React·HTML 기본 속성 2개를 받는다.
 
+## LogProvider
+
+```ts
+import { LogProvider } from '@nurihaus/web-design-system/logging';   // 이 컴포넌트만 싣는다 (권장)
+import { LogProvider } from '@nurihaus/web-design-system';             // 루트. 첫 로드 JS 가 커진다
+```
+
+**언제 쓴다.** 앱 루트에 한 번 두고 사용 로그를 받는다. 디자인시스템 컴포넌트에 `track` 을 주면 그 컴포넌트의 상호작용이 이벤트 하나(`LogEvent`)로 `onEvent` 에 온다. 이벤트를 어느 로그 수집기로 보낼지는 `onEvent` 안에서 앱이 정한다. `onEvent` 가 던져도 화면 동작은 멈추지 않는다.
+`track` 에는 `'report/download'` 처럼 개발자가 정한 이름을 쓴다. 이벤트의 `value` 에는 탭 id·칩 id·옵션 value 처럼 개발자가 정한 id 만 들어가고 사용자가 입력한 글자는 들어가지 않는다. 더 붙일 값은 `trackProps` 로 명시한다.
+LogProvider 가 없거나 `track` 을 주지 않으면 아무것도 보내지 않는다.
+컴포넌트 밖의 로그(화면 진입, 직접 만든 요소)는 `useLog()` 가 돌려주는 함수에 `{ component, action, track }` 을 넘긴다. `timestamp` 는 자동으로 붙는다.
+
+**쓰지 않는다.** 에러 보고에 쓰지 않는다. 에러는 앱의 에러 처리에서 따로 남긴다. 화면마다 LogProvider 를 겹쳐 두지 않는다. 안쪽 Provider 가 바깥 것을 가린다.
+
+```tsx
+<LogProvider onEvent={(event) => console.log(event)}>
+  <CTAButton text="리포트 받기" track="report/download" trackProps={{ format: "csv" }} />
+</LogProvider>
+```
+
+### props
+
+| prop | 타입 | 필수 | 기본값 |
+| --- | --- | --- | --- |
+| `onEvent` | `(event: LogEvent) => void` | 예 |  |
+| `children` | `ReactNode` |  |  |
+
 ## 아직 없는 것
 
 아래는 디자인 시스템에 없다. 비슷한 이름의 컴포넌트를 지어내 import 하지 않는다.

package/dist/avatar.js

@@ -280,7 +280,7 @@ module.exports = x({ ["jsx"]: () => (__WEBPACK_EXTERNAL_MODULE_react_jsx_runtime
 /******/ 	// undefined = chunk not loaded, null = chunk preloaded/prefetched
 /******/ 	// [resolve, Promise] = chunk loading, 0 = chunk loaded
 /******/ 	var installedChunks = {
-/******/ 		716: 0
+/******/ 		8716: 0
 /******/ 	};
 /******/ 	
 /******/ 	var installChunk = (data) => {
@@ -320,17 +320,17 @@ module.exports = x({ ["jsx"]: () => (__WEBPACK_EXTERNAL_MODULE_react_jsx_runtime
 /******/ 
 /************************************************************************/
 /******/ 
-/******/ import * as __webpack_chunk_1__ from "./chunk-364.js";
+/******/ import * as __webpack_chunk_1__ from "./chunk-6364.js";
 /******/ __nuri_require__.C(__webpack_chunk_1__);
-/******/ import * as __webpack_chunk_2__ from "./chunk-777.js";
+/******/ import * as __webpack_chunk_2__ from "./chunk-2777.js";
 /******/ __nuri_require__.C(__webpack_chunk_2__);
-/******/ import * as __webpack_chunk_3__ from "./chunk-298.js";
+/******/ import * as __webpack_chunk_3__ from "./chunk-7298.js";
 /******/ __nuri_require__.C(__webpack_chunk_3__);
 /******/ 
 /******/ // startup
 /******/ // Load entry module and return exports
 /******/ // This entry module depends on other loaded chunks and execution need to be delayed
-/******/ var __webpack_exports__ = __nuri_require__.O(undefined, [364,777,298], () => (__nuri_require__(5468)))
+/******/ var __webpack_exports__ = __nuri_require__.O(undefined, [6364,2777,7298], () => (__nuri_require__(5468)))
 /******/ __webpack_exports__ = __nuri_require__.O(__webpack_exports__);
 /******/ const __webpack_exports__default = __webpack_exports__.A;
 /******/ export { __webpack_exports__default as default };

package/dist/bottom-nav.js

@@ -17,6 +17,8 @@ __nuri_require__.d(__webpack_exports__, {
 var jsx_runtime_ = __nuri_require__(612);
 // EXTERNAL MODULE: external {"root":"React","commonjs2":"react","commonjs":"react","amd":"react","module":"react"}
 var external_root_React_commonjs2_react_commonjs_react_amd_react_module_react_ = __nuri_require__(1041);
+// EXTERNAL MODULE: ./helpers/hooks/useTrack.ts
+var useTrack = __nuri_require__(4560);
 // EXTERNAL MODULE: ./helpers/utils/classNames.js
 var classNames = __nuri_require__(3274);
 // EXTERNAL MODULE: ./helpers/utils/getMergedProps.ts
@@ -118,6 +120,7 @@ var bottom_nav_assign = undefined && undefined.__assign || function () {
 
 
 
+
 var Anchor = function Anchor(props) {
   return (0,jsx_runtime_.jsx)("a", bottom_nav_assign({}, props));
 };
@@ -130,7 +133,13 @@ var BottomNav = /*#__PURE__*/(0,external_root_React_commonjs2_react_commonjs_rea
     items = _a.items,
     value = _a.value,
     label = _a.label,
-    linkComponent = _a.linkComponent;
+    linkComponent = _a.linkComponent,
+    track = _a.track,
+    trackProps = _a.trackProps;
+  var emit = (0,useTrack/* useTrack */.n)('BottomNav', {
+    track: track,
+    trackProps: trackProps
+  });
   var Link = linkComponent !== null && linkComponent !== void 0 ? linkComponent : Anchor;
   var activeIndex = items.findIndex(function (item) {
     return item.id === value;
@@ -153,6 +162,9 @@ var BottomNav = /*#__PURE__*/(0,external_root_React_commonjs2_react_commonjs_rea
         className: itemClassName,
         href: item.href,
         "aria-current": isActive ? 'page' : undefined,
+        onClick: function onClick() {
+          return emit('navigate', item.id);
+        },
         children: [(0,jsx_runtime_.jsx)("span", {
           className: 'bottom-nav-label',
           children: item.label
@@ -244,7 +256,7 @@ var x = (y) => {
 	var x = {}; __nuri_require__.d(x, y); return x
 } 
 var y = (x) => (() => (x))
-module.exports = x({ ["forwardRef"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.forwardRef) });
+module.exports = x({ ["createContext"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.createContext), ["forwardRef"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.forwardRef), ["useCallback"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.useCallback), ["useContext"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.useContext), ["useRef"]: () => (__WEBPACK_EXTERNAL_MODULE_react__.useRef) });
 
 /***/ },
 
@@ -349,8 +361,8 @@ module.exports = x({ ["jsx"]: () => (__WEBPACK_EXTERNAL_MODULE_react_jsx_runtime
 /******/ 	// undefined = chunk not loaded, null = chunk preloaded/prefetched
 /******/ 	// [resolve, Promise] = chunk loading, 0 = chunk loaded
 /******/ 	var installedChunks = {
-/******/ 		480: 0,
-/******/ 		918: 0
+/******/ 		918: 0,
+/******/ 		6480: 0
 /******/ 	};
 /******/ 	
 /******/ 	var installChunk = (data) => {
@@ -390,17 +402,19 @@ module.exports = x({ ["jsx"]: () => (__WEBPACK_EXTERNAL_MODULE_react_jsx_runtime
 /******/ 
 /************************************************************************/
 /******/ 
-/******/ import * as __webpack_chunk_1__ from "./chunk-364.js";
+/******/ import * as __webpack_chunk_1__ from "./chunk-6364.js";
 /******/ __nuri_require__.C(__webpack_chunk_1__);
-/******/ import * as __webpack_chunk_2__ from "./chunk-298.js";
+/******/ import * as __webpack_chunk_2__ from "./chunk-4560.js";
 /******/ __nuri_require__.C(__webpack_chunk_2__);
-/******/ import * as __webpack_chunk_3__ from "./chunk-653.js";
+/******/ import * as __webpack_chunk_3__ from "./chunk-7298.js";
 /******/ __nuri_require__.C(__webpack_chunk_3__);
+/******/ import * as __webpack_chunk_4__ from "./chunk-7653.js";
+/******/ __nuri_require__.C(__webpack_chunk_4__);
 /******/ 
 /******/ // startup
 /******/ // Load entry module and return exports
 /******/ // This entry module depends on other loaded chunks and execution need to be delayed
-/******/ var __webpack_exports__ = __nuri_require__.O(undefined, [364,298,653], () => (__nuri_require__(1768)))
+/******/ var __webpack_exports__ = __nuri_require__.O(undefined, [6364,4560,7298,7653], () => (__nuri_require__(1768)))
 /******/ __webpack_exports__ = __nuri_require__.O(__webpack_exports__);
 /******/ const __webpack_exports__default = __webpack_exports__.A;
 /******/ export { __webpack_exports__default as default };