@mindlogic-ai/logician-ui 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/components/Tabs/Tabs.usage.mdx

@@ -25,16 +25,35 @@ One section shows at a time.
 ## When not to use
 
 - To change how the same content is shown, or to filter it (일/주/월, 목록/카드)
-  → `SegmentedControl`. Tabs change *what* you are looking at, not how.
+  → `SegmentedControl`. Tabs change _what_ you are looking at, not how.
 - For the steps of a flow the user must complete in order → a stepper or a
   sequence of pages. Tabs let the user jump ahead.
-- To move to another page of the app → navigation links or `Breadcrumb`.
+- For destinations or filters, such as the side navigation of an area or a
+  filter rail beside a list, and for a list that is long or keeps growing, or
+  whose rows carry counts or icons → `NavList`. Tabs own their panels, move
+  with the arrow keys and mark the choice with `aria-selected`; a rail is
+  links or filters, reached with Tab.
+- To show where this page sits in a hierarchy → `Breadcrumb`.
 - For two or three short panels the user needs side by side → show them on
   the page.
 
+## Which component
+
+Tabs and `NavList` both mark one row as current; they say the same thing from
+opposite sides. Pick by what the rows are:
+
+| What you have                                                    | Use                                                                                          |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| A few sections of one object that swap a panel in place          | `Tabs`                                                                                       |
+| Destinations, or the side navigation of an area                  | `NavList`, each item with `href`                                                             |
+| A filter over one list or grid, with many options or with counts | `NavList`: links (`href`) when the filter state is in the URL, buttons (`onClick`) otherwise |
+| A short horizontal switch of two to five options                 | `SegmentedControl`                                                                           |
+| A hierarchy the user expands and collapses                       | `Tree`                                                                                       |
+| Commands (초대하기, 내보내기)                                    | `Button`, or a `Menu` when there are several                                                 |
+
 ## Variants and what they mean
 
-Tabs has one look. A selected tab is a *place*, not a value, so it is marked
+Tabs has one look. A selected tab is a _place_, not a value, so it is marked
 with ink and weight, not with a brand or status colour. `orientation` decides
 the layout:
 
@@ -59,9 +78,27 @@ the layout:
   씁니다. 탭은 무엇을 보는지를 바꾸고, 어떻게 보는지를 바꾸지 않습니다.
 - 차례대로 끝내야 하는 흐름의 단계에는 단계 표시나 이어지는 페이지를 씁니다. 탭은 사용자가
   단계를 건너뛰게 둡니다.
-- 앱의 다른 페이지로 옮겨 가는 것은 내비게이션 링크나 `Breadcrumb`가 맡습니다.
+- 다른 곳으로 옮겨 가는 항목이나 필터(한 영역의 옆 내비게이션, 목록 옆의 필터 레일)는
+  `NavList`가 맡습니다. 항목이 많거나 계속 늘어나는 목록, 항목에 개수나 아이콘이 붙는
+  목록도 `NavList`를 씁니다. 탭은 패널을 갖고, 방향키로 옮기며, 고른 것을
+  `aria-selected`로 알립니다. 레일은 링크나 필터이고 Tab 키로 오갑니다.
+- 이 페이지가 계층의 어디에 있는지 보여 줄 때는 `Breadcrumb`를 씁니다.
 - 나란히 봐야 하는 짧은 패널 두세 개는 탭에 숨기지 말고 페이지에 그대로 보입니다.
 
+## 어떤 컴포넌트를 쓰나요
+
+Tabs와 `NavList`는 둘 다 항목 하나를 현재 항목으로 표시합니다. 두 문서는 같은 기준을 서로
+반대쪽에서 설명합니다. 항목이 무엇인지를 보고 고릅니다.
+
+| 이런 경우                                                            | 쓰는 컴포넌트                                                            |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 한 대상의 구역 몇 개를 그 자리에서 패널로 바꿔 보여 줄 때            | `Tabs`                                                                   |
+| 다른 곳으로 옮겨 가는 항목, 한 영역의 옆 내비게이션                  | 항목마다 `href`를 준 `NavList`                                           |
+| 목록이나 그리드 하나를 거르는 필터로, 선택지가 많거나 개수를 붙일 때 | `NavList`. 필터 상태가 URL에 있으면 링크(`href`), 아니면 버튼(`onClick`) |
+| 선택지 둘에서 다섯 개를 가로로 짧게 바꿀 때                          | `SegmentedControl`                                                       |
+| 펼치고 접는 계층                                                     | `Tree`                                                                   |
+| 명령(초대하기, 내보내기)                                             | `Button`, 여러 개라면 `Menu`                                             |
+
 ## 변형과 뜻
 
 Tabs의 모양은 하나입니다. 선택된 탭은 값이 아니라 지금 있는 곳이므로, 브랜드색이나
