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

package/src/components/Textarea/Textarea.usage.mdx

@@ -0,0 +1,186 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TextareaStories from './Textarea.stories';
+
+<Meta of={TextareaStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Textarea
+
+A multi-line text field for prose the user writes: instructions, descriptions,
+messages.
+
+## When to use
+
+- Text that can run to several sentences or lines: a chatbot's system
+  instructions, a description, a reason for a request.
+
+## When not to use
+
+- A one-line value such as a name or a title → `Input`.
+- The chat composer, which grows with the message and sends on Enter → the
+  chat input in your app, not this field.
+- Formatted text (headings, lists, links) → a rich-text editor.
+
+## Props
+
+</En>
+
+<Ko>
+
+# Textarea
+
+사용자가 직접 쓰는 여러 줄짜리 글(지시문, 설명, 메시지)을 받는 입력란입니다.
+
+## 언제 쓰나요
+
+- 몇 문장이나 몇 줄로 길어질 수 있는 글: 챗봇의 시스템 지시문, 설명, 요청 사유.
+
+## 언제 쓰지 않나요
+
+- 이름이나 제목처럼 한 줄이면 되는 값은 `Input`을 씁니다.
+- 내용에 따라 높이가 늘고 Enter로 보내는 채팅 입력창은 이 컴포넌트가 아니라 앱의 채팅
+  입력 컴포넌트를 씁니다.
+- 제목, 목록, 링크 같은 서식이 필요한 글은 리치 텍스트 편집기를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={TextareaStories} include={['invalid']} />
+
+<En>
+
+- `rows` sets the height. Textarea is fixed at `resize="none"` and does not
+  grow with its content; pass `resize="vertical"` if the user should be able to
+  drag it taller.
+- `invalid` changes the border only. Put the field in `FieldRow` with `error`
+  so assistive technology hears it too.
+- `readOnly` and `disabled` look the same as on `Input`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- 높이는 `rows`로 정합니다. Textarea는 `resize="none"`으로 고정되어 있고 내용에 따라
+  늘어나지 않습니다. 사용자가 끌어서 늘릴 수 있어야 한다면 `resize="vertical"`을
+  넘깁니다.
+- `invalid`는 테두리만 바꿉니다. 보조기술에도 알리려면 `FieldRow`에 넣고 `error`를
+  줍니다.
+- `readOnly`와 `disabled`는 `Input`과 같은 모양입니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TextareaStories.DoInstructionsWithCount} />
+<Verdict
+  kind="do"
+  en="Give long text a label, a line of help, and a visible count when there is a limit."
+  ko="긴 글을 받는 입력란에는 라벨과 한 줄 도움말을 두고, 글자 수 제한이 있으면 남은 양을 보여 줍니다."
+/>
+
+<Canvas of={TextareaStories.DontSingleValue} />
+<Verdict
+  kind="dont"
+  en="Use a Textarea for a one-line value. The height promises a paragraph that never comes."
+  ko="한 줄이면 되는 값에 Textarea를 쓰지 마세요. 높이만 보고 긴 글을 써야 하는 줄 압니다."
+/>
+
+<Canvas of={TextareaStories.DoSingleValueInInput} />
+<Verdict
+  kind="do"
+  en="Use Input for a name or a title."
+  ko="이름이나 제목에는 Input을 씁니다."
+/>
+
+<En>
+
+## Content
+
+- Label and error rules are the same as `Input`.
+- Size the field to the expected answer: `rows={3}` for a short reason, more
+  for instructions. Height is a hint about how much to write.
+- Put examples in helper text, not in a long placeholder that vanishes on the
+  first keystroke.
+
+## Accessibility
+
+What Textarea does for you:
+
+- Renders a native `<textarea>`. Enter inserts a new line; Tab moves focus out.
+- Shows a `primary.main` focus border and ring (WCAG 2.4.7), and inside
+  `FormControl` / `FieldRow` it is labelled and gets `aria-invalid` and
+  `aria-describedby` from the field.
+
+What you still have to do:
+
+- Give it a visible label with `FieldRow` or `FormControl` + `FormLabel`
+  (WCAG 4.1.2; KWCAG 5.3.4.1 레이블 제공).
+- Put errors in words with `FieldRow` `error`, not as a red border alone
+  (WCAG 1.4.1, 3.3.1).
+- If you set `maxLength`, show the count; the browser stops input silently at
+  the limit.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨과 오류 문구 규칙은 `Input`과 같습니다.
+- 예상되는 답의 길이에 맞춰 높이를 정합니다. 짧은 사유는 `rows={3}`, 지시문은 그보다
+  길게 잡습니다. 높이는 얼마나 써야 하는지 알려 주는 단서입니다.
+- 예시는 첫 글자를 입력하면 사라지는 긴 플레이스홀더가 아니라 도움말에 씁니다.
+
+## 접근성
+
+Textarea가 알아서 하는 일
+
+- 네이티브 `<textarea>`를 그립니다. Enter는 줄을 바꾸고, Tab은 초점을 다음 요소로
+  옮깁니다.
+- 초점을 받으면 `primary.main` 테두리와 링을 보여 주고(WCAG 2.4.7), `FormControl`이나
+  `FieldRow` 안에서는 라벨과 연결되며 `aria-invalid`와 `aria-describedby`를 받습니다.
+
+직접 챙겨야 하는 일
+
+- `FieldRow`나 `FormControl`과 `FormLabel`로 보이는 라벨을 붙입니다(WCAG 4.1.2, KWCAG
+  5.3.4.1 레이블 제공).
+- 오류는 빨간 테두리만이 아니라 `FieldRow`의 `error`로 문구를 함께 보여 줍니다(WCAG
+  1.4.1, 3.3.1).
+- `maxLength`를 정했다면 글자 수를 보여 줍니다. 브라우저는 제한에 닿으면 아무 안내 없이
+  입력을 막습니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={TextareaStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Input**: one line of text.
+- **FieldRow**: label, helper text, error and the count slot.
+- **MaxLengthIndicator**: the character count.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Input**: 한 줄짜리 텍스트.
+- **FieldRow**: 라벨, 도움말, 오류 문구, 글자 수 자리.
+- **MaxLengthIndicator**: 글자 수 표시.
+
+</Ko>

package/src/components/Toast/Toast.stories.tsx

@@ -1,10 +1,20 @@
-import { useState } from 'react';
-import { Flex, Stack, Text } from '@chakra-ui/react';
+import { ReactNode, useState } from 'react';
+import {
+  Box,
+  Toaster as ChakraToaster,
+  createToaster,
+  Flex,
+  Stack,
+  Text,
+} from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Button } from '../Button';
 import { Toast } from './Toast';
