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

package/src/components/PinInput/PinInput.usage.mdx

@@ -0,0 +1,194 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as PinInputStories from './PinInput.stories';
+
+<Meta of={PinInputStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# PinInput
+
+A row of single-character boxes for a short code: a sign-in code sent by
+email, a two-factor code from an authenticator app.
+
+## When to use
+
+- A code of fixed, known length (4 to 8 characters) that the user copies from
+  somewhere else.
+
+## When not to use
+
+- A password → `PasswordInput`.
+- A code of unknown or variable length, or one usually pasted from a
+  clipboard as a whole (a licence key, an invite token) → `Input`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# PinInput
+
+짧은 코드를 한 칸에 한 글자씩 받는 입력란입니다. 메일로 받은 로그인 코드나 인증 앱의
+2단계 인증 코드에 씁니다.
+
+## 언제 쓰나요
+
+- 다른 곳에서 보고 옮겨 적는, 길이가 정해진 코드(4~8자).
+
+## 언제 쓰지 않나요
+
+- 비밀번호는 `PasswordInput`을 씁니다.
+- 길이가 정해지지 않았거나, 대개 통째로 붙여 넣는 값(라이선스 키, 초대 토큰)은
+  `Input`을 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={PinInputStories}
+  include={['length', 'value', 'onChange', 'onComplete', 'inputProps']}
+/>
+
+<En>
+
+- `value` is one string, and `onChange` / `onComplete` receive one string.
+  `onComplete` fires when every box is filled; submit from there.
+- `type` (`numeric`, `alphanumeric`, `alphabetic`), `otp`, `mask`, `invalid`
+  and `disabled` come from Chakra's `PinInput.Root`. `otp` sets
+  `autocomplete="one-time-code"`, which lets phones offer the code from SMS.
+- `inputProps` go to the hidden input that carries the whole value, for
+  `name` in a native form.
+- Boxes are empty by default (`placeholder=""`).
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- `value`는 문자열 하나이고, `onChange`와 `onComplete`도 문자열 하나를 받습니다.
+  `onComplete`는 모든 칸이 채워지면 호출되므로 여기서 제출합니다.
+- `type`(`numeric`, `alphanumeric`, `alphabetic`), `otp`, `mask`, `invalid`,
+  `disabled`는 Chakra `PinInput.Root`의 속성입니다. `otp`를 주면
+  `autocomplete="one-time-code"`가 붙어 휴대폰이 문자로 받은 코드를 제안합니다.
+- `inputProps`는 전체 값을 담는 숨은 입력란에 전달됩니다. 네이티브 폼에서 `name`을 줄
+  때 씁니다.
+- 칸은 기본으로 비어 있습니다(`placeholder=""`).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={PinInputStories.DoSayWhereTheCodeWent} />
+<Verdict
+  kind="do"
+  en="Say above the boxes how long the code is and where it was sent."
+  ko="칸 위에 코드가 몇 자리인지, 어디로 보냈는지 적습니다."
+/>
+
+<Canvas of={PinInputStories.DontCodeWithoutContext} />
+<Verdict
+  kind="dont"
+  en="Show the boxes with nothing around them. The user does not know which code to look for, and a screen reader has nothing to read before the first box."
+  ko="아무 설명 없이 칸만 두지 마세요. 어떤 코드를 찾아야 하는지 알 수 없고, 화면 낭독기도 첫 칸 앞에서 읽을 것이 없습니다."
+/>
+
+<Canvas of={PinInputStories.DoErrorBelow} />
+<Verdict
+  kind="do"
+  en="Mark a wrong code with invalid and a message that says what to do next."
+  ko="틀린 코드는 invalid로 표시하고, 다음에 무엇을 할지 알려 주는 문구를 함께 둡니다."
+/>
+
+<En>
+
+## Content
+
+- The sentence above the boxes: the length and the destination, for example
+  "Enter the 6-digit code we sent to name@company.com".
+- Offer a way out next to it: resend the code, or use another method.
+- Error: what happened and what to do (코드가 맞지 않습니다. 메일을 다시 확인해
+  주세요.).
+
+## Accessibility
+
+What PinInput does for you:
+
+- Each box is a native input. Typing moves focus to the next box and
+  Backspace moves back; this behaviour comes from Chakra.
+- Focus shows a `primary.main` border and ring (WCAG 2.4.7). On touch devices
+  the text is raised to 16px so iOS Safari does not zoom.
+
+What you still have to do:
+
+- **Put the instruction in text right before the boxes**, so the first thing a
+  screen reader reaches is what the code is for (WCAG 3.3.2).
+- Chakra names each box in English ("pin code 1 of 6"). Pass Chakra's
+  `translations` when the screen is Korean.
+- Put errors in words, not only in the red border (WCAG 1.4.1, 3.3.1).
+- Do not auto-submit on a time limit without saying how long the code is
+  valid.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 칸 위 문장에는 자릿수와 보낸 곳을 씁니다. 예: name@company.com 으로 보낸 6자리
+  코드를 입력하세요.
+- 바로 옆에 다른 길을 둡니다. 코드 다시 보내기나 다른 인증 방법입니다.
+- 오류 문구는 무슨 일이 있었고 무엇을 하면 되는지 씁니다. 예: 코드가 맞지 않습니다.
+  메일을 다시 확인해 주세요.
+
+## 접근성
+
+PinInput이 알아서 하는 일
+
+- 칸마다 네이티브 입력란입니다. 입력하면 다음 칸으로, Backspace를 누르면 앞 칸으로
+  초점이 옮겨 갑니다. Chakra가 제공하는 동작입니다.
+- 초점을 받으면 `primary.main` 테두리와 링이 보입니다(WCAG 2.4.7). 터치 기기에서는
+  글자를 16px로 키워 iOS Safari가 화면을 확대하지 않게 합니다.
+
+직접 챙겨야 하는 일
+
+- **안내 문장을 칸 바로 앞에 둡니다.** 그래야 화면 낭독기가 칸보다 코드의 용도를 먼저
+  읽습니다(WCAG 3.3.2).
+- Chakra는 칸마다 영어 이름("pin code 1 of 6")을 붙입니다. 한국어 화면에서는 Chakra의
+  `translations`를 넘깁니다.
+- 오류는 빨간 테두리만이 아니라 문구로 알립니다(WCAG 1.4.1, 3.3.1).
+- 코드의 유효 시간을 알리지 않은 채 시간이 지나면 자동으로 넘어가게 하지 않습니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={PinInputStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **PasswordInput**: a secret the user chooses.
+- **Input**: codes of variable length.
+- **FieldRow**: the error under the boxes.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **PasswordInput**: 사용자가 정하는 비밀 값.
+- **Input**: 길이가 정해지지 않은 코드.
+- **FieldRow**: 칸 아래 오류 문구.
+
+</Ko>

package/src/components/Popover/Popover.stories.tsx

@@ -1,6 +1,9 @@
-import { Stack, Text } from '@chakra-ui/react';
+import type { ReactNode } from 'react';
+import { Box, Stack, Text } 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';
 import { Checkbox } from '../Checkbox';
 import { Popover } from './Popover';
@@ -139,3 +142,103 @@ export const Comparison: Story = {
     </Stack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Popover.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Popover content is not portalled, so an open popover sits
+// in the canvas; `autoFocus={false}` keeps it from taking focus on page load.
+
+const OpenPopover = ({
+  trigger,
+  children,
+}: {
+  trigger: string;
+  children: ReactNode;
+}) => (
+  <Box h="260px">
+    <Popover
+      open
+      autoFocus={false}
+      closeOnInteractOutside={false}
+      closeOnEscape={false}
+      // No flip: a canvas below the fold would otherwise open upward and
+      // be clipped by the canvas.
+      positioning={{ placement: 'bottom-start', flip: false }}
+    >
+      <Popover.Trigger asChild>
+        <Button variant="secondary">{trigger}</Button>
+      </Popover.Trigger>
+      <Popover.Content>
+        <Popover.Arrow>
+          <Popover.ArrowTip />
+        </Popover.Arrow>
+        <Popover.Body>{children}</Popover.Body>
+      </Popover.Content>
+    </Popover>
+  </Box>
+);
+
+export const DoControlsPanel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a few controls about the trigger',
+  render: () => (
+    <OpenPopover trigger="공유">
+      <Popover.Title fontWeight="bold">링크 공유</Popover.Title>
+      <Stack gap={3} mt={2}>
+        <Checkbox defaultChecked>
+          <Checkbox.Control />
+          <Checkbox.Label>조직 안의 모든 사람</Checkbox.Label>
+        </Checkbox>
+        <Checkbox>
+          <Checkbox.Control />
+          <Checkbox.Label>대화 기록 포함</Checkbox.Label>
+        </Checkbox>
+      </Stack>
+      <Popover.Footer mt={4} p={0}>
+        <Button size="sm" variant="primary">
+          링크 복사
+        </Button>
+      </Popover.Footer>
+    </OpenPopover>
+  ),
+};
+
+export const DontActionListInPopover: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a list of actions in a popover",
+  render: () => (
+    <OpenPopover trigger="더 보기">
+      <Stack gap={1} align="stretch">
+        <Button variant="ghost" size="sm">
+          이름 변경
+        </Button>
+        <Button variant="ghost" size="sm">
+          복제
+        </Button>
+        <Button variant="ghost" size="sm">
+          삭제
+        </Button>
+      </Stack>
+    </OpenPopover>
+  ),
+};
+
+/** Tokens the popover reads: its border from `PopoverContent` / `PopoverArrowTip`, its panel from the Chakra recipe. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.panel', use: <T en="Panel" ko="패널" /> },
+        {
+          token: 'border.subtle',
+          use: <T en="Panel and arrow border" ko="패널·화살표 테두리" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Popover/Popover.usage.mdx

@@ -0,0 +1,197 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as PopoverStories from './Popover.stories';
+
+<Meta of={PopoverStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Popover
+
+A small panel anchored to the button that opened it, for a few controls or a
+short piece of content about that button. The page behind stays usable.
+
+## When to use
+
+- For a few settings that belong to one button: share options, an inline credit
+  limit editor, a mail-block toggle.
+- For a panel of content opened from the top bar: notifications, announcements,
+  the account panel.
+- For a picker that needs more than a plain list, such as a model picker with
+  a search field.
+
+## When not to use
+
+- A list of actions on one object → `Menu`. Menu gives arrow-key navigation and
+  menu roles; a column of buttons in a popover gives neither.
+- A short label or hint on hover → `Tooltip`. A definition next to a label →
+  `InfoSprinkle`.
+- A task the user must finish or cancel before going on → `Modal`.
+- On a phone, a list to pick from → `BottomSheet`.
+
+## Variants and what they mean
+
+Popover has no visual variants. `baseFontSize` (default `14px`) sets the base
+size that the content's `em` spacing and type scale from.
+
+</En>
+
+<Ko>
+
+# Popover
+
+자기를 연 버튼에 붙어 열리는 작은 패널입니다. 그 버튼에 관한 컨트롤 몇 개나 짧은 내용을
+담고, 뒤의 페이지는 그대로 쓸 수 있습니다.
+
+## 언제 쓰나요
+
+- 한 버튼에 딸린 설정 몇 가지를 보일 때: 공유 옵션, 바로 고치는 크레딧 한도, 메일 차단
+  설정.
+- 상단 바에서 여는 내용 패널: 알림, 공지, 계정 패널.
+- 단순한 목록보다 많은 것이 필요한 선택기: 검색창이 있는 모델 선택기.
+
+## 언제 쓰지 않나요
+
+- 한 대상에 대한 동작 목록은 `Menu`를 씁니다. Menu는 방향키 이동과 메뉴 역할을
+  제공하지만, Popover 안에 버튼을 늘어놓으면 둘 다 없습니다.
+- 마우스를 올렸을 때 보이는 짧은 라벨이나 힌트는 `Tooltip`, 라벨 옆의 용어 설명은
+  `InfoSprinkle`을 씁니다.
+- 끝내거나 취소해야 다음으로 넘어갈 수 있는 작업은 `Modal`을 씁니다.
+- 휴대폰에서 목록 중 하나를 고르게 할 때는 `BottomSheet`를 씁니다.
+
+## 변형과 뜻
+
+Popover에는 모양 변형이 없습니다. `baseFontSize`(기본 `14px`)는 콘텐츠의 `em` 단위
+간격과 글자 크기가 따르는 기준 크기입니다.
+
+</Ko>
+
+<ArgTypes of={PopoverStories} include={['baseFontSize']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={PopoverStories.DoControlsPanel} />
+<Verdict
+  kind="do"
+  en="Title the panel with Popover.Title and keep it to a few controls about the trigger."
+  ko="Popover.Title로 패널에 제목을 달고, 연 버튼에 관한 컨트롤 몇 개만 담습니다."
+/>
+
+<Canvas of={PopoverStories.DontActionListInPopover} />
+<Verdict
+  kind="dont"
+  en="Stack action buttons in a popover. Use Menu: it has arrow keys, typeahead and the menu roles a screen reader expects."
+  ko="Popover 안에 동작 버튼을 쌓지 마세요. Menu를 씁니다. Menu에는 방향키 이동, 글자 입력으로 찾기, 화면 낭독기가 기대하는 메뉴 역할이 있습니다."
+/>
+
+<En>
+
+## Content
+
+- **Title:** a noun phrase in sentence case, no full stop: "링크 공유".
+- Keep it short enough to read without scrolling. If it needs a scroll bar, it
+  probably needs a page or a modal.
+- A button inside the panel names its action ("링크 복사"), like any other
+  button.
+
+## Accessibility
+
+What Popover does for you:
+
+- The trigger gets `aria-haspopup="dialog"`, `aria-expanded` and
+  `aria-controls`; the panel is `role="dialog"`, named by `Popover.Title` and
+  described by `Popover.Description` when you render them (WCAG 4.1.2).
+- Opening moves focus into the panel; `Escape` closes it and returns focus to
+  the trigger (WCAG 2.1.1, 2.4.3). A click outside also closes it.
+- It is not modal: focus is not trapped and the page does not lock.
+
+What you still have to do:
+
+- **Render `Popover.Title`** (it may be visually hidden). Without it the dialog
+  has no name.
+- **Name an icon-only trigger** with `aria-label`.
+- Use `Popover.Trigger asChild` on a real `Button`, so the trigger is a single
+  button and not a button inside a button.
+- Popover content is not portalled. Inside a container with `overflow: hidden`
+  it can be clipped; check it there.
+
+## Tokens
+
+The border is set in `PopoverContent` and `PopoverArrowTip`; the panel colour
+comes from Chakra's Popover recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- **제목:** 명사구로 쓰고 마침표를 찍지 않습니다. "링크 공유".
+- 스크롤 없이 읽을 수 있을 만큼만 담습니다. 스크롤바가 필요하다면 페이지나 모달로 옮길
+  때입니다.
+- 패널 안의 버튼도 다른 버튼처럼 동작 이름("링크 복사")을 씁니다.
+
+## 접근성
+
+Popover가 알아서 하는 일
+
+- 여는 버튼에 `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`를 붙입니다.
+  패널은 `role="dialog"`이며, `Popover.Title`과 `Popover.Description`을 렌더하면 각각
+  이름과 설명이 됩니다(WCAG 4.1.2).
+- 열리면 초점이 패널 안으로 옮겨 가고, `Escape`로 닫으면 여는 버튼으로 돌아옵니다
+  (WCAG 2.1.1, 2.4.3). 바깥을 눌러도 닫힙니다.
+- 모달이 아닙니다. 초점을 가두지 않고 페이지도 잠그지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **`Popover.Title`을 렌더합니다**(눈에 보이지 않게 숨겨도 됩니다). 제목이 없으면
+  대화상자에 이름이 없습니다.
+- **아이콘만 있는 여는 버튼에는** `aria-label`로 이름을 붙입니다.
+- `Popover.Trigger`에 `asChild`를 주고 실제 `Button`을 넣습니다. 그래야 버튼 안에 버튼이
+  들어가지 않습니다.
+- Popover 콘텐츠는 포털로 빠지지 않습니다. `overflow: hidden`인 컨테이너 안에서는
+  잘릴 수 있으니 그 자리에서 확인합니다.
+
+## 토큰
+
+테두리는 `PopoverContent`와 `PopoverArrowTip`에서, 패널 색은 Chakra Popover
+레시피에서 정합니다.
+
+</Ko>
+
+<Canvas of={PopoverStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Menu**: actions on one object.
+- **Tooltip**: a short label on hover or focus.
+- **InfoSprinkle**: a definition next to a label.
+- **Modal**: a task that stops the page.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Menu**: 한 대상에 대한 동작.
+- **Tooltip**: 마우스를 올리거나 초점이 갔을 때 보이는 짧은 라벨.
+- **InfoSprinkle**: 라벨 옆의 용어 설명.
+- **Modal**: 페이지를 멈추는 작업.
+
+</Ko>

package/src/components/ProgressBar/ProgressBar.stories.tsx

@@ -1,6 +1,9 @@
-import { Box, Text, VStack } from '@chakra-ui/react';
+import { Box, Flex, Text, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Subtext } from '../Typography';
 import { ProgressBar } from '.';
 
 const meta = {
@@ -57,3 +60,91 @@ export const AllSizes: Story = {
     </VStack>
   ),
 };
+
+export const Indeterminate: Story = {
+  args: { indeterminate: true, size: 'sm' },
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `ProgressBar.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written on each story because the indexer reads
+// CSF statically.
+
+export const DoLabelAndNumber: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: say what is measured, and the number',
+  render: () => (
+    <Box w="360px">
+      <Flex justify="space-between" mb={1}>
+        <Text fontSize="sm" fontWeight="semibold">
+          문서 업로드
+        </Text>
+        <Subtext>3 / 5</Subtext>
+      </Flex>
+      <ProgressBar size="sm" value={60} />
+    </Box>
+  ),
+};
+
+export const DontBareBar: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a bar with nothing next to it",
+  render: () => (
+    <Box w="360px">
+      <ProgressBar size="sm" value={60} />
+    </Box>
+  ),
+};
+
+export const DoDangerWhenOver: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: danger fill and words when over a limit',
+  render: () => (
+    <Box w="360px">
+      <Flex justify="space-between" mb={1}>
+        <Text fontSize="sm" fontWeight="semibold">
+          이번 달 크레딧
+        </Text>
+        <Subtext color="danger.fg">한도 초과 · 112%</Subtext>
+      </Flex>
+      <ProgressBar size="xs" value={100} filledTrackColor="danger.solid" />
+    </Box>
+  ),
+};
+
+export const DoIndeterminateWithHint: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: indeterminate only with no denominator, plus a hint',
+  render: () => (
+    <Box w="360px">
+      <ProgressBar size="sm" indeterminate />
+      <Subtext mt={2}>동기화하는 중입니다. 몇 분 걸릴 수 있습니다.</Subtext>
+    </Box>
+  ),
+};
+
+/** Tokens the bar reads, from `ProgressBar.tsx` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.track', use: <T en="track" ko="트랙" /> },
+        {
+          token: 'primary.main',
+          use: <T en="fill (default `filledTrackColor`)" ko="채움(기본 `filledTrackColor`)" />,
+        },
+        {
+          token: 'danger.solid',
+          use: <T en="fill when over a limit" ko="한도를 넘었을 때 채움" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/ProgressBar/ProgressBar.types.ts

@@ -3,7 +3,16 @@ import { ProgressRootProps as ChakraProgressRootProps } from '@chakra-ui/react';
 export type ProgressBarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
 export interface ProgressBarProps extends ChakraProgressRootProps {
+  /**
+   * Fill colour token. `danger.solid` only when the value means a problem
+   * (over a limit); otherwise leave the default.
+   * @default 'primary.main'
+   */
   filledTrackColor?: string;
+  /**
+   * Track height: `xs` 4px · `sm` 8px · `md` 16px · `lg` 24px · `xl` 32px.
+   * @default 'md'
+   */
   size?: ProgressBarSize;
   /**
    * Work whose length is not known yet: the bar slides across the track instead