@@ -69,14 +106,17 @@ Tabs의 모양은 하나입니다. 선택된 탭은 값이 아니라 지금 있
 
 </Ko>
 
-<ArgTypes of={TabsStories} include={['orientation', 'defaultValue', 'value', 'activationMode']} />
+<ArgTypes
+  of={TabsStories}
+  include={['orientation', 'defaultValue', 'value', 'activationMode']}
+/>
 
 <En>
 
-| `orientation` | Selected tab | Use for |
-| --- | --- | --- |
-| `horizontal` (default) | `fg.emphasized` label, semibold, with a 2px `primary.main` underline | Sections across the top of a page or panel |
-| `vertical` | `bg.muted` fill, bold, with a 2px `primary.main` bar on the leading edge | A long settings page in a narrow side column |
+| `orientation`          | Selected tab                                                             | Use for                                      |
+| ---------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
+| `horizontal` (default) | `fg.emphasized` label, semibold, with a 2px `primary.main` underline     | Sections across the top of a page or panel   |
+| `vertical`             | `bg.muted` fill, bold, with a 2px `primary.main` bar on the leading edge | A long settings page in a narrow side column |
 
 ## Do / Don't
 
@@ -84,10 +124,10 @@ Tabs의 모양은 하나입니다. 선택된 탭은 값이 아니라 지금 있
 
 <Ko>
 
-| `orientation` | 선택된 탭 | 쓰는 곳 |
-| --- | --- | --- |
-| `horizontal` (기본) | `fg.emphasized` 글자를 semibold로 쓰고 아래에 2px `primary.main` 밑줄 | 페이지나 패널 위쪽의 구역 |
-| `vertical` | `bg.muted` 배경에 bold, 앞쪽 가장자리에 2px `primary.main` 막대 | 좁은 옆 열에 둔 긴 설정 화면 |
+| `orientation`       | 선택된 탭                                                             | 쓰는 곳                      |
+| ------------------- | --------------------------------------------------------------------- | ---------------------------- |
+| `horizontal` (기본) | `fg.emphasized` 글자를 semibold로 쓰고 아래에 2px `primary.main` 밑줄 | 페이지나 패널 위쪽의 구역    |
+| `vertical`          | `bg.muted` 배경에 bold, 앞쪽 가장자리에 2px `primary.main` 막대       | 좁은 옆 열에 둔 긴 설정 화면 |
 
 ## 이렇게 하세요 / 이렇게 하지 마세요
 
@@ -116,7 +156,7 @@ Tabs의 모양은 하나입니다. 선택된 탭은 값이 아니라 지금 있
 - Keep labels the same length class; one long label next to short ones reads as
   a different kind of tab.
 - Stay under about six horizontal tabs. More than that, use `vertical` or split
-  the page.
+  the page; if the rows are places or filters, use `NavList`.
 - Do not put a count in the label unless it changes what the user does next.
 
 ## Accessibility
@@ -162,6 +202,7 @@ The selected ramp is `TAB_RAMP` in `Tab.styles.ts`; the other tokens are set in
 - 라벨 길이를 비슷하게 맞춥니다. 짧은 라벨 사이의 긴 라벨 하나는 다른 종류의 탭처럼
   보입니다.
 - 가로 탭은 여섯 개 안쪽으로 둡니다. 더 많으면 `vertical`을 쓰거나 페이지를 나눕니다.
