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

package/src/components/CountUp/CountUp.usage.mdx

@@ -0,0 +1,107 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as CountUpStories from './CountUp.stories';
+
+<Meta of={CountUpStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# CountUp
+
+Counts a number up (or down) to `to`, for a balance that just grew, a total
+that just settled, or a KPI that just loaded.
+
+</En>
+
+<Ko>
+
+# CountUp
+
+숫자를 `to`까지 세어 올리거나 내립니다. 방금 늘어난 잔액, 방금 확정된 합계, 방금 불러온
+지표에 씁니다.
+
+</Ko>
+
+<Canvas of={CountUpStories.Default} />
+
+<En>
+
+## When to use
+
+- Credits added after a purchase, counting from the old balance to the new one.
+- The headline number on a stat card when the dashboard first loads
+  (`from={0}`).
+- A score on a result screen, with `delayMs` so it starts after the screen has
+  arrived.
+
+## When not to use
+
+- Numbers in tables, lists or running text that did not just change → plain
+  text. A count is a flourish on a number that is already known.
+- Values that update all the time (live usage, a timer) → plain text. Every
+  update would start a new count.
+- Only emphasis is needed, not the change itself → `Pulse`.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` the final value renders immediately,
+  and `onEnd` still fires.
+- The text changes on every frame while counting. Do not put CountUp inside an
+  `aria-live` region, or a screen reader may read intermediate values. If the
+  new value must be announced, announce the final number separately
+  (WCAG 4.1.3).
+- It renders a single `<span>` with tabular figures and wraps nothing, so it
+  is safe inside a heading, a button or running text.
+- The default `durationMs` is `motion.slower` (700ms). Longer counts make
+  people wait for a number the screen already knows.
+
+## Props
+
+`format` receives every intermediate value; the default rounds and groups
+digits with commas. Later changes to `to` count on from wherever the last count
+landed.
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 구매 뒤 추가된 크레딧을, 이전 잔액에서 새 잔액까지 세어 올릴 때.
+- 대시보드를 처음 열 때 통계 카드의 큰 숫자(`from={0}`).
+- 결과 화면의 점수. 화면이 다 들어온 뒤에 세도록 `delayMs`를 줍니다.
+
+## 언제 쓰지 않나요
+
+- 방금 바뀌지 않은 표, 목록, 본문 속 숫자는 그냥 글자로 씁니다. 세어 올리는 효과는 이미
+  알려진 숫자에 더하는 장식입니다.
+- 실시간 사용량이나 타이머처럼 계속 바뀌는 값도 그냥 글자로 씁니다. 바뀔 때마다 새로
+  세기 시작합니다.
+- 바뀌는 과정이 아니라 강조만 필요하다면 `Pulse`를 씁니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 최종 값이 바로 나타나고, `onEnd`도 그대로
+  호출됩니다.
+- 세는 동안 글자가 매 프레임 바뀝니다. CountUp을 `aria-live` 영역 안에 두지 마세요.
+  화면 낭독기가 중간 값을 읽을 수 있습니다. 새 값을 알려야 한다면 최종 숫자를 따로
+  알립니다(WCAG 4.1.3).
+- 고정 폭 숫자로 된 `<span>` 하나만 그리고 아무것도 감싸지 않으므로, 제목, 버튼, 본문
+  안에 넣어도 됩니다.
+- `durationMs` 기본값은 `motion.slower`(700ms)입니다. 이보다 길면 화면이 이미 아는
+  숫자를 사용자가 기다리게 됩니다.
+
+## 속성
+
+`format`은 중간 값마다 호출되며, 기본값은 반올림한 뒤 쉼표로 자릿수를 묶습니다. 나중에
+`to`가 바뀌면 마지막으로 멈춘 값에서 이어서 셉니다.
+
+</Ko>
+
+<ArgTypes
+  of={CountUpStories}
+  include={['to', 'from', 'durationMs', 'delayMs', 'format', 'onEnd']}
+/>

package/src/components/DatePicker/DatePicker.usage.mdx

@@ -0,0 +1,177 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as RangeStories from './RangeDatePicker.stories';
+
+<Meta title="Components/DatePicker/Usage" />
+
+<LangToggle />
+
+<En>
+
+# SingleDatePicker, RangeDatePicker
+
+A button that opens a calendar for picking one date, or a start and end date.
+
+## When to use
+
+- `RangeDatePicker`: a period to filter by: audit logs, API key usage, group
+  usage.
+- `SingleDatePicker`: one day, such as an expiry date or a scheduled send.
+
+## When not to use
+
+- A whole month or a range of months → `MonthPicker`.
+- A date the user knows by heart and types faster than they click, such as a
+  date of birth → `Input` with a clear format.
+- A handful of preset periods (last 7 days, last 30 days) → `SegmentedControl`
+  or `SelectField`, optionally next to a range picker for "custom".
+
+## Props
+
+Both wrap `chakra-dayzed-datepicker`; its props pass through.
+`SingleDatePicker` takes `date` and `onDateChange(date)`; `RangeDatePicker`
+takes `selectedDates` and `onDateChange(dates)`. Month and weekday names and
+the default `configs.dateFormat` follow the provider language. The trigger is
+a secondary `Button` with a calendar icon; style it with
+`propsConfigs.triggerBtnProps`. The calendar is portalled (`usePortal`
+defaults to `true`).
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# SingleDatePicker, RangeDatePicker
+
+버튼을 누르면 달력이 열리고, 날짜 하나나 시작일과 종료일을 고릅니다.
+
+## 언제 쓰나요
+
+- `RangeDatePicker`: 감사 로그, API 키 사용량, 그룹 사용량처럼 기간으로 거를 때.
+- `SingleDatePicker`: 만료일이나 예약 발송일처럼 하루를 고를 때.
+
+## 언제 쓰지 않나요
+
+- 한 달이나 여러 달의 범위는 `MonthPicker`를 씁니다.
+- 생년월일처럼 외우고 있어서 누르는 것보다 입력이 빠른 날짜는 형식을 분명히 적은
+  `Input`을 씁니다.
+- 최근 7일, 최근 30일 같은 정해진 기간 몇 개는 `SegmentedControl`이나
+  `SelectField`를 쓰고, 필요하면 "직접 지정"용으로 기간 선택기를 옆에 둡니다.
+
+## 속성
+
+둘 다 `chakra-dayzed-datepicker`를 감싸며, 그 속성이 그대로 전달됩니다.
+`SingleDatePicker`는 `date`와 `onDateChange(date)`를, `RangeDatePicker`는
+`selectedDates`와 `onDateChange(dates)`를 받습니다. 월과 요일 이름, 기본
+`configs.dateFormat`은 프로바이더의 언어를 따릅니다. 트리거는 달력 아이콘이 있는
+secondary `Button`이고, 모양은 `propsConfigs.triggerBtnProps`로 바꿉니다. 달력은
+포털로 그려집니다(`usePortal` 기본값 `true`).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={RangeStories.DoLabelledRange} />
+<Verdict
+  kind="do"
+  en="Label the filter and start from a sensible default range, so the page shows data before anyone touches the picker."
+  ko="필터에 라벨을 붙이고 알맞은 기본 기간으로 시작합니다. 그래야 선택기를 건드리기 전에도 화면에 데이터가 보입니다."
+/>
+
+<Canvas of={RangeStories.DontEmptyTrigger} />
+<Verdict
+  kind="dont"
+  en="Leave the trigger empty with no label. It shows only an icon, and a screen reader hears a button with no name."
+  ko="라벨 없이 빈 트리거를 두지 마세요. 아이콘만 보이고, 화면 낭독기에는 이름 없는 버튼으로 들립니다."
+/>
+
+<En>
+
+## Content
+
+- Label the period (조회 기간, 만료일), not the action (날짜 선택).
+- Leave the date format to the default for the language unless the screen
+  already uses another one.
+
+## Accessibility
+
+What the pickers do for you:
+
+- The trigger is a real `button`, reachable with Tab, and the selected date
+  is its text.
+- The calendar's day buttons and their keyboard behaviour come from
+  `chakra-dayzed-datepicker`. Check them with a keyboard on your screen before
+  relying on them (WCAG 2.1.1).
+
+What you still have to do:
+
+- **Name the trigger.** Its accessible name is the date text only, and it is
+  empty when nothing is picked. Put it in `FieldRow` with a label, and give
+  the button an `aria-label` through `propsConfigs.triggerBtnProps` when it
+  can be empty (WCAG 4.1.2; KWCAG 5.3.4.1 레이블 제공).
+- Keep an `Input` route for dates far from today; paging month by month to a
+  date years away is slow for everyone.
+
+## Tokens
+
+The trigger reads the secondary `Button` tokens. The calendar reads:
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 동작(날짜 선택)이 아니라 기간의 이름(조회 기간, 만료일)을 라벨로 씁니다.
+- 화면이 이미 다른 형식을 쓰고 있지 않다면 날짜 형식은 언어별 기본값을 그대로 씁니다.
+
+## 접근성
+
+선택기가 알아서 하는 일
+
+- 트리거는 실제 `button`이라 Tab으로 갈 수 있고, 고른 날짜가 버튼의 글자가 됩니다.
+- 달력의 날짜 버튼과 키보드 동작은 `chakra-dayzed-datepicker`가 제공합니다. 화면에
+  쓰기 전에 키보드로 직접 확인합니다(WCAG 2.1.1).
+
+직접 챙겨야 하는 일
+
+- **트리거에 이름을 붙입니다.** 접근 가능한 이름은 날짜 글자뿐이라 아무것도 고르지
+  않으면 비어 있습니다. 라벨이 있는 `FieldRow`에 넣고, 비어 있을 수 있다면
+  `propsConfigs.triggerBtnProps`로 버튼에 `aria-label`을 줍니다(WCAG 4.1.2, KWCAG
+  5.3.4.1 레이블 제공).
+- 오늘과 멀리 떨어진 날짜는 `Input`으로도 넣을 수 있게 합니다. 몇 년 떨어진 날짜까지 한
+  달씩 넘기는 것은 누구에게나 느립니다.
+
+## 토큰
+
+트리거는 secondary `Button`의 토큰을 씁니다. 달력은 아래 토큰을 씁니다.
+
+</Ko>
+
+<Canvas of={RangeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **MonthPicker**: months and month ranges.
+- **SegmentedControl** / **SelectField**: preset periods.
+- **FieldRow**: the label.
+- Live examples: <code>Components/DatePicker/SingleDatePicker</code> and
+  <code>RangeDatePicker</code>.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **MonthPicker**: 월과 월 범위.
+- **SegmentedControl** / **SelectField**: 정해진 기간.
+- **FieldRow**: 라벨.
+- 실제 예시: <code>Components/DatePicker/SingleDatePicker</code>와
+  <code>RangeDatePicker</code>.
+
+</Ko>

package/src/components/DatePicker/RangeDatePicker.stories.tsx

@@ -5,6 +5,9 @@ import { useState } from 'react';
 import { formatDateByLocale } from '@/utils/formatDateByLocale';
 
 import { Text } from '../Typography';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
 import { RangeDatePicker } from './RangeDatePicker';
 
 const meta = {
@@ -15,7 +18,7 @@ const meta = {
       new Date(),
       new Date(),
     ]);
-  
+
     return (
       <>
         <Box mb={2}>
@@ -31,11 +34,92 @@ const meta = {
         </Text>
       </>
     );
-  }
+  },
 } satisfies Meta<typeof RangeDatePicker>;
 
 export default meta;
 
 type Story = StoryObj<typeof RangeDatePicker>;
 
-export const Basic: Story = {}
+export const Basic: Story = {};
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `DatePicker.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoLabelledRange: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a labelled filter with a default range',
+  render: () => {
+    const [dates, setDates] = useState<Date[]>([
+      new Date(2026, 9, 1),
+      new Date(2026, 9, 22),
+    ]);
+    return (
+      <Box maxW="360px">
+        <FieldRow label="조회 기간">
+          <RangeDatePicker selectedDates={dates} onDateChange={setDates} />
+        </FieldRow>
+      </Box>
+    );
+  },
+};
+
+export const DontEmptyTrigger: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: an empty trigger with no label",
+  render: () => {
+    const [dates, setDates] = useState<Date[]>([]);
+    return <RangeDatePicker selectedDates={dates} onDateChange={setDates} />;
+  },
+};
+
+/** Tokens the calendar reads, as written in `RangeDatePicker.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'primary.main',
+          use: (
+            <T
+              en="Selected day; month arrows"
+              ko="선택한 날짜, 월 이동 화살표"
+            />
+          ),
+        },
+        {
+          token: 'fg.onPrimary',
+          use: <T en="Selected day number" ko="선택한 날짜 숫자" />,
+        },
+        {
+          token: 'primary.selected',
+          use: <T en="Days inside the range" ko="기간 안의 날짜" />,
+        },
+        {
+          token: 'primary.wash',
+          use: <T en="Day on hover" ko="마우스를 올린 날짜" />,
+        },
+        {
+          token: 'border.strong',
+          use: <T en="Today outline" ko="오늘 표시 테두리" />,
+        },
+        { token: 'fg.muted', use: <T en="Weekday names" ko="요일 이름" /> },
+        {
+          token: 'fg.subtle',
+          use: (
+            <T en="Calendar icon in the trigger" ko="트리거의 달력 아이콘" />
+          ),
+        },
+        { token: 'bg.surface', use: <T en="Calendar panel" ko="달력 패널" /> },
+        {
+          token: 'border.default',
+          use: <T en="Calendar panel border" ko="달력 패널 테두리" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/ErrorFallback/ErrorFallback.types.ts

@@ -1,9 +1,15 @@
 export interface ErrorFallbackProps {
+  /** The caught error. Its `message` is shown as is; a translated default when empty. */
   error: Error | null;
