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

package/src/components/InfoSprinkle/InfoSprinkle.stories.tsx

@@ -1,7 +1,11 @@
 import { Box, HStack, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Subtitle, Text } from '../Typography';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { Input } from '../Input';
+import { Subtext, Subtitle, Text } from '../Typography';
 import { InfoSprinkle } from './InfoSprinkle';
 
 const meta = {
@@ -39,3 +43,75 @@ export const LargerBaseFontSize: Story = {
     baseFontSize: '18px',
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `InfoSprinkle.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each card is held open (`open`) so the page shows it
+// without a hover.
+
+export const DoDefineALabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: define the label next to it',
+  render: () => (
+    <Box pt="96px" px={16}>
+      <Card p={4} w="240px">
+        <HStack gap={1}>
+          <Subtext>활성 멤버</Subtext>
+          <InfoSprinkle
+            open
+            iconButtonProps={{ size: 'xs', 'aria-label': '활성 멤버 설명' }}
+          >
+            <Text maxW="220px">
+              최근 30일 동안 한 번 이상 대화한 멤버 수입니다.
+            </Text>
+          </InfoSprinkle>
+        </HStack>
+        <Text fontWeight="bold" fontSize="lg">
+          128
+        </Text>
+      </Card>
+    </Box>
+  ),
+};
+
+export const DontHideTheRule: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: hide a rule the user must follow",
+  render: () => (
+    <Box pt="96px" px={16}>
+      <VStack align="stretch" gap={1} w="260px">
+        <HStack gap={1}>
+          <Text as="label" htmlFor="usage-password" fontWeight="semibold">
+            새 비밀번호
+          </Text>
+          <InfoSprinkle
+            open
+            iconButtonProps={{ size: 'xs', 'aria-label': '비밀번호 규칙' }}
+          >
+            <Text maxW="220px">
+              8자 이상, 숫자와 특수문자를 포함해야 합니다.
+            </Text>
+          </InfoSprinkle>
+        </HStack>
+        <Input id="usage-password" type="password" />
+      </VStack>
+    </Box>
+  ),
+};
+
+/** Tokens the trigger and card read: the icon colour from `InfoSprinkle.tsx`, the card from the Chakra HoverCard recipe. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'fg.muted', use: <T en="Icon" ko="아이콘" /> },
+        { token: 'bg.panel', use: <T en="Card" ko="카드" /> },
+      ]}
+    />
+  ),
+};

package/src/components/InfoSprinkle/InfoSprinkle.usage.mdx

@@ -0,0 +1,189 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as InfoSprinkleStories from './InfoSprinkle.stories';
+
+<Meta of={InfoSprinkleStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# InfoSprinkle
+
+A small info icon next to a label that opens a card with a definition or a
+short explanation, on hover, on focus, or on tap.
+
+## When to use
+
+- To define a term on a stat card or a table header: what "활성 멤버" counts,
+  whether a member count includes subgroups.
+- To explain how a number is calculated, such as rounding.
+- To say when something runs, such as an analysis schedule.
+
+## When not to use
+
+- A rule the user must follow to succeed (password rules, file limits) → put it
+  in visible helper text under the field.
+- The name of an icon-only button → `Tooltip`.
+- Content with links or controls → `Popover`.
+- A warning or a status → `Banner` or `Badge`.
+
+## Variants and what they mean
+
+InfoSprinkle has no visual variants. Set the size and name of the icon with
+`iconButtonProps`, the card's padding with `contentProps`, and its placement
+with `positioning` (default `top`).
+
+</En>
+
+<Ko>
+
+# InfoSprinkle
+
+라벨 옆의 작은 정보 아이콘입니다. 포인터를 올리거나, 초점이 닿거나, 누르면 용어 설명이나
+짧은 해설을 담은 카드가 열립니다.
+
+## 언제 쓰나요
+
+- 통계 카드나 표 머리글의 용어를 설명할 때: "활성 멤버"가 무엇을 세는지, 멤버 수에 하위
+  그룹이 들어가는지.
+- 반올림처럼 숫자를 계산하는 방식을 설명할 때.
+- 분석 일정처럼 무언가가 언제 실행되는지 알릴 때.
+
+## 언제 쓰지 않나요
+
+- 비밀번호 규칙이나 파일 제한처럼 사용자가 꼭 지켜야 하는 규칙은 입력란 아래에 눈에 보이는
+  도움말로 씁니다.
+- 아이콘만 있는 버튼의 이름은 `Tooltip`으로 보입니다.
+- 링크나 컨트롤이 들어가는 내용은 `Popover`에 넣습니다.
+- 경고나 상태는 `Banner`나 `Badge`로 알립니다.
+
+## 변형과 뜻
+
+InfoSprinkle에는 모양 변형이 없습니다. 아이콘의 크기와 이름은 `iconButtonProps`로,
+카드 여백은 `contentProps`로, 위치는 `positioning`(기본 `top`)으로 정합니다.
+
+</Ko>
+
+<ArgTypes of={InfoSprinkleStories} include={['iconButtonProps', 'contentProps', 'baseFontSize']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={InfoSprinkleStories.DoDefineALabel} />
+<Verdict
+  kind="do"
+  en="Put it right after the label it explains, and name the icon after that label ('활성 멤버 설명')."
+  ko="설명하는 라벨 바로 뒤에 두고, 아이콘 이름도 그 라벨을 따라 붙입니다('활성 멤버 설명')."
+/>
+
+<Canvas of={InfoSprinkleStories.DontHideTheRule} />
+<Verdict
+  kind="dont"
+  en="Hide a rule the user must follow behind the icon. Most people will not open it, and they find out only when the form is rejected. Show the rule under the field."
+  ko="꼭 지켜야 하는 규칙을 아이콘 뒤에 숨기지 마세요. 대부분은 열어 보지 않고, 양식이 거부된 뒤에야 알게 됩니다. 규칙은 입력란 아래에 보이게 씁니다."
+/>
+
+<En>
+
+## Content
+
+- One or two sentences that define or explain. Full stops, sentence case.
+- Start with the answer: "최근 30일 동안 한 번 이상 대화한 멤버 수입니다.", not
+  "이 숫자는 …를 뜻합니다".
+- No links or buttons inside; the card closes as soon as the pointer or focus
+  leaves the icon.
+
+## Accessibility
+
+What InfoSprinkle does for you:
+
+- The trigger is a real `IconButton`, so it is reachable with `Tab`
+  (WCAG 2.1.1). The card opens on hover and on focus, and on tap on touch
+  devices that have no hover.
+- The card is portalled and closes when the pointer or focus moves away.
+
+What you still have to do:
+
+- **Name each icon.** The default `aria-label` is the English "Info", and every
+  icon on the screen gets the same one. Pass a name through `iconButtonProps`
+  that says what it explains: `'aria-label': '활성 멤버 설명'` (WCAG 2.4.6,
+  4.1.2).
+- **Do not rely on screen readers reading the card.** It is a Chakra
+  `HoverCard`: the trigger has no `aria-describedby` or `aria-expanded`
+  pointing at it, and the card sits at the end of the page. Keep the
+  information a screen reader user needs in visible text or in the label.
+- Do not put the only copy of required information in it.
+
+## Tokens
+
+The icon colour is set in `InfoSprinkle.tsx`; the card colour comes from
+Chakra's HoverCard recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 용어를 정의하거나 해설하는 한두 문장을 씁니다. 마침표를 찍습니다.
+- 답부터 씁니다. "이 숫자는 …를 뜻합니다"가 아니라 "최근 30일 동안 한 번 이상 대화한
+  멤버 수입니다."처럼 씁니다.
+- 안에 링크나 버튼을 넣지 않습니다. 포인터나 초점이 아이콘을 떠나면 카드가 바로 닫힙니다.
+
+## 접근성
+
+InfoSprinkle이 알아서 하는 일
+
+- 여는 요소가 실제 `IconButton`이라 `Tab`으로 닿을 수 있습니다(WCAG 2.1.1). 포인터를
+  올리거나 초점이 닿으면 카드가 열리고, 마우스 올리기가 없는 터치 기기에서는 누르면
+  열립니다.
+- 카드는 포털로 그려지며, 포인터나 초점이 떠나면 닫힙니다.
+
+직접 챙겨야 하는 일
+
+- **아이콘마다 이름을 붙입니다.** 기본 `aria-label`은 영어 "Info"라서 화면의 모든 아이콘이
+  같은 이름을 갖게 됩니다. `iconButtonProps`로 무엇을 설명하는지 밝힌 이름을 넘깁니다.
+  예: `'aria-label': '활성 멤버 설명'`(WCAG 2.4.6, 4.1.2).
+- **화면 낭독기가 카드를 읽어 줄 것이라 기대하지 않습니다.** Chakra `HoverCard`라서
+  여는 버튼에 카드를 가리키는 `aria-describedby`나 `aria-expanded`가 없고, 카드는 페이지
+  맨 끝에 붙습니다. 화면 낭독기 사용자에게 필요한 정보는 보이는 문구나 라벨에 둡니다.
+- 꼭 필요한 정보를 이 카드에만 두지 않습니다.
+
+## 토큰
+
+아이콘 색은 `InfoSprinkle.tsx`에서, 카드 색은 Chakra HoverCard 레시피에서 정합니다.
+
+</Ko>
+
+<Canvas of={InfoSprinkleStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tooltip**: the name of an icon-only button.
+- **Popover**: a panel with links or controls.
+- **FormControl**: helper text under a field, for rules the user must follow.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tooltip**: 아이콘만 있는 버튼의 이름.
+- **Popover**: 링크나 컨트롤이 있는 패널.
+- **FormControl**: 사용자가 지켜야 하는 규칙을 담는 입력란 아래 도움말.
+
+</Ko>

package/src/components/InlineCode/InlineCode.stories.tsx

@@ -0,0 +1,75 @@
+import { Meta, StoryObj } from '@storybook/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Text } from '../Typography';
+import { InlineCode } from './InlineCode';
+
+const meta = {
+  title: 'Components/InlineCode',
+  component: InlineCode,
+  args: {
+    children: 'model_id',
+  },
+} satisfies Meta<typeof InlineCode>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {};
+
+/** In running text, where it is meant to be used. */
+export const InSentence: Story = {
+  render: (args) => (
+    <Text>
+      요청 본문의 <InlineCode {...args} /> 칸에 모델 이름을 넣습니다.
+    </Text>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `InlineCode.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 DoIdentifierInSentence: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: names the user types or sees in code',
+  render: () => (
+    <Text>
+      응답이 끊기면 <InlineCode>finish_reason</InlineCode> 값이{' '}
+      <InlineCode>length</InlineCode>인지 확인하세요.
+    </Text>
+  ),
+};
+
+export const DontEmphasis: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: code styling for emphasis",
+  render: () => (
+    <Text>
+      이 작업은 <InlineCode>되돌릴 수 없습니다</InlineCode>.
+    </Text>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.subtle', use: <T en="Chip fill" ko="칩 배경" /> },
+        { token: 'fg.default', use: <T en="Text" ko="글자" /> },
+        {
+          token: 'border.subtle',
+          use: <T en="1px ring (box-shadow)" ko="1px 테두리(box-shadow)" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/InlineCode/InlineCode.usage.mdx

@@ -0,0 +1,142 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as InlineCodeStories from './InlineCode.stories';
+
+<Meta of={InlineCodeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# InlineCode
+
+Code inside a sentence: a field name, a value, a shortcut. A small chip one
+size below the text around it (`textStyle="subtext"`, em-relative), with a
+`bg.subtle` fill and a hairline ring.
+
+## When to use
+
+- Identifiers the user types or will see in code or settings:
+  `finish_reason`, `model_id`, a file name.
+
+## When not to use
+
+- More than one line → `Code`.
+- A value the user only needs to copy → `CopyableCode`.
+- Emphasis or warnings → plain text, bold if it must stand out.
+- Keyboard keys in instructions → write them out (Ctrl + C); the chip says
+  "code", not "key".
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# InlineCode
+
+문장 안의 코드입니다. 필드 이름, 값, 단축키 같은 것을 씁니다. 주변 글자보다 한 단계
+작은 칩으로 그려지고(`textStyle="subtext"`, em 단위), `bg.subtle` 배경과 얇은 테두리가
+있습니다.
+
+## 언제 쓰나요
+
+- 사용자가 직접 입력하거나 코드·설정에서 보게 될 식별자: `finish_reason`,
+  `model_id`, 파일 이름.
+
+## 언제 쓰지 않나요
+
+- 두 줄 이상이라면 `Code`를 씁니다.
+- 복사만 하면 되는 값은 `CopyableCode`를 씁니다.
+- 강조나 경고에는 일반 글자를 쓰고, 꼭 눈에 띄어야 하면 굵게 씁니다.
+- 안내문의 키보드 키는 글자로 씁니다(Ctrl + C). 이 칩은 '코드'라는 뜻이지 '키'라는
+  뜻이 아닙니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={InlineCodeStories.DoIdentifierInSentence} />
+<Verdict
+  kind="do"
+  en="Mark names and values the user will meet in code."
+  ko="사용자가 코드에서 만나게 될 이름과 값을 표시합니다."
+/>
+
+<Canvas of={InlineCodeStories.DontEmphasis} />
+<Verdict
+  kind="dont"
+  en="Use code styling to make words stand out. It tells the reader the words are code."
+  ko="말을 돋보이게 하려고 코드 모양을 쓰지 마세요. 읽는 사람은 그 말을 코드로 받아들입니다."
+/>
+
+<En>
+
+## Content
+
+- Write the identifier exactly as it appears, including case.
+- Keep Korean particles outside the chip: `length`인지, not `length인지`.
+
+## Accessibility
+
+What InlineCode does for you:
+
+- It renders `<code>`, so assistive technology that reports code can, and
+  the chip ring keeps it visible on `bg.sunken`, where the fill alone would
+  vanish.
+
+What you still have to do:
+
+- Nothing in the chip is read differently by most screen readers. Do not
+  rely on the code styling to carry meaning (WCAG 1.3.1); the sentence must
+  make sense on its own.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 식별자는 대소문자까지 보이는 그대로 씁니다.
+- 한국어 조사는 칩 밖에 둡니다. `length인지`가 아니라 `length`인지로 씁니다.
+
+## 접근성
+
+InlineCode가 알아서 하는 일
+
+- `<code>`로 그리므로 코드를 구분해 알려 주는 보조 기술은 그렇게 읽습니다. 배경만으로는
+  `bg.sunken` 위에서 칩이 사라지기 때문에 테두리를 둡니다.
+
+직접 챙겨야 하는 일
+
+- 대부분의 화면 낭독기는 칩 안의 글자를 다르게 읽지 않습니다. 코드 모양에 뜻을 맡기지
+  말고(WCAG 1.3.1), 문장만으로 뜻이 통하게 씁니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={InlineCodeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Code**: multi-line code.
+- **CopyableCode**: a value with a copy button.
+- **Typography**: the text InlineCode sits in.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Code**: 여러 줄 코드.
+- **CopyableCode**: 복사 버튼이 있는 값.
+- **Typography**: InlineCode가 들어가는 본문.
+
+</Ko>

package/src/components/Input/Input.stories.tsx

@@ -3,6 +3,9 @@ import { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 
 import { PhoneFilledIcon, SearchIcon, MailIcon } from '@/components/Icon';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
 import { MaxLengthIndicator } from '../MaxLengthIndicator';
 
 import { Input } from './Input';
@@ -257,3 +260,180 @@ export const FocusState: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Input.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 DoLabelAbove: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a label above the field',
+  render: () => (
+    <Box maxW="360px">
+      <FieldRow
+        label="업무용 이메일"
+        helperText="초대 메일이 이 주소로 갑니다."
+        required
+      >
+        <Input
+          type="email"
+          autoComplete="email"
+          placeholder="name@company.com"
+        />
+      </FieldRow>
+    </Box>
+  ),
+};
+
+export const DontPlaceholderAsLabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the placeholder as the label",
+  render: () => (
+    <Box maxW="360px">
+      <Input type="email" placeholder="업무용 이메일" />
+    </Box>
+  ),
+};
+
+export const DoErrorInWords: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: say what is wrong, under the field',
+  render: () => (
+    <Box maxW="360px">
+      <FieldRow label="업무용 이메일" error="이메일 주소 형식이 아닙니다.">
+        <Input type="email" value="name@company" onChange={() => {}} />
+      </FieldRow>
+    </Box>
+  ),
+};
+
+export const DontBorderOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a red border and nothing else",
+  render: () => (
+    <Box maxW="360px">
+      <Input type="email" value="name@company" onChange={() => {}} invalid />
+    </Box>
+  ),
+};
+
+export const DoMaskedAmount: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: maskNumber for amounts',
+  render: () => {
+    const [value, setValue] = useState('2000000');
+    return (
+      <Box maxW="360px">
+        <FieldRow
+          label="월 크레딧 한도"
+          helperText={`저장되는 값: ${value || '(비어 있음)'}`}
+        >
+          <Input
+            type="number"
+            maskNumber
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+          />
+        </FieldRow>
+      </Box>
+    );
+  },
+};
+
+export const DoCountWithLimit: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: show the limit next to maxLength',
+  render: () => {
+    const [value, setValue] = useState('마케팅팀');
+    return (
+      <Box maxW="360px">
+        <FieldRow
+          label="그룹 이름"
+          endAdornment={
+            <MaxLengthIndicator value={value.length} maxLength={20} />
+          }
+        >
+          <Input
+            maxLength={20}
+            value={value}
+            onChange={(e) => setValue(e.target.value)}
+          />
+        </FieldRow>
+      </Box>
+    );
+  },
+};
+
+/**
+ * Tokens Input reads. Input has no styles file — the values are written in
+ * `Input.tsx` (and mirrored by `Select.styles.ts`); this list follows that file.
+ */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.surface',
+          use: <T en="Field background" ko="입력란 배경" />,
+        },
+        { token: 'fg.default', use: <T en="Typed text" ko="입력한 글자" /> },
+        {
+          token: 'border.control',
+          use: (
+            <T
+              en="Border at rest (3:1 against the page)"
+              ko="평소 테두리(배경과 3:1)"
+            />
+          ),
+        },
+        {
+          token: 'fg.icon',
+          use: <T en="Border on hover" ko="마우스를 올렸을 때 테두리" />,
+        },
+        {
+          token: 'primary.main',
+          use: (
+            <T
+              en="Border and 1px ring on focus"
+              ko="초점을 받았을 때 테두리와 1px 링"
+            />
+          ),
+        },
+        {
+          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: 'border.subtle',
+          use: <T en="Read-only border" ko="읽기 전용 테두리" />,
+        },
+        {
+          token: 'disabled.bg',
+          use: <T en="Disabled background" ko="비활성 배경" />,
+        },
+        {
+          token: 'disabled.fg',
+          use: <T en="Disabled text" ko="비활성 글자" />,
+        },
+      ]}
+    />
+  ),
+};