+  항목이 곳이나 필터라면 `NavList`를 씁니다.
 - 다음 행동을 바꾸는 경우가 아니면 라벨에 개수를 넣지 않습니다.
 
 ## 접근성
@@ -200,6 +241,8 @@ Tabs가 알아서 하는 일
 
 ## Related
 
+- **NavList**: destinations and filters, such as side navigation and filter
+  rails.
 - **SegmentedControl**: change how the same content is shown.
 - **Breadcrumb**: where this page sits in a hierarchy.
 - **Foundations/Brand & colour usage**: why a selected place is ink, not
@@ -211,6 +254,7 @@ Tabs가 알아서 하는 일
 
 ## 관련 컴포넌트
 
+- **NavList**: 다른 곳으로 옮겨 가는 항목과 필터. 옆 내비게이션, 필터 레일.
 - **SegmentedControl**: 같은 내용을 보는 방식 바꾸기.
 - **Breadcrumb**: 이 페이지가 계층의 어디에 있는지.
 - **Foundations/Brand & colour usage**: 선택된 곳을 색이 아니라 진한 글자로 표시하는

package/src/components/Tooltip/Tooltip.usage.mdx

@@ -144,6 +144,10 @@ What you still have to do:
   shows.
 - Never put the only copy of required information in a tooltip; touch screens
   have no hover.
+- **Tooltip + Menu on one trigger: share `ids.trigger`.** Both make the
+  button their trigger and each gives it its own id, so the menu cannot find
+  its anchor and opens at the top-left of the page. Pass one `useId()` to
+  both: `<Menu ids={{ trigger: id }}><Tooltip ids={{ trigger: id }} …>`.
 
 ## Tokens
 
@@ -178,6 +182,10 @@ Tooltip이 알아서 하는 일
   자식은 실제 버튼, 링크처럼 초점을 받는 요소여야 합니다. 비활성 버튼은 포인터도 초점도
   받지 않아 툴팁이 뜨지 않습니다.
 - 꼭 필요한 정보를 툴팁에만 두지 않습니다. 터치 화면에는 마우스 올리기가 없습니다.
+- **한 버튼에 Tooltip과 Menu를 함께 걸 때는 `ids.trigger`를 같이 씁니다.** 둘 다 그 버튼을
+  여는 요소로 삼고 각자 다른 id를 붙이므로, 메뉴가 기준 위치를 못 찾고 화면 왼쪽 위에서
+  열립니다. `useId()` 하나를 양쪽에 넘깁니다:
+  `<Menu ids={{ trigger: id }}><Tooltip ids={{ trigger: id }} …>`.
 
 ## 토큰
 

package/src/components/a11y.kwcag.test.tsx

@@ -6,6 +6,7 @@ import { buttonVariantStyles } from '@/components/Button/Button.styles';
 import { FileInput } from '@/components/FileInput';
 import { LogicianProvider } from '@/components/LogicianProvider';
 import { baseMarkdownComponents } from '@/components/Markdown/Markdown';
