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

package/src/components/Masonry/Masonry.usage.mdx

@@ -0,0 +1,142 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as MasonryStories from './Masonry.stories';
+
+<Meta of={MasonryStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Masonry
+
+Equal-width columns that pack items of different heights without gaps,
+re-measuring as items resize. FactChat uses it for the model and voice menus.
+
+## When to use
+
+- Unordered groups or cards whose heights differ a lot, where a grid would
+  leave holes.
+
+## When not to use
+
+- Items with similar heights → `SimpleGrid` / `Grid`, which keeps row order.
+- Anything with an order (steps, a ranking, a timeline, search results) →
+  a list or a grid. Masonry's reading order is column by column.
+- A data list → `Table`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# Masonry
+
+너비가 같은 열에 높이가 다른 항목을 빈틈없이 채우고, 항목 크기가 바뀌면 다시 재는
+레이아웃입니다. FactChat은 모델 메뉴와 음성 메뉴에 씁니다.
+
+## 언제 쓰나요
+
+- 순서가 없고 높이 차이가 커서 격자로 놓으면 빈칸이 생기는 묶음이나 카드.
+
+## 언제 쓰지 않나요
+
+- 높이가 비슷한 항목은 행 순서를 지키는 `SimpleGrid` / `Grid`를 씁니다.
+- 순서가 있는 것(단계, 순위, 타임라인, 검색 결과)은 목록이나 격자를 씁니다.
+  Masonry의 읽기 순서는 열 단위입니다.
+- 데이터 목록은 `Table`을 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={MasonryStories} include={['numCols', 'gap', 'horizontalArrangement']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={MasonryStories.DoUnorderedGroups} />
+<Verdict
+  kind="do"
+  en="Pack unordered groups of different heights. Nothing depends on which comes first."
+  ko="높이가 다르고 순서가 없는 묶음을 빈틈없이 채웁니다. 어느 것이 먼저 오든 상관없습니다."
+/>
+
+<Canvas of={MasonryStories.DontOrderedContent} />
+<Verdict
+  kind="dont"
+  en="Lay out steps in it. Placement follows height, so the visual order scrambles, and keyboard and screen-reader order runs down each column."
+  ko="단계를 Masonry로 늘어놓지 마세요. 높이에 따라 자리가 정해져 눈에 보이는 순서가 뒤섞이고, 키보드와 화면 낭독기는 열마다 위에서 아래로 읽습니다."
+/>
+
+<En>
+
+## Accessibility
+
+What Masonry does for you:
+
+- Nothing beyond layout. It renders plain boxes, one column after another.
+
+What you still have to do:
+
+- **Keep the content order-free** (WCAG 1.3.2, 2.4.3). The DOM order is
+  column 1 top to bottom, then column 2, so Tab and a screen reader follow
+  columns, not the rows a sighted reader sees.
+- **Set `numCols` for the viewport** with `useBreakpointValue`; at 320px wide
+  one column avoids sideways scrolling (WCAG 1.4.10).
+
+## Tokens
+
+Masonry sets no colour tokens.
+
+</En>
+
+<Ko>
+
+## 접근성
+
+Masonry가 알아서 하는 일
+
+- 레이아웃 말고는 없습니다. 열을 하나씩 차례로 그리는 일반 상자입니다.
+
+직접 챙겨야 하는 일
+
+- **순서가 없는 내용에만 씁니다**(WCAG 1.3.2, 2.4.3). DOM 순서가 1열 위에서 아래, 그다음
+  2열이라, Tab과 화면 낭독기는 눈에 보이는 행이 아니라 열을 따라갑니다.
+- **화면 너비에 맞게 `numCols`를 정합니다.** `useBreakpointValue`를 쓰고, 폭 320px에서는
+  한 열로 두어 가로 스크롤을 막습니다(WCAG 1.4.10).
+
+## 토큰
+
+Masonry는 색 토큰을 쓰지 않습니다.
+
+</Ko>
+
+<En>
+
+## Related
+
+- **Card**: what usually goes in each cell.
+- **Container**: page width.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Card**: 칸마다 주로 들어가는 것.
+- **Container**: 페이지 너비.
+
+</Ko>

package/src/components/MaxLengthIndicator/MaxLengthIndicator.stories.tsx

@@ -1,5 +1,10 @@
+import { useState } from 'react';
+import { Box, chakra, Flex } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Textarea } from '../Textarea';
 import { MaxLengthIndicator } from '.';
 
 const meta = {
@@ -24,3 +29,55 @@ export default meta;
 type Story = StoryObj<typeof MaxLengthIndicator>;
 
 export const Basic: Story = {};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `MaxLengthIndicator.usage.mdx` with <Canvas of={…} />. Hidden
+// from the sidebar (`!dev`).
+
+const LIMIT = 200;
+
+export const DoUnderField: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: under the field, tied to it, with the real limit',
+  render: function DoUnderFieldStory() {
+    const [text, setText] = useState('신입 사원을 위한 사내 규정 안내 챗봇입니다.');
+    return (
+      <Box w="360px">
+        <chakra.label
+          display="block"
+          htmlFor="bot-description"
+          fontSize="sm"
+          fontWeight="semibold"
+          mb={1}
+        >
+          설명
+        </chakra.label>
+        <Textarea
+          id="bot-description"
+          value={text}
+          maxLength={LIMIT}
+          aria-describedby="bot-description-count"
+          onChange={(event) => setText(event.target.value)}
+        />
+        <Flex justify="flex-end" mt={1}>
+          <MaxLengthIndicator
+            id="bot-description-count"
+            value={text.length}
+            maxLength={LIMIT}
+          />
+        </Flex>
+      </Box>
+    );
+  },
+};
+
+/** Tokens the indicator reads, from `MaxLengthIndicator.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable rows={[{ token: 'fg.subtle', use: <T en="count text" ko="개수 글자" /> }]} />
+  ),
+};

package/src/components/MaxLengthIndicator/MaxLengthIndicator.usage.mdx

@@ -0,0 +1,125 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as MaxLengthIndicatorStories from './MaxLengthIndicator.stories';
+
+<Meta of={MaxLengthIndicatorStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# MaxLengthIndicator
+
+A small `value/maxLength` counter under a text field that has a length limit.
+
+## When to use
+
+- Under an `Input` or `Textarea` with a hard character limit the reader is
+  likely to reach: a description, a prompt, a name with a short limit.
+
+## When not to use
+
+- No limit, or one nobody comes near → leave it out.
+- A count of items, not characters → plain text or `CountBadge`.
+
+## How it works
+
+- It only displays the two numbers, in `subtext` style and `fg.subtle`. It does
+  not count, enforce the limit, change colour near the limit or announce
+  anything.
+- Pass the field's current length as `value` and the same limit you set on the
+  field's `maxLength`, which is what actually stops input.
+- Other `Text` props (`id`, `textAlign`, …) pass through.
+
+## Do
+
+</En>
+
+<Ko>
+
+# MaxLengthIndicator
+
+글자 수 제한이 있는 입력란 아래에 `value/maxLength`를 보여 주는 작은 숫자입니다.
+
+## 언제 쓰나요
+
+- 설명, 프롬프트, 짧은 이름처럼 사용자가 닿을 만한 글자 수 제한이 있는 `Input`이나
+  `Textarea` 아래에 둡니다.
+
+## 언제 쓰지 않나요
+
+- 제한이 없거나 아무도 닿지 않을 제한이라면 두지 않습니다.
+- 글자가 아니라 항목의 개수라면 일반 글자나 `CountBadge`를 씁니다.
+
+## 동작 방식
+
+- 숫자 두 개를 `subtext` 스타일과 `fg.subtle` 색으로 보여 주기만 합니다. 글자를
+  세거나, 제한을 지키게 하거나, 제한에 가까워질 때 색을 바꾸거나, 무언가를 알려 주지
+  않습니다.
+- 입력란의 현재 길이를 `value`로, 입력란의 `maxLength`와 같은 제한 값을 `maxLength`로
+  넘깁니다. 입력을 실제로 막는 것은 입력란의 `maxLength`입니다.
+- `id`, `textAlign` 같은 다른 `Text` 속성은 그대로 전달됩니다.
+
+## 이렇게 하세요
+
+</Ko>
+
+<Canvas of={MaxLengthIndicatorStories.DoUnderField} />
+<Verdict
+  kind="do"
+  en="Put it under the field, set the same limit as the field's maxLength, and point the field's aria-describedby at the counter's id so the limit is read with the field."
+  ko="입력란 아래에 두고, 입력란의 maxLength와 같은 제한 값을 쓰며, 입력란의 aria-describedby가 카운터의 id를 가리키게 해서 제한이 입력란과 함께 읽히게 합니다."
+/>
+
+<En>
+
+## Accessibility
+
+- Tie the counter to the field with `aria-describedby`, so the limit is
+  announced when the field gets focus (WCAG 1.3.1).
+- It does not announce changes while typing, which is usually right: a
+  number read out on every keystroke is noise. If reaching the limit matters,
+  say so once in a `role="status"` region (WCAG 4.1.3).
+- `fg.subtle` is for secondary text. If the counter is the only place the
+  limit is stated, check its contrast on the field's background (WCAG 1.4.3).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- `aria-describedby`로 카운터를 입력란에 연결해서, 입력란에 초점이 오면 제한이 함께
+  읽히게 합니다(WCAG 1.3.1).
+- 입력하는 동안 바뀐 숫자를 알려 주지 않습니다. 대개는 이것이 맞습니다. 글자를 칠 때마다
+  숫자를 읽으면 소음이 됩니다. 제한에 닿았다는 사실이 중요하다면 `role="status"`
+  영역으로 한 번만 알립니다(WCAG 4.1.3).
+- `fg.subtle`은 보조 글자용 색입니다. 카운터가 제한을 알리는 유일한 곳이라면 입력란
+  배경 위에서 대비를 확인합니다(WCAG 1.4.3).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={MaxLengthIndicatorStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Input** / **Textarea**: the field and its `maxLength`.
+- **FormControl**: label, help and error text for the field.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Input** / **Textarea**: 입력란과 그 `maxLength`.
+- **FormControl**: 입력란의 라벨, 도움말, 오류 문구.
+
+</Ko>

package/src/components/Menu/Menu.stories.tsx

@@ -1,8 +1,18 @@
-import { useState } from 'react';
+import { type ReactNode, useState } from 'react';
+import { Box } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Button } from '../Button/Button';
-import { IoChevronDownOutline, SlSettings } from '../Icon';
+import {
+  CopyIcon,
+  EditIcon,
+  IoChevronDownOutline,
+  SlSettings,
+  TrashIcon,
+  VerticalEllipsisIcon,
+} from '../Icon';
 import { IconButton } from '../IconButton';
 import { Menu } from './Menu';
 import { MenuItemProps } from './MenuItem.types';
@@ -223,3 +233,137 @@ export const SelectiveIcon: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Menu.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each menu is held open and rendered in place
+// (`portalled={false}`) so it sits inside its canvas.
+
+const OpenMenu = ({
+  trigger,
+  children,
+}: {
+  trigger: ReactNode;
+  children: ReactNode;
+}) => (
+  <Box h="200px">
+    <Menu
+      open
+      closeOnSelect={false}
+      positioning={{ placement: 'bottom-start', flip: false }}
+    >
+      <Menu.Trigger asChild>{trigger}</Menu.Trigger>
+      {/* The list caps itself at the viewport space left below the
+          trigger; a canvas near the fold would clip the last row. */}
+      <Menu.List portalled={false} maxH="none">
+        {children}
+      </Menu.List>
+    </Menu>
+  </Box>
+);
+
+// An element, not a component: `Menu.Trigger asChild` passes its ref and
+// props to its direct child, which must be the button itself.
+const rowTrigger = (
+  <IconButton aria-label="김민지 님 작업 메뉴" variant="ghost">
+    <VerticalEllipsisIcon aria-hidden />
+  </IconButton>
+);
+
+export const DoRowActions: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: actions on one row, danger last',
+  render: () => (
+    <OpenMenu trigger={rowTrigger}>
+      <Menu.Item value="rename" icon={<EditIcon aria-hidden />}>
+        이름 변경
+      </Menu.Item>
+      <Menu.Item value="duplicate" icon={<CopyIcon aria-hidden />}>
+        복제
+      </Menu.Item>
+      <Menu.Separator />
+      <Menu.Item
+        value="delete"
+        variant="danger"
+        icon={<TrashIcon aria-hidden />}
+      >
+        삭제
+      </Menu.Item>
+    </OpenMenu>
+  ),
+};
+
+export const DontDangerEverywhere: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: danger on actions that are not destructive",
+  render: () => (
+    <OpenMenu trigger={rowTrigger}>
+      <Menu.Item value="rename" variant="danger">
+        이름 변경
+      </Menu.Item>
+      <Menu.Item value="archive" variant="danger">
+        보관
+      </Menu.Item>
+      <Menu.Item value="delete" variant="danger">
+        삭제
+      </Menu.Item>
+    </OpenMenu>
+  ),
+};
+
+export const DontUnnamedTrigger: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the same unnamed trigger on every row",
+  render: () => (
+    <OpenMenu
+      trigger={
+        <IconButton aria-label="메뉴" variant="ghost">
+          <VerticalEllipsisIcon aria-hidden />
+        </IconButton>
+      }
+    >
+      <Menu.Item value="rename">이름 변경</Menu.Item>
+      <Menu.Item value="delete" variant="danger">
+        삭제
+      </Menu.Item>
+    </OpenMenu>
+  ),
+};
+
+/** Tokens a menu row reads, as set in `MenuItem.tsx` and `MenuList.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.panel', use: <T en="List" ko="목록" /> },
+        {
+          token: 'border.subtle',
+          use: <T en="List border" ko="목록 테두리" />,
+        },
+        { token: 'fg.muted', use: <T en="Row · text" ko="줄 · 글자" /> },
+        {
+          token: 'fg.default',
+          use: <T en="Row · highlighted text" ko="줄 · 강조된 글자" />,
+        },
+        {
+          token: 'primary.wash',
+          use: <T en="Row · highlighted" ko="줄 · 강조 배경" />,
+        },
+        {
+          token: 'danger.fg',
+          use: <T en="Danger row · text" ko="위험 줄 · 글자" />,
+        },
+        {
+          token: 'danger.bg',
+          use: <T en="Danger row · highlighted" ko="위험 줄 · 강조 배경" />,
+        },
+      ]}
+    />
+  ),
+};