@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.4

package/src/components/BottomSheet/BottomSheet.usage.mdx

@@ -0,0 +1,216 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BottomSheetStories from './BottomSheet.stories';
+
+<Meta of={BottomSheetStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# BottomSheet
+
+A panel that rises from the bottom edge of a phone screen. The user can drag it
+between snap points or swipe it away.
+
+## When to use
+
+- On a phone, to pick one item from a list: a node palette in the workflow
+  editor, an answer to a question the assistant asks.
+- On a phone, for a few related choices the user applies together, such as
+  filters.
+- Next to a canvas the user keeps working on: a non-modal sheet
+  (`modal={false}`) resting on a snap point leaves the page usable.
+
+## When not to use
+
+- On a desktop layout → `Modal` for a task, `Menu` or `Popover` for options
+  next to their trigger.
+- To confirm something that cannot be undone → `Modal`. A swipe should never
+  be the only thing between the user and a deletion.
+- For a result or status → `Toast` or `Banner`.
+- For a long form → a page. The sheet is capped at 85% of the screen height.
+
+## Variants and what they mean
+
+The sheet has no visual variants. These props decide how it behaves:
+
+</En>
+
+<Ko>
+
+# BottomSheet
+
+휴대폰 화면 아래 가장자리에서 올라오는 패널입니다. 사용자가 끌어서 멈춤 지점 사이를
+오가거나 쓸어내려 닫을 수 있습니다.
+
+## 언제 쓰나요
+
+- 휴대폰에서 목록 중 하나를 고르게 할 때: 워크플로 편집기의 노드 팔레트, 어시스턴트가
+  묻는 질문의 답.
+- 휴대폰에서 함께 적용하는 몇 가지 선택지를 보일 때: 필터.
+- 사용자가 계속 작업하는 캔버스 옆에 둘 때: 멈춤 지점에 걸쳐 둔 비모달 시트
+  (`modal={false}`)는 뒤의 페이지를 그대로 쓸 수 있게 둡니다.
+
+## 언제 쓰지 않나요
+
+- 데스크톱 화면에서는 작업에 `Modal`을, 버튼 옆 선택지에 `Menu`나 `Popover`를 씁니다.
+- 되돌릴 수 없는 동작의 확인은 `Modal`로 받습니다. 쓸어내리는 동작 하나만으로 삭제가
+  일어나서는 안 됩니다.
+- 결과나 상태는 `Toast`나 `Banner`로 알립니다.
+- 긴 양식은 페이지에 둡니다. 시트 높이는 화면의 85%까지만 늘어납니다.
+
+## 변형과 뜻
+
+시트에는 모양 변형이 없습니다. 동작을 정하는 속성은 다음과 같습니다.
+
+</Ko>
+
+<En>
+
+| Prop | Effect | Use for |
+| --- | --- | --- |
+| `modal` (default `true`) | Scrim, focus trap and scroll lock. | Most sheets: a pick or a set of choices. |
+| `modal={false}` | No scrim, no focus trap, no scroll lock; the page behind stays usable. | A palette beside a canvas, usually with `snapPoints`. |
+| `snapPoints` / `defaultSnapPoint` | Heights the sheet rests at. Numbers up to 1 are fractions of the viewport (`[0.4, 1]`); strings take `px` or `rem`. | A sheet that opens half-way and expands. |
+| `BottomSheetContent showGrabber` (default `true`) | Draws the drag handle. | Leave it on; turn it off only when the sheet cannot be dragged. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 효과 | 쓰는 곳 |
+| --- | --- | --- |
+| `modal` (기본 `true`) | 배경 막, 초점 가두기, 스크롤 잠금. | 대부분의 시트: 하나 고르기, 선택지 묶음. |
+| `modal={false}` | 배경 막, 초점 가두기, 스크롤 잠금이 모두 없어 뒤의 페이지를 쓸 수 있습니다. | 캔버스 옆의 팔레트. 보통 `snapPoints`와 함께 씁니다. |
+| `snapPoints` / `defaultSnapPoint` | 시트가 멈추는 높이. 1 이하의 숫자는 화면 높이의 비율(`[0.4, 1]`)이고, 문자열은 `px`나 `rem` 값입니다. | 반쯤 열렸다가 더 펼치는 시트. |
+| `BottomSheetContent`의 `showGrabber` (기본 `true`) | 끌기 손잡이를 그립니다. | 켜 둡니다. 시트를 끌 수 없을 때만 끕니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BottomSheetStories.DoPickFromList} />
+<Verdict
+  kind="do"
+  en="Give the sheet a header and a close button, and keep each row a single button."
+  ko="시트에 헤더와 닫기 버튼을 두고, 목록의 한 줄은 버튼 하나로 만듭니다."
+/>
+
+<Canvas of={BottomSheetStories.DontNoHeader} />
+<Verdict
+  kind="dont"
+  en="Leave out the header. The header is the sheet's accessible name; without it a screen reader announces an unnamed dialog, and nobody sees what the list is for."
+  ko="헤더를 빼지 마세요. 헤더가 시트의 접근 가능한 이름입니다. 헤더가 없으면 화면 낭독기는 이름 없는 대화상자로 읽고, 보는 사람도 목록이 무엇인지 알 수 없습니다."
+/>
+
+<Canvas of={BottomSheetStories.DoFooterToApply} />
+<Verdict
+  kind="do"
+  en="Add BottomSheetFooter only when the choices apply together. For a single pick, the row itself is the action."
+  ko="선택지를 한꺼번에 적용할 때만 BottomSheetFooter를 둡니다. 하나만 고르는 시트에서는 줄을 누르는 것이 곧 동작입니다."
+/>
+
+<En>
+
+## Content
+
+- **Header:** a noun or a short task name, no full stop: "노드 추가", "필터".
+- **Rows:** a label and, if needed, one line of hint in `fg.muted`.
+- **Footer buttons:** verbs ("적용", "초기화"), at most two.
+
+## Accessibility
+
+What BottomSheet does for you:
+
+- `BottomSheetHeader` becomes the sheet's title, which the content's
+  `aria-labelledby` points at (WCAG 4.1.2).
+- When modal, it traps focus in the sheet and locks the page's scroll.
+  `Escape` closes it (WCAG 2.1.1).
+- `BottomSheetCloseButton` carries a translated `aria-label` (닫기 / Close).
+- The grabber is `aria-hidden`: it is a pointer affordance, and dragging is
+  never the only way to close the sheet (WCAG 2.5.1).
+- `BottomSheetBody` scrolls inside the sheet; a drag starts from the body only
+  when the list is scrolled to the top, so scrolling never drags the sheet.
+
+What you still have to do:
+
+- **Always render `BottomSheetHeader`.** Without it the sheet has no name.
+- **Keep a close button or a footer action.** A swipe or an outside tap is not
+  available to keyboard and switch users.
+- Put `BottomSheetCloseButton` directly inside `BottomSheetContent`, next to
+  the header, not inside it.
+- A non-modal sheet does not trap focus: `Tab` can leave it for the page
+  behind. Check that the tab order between the two still makes sense.
+
+## Tokens
+
+The table is generated from `bottomSheetSlotRecipe` in `BottomSheet.styles.ts`.
+The scrim is `blackAlpha.500`, a fixed value rather than a semantic token.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- **헤더:** 명사나 짧은 작업 이름을 쓰고 마침표를 찍지 않습니다. "노드 추가", "필터".
+- **목록 한 줄:** 라벨 하나와, 필요하면 `fg.muted`로 쓴 도움말 한 줄.
+- **푸터 버튼:** 동사("적용", "초기화")로 두 개까지 씁니다.
+
+## 접근성
+
+BottomSheet가 알아서 하는 일
+
+- `BottomSheetHeader`가 시트의 제목이 되고, 콘텐츠의 `aria-labelledby`가 이 제목을
+  가리킵니다(WCAG 4.1.2).
+- 모달일 때는 초점을 시트 안에 가두고 페이지 스크롤을 막습니다. `Escape`로 닫힙니다
+  (WCAG 2.1.1).
+- `BottomSheetCloseButton`에는 번역된 `aria-label`(닫기 / Close)이 붙어 있습니다.
+- 손잡이는 `aria-hidden`입니다. 포인터용 표시일 뿐이고, 끌기만이 시트를 닫는 유일한
+  방법이 되지 않습니다(WCAG 2.5.1).
+- `BottomSheetBody`는 시트 안에서 스크롤됩니다. 목록이 맨 위에 있을 때만 본문에서 끌기가
+  시작되므로, 목록을 스크롤하다가 시트가 끌려 내려가지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **`BottomSheetHeader`를 언제나 둡니다.** 헤더가 없으면 시트에 이름이 없습니다.
+- **닫기 버튼이나 푸터 동작을 남깁니다.** 쓸어내리기나 바깥 누르기는 키보드나 스위치
+  사용자가 쓸 수 없습니다.
+- `BottomSheetCloseButton`은 헤더 안이 아니라 헤더 옆, `BottomSheetContent`의 바로
+  아래에 둡니다.
+- 비모달 시트는 초점을 가두지 않으므로 `Tab`으로 뒤의 페이지로 나갈 수 있습니다. 시트와
+  페이지 사이의 탭 순서가 자연스러운지 확인합니다.
+
+## 토큰
+
+아래 표는 `BottomSheet.styles.ts`의 `bottomSheetSlotRecipe`에서 자동으로 만듭니다. 배경
+막은 의미 토큰이 아니라 고정값 `blackAlpha.500`입니다.
+
+</Ko>
+
+<Canvas of={BottomSheetStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Modal**: the same job on a wide screen, and every destructive confirmation.
+- **Menu**: a short list of actions next to its trigger.
+- **Popover**: a small panel of controls anchored to its trigger.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Modal**: 넓은 화면에서 같은 일을 하며, 되돌릴 수 없는 동작의 확인은 모두 Modal로
+  받습니다.
+- **Menu**: 버튼 옆에 여는 짧은 동작 목록.
+- **Popover**: 버튼에 붙어 열리는 작은 컨트롤 패널.
+
+</Ko>

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -1,6 +1,9 @@
 import { Stack, Text } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+
 import { Breadcrumb } from './Breadcrumb';
 import { BreadcrumbItem } from './BreadcrumbItem';
 import { BreadcrumbLink } from './BreadcrumbLink';
@@ -74,3 +77,59 @@ export const CustomSeparator: Story = {
     </Stack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Breadcrumb.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`).
+
+export const DoCurrentPageIsText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ancestors are links, the current page is text',
+  render: () => (
+    <Breadcrumb aria-label="현재 위치">
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">전체 조직</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업본부</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <Text as="span" aria-current="page" fontWeight="semibold">
+          영업 1팀
+        </Text>
+      </BreadcrumbItem>
+    </Breadcrumb>
+  ),
+};
+
+export const DontEveryCrumbALink: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the current page as a link to itself",
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">전체 조직</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업본부</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업 1팀</BreadcrumbLink>
+      </BreadcrumbItem>
+    </Breadcrumb>
+  ),
+};
+
+/** Tokens the trail reads, as set in `BreadcrumbLink.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[{ token: 'fg.default', use: <T en="Link" ko="링크" /> }]}
+    />
+  ),
+};