+  /** ID shown for support; generated (`ERR-…`) when missing. */
   errorId?: string;
+  /** ISO time for the copied report only; the card shows the render time. */
   timestamp?: string;
+  /** Where it failed, shown and copied; "unknown" (translated) when missing. */
   componentName?: string;
+  /** Shown and copied; "anonymous" (translated) when missing. */
   userId?: string;
+  /** Called by the "try again" button, e.g. the error boundary's reset. */
   onErrorReset?: () => void;
 }
 

package/src/components/ErrorFallback/ErrorFallback.usage.mdx

@@ -0,0 +1,127 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ErrorFallbackStories from './ErrorFallback.stories';
+
+<Meta of={ErrorFallbackStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# ErrorFallback
+
+The full-height card an error boundary renders when a page or a large section
+fails to render: what happened, details for support, and a way to try again.
+
+## When to use
+
+- As the `fallback` of a React error boundary or a route-level error page
+  (FactChat uses it in its `ErrorBoundary` and route error screens).
+
+## When not to use
+
+- A request failed but the page still works → `Banner` (`danger`) in place, or
+  a `Toast`.
+- One block inside a page, such as a code block or a table in a chat message,
+  failed → a small inline fallback. ErrorFallback is at least one screen tall
+  (`100svh`).
+
+## Props
+
+</En>
+
+<Ko>
+
+# ErrorFallback
+
+페이지나 큰 영역을 그리지 못했을 때 에러 바운더리가 대신 그리는 전체 높이의
+카드입니다. 무슨 일이 있었는지, 지원팀에 전할 정보, 다시 시도하는 방법을 보여 줍니다.
+
+## 언제 쓰나요
+
+- React 에러 바운더리의 `fallback`이나 라우트 단위 오류 화면으로 씁니다(FactChat은
+  `ErrorBoundary`와 라우트 오류 화면에서 씁니다).
+
+## 언제 쓰지 않나요
+
+- 요청은 실패했지만 페이지는 쓸 수 있다면, 그 자리에 `Banner`(`danger`)를 두거나
+  `Toast`를 씁니다.
+- 채팅 메시지 안의 코드 블록이나 표처럼 페이지 안의 한 덩어리만 실패했다면 작은 인라인
+  대체 화면을 씁니다. ErrorFallback은 높이가 화면 하나(`100svh`) 이상입니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={ErrorFallbackStories} />
+
+<En>
+
+What it shows and does:
+
+- Title, subtitle, help text and button labels come from the library's
+  translations, in the app's language.
+- `error.message` is shown to the reader as is, in a `danger.bg` box. Throw
+  errors whose message a person can read, or pass an `Error` with a
+  user-facing message.
+- The support block lists the error ID (generated when `errorId` is missing),
+  the time, `componentName`, `userId` and the page path.
+- **Copy error details** copies a report with the ID, `timestamp`, component,
+  message, full URL, user ID and user agent, then confirms with a toast. The
+  app must mount `<Toaster />` for that toast to appear.
+- **Try again** calls `onErrorReset`; **Refresh page** reloads the window.
+- The time on screen is when the card rendered; the `timestamp` prop goes only
+  into the copied report.
+
+<Canvas of={ErrorFallbackStories.Default} />
+
+## Accessibility
+
+- The card is a `<section>` named by its title, so it is a landmark even when
+  the page's `<main>` failed with it (WCAG 1.3.1).
+- The title is an `<h1>` and the support block an `<h2>`, so the outline does
+  not skip levels (`ACCESSIBILITY.md` §2, KWCAG 5.2.4.2).
+- Move focus to the card's heading when it replaces content the reader was
+  using, so a screen reader user learns that the page changed (WCAG 2.4.3).
+
+## Related
+
+- **Banner**: a failure the page survives.
+- **Toast**: a failed background action.
+
+</En>
+
+<Ko>
+
+보여 주는 것과 하는 일
+
+- 제목, 부제, 도움말, 버튼 라벨은 라이브러리 번역에서 앱의 언어로 가져옵니다.
+- `error.message`는 `danger.bg` 상자 안에 그대로 보입니다. 사람이 읽을 수 있는
+  메시지로 오류를 던지거나, 사용자에게 보여 줄 메시지를 담은 `Error`를 넘깁니다.
+- 지원 정보에는 오류 ID(`errorId`가 없으면 새로 만듦), 시간, `componentName`,
+  `userId`, 페이지 경로가 나옵니다.
+- **오류 정보 복사**는 ID, `timestamp`, 컴포넌트, 메시지, 전체 URL, 사용자 ID,
+  사용자 에이전트를 담은 보고서를 복사하고 토스트로 알립니다. 그 토스트가 보이려면 앱에
+  `<Toaster />`가 있어야 합니다.
+- **다시 시도**는 `onErrorReset`을 부르고, **페이지 새로고침**은 창을 다시 엽니다.
+- 화면의 시간은 카드를 그린 시각입니다. `timestamp` 속성은 복사되는 보고서에만
+  들어갑니다.
+
+<Canvas of={ErrorFallbackStories.Default} />
+
+## 접근성
+
+- 카드는 제목으로 이름을 붙인 `<section>`이라서, 페이지의 `<main>`이 함께 사라져도
+  랜드마크가 남습니다(WCAG 1.3.1).
+- 제목은 `<h1>`, 지원 정보는 `<h2>`라서 제목 수준을 건너뛰지 않습니다
+  (`ACCESSIBILITY.md` §2, KWCAG 5.2.4.2).
+- 사용자가 쓰던 내용을 이 카드가 대신한다면 카드 제목으로 초점을 옮깁니다. 그래야 화면
+  낭독기 사용자가 페이지가 바뀐 것을 압니다(WCAG 2.4.3).
+
+## 관련 컴포넌트
+
+- **Banner**: 페이지는 살아 있는 실패.
+- **Toast**: 백그라운드 작업의 실패.
+
+</Ko>

package/src/components/ExpandableText/ExpandableText.stories.tsx

@@ -1,5 +1,8 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { LINK_RAMP, Text } from '../Typography';
 import { ExpandableText } from './ExpandableText';
 
 const meta = {
@@ -163,3 +166,55 @@ export const ComponentComparison: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `ExpandableText.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`); `tags` is written out on each story because the
+// indexer reads CSF statically.
+
+const DESCRIPTION =
+  '회의 내용을 바탕으로 요약, 결정 사항, 할 일을 정리해 주는 챗봇입니다. 녹음 파일이나 회의록을 올리면 참석자별 발언을 나눠 보여 주고, 다음 회의 전에 확인할 항목을 골라 줍니다. 팀 공용 챗봇으로 공유해 같은 형식의 회의록을 쓸 수 있습니다.';
+
+export const DoSecondaryDescription: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a long secondary description in a card',
+  render: () => (
+    <Card p={5} maxW="360px">
+      <Text fontWeight="bold" mb={1}>
+        회의록 도우미
+      </Text>
+      <ExpandableText lineClamp={2} component="Subtext">
+        {DESCRIPTION}
+      </ExpandableText>
+    </Card>
+  ),
+};
+
+export const DontClipTheMessage: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: clip what the reader must not miss",
+  render: () => (
+    <Card p={5} maxW="360px">
+      <ExpandableText lineClamp={1}>
+        이 작업은 되돌릴 수 없습니다. 그룹을 삭제하면 그룹에 속한 멤버 42명의
+        크레딧 한도와 챗봇 공유 설정이 함께 지워집니다.
+      </ExpandableText>
+    </Card>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: LINK_RAMP.default, use: '더보기 / 접기 (Link)' },
+        { token: 'fg.default', use: '더보기 / 접기 · hover' },
+      ]}
+    />
+  ),
+};