+import { NavList } from '@/components/NavList';
 import { Radio, RadioGroup } from '@/components/Radio';
 import { SelectField } from '@/components/Select';
 import {
@@ -292,6 +293,71 @@ describe('axe — 구조·ARIA 규칙', () => {
       </RadioGroup>,
     ],
     ['파일 입력', <FileInput key="file" onChange={() => {}} />],
+    [
+      // Rows are links or buttons with aria-current — never tabs — and the
+      // trailing action sits beside its row, not inside it (nested-interactive).
+      '내비게이션 목록',
+      <NavList key="navlist" aria-label="소스">
+        <NavList.Item href="/recent" isCurrent trailingVisual="3">
+          최근
+        </NavList.Item>
+        <NavList.Item href="/off" isDisabled>
+          사용 불가
+        </NavList.Item>
+        <NavList.Group title="공유 드라이브">
+          <NavList.Item
+            onClick={() => {}}
+            trailingAction={
+              <button type="button" aria-label="마케팅 옵션">
+                …
+              </button>
+            }
+          >
+            마케팅
+          </NavList.Item>
+          <NavList.Item onClick={() => {}} isDisabled>
+            보관됨
+          </NavList.Item>
+        </NavList.Group>
+      </NavList>,
+    ],
+    [
+      // Icon-only rows keep their label as the name; a new-window link says
+      // so in its name; a collapsible group is a disclosure with its list
+      // still labelled; a hover-revealed action is still in the tree.
+      '접힌 내비게이션 레일과 새 창 링크',
+      <NavList key="navlist-collapsed" aria-label="관리자 메뉴" isCollapsed>
+        <NavList.Item href="/a" isCurrent leadingVisual={<svg />}>
+          멤버 관리
+        </NavList.Item>
+        <NavList.Item
+          href="https://docs.example"
+          target="_blank"
+          leadingVisual={<svg />}
+        >
+          사용 가이드
+        </NavList.Item>
+      </NavList>,
+    ],
+    [
+      '접을 수 있는 내비게이션 묶음',
+      <NavList key="navlist-collapsible" aria-label="설정">
+        <NavList.Group title="결제" isCollapsible>
+          <NavList.Item
+            href="/b"
+            tooltip="요금제와 결제 수단"
+            trailingActionVisibility="hover"
+            trailingAction={
+              <button type="button" aria-label="요금제 옵션">
+                …
+              </button>
+            }
+          >
+            요금제
+          </NavList.Item>
+        </NavList.Group>
+      </NavList>,
+    ],
   ])('%s', async (_name, ui) => {
     const { container } = withProvider(ui);
     expect(await axeViolations(container)).toEqual([]);

package/src/components/claude.md

@@ -348,7 +348,7 @@ When adding to `src/index.ts`, follow these categories:
 
 - **Core Components**: Button, Card, Badge, Tag
 - **Form Components**: Input, Select, Checkbox, Radio
-- **Navigation**: Breadcrumb, Pagination, Menu, Tabs
+- **Navigation**: Breadcrumb, Pagination, Menu, Tabs, NavList
 - **Feedback**: Alert, Toast, Modal, Tooltip
 - **Data Display**: Table, Avatar, Typography, Code
 - **File Components**: FileInput, FileItem, FileList

package/src/index.ts

@@ -66,6 +66,7 @@ export * from './components/MonthPicker';
 export * from './components/Popover';
 
 // Navigation Components
+export * from './components/NavList';
 export * from './components/Pagination';
 
 // Input Variants
@@ -178,7 +179,12 @@ export {
 } from './theme/motion';
 export { cubicBezier } from './utils/cubicBezier';
 export { disabledControl, disabledText } from './utils/disabledControl';
-export { FOCUS_RING_SHADOW, focusRing } from './utils/focusRing';
+export {
+  FOCUS_RING_INSET_SHADOW,
+  FOCUS_RING_SHADOW,
+  focusRing,
+  focusRingInset,
+} from './utils/focusRing';
 export {
   staggerDelayMs,
   type StaggerProps,

package/src/utils/focusRing.ts

@@ -25,3 +25,26 @@ export const focusRing = {
     boxShadow: FOCUS_RING_SHADOW,
   },
 } as const;
+
+/**
+ * The same two bands as {@link FOCUS_RING_SHADOW}, drawn INSIDE the element's
+ * edge: the outer 2px in `focus.ring`, then the 2px `bg.canvas` band that keeps
+ * the ring legible against whatever fill the element has.
+ *
+ * {@link focusRing} needs 4px of clear space on every side, because both bands
+ * paint outside the box. Rows packed into a list cannot give it that — the band
+ * lands on the neighbouring row, which paints its own background back over
+ * half of it — and a list that scrolls (`overflow-x: auto`) clips it outright.
+ * Same colour and weight, inside the box instead.
+ */
+export const FOCUS_RING_INSET_SHADOW =
+  'inset 0 0 0 2px var(--chakra-colors-focus-ring), inset 0 0 0 4px var(--chakra-colors-bg-canvas)';
+
+/** {@link focusRing}'s inset counterpart, for rows in a dense or scrolling list. */
+export const focusRingInset = {
+  _focus: { outline: 'none' },
+  _focusVisible: {
+    outline: 'none',
+    boxShadow: FOCUS_RING_INSET_SHADOW,
+  },
+} as const;