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

package/src/components/Pagination/Pagination.usage.mdx

@@ -0,0 +1,186 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as PaginationStories from './Pagination.stories';
+
+<Meta of={PaginationStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Pagination
+
+Previous and next buttons with a "current / last" page counter, and an
+optional page-size select, for a list or table that is longer than one page.
+
+## When to use
+
+- Under a table or list that the server returns one page at a time: members,
+  audit logs, API call history, inquiries.
+- When the user needs to come back to a known position, such as page 3 of the
+  audit log.
+
+## When not to use
+
+- The list fits on one page → show it all, without a pagination row.
+- A feed the user scrolls through without looking for a position → load more
+  as they scroll.
+- To move between steps or sections → a stepper or `Tabs`.
+
+## Variants and what they mean
+
+Pagination has no visual variants. The props decide what it shows:
+
+</En>
+
+<Ko>
+
+# Pagination
+
+한 페이지보다 긴 목록이나 표에 쓰는 이전·다음 버튼과 "현재 / 마지막" 쪽 번호입니다.
+페이지당 항목 수를 고르는 선택 상자를 함께 둘 수 있습니다.
+
+## 언제 쓰나요
+
+- 서버가 한 페이지씩 돌려주는 표나 목록 아래: 멤버, 감사 로그, API 호출 기록, 문의.
+- 사용자가 감사 로그 3쪽처럼 알고 있는 위치로 돌아와야 할 때.
+
+## 언제 쓰지 않나요
+
+- 한 페이지에 다 들어가는 목록은 페이지 줄 없이 모두 보입니다.
+- 위치를 찾지 않고 계속 내려 보는 피드는 스크롤하면 더 불러옵니다.
+- 단계나 구역 사이를 오가는 것은 단계 표시나 `Tabs`가 맡습니다.
+
+## 변형과 뜻
+
+Pagination에는 모양 변형이 없습니다. 무엇을 보일지는 속성이 정합니다.
+
+</Ko>
+
+<ArgTypes of={PaginationStories} include={['numTotalItems', 'itemsPerPage', 'itemsPerPageOptions', 'currentPage']} />
+
+<En>
+
+| Prop | Effect |
+| --- | --- |
+| `numTotalItems` + `itemsPerPage` | The last page is `Math.ceil(numTotalItems / itemsPerPage)`. With one page the buttons are hidden and only "1 / 1" remains. |
+| `itemsPerPageOptions` | Adds the page-size select on the left. `itemsPerPage` is always yours to update, from `onItemsPerPageOptionChange`. |
+| `currentPage` | Controlled. Update it from `onBack` / `onNext`, and from `onCurrentPageChange`, which fires when a larger page size puts the current page past the end. Leave it out and the component keeps the page itself. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 효과 |
+| --- | --- |
+| `numTotalItems` + `itemsPerPage` | 마지막 쪽은 `Math.ceil(numTotalItems / itemsPerPage)`입니다. 한 쪽뿐이면 버튼이 사라지고 "1 / 1"만 남습니다. |
+| `itemsPerPageOptions` | 왼쪽에 페이지당 항목 수 선택 상자를 더합니다. `itemsPerPage`는 언제나 호출부가 `onItemsPerPageOptionChange`에서 바꿔 줍니다. |
+| `currentPage` | 제어 모드입니다. `onBack`/`onNext`에서, 그리고 페이지 크기를 키워 현재 쪽이 범위를 벗어날 때 불리는 `onCurrentPageChange`에서 값을 바꿉니다. 넘기지 않으면 컴포넌트가 직접 쪽을 기억합니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={PaginationStories.DoUnderTheList} />
+<Verdict
+  kind="do"
+  en="Put it directly under the list it pages, full width, and keep the page when the data refetches so the row does not jump."
+  ko="넘기는 목록 바로 아래에 전체 너비로 둡니다. 데이터를 다시 불러오는 동안에도 쪽 번호를 유지해 줄이 들썩이지 않게 합니다."
+/>
+
+<Canvas of={PaginationStories.DontOnePage} />
+<Verdict
+  kind="dont"
+  en="Show a pagination row for a list that fits on one page. '1 / 1' tells the user nothing."
+  ko="한 페이지에 다 들어가는 목록에 페이지 줄을 두지 마세요. '1 / 1'은 아무것도 알려 주지 않습니다."
+/>
+
+<En>
+
+## Content
+
+- The counter and the button names come from the library's translations
+  (이전 / 다음, 항목 수). Do not add your own labels beside them.
+- If the total matters, say it above the list ("멤버 124명"), not in the
+  pagination row.
+
+## Accessibility
+
+What Pagination does for you:
+
+- The previous and next buttons are `IconButton`s with translated names (이전,
+  다음), and are disabled on the first and last page (WCAG 4.1.2).
+- The page-size select carries the same words as the visible text beside it
+  as its accessible name (WCAG 2.5.3; KWCAG 5.3.4.1).
+- The counter is a paragraph, not a heading, so it stays out of the page
+  outline.
+
+What you still have to do:
+
+- **Look after focus on page change.** The counter is not a live region, and
+  on the first or last page the button the user just pressed becomes disabled
+  and drops focus. Move focus to the other button or to the top of the list
+  when that happens (WCAG 2.4.3).
+- Keep `currentPage` at the page you requested while the data loads, so the
+  next button cannot request a page past the end.
+
+## Tokens
+
+The table lists the tokens set in `Pagination.tsx`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 쪽 번호와 버튼 이름은 라이브러리 번역(이전 / 다음, 항목 수)에서 옵니다. 옆에 따로 라벨을
+  붙이지 않습니다.
+- 전체 개수가 중요하다면 페이지 줄이 아니라 목록 위에 씁니다("멤버 124명").
+
+## 접근성
+
+Pagination이 알아서 하는 일
+
+- 이전·다음 버튼은 번역된 이름(이전, 다음)이 붙은 `IconButton`이며, 첫 쪽과 마지막
+  쪽에서는 비활성이 됩니다(WCAG 4.1.2).
+- 페이지당 항목 수 선택 상자는 옆에 보이는 문구와 같은 말을 접근 가능한 이름으로
+  갖습니다(WCAG 2.5.3, KWCAG 5.3.4.1).
+- 쪽 번호는 제목이 아니라 문단이라 문서 개요에 끼어들지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **쪽을 넘길 때 초점을 챙깁니다.** 쪽 번호는 라이브 영역이 아니고, 첫 쪽이나 마지막 쪽에
+  닿으면 방금 누른 버튼이 비활성이 되면서 초점을 잃습니다. 그럴 때는 반대쪽 버튼이나 목록
+  맨 위로 초점을 옮깁니다(WCAG 2.4.3).
+- 데이터를 불러오는 동안 `currentPage`를 요청한 쪽으로 유지합니다. 그래야 다음 버튼이
+  범위 밖의 쪽을 요청하지 않습니다.
+
+## 토큰
+
+아래 표는 `Pagination.tsx`에서 정한 토큰입니다.
+
+</Ko>
+
+<Canvas of={PaginationStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Table**: the usual thing Pagination sits under.
+- **Select**: the page-size control inside it.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Table**: Pagination이 보통 그 아래에 놓이는 표.
+- **Select**: 안에 들어 있는 페이지 크기 선택 상자.
+
+</Ko>

package/src/components/PasswordInput/PasswordInput.stories.tsx

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Stack, Text } from '@chakra-ui/react';
 
+import { FieldRow } from '../Form';
 import { PasswordInput } from './PasswordInput';
 
 const meta = {
@@ -54,3 +55,53 @@ export const Disabled: Story = {
     defaultValue: 'password123',
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `PasswordInput.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoSignInPassword: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: labelled, with autocomplete',
+  render: () => (
+    <Stack maxW="360px">
+      <FieldRow label="비밀번호" required>
+        <PasswordInput autoComplete="current-password" />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DoRulesBeforeTyping: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: state the rule before the user types',
+  render: () => (
+    <Stack maxW="360px">
+      <FieldRow
+        label="새 비밀번호"
+        helperText="영문, 숫자, 특수문자를 섞어 8자 이상 입력합니다."
+        required
+      >
+        <PasswordInput autoComplete="new-password" />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DontRuleOnlyInError: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: reveal the rule only as an error",
+  render: () => (
+    <Stack maxW="360px">
+      <FieldRow
+        label="새 비밀번호"
+        error="비밀번호가 올바르지 않습니다."
+        required
+      >
+        <PasswordInput autoComplete="new-password" defaultValue="abcd" />
+      </FieldRow>
+    </Stack>
+  ),
+};

package/src/components/PasswordInput/PasswordInput.usage.mdx

@@ -0,0 +1,193 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as PasswordInputStories from './PasswordInput.stories';
+
+<Meta of={PasswordInputStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# PasswordInput
+
+An `Input` for passwords and other secrets, with an eye button that shows or
+hides what was typed.
+
+## When to use
+
+- Sign-in, sign-up and password reset.
+- A secret the user pastes once, such as an OAuth client secret or an API key.
+
+## When not to use
+
+- A one-time code sent by email or SMS → `PinInput`.
+- A secret the user only needs to copy, not type → `CopyableCode`.
+- Any value that is not secret → `Input`. Hiding it only makes it harder to
+  check.
+
+## Props
+
+</En>
+
+<Ko>
+
+# PasswordInput
+
+비밀번호 같은 비밀 값을 받는 `Input`입니다. 눈 모양 버튼으로 입력한 내용을 보이거나
+가립니다.
+
+## 언제 쓰나요
+
+- 로그인, 회원가입, 비밀번호 재설정.
+- OAuth 클라이언트 시크릿이나 API 키처럼 한 번 붙여 넣는 비밀 값.
+
+## 언제 쓰지 않나요
+
+- 메일이나 문자로 받은 일회용 코드는 `PinInput`을 씁니다.
+- 입력하지 않고 복사만 하면 되는 비밀 값은 `CopyableCode`를 씁니다.
+- 비밀이 아닌 값은 `Input`을 씁니다. 가리면 확인하기만 어려워집니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={PasswordInputStories}
+  include={[
+    'defaultVisible',
+    'visible',
+    'onVisibleChange',
+    'visibilityIcon',
+    'rootProps',
+  ]}
+/>
+
+<En>
+
+Every other prop goes to the inner `Input`, so `noSpaces`, `invalid`,
+`autoComplete` and `name` work the same way. `type` is not accepted; the
+component sets it from `visible`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+나머지 속성은 모두 안쪽 `Input`에 그대로 전달되므로 `noSpaces`, `invalid`,
+`autoComplete`, `name`이 `Input`과 똑같이 동작합니다. `type`은 받지 않으며 `visible`에
+따라 컴포넌트가 정합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={PasswordInputStories.DoSignInPassword} />
+<Verdict
+  kind="do"
+  en="Label it and set autoComplete: current-password to sign in, new-password to create one, so password managers fill the right field (WCAG 1.3.5)."
+  ko="라벨을 붙이고 autoComplete를 지정합니다. 로그인에는 current-password, 새로 만들 때는 new-password를 써야 비밀번호 관리자가 알맞은 칸을 채웁니다(WCAG 1.3.5)."
+/>
+
+<Canvas of={PasswordInputStories.DoRulesBeforeTyping} />
+<Verdict
+  kind="do"
+  en="State the password rule in helper text before the user types."
+  ko="비밀번호 규칙은 입력하기 전에 도움말로 알려 줍니다."
+/>
+
+<Canvas of={PasswordInputStories.DontRuleOnlyInError} />
+<Verdict
+  kind="dont"
+  en="Reveal the rule only after a failed attempt, in an error that does not say what is wrong."
+  ko="실패한 뒤에야 규칙을 알려 주거나, 무엇이 틀렸는지 말하지 않는 오류 문구를 쓰지 마세요."
+/>
+
+<En>
+
+## Content
+
+- Label: "Password", "New password", "Client secret". Korean: 비밀번호, 새
+  비밀번호.
+- Do not repeat the rule in the placeholder; it disappears on the first
+  keystroke.
+- Error text names the rule that failed: 8자 이상 입력해 주세요, not
+  비밀번호가 올바르지 않습니다.
+
+## Accessibility
+
+What PasswordInput does for you:
+
+- The field itself is the `Input`: native `<input>`, labelled and wired by
+  `FieldRow` / `FormControl`.
+- The eye button has an accessible name ("Toggle password visibility") and
+  does nothing while the field is `disabled`.
+
+What you still have to do, and known gaps:
+
+- **The eye button is mouse and touch only.** It has `tabIndex={-1}` and acts
+  on pointer down, so a keyboard user cannot reveal the password (WCAG
+  2.1.1). Until the component is fixed, do not make showing the password the
+  only way to check it; a confirm field or a clear error works for everyone.
+- **Its name is English and its state is not announced.** The label is fixed
+  and there is no `aria-pressed`, so a screen reader does not say whether the
+  password is shown (WCAG 4.1.2).
+- Label the field (WCAG 4.1.2; KWCAG 5.3.4.1 레이블 제공) and put errors in
+  `FieldRow` `error` (WCAG 3.3.1).
+
+## Tokens
+
+PasswordInput has no colours of its own. The field reads the `Input` tokens;
+the eye button is a ghost `IconButton`.
+
+## Related
+
+- **Input**: the field it wraps, and its tokens.
+- **PinInput**: one-time codes.
+- **FieldRow**: label, rule and error.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨: 비밀번호, 새 비밀번호, 클라이언트 시크릿.
+- 규칙을 플레이스홀더에 되풀이하지 않습니다. 첫 글자를 입력하면 사라집니다.
+- 오류 문구는 어긋난 규칙을 말합니다. "비밀번호가 올바르지 않습니다"가 아니라 "8자
+  이상 입력해 주세요"라고 씁니다.
+
+## 접근성
+
+PasswordInput이 알아서 하는 일
+
+- 입력란은 `Input` 그대로입니다. 네이티브 `<input>`이고, `FieldRow`나 `FormControl`
+  안에서 라벨과 연결됩니다.
+- 눈 모양 버튼에는 접근 가능한 이름("Toggle password visibility")이 있고, 입력란이
+  `disabled`이면 동작하지 않습니다.
+
+직접 챙겨야 하는 일과 알려진 한계
+
+- **눈 모양 버튼은 마우스와 터치로만 동작합니다.** `tabIndex={-1}`이고 포인터를 누를
+  때만 반응하므로 키보드 사용자는 비밀번호를 볼 수 없습니다(WCAG 2.1.1). 컴포넌트가
+  고쳐지기 전까지는 비밀번호 보기를 유일한 확인 방법으로 두지 마세요. 확인 입력란이나
+  분명한 오류 문구는 누구에게나 통합니다.
+- **버튼 이름이 영어이고 상태를 알리지 않습니다.** 라벨이 고정되어 있고
+  `aria-pressed`가 없어서, 화면 낭독기는 지금 비밀번호가 보이는지 알려 주지 않습니다
+  (WCAG 4.1.2).
+- 입력란에 라벨을 붙이고(WCAG 4.1.2, KWCAG 5.3.4.1 레이블 제공), 오류는 `FieldRow`의
+  `error`로 보여 줍니다(WCAG 3.3.1).
+
+## 토큰
+
+PasswordInput에는 따로 정한 색이 없습니다. 입력란은 `Input`의 토큰을 쓰고, 눈 모양
+버튼은 ghost `IconButton`입니다.
+
+## 관련 컴포넌트
+
+- **Input**: 감싸고 있는 입력란과 그 토큰.
+- **PinInput**: 일회용 코드.
+- **FieldRow**: 라벨, 규칙, 오류 문구.
+
+</Ko>

package/src/components/PinInput/PinInput.stories.tsx

@@ -1,6 +1,12 @@
 import { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 
+import { Stack } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
+import { Subtext } from '../Typography';
 import { PinInput } from '.';
 
 const meta = {
@@ -55,3 +61,88 @@ export const Invalid: Story = {
   args: { length: 5, invalid: true },
   render: (args) => <Controlled {...args} />,
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `PinInput.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoSayWhereTheCodeWent: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: say where the code was sent',
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Stack gap={2} maxW="420px">
+        <Subtext color="fg.muted">
+          name@company.com 으로 보낸 6자리 코드를 입력하세요.
+        </Subtext>
+        <PinInput
+          length={6}
+          type="numeric"
+          otp
+          value={value}
+          onChange={setValue}
+        />
+      </Stack>
+    );
+  },
+};
+
+export const DontCodeWithoutContext: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: boxes with no context",
+  render: () => <PinInput length={6} type="numeric" />,
+};
+
+export const DoErrorBelow: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a wrong code, in words',
+  render: () => (
+    <Stack maxW="420px">
+      <FieldRow error="코드가 맞지 않습니다. 메일을 다시 확인해 주세요.">
+        <PinInput length={6} type="numeric" value="123456" invalid />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+/** Tokens each box reads, as written in `PinInput.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.surface', use: <T en="Box background" ko="칸 배경" /> },
+        { token: 'fg.default', use: <T en="Character" ko="글자" /> },
+        {
+          token: 'border.control',
+          use: <T en="Border at rest" ko="평소 테두리" />,
+        },
+        {
+          token: 'fg.icon',
+          use: <T en="Border on hover" ko="마우스를 올렸을 때 테두리" />,
+        },
+        {
+          token: 'primary.main',
+          use: <T en="Border and ring on focus" ko="초점 테두리와 링" />,
+        },
+        {
+          token: 'danger.solid',
+          use: <T en="Border when invalid" ko="오류 상태 테두리" />,
+        },
+        {
+          token: 'disabled.bg',
+          use: <T en="Disabled background" ko="비활성 배경" />,
+        },
+        {
+          token: 'disabled.fg',
+          use: <T en="Disabled text" ko="비활성 글자" />,
+        },
+      ]}
+    />
+  ),
+};