@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/components/Tree/Tree.usage.mdx

@@ -0,0 +1,207 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TreeStories from './Tree.stories';
+
+<Meta of={TreeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Tree
+
+A hierarchy the user browses and selects from, such as an organisation's
+groups: 본사 › 개발본부 › 백엔드그룹 › API팀. Built on Chakra's TreeView, with
+the house hover, selection and focus styles.
+
+Data comes in through `createTreeCollection`; `Tree.Node` renders each node
+with your `render` function, as a `Tree.BranchControl` (has children) or a
+`Tree.Item` (leaf).
+
+## When to use
+
+- Data that really nests, more than one level deep, where the parent matters:
+  groups and sub-groups, folders.
+- When the user picks one node (`selectionMode="single"`, the default) or
+  several (`"multiple"`), or expands branches to find one.
+
+## When not to use
+
+- A flat list → a plain list, `Select`, or `Table`.
+- Two levels where the parent is only a heading → a list with section headings,
+  or `Accordion`.
+- Records with several attributes to compare → `Table`.
+- Site navigation → links in a nav landmark. A tree is a widget, not a
+  navigation menu.
+
+## Options
+
+| Option | Means |
+| --- | --- |
+| `selectionMode` | `single` (default) or `multiple` (Ctrl/Cmd-click, Shift-click for a range) |
+| `defaultExpandedValue` / `expandedValue` | Branches open at start, or controlled |
+| `defaultSelectedValue` / `selectedValue` | Selected nodes at start, or controlled |
+| `size` | `xs` / `sm` / `md`: text, padding, indent and icon scale together |
+| `Tree.BranchIndentGuide elbow` | `├` / `└` guide lines instead of a plain rail; `guideColor` (default `border.default`) and `footLength` tune it |
+| `Tree.BranchIndicator` children | Replace the chevron, e.g. with a folder icon |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Tree
+
+사용자가 펼쳐 보며 고르는 계층 구조입니다. 예를 들어 기관의 그룹(본사 › 개발본부 ›
+백엔드그룹 › API팀)을 보여 줍니다. Chakra의 TreeView 위에 이 디자인 시스템의 호버,
+선택, 초점 스타일을 얹었습니다.
+
+데이터는 `createTreeCollection`으로 넘기고, `Tree.Node`가 넘겨받은 `render` 함수로
+노드를 하나씩 그립니다. 자식이 있으면 `Tree.BranchControl`, 없으면 `Tree.Item`으로
+그립니다.
+
+## 언제 쓰나요
+
+- 실제로 두 단계 넘게 중첩되고 상위 항목이 의미를 가지는 데이터: 그룹과 하위 그룹,
+  폴더.
+- 사용자가 노드 하나(`selectionMode="single"`, 기본값)나 여러 개(`"multiple"`)를
+  고르거나, 가지를 펼쳐 가며 찾을 때.
+
+## 언제 쓰지 않나요
+
+- 단계가 없는 목록이라면 일반 목록, `Select`, `Table`을 씁니다.
+- 상위 항목이 제목 역할만 하는 두 단계라면 섹션 제목이 있는 목록이나 `Accordion`을
+  씁니다.
+- 여러 속성을 비교하는 기록이라면 `Table`을 씁니다.
+- 사이트 내비게이션에는 nav 랜드마크 안의 링크를 씁니다. 트리는 위젯이지 탐색 메뉴가
+  아닙니다.
+
+## 옵션
+
+| 옵션 | 뜻 |
+| --- | --- |
+| `selectionMode` | `single`(기본값) 또는 `multiple`(Ctrl/Cmd 클릭, 범위는 Shift 클릭) |
+| `defaultExpandedValue` / `expandedValue` | 처음 펼쳐 둘 가지, 또는 제어 값 |
+| `defaultSelectedValue` / `selectedValue` | 처음 선택할 노드, 또는 제어 값 |
+| `size` | `xs` / `sm` / `md`. 글자, 여백, 들여쓰기, 아이콘 크기가 함께 바뀝니다 |
+| `Tree.BranchIndentGuide elbow` | 세로줄 대신 `├` / `└` 안내선. `guideColor`(기본 `border.default`)와 `footLength`로 조정합니다 |
+| `Tree.BranchIndicator`의 children | 화살표 대신 폴더 아이콘 같은 다른 표시를 넣습니다 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TreeStories.DoNamedWithElbows} />
+<Verdict
+  kind="do"
+  en="Name the tree with Tree.Label (or aria-label on Tree.Root), and use elbow guides when it goes three or more levels deep."
+  ko="Tree.Label(또는 Tree.Root의 aria-label)로 트리에 이름을 붙이고, 세 단계 넘게 깊어지면 elbow 안내선을 씁니다."
+/>
+
+<Canvas of={TreeStories.DontFlatList} />
+<Verdict
+  kind="dont"
+  en="Use a tree for a flat list. It adds tree keyboard rules and announcements for no hierarchy; a list or Select is simpler."
+  ko="단계가 없는 목록에 트리를 쓰지 마세요. 계층이 없는데도 트리 키보드 규칙과 낭독이 붙습니다. 목록이나 Select가 더 단순합니다."
+/>
+
+<En>
+
+## Content
+
+- Node names are short nouns, the name the user knows the thing by.
+- Do not repeat the parent in the child: 백엔드그룹 › API팀, not 백엔드그룹 ›
+  백엔드그룹 API팀.
+- Long names wrap; keep the tree in a column wide enough that most names fit
+  on one line.
+
+## Accessibility
+
+What Tree does for you:
+
+- Chakra/Ark render the tree pattern: `role="tree"` on the tree, `treeitem`
+  on each node, with `aria-expanded` on branches and `aria-selected` on
+  selected nodes (WCAG 4.1.2).
+- It is one tab stop. Arrow keys move between nodes and open or close
+  branches, Home/End jump to the first and last node, and typing a letter
+  moves to a matching name (WCAG 2.1.1).
+- Rows and branch triggers show the shared focus ring on keyboard focus
+  (WCAG 2.4.7).
+
+What you still have to do:
+
+- **Give the tree a name**: `Tree.Label` inside `Tree.Root`, or `aria-label`
+  on `Tree.Root` (WCAG 4.1.2).
+- **Keep interactive content out of rows.** A row is already the control; a
+  button inside a `treeitem` is a nested interactive control
+  (`ACCESSIBILITY.md` §3). Put row actions in a toolbar outside the tree, or
+  use `Tree.NodeCheckbox` for checkable trees.
+- A custom `BranchIndicator` icon is decorative; the expanded state is
+  already announced.
+
+## Tokens
+
+The colours the Tree parts set on top of the Chakra recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 노드 이름은 사용자가 그 대상을 부르는 짧은 명사로 씁니다.
+- 하위 항목에 상위 이름을 되풀이하지 않습니다. '백엔드그룹 › 백엔드그룹 API팀'이
+  아니라 '백엔드그룹 › API팀'으로 씁니다.
+- 긴 이름은 줄바꿈됩니다. 이름 대부분이 한 줄에 들어갈 만큼 넓은 열에 트리를 둡니다.
+
+## 접근성
+
+Tree가 알아서 하는 일
+
+- Chakra/Ark가 트리 패턴을 그립니다. 트리에는 `role="tree"`, 노드마다 `treeitem`을
+  주고, 가지에는 `aria-expanded`, 선택된 노드에는 `aria-selected`를 붙입니다(WCAG
+  4.1.2).
+- 탭 한 번으로 들어가는 하나의 정지점입니다. 화살표 키로 노드를 오가며 가지를 열고
+  닫고, Home/End로 처음과 끝 노드로 가고, 글자를 입력하면 그 글자로 시작하는 이름으로
+  이동합니다(WCAG 2.1.1).
+- 키보드로 초점이 오면 행과 가지 트리거에 공통 초점 링이 나타납니다(WCAG 2.4.7).
+
+직접 챙겨야 하는 일
+
+- **트리에 이름을 붙입니다.** `Tree.Root` 안에 `Tree.Label`을 두거나 `Tree.Root`에
+  `aria-label`을 줍니다(WCAG 4.1.2).
+- **행 안에 상호작용 요소를 넣지 않습니다.** 행 자체가 이미 컨트롤이라, `treeitem`
+  안의 버튼은 상호작용 요소 중첩이 됩니다(`ACCESSIBILITY.md` 3절). 행 동작은 트리 밖의
+  도구 모음에 두고, 체크가 필요하면 `Tree.NodeCheckbox`를 씁니다.
+- 직접 넣은 `BranchIndicator` 아이콘은 장식입니다. 펼침 상태는 이미 읽어 줍니다.
+
+## 토큰
+
+Chakra 레시피 위에 Tree 파트들이 정하는 색입니다.
+
+</Ko>
+
+<Canvas of={TreeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Table**: flat records with columns.
+- **Accordion** / **Collapsible**: sections that open, not a selectable
+  hierarchy.
+- **Checkbox**: checkable trees use `Tree.NodeCheckbox`.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Table**: 열이 있는 평평한 기록.
+- **Accordion** / **Collapsible**: 고르는 계층이 아니라 여닫는 섹션.
+- **Checkbox**: 체크할 수 있는 트리에는 `Tree.NodeCheckbox`를 씁니다.
+
+</Ko>

package/src/components/Typography/Caption.tsx

@@ -28,7 +28,6 @@ const CaptionImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
         textStyle={fontSize ? undefined : 'caption'}
         fontSize={fontSize}
         color="fg.subtle"
-        wordBreak="keep-all"
         {...rest}
       />
     );

