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

package/src/components/FormControl/FormControl.usage.mdx

@@ -0,0 +1,128 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormControlStories from './FormControl.stories';
+
+<Meta of={FormControlStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FormControl
+
+Chakra's `Field.Root` under the design-system name: the wrapper that shares one
+field's id and state with its label, control, helper and error.
+
+## When to use
+
+- A field layout `FieldRow` does not cover, built from `FormLabel`, a control,
+  `FieldHelp` and `FieldError`.
+- Wrapping a control so a parent can set `required`, `invalid`, `disabled` or
+  `readOnly` once.
+
+## When not to use
+
+- A standard field → `FieldRow`, which is `FormControl` with the label, helper
+  and error already laid out.
+
+## Props
+
+`required`, `invalid`, `disabled` and `readOnly` (plus every `Field.Root`
+prop). The state reaches `Input`, `Textarea` and `PasswordInput` through
+Chakra's field context, together with the id the label points at and the
+`aria-describedby` for helper and error text. Composed controls (`SelectField`,
+`ComboboxField`, `Slider`) take their name from their own label part, so give
+them `label` or `ariaLabel` and pass `invalid` / `disabled` to them directly.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# FormControl
+
+Chakra `Field.Root`를 디자인 시스템 이름으로 내보낸 것입니다. 필드 하나의 id와 상태를
+라벨, 컨트롤, 도움말, 오류 문구에 나눠 주는 래퍼입니다.
+
+## 언제 쓰나요
+
+- `FieldRow`로 안 되는 필드 배치를 `FormLabel`, 컨트롤, `FieldHelp`, `FieldError`로
+  직접 짤 때.
+- 상위에서 `required`, `invalid`, `disabled`, `readOnly`를 한 번에 정하려고 컨트롤을
+  감쌀 때.
+
+## 언제 쓰지 않나요
+
+- 일반적인 필드는 `FieldRow`를 씁니다. 라벨, 도움말, 오류 문구가 이미 배치된
+  `FormControl`입니다.
+
+## 속성
+
+`required`, `invalid`, `disabled`, `readOnly`(그리고 `Field.Root`의 모든 속성)를
+받습니다. 이 상태는 Chakra의 필드 컨텍스트를 타고 `Input`, `Textarea`,
+`PasswordInput`에 전달되며, 라벨이 가리키는 id와 도움말·오류 문구용
+`aria-describedby`도 함께 전달됩니다. 부품을 조합한 컨트롤(`SelectField`,
+`ComboboxField`, `Slider`)은 자기 라벨 부품에서 이름을 가져오므로 `label`이나
+`ariaLabel`을 주고, `invalid`·`disabled`도 컨트롤에 직접 넘깁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FormControlStories.DoFieldRowFirst} />
+<Verdict
+  kind="do"
+  en="Reach for FieldRow first. It is FormControl with the label, help and error placed for you."
+  ko="먼저 FieldRow를 씁니다. 라벨, 도움말, 오류 문구를 알아서 배치한 FormControl입니다."
+/>
+
+<Canvas of={FormControlStories.DoInvalidOnTheField} />
+<Verdict
+  kind="do"
+  en="When you compose by hand, set invalid on FormControl, not on the Input, and add a FieldError with the reason."
+  ko="직접 조합할 때는 invalid를 Input이 아니라 FormControl에 주고, 이유를 적은 FieldError를 함께 둡니다."
+/>
+
+<En>
+
+## Accessibility
+
+- `invalid` on `FormControl` sets `aria-invalid` on the input; `invalid` on
+  `Input` only paints the border (WCAG 3.3.1, 4.1.2).
+- `required` marks the input required and shows the asterisk in `FormLabel`.
+  Say "required" in words somewhere on the form too; an asterisk alone is a
+  symbol not everyone knows (WCAG 3.3.2).
+
+## Tokens
+
+None. FormControl draws nothing; the label colours are on the FormLabel page.
+
+## Related
+
+- **FieldRow**: the laid-out field.
+- **FormLabel**, **FieldHelp**, **FieldError**: the parts.
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- `FormControl`의 `invalid`는 입력란에 `aria-invalid`를 붙이고, `Input`의 `invalid`는
+  테두리만 칠합니다(WCAG 3.3.1, 4.1.2).
+- `required`는 입력란을 필수로 표시하고 `FormLabel`에 별표를 보여 줍니다. 별표는 모두가
+  아는 기호가 아니므로 폼 어딘가에 "필수"라고 글자로도 적습니다(WCAG 3.3.2).
+
+## 토큰
+
+없습니다. FormControl은 아무것도 그리지 않습니다. 라벨 색은 FormLabel 페이지에
+있습니다.
+
+## 관련 컴포넌트
+
+- **FieldRow**: 배치까지 된 필드.
+- **FormLabel**, **FieldHelp**, **FieldError**: 부품.
+
+</Ko>

