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

package/src/components/Tag/Tag.stories.tsx

@@ -3,8 +3,11 @@ import { Box, Flex, Text, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
 import { SYSTEM_HUE_NAMES } from '@/theme/colors';
+import { disabledControl } from '@/utils/disabledControl';
 
-import { Tag, tagTones } from '.';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { getTagStyles, Tag, tagTones, tagToneStyles } from '.';
 import { TagCloseButton } from './TagCloseButton';
 
 const meta = {
@@ -17,16 +20,19 @@ const meta = {
     tone: {
       control: 'select',
       options: tagTones,
-      description: 'Colour role; `neutral` (grey wash) is the default',
+      description:
+        '`neutral` (default): a plain label. `success` / `warning` / `danger` / `info`: only when the tag reports a status every reader shares. Ignored while `selected` or `category` is set.',
     },
     selected: {
       control: 'boolean',
-      description: 'Filter-chip "on" state (black fill)',
+      description:
+        'Filter-chip "on" state (black fill). Passing it, true or false, makes the tag a toggle; with `as="button"` it sets `aria-pressed`.',
     },
     category: {
       control: 'select',
       options: [undefined, ...SYSTEM_HUE_NAMES],
-      description: 'Decorative category hue (no status meaning)',
+      description:
+        'One of twelve category hues. Classifies only: no status meaning. Wins over `tone`.',
     },
     disabled: { control: 'boolean' },
   },
@@ -180,3 +186,174 @@ export const UseCases: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Tag.usage.mdx` with <Canvas of={…} />. Hidden from the sidebar
+// (`!dev`); `tags` is written on each story because the indexer reads CSF
+// statically.
+
+const TOPICS = [
+  { label: '연구', hue: 'blue' },
+  { label: '수업', hue: 'purple' },
+  { label: '행정', hue: 'brown' },
+] as const;
+
+export const DoCategoryForTopics: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: category hues for topics',
+  render: () => (
+    <Flex gap={2} wrap="wrap">
+      {TOPICS.map(({ label, hue }) => (
+        <Tag key={label} category={hue} icon="#">
+          {label}
+        </Tag>
+      ))}
+    </Flex>
+  ),
+};
+
+export const DontToneForTopics: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: status tones for topics",
+  render: () => (
+    <Flex gap={2} wrap="wrap">
+      <Tag tone="success">연구</Tag>
+      <Tag tone="danger">수업</Tag>
+      <Tag tone="warning">행정</Tag>
+    </Flex>
+  ),
+};
+
+export const DoFilterToggle: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: filter chips as buttons with `selected`',
+  render: function DoFilterToggleStory() {
+    const [on, setOn] = useState('전체');
+    return (
+      <Flex gap={2} wrap="wrap" role="group" aria-label="파일 종류">
+        {['전체', '이미지', '문서', '코드'].map((name) => (
+          <Tag
+            key={name}
+            as="button"
+            selected={on === name}
+            onClick={() => setOn(name)}
+          >
+            {name}
+          </Tag>
+        ))}
+      </Flex>
+    );
+  },
+};
+
+export const DoRemovableWithName: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a remove button with its own name',
+  render: function DoRemovableStory() {
+    const [items, setItems] = useState(['마케팅팀', '영업팀', '개발팀']);
+    return (
+      <Flex gap={2} wrap="wrap">
+        {items.map((item) => (
+          <Tag key={item}>
+            {item}
+            <TagCloseButton
+              type="button"
+              aria-label={`${item} 삭제`}
+              onClick={() => setItems((prev) => prev.filter((i) => i !== item))}
+            />
+          </Tag>
+        ))}
+      </Flex>
+    );
+  },
+};
+
+export const DontSelectedForStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: `selected` to mark a status",
+  render: () => (
+    <Flex gap={2} wrap="wrap" align="center">
+      <Text fontSize="sm">보고서 초안</Text>
+      <Tag selected>게시됨</Tag>
+    </Flex>
+  ),
+};
+
+/** Tokens each tone and state reads, from `Tag.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => {
+    const selected = getTagStyles({ selected: true });
+    const category = getTagStyles({ category: 'blue' });
+    return (
+      <TokenTable
+        rows={[
+          ...tagTones.flatMap((tone) => [
+            {
+              token: tagToneStyles[tone].bgColor,
+              use: <T en={`${tone} · background`} ko={`${tone} · 배경`} />,
+            },
+            {
+              token: tagToneStyles[tone].color,
+              use: <T en={`${tone} · text`} ko={`${tone} · 글자`} />,
+            },
+            {
+              token: tagToneStyles[tone].hoverBorder,
+              use: (
+                <T
+                  en={`${tone} · hover border (interactive)`}
+                  ko={`${tone} · 호버 테두리(누를 수 있을 때)`}
+                />
+              ),
+            },
+          ]),
+          {
+            token: selected.bgColor as string,
+            use: <T en="selected · background" ko="selected · 배경" />,
+          },
+          {
+            token: selected.color as string,
+            use: <T en="selected · text" ko="selected · 글자" />,
+          },
+          {
+            token: category.bgColor as string,
+            use: (
+              <T
+                en="category (blue shown) · background"
+                ko="category(예: blue) · 배경"
+              />
+            ),
+          },
+          {
+            token: 'category.blue.fg',
+            use: (
+              <T
+                en="category (blue shown) · icon mark"
+                ko="category(예: blue) · 앞쪽 표시"
+              />
+            ),
+          },
+          {
+            token: category.color as string,
+            use: <T en="category · text" ko="category · 글자" />,
+          },
+          {
+            token: disabledControl.bg,
+            use: <T en="disabled · background" ko="disabled · 배경" />,
+          },
+          {
+            token: disabledControl.color,
+            use: <T en="disabled · text" ko="disabled · 글자" />,
+          },
+        ]}
+      />
+    );
+  },
+};

package/src/components/Tag/Tag.usage.mdx

@@ -0,0 +1,257 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TagStories from './Tag.stories';
+
+<Meta of={TagStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Tag
+
+A compact label that classifies an item, or that the reader can select or
+remove: a topic, a filter, a chosen group.
+
+## When to use
+
+- To classify items into groups with no fixed meaning: topics, file types,
+  departments. Use `category`.
+- As a filter chip the reader turns on and off. Render it `as="button"` with
+  `selected`.
+- To show a choice the reader made and can take back: a selected group in a
+  picker, an active filter. Add `TagCloseButton`.
+
+## When not to use
+
+- A status or a well-defined system fact (완료, 실패, 이 그룹만) → `Badge`.
+- One choice out of a few, where exactly one is always on → `SegmentedControl`
+  or `Tabs`.
+- A count → `CountBadge`.
+- `Chip` is a deprecated alias of Tag; new code uses Tag.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Tag
+
+항목을 분류하거나, 사용자가 고르거나 지울 수 있는 작은 라벨입니다. 주제, 필터, 선택한
+그룹 같은 곳에 씁니다.
+
+## 언제 쓰나요
+
+- 정해진 뜻이 없는 묶음으로 항목을 나눌 때: 주제, 파일 종류, 부서. `category`를 씁니다.
+- 사용자가 켜고 끄는 필터 칩으로 쓸 때. `as="button"`으로 그리고 `selected`를 넘깁니다.
+- 사용자가 고른 뒤 다시 뺄 수 있는 선택을 보여 줄 때: 선택기에서 고른 그룹, 적용 중인
+  필터. `TagCloseButton`을 붙입니다.
+
+## 언제 쓰지 않나요
+
+- 상태나 뜻이 명확한 시스템 사실(완료, 실패, 이 그룹만)은 `Badge`를 씁니다.
+- 몇 가지 중 늘 하나만 켜져 있는 선택은 `SegmentedControl`이나 `Tabs`를 씁니다.
+- 개수는 `CountBadge`를 씁니다.
+- `Chip`은 Tag의 지원 중단된 별칭입니다. 새 코드에서는 Tag를 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={TagStories} include={['tone', 'selected', 'category', 'icon', 'disabled']} />
+
+<En>
+
+| Prop | Means | Use for |
+| --- | --- | --- |
+| `tone="neutral"` (default) | A plain label | Group names, file extensions, active filters |
+| `category` | A group with no meaning beyond telling items apart | Topics, departments, projects |
+| `selected` | A filter chip that is on (black fill) | Filter bars |
+| `tone="success"` / `warning` / `danger` / `info` | A status every reader shares | Rare on Tag; usually `Badge` is the right component |
+| `disabled` | Cannot be used right now | A filter with no results |
+
+When more than one is set, `selected` wins over `category`, and `category`
+wins over `tone`.
+
+A tag becomes interactive (pointer, hover border) when it has `onClick`, is a
+toggle (`selected` passed, true or false), or renders as a button or a link.
+With `as="button"` it gets `type="button"`, `aria-pressed` for a toggle, and the
+native `disabled` attribute.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 뜻 | 예 |
+| --- | --- | --- |
+| `tone="neutral"` (기본) | 단순한 라벨 | 그룹 이름, 파일 확장자, 적용 중인 필터 |
+| `category` | 항목을 나누는 것 말고는 뜻이 없는 묶음 | 주제, 부서, 프로젝트 |
+| `selected` | 켜져 있는 필터 칩(검은 바탕) | 필터 막대 |
+| `tone="success"` / `warning` / `danger` / `info` | 모든 사용자가 같은 뜻으로 읽는 상태 | Tag에서는 드뭅니다. 대개 `Badge`가 맞습니다 |
+| `disabled` | 지금은 쓸 수 없음 | 결과가 없는 필터 |
+
+여러 속성을 함께 주면 `selected`가 `category`보다, `category`가 `tone`보다
+우선합니다.
+
+`onClick`이 있거나, 토글이거나(`selected`를 true든 false든 넘긴 경우), 버튼이나
+링크로 그리면 Tag는 누를 수 있는 모양(포인터, 호버 테두리)이 됩니다. `as="button"`으로
+그리면 `type="button"`이 붙고, 토글이면 `aria-pressed`가, 비활성이면 기본
+`disabled` 속성이 붙습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TagStories.DoCategoryForTopics} />
+<Verdict
+  kind="do"
+  en="Use category hues for topics. They tell items apart without implying that one is good and another is bad."
+  ko="주제에는 category 색을 씁니다. 항목을 나누면서도 어느 쪽이 좋고 나쁘다는 뜻을 담지 않습니다."
+/>
+
+<Canvas of={TagStories.DontToneForTopics} />
+<Verdict
+  kind="dont"
+  en="Borrow status tones to colour topics. Readers will take 수업 to be an error."
+  ko="주제에 색을 입히려고 상태 tone을 빌려 쓰지 마세요. 사용자는 '수업'을 오류로 읽습니다."
+/>
+
+<Canvas of={TagStories.DoFilterToggle} />
+<Verdict
+  kind="do"
+  en='Render filter chips as="button" and pass selected. They are then reachable with Tab, work with Enter and Space, and announce pressed or not pressed.'
+  ko='필터 칩은 as="button"으로 그리고 selected를 넘깁니다. 그래야 Tab으로 이동하고 Enter와 Space로 누를 수 있으며, 눌림 여부가 읽힙니다.'
+/>
+
+<Canvas of={TagStories.DoRemovableWithName} />
+<Verdict
+  kind="do"
+  en="Give every remove button its own name, such as '마케팅팀 삭제'. Three buttons all called 'close' are impossible to tell apart."
+  ko="삭제 버튼마다 '마케팅팀 삭제'처럼 고유한 이름을 붙입니다. 이름이 모두 '닫기'인 버튼 세 개는 서로 구분할 수 없습니다."
+/>
+
+<Canvas of={TagStories.DontSelectedForStatus} />
+<Verdict
+  kind="dont"
+  en="Use the selected fill to show a status. Black means 'this filter is on'. For 게시됨 use a Badge."
+  ko="상태를 보여 주려고 selected 바탕을 쓰지 마세요. 검은 바탕은 '이 필터가 켜져 있음'이라는 뜻입니다. '게시됨'에는 Badge를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- One to three words. No full stop.
+- Nouns, not verbs: 이미지, not 이미지 보기.
+- Sentence case in English. No 「」, quotation marks or brackets around
+  Korean labels.
+- For a long name, shorten the label and keep the full name in the remove
+  button's `aria-label` or a `Tooltip`.
+
+## Accessibility
+
+What Tag does for you:
+
+- A plain tag is a `<span>`, so it is safe inside a button or link (phrasing
+  content, `ACCESSIBILITY.md` §5, KWCAG 5.4.1.1).
+- `as="button"` adds `type="button"`, `aria-pressed` for a toggle, the native
+  `disabled` attribute and the house focus ring (WCAG 2.4.7, 4.1.2).
+- A disabled tag that would otherwise be a link or clickable span gets
+  `aria-disabled`, leaves the Tab order and ignores clicks.
+- Text on every tone and on `selected` passes the contrast audit in both modes
+  (WCAG 1.4.3).
+
+What you still have to do:
+
+- **Clickable means a button or a link** (WCAG 2.1.1). `onClick` on the default
+  `<span>` is not reachable by keyboard. Use `as="button"`, or `as="a"` with
+  `href` when it navigates.
+- **Name the remove button.** `TagCloseButton` is an icon-only `<button>` with
+  no name and no handler of its own. Pass `aria-label` (for example
+  `` `${label} 삭제` ``) and `onClick` (WCAG 4.1.2). Inside a `<form>`, also
+  pass `type="button"`, or it submits the form.
+- Group related filter chips under a label (`role="group"` with
+  `aria-label`, or a visible heading) so a screen reader knows what they
+  filter.
+- Words, not colour alone (WCAG 1.4.1): category hues only tell items apart;
+  the label carries the meaning.
+
+## Tokens
+
+The table is generated from `Tag.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한 단어에서 세 단어까지 씁니다. 마침표를 찍지 않습니다.
+- 동사가 아니라 명사로 씁니다. "이미지 보기"가 아니라 "이미지"라고 씁니다.
+- 영어는 문장형 대소문자를 씁니다. 한국어 라벨에는 「」, 따옴표, 괄호를 두르지
+  않습니다.
+- 이름이 길면 라벨은 줄이고, 전체 이름은 삭제 버튼의 `aria-label`이나 `Tooltip`에
+  담습니다.
+
+## 접근성
+
+Tag가 알아서 하는 일
+
+- 기본 Tag는 `<span>`이라 버튼이나 링크 안에 넣어도 됩니다(구문 콘텐츠,
+  `ACCESSIBILITY.md` §5, KWCAG 5.4.1.1).
+- `as="button"`으로 그리면 `type="button"`, 토글일 때 `aria-pressed`, 기본
+  `disabled` 속성, 공통 초점 링이 붙습니다(WCAG 2.4.7, 4.1.2).
+- 링크나 누를 수 있는 span이 비활성이면 `aria-disabled`가 붙고, Tab 순서에서 빠지며,
+  클릭을 무시합니다.
+- 모든 tone과 `selected`의 글자 색은 라이트·다크 모두 대비 감사를 통과합니다(WCAG
+  1.4.3).
+
+직접 챙겨야 하는 일
+
+- **누를 수 있다면 버튼이나 링크로 그립니다**(WCAG 2.1.1). 기본 `<span>`에
+  `onClick`만 달면 키보드로 닿지 않습니다. `as="button"`을 쓰고, 다른 곳으로
+  이동한다면 `href`와 함께 `as="a"`를 씁니다.
+- **삭제 버튼에 이름을 붙입니다.** `TagCloseButton`은 아이콘만 있는 `<button>`이며,
+  이름도 동작도 스스로 갖지 않습니다. `aria-label`(예: `` `${label} 삭제` ``)과
+  `onClick`을 넘깁니다(WCAG 4.1.2). `<form>` 안에서는 `type="button"`도 넘겨야
+  폼이 제출되지 않습니다.
+- 관련된 필터 칩은 라벨로 묶습니다(`aria-label`을 단 `role="group"`, 또는 눈에 보이는
+  제목). 그래야 화면 낭독기 사용자가 무엇을 거르는 필터인지 압니다.
+- 색만으로 알리지 않습니다(WCAG 1.4.1). category 색은 항목을 나눌 뿐이고, 뜻은 라벨이
+  전합니다.
+
+## 토큰
+
+아래 표는 `Tag.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={TagStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Badge**: a status or a well-defined system fact.
+- **CountBadge**: a number.
+- **Chip**: deprecated alias of Tag; see its migration table.
+- **SegmentedControl**: exactly one of a few options.
+- **Foundations/Brand & colour usage**: category hues vs status colours.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Badge**: 상태나 뜻이 명확한 시스템 사실.
+- **CountBadge**: 숫자.
+- **Chip**: Tag의 지원 중단된 별칭. 바꾸는 방법은 Chip 페이지의 표를 봅니다.
+- **SegmentedControl**: 몇 가지 중 정확히 하나.
+- **Foundations/Brand & colour usage**: category 색과 상태색의 차이.
+
+</Ko>

package/src/components/Textarea/Textarea.stories.tsx

@@ -1,6 +1,13 @@
 import { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 
+import { Box } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
+import { Input } from '../Input';
+import { MaxLengthIndicator } from '../MaxLengthIndicator';
 import { Textarea } from '.';
 
 const meta = {
@@ -77,3 +84,109 @@ export const Invalid: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Textarea.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+const INSTRUCTIONS =
+  '답변은 존댓말로 합니다. 근거가 되는 문서가 있으면 제목을 함께 알려 줍니다.';
+
+export const DoInstructionsWithCount: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: long text with a label and a count',
+  render: () => {
+    const [value, setValue] = useState(INSTRUCTIONS);
+    return (
+      <Box maxW="420px">
+        <FieldRow
+          label="시스템 지시문"
+          helperText="챗봇이 모든 대화에서 따르는 규칙입니다."
+          endAdornment={
+            <MaxLengthIndicator value={value.length} maxLength={500} />
+          }
+        >
+          <Textarea
+            rows={4}
+            maxLength={500}
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+          />
+        </FieldRow>
+      </Box>
+    );
+  },
+};
+
+export const DontSingleValue: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a textarea for a one-line value",
+  render: () => (
+    <Box maxW="420px">
+      <FieldRow label="그룹 이름">
+        <Textarea rows={4} value="마케팅팀" onChange={() => {}} />
+      </FieldRow>
+    </Box>
+  ),
+};
+
+export const DoSingleValueInInput: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: an Input for a one-line value',
+  render: () => (
+    <Box maxW="420px">
+      <FieldRow label="그룹 이름">
+        <Input value="마케팅팀" onChange={() => {}} />
+      </FieldRow>
+    </Box>
+  ),
+};
+
+/** Tokens Textarea reads, as written in `Textarea.tsx` (same set as Input). */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.surface', use: <T en="Background" ko="배경" /> },
+        { token: 'fg.default', use: <T en="Text" ko="글자" /> },
+        {
+          token: 'border.control',
+          use: <T en="Border at rest" ko="평소 테두리" />,
+        },
+        {
+          token: 'fg.icon',
+          use: <T en="Border on hover" ko="마우스를 올렸을 때 테두리" />,
+        },
+        {
+          token: 'primary.main',
+          use: <T en="Border and ring on focus" ko="초점 테두리와 링" />,
+        },
+        {
+          token: 'danger.solid',
+          use: <T en="Border when invalid" ko="오류 상태 테두리" />,
+        },
+        {
+          token: 'bg.subtle',
+          use: <T en="Read-only background" ko="읽기 전용 배경" />,
+        },
+        {
+          token: 'fg.muted',
+          use: <T en="Read-only text" ko="읽기 전용 글자" />,
+        },
+        {
+          token: 'disabled.bg',
+          use: <T en="Disabled background" ko="비활성 배경" />,
+        },
+        {
+          token: 'disabled.fg',
+          use: <T en="Disabled text" ko="비활성 글자" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Textarea/Textarea.tsx

@@ -88,6 +88,10 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
           bg: 'bg.subtle',
           color: 'fg.muted',
           borderColor: 'border.subtle',
+          // Nothing can be typed here, so hovering must not promise an edit.
+          _hover: {
+            borderColor: 'border.subtle',
+          },
         }}
         _disabled={{
           ...disabledControl,