package/src/components/Typography/H1.tsx

@@ -14,7 +14,6 @@ const H1Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
       color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h1'}
       fontSize={fontSize}
-      wordBreak="keep-all"
       {...rest}
     />
   );

package/src/components/Typography/H2.tsx

@@ -14,7 +14,6 @@ const H2Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
       color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h2'}
       fontSize={fontSize}
-      wordBreak="keep-all"
       {...rest}
     />
   );

package/src/components/Typography/H3.tsx

@@ -14,7 +14,6 @@ const H3Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
       color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h3'}
       fontSize={fontSize}
-      wordBreak="keep-all"
       {...rest}
     />
   );

package/src/components/Typography/H4.tsx

@@ -14,7 +14,6 @@ const H4Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
       color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h4'}
       fontSize={fontSize}
-      wordBreak="keep-all"
       {...rest}
     />
   );

package/src/components/Typography/H5.tsx

@@ -14,7 +14,6 @@ const H5Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
       color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h5'}
       fontSize={fontSize}
-      wordBreak="keep-all"
       {...rest}
     />
   );

package/src/components/Typography/Link.tsx

@@ -75,7 +75,6 @@ const LinkImpl = forwardRef<HTMLAnchorElement, LinkOwnProps>(
         // scale the way `primary.main` used to. `{...rest}` below still lets
         // a call site override it.
         fontWeight={500}
-        wordBreak="keep-all"
         color={linkColor}
         textDecoration="underline"
         textDecorationThickness="1px"

package/src/components/Typography/Overline.tsx

@@ -26,7 +26,6 @@ const OverlineImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
         textStyle={fontSize ? undefined : 'overline'}
         fontSize={fontSize}
         color="fg.muted"
-        wordBreak="keep-all"
         {...rest}
       />
     );