package/src/components/FormIntegration/FormIntegration.usage.mdx

@@ -0,0 +1,158 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormIntegrationStories from './FormIntegration.stories';
+
+<Meta title="Components/FormIntegration/Usage" />
+
+<LangToggle />
+
+<En>
+
+# Form integration
+
+How the form controls connect to a form library. There is no
+`FormIntegration` component: this page and the stories under
+**Examples/Form Integration** show the wiring.
+
+## The rule
+
+Put field state on the field, not on the control:
+
+1. One `FieldRow` (or `FormControl`) per field. Set `error` on it from the
+   library's error for that field; `invalid` follows, and `aria-invalid` and
+   `aria-describedby` reach the control.
+2. Pass the library's `value`, `onChange`, `onBlur` and `name` to the control.
+   `Input` re-emits change and blur events with `name` and the processed value
+   (trimmed, or digits only with `maskNumber`), so Formik's `handleChange` and
+   React Hook Form's `field.onChange` both work.
+3. Controls with their own value API take it directly: `SelectField` /
+   `ComboboxField` `onChange(value)`, `RadioGroup` `onValueChange`, `Checkbox`
+   / `Switch` `onCheckedChange`, `Slider` `onValueChange` (an array),
+   `FileInput` `onChange(files)`. With React Hook Form, wrap them in a
+   `Controller`.
+
+## When to use which library
+
+- **React Hook Form** with a `Controller` per non-text control: what FactChat
+  uses for admin and studio forms.
+- **Formik + Yup**: the first example below.
+- **Plain state**: small forms, the second example.
+
+## Examples
+
+</En>
+
+<Ko>
+
+# 폼 연동
+
+폼 컨트롤을 폼 라이브러리에 연결하는 방법입니다. `FormIntegration`이라는 컴포넌트는
+없습니다. 이 페이지와 **Examples/Form Integration** 아래 스토리가 연결 방법을 보여
+줍니다.
+
+## 원칙
+
+필드 상태는 컨트롤이 아니라 필드에 둡니다.
+
+1. 필드마다 `FieldRow`(또는 `FormControl`)를 하나씩 둡니다. 라이브러리가 그 필드에
+   대해 준 오류를 `error`에 넣으면 `invalid`도 따라 바뀌고, `aria-invalid`와
+   `aria-describedby`가 컨트롤까지 전달됩니다.
+2. 라이브러리의 `value`, `onChange`, `onBlur`, `name`을 컨트롤에 넘깁니다. `Input`은
+   변경·이탈 이벤트를 `name`과 가공한 값(공백을 정리한 값, `maskNumber`면 숫자만)으로
+   다시 만들어 보내므로 Formik의 `handleChange`와 React Hook Form의 `field.onChange`가
+   모두 동작합니다.
+3. 값을 다루는 방식이 따로 있는 컨트롤은 그 방식을 그대로 씁니다. `SelectField`·
+   `ComboboxField`는 `onChange(value)`, `RadioGroup`은 `onValueChange`, `Checkbox`·
+   `Switch`는 `onCheckedChange`, `Slider`는 `onValueChange`(배열), `FileInput`은
+   `onChange(files)`입니다. React Hook Form에서는 `Controller`로 감쌉니다.
+
+## 어떤 라이브러리를 쓰나요
+
+- **React Hook Form**과 텍스트가 아닌 컨트롤마다 `Controller`: FactChat의 관리자·
+  스튜디오 폼이 쓰는 방식입니다.
+- **Formik + Yup**: 아래 첫 번째 예시.
+- **일반 상태**: 작은 폼. 아래 두 번째 예시.
+
+## 예시
+
+</Ko>
+
+<Canvas of={FormIntegrationStories.FormikFormExample} />
+<Verdict
+  kind="do"
+  en="Formik: the error for each field goes to that field's Field.Root, and the message renders under it."
+  ko="Formik: 필드마다 오류를 그 필드의 Field.Root에 넘기고, 문구는 필드 바로 아래에 그립니다."
+/>
+
+<Canvas of={FormIntegrationStories.RegularFormExample} />
+<Verdict
+  kind="do"
+  en="Plain state: validate on submit, keep errors in state per field, and clear a field's error when it changes."
+  ko="일반 상태: 제출할 때 검사하고, 오류는 필드별로 상태에 두며, 값이 바뀌면 그 필드의 오류를 지웁니다."
+/>
+
+<En>
+
+## Pitfalls
+
+- **`trimWhiteSpace` trims on every keystroke**, so a name with a space can
+  only be pasted. Trim at submit instead.
+- **`maskNumber` needs `type="number"`** and then renders a text input; `min`
+  and `max` do nothing there. Validate the range in the schema.
+- **`SelectField` inside `FieldRow` needs `ariaLabel`** with the row's label;
+  the row's label does not name it.
+- **Don't set `invalid` on the control alone.** It paints the border without
+  telling assistive technology (WCAG 3.3.1).
+
+## Accessibility
+
+- Every field has a visible label (WCAG 3.3.2; KWCAG 5.3.4.1 레이블 제공), and
+  every error is text under its field (WCAG 3.3.1).
+- After a failed submit, move focus to the first invalid field or to an error
+  summary at the top.
+- Do not disable the submit button until the form is valid without saying
+  why; the user cannot find out what is missing. Validate on submit and show
+  the errors.
+
+## Tokens
+
+None of its own; see Input, Select and Form.
+
+## Related
+
+- **Form** (`FieldRow`, `FormSection`, footers), **FormControl**, **Input**,
+  **Select**.
+
+</En>
+
+<Ko>
+
+## 자주 하는 실수
+
+- **`trimWhiteSpace`는 입력할 때마다 공백을 지웁니다.** 그래서 공백이 든 이름은 붙여
+  넣기로만 넣을 수 있습니다. 공백 정리는 제출할 때 합니다.
+- **`maskNumber`는 `type="number"`가 있어야 동작하고**, 그때는 텍스트 입력란을 그립니다.
+  `min`과 `max`는 효과가 없으므로 범위는 스키마에서 검사합니다.
+- **`FieldRow` 안의 `SelectField`에는 행의 라벨을 `ariaLabel`로 넘깁니다.** 행의 라벨은
+  셀렉트의 이름이 되지 않습니다.
+- **컨트롤에만 `invalid`를 주지 않습니다.** 테두리만 칠하고 보조기술에는 알리지
+  않습니다(WCAG 3.3.1).
+
+## 접근성
+
+- 모든 필드에 보이는 라벨을 두고(WCAG 3.3.2, KWCAG 5.3.4.1 레이블 제공), 모든 오류는 해당
+  필드 아래에 문구로 보여 줍니다(WCAG 3.3.1).
+- 제출에 실패하면 첫 오류 필드나 위쪽의 오류 요약으로 초점을 옮깁니다.
+- 이유를 알리지 않은 채 폼이 유효해질 때까지 제출 버튼을 비활성으로 두지 않습니다.
+  무엇이 빠졌는지 알 수 없습니다. 제출할 때 검사하고 오류를 보여 줍니다.
+
+## 토큰
+
+따로 정한 토큰이 없습니다. Input, Select, Form 페이지를 보세요.
+
+## 관련 컴포넌트
+
+- **Form**(`FieldRow`, `FormSection`, 푸터), **FormControl**, **Input**, **Select**.
+
+</Ko>

