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

package/src/components/Banner/Banner.stories.tsx

@@ -1,8 +1,14 @@
-import { VStack } from '@chakra-ui/react';
+import type { ReactNode } from 'react';
+import { Flex, Stack, VStack } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
-import { H5, Subtext } from '../Typography';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { Card } from '../Card';
+import { H5, Subtext, Text } from '../Typography';
 import { Banner } from './Banner';
+import { accentStyles, bannerStyles } from './Banner.styles';
 
 const meta = {
   title: 'Components/Banner',
@@ -10,6 +16,14 @@ const meta = {
   args: {
     children: 'This is a banner message',
   },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['info', 'success', 'warning', 'danger', 'neutral'],
+      description:
+        '`info` (default): a system fact to know before acting; nothing is wrong. `success`: finished, and the result stays relevant here. `warning`: still works, read this first. `danger`: failed or blocked; the reader must act. `neutral`: a brand notice with no status.',
+    },
+  },
 } satisfies Meta<typeof Banner>;
 
 export default meta;
@@ -79,3 +93,139 @@ export const AllVariants: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Banner.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written on each story because the indexer reads
+// CSF statically.
+
+/** A confirm step like FactChat's credit distribution dialog. */
+const ConfirmPanel = ({ children }: { children?: ReactNode }) => (
+  <Card p={4} maxW="420px">
+    <Stack gap={3}>
+      <Text fontWeight="bold">크레딧 1,000을 하위 그룹 3곳에 나눕니다</Text>
+      {children}
+      <Flex gap={2} justify="flex-end">
+        <Button variant="secondary">취소</Button>
+        <Button variant="primary">나누기</Button>
+      </Flex>
+    </Stack>
+  </Card>
+);
+
+export const DoWarningBeforeAction: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: warning next to the action it is about',
+  render: () => (
+    <ConfirmPanel>
+      <Banner variant="warning" size="sm" my={0}>
+        나눈 크레딧은 되돌릴 수 없습니다.
+      </Banner>
+    </ConfirmPanel>
+  ),
+};
+
+export const DontBannerForTransientSuccess: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a banner for a passing success",
+  render: () => (
+    <Card p={4} maxW="420px">
+      <Stack gap={3}>
+        <Banner variant="success" size="sm" my={0}>
+          저장했습니다.
+        </Banner>
+        <Text fontWeight="bold">그룹 설정</Text>
+        <Subtext>이름, 설명, 관리자</Subtext>
+      </Stack>
+    </Card>
+  ),
+};
+
+export const DoInfoForLockedSetting: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: info for a locked setting',
+  render: () => (
+    <Card p={4} maxW="420px">
+      <Stack gap={2}>
+        <Text fontWeight="bold">인증 방식</Text>
+        <Banner variant="info" size="sm" my={0}>
+          인증 방식은 연결을 만든 뒤에는 바꿀 수 없습니다.
+        </Banner>
+      </Stack>
+    </Card>
+  ),
+};
+
+export const DontStackBanners: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a stack of banners",
+  render: () => (
+    <Stack gap={0} maxW="420px">
+      <Banner variant="info" size="sm">
+        이 그룹에만 적용됩니다.
+      </Banner>
+      <Banner variant="warning" size="sm">
+        크레딧이 7일 뒤 만료됩니다.
+      </Banner>
+      <Banner variant="warning" size="sm">
+        나눈 크레딧은 되돌릴 수 없습니다.
+      </Banner>
+      <Banner variant="danger" size="sm">
+        한 번에 50곳까지만 나눌 수 있습니다.
+      </Banner>
+    </Stack>
+  ),
+};
+
+export const DoDangerWithAlert: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: danger with role="alert" when it appears after submit',
+  render: () => (
+    <Stack gap={3} maxW="420px">
+      <Banner variant="danger" size="sm" my={0} role="alert">
+        저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요.
+      </Banner>
+      <Flex justify="flex-end">
+        <Button variant="primary">다시 저장</Button>
+      </Flex>
+    </Stack>
+  ),
+};
+
+const VARIANTS = ['info', 'success', 'warning', 'danger', 'neutral'] as const;
+
+/** Tokens each variant reads, from `Banner.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={VARIANTS.flatMap((variant) => [
+        {
+          token: bannerStyles[variant].bg as string,
+          use: <T en={`${variant} · background`} ko={`${variant} · 배경`} />,
+        },
+        {
+          token: bannerStyles[variant].borderColor as string,
+          use: <T en={`${variant} · border`} ko={`${variant} · 테두리`} />,
+        },
+        {
+          token: (accentStyles[variant] as { bg: string }).bg,
+          use: <T en={`${variant} · accent bar`} ko={`${variant} · 왼쪽 막대`} />,
+        },
+        {
+          token: bannerStyles[variant].color as string,
+          use: (
+            <T en={`${variant} · text and icon`} ko={`${variant} · 글자와 아이콘`} />
+          ),
+        },
+      ])}
+    />
+  ),
+};

package/src/components/Banner/Banner.types.ts

@@ -2,8 +2,37 @@ import { BoxProps } from '@chakra-ui/react';
 
 export type BannerSize = 'sm' | 'md' | 'lg';
 
+/**
+ * Banner variants (5.0).
+ *
+ * - `info` (default): a system fact the reader should know before acting
+ *   (a setting that is locked, where a value comes from). Nothing is wrong.
+ * - `success`: something finished and the result stays relevant on this
+ *   screen.
+ * - `warning`: it still works, but read this first (irreversible step,
+ *   something expiring).
+ * - `danger`: it failed or is blocked, and the reader has to do something.
+ * - `neutral`: a brand notice with no status (`primary.main` accent bar).
+ */
+export type BannerVariant =
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'neutral';
+
 export interface BannerProps extends BoxProps {
-  variant?: 'info' | 'success' | 'warning' | 'danger' | 'neutral';
+  /**
+   * Meaning of the message. Status variants only for a status every reader
+   * shares; `neutral` for a notice with none.
+   * @default 'info'
+   */
+  variant?: BannerVariant;
+  /** Hide the leading status icon. The text must still say the status. */
   hideIcon?: boolean;
+  /**
+   * `sm` = subtext, `md` = body text, `lg` = h5 text style.
+   * @default 'md'
+   */
   size?: BannerSize;
 }

