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

package/src/components/SegmentedControl/SegmentedControl.usage.mdx

@@ -0,0 +1,216 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SegmentedControlStories from './SegmentedControl.stories';
+
+<Meta of={SegmentedControlStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SegmentedControl
+
+A row of two to five mutually exclusive options in one track. Choosing one
+changes how the content next to it is shown, or which setting applies.
+
+## When to use
+
+- To change the unit or view of the same data: 일 / 주 / 월, chart / table.
+- To filter one list by a small, fixed set: all models, chat models, image
+  models.
+- For a setting with a few named values that all fit on screen, such as
+  상위 설정 따름 / 허용 / 차단.
+- To switch the language of a field being edited (한국어 / English).
+
+## When not to use
+
+- To switch between different sections with their own content → `Tabs`.
+- For more than five options, or options that do not fit on one line →
+  `Select` or `Radio`.
+- For on / off → `Switch`.
+- For actions (저장, 삭제) → `Button`s. A segment holds a value; it does not
+  do something when pressed.
+- To pick several at once → `Checkbox` or `Tag` with `selected`.
+
+## Variants and what they mean
+
+SegmentedControl has one look: the selected option sits on a raised thumb in a
+`bg.subtle` track. `size` matches the height of the `Button` of the same size,
+so a control and a button line up in one row.
+
+</En>
+
+<Ko>
+
+# SegmentedControl
+
+한 트랙 안에 둘에서 다섯 개의 선택지를 나란히 두고 하나만 고르게 합니다. 하나를 고르면
+옆 내용을 보는 방식이나 적용되는 설정이 바뀝니다.
+
+## 언제 쓰나요
+
+- 같은 데이터의 단위나 보기를 바꿀 때: 일 / 주 / 월, 차트 / 표.
+- 적고 정해진 기준으로 목록 하나를 거를 때: 전체 모델, 대화 모델, 이미지 모델.
+- 이름 붙은 값 몇 개가 화면에 다 들어가는 설정: 상위 설정 따름 / 허용 / 차단.
+- 편집 중인 입력란의 언어를 바꿀 때(한국어 / English).
+
+## 언제 쓰지 않나요
+
+- 내용이 따로 있는 서로 다른 구역을 오갈 때는 `Tabs`를 씁니다.
+- 선택지가 다섯 개보다 많거나 한 줄에 들어가지 않으면 `Select`나 `Radio`를 씁니다.
+- 켜고 끄는 것은 `Switch`를 씁니다.
+- 저장, 삭제 같은 동작은 `Button`으로 둡니다. 세그먼트는 값을 고르는 것이지 누르면 무언가를
+  하는 것이 아닙니다.
+- 여러 개를 함께 고르게 하려면 `Checkbox`나 `selected`를 쓰는 `Tag`를 씁니다.
+
+## 변형과 뜻
+
+SegmentedControl의 모양은 하나입니다. `bg.subtle` 트랙 위에 선택된 칸이 떠 있는 판으로
+올라옵니다. `size`는 같은 크기의 `Button`과 높이가 같아서 한 줄에 나란히 두면 맞아떨어집니다.
+
+</Ko>
+
+<ArgTypes of={SegmentedControlStories} include={['options', 'value', 'defaultValue', 'onSelect', 'size']} />
+
+<En>
+
+Heights come from the shared control scale (`controlSizes`), so they are
+always the `Button` height of the same size: px below at the 14px root, and in
+brackets inside a 16px `ScaledContext` (FactChat's `ReadingScale`).
+
+| `size` | Height | Next to |
+| --- | --- | --- |
+| `xs` | 28px (28px) | A `Button size="xs"`, a dense field header |
+| `sm` | 31.5px (36px) | Settings rows and filters in admin tables |
+| `md` (default) | 35px (40px) | Page-level view switches |
+| `lg` | 38.5px (44px) | A `Button size="lg"` |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+높이는 공통 컨트롤 스케일(`controlSizes`)에서 오므로 언제나 같은 크기 `Button`의 높이와 같습니다.
+아래 값은 14px 루트 기준이고, 괄호 안은 16px `ScaledContext`(FactChat `ReadingScale`) 안의 값입니다.
+
+| `size` | 높이 | 함께 두는 것 |
+| --- | --- | --- |
+| `xs` | 28px (28px) | `Button size="xs"`, 촘촘한 입력란 머리 |
+| `sm` | 31.5px (36px) | 관리 화면 표의 설정 줄과 필터 |
+| `md` (기본) | 35px (40px) | 페이지 전체의 보기 전환 |
+| `lg` | 38.5px (44px) | `Button size="lg"` |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SegmentedControlStories.DoChangeTheView} />
+<Verdict
+  kind="do"
+  en="Use it to change the unit of the data beside it, and name the group with aria-label ('집계 단위')."
+  ko="옆 데이터의 단위를 바꾸는 데 쓰고, 묶음에 aria-label('집계 단위')로 이름을 붙입니다."
+/>
+
+<Canvas of={SegmentedControlStories.DontSectionsAsSegments} />
+<Verdict
+  kind="dont"
+  en="Use it to switch between unrelated sections. That is Tabs: it gives each section a panel and the tab roles."
+  ko="서로 다른 구역을 오가는 데 쓰지 마세요. 그것은 Tabs의 일입니다. Tabs는 구역마다 패널과 탭 역할을 줍니다."
+/>
+
+<En>
+
+## Content
+
+- One or two words per option, nouns or short adjectives. No full stop.
+- Keep options parallel: 일 / 주 / 월, not 일별 / 이번 주 / 월.
+- Keep the order fixed across screens. When the same choice appears in several
+  places, users find it by position.
+
+## Accessibility
+
+What SegmentedControl does for you:
+
+- It is a radio group: the root is `role="radiogroup"` and each option is a
+  radio with a hidden native input, so `Tab` reaches the group and the arrow
+  keys change the selection (WCAG 2.1.1, 4.1.2).
+- The selected option is shown by the raised thumb and by a heavier, darker
+  label, not by colour alone (WCAG 1.4.1). The bold width is reserved in
+  advance, so the labels do not shift when the selection moves.
+- A hairline ring keeps the track visible on any page colour.
+
+What you still have to do:
+
+- **Name the group.** Pass `aria-label` (or `aria-labelledby` pointing at the
+  visible label) on `SegmentedControl`. Without it, a screen reader announces
+  the options with no question.
+- Give icon-only options a text alternative inside the label.
+- A disabled option (`disabled: true` in `options`) cannot be chosen; say why
+  nearby if the reason is not obvious.
+
+## Tokens
+
+The table lists the tokens set in `SegmentedControl.tsx`. In dark mode the
+ring and the thumb's edge are translucent white, not tokens.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 선택지마다 한두 단어의 명사나 짧은 형용사를 씁니다. 마침표를 찍지 않습니다.
+- 선택지를 같은 꼴로 맞춥니다. "일별 / 이번 주 / 월"이 아니라 "일 / 주 / 월"처럼 씁니다.
+- 화면이 달라도 순서를 바꾸지 않습니다. 같은 선택이 여러 곳에 나오면 사용자는 위치로
+  찾습니다.
+
+## 접근성
+
+SegmentedControl이 알아서 하는 일
+
+- 라디오 묶음입니다. 루트는 `role="radiogroup"`이고 각 선택지는 숨은 기본 입력이 있는
+  라디오라서, `Tab`으로 묶음에 닿고 방향키로 선택을 바꿉니다(WCAG 2.1.1, 4.1.2).
+- 선택된 칸은 떠 있는 판과 더 굵고 진한 라벨로 보이며, 색만으로 알리지 않습니다
+  (WCAG 1.4.1). 굵은 글자의 너비를 미리 잡아 두므로 선택이 옮겨 가도 라벨이 흔들리지
+  않습니다.
+- 가는 테두리가 있어 어떤 페이지 색 위에서도 트랙이 보입니다.
+
+직접 챙겨야 하는 일
+
+- **묶음에 이름을 붙입니다.** `SegmentedControl`에 `aria-label`을 넘기거나, 보이는
+  라벨을 가리키는 `aria-labelledby`를 넘깁니다. 이름이 없으면 화면 낭독기는 무엇을 고르는지
+  모른 채 선택지만 읽습니다.
+- 아이콘만 있는 선택지에는 라벨 안에 대체 텍스트를 넣습니다.
+- 비활성 선택지(`options`의 `disabled: true`)는 고를 수 없습니다. 이유가 분명하지 않다면
+  가까이에 이유를 적습니다.
+
+## 토큰
+
+아래 표는 `SegmentedControl.tsx`에서 정한 토큰입니다. 다크 모드의 테두리와 판 가장자리는
+토큰이 아니라 반투명한 흰색입니다.
+
+</Ko>
+
+<Canvas of={SegmentedControlStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tabs**: different sections with their own content.
+- **Select** / **Radio**: more options, or options in a form.
+- **Switch**: on / off.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tabs**: 내용이 따로 있는 서로 다른 구역.
+- **Select** / **Radio**: 선택지가 많거나 양식 안의 선택지.
+- **Switch**: 켜기 / 끄기.
+
+</Ko>

package/src/components/SegmentedProgressBar/SegmentedProgressBar.stories.tsx

@@ -1,6 +1,8 @@
 import { Box, Flex, Text, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { ProgressSegment, SegmentedProgressBar } from './';
 
 const meta = {
@@ -274,3 +276,55 @@ export const CustomColors: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `SegmentedProgressBar.usage.mdx` with <Canvas of={…} />. Hidden
+// from the sidebar (`!dev`).
+
+export const DoCountsInText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: counts in words next to the bar',
+  render: () => (
+    <Box width="400px">
+      <SegmentedProgressBar max={100} height="8px" aria-hidden>
+        <ProgressSegment value={42} filledTrackColor="success.solid" />
+        <ProgressSegment value={3} filledTrackColor="danger.solid" />
+      </SegmentedProgressBar>
+      <Flex gap={4} mt={2} textStyle="subtext" color="fg.muted">
+        <Text>보냄 42</Text>
+        <Text color="danger.fg">실패 3</Text>
+        <Text>남음 55</Text>
+      </Flex>
+    </Box>
+  ),
+};
+
+export const DontColourOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: segments with no words",
+  render: () => (
+    <Box width="400px">
+      <SegmentedProgressBar max={100} height="8px">
+        <ProgressSegment value={42} filledTrackColor="success.solid" />
+        <ProgressSegment value={3} filledTrackColor="danger.solid" />
+      </SegmentedProgressBar>
+    </Box>
+  ),
+};
+
+/** Tokens the bar reads, from `SegmentedProgressBar.tsx` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.track', use: <T en="remainder behind the segments" ko="세그먼트 뒤의 남은 부분" /> },
+        { token: 'primary.main', use: <T en="segment fill (default)" ko="세그먼트 채움(기본)" /> },
+      ]}
+    />
+  ),
+};

package/src/components/SegmentedProgressBar/SegmentedProgressBar.types.ts

@@ -3,9 +3,11 @@ import { BoxProps } from '@chakra-ui/react';
 import { ProgressBarProps } from '../ProgressBar/ProgressBar.types';
 
 export type SegmentedProgressBarProps = BoxProps & {
+  /** The whole; each segment's width is `value / max`. */
   max: number;
 };
 
 export type ProgressSegmentProps = ProgressBarProps & {
+  /** This part's amount, in the same unit as the bar's `max`. */
   value: number;
 };

package/src/components/SegmentedProgressBar/SegmentedProgressBar.usage.mdx

@@ -0,0 +1,145 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SegmentedProgressBarStories from './SegmentedProgressBar.stories';
+
+<Meta of={SegmentedProgressBarStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SegmentedProgressBar
+
+One bar split into parts of a single whole, such as messages sent, failed and
+still to go.
+
+## When to use
+
+- A batch job with more than one outcome: sent and failed, accepted and
+  rejected.
+- A total split into two or three parts the reader compares at a glance.
+
+## When not to use
+
+- A single value against a limit → `ProgressBar`.
+- Many categories, or a share of storage or budget → `RadialProgress` with a
+  legend, or a table.
+
+## How it works
+
+- `<SegmentedProgressBar max={total}>` draws the `bg.track` remainder; each
+  `<ProgressSegment value={n} filledTrackColor="…" />` inside it takes
+  `n / max` of the width, in order.
+- `height` defaults to 16px; pass `height` for a slimmer bar.
+
+</En>
+
+<Ko>
+
+# SegmentedProgressBar
+
+보낸 메시지, 실패한 메시지, 남은 메시지처럼 하나의 전체를 이루는 부분을 막대 하나에
+나눠 보여 줍니다.
+
+## 언제 쓰나요
+
+- 결과가 둘 이상인 일괄 작업: 보냄과 실패, 승인과 거절.
+- 전체를 두세 부분으로 나눠 한눈에 비교할 때.
+
+## 언제 쓰지 않나요
+
+- 한도에 대한 값 하나는 `ProgressBar`를 씁니다.
+- 분류가 많거나 저장 공간, 예산의 비율이라면 범례를 붙인 `RadialProgress`나 표를
+  씁니다.
+
+## 동작 방식
+
+- `<SegmentedProgressBar max={total}>`이 `bg.track` 바탕을 그리고, 그 안의
+  `<ProgressSegment value={n} filledTrackColor="…" />`가 차례대로 폭의 `n / max`만큼
+  차지합니다.
+- 높이 기본값은 16px입니다. 더 얇게 하려면 `height`를 넘깁니다.
+
+</Ko>
+
+<ArgTypes of={SegmentedProgressBarStories} include={['max', 'height']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SegmentedProgressBarStories.DoCountsInText} />
+<Verdict
+  kind="do"
+  en="Write each count next to the bar and colour the failure count's text too. Hide the bar itself from screen readers (aria-hidden) when the text says everything."
+  ko="부분별 개수를 막대 옆에 글자로 쓰고, 실패 개수는 글자에도 색을 입힙니다. 글자가 모든 정보를 전한다면 막대는 화면 낭독기에서 숨깁니다(aria-hidden)."
+/>
+
+<Canvas of={SegmentedProgressBarStories.DontColourOnly} />
+<Verdict
+  kind="dont"
+  en="Show the segments with no words. Green and red are the only way to tell them apart, and each segment is announced as a full progress bar."
+  ko="글자 없이 세그먼트만 보여 주지 마세요. 초록과 빨강 말고는 구분할 방법이 없고, 세그먼트마다 꽉 찬 진행 막대로 읽힙니다."
+/>
+
+<En>
+
+## Accessibility
+
+- **Each segment is announced as a separate, full progress bar.**
+  `ProgressSegment` is a `ProgressBar` with `max` set to its own `value`, so a
+  screen reader hears "100%" once per segment, and the container has no role
+  or name. Until that changes, put the counts in text and set `aria-hidden` on
+  the bar (WCAG 1.3.1, 4.1.2).
+- **Words, not colour alone** (WCAG 1.4.1).
+- Status colours (`success.solid`, `danger.solid`) only when the parts are
+  outcomes; other parts take `primary.main` or category tokens. Use tokens,
+  not hex.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- **세그먼트마다 따로, 꽉 찬 진행 막대로 읽힙니다.** `ProgressSegment`는 `max`를 자기
+  `value`로 정한 `ProgressBar`라서, 화면 낭독기는 세그먼트마다 "100%"라고 읽습니다.
+  바깥 요소에는 역할도 이름도 없습니다. 이 문제가 고쳐질 때까지는 개수를 글자로 쓰고
+  막대에 `aria-hidden`을 붙입니다(WCAG 1.3.1, 4.1.2).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1).
+- 부분이 작업 결과일 때만 상태색(`success.solid`, `danger.solid`)을 씁니다. 그 밖의
+  부분은 `primary.main`이나 category 토큰을 씁니다. 16진수가 아니라 토큰을 씁니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SegmentedProgressBarStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **ProgressBar**: one value against a limit.
+- **RadialProgress**: a share split into categories.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **ProgressBar**: 한도에 대한 값 하나.
+- **RadialProgress**: 분류별로 나눈 비율.
+
+</Ko>

package/src/components/Select/Combobox.tsx

@@ -1,10 +1,17 @@
 import { forwardRef } from 'react';
 import { Combobox as ChakraCombobox } from '@chakra-ui/react';
 
+import { useTranslate } from '@/hooks/useTranslate';
 import { noZoomOnFocus } from '@/theme/formControls';
 import { mergeCss } from '@/utils/mergeCss';
 
-import { contentStyles, inputStyles, itemStyles } from './Select.styles';
+import { CloseIcon } from '../Icon';
+import {
+  comboboxClearTriggerStyles,
+  contentStyles,
+  inputStyles,
+  itemStyles,
+} from './Select.styles';
 
 const Input = forwardRef<HTMLInputElement, ChakraCombobox.InputProps>(
   function ComboboxInput({ css, ...props }, ref) {
@@ -47,10 +54,28 @@ const Item = forwardRef<HTMLDivElement, ChakraCombobox.ItemProps>(
   }
 );
 
+/** Same × as `Select.ClearTrigger`; see there. */
+const ClearTrigger = forwardRef<
+  HTMLButtonElement,
+  ChakraCombobox.ClearTriggerProps
+>(function ComboboxClearTrigger({ css, children, ...props }, ref) {
+  const translate = useTranslate();
+  return (
+    <ChakraCombobox.ClearTrigger
+      ref={ref}
+      aria-label={translate('clear_selection') as string}
+      {...props}
+      css={mergeCss(comboboxClearTriggerStyles, css)}
+    >
+      {children ?? <CloseIcon aria-hidden />}
+    </ChakraCombobox.ClearTrigger>
+  );
+});
+
 /**
  * Compound Combobox primitives — Chakra's `Combobox` namespace with the
  * Logician design-system styling baked into the visual parts (`Input`,
- * `Content`, `Item`). Use these directly for full compositional control;
+ * `Content`, `Item`, `ClearTrigger`). Use these directly for full compositional control;
  * use `ComboboxField` for the common single-select case.
  */
 export const Combobox = {
@@ -62,7 +87,7 @@ export const Combobox = {
   Input,
   Trigger: ChakraCombobox.Trigger,
   IndicatorGroup: ChakraCombobox.IndicatorGroup,
-  ClearTrigger: ChakraCombobox.ClearTrigger,
+  ClearTrigger,
   Positioner: ChakraCombobox.Positioner,
   Content,
   Empty: ChakraCombobox.Empty,

package/src/components/Select/Select.clearTrigger.test.tsx

@@ -0,0 +1,76 @@
+import { ChakraProvider, createListCollection } from '@chakra-ui/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { system } from '../../theme';
+import { Select } from './Select';
+
+const collection = createListCollection({
+  items: [
+    { label: 'React', value: 'react' },
+    { label: 'Vue', value: 'vue' },
+  ],
+});
+
+const renderClearable = (
+  clearTrigger: React.ReactNode,
+  onValueChange = vi.fn(),
+  defaultValue = ['react']
+) =>
+  render(
+    <ChakraProvider value={system}>
+      <Select.Root
+        collection={collection}
+        defaultValue={defaultValue}
+        onValueChange={onValueChange}
+      >
+        <Select.HiddenSelect />
+        <Select.Control>
+          <Select.Trigger>
+            <Select.ValueText />
+          </Select.Trigger>
+          <Select.IndicatorGroup>
+            {clearTrigger}
+            <Select.Indicator />
+          </Select.IndicatorGroup>
+        </Select.Control>
+      </Select.Root>
+    </ChakraProvider>
+  );
+
+describe('Select.ClearTrigger', () => {
+  it('names itself in the library language instead of "Clear value"', () => {
+    renderClearable(<Select.ClearTrigger />);
+
+    const button = screen.getByRole('button', { name: '선택 지우기' });
+    expect(button.querySelector('svg')).not.toBeNull();
+    expect(screen.queryByRole('button', { name: 'Clear value' })).toBeNull();
+  });
+
+  it("keeps the caller's aria-label and still clears the value", async () => {
+    const onValueChange = vi.fn();
+    renderClearable(
+      <Select.ClearTrigger aria-label="조직 선택 지우기" />,
+      onValueChange
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '조직 선택 지우기' }));
+
+    await waitFor(() =>
+      expect(onValueChange).toHaveBeenCalledWith(
+        expect.objectContaining({ value: [] })
+      )
+    );
+  });
+
+  it('stays hidden while nothing is selected', () => {
+    renderClearable(<Select.ClearTrigger />, vi.fn(), []);
+
+    const button = document.querySelector<HTMLElement>(
+      '[data-part="clear-trigger"]'
+    );
+    expect(button).not.toBeNull();
+    expect(button).toHaveAttribute('hidden');
+    expect(getComputedStyle(button!).display).toBe('none');
+  });
+});