package/src/components/FormLabel/FormLabel.stories.tsx

@@ -0,0 +1,71 @@
+import { Stack } from '@chakra-ui/react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { FormControl } from '../FormControl';
+import { Input } from '../Input';
+import { FormLabel } from './FormLabel';
+
+const meta = {
+  title: 'Components/FormLabel',
+  component: FormLabel,
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof FormLabel>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A label inside `FormControl`; it is associated with the control for you. */
+export const Basic: Story = {
+  render: () => (
+    <FormControl w="300px">
+      <FormLabel>표시 이름</FormLabel>
+      <Input placeholder="홍길동" />
+    </FormControl>
+  ),
+};
+
+/** `required` on `FormControl` adds the asterisk; nothing to pass here. */
+export const Required: Story = {
+  render: () => (
+    <FormControl required w="300px">
+      <FormLabel>업무용 이메일</FormLabel>
+      <Input type="email" />
+    </FormControl>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FormLabel.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoNounLabels: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: short noun labels',
+  render: () => (
+    <Stack gap={4} maxW="320px">
+      <FormControl required>
+        <FormLabel>그룹 이름</FormLabel>
+        <Input />
+      </FormControl>
+      <FormControl>
+        <FormLabel>설명</FormLabel>
+        <Input />
+      </FormControl>
+    </Stack>
+  ),
+};
+
+export const DontSentenceLabels: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: instructions as labels",
+  render: () => (
+    <Stack gap={4} maxW="320px">
+      <FormControl required>
+        <FormLabel>그룹 이름을 입력해 주세요 (필수):</FormLabel>
+        <Input />
+      </FormControl>
+    </Stack>
+  ),
+};

package/src/components/FormLabel/FormLabel.usage.mdx

@@ -0,0 +1,125 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormLabelStories from './FormLabel.stories';
+
+<Meta of={FormLabelStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FormLabel
+
+The visible label of a field. Inside `FormControl` it is associated with the
+control and shows the required asterisk on its own.
+
+## When to use
+
+- Inside `FormControl`, when you compose a field by hand. `FieldRow` (through
+  `FieldLabel`) already renders one.
+
+## When not to use
+
+- A section title → `FormSection` `title`.
+- A label for a checkbox, radio or switch option → `Checkbox.Label`,
+  `Radio.Text`, `Switch.Label`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# FormLabel
+
+필드의 보이는 라벨입니다. `FormControl` 안에서는 컨트롤과 연결되고 필수 별표도 알아서
+보여 줍니다.
+
+## 언제 쓰나요
+
+- 필드를 직접 조합할 때 `FormControl` 안에서 씁니다. `FieldRow`는 `FieldLabel`을 통해
+  이미 FormLabel을 그립니다.
+
+## 언제 쓰지 않나요
+
+- 섹션 제목은 `FormSection`의 `title`을 씁니다.
+- 체크박스, 라디오, 스위치 선택지의 라벨은 `Checkbox.Label`, `Radio.Text`,
+  `Switch.Label`을 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FormLabelStories.DoNounLabels} />
+<Verdict
+  kind="do"
+  en="Write short nouns and let FormControl required add the asterisk."
+  ko="짧은 명사로 쓰고, 별표는 FormControl의 required가 붙이게 둡니다."
+/>
+
+<Canvas of={FormLabelStories.DontSentenceLabels} />
+<Verdict
+  kind="dont"
+  en="Write an instruction with a colon and type '(필수)' by hand. The asterisk already says it, so the label says it twice."
+  ko="쌍점을 붙인 지시문으로 쓰거나 '(필수)'를 직접 적지 마세요. 별표가 이미 알려 주므로 두 번 말하게 됩니다."
+/>
+
+<En>
+
+## Content
+
+- A noun phrase in sentence case, no colon, no "(required)".
+- Keep it under about four words; anything longer goes in `FieldRow`
+  `description` or helper text.
+
+## Accessibility
+
+- It renders Chakra's `Field.Label`, a `<label>` whose `for` is the field's
+  control id, so clicking it focuses the control and screen readers read it as
+  the control's name (WCAG 1.3.1, 4.1.2; KWCAG 5.3.4.1 레이블 제공).
+- Outside `FormControl` there is no id to point at: pass `htmlFor` yourself.
+- Composed controls (`SelectField`, `ComboboxField`, `Slider`) are not named
+  by it; give them `label` or `ariaLabel`.
+
+## Tokens
+
+The label text is `fg.muted` from its wrapper (`FieldLabel` overrides it to
+`fg.default`, semibold). The asterisk is `danger.fg`.
+
+## Related
+
+- **FormControl**: the field it labels.
+- **FieldRow** / **FieldLabel**: the laid-out label with description and an
+  end slot.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 문장형 대소문자의 명사구로 쓰고, 쌍점이나 "(필수)"를 붙이지 않습니다.
+- 네 단어 안팎으로 씁니다. 더 긴 설명은 `FieldRow`의 `description`이나 도움말에
+  넣습니다.
+
+## 접근성
+
+- Chakra `Field.Label`을 그립니다. `for`가 필드 컨트롤의 id인 `<label>`이라, 누르면
+  컨트롤로 초점이 가고 화면 낭독기는 이를 컨트롤의 이름으로 읽습니다(WCAG 1.3.1, 4.1.2,
+  KWCAG 5.3.4.1 레이블 제공).
+- `FormControl` 밖에서는 가리킬 id가 없으므로 `htmlFor`를 직접 넘깁니다.
+- 부품을 조합한 컨트롤(`SelectField`, `ComboboxField`, `Slider`)에는 이 라벨이 이름으로
+  닿지 않습니다. `label`이나 `ariaLabel`을 줍니다.
+
+## 토큰
+
+라벨 글자는 감싸는 요소의 `fg.muted`를 씁니다(`FieldLabel`은 `fg.default` 굵은
+글자로 바꿉니다). 별표는 `danger.fg`입니다.
+
+## 관련 컴포넌트
+
+- **FormControl**: 라벨이 붙는 필드.
+- **FieldRow** / **FieldLabel**: 설명과 끝 자리가 있는 배치된 라벨.
+
+</Ko>

package/src/components/Icon/Icon.stories.tsx

@@ -13,9 +13,18 @@ import { useMemo } from 'react';
 import { FaBuildingUser } from 'react-icons/fa6';
 import { MdDashboard } from 'react-icons/md';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { IconButton } from '../IconButton';
 import { Icons } from './_constants/iconList';
 import { createIcon } from './_utils/createIcon';
-import { Analytics } from './index';
+import {
+  Analytics,
+  CheckIcon,
+  CloseIcon,
+  DownloadIcon,
+  TrashIcon,
+} from './index';
 
 const meta = {
   title: 'Components/Icon',
@@ -423,3 +432,54 @@ const MyCustomIcon = createIcon(
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Icon.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 DoIconWithLabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: decorative next to a label, named when alone',
+  render: () => (
+    <HStack gap={3}>
+      <Button variant="secondary">
+        <DownloadIcon boxSize="xs" aria-hidden />
+        내려받기
+      </Button>
+      <IconButton aria-label="삭제" variant="ghost">
+        <TrashIcon boxSize="xs" aria-hidden />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+export const DontIconAsStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a coloured icon as the only status",
+  render: () => (
+    <HStack gap={4}>
+      <Text>결제 1</Text>
+      <CheckIcon boxSize="xs" color="success.fg" />
+      <Text>결제 2</Text>
+      <CloseIcon boxSize="xs" color="danger.fg" />
+    </HStack>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'fg.icon', use: 'icons on their own (stories default)' },
+        { token: 'fg.default', use: 'icon in running text' },
+        { token: 'fg.muted', use: 'secondary icon' },
+      ]}
+    />
+  ),
+};