package/src/components/Banner/Banner.usage.mdx

@@ -0,0 +1,233 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BannerStories from './Banner.stories';
+
+<Meta of={BannerStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Banner
+
+An inline message that stays on the page, next to the thing it is about, until
+the condition behind it changes.
+
+## When to use
+
+- To warn before an action the reader is about to take: an irreversible step,
+  something about to expire.
+- To state a system fact that shapes what the reader can do here: a setting
+  that is locked, a limit, where a value comes from.
+- To report a failure that blocks the form or section, with what to do next.
+
+## When not to use
+
+- The message only confirms that something just happened ("Saved") → `Toast`.
+- A short status attached to one item → `Badge`.
+- An error about one field → the field's own error text (`FormControl`).
+- The whole page failed to render → `ErrorFallback`.
+- An explanation the reader asks for → `InfoSprinkle` or `Tooltip`.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Banner
+
+관련된 내용 바로 옆에 붙어서, 원인이 해결될 때까지 화면에 남아 있는 안내
+문구입니다.
+
+## 언제 쓰나요
+
+- 되돌릴 수 없는 작업이나 곧 만료되는 항목처럼, 사용자가 하려는 일 앞에서 주의를
+  줄 때.
+- 잠긴 설정, 한도, 값의 출처처럼 이 화면에서 할 수 있는 일을 정하는 시스템 사실을
+  알릴 때.
+- 폼이나 영역 전체를 막는 실패를 알리고, 다음에 할 일을 함께 적을 때.
+
+## 언제 쓰지 않나요
+
+- 방금 끝난 일을 확인만 해 준다면("저장했습니다") `Toast`를 씁니다.
+- 항목 하나에 붙는 짧은 상태는 `Badge`를 씁니다.
+- 입력란 하나의 오류는 그 입력란의 오류 문구(`FormControl`)로 알립니다.
+- 페이지 전체를 그리지 못했다면 `ErrorFallback`을 씁니다.
+- 사용자가 찾아보는 설명은 `InfoSprinkle`이나 `Tooltip`을 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={BannerStories} include={['variant', 'size', 'hideIcon']} />
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `info` (default) | A system fact to know before acting; nothing is wrong | Locked setting, scope, where a value comes from |
+| `success` | Finished, and the result stays relevant on this screen | A connection that is now live |
+| `warning` | Still works, but read this first | Irreversible step, expiring credit |
+| `danger` | Failed or blocked; the reader has to act | Load failure, over a limit, submit error |
+| `neutral` | A brand notice with no status | Announcements |
+
+Use `size="sm"` inside cards, dialogs and forms; `md` (default) at the top of a
+page section. Banner adds `my={2}`; pass `my={0}` when the parent already sets
+the gap.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `info` (기본) | 작업 전에 알아야 할 시스템 사실이며, 문제가 있다는 뜻은 아님 | 잠긴 설정, 적용 범위, 값의 출처 |
+| `success` | 끝났고, 그 결과가 이 화면에서 계속 의미가 있음 | 연결이 활성화됨 |
+| `warning` | 동작은 하지만 먼저 읽어야 함 | 되돌릴 수 없는 작업, 만료 임박 크레딧 |
+| `danger` | 실패했거나 막혔고, 사용자가 무언가 해야 함 | 불러오기 실패, 한도 초과, 저장 오류 |
+| `neutral` | 상태가 없는 브랜드 공지 | 공지 |
+
+카드, 대화상자, 폼 안에서는 `size="sm"`을, 페이지 영역 맨 위에서는 기본값 `md`를
+씁니다. Banner에는 `my={2}`가 들어 있으니, 부모가 이미 간격을 정한다면
+`my={0}`을 넘깁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BannerStories.DoWarningBeforeAction} />
+<Verdict
+  kind="do"
+  en="Put a warning right above the action it is about, inside the same panel."
+  ko="주의 문구는 관련된 버튼 바로 위, 같은 패널 안에 둡니다."
+/>
+
+<Canvas of={BannerStories.DontBannerForTransientSuccess} />
+<Verdict
+  kind="dont"
+  en="Leave a success banner on the page after a save. It is out of date the moment the reader edits again. Confirm with a Toast."
+  ko="저장한 뒤 성공 배너를 화면에 남겨 두지 마세요. 다시 고치는 순간 맞지 않는 말이 됩니다. 확인은 Toast로 합니다."
+/>
+
+<Canvas of={BannerStories.DoInfoForLockedSetting} />
+<Verdict
+  kind="do"
+  en="Use info to explain why a setting cannot change. Nothing is wrong, so it is not a warning."
+  ko="설정을 바꿀 수 없는 이유는 info로 알립니다. 문제가 생긴 것이 아니므로 warning이 아닙니다."
+/>
+
+<Canvas of={BannerStories.DontStackBanners} />
+<Verdict
+  kind="dont"
+  en="Stack several banners. The reader stops reading after the first. Keep the one that blocks the next step and move the rest to where they apply."
+  ko="배너를 여러 개 쌓지 마세요. 사용자는 첫 번째 배너만 읽습니다. 다음 단계를 막는 배너 하나만 남기고, 나머지는 해당하는 자리로 옮기세요."
+/>
+
+<Canvas of={BannerStories.DoDangerWithAlert} />
+<Verdict
+  kind="do"
+  en='When a danger banner appears in response to a submit, give it role="alert" so screen readers announce it. Say what happened and what to do next.'
+  ko='저장 같은 동작의 결과로 나타나는 danger 배너에는 role="alert"를 붙여 화면 낭독기가 바로 읽게 합니다. 무슨 일이 있었는지와 다음에 할 일을 함께 적습니다.'
+/>
+
+<En>
+
+## Content
+
+- One or two sentences. Lead with what happened or what is true, then what to
+  do: "저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요."
+- Full sentences end with a full stop. Sentence case in English.
+- Numbers and dates the reader needs go in the text, not only in a link.
+- Do not repeat the icon's meaning as a prefix ("경고:", "Error:"). The variant
+  already says it, and the words say the rest.
+
+## Accessibility
+
+What Banner does for you:
+
+- A string child renders as body text in the variant's `{status}.fg` colour,
+  which the contrast audit checks against `{status}.bg` in both modes
+  (WCAG 1.4.3).
+- The icon is a decoration next to the words; the status is in the text.
+
+What you still have to do:
+
+- **Banner has no live-region role.** A banner that is on the page when it
+  loads needs none. One that appears after an action does: pass
+  `role="alert"` for an error, `role="status"` for anything else
+  (WCAG 4.1.3).
+- **Words, not colour alone** (WCAG 1.4.1). If you set `hideIcon`, the text
+  still has to say it is a warning or an error when that matters.
+- A link or button inside the banner needs a name that makes sense on its own
+  (WCAG 2.4.4).
+
+## Tokens
+
+The table is generated from `Banner.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한두 문장으로 씁니다. 무슨 일이 있었는지 또는 무엇이 사실인지 먼저 쓰고, 다음에 할
+  일을 씁니다. 예: "저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요."
+- 완전한 문장은 마침표로 끝냅니다. 영어는 문장형 대소문자를 씁니다.
+- 사용자에게 필요한 숫자와 날짜는 링크 안에만 두지 말고 본문에 씁니다.
+- 아이콘의 뜻을 "경고:", "오류:" 같은 머리말로 반복하지 않습니다. 변형이 이미 알려
+  주고, 나머지는 문장이 전합니다.
+
+## 접근성
+
+Banner가 알아서 하는 일
+
+- 문자열을 넘기면 변형의 `{status}.fg` 색으로 본문 글자를 그립니다. 이 색은 대비
+  감사에서 라이트·다크 모두 `{status}.bg` 위에서 검사합니다(WCAG 1.4.3).
+- 아이콘은 문구 옆의 장식이고, 상태는 문구가 전합니다.
+
+직접 챙겨야 하는 일
+
+- **Banner에는 라이브 영역 역할이 없습니다.** 페이지를 열 때부터 있는 배너는 역할이
+  필요 없습니다. 어떤 동작 뒤에 나타나는 배너는 다릅니다. 오류라면 `role="alert"`,
+  그 밖에는 `role="status"`를 넘깁니다(WCAG 4.1.3).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1). `hideIcon`을 쓴다면, 주의나 오류라는
+  사실이 중요할 때 문구가 그것을 말해야 합니다.
+- 배너 안의 링크나 버튼에는 그것만 읽어도 뜻이 통하는 이름을 붙입니다(WCAG 2.4.4).
+
+## 토큰
+
+아래 표는 `Banner.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={BannerStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Toast**: a passing confirmation or a result with one follow-up action.
+- **Badge**: a one-to-three-word status on one item.
+- **ErrorFallback**: the page or section failed to render.
+- **Guidelines/Actions in feedback surfaces**: buttons and links inside a
+  banner.
+- **Foundations/Brand & colour usage**: status colours mean status.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Toast**: 잠깐 보이는 확인 메시지, 또는 후속 동작이 하나 있는 결과 안내.
+- **Badge**: 항목 하나에 붙는 한두 단어의 상태.
+- **ErrorFallback**: 페이지나 영역을 그리지 못했을 때.
+- **Guidelines/Actions in feedback surfaces**: 배너 안의 버튼과 링크.
+- **Foundations/Brand & colour usage**: 상태색은 상태를 뜻합니다.
+
+</Ko>

package/src/components/BottomSheet/BottomSheet.stories.tsx

@@ -7,10 +7,12 @@
  * emulation) to try the gestures; with a mouse the same drags work by
  * pointer.
  */
