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

package/src/components/FileItem/FileItem.stories.tsx

@@ -1,5 +1,10 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { Stack } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
 import { FileItem } from './FileItem';
 
 const meta = {
@@ -53,3 +58,69 @@ export const Deleting: Story = {
     isDeleting: true,
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FileItem.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoErrorInText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: repeat the error in text',
+  render: () => (
+    <Stack maxW="480px">
+      <FieldRow error="members.xlsx: 파일이 5MB를 넘습니다. 나눠서 올려 주세요.">
+        <FileItem
+          fileName="members.xlsx"
+          error="파일이 5MB를 넘습니다."
+          onFileDelete={() => {}}
+        />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DontErrorInTooltipOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the reason only in a tooltip",
+  render: () => (
+    <Stack maxW="480px">
+      <FileItem
+        fileName="members.xlsx"
+        error="파일이 5MB를 넘습니다."
+        onFileDelete={() => {}}
+      />
+    </Stack>
+  ),
+};
+
+/** Tokens `FileItem.tsx` reads. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'border.subtle', use: <T en="Row border" ko="행 테두리" /> },
+        {
+          token: 'fg.muted',
+          use: <T en="File icon, action icons" ko="파일 아이콘, 동작 아이콘" />,
+        },
+        {
+          token: 'fg.subtle',
+          use: <T en="Cancel-upload icon" ko="업로드 취소 아이콘" />,
+        },
+        {
+          token: 'danger.fg',
+          use: (
+            <T
+              en="Error: left bar, icon, file name"
+              ko="오류: 왼쪽 막대, 아이콘, 파일 이름"
+            />
+          ),
+        },
+      ]}
+    />
+  ),
+};

package/src/components/FileItem/FileItem.usage.mdx

@@ -0,0 +1,180 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FileItemStories from './FileItem.stories';
+
+<Meta of={FileItemStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FileItem
+
+One row for one file: its name, upload progress or size, and download and
+delete buttons.
+
+## When to use
+
+- A single attached or uploaded file in a form: the CSV just picked, a
+  template being uploaded, a verification document.
+
+## When not to use
+
+- Several files → `FileList`, which renders FileItem rows and a "see more".
+- A file inside a chat message → the chat attachment components.
+
+## Props
+
+</En>
+
+<Ko>
+
+# FileItem
+
+파일 하나를 보여 주는 한 줄입니다. 파일 이름, 업로드 진행률이나 크기, 내려받기와 삭제
+버튼이 있습니다.
+
+## 언제 쓰나요
+
+- 폼에 붙인 파일 하나: 방금 고른 CSV, 올리는 중인 템플릿, 증빙 서류.
+
+## 언제 쓰지 않나요
+
+- 파일이 여러 개라면 `FileList`를 씁니다. FileItem 행과 "더 보기"를 그려 줍니다.
+- 채팅 메시지 안의 파일은 채팅 첨부 컴포넌트를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={FileItemStories}
+  include={[
+    'fileName',
+    'progress',
+    'fileSize',
+    'error',
+    'onFileDownload',
+    'onFileDelete',
+    'isDownloading',
+    'isDeleting',
+  ]}
+/>
+
+<En>
+
+- `progress` from 0 to 99 shows a percentage, a bar, a spinner and a cancel
+  button that calls `onFileDelete`. At 100, or with no `progress`, the row
+  shows the size and the actions.
+- The download and delete buttons appear only when you pass their handlers.
+  `isDownloading` / `isDeleting` swap them for a spinner.
+- `error` turns the name, icon and left edge `danger.fg` and puts the message
+  in a tooltip on an alert icon. It hides the download button.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- `progress`가 0~99이면 백분율, 진행 막대, 스피너, `onFileDelete`를 부르는 취소 버튼을
+  보여 줍니다. 100이거나 `progress`가 없으면 크기와 동작 버튼을 보여 줍니다.
+- 내려받기와 삭제 버튼은 처리 함수를 넘겼을 때만 나타납니다. `isDownloading`·
+  `isDeleting`이면 버튼 대신 스피너가 보입니다.
+- `error`를 주면 이름, 아이콘, 왼쪽 가장자리가 `danger.fg`로 바뀌고, 문구는 경고
+  아이콘의 툴팁에 들어갑니다. 내려받기 버튼은 숨겨집니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FileItemStories.DoErrorInText} />
+<Verdict
+  kind="do"
+  en="Repeat the reason in text under the row, with the file name, so it can be read without hovering."
+  ko="실패 이유를 파일 이름과 함께 행 아래에 글자로 한 번 더 보여 줍니다. 마우스를 올리지 않아도 읽을 수 있습니다."
+/>
+
+<Canvas of={FileItemStories.DontErrorInTooltipOnly} />
+<Verdict
+  kind="dont"
+  en="Leave the reason only in the tooltip. The icon is not focusable, so keyboard and screen reader users never reach it."
+  ko="실패 이유를 툴팁에만 두지 마세요. 아이콘이 초점을 받지 않아서 키보드와 화면 낭독기 사용자는 끝내 읽지 못합니다."
+/>
+
+<En>
+
+## Content
+
+- Show the real file name; let it truncate rather than rewriting it.
+- Error text says what failed and what to do (파일이 5MB를 넘습니다. 나눠서
+  올려 주세요.).
+
+## Accessibility
+
+What FileItem does for you:
+
+- Download and delete are `IconButton`s with translated names and tooltips.
+
+Known gaps, and what to do:
+
+- **The error is in a hover tooltip on a non-focusable icon** (WCAG 1.4.1,
+  3.3.1). Repeat it in text, as above.
+- **The cancel-upload button is named in English** ("remove uploading file
+  button") on every screen, Korean included.
+- Progress is shown as a percentage and a bar; a screen reader is not told
+  when the upload finishes. Announce completion with a toast (WCAG 4.1.3).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 실제 파일 이름을 그대로 보여 줍니다. 길면 고쳐 쓰지 말고 말줄임표로 자릅니다.
+- 오류 문구는 무엇이 실패했고 어떻게 하면 되는지 씁니다(파일이 5MB를 넘습니다. 나눠서
+  올려 주세요.).
+
+## 접근성
+
+FileItem이 알아서 하는 일
+
+- 내려받기와 삭제는 번역된 이름과 툴팁이 있는 `IconButton`입니다.
+
+알려진 한계와 대처
+
+- **오류 문구가 초점을 받지 않는 아이콘의 툴팁에만 있습니다**(WCAG 1.4.1, 3.3.1). 위처럼
+  글자로 한 번 더 보여 줍니다.
+- **업로드 취소 버튼 이름이 영어입니다**("remove uploading file button"). 한국어 화면에서도
+  영어로 읽힙니다.
+- 진행 상황은 백분율과 막대로만 보이고, 업로드가 끝났다는 사실은 화면 낭독기에 알리지
+  않습니다. 끝나면 토스트로 알립니다(WCAG 4.1.3).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={FileItemStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **FileList**: several FileItem rows.
+- **FileInput**: picking the file.
+- **ProgressBar** / **Tooltip**: the parts it uses.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **FileList**: FileItem 여러 줄.
+- **FileInput**: 파일 고르기.
+- **ProgressBar** / **Tooltip**: 안에서 쓰는 부품.
+
+</Ko>

package/src/components/FileList/FileList.stories.tsx

@@ -53,3 +53,28 @@ export const Default: Story = {
     return <FileList {...args} files={files} onFileDelete={handleFileDelete} />;
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FileList.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoDownloadAndDelete: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: download where there is a URL',
+  render: () => (
+    <FileList
+      files={[
+        {
+          id: 1,
+          name: '2026년 3분기 이용 보고서.pdf',
+          size: 482_133,
+          fileUrl: '#',
+        },
+        { id: 2, name: '서비스 이용약관.docx', size: 91_204, fileUrl: '#' },
+        { id: 3, name: '업로드 중인 파일.pptx', progress: 40 },
+      ]}
+      onFileDownload={() => {}}
+      onFileDelete={async () => {}}
+    />
+  ),
+};

package/src/components/FileList/FileList.usage.mdx

@@ -0,0 +1,165 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FileListStories from './FileList.stories';
+
+<Meta of={FileListStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FileList
+
+A bordered list of `FileItem` rows that shows the first few files and reveals
+more on request.
+
+## When to use
+
+- The files attached to something: a chatbot's knowledge files, a project's
+  uploads, a policy's documents.
+
+## When not to use
+
+- One file → `FileItem`.
+- Hundreds of files the user searches, sorts or selects → `Table`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# FileList
+
+`FileItem` 행을 테두리 안에 모아, 처음 몇 개만 보여 주고 요청하면 더 펼치는
+목록입니다.
+
+## 언제 쓰나요
+
+- 어떤 대상에 붙은 파일들: 챗봇의 지식 파일, 프로젝트에 올린 파일, 정책 문서.
+
+## 언제 쓰지 않나요
+
+- 파일이 하나라면 `FileItem`을 씁니다.
+- 검색, 정렬, 선택이 필요한 수백 개의 파일은 `Table`을 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={FileListStories}
+  include={[
+    'files',
+    'visibleCount',
+    'onFileDownload',
+    'onFileDelete',
+    'stagger',
+  ]}
+/>
+
+<En>
+
+- Shows `visibleCount` rows (default 3); the "see more" button adds three at
+  a time. With no files it renders nothing.
+- A row gets a download button only when the file has a `fileUrl` and you pass
+  `onFileDownload`.
+- `onFileDelete` may return a promise; the row shows a spinner until it
+  settles, and a second click on the same row is ignored meanwhile.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- `visibleCount`개 행(기본 3개)을 보여 주고, "더 보기" 버튼을 누를 때마다 세 개씩
+  늘립니다. 파일이 없으면 아무것도 그리지 않습니다.
+- 내려받기 버튼은 파일에 `fileUrl`이 있고 `onFileDownload`를 넘겼을 때만 생깁니다.
+- `onFileDelete`는 프로미스를 돌려줘도 됩니다. 끝날 때까지 그 행에 스피너가 보이고, 그
+  사이 같은 행을 다시 눌러도 무시합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FileListStories.DoDownloadAndDelete} />
+<Verdict
+  kind="do"
+  en="Pass fileUrl for files that can be downloaded and let uploads in progress show their own bar."
+  ko="내려받을 수 있는 파일에는 fileUrl을 넘기고, 올리는 중인 파일은 진행 막대가 보이게 둡니다."
+/>
+
+<En>
+
+## Content
+
+- When the list is empty, say so outside it (no files yet, and how to add
+  one); FileList renders nothing.
+- Put a heading or label above it that says whose files these are.
+
+## Accessibility
+
+What FileList does for you:
+
+- Renders a real list (`<ul>` / `<li>`), so a screen reader announces the
+  number of files (WCAG 1.3.1).
+
+Known gaps, and what to do:
+
+- **The "see more" button has no focus ring.** Its styles are reset with
+  `all: unset`, which removes the outline (WCAG 2.4.7).
+- Its count shows the initial `visibleCount`, not the number of rows on
+  screen, after the first click.
+- Rows inherit the `FileItem` gaps (errors in tooltips, English cancel
+  label).
+
+## Tokens
+
+The frame and row dividers are `border.subtle`; the "see more" text and
+chevron are `fg.subtle`. Row colours are listed on the FileItem page.
+
+## Related
+
+- **FileItem**: one row.
+- **FileInput**: adding files.
+- **Table**: large file sets.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 목록이 비면 FileList는 아무것도 그리지 않으므로, 목록 밖에서 아직 파일이 없다는 것과
+  추가하는 방법을 알려 줍니다.
+- 위에 누구의 파일인지 알려 주는 제목이나 라벨을 둡니다.
+
+## 접근성
+
+FileList가 알아서 하는 일
+
+- 실제 목록(`<ul>`·`<li>`)으로 그리므로 화면 낭독기가 파일 개수를 알려 줍니다(WCAG
+  1.3.1).
+
+알려진 한계와 대처
+
+- **"더 보기" 버튼에 초점 표시가 없습니다.** 스타일을 `all: unset`으로 지워서 윤곽선이
+  사라집니다(WCAG 2.4.7).
+- 한 번 누른 뒤에도 버튼의 숫자는 화면에 보이는 행 수가 아니라 처음 `visibleCount`를
+  보여 줍니다.
+- 각 행은 `FileItem`의 한계(툴팁 속 오류, 영어 취소 버튼 이름)를 그대로 가집니다.
+
+## 토큰
+
+테두리와 행 구분선은 `border.subtle`, "더 보기" 글자와 화살표는 `fg.subtle`입니다. 행의
+색은 FileItem 페이지에 있습니다.
+
+## 관련 컴포넌트
+
+- **FileItem**: 한 줄.
+- **FileInput**: 파일 추가.
+- **Table**: 많은 파일.
+
+</Ko>

package/src/components/FlyTo/FlyTo.usage.mdx

@@ -0,0 +1,99 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as FlyToStories from './FlyTo.stories';
+
+<Meta of={FlyToStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FlyTo
+
+Sends a ghost of an element arcing from one rect to another, to say "this went
+there": a reward chip into a balance, a file into a folder.
+
+</En>
+
+<Ko>
+
+# FlyTo
+
+요소의 복제본을 한 위치에서 다른 위치로 포물선을 그리며 날려 보내, "이것이 저기로
+갔다"를 보여 줍니다. 보상 칩이 잔액으로, 파일이 폴더로 들어가는 장면에 씁니다.
+
+</Ko>
+
+<Canvas of={FlyToStories.Default} />
+
+<En>
+
+## When to use
+
+- A reward the reader just earned travels to the balance or counter it adds
+  to, and the balance updates when it lands (`onDone`).
+- An item moves to a place that is visible on screen, and seeing it go there
+  explains where it went.
+
+## When not to use
+
+- The target is not on screen, or there is no meaningful source → skip the
+  flight and `Pulse` the value that changed.
+- Only a number changed → `CountUp`, optionally inside a `Pulse`.
+- Something new appears in place → `Appear`.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` nothing flies: FlyTo renders nothing and
+  calls `onDone` right after mounting, so whatever the flight was sequencing
+  still happens.
+- The ghost is decoration. It renders into a portal at the end of the page, so
+  a screen reader can reach a copy of its text there. Pass `aria-hidden` when
+  the ghost holds text.
+- The meaning lives in the state change, not the flight. Update the target
+  value in `onDone`, and if the reader must hear it, announce it yourself
+  (WCAG 4.1.3).
+- The ghost ignores the pointer (`pointer-events: none`), so it never blocks
+  a click.
+
+## Props
+
+`from` and `to` are viewport rects, usually from `getBoundingClientRect()`.
+The caller mounts FlyTo to start a flight and unmounts it in `onDone`.
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 사용자가 방금 받은 보상이 그것이 더해질 잔액이나 카운터로 날아가고, 도착하는 순간
+  잔액이 바뀔 때(`onDone`).
+- 항목이 화면에 보이는 다른 자리로 옮겨 가고, 날아가는 모습이 어디로 갔는지를 설명해 줄 때.
+
+## 언제 쓰지 않나요
+
+- 목적지가 화면에 없거나 출발점이 뚜렷하지 않다면 날리지 말고, 바뀐 값에 `Pulse`를
+  씁니다.
+- 숫자만 바뀌었다면 `CountUp`을 쓰고, 필요하면 `Pulse`로 감쌉니다.
+- 새 요소가 제자리에 나타난다면 `Appear`를 씁니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 아무것도 날지 않습니다. FlyTo는 아무것도
+  그리지 않고 마운트 직후 `onDone`을 부르므로, 비행 뒤에 이어지던 일은 그대로 진행됩니다.
+- 복제본은 장식입니다. 페이지 끝의 포털에 그려지므로 화면 낭독기가 거기서 그 글자를 한
+  번 더 만날 수 있습니다. 복제본에 글자가 있다면 `aria-hidden`을 넘깁니다.
+- 뜻은 비행이 아니라 상태 변화에 있습니다. `onDone`에서 목적지 값을 바꾸고, 사용자가
+  들어야 하는 변화라면 직접 알립니다(WCAG 4.1.3).
+- 복제본은 포인터를 받지 않으므로(`pointer-events: none`) 클릭을 막지 않습니다.
+
+## 속성
+
+`from`과 `to`는 뷰포트 기준 사각형이며 보통 `getBoundingClientRect()`에서 얻습니다.
+비행을 시작하려면 FlyTo를 마운트하고, `onDone`에서 언마운트합니다.
+
+</Ko>
+
+<ArgTypes of={FlyToStories} include={['from', 'to', 'lift', 'onDone']} />

package/src/components/Form/Form.stories.tsx

@@ -0,0 +1,149 @@
+import { useState } from 'react';
+import { Box, Dialog } from '@chakra-ui/react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '../Button';
+import { Input } from '../Input';
+import { SelectField } from '../Select';
+import { Switch } from '../Switch';
+import { Textarea } from '../Textarea';
+import { Subtext } from '../Typography';
+import {
+  FieldRow,
+  FormFooter,
+  FormModalFooter,
+  FormScrollArea,
+  FormSection,
+} from '.';
+
+/**
+ * The Form building blocks together: `FormSection` groups, `FieldRow` fields,
+ * a `FormFooter` pinned under a `FormScrollArea`. Each part has its own story
+ * set below this one.
+ */
+const meta = {
+  title: 'Components/Form',
+  parameters: { layout: 'padded' },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+const MODELS = [
+  { label: 'GPT-5', value: 'gpt-5' },
+  { label: 'Claude Sonnet', value: 'claude-sonnet' },
+  { label: 'Gemini Flash', value: 'gemini-flash' },
+];
+
+const SettingsPanel = ({ withErrors = false }: { withErrors?: boolean }) => {
+  const [name, setName] = useState(withErrors ? '' : '사내 규정 도우미');
+  return (
+    <Box
+      h="460px"
+      w="400px"
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderRadius="12px"
+      overflow="hidden"
+    >
+      <FormScrollArea>
+        <Box p={4} flex={1}>
+          <FormSection title="기본 정보" gap={4}>
+            <FieldRow
+              label="챗봇 이름"
+              required
+              error={
+                withErrors && !name ? '챗봇 이름을 입력해 주세요.' : undefined
+              }
+            >
+              <Input value={name} onChange={(e) => setName(e.target.value)} />
+            </FieldRow>
+            <FieldRow label="설명" helperText="목록에서 이름 아래에 보입니다.">
+              <Textarea rows={3} />
+            </FieldRow>
+          </FormSection>
+          <FormSection title="동작" divider mt={6} gap={4}>
+            <FieldRow label="기본 모델">
+              <SelectField
+                ariaLabel="기본 모델"
+                options={MODELS}
+                defaultValue="gpt-5"
+              />
+            </FieldRow>
+            <Switch display="flex" justifyContent="space-between" w="100%">
+              <Switch.Label>웹 검색 사용</Switch.Label>
+              <Switch.Control />
+            </Switch>
+          </FormSection>
+        </Box>
+        <FormFooter
+          meta={<Subtext color="fg.muted">오후 2:14에 저장됨</Subtext>}
+          action={<Button variant="primary">저장</Button>}
+        />
+      </FormScrollArea>
+    </Box>
+  );
+};
+
+/** A settings panel: two sections, a pinned footer with meta and action. */
+export const Basic: Story = {
+  render: () => <SettingsPanel />,
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Form.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoErrorsAtTheField: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: errors at the field',
+  render: () => <SettingsPanel withErrors />,
+};
+
+export const DoModalFooter: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: FormModalFooter in a modal form',
+  render: () => (
+    // `ModalFooter` reads the dialog's style context; a closed root provides it
+    // without opening anything.
+    <Dialog.Root>
+      <Box
+        w="480px"
+        bg="bg.surface"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        borderRadius="12px"
+      >
+        <FormModalFooter
+          onDelete={() => {}}
+          deleteLabel="그룹 삭제"
+          onCancel={() => {}}
+          cancelLabel="취소"
+          submitLabel="저장"
+          onSubmit={() => {}}
+        />
+      </Box>
+    </Dialog.Root>
+  ),
+};
+
+export const DontHandRolledFooter: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: a hand-rolled footer",
+  render: () => (
+    <Box
+      w="480px"
+      p={4}
+      display="flex"
+      gap={2}
+      bg="bg.surface"
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderRadius="12px"
+    >
+      <Button variant="primary">저장</Button>
+      <Button variant="danger">그룹 삭제</Button>
+      <Button variant="subtle">취소</Button>
+    </Box>
+  ),
+};