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

package/src/components/Accordion/Accordion.usage.mdx

@@ -0,0 +1,200 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as AccordionStories from './Accordion.stories';
+
+<Meta of={AccordionStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Accordion
+
+A stack of sections, each with a heading button that opens and closes its
+content. `Accordion` › `AccordionItem` (`value`) › `AccordionButton` +
+`AccordionPanel`.
+
+Defaults that differ from Chakra: `multiple` is `true` (several sections can
+be open at once) and `variant` is `enclosed`. Content opens on the house
+presence clock (300 ms in, 150 ms out).
+
+## When to use
+
+- A list of questions or topics the reader scans, opening only the ones they
+  need: an FAQ, a landing page's feature list.
+- Long optional content grouped into several named sections.
+
+## When not to use
+
+- One section → `Collapsible`.
+- Content everyone needs, or steps that must be completed in order → show it
+  on the page, or use a stepper. Do not hide required input.
+- Switching between views of the same thing → `Tabs`.
+- A hierarchy the user selects from → `Tree`.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `variant` | `enclosed` (default), `outline`, `subtle`, `plain`: Chakra's accordion recipe styles |
+| `multiple` | Default `true`. Set `false` to keep one open at a time |
+| `collapsible` | With `multiple={false}`, lets the open item be closed again |
+| `defaultValue` / `value` | Item values open at start, or controlled |
+| `lazyMount` / `unmountOnExit` | Mount heavy content only when opened |
+| `AccordionButton customIcon` | Replace the chevron indicator |
+
+`AccordionPanel` is marked deprecated in favour of `Accordion.ItemContent` +
+`Accordion.ItemBody` from Chakra; it still works and renders exactly that.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Accordion
+
+섹션을 쌓아 두고, 섹션마다 제목 버튼으로 내용을 여닫는 컴포넌트입니다. 구조는
+`Accordion` › `AccordionItem`(`value`) › `AccordionButton` + `AccordionPanel`입니다.
+
+Chakra와 다른 기본값이 있습니다. `multiple`이 `true`라 여러 섹션을 함께 열 수 있고,
+`variant`는 `enclosed`입니다. 내용은 공통 등장 시간(열 때 300ms, 닫을 때 150ms)으로
+열립니다.
+
+## 언제 쓰나요
+
+- 읽는 사람이 훑어보다가 필요한 것만 여는 질문이나 주제 목록: 자주 묻는 질문, 랜딩
+  페이지의 기능 목록.
+- 길지만 선택적인 내용을 이름 붙은 여러 섹션으로 나눌 때.
+
+## 언제 쓰지 않나요
+
+- 섹션이 하나라면 `Collapsible`을 씁니다.
+- 모두가 봐야 하는 내용이나 순서대로 마쳐야 하는 단계는 페이지에 그대로 보여 주거나
+  단계 표시를 씁니다. 필수 입력을 숨기지 않습니다.
+- 같은 대상의 보기를 바꾼다면 `Tabs`를 씁니다.
+- 고르는 계층이라면 `Tree`를 씁니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `variant` | `enclosed`(기본값), `outline`, `subtle`, `plain`. Chakra 아코디언 레시피의 모양 |
+| `multiple` | 기본값 `true`. `false`로 두면 한 번에 하나만 열림 |
+| `collapsible` | `multiple={false}`일 때 열린 항목을 다시 닫을 수 있게 함 |
+| `defaultValue` / `value` | 처음 열어 둘 항목, 또는 제어 값 |
+| `lazyMount` / `unmountOnExit` | 무거운 내용을 열 때만 그림 |
+| `AccordionButton`의 `customIcon` | 화살표 표시를 바꿈 |
+
+`AccordionPanel`은 Chakra의 `Accordion.ItemContent` + `Accordion.ItemBody`를 쓰라는
+뜻으로 deprecated 표시가 되어 있습니다. 지금도 동작하며 그 구조를 그대로 그립니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={AccordionStories.DoFaq} />
+<Verdict
+  kind="do"
+  en="Use it for questions the reader scans. Each heading is a full question, so the closed list already says what is inside."
+  ko="훑어보는 질문 목록에 씁니다. 제목마다 완전한 질문이라 닫힌 상태에서도 안에 무엇이 있는지 알 수 있습니다."
+/>
+
+<Canvas of={AccordionStories.DontHideRequired} />
+<Verdict
+  kind="dont"
+  en="Hide a required step behind a closed section. People submit without opening it. Show required input on the page."
+  ko="필수 단계를 닫힌 섹션 뒤에 숨기지 마세요. 사람들은 열어 보지 않고 제출합니다. 필수 입력은 페이지에 보여 줍니다."
+/>
+
+<En>
+
+## Content
+
+- Headings say what is inside: a question, or a noun phrase. Not 더 보기.
+- Keep headings to one line on mobile.
+- Do not put another Accordion inside a panel.
+
+## Accessibility
+
+What Accordion does for you:
+
+- Each `AccordionButton` is a `<button>` with `aria-expanded` and
+  `aria-controls`, and the content region is labelled by it (WCAG 4.1.2).
+- Enter and Space toggle; arrow keys, Home and End move between headings
+  (WCAG 2.1.1). The button shows the shared focus ring (WCAG 2.4.7).
+
+What you still have to do:
+
+- **Put the button inside a heading when the sections are part of the page
+  structure**, so heading navigation finds them (WCAG 1.3.1): wrap the
+  `AccordionButton` in a heading of the level your page needs.
+- Keep the trigger to phrasing content: text, icons, `Badge`. No `<div>` or
+  `<p>` inside the button (`ACCESSIBILITY.md` §5).
+- A custom icon is decorative; give it `aria-hidden`.
+
+## Tokens
+
+The variant colours come from Chakra's accordion recipe. The library adds
+only the focus ring and the presence timing (`theme/recipes/accordion.ts`).
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 제목에는 안에 무엇이 있는지 씁니다. 질문이나 명사구로 쓰고, '더 보기'처럼 쓰지
+  않습니다.
+- 제목은 모바일에서 한 줄에 들어가게 씁니다.
+- 패널 안에 다시 Accordion을 넣지 않습니다.
+
+## 접근성
+
+Accordion이 알아서 하는 일
+
+- `AccordionButton`은 `aria-expanded`와 `aria-controls`가 있는 `<button>`이고, 내용
+  영역은 그 버튼을 이름으로 씁니다(WCAG 4.1.2).
+- Enter와 Space로 여닫고, 화살표 키와 Home/End로 제목 사이를 오갑니다(WCAG 2.1.1).
+  버튼에는 공통 초점 링이 나타납니다(WCAG 2.4.7).
+
+직접 챙겨야 하는 일
+
+- **섹션이 페이지 구조의 일부라면 버튼을 제목 요소 안에 둡니다.** 그래야 제목으로
+  이동할 때 찾을 수 있습니다(WCAG 1.3.1). `AccordionButton`을 페이지에 맞는 수준의
+  제목으로 감쌉니다.
+- 트리거 안에는 글자, 아이콘, `Badge` 같은 phrasing content만 넣습니다. 버튼 안에
+  `<div>`나 `<p>`를 넣지 않습니다(`ACCESSIBILITY.md` 5절).
+- 직접 넣은 아이콘은 장식이므로 `aria-hidden`을 붙입니다.
+
+## 토큰
+
+변형의 색은 Chakra 아코디언 레시피에서 옵니다. 이 라이브러리는 초점 링과 등장
+시간(`theme/recipes/accordion.ts`)만 더합니다.
+
+</Ko>
+
+<Canvas of={AccordionStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Collapsible**: a single section that opens.
+- **Tabs**: switch between views.
+- **ExpandableText**: clip one block of text.
+- **Tree**: a hierarchy to select from.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Collapsible**: 여닫는 섹션 하나.
+- **Tabs**: 보기 전환.
+- **ExpandableText**: 글 한 덩어리를 접어 둘 때.
+- **Tree**: 고르는 계층.
+
+</Ko>

package/src/components/Appear/Appear.usage.mdx

@@ -0,0 +1,107 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as AppearStories from './Appear.stories';
+
+<Meta of={AppearStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Appear
+
+Brings a single element in once, on mount: a fade, plus an optional scale (a
+stamp landing) or a short rise (content arriving).
+
+</En>
+
+<Ko>
+
+# Appear
+
+요소 하나를 마운트될 때 한 번 등장시킵니다. 기본은 페이드이고, 도장이 찍히듯 커지는
+효과나 아래에서 올라오는 효과를 더할 수 있습니다.
+
+</Ko>
+
+<Canvas of={AppearStories.Default} />
+
+<En>
+
+## When to use
+
+- A mark that lands on something the reader just did: a ✓ on a correct
+  answer, a reward medallion (`scaleFrom`).
+- A line or card that arrives on its own schedule, such as the beats of a
+  level-up screen, each with its own `delayMs` (`rise`).
+
+## When not to use
+
+- The element can also close (a menu, popover or modal) →
+  `animationStyle="presence"`, which those parts already use. Appear cannot
+  animate out.
+- Several items of one list arrive together → `staggerProps(index)`.
+- The content opens underneath something and pushes the layout down →
+  `Reveal`.
+- One piece of content replaces another → `SwapTransition`.
+- A value that is already on screen changed → `Pulse` or `CountUp`.
+
+The **어느 것을 쓸까** story plays `presence`, `stagger` and Appear side by side.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` the fade stays and the scale and rise
+  are dropped. The element still has to become visible; the movement carries no
+  information.
+- Appear adds one `div` around `children`, and layout props land on that
+  wrapper. Inside a `<button>` pass `as="span"`, because a button may only hold
+  phrasing content (ACCESSIBILITY.md §5). Where the parent needs its children
+  directly (a `<tr>`, Ark parts such as `Menu.List`), animate the inner element
+  instead of wrapping.
+- Appearing does not announce anything. If the new element is a result the
+  reader has to hear, put the message in a live region yourself
+  (WCAG 4.1.3).
+
+## Props
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 사용자가 방금 한 일 위에 표시가 찍힐 때: 정답 위의 ✓, 보상 메달(`scaleFrom`).
+- 한 줄이나 카드가 각자 정한 시점에 들어올 때. 예를 들어 레벨 업 화면의 문구들은 저마다
+  다른 `delayMs`로 들어옵니다(`rise`).
+
+## 언제 쓰지 않나요
+
+- 요소가 닫히기도 한다면(메뉴, 팝오버, 모달) `animationStyle="presence"`를 씁니다. 이
+  파트들은 이미 presence를 씁니다. Appear는 사라지는 애니메이션이 없습니다.
+- 한 목록의 항목 여럿이 함께 들어온다면 `staggerProps(index)`를 씁니다.
+- 내용이 무언가의 아래에서 열리며 레이아웃을 밀어낸다면 `Reveal`을 씁니다.
+- 한 내용이 다른 내용으로 바뀐다면 `SwapTransition`을 씁니다.
+- 이미 화면에 있는 값이 바뀌었다면 `Pulse`나 `CountUp`을 씁니다.
+
+**어느 것을 쓸까** 스토리에서 `presence`, `stagger`, Appear를 나란히 재생해 볼 수 있습니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 페이드만 남고 커지는 효과와 올라오는 효과는
+  빠집니다. 요소는 여전히 나타나야 하지만, 움직임 자체는 정보가 아니기 때문입니다.
+- Appear는 `children` 바깥에 `div`를 하나 더하고, 레이아웃 속성은 그 감싸는 요소에
+  적용됩니다. `<button>` 안에서는 `as="span"`을 넘깁니다. 버튼 안에는 phrasing
+  content만 들어갈 수 있습니다(ACCESSIBILITY.md 5절). 부모가 자식을 직접 다뤄야 하는
+  곳(`<tr>`, `Menu.List` 같은 Ark 파트)에서는 감싸지 말고 안쪽 요소에 애니메이션을 줍니다.
+- 나타난다고 해서 무언가를 읽어 주지는 않습니다. 사용자가 들어야 하는 결과라면 그
+  메시지를 직접 라이브 영역에 넣습니다(WCAG 4.1.3).
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={AppearStories}
+  include={['scaleFrom', 'rise', 'delayMs', 'durationMs']}
+/>

package/src/components/Avatar/Avatar.recipe.test.tsx

@@ -0,0 +1,176 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { Avatar, avatarColorPalette, hueForName } from '.';
+
+const wrap = (ui: React.ReactNode) =>
+  render(<ChakraProvider value={system}>{ui}</ChakraProvider>);
+
+/**
+ * The rules emotion emitted for `el`'s own `css-*` class, one per line. jsdom
+ * cannot compute styles inside Chakra's `@layer` blocks, so the tests read the
+ * generated rules instead of `getComputedStyle`.
+ */
+function rulesFor(el: Element | null): string[] {
+  if (!el) throw new Error('element not rendered');
+  const cls = [...el.classList].find((c) => c.startsWith('css-'));
+  return [...document.querySelectorAll('style')]
+    .flatMap((s) => (s.textContent ?? '').split('\n'))
+    .filter((line) => line.includes(`.${cls}{`));
+}
+
+/** Every declaration for `el`, layered or not, as one string. */
+const declarations = (el: Element | null) => rulesFor(el).join('');
+
+/**
+ * Only the rules outside any `@layer` (style props such as `colorPalette`) —
+ * these beat the recipe's `@layer recipes` rules.
+ */
+const unlayered = (el: Element | null) =>
+  rulesFor(el)
+    .filter((line) => !line.startsWith('@layer'))
+    .join('');
+
+const root = (c: HTMLElement) => c.querySelector('[data-part="root"]');
+const fallback = (c: HTMLElement) => c.querySelector('[data-part="fallback"]');
+
+describe('avatar recipe', () => {
+  it('the fallback fills the root and the root carries the fill', () => {
+    const { container } = wrap(<Avatar name="Sean Park" />);
+    const r = declarations(root(container));
+    const f = declarations(fallback(container));
+    // The regression: Chakra sizes only the root, so a fill on an unsized
+    // fallback covered just the glyph box.
+    expect(f).toContain('width:100%');
+    expect(f).toContain('height:100%');
+    expect(f).toContain('justify-content:center');
+    expect(f).not.toMatch(/background:/);
+    expect(r).toContain(
+      'background:var(--chakra-colors-color-palette-surface,'
+    );
+    expect(r).toContain('color:var(--chakra-colors-color-palette-fg)');
+    expect(r).toContain('border-width:1px');
+    expect(r).toContain('overflow:hidden');
+  });
+
+  it('maps colorPalette onto the person’s category pair', () => {
+    const hue = hueForName('Sean Park');
+    const { container } = wrap(<Avatar name="Sean Park" />);
+    // Unlayered, so it wins over the recipe's own `category.neutral` default.
+    expect(unlayered(root(container))).toContain(
+      `--chakra-colors-color-palette-surface:var(--chakra-colors-category-${hue}-surface)`
+    );
+    expect(avatarColorPalette('Sean Park')).toBe(`category.${hue}`);
+    expect(avatarColorPalette('Sean Park', 'blue')).toBe('category.blue');
+  });
+
+  it('a nameless avatar — and a bare Avatar.Root — use the neutral pair', () => {
+    expect(avatarColorPalette(undefined)).toBe('category.neutral');
+    for (const ui of [
+      <Avatar key="a" />,
+      <Avatar.Root key="b">
+        <Avatar.Fallback name="Bare Root" />
+      </Avatar.Root>,
+    ]) {
+      const { container, unmount } = wrap(ui);
+      const r = declarations(root(container));
+      expect(r).toContain(
+        '--chakra-colors-color-palette-surface:var(--chakra-colors-category-neutral-surface)'
+      );
+      expect(declarations(fallback(container))).toContain('width:100%');
+      unmount();
+    }
+  });
+
+  it('variant="logo" paints the light logo tile, not the palette', () => {
+    const { container } = wrap(<Avatar name="GPT" variant="logo" />);
+    const r = declarations(root(container));
+    expect(r).toContain('background:var(--chakra-colors-bg-logo)');
+    expect(r).toContain('color:var(--chakra-colors-fg-on-logo)');
+  });
+
+  it('a Chakra palette without `surface` still fills (falls back to `muted`)', () => {
+    const { container } = wrap(<Avatar name="X" colorPalette="blue" />);
+    expect(declarations(root(container))).toMatch(
+      /background:var\(--chakra-colors-color-palette-surface, ?var\(--chakra-colors-color-palette-muted\)\)/
+    );
+  });
+
+  it('solid / outline fall back onto the category pair', () => {
+    const solid = wrap(<Avatar name="X" variant="solid" />);
+    expect(declarations(root(solid.container))).toMatch(
+      /background:var\(--chakra-colors-color-palette-solid, ?var\(--chakra-colors-color-palette-fg\)\)/
+    );
+    solid.unmount();
+    const outline = wrap(<Avatar name="X" variant="outline" />);
+    expect(declarations(root(outline.container))).toMatch(
+      /border-color:var\(--chakra-colors-color-palette-border, ?var\(--chakra-colors-color-palette-fg\)\)/
+    );
+  });
+
+  it('keeps Chakra’s size variants', () => {
+    const { container } = wrap(<Avatar name="A" size="2xl" />);
+    expect(declarations(root(container))).toContain(
+      '--avatar-size:var(--chakra-sizes-16)'
+    );
+  });
+});
+
+describe('Avatar.Group max', () => {
+  const names = ['김지민', '이서준', '박하은', '최유나', '정민호'];
+
+  it('shows max avatars plus a neutral "+N" counter', () => {
+    const { container } = wrap(
+      <Avatar.Group max={3}>
+        {names.map((n) => (
+          <Avatar key={n} name={n} />
+        ))}
+      </Avatar.Group>
+    );
+    const roots = container.querySelectorAll('[data-part="root"]');
+    expect(roots).toHaveLength(4);
+    const counter = roots[3];
+    expect(counter.textContent).toBe('+2');
+    // Phrasing content, so `<Avatar.Group as="span">` can sit in a button.
+    expect(counter.tagName).toBe('SPAN');
+    expect(counter.querySelector('[data-part="fallback"]')?.tagName).toBe(
+      'SPAN'
+    );
+    expect(declarations(counter)).toContain(
+      '--chakra-colors-color-palette-surface:var(--chakra-colors-category-neutral-surface)'
+    );
+    expect(declarations(counter)).toContain(
+      'background:var(--chakra-colors-color-palette-surface,'
+    );
+  });
+
+  it('the counter stays neutral in a logo group', () => {
+    const { container } = wrap(
+      <Avatar.Group max={1} variant="logo">
+        <Avatar name="A" />
+        <Avatar name="B" />
+      </Avatar.Group>
+    );
+    const roots = container.querySelectorAll('[data-part="root"]');
+    expect(declarations(roots[0])).toContain('var(--chakra-colors-bg-logo)');
+    expect(declarations(roots[1])).not.toContain('bg-logo');
+  });
+
+  it('no max, or max ≥ count, renders every avatar and no counter', () => {
+    for (const max of [undefined, 5, 9]) {
+      const { container, unmount } = wrap(
+        <Avatar.Group max={max}>
+          {names.map((n) => (
+            <Avatar key={n} name={n} />
+          ))}
+        </Avatar.Group>
+      );
+      const roots = container.querySelectorAll('[data-part="root"]');
+      expect(roots).toHaveLength(5);
+      expect(container.textContent).not.toContain('+');
+      unmount();
+    }
+  });
+});