-import { useState } from 'react';
+import { type ReactNode, useState } from 'react';
 import { Box, HStack, Stack } 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 {
   BoltIcon,
@@ -30,6 +32,8 @@ import {
   BottomSheetContent,
   BottomSheetFooter,
   BottomSheetHeader,
+  BottomSheetOverlay,
+  bottomSheetSlotRecipe,
 } from '.';
 
 const meta = {
@@ -202,3 +206,166 @@ export const LongScrollingList: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `BottomSheet.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each is a real, open sheet held inside a phone-sized frame
+// on the docs page: the portal is disabled, the frame's transform makes it the
+// containing block for the fixed positioner and scrim, and `modal={false}`
+// keeps the specimen from trapping focus or locking the page's scroll (the
+// scrim is drawn with `BottomSheetOverlay` so it still looks modal).
+
+const PhoneFrame = ({ children }: { children: ReactNode }) => (
+  <Box
+    position="relative"
+    w="360px"
+    maxW="100%"
+    h="420px"
+    mx="auto"
+    overflow="hidden"
+    borderRadius="l3"
+    borderWidth="1px"
+    borderColor="border.subtle"
+    bg="bg.canvas"
+    transform="translateZ(0)"
+    css={{
+      '& [data-scope=drawer][data-part=positioner], & [data-scope=drawer][data-part=backdrop]':
+        { width: '100%', height: '100%' },
+    }}
+  >
+    {children}
+  </Box>
+);
+
+const OpenSheet = ({ children }: { children: ReactNode }) => (
+  <PhoneFrame>
+    <BottomSheet
+      open
+      modal={false}
+      closeOnInteractOutside={false}
+      closeOnEscape={false}
+      portalProps={{ disabled: true }}
+    >
+      <BottomSheetOverlay />
+      <BottomSheetContent>{children}</BottomSheetContent>
+    </BottomSheet>
+  </PhoneFrame>
+);
+
+const SHORT_PALETTE = PALETTE.slice(0, 4);
+
+export const DoPickFromList: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a titled list to pick from',
+  render: () => (
+    <OpenSheet>
+      <BottomSheetHeader>노드 추가</BottomSheetHeader>
+      <BottomSheetCloseButton />
+      <BottomSheetBody>
+        {/* Inline: the docs page's `.sbdocs-content ul` marker rule
+            outranks a style prop. */}
+        <Stack as="ul" gap="1" style={{ listStyle: 'none' }} m="0" p="0">
+          {SHORT_PALETTE.map(({ icon: Icon, label, hint }) => (
+            <Box as="li" key={label}>
+              <HStack
+                as="button"
+                w="full"
+                gap="3"
+                px="3"
+                py="2.5"
+                borderRadius="l2"
+                textAlign="start"
+              >
+                <Icon boxSize="sm" aria-hidden />
+                <Stack gap="0">
+                  <Text fontWeight="semibold">{label}</Text>
+                  <Subtext color="fg.muted">{hint}</Subtext>
+                </Stack>
+              </HStack>
+            </Box>
+          ))}
+        </Stack>
+      </BottomSheetBody>
+    </OpenSheet>
+  ),
+};
+
+export const DontNoHeader: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a sheet with no header",
+  render: () => (
+    <OpenSheet>
+      <BottomSheetBody>
+        <Stack gap="2" pt="2">
+          {SHORT_PALETTE.map(({ label }) => (
+            <Text key={label}>{label}</Text>
+          ))}
+        </Stack>
+      </BottomSheetBody>
+    </OpenSheet>
+  ),
+};
+
+export const DoFooterToApply: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a footer when choices apply together',
+  render: () => (
+    <OpenSheet>
+      <BottomSheetHeader>필터</BottomSheetHeader>
+      <BottomSheetCloseButton />
+      <BottomSheetBody>
+        <Stack gap="2">
+          <Text>모델: 전체</Text>
+          <Text>기간: 최근 7일</Text>
+          <Text>상태: 완료</Text>
+        </Stack>
+      </BottomSheetBody>
+      <BottomSheetFooter>
+        <Button variant="secondary">초기화</Button>
+        <Button variant="primary">적용</Button>
+      </BottomSheetFooter>
+    </OpenSheet>
+  ),
+};
+
+const sheet = bottomSheetSlotRecipe.base ?? {};
+
+/** Tokens each sheet part reads, from `bottomSheetSlotRecipe` in `BottomSheet.styles.ts`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: String(sheet.content?.bg),
+          use: <T en="Sheet · background" ko="시트 · 배경" />,
+        },
+        {
+          token: String(sheet.content?.color),
+          use: <T en="Sheet · text" ko="시트 · 글자" />,
+        },
+        {
+          token: String(sheet.content?.borderColor),
+          use: <T en="Sheet · top edge" ko="시트 · 위 테두리" />,
+        },
+        {
+          token: String(sheet.grabberIndicator?.bg),
+          use: <T en="Grabber" ko="손잡이" />,
+        },
+        {
+          token: String(sheet.description?.color),
+          use: <T en="Description" ko="설명" />,
+        },
+        {
+          token: String(sheet.footer?.borderColor),
+          use: <T en="Footer · top rule" ko="푸터 · 위 선" />,
+        },
+      ]}
+    />
+  ),
+};