package/src/components/Breadcrumb/Breadcrumb.usage.mdx

@@ -0,0 +1,181 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BreadcrumbStories from './Breadcrumb.stories';
+
+<Meta of={BreadcrumbStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Breadcrumb
+
+A trail of links that shows where the current page sits in a hierarchy and
+lets the user go back up it.
+
+## When to use
+
+- In a hierarchy more than two levels deep: a group inside a group inside the
+  organisation, a folder in a file picker.
+- At the top of a course or a detail view, to lead back to the level above.
+
+## When not to use
+
+- For a flat app section with one level → the page title is enough.
+- For the user's history ("where I was before") → the browser's back button.
+  A breadcrumb shows the hierarchy, not the path taken.
+- To switch between siblings of the same level → `Tabs` or a navigation list.
+- For the steps of a flow → a stepper.
+
+## Variants and what they mean
+
+Breadcrumb has no visual variants. `separator` (default `›`) and
+`separatorGap` (default `2`) set the mark between items and the space around
+it.
+
+</En>
+
+<Ko>
+
+# Breadcrumb
+
+지금 페이지가 계층의 어디에 있는지 보이고, 위 단계로 돌아갈 수 있게 하는 링크
+경로입니다.
+
+## 언제 쓰나요
+
+- 두 단계보다 깊은 계층에서: 조직 안의 그룹 안의 그룹, 파일 선택기의 폴더.
+- 강의나 상세 화면 맨 위에서 한 단계 위로 돌아가는 길을 보일 때.
+
+## 언제 쓰지 않나요
+
+- 한 단계뿐인 평평한 화면에서는 페이지 제목으로 충분합니다.
+- 사용자가 지나온 기록("방금 있던 곳")은 브라우저의 뒤로 가기가 맡습니다. Breadcrumb는
+  거쳐 온 길이 아니라 계층을 보입니다.
+- 같은 단계의 형제 사이를 오가는 것은 `Tabs`나 내비게이션 목록을 씁니다.
+- 흐름의 단계는 단계 표시를 씁니다.
+
+## 변형과 뜻
+
+Breadcrumb에는 모양 변형이 없습니다. `separator`(기본 `›`)와 `separatorGap`(기본
+`2`)으로 항목 사이의 표시와 간격을 정합니다.
+
+</Ko>
+
+<ArgTypes of={BreadcrumbStories} include={['separator', 'separatorGap']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BreadcrumbStories.DoCurrentPageIsText} />
+<Verdict
+  kind="do"
+  en="Link the ancestors and render the current page as text with aria-current='page'. Name the trail in the user's language."
+  ko="위 단계는 링크로, 지금 페이지는 aria-current='page'를 단 글자로 둡니다. 경로의 이름은 사용자의 언어로 붙입니다."
+/>
+
+<Canvas of={BreadcrumbStories.DontEveryCrumbALink} />
+<Verdict
+  kind="dont"
+  en="Make the current page a link to itself. It looks clickable, does nothing, and a screen reader cannot tell which crumb is the current page."
+  ko="지금 페이지를 자기 자신으로 가는 링크로 만들지 마세요. 누를 수 있어 보이지만 아무 일도 하지 않고, 화면 낭독기는 어느 항목이 지금 페이지인지 알 수 없습니다."
+/>
+
+<En>
+
+## Content
+
+- Each crumb is the title of that level, exactly as the page itself shows it.
+- Leave out the app's home if every page starts there.
+- In a very deep tree, keep the root and the last two or three levels and
+  collapse the middle.
+
+## Accessibility
+
+What Breadcrumb does for you:
+
+- Renders a `<nav>` with an ordered list, so the trail is a landmark and its
+  length is announced.
+- Separators are `aria-hidden`; a screen reader reads only the crumbs.
+- `BreadcrumbLink` shows the focus ring (WCAG 2.4.7). It renders through
+  `next/link` when Next.js is installed.
+
+What you still have to do:
+
+- **Name the landmark in the user's language.** Chakra's default `aria-label`
+  is the English "breadcrumb". Pass `aria-label="현재 위치"` or a translation
+  (WCAG 2.4.6).
+- **Mark the current page.** Render it as text with `aria-current="page"`, not
+  as a `BreadcrumbLink`.
+- Truncated crumbs need their full text available, for example as the link's
+  visible text with CSS truncation and a `Tooltip`.
+
+## Tokens
+
+The table lists the tokens set in `BreadcrumbLink.tsx`. The separator colour
+comes from Chakra's Breadcrumb recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 각 항목은 그 단계의 페이지 제목을 화면에 보이는 그대로 씁니다.
+- 모든 페이지가 같은 홈에서 시작한다면 홈은 뺍니다.
+- 아주 깊은 트리에서는 맨 위와 마지막 두세 단계만 두고 가운데는 접습니다.
+
+## 접근성
+
+Breadcrumb가 알아서 하는 일
+
+- `<nav>`와 순서 있는 목록으로 그려지므로 경로가 랜드마크가 되고 항목 수가 읽힙니다.
+- 구분 표시는 `aria-hidden`이라 화면 낭독기는 항목만 읽습니다.
+- `BreadcrumbLink`에는 초점 테두리가 보입니다(WCAG 2.4.7). Next.js가 설치되어 있으면
+  `next/link`로 그립니다.
+
+직접 챙겨야 하는 일
+
+- **랜드마크 이름을 사용자의 언어로 붙입니다.** Chakra의 기본 `aria-label`은 영어
+  "breadcrumb"입니다. `aria-label="현재 위치"`나 번역 문자열을 넘깁니다(WCAG 2.4.6).
+- **지금 페이지를 표시합니다.** `BreadcrumbLink`가 아니라 `aria-current="page"`를 단
+  글자로 그립니다.
+- 잘린 항목은 전체 문구를 볼 방법이 있어야 합니다. 예를 들어 링크 글자는 CSS로 자르고
+  `Tooltip`으로 전체를 보입니다.
+
+## 토큰
+
+아래 표는 `BreadcrumbLink.tsx`에서 정한 토큰입니다. 구분 표시의 색은 Chakra Breadcrumb
+레시피에서 옵니다.
+
+</Ko>
+
+<Canvas of={BreadcrumbStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tabs**: siblings of the same level.
+- **Menu**: the collapsed middle of a long trail.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tabs**: 같은 단계의 형제 사이 이동.
+- **Menu**: 긴 경로의 접힌 가운데 부분.
+
+</Ko>