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

package/src/components/Slider/Slider.stories.tsx

@@ -9,6 +9,11 @@ import {
   SliderThumbs,
   SliderTrack,
 } from '@/components/Slider';
+import { Flex } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Text } from '../Typography';
 
 const meta = {
   title: 'Components/Slider',
@@ -277,3 +282,114 @@ export const Sizes: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Slider.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoValueBeside: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a name and the value beside it',
+  render: () => {
+    const [value, setValue] = useState([70]);
+    return (
+      <Flex align="center" gap={4} maxW="420px">
+        <Text id="usage-volume" fontWeight="semibold" minW="48px">
+          음량
+        </Text>
+        <Slider
+          flex={1}
+          ariaLabel="음량"
+          value={value}
+          min={0}
+          max={100}
+          onValueChange={(d) => setValue(d.value)}
+        >
+          <SliderTrack>
+            <SliderFilledTrack />
+          </SliderTrack>
+          <SliderThumb />
+        </Slider>
+        <Text minW="40px" textAlign="end">
+          {value[0]}%
+        </Text>
+      </Flex>
+    );
+  },
+};
+
+export const DontExactNumber: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a slider for an exact number",
+  render: () => {
+    const [value, setValue] = useState([1250]);
+    return (
+      <Flex align="center" gap={4} maxW="420px">
+        <Text fontWeight="semibold">월 한도</Text>
+        <Slider
+          flex={1}
+          ariaLabel="월 한도"
+          value={value}
+          min={0}
+          max={100000}
+          onValueChange={(d) => setValue(d.value)}
+        >
+          <SliderTrack>
+            <SliderFilledTrack />
+          </SliderTrack>
+          <SliderThumb />
+        </Slider>
+      </Flex>
+    );
+  },
+};
+
+/** Tokens the slider parts read, as written in their `.tsx` files. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.track',
+          use: <T en="Empty rail (SliderTrack)" ko="빈 레일(SliderTrack)" />,
+        },
+        {
+          token: 'primary.main',
+          use: (
+            <T
+              en="Filled rail and thumb border"
+              ko="채운 레일과 손잡이 테두리"
+            />
+          ),
+        },
+        { token: 'bg.canvas', use: <T en="Thumb centre" ko="손잡이 가운데" /> },
+        {
+          token: 'bg.muted',
+          use: (
+            <T
+              en="Disabled thumb and filled rail"
+              ko="비활성 손잡이와 채운 레일"
+            />
+          ),
+        },
+        {
+          token: 'border.default',
+          use: <T en="Disabled thumb border" ko="비활성 손잡이 테두리" />,
+        },
+        {
+          token: 'focus.ring',
+          use: (
+            <T
+              en="Keyboard focus ring on the thumb"
+              ko="손잡이의 키보드 초점 링"
+            />
+          ),
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Slider/Slider.usage.mdx

@@ -0,0 +1,179 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SliderStories from './Slider.stories';
+
+<Meta of={SliderStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Slider
+
+A thumb the user drags along a rail to set a value, or two thumbs for a range,
+when the position matters more than the exact number.
+
+## When to use
+
+- Seeking in audio or video, setting a volume.
+- A value the user tunes by feel and sees the effect of right away, with the
+  number shown beside it.
+
+## When not to use
+
+- An exact number (a credit limit, a count) → `Input` with `type="number"`.
+- A choice between a few named levels → `Radio` or `SegmentedControl`.
+- Showing progress the user cannot change → `ProgressBar`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# Slider
+
+레일 위의 손잡이를 끌어 값을 정합니다. 손잡이 두 개로 범위도 정할 수 있습니다. 정확한
+숫자보다 위치가 중요할 때 씁니다.
+
+## 언제 쓰나요
+
+- 오디오나 영상의 재생 위치 이동, 음량 조절.
+- 감으로 맞추면서 결과를 바로 확인하는 값. 숫자는 옆에 함께 보여 줍니다.
+
+## 언제 쓰지 않나요
+
+- 크레딧 한도나 개수처럼 정확한 숫자는 `type="number"`인 `Input`을 씁니다.
+- 이름 붙은 몇 단계 중 하나를 고를 때는 `Radio`나 `SegmentedControl`을 씁니다.
+- 사용자가 바꿀 수 없는 진행 상황은 `ProgressBar`를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={SliderStories}
+  include={['value', 'defaultValue', 'onValueChange', 'ariaLabel']}
+/>
+
+<En>
+
+Values are arrays: `[50]` for one thumb, `[20, 80]` for a range. Compose
+`SliderTrack` > `SliderFilledTrack` and one `SliderThumb` per value (with
+`index`), or `SliderThumbs` to render one per value automatically. Children
+are wrapped in `SliderControl` for you. `min`, `max`, `step`, `disabled` and
+`onValueChangeEnd` come from Chakra's `Slider.Root`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+값은 배열입니다. 손잡이 하나는 `[50]`, 범위는 `[20, 80]`입니다. `SliderTrack` 안에
+`SliderFilledTrack`을 두고, 값마다 `SliderThumb`를 하나씩(`index`와 함께) 두거나
+`SliderThumbs`로 값 개수만큼 자동으로 그립니다. 자식은 `SliderControl`로 알아서
+감쌉니다. `min`, `max`, `step`, `disabled`, `onValueChangeEnd`는 Chakra
+`Slider.Root`의 속성입니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SliderStories.DoValueBeside} />
+<Verdict
+  kind="do"
+  en="Show the name and the current value beside the slider, and pass the name as ariaLabel."
+  ko="슬라이더 옆에 이름과 현재 값을 보여 주고, 이름은 ariaLabel로도 넘깁니다."
+/>
+
+<Canvas of={SliderStories.DontExactNumber} />
+<Verdict
+  kind="dont"
+  en="Ask for an exact number with a slider. One pixel covers dozens of values, and the user cannot see what they chose."
+  ko="정확한 숫자를 슬라이더로 받지 마세요. 1픽셀에 수십 개의 값이 걸리고, 무엇을 골랐는지도 보이지 않습니다."
+/>
+
+<En>
+
+## Content
+
+- Show the value with its unit (70%, 1:24) next to the rail, and update it
+  while dragging.
+- Label the ends when the meaning is not obvious (느리게 / 빠르게).
+
+## Accessibility
+
+What Slider does for you:
+
+- Each thumb is a `slider` with its value exposed. Arrow keys step, Page Up /
+  Page Down jump, Home / End go to the ends (Chakra / Zag) (WCAG 2.1.1).
+- The thumb shows the keyboard focus ring (WCAG 2.4.7). The empty rail is the
+  filled `bg.track`, which stays visible on sunken surfaces (WCAG 1.4.11).
+- With `ariaLabel` it renders a visually hidden label part, so the name is in
+  the server markup.
+
+What you still have to do:
+
+- **Pass `ariaLabel`, or compose a visible `Slider.Label`.** Without either
+  the thumb has no name: it points at a label part that does not exist
+  (`ACCESSIBILITY.md` §1; KWCAG 5.3.4.1 레이블 제공).
+- Dragging is not the only way: keyboard works, but give an `Input` as well
+  when people need an exact value (WCAG 2.5.7).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 레일 옆에 단위와 함께 값을 보여 주고(70%, 1:24), 끄는 동안 바로 바꿉니다.
+- 양 끝의 뜻이 분명하지 않다면 끝에 라벨을 붙입니다(느리게 / 빠르게).
+
+## 접근성
+
+Slider가 알아서 하는 일
+
+- 손잡이마다 값을 드러내는 `slider`입니다. 방향키로 한 단계씩, Page Up·Page Down으로
+  크게, Home·End로 끝까지 옮깁니다(Chakra와 Zag가 제공, WCAG 2.1.1).
+- 손잡이에 키보드 초점 링이 보입니다(WCAG 2.4.7). 빈 레일은 채워진 `bg.track`이라
+  움푹한 면 위에서도 보입니다(WCAG 1.4.11).
+- `ariaLabel`을 주면 시각적으로 숨긴 라벨 부품을 그리므로 이름이 서버 마크업 안에
+  있습니다.
+
+직접 챙겨야 하는 일
+
+- **`ariaLabel`을 넘기거나 보이는 `Slider.Label`을 조합합니다.** 둘 다 없으면 손잡이가
+  있지도 않은 라벨 부품을 가리켜서 이름이 없습니다(`ACCESSIBILITY.md` 1절, KWCAG
+  5.3.4.1 레이블 제공).
+- 끄는 것이 유일한 방법이 되지 않게 합니다. 키보드로도 움직일 수 있지만, 정확한 값이
+  필요한 사람을 위해 `Input`도 함께 둡니다(WCAG 2.5.7).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SliderStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Input**: exact numbers.
+- **ProgressBar**: progress the user cannot change.
+- **SegmentedControl**: a few named levels.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Input**: 정확한 숫자.
+- **ProgressBar**: 사용자가 바꿀 수 없는 진행 상황.
+- **SegmentedControl**: 이름 붙은 몇 단계.
+
+</Ko>

package/src/components/Spinner/Spinner.stories.tsx

@@ -1,5 +1,10 @@
+import { HStack } 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 { Subtext } from '../Typography';
 import { Spinner } from './Spinner';
 
 const meta = {
@@ -14,3 +19,62 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {},
 };
+
+export const Sizes: Story = {
+  render: () => (
+    <HStack gap={4}>
+      <Spinner size="xs" />
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+    </HStack>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Spinner.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`).
+
+export const DoSpinnerWithStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: spinner and words in a status',
+  render: () => (
+    <HStack gap={2} role="status">
+      <Spinner size="sm" />
+      <Subtext>파일을 불러오는 중</Subtext>
+    </HStack>
+  ),
+};
+
+export const DoButtonLoading: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a busy button uses its own loading state',
+  render: () => (
+    <Button variant="primary" loading loadingText="저장 중">
+      저장
+    </Button>
+  ),
+};
+
+/** Tokens the spinner reads, from `Spinner.tsx` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'primary.main',
+          use: <T en="turning arc (default colour)" ko="도는 호(기본 색)" />,
+        },
+        {
+          token: 'bg.track',
+          use: <T en="track ring" ko="트랙 고리" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Spinner/Spinner.usage.mdx

@@ -0,0 +1,136 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SpinnerStories from './Spinner.stories';
+
+<Meta of={SpinnerStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Spinner
+
+A small turning ring that says "still working" when the wait is short and its
+length is unknown.
+
+## When to use
+
+- Inline, next to the words that say what is loading: a list row, a menu, a
+  file being read.
+- Inside a custom control that has no loading state of its own.
+
+## When not to use
+
+- A busy button → the button's `loading` prop (Chakra draws the spinner and
+  disables the button).
+- A whole region or page → `SectionLoader` or `PageLoader`, which also
+  announce themselves.
+- The AI is working → `ThinkingDots` or the loaders' `thinking` variant.
+- Work with a known length → `ProgressBar`.
+
+## How it works
+
+- Chakra's `Spinner` with `color="primary.main"` and the `bg.track` ring.
+  `size` takes Chakra's `xs` to `xl`; `color` can be overridden with a token.
+- It turns at a constant rate. Under `prefers-reduced-motion` it keeps turning
+  at about a third of the speed, because a frozen spinner reads as a hung
+  request.
+
+## Do
+
+</En>
+
+<Ko>
+
+# Spinner
+
+대기가 짧고 얼마나 걸릴지 모를 때 "아직 처리 중"이라고 알려 주는 작은 회전 고리입니다.
+
+## 언제 쓰나요
+
+- 무엇을 불러오는지 알려 주는 글자 옆에 작게 둘 때: 목록 행, 메뉴, 읽는 중인 파일.
+- 로딩 상태를 따로 갖지 않은 직접 만든 컨트롤 안에 둘 때.
+
+## 언제 쓰지 않나요
+
+- 작업 중인 버튼은 그 버튼의 `loading` 속성을 씁니다(Chakra가 스피너를 그리고 버튼을
+  비활성으로 만듭니다).
+- 영역이나 페이지 전체는 `SectionLoader`나 `PageLoader`를 씁니다. 이 둘은 스스로 상태를
+  알립니다.
+- AI가 일하는 동안에는 `ThinkingDots`나 로더의 `thinking` 변형을 씁니다.
+- 길이를 아는 작업은 `ProgressBar`를 씁니다.
+
+## 동작 방식
+
+- `color="primary.main"`과 `bg.track` 고리를 쓴 Chakra `Spinner`입니다. `size`는
+  Chakra의 `xs`부터 `xl`까지 받으며, `color`는 토큰으로 바꿀 수 있습니다.
+- 일정한 속도로 돕니다. `prefers-reduced-motion`에서는 멈추지 않고 약 3분의 1 속도로
+  돕니다. 멈춘 스피너는 요청이 멈춘 것처럼 보이기 때문입니다.
+
+## 이렇게 하세요
+
+</Ko>
+
+<Canvas of={SpinnerStories.DoSpinnerWithStatus} />
+<Verdict
+  kind="do"
+  en='Put the spinner next to words that say what is loading, inside a role="status" element. The spinner itself is a plain span with no name.'
+  ko='스피너는 무엇을 불러오는지 알려 주는 글자 옆에 두고, 둘을 role="status" 요소로 감쌉니다. 스피너 자체는 이름 없는 span일 뿐입니다.'
+/>
+
+<Canvas of={SpinnerStories.DoButtonLoading} />
+<Verdict
+  kind="do"
+  en="For a busy button, use the button's loading state instead of placing a Spinner inside it."
+  ko="작업 중인 버튼에는 Spinner를 직접 넣지 말고 버튼의 loading 상태를 씁니다."
+/>
+
+<En>
+
+## Accessibility
+
+- **Spinner has no role and no accessible name.** On its own it says nothing
+  to a screen reader. Pair it with visible text and wrap both in
+  `role="status"` so the change is announced (WCAG 4.1.3, 1.1.1).
+- The `bg.track` ring is there so the spinner stays visible on any background
+  (WCAG 1.4.11).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- **Spinner에는 역할도 접근 가능한 이름도 없습니다.** 혼자서는 화면 낭독기에 아무것도
+  알리지 않습니다. 눈에 보이는 글자와 함께 두고 둘을 `role="status"`로 감싸서 변화가
+  읽히게 합니다(WCAG 4.1.3, 1.1.1).
+- `bg.track` 고리 덕분에 어떤 배경 위에서도 스피너가 보입니다(WCAG 1.4.11).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SpinnerStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Loaders**: `PageLoader`, `SectionLoader`, `ThinkingDots`.
+- **ProgressBar**: work whose length is known.
+- **Button**: `loading`.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Loaders**: `PageLoader`, `SectionLoader`, `ThinkingDots`.
+- **ProgressBar**: 길이를 아는 작업.
+- **Button**: `loading`.
+
+</Ko>

package/src/components/SwapTransition/SwapTransition.usage.mdx

@@ -0,0 +1,102 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as SwapTransitionStories from './SwapTransition.stories';
+
+<Meta of={SwapTransitionStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SwapTransition
+
+Swaps one piece of content for another with a short directional slide, for
+moving between steps of a sequence or between records in the same frame.
+
+</En>
+
+<Ko>
+
+# SwapTransition
+
+한 내용을 다른 내용으로 바꿀 때 짧게 옆으로 밀어 넘깁니다. 순서가 있는 단계 사이를
+오가거나, 같은 틀 안에서 다른 항목으로 넘어갈 때 씁니다.
+
+</Ko>
+
+<Canvas of={SwapTransitionStories.Default} />
+
+<En>
+
+## When to use
+
+- Question 1 → question 2 in a quiz or a multi-step flow, keyed on the step
+  index.
+- Moving from an overview screen to the step runner, or between items under
+  review, keyed on the record id.
+- Going back: pass a negative `distance` so the content travels the other way.
+
+## When not to use
+
+- New content is added under existing content rather than replacing it →
+  `Reveal`, or `Appear` if nothing is pushed.
+- A value changes in place → `CountUp` or `Pulse`.
+- The key would change on unrelated re-renders → pick a key that identifies the
+  content (a step index, a record id), or the content swaps with itself.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` both halves take no time and nothing
+  slides. The outgoing content is hidden at once, and the new content appears
+  when the 150ms exit timer ends.
+- While the old content leaves it gets `aria-hidden` and ignores the pointer,
+  so it cannot be read or clicked on its way out.
+- SwapTransition does not move focus. After a step change, move focus to the
+  new step (its heading, or its first field) yourself, so keyboard and
+  screen reader users start in the right place (WCAG 2.4.3).
+- It renders one `div`, and every prop lands on that element, so a wrapper
+  told to fill (`display="flex" flex={1} minH={0}`) still fills.
+
+## Props
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 퀴즈나 여러 단계로 된 흐름에서 1번 문항에서 2번 문항으로 넘어갈 때. 단계 번호를
+  key로 씁니다.
+- 개요 화면에서 단계 진행 화면으로, 또는 검토 중인 항목 사이를 오갈 때. 항목 id를
+  key로 씁니다.
+- 뒤로 갈 때는 `distance`에 음수를 넘겨 반대 방향으로 움직입니다.
+
+## 언제 쓰지 않나요
+
+- 새 내용이 기존 내용을 바꾸지 않고 그 아래에 더해진다면 `Reveal`을 씁니다. 아무것도
+  밀어내지 않는다면 `Appear`를 씁니다.
+- 값이 제자리에서 바뀐다면 `CountUp`이나 `Pulse`를 씁니다.
+- 상관없는 렌더에서도 key가 바뀐다면, 내용을 식별하는 값(단계 번호, 항목 id)으로 key를
+  바꿉니다. 그러지 않으면 같은 내용끼리 서로 바뀌는 애니메이션이 재생됩니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 나가고 들어오는 동작 모두 시간이 0이라
+  밀리는 움직임이 없습니다. 나가는 내용은 바로 사라지고, 새 내용은 150ms의 퇴장
+  타이머가 끝나면 나타납니다.
+- 나가는 동안 이전 내용에는 `aria-hidden`이 붙고 포인터도 받지 않으므로, 사라지는 중에
+  읽히거나 눌리지 않습니다.
+- SwapTransition은 초점을 옮기지 않습니다. 단계가 바뀌면 새 단계(제목이나 첫 입력란)로
+  직접 초점을 옮겨, 키보드와 화면 낭독기 사용자가 제자리에서 시작하게 합니다(WCAG 2.4.3).
+- `div` 하나만 그리고 모든 속성이 그 요소에 적용됩니다. 그래서 채우도록 지정한 감싸는
+  요소(`display="flex" flex={1} minH={0}`)도 그대로 채웁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={SwapTransitionStories}
+  include={['transitionKey', 'distance', 'animateInitial']}
+/>