package/src/components/Typography/Subtext.tsx

@@ -14,7 +14,6 @@ const SubtextImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
         textStyle={fontSize ? undefined : 'subtext'}
         fontSize={fontSize}
         color="fg.default"
-        wordBreak="keep-all"
         {...rest}
       />
     );

package/src/components/Typography/Subtitle.tsx

@@ -31,7 +31,6 @@ const SubtitleImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
         textStyle={fontSize ? undefined : 'subtitle'}
         fontSize={fontSize}
         color="fg.muted"
-        wordBreak="keep-all"
         {...rest}
       />
     );

package/src/components/Typography/Text.tsx

@@ -17,7 +17,6 @@ const TextImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
         textStyle={fontSize ? undefined : 'p'}
         fontSize={fontSize}
         color="fg.default"
-        wordBreak="keep-all"
         {...rest}
       />
     );

package/src/components/Typography/Typography.stories.tsx

@@ -1,5 +1,9 @@
+import { Stack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
 import { InlineCode } from '../InlineCode';
 
 import {
@@ -14,6 +18,7 @@ import {
   Subtext,
   Subtitle,
   Text,
+  LINK_RAMP,
 } from '.';
 
 const meta = {
@@ -119,3 +124,115 @@ export const AsElement: Story = {
     </>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Typography.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+export const DoLevelFromOutline: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: size by layout, level by outline',
+  render: () => (
+    <Card p={6} maxW="420px">
+      <H3 as="h2" mb={1}>
+        사용량
+      </H3>
+      <Subtext color="fg.muted">이번 달 1일부터 오늘까지의 합계입니다.</Subtext>
+    </Card>
+  ),
+};
+
+export const DontSubtitleAsHeading: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a heading tag for helper copy",
+  render: () => (
+    <Card p={6} maxW="420px">
+      <H2 mb={1}>사용량</H2>
+      <Subtitle as="h6">이번 달 1일부터 오늘까지의 합계입니다.</Subtitle>
+    </Card>
+  ),
+};
+
+export const DoLinkSaysWhere: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: the link text names the destination',
+  render: () => (
+    <Text>
+      팀 요금제는 인원 수에 따라 달라집니다.{' '}
+      <Link href="#plans">요금제 비교 보기</Link>
+    </Text>
+  ),
+};
+
+export const DontLinkHere: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: “click here” and no underline",
+  render: () => (
+    <Text>
+      팀 요금제가 궁금하다면{' '}
+      <Link href="#plans" textDecoration="none">
+        여기
+      </Link>
+      를 누르세요.
+    </Text>
+  ),
+};
+
+export const DoCaptionForMetadata: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: Caption for metadata only',
+  render: () => (
+    <Stack gap={1} maxW="420px">
+      <Text>회의록 요약이 준비되었습니다.</Text>
+      <Caption>오후 3:42 · 12분 분량</Caption>
+    </Stack>
+  ),
+};
+
+export const DontCaptionForErrors: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: Caption for something the user must act on",
+  render: () => (
+    <Stack gap={1} maxW="420px">
+      <Text>회의록 요약이 준비되지 않았습니다.</Text>
+      <Caption>녹음 파일이 손상되어 다시 올려야 합니다.</Caption>
+    </Stack>
+  ),
+};
+
+const TEXT_TOKENS = [
+  { token: 'fg.emphasized', en: 'H1–H5', ko: 'H1–H5' },
+  { token: 'fg.default', en: 'Text, Subtext', ko: 'Text, Subtext' },
+  { token: 'fg.muted', en: 'Subtitle, Overline', ko: 'Subtitle, Overline' },
+  { token: 'fg.subtle', en: 'Caption', ko: 'Caption' },
+];
+
+/** Text colours each tier sets by default, and the link ramp (`LINK_RAMP`). */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        ...TEXT_TOKENS.map(({ token, en, ko }) => ({
+          token,
+          use: <T en={en} ko={ko} />,
+        })),
+        // `errorHover` is the same token as `error` (no darker danger token
+        // exists), so it is not listed twice.
+        ...(['default', 'defaultHover', 'error'] as const).map((state) => ({
+          token: LINK_RAMP[state],
+          use: <T en={`Link · ${state}`} ko={`Link · ${state}`} />,
+        })),
+      ]}
+    />
+  ),
+};