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

package/src/components/Menu/Menu.usage.mdx

@@ -0,0 +1,230 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as MenuStories from './Menu.stories';
+
+<Meta of={MenuStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Menu
+
+A list of actions or choices that opens from a button. Each row does one
+thing when chosen.
+
+## When to use
+
+- For the actions on one row or object, behind a "more" button: 이름 변경,
+  복제, 삭제.
+- For a set of related commands under one button: export as CSV or Excel.
+- For picking one setting from a short list in a top bar, such as the display
+  language.
+
+## When not to use
+
+- Two or three actions that fit on screen → show them as `Button`s. A menu
+  hides them behind an extra click.
+- A value in a form → `Select`. A menu does not hold a value or work with a
+  label and validation.
+- A panel with inputs or checkboxes → `Popover`.
+- Switching between views of the same content → `Tabs` or `SegmentedControl`.
+
+## Variants and what they mean
+
+`Menu.Item` takes a `variant`:
+
+</En>
+
+<Ko>
+
+# Menu
+
+버튼을 누르면 열리는 동작이나 선택지 목록입니다. 한 줄을 고르면 한 가지 일을 합니다.
+
+## 언제 쓰나요
+
+- 한 줄이나 한 대상에 대한 동작을 "더 보기" 버튼 뒤에 모을 때: 이름 변경, 복제, 삭제.
+- 관련된 명령 여러 개를 버튼 하나에 묶을 때: CSV나 Excel로 내보내기.
+- 상단 바에서 짧은 목록 중 설정 하나를 고를 때: 표시 언어.
+
+## 언제 쓰지 않나요
+
+- 화면에 들어가는 동작 두세 개는 `Button`으로 그대로 보입니다. 메뉴에 넣으면 한 번 더
+  눌러야 합니다.
+- 양식의 값은 `Select`로 받습니다. 메뉴는 값을 들고 있지 않고 라벨이나 검증과도 엮이지
+  않습니다.
+- 입력란이나 체크박스가 있는 패널은 `Popover`를 씁니다.
+- 같은 내용의 보기를 바꾸는 것은 `Tabs`나 `SegmentedControl`을 씁니다.
+
+## 변형과 뜻
+
+`Menu.Item`에는 `variant`가 있습니다.
+
+</Ko>
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `default` | An ordinary action | 이름 변경, 복제, 내보내기 |
+| `danger` | Deletes or removes something and cannot be undone | 삭제, 연결 해제 |
+
+`Menu.List stagger` deals the rows in one after another; keep it for short
+menus opened on purpose. `baseFontSize` (default `14px`) sets the base size
+the list scales from.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `default` | 일반 동작 | 이름 변경, 복제, 내보내기 |
+| `danger` | 무언가를 지우거나 없애며 되돌릴 수 없음 | 삭제, 연결 해제 |
+
+`Menu.List`의 `stagger`는 줄을 하나씩 차례로 보입니다. 일부러 여는 짧은 메뉴에만
+씁니다. `baseFontSize`(기본 `14px`)는 목록 크기의 기준입니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={MenuStories.DoRowActions} />
+<Verdict
+  kind="do"
+  en="Name the trigger after the row ('김민지 님 작업 메뉴'), put the destructive action last behind a separator, and confirm it in a Modal."
+  ko="여는 버튼 이름에 대상을 밝히고('김민지 님 작업 메뉴'), 되돌릴 수 없는 동작은 구분선 뒤 맨 아래에 두고, Modal로 한 번 더 확인합니다."
+/>
+
+<Canvas of={MenuStories.DontDangerEverywhere} />
+<Verdict
+  kind="dont"
+  en="Mark every row danger. Danger is a promise that the action destroys something; spent on 이름 변경 it stops warning anyone."
+  ko="모든 줄을 danger로 칠하지 마세요. danger는 무언가를 없애는 동작이라는 약속입니다. '이름 변경'에까지 쓰면 아무에게도 경고가 되지 않습니다."
+/>
+
+<Canvas of={MenuStories.DontUnnamedTrigger} />
+<Verdict
+  kind="dont"
+  en="Give every row's more button the same name. A screen reader user tabbing down a table hears '메뉴' twenty times."
+  ko="모든 줄의 더 보기 버튼에 같은 이름을 붙이지 마세요. 화면 낭독기 사용자가 표를 따라 내려가면 '메뉴'를 스무 번 듣습니다."
+/>
+
+<En>
+
+## Content
+
+- Rows start with a verb or are the verb: "이름 변경", "CSV로 내보내기". No full
+  stop.
+- Order by frequency, with destructive actions last.
+- If a row opens a dialog, the label does not need "…"; the dialog's title
+  repeats the action.
+- Keep one menu under about seven rows. Group longer ones with
+  `Menu.ItemGroup` and `Menu.ItemGroupLabel`.
+
+## Accessibility
+
+What Menu does for you:
+
+- The list is `role="menu"`, its rows `role="menuitem"`, and the list is named
+  by its trigger. The trigger gets `aria-haspopup`, `aria-expanded` and
+  `aria-controls` (WCAG 4.1.2).
+- Keyboard (WCAG 2.1.1): `Enter`, `Space` or `↓` opens the menu; `↑` / `↓`
+  move between rows, typing a letter jumps to a row, `Enter` chooses, and
+  `Escape` closes and returns focus to the trigger.
+- The highlighted row is painted the same way for the pointer and the
+  keyboard (`primary.wash`, `danger.bg` on a danger row). Focus stays on the
+  list and the row is tracked with `aria-activedescendant`, so that fill is
+  the visible focus indicator (WCAG 2.4.7).
+- A disabled row cannot be chosen and shows a not-allowed cursor.
+
+What you still have to do:
+
+- **Name an icon-only trigger, and include the object.** `aria-label` on the
+  `IconButton` inside `Menu.Trigger asChild`: "김민지 님 작업 메뉴", not "메뉴"
+  (WCAG 2.4.6).
+- **Give row icons `aria-hidden`.** The text is the name.
+- **Confirm destructive rows.** `variant="danger"` colours the row; it does not
+  ask the user. Open a `Modal`.
+- A row that navigates should be a real link: `Menu.Item as={NextLink}
+  href=…`, so middle-click and "open in new tab" still work.
+
+## Tokens
+
+The table lists the tokens set in `MenuItem.tsx` and `MenuList.tsx`, plus the
+list panel colour from Chakra's Menu recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 줄은 동사로 쓰거나 동사로 시작합니다. "이름 변경", "CSV로 내보내기". 마침표를 찍지
+  않습니다.
+- 자주 쓰는 순서로 놓고, 되돌릴 수 없는 동작은 맨 아래에 둡니다.
+- 대화상자를 여는 줄이라도 "…"를 붙이지 않아도 됩니다. 대화상자 제목이 동작을 다시
+  말해 줍니다.
+- 메뉴 하나는 일곱 줄 안쪽으로 둡니다. 더 길면 `Menu.ItemGroup`과
+  `Menu.ItemGroupLabel`로 묶습니다.
+
+## 접근성
+
+Menu가 알아서 하는 일
+
+- 목록은 `role="menu"`, 줄은 `role="menuitem"`이며, 목록의 이름은 여는 버튼에서
+  옵니다. 여는 버튼에는 `aria-haspopup`, `aria-expanded`, `aria-controls`가 붙습니다
+  (WCAG 4.1.2).
+- 키보드(WCAG 2.1.1): `Enter`, `Space`, `↓`로 열고, `↑`/`↓`로 줄을 옮기고, 글자를
+  입력하면 그 글자로 시작하는 줄로 가고, `Enter`로 고르고, `Escape`로 닫으면 초점이 여는
+  버튼으로 돌아옵니다.
+- 강조된 줄은 포인터든 키보드든 같은 모양(`primary.wash`, 위험 줄은 `danger.bg`)으로
+  칠해집니다. 초점은 목록에 머물고 줄은 `aria-activedescendant`로 가리키므로, 이 배경색이
+  눈에 보이는 초점 표시입니다(WCAG 2.4.7).
+- 비활성 줄은 고를 수 없고, 커서가 금지 모양으로 바뀝니다.
+
+직접 챙겨야 하는 일
+
+- **아이콘만 있는 여는 버튼에 대상까지 담은 이름을 붙입니다.** `Menu.Trigger asChild`
+  안의 `IconButton`에 `aria-label`을 줍니다. "메뉴"가 아니라 "김민지 님 작업 메뉴"처럼
+  씁니다(WCAG 2.4.6).
+- **줄 아이콘에는 `aria-hidden`을 붙입니다.** 이름은 문구가 맡습니다.
+- **되돌릴 수 없는 줄은 한 번 더 확인합니다.** `variant="danger"`는 색만 바꿀 뿐 사용자에게
+  묻지 않습니다. `Modal`을 엽니다.
+- 다른 페이지로 가는 줄은 실제 링크로 만듭니다. `Menu.Item as={NextLink} href=…`로
+  쓰면 가운데 클릭과 "새 탭에서 열기"가 그대로 동작합니다.
+
+## 토큰
+
+아래 표는 `MenuItem.tsx`와 `MenuList.tsx`에서 정한 토큰과, Chakra Menu 레시피에서 오는
+목록 패널 색입니다.
+
+</Ko>
+
+<Canvas of={MenuStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Button**: actions that fit on screen.
+- **Select**: a value in a form.
+- **Popover**: a panel with controls.
+- **Modal**: confirming a destructive row.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Button**: 화면에 그대로 둘 수 있는 동작.
+- **Select**: 양식의 값.
+- **Popover**: 컨트롤이 있는 패널.
+- **Modal**: 되돌릴 수 없는 줄의 확인.
+
+</Ko>

package/src/components/Menu/MenuItem.types.ts

@@ -15,8 +15,16 @@ export type ItemVariant = (typeof ItemVariant)[keyof typeof ItemVariant];
 
 export type MenuItemOwnProps = Omit<ChakraMenuItemProps, 'as'> & {
   value: string; // Required in Chakra v3 for menu item identification
+  /**
+   * `'danger'`: an action that deletes or removes something and cannot be
+   * undone (삭제, 연결 해제). Text is `danger.fg`; the highlighted row is
+   * `danger.bg`. Everything else is `'default'`.
+   * @default 'default'
+   */
   variant?: ItemVariant | null;
+  /** Leading icon. Decorative: give it `aria-hidden`. */
   icon?: React.ReactElement;
+  /** Trailing icon, pushed to the end of the row. Decorative: give it `aria-hidden`. */
   rightIcon?: React.ReactElement;
 };
 

package/src/components/Modal/Modal.stories.tsx

@@ -17,11 +17,16 @@
  *
  * @see ModalCloseButton.tsx - 구현 세부사항 확인
  */
-import { useState } from 'react';
+import { ReactNode, useState } from 'react';
+import { Box, Stack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Button } from '../Button';
 import { ButtonVariant } from '../Button/Button.types';
+import { Input } from '../Input';
+import { Text } from '../Typography';
 import {
   Modal,
   ModalBody,
@@ -29,6 +34,7 @@ import {
   ModalContent,
   ModalFooter,
   ModalHeader,
+  type ModalProps,
 } from '.';
 
 interface ModalArgs {
@@ -620,3 +626,173 @@ export const BrandHeader: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Modal.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each one is a real, open `Modal` held inside a framed box
+// on the docs page rather than over it: the portal is disabled, the frame's
+// transform makes it the containing block for the fixed positioner and
+// backdrop, and `modal={false}` keeps the specimen from trapping focus or
+// locking the page's scroll.
+
+const ModalFrame = ({ children }: { children: ReactNode }) => (
+  <Box
+    position="relative"
+    h="320px"
+    overflow="hidden"
+    borderRadius="l3"
+    borderWidth="1px"
+    borderColor="border.subtle"
+    bg="bg.canvas"
+    transform="translateZ(0)"
+    css={{
+      '& [data-scope=dialog][data-part=positioner], & [data-scope=dialog][data-part=backdrop]':
+        { width: '100%', height: '100%' },
+    }}
+  >
+    {children}
+  </Box>
+);
+
+/** An open, inert `Modal` for a docs specimen. */
+const OpenModal = ({
+  children,
+  ...props
+}: Omit<ModalProps, 'open' | 'children'> & { children: ReactNode }) => (
+  <ModalFrame>
+    <Modal
+      open
+      modal={false}
+      trapFocus={false}
+      preventScroll={false}
+      closeOnInteractOutside={false}
+      closeOnEscape={false}
+      portalProps={{ disabled: true }}
+      {...props}
+    >
+      <ModalContent maxW="400px">{children}</ModalContent>
+    </Modal>
+  </ModalFrame>
+);
+
+export const DoConfirmNamesTheAction: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: the title asks, the button answers',
+  render: () => (
+    <OpenModal>
+      <ModalHeader>멤버를 삭제할까요?</ModalHeader>
+      <ModalCloseButton />
+      <ModalBody>
+        김민지 님의 대화 기록과 크레딧 내역이 함께 삭제되며 되돌릴 수 없습니다.
+      </ModalBody>
+      <ModalFooter>
+        <Button variant="secondary">취소</Button>
+        <Button variant="danger">삭제</Button>
+      </ModalFooter>
+    </OpenModal>
+  ),
+};
+
+export const DontVagueConfirm: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a title and buttons that say nothing",
+  render: () => (
+    <OpenModal>
+      <ModalHeader>알림</ModalHeader>
+      <ModalBody>정말 진행하시겠습니까?</ModalBody>
+      <ModalFooter>
+        <Button variant="secondary">아니요</Button>
+        <Button variant="primary">예</Button>
+      </ModalFooter>
+    </OpenModal>
+  ),
+};
+
+export const DoShortForm: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one short task',
+  render: () => (
+    <OpenModal closeOnInteractOutside={false}>
+      <ModalHeader subtitle="허용 목록에 있는 도메인은 SSO 없이 가입할 수 있습니다.">
+        도메인 추가
+      </ModalHeader>
+      <ModalCloseButton />
+      <ModalBody>
+        <Input aria-label="도메인" placeholder="example.com" />
+      </ModalBody>
+      <ModalFooter>
+        <Button variant="secondary">취소</Button>
+        <Button variant="primary">추가</Button>
+      </ModalFooter>
+    </OpenModal>
+  ),
+};
+
+export const DontModalForDone: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a modal to say it worked",
+  render: () => (
+    <OpenModal>
+      <ModalBody>
+        <Stack gap={2} py={4} align="center">
+          <Text fontWeight="bold">저장되었습니다.</Text>
+        </Stack>
+      </ModalBody>
+      <ModalFooter>
+        <Button variant="primary">확인</Button>
+      </ModalFooter>
+    </OpenModal>
+  ),
+};
+
+export const DoBrandHeaderOnboarding: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: brand header for a welcome step',
+  render: () => (
+    <OpenModal headerTone="brand">
+      <ModalHeader subtitle="세 단계만 거치면 첫 대화를 시작할 수 있습니다.">
+        워크스페이스를 준비할게요
+      </ModalHeader>
+      <ModalCloseButton />
+      <ModalBody>조직 이름과 기본 모델을 고르면 바로 시작합니다.</ModalBody>
+      <ModalFooter>
+        <Button variant="primary">시작하기</Button>
+      </ModalFooter>
+    </OpenModal>
+  ),
+};
+
+/** Tokens the modal parts read, as written in `ModalHeader` / `ModalFooter` and the Dialog recipe. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.panel', use: <T en="Panel" ko="패널" /> },
+        {
+          token: 'fg.muted',
+          use: <T en="Header subtitle" ko="헤더 부제목" />,
+        },
+        {
+          token: 'layer.3',
+          use: <T en="Brand header · band" ko="브랜드 헤더 · 띠" />,
+        },
+        {
+          token: 'secondary.border',
+          use: <T en="Brand header · bottom rule" ko="브랜드 헤더 · 아래 선" />,
+        },
+        {
+          token: 'border.subtle',
+          use: <T en="Footer · top rule" ko="푸터 · 위 선" />,
+        },
+      ]}
+    />
+  ),
+};