-import type { UseToastOptions } from './Toast.types';
+import { toastStyles } from './Toast.styles';
+import type { ToastAction, ToastStatus, UseToastOptions } from './Toast.types';
 import { Toaster } from './Toaster';
 import { useToast } from './useToast';
 
@@ -14,6 +24,14 @@ const meta = {
   parameters: {
     layout: 'centered',
   },
+  argTypes: {
+    status: {
+      control: 'select',
+      options: ['neutral', 'info', 'success', 'warning', 'error'],
+      description:
+        '`neutral` (default): a plain result with no status, no icon. `success`: done as asked. `info`: a fact about what just happened; nothing is wrong. `warning`: done, but not quite as expected. `error`: it did not happen.',
+    },
+  },
 } satisfies Meta<typeof Toast>;
 
 export default meta;
@@ -602,3 +620,167 @@ export const ActionShortMessage: Story = {
     />
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Toast.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written on each story because the indexer reads
+// CSF statically.
+//
+// Each specimen renders the real `Toast` through its own toaster, held open
+// (`duration: Infinity`) inside a transformed box. The transform makes the
+// toaster's `position: fixed` region relative to the box, so the toast sits in
+// the docs page instead of at the top of the window, and the specimens do not
+// share the app-wide `toaster`.
+
+const ToastPreview = ({
+  status = 'neutral',
+  title,
+  description,
+  action,
+  height = 150,
+}: {
+  status?: ToastStatus;
+  title?: ReactNode;
+  description?: ReactNode;
+  action?: ToastAction;
+  height?: number;
+}) => {
+  // Created with its toast in the initialiser, not in an effect: a toast
+  // dismissed by a StrictMode effect cleanup did not come back.
+  const [local] = useState(() => {
+    const toaster = createToaster({ placement: 'top' });
+    toaster.create({
+      type: status === 'neutral' ? 'info' : status,
+      title,
+      description,
+      duration: Infinity,
+      meta: { status, action },
+    });
+    return toaster;
+  });
+  return (
+    <Box
+      position="relative"
+      transform="translateZ(0)"
+      h={`${height}px`}
+      w="100%"
+      minW={{ md: '420px' }}
+      overflow="hidden"
+    >
+      <ChakraToaster toaster={local} insetInline={{ mdDown: '4' }} gap={3}>
+        {(toast) => {
+          const s = (toast.meta?.status ?? 'neutral') as ToastStatus;
+          return (
+            <Toast
+              title={toast.title}
+              description={toast.description}
+              status={s}
+              action={toast.meta?.action}
+              onClose={() => {}}
+              {...toastStyles[s]}
+            />
+          );
+        }}
+      </ChakraToaster>
+    </Box>
+  );
+};
+
+const noop = () => {};
+
+export const DoActionProp: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one action through `action`',
+  render: () => (
+    <ToastPreview
+      status="error"
+      description="크레딧이 부족해 응답을 생성하지 못했습니다."
+      action={{ label: '크레딧 구매', onClick: noop }}
+    />
+  ),
+};
+
+export const DontButtonInDescription: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a Button inside `description`",
+  render: () => (
+    <ToastPreview
+      status="error"
+      height={170}
+      description={
+        <Stack gap={2} align="flex-start">
+          <span>크레딧이 부족해 응답을 생성하지 못했습니다.</span>
+          <Button variant="secondary" size="sm">
+            크레딧 구매
+          </Button>
+        </Stack>
+      }
+    />
+  ),
+};
+
+export const DoUndoAfterDelete: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: confirm, and offer undo',
+  render: () => (
+    <ToastPreview
+      status="success"
+      description="채팅을 삭제했습니다."
+      action={{ label: '되돌리기', onClick: noop }}
+    />
+  ),
+};
+
+export const DontToastForFieldError: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a toast for a field error",
+  render: () => (
+    <ToastPreview
+      status="error"
+      description="이메일 형식이 올바르지 않습니다."
+    />
+  ),
+};
+
+export const DoNeutralResult: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: neutral for a plain result',
+  render: () => <ToastPreview description="링크를 복사했습니다." />,
+};
+
+const STATUSES: ToastStatus[] = ['neutral', 'info', 'success', 'warning', 'error'];
+
+/** Tokens each status reads, from `Toast.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={STATUSES.flatMap((status) => [
+        {
+          token: toastStyles[status].bg as string,
+          use: <T en={`${status} · background`} ko={`${status} · 배경`} />,
+        },
+        {
+          token: toastStyles[status].borderColor as string,
+          use: <T en={`${status} · border`} ko={`${status} · 테두리`} />,
+        },
+        {
+          token: toastStyles[status].color as string,
+          use: (
+            <T
+              en={`${status} · text, icon, action, ×`}
+              ko={`${status} · 글자, 아이콘, 동작, ×`}
+            />
+          ),
+        },
+      ])}
+    />
+  ),
+};

package/src/components/Toast/Toast.styles.ts

@@ -7,8 +7,12 @@ import type { ToastStatus } from './Toast.types';
  *
  * Each status is bg `{s}.bg` + text `{s}.fg` + a 1px `{s}.border` outline —
  * `info` reads its own `info.*` family instead of borrowing `primary.*`.
- * `neutral` carries no status (it is the default when none is given):
- * `border.default` / `bg.surface` / `fg.default`.
+ * `neutral` carries no status (it is the default when none is given) and is
+ * inverted: the tooltip pair `tooltip.bg` / `tooltip.fg`. A `bg.surface` toast
+ * was white on a white canvas in light mode, set apart only by a 1px border
+ * and the shadow — a "링크를 복사했어요" confirmation was easy to miss. The
+ * tooltip pair already flips per mode (ink in light, off-white in dark), so the
+ * toast stays the highest-contrast thing on the page in both.
  */
 export const toastStyles: Record<ToastStatus, BoxProps> = {
   info: {
@@ -32,9 +36,9 @@ export const toastStyles: Record<ToastStatus, BoxProps> = {
     borderColor: 'danger.border',
   },
   neutral: {
-    bg: 'bg.surface',
-    color: 'fg.default',
-    borderColor: 'border.default',
+    bg: 'tooltip.bg',
+    color: 'tooltip.fg',
+    borderColor: 'tooltip.bg',
   },
 };
 
@@ -69,9 +73,11 @@ export const closeButtonStyles: Record<ToastStatus, BoxProps> = {
     },
   },
   neutral: {
-    color: 'fg.default',
+    color: 'tooltip.fg',
     _hover: {
-      bg: 'bg.muted',
+      // A tint of the toast's own text colour: no surface token sits on the
+      // inverted ground in both modes.
+      bg: 'color-mix(in srgb, var(--chakra-colors-tooltip-fg) 16%, transparent)',
     },
   },
 };
@@ -127,9 +133,11 @@ export const actionStyles: Record<ToastStatus, BoxProps> = {
   },
   neutral: {
     ...actionBase,
-    color: 'fg.default',
-    _hover: { bg: 'bg.muted' },
-    _focusVisible: { outline: '2px solid', outlineColor: 'fg.default' },
+    color: 'tooltip.fg',
+    _hover: {
+      bg: 'color-mix(in srgb, var(--chakra-colors-tooltip-fg) 16%, transparent)',
+    },
+    _focusVisible: { outline: '2px solid', outlineColor: 'tooltip.fg' },
   },
 };