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

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');
+  });
+});

package/src/components/Select/Select.stories.tsx

@@ -9,11 +9,22 @@ import {
   Stack,
   Text,
 } from '@chakra-ui/react';
-import { Meta } from '@storybook/react';
+import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Badge } from '../Badge';
+import { Radio, RadioGroup } from '../Radio';
 import { IoCall, IoChatbubbleEllipses, IoIosMail } from '../Icon';
+import { ComboboxField } from './ComboboxField';
 import { Select } from './Select';
+import {
+  contentStyles,
+  indicatorStyles,
+  itemStyles,
+  selectClearTriggerStyles,
+  triggerStyles,
+} from './Select.styles';
 import { SelectField } from './SelectField';
 
 const meta = {
@@ -188,6 +199,76 @@ export const MultiSelect = () => (
   </Box>
 );
 
+/**
+ * An optional field the member can empty again. `ClearTrigger` goes before
+ * the chevron and shows only while something is selected. It draws its own
+ * icon and is named 「선택 지우기」 in the provider's language; pass
+ * `aria-label` to say what is cleared. A divider separates it from the
+ * chevron, and a long value ends in an ellipsis before it. On a touch screen
+ * its hit area widens to 44px toward the value, at the field's own height.
+ */
+const longValueCollection = createListCollection({
+  items: [
+    {
+      label: 'Engineering / Platform / Developer Experience',
+      value: 'dx',
+    },
+    { label: 'Design', value: 'design' },
+  ],
+});
+
+export const Clearable = () => (
+  <Stack maxW="320px" gap={4}>
+    <Box maxW="180px">
+      <Select.Root collection={longValueCollection} defaultValue={['dx']}>
+        <Select.HiddenSelect />
+        <Select.Label>Team (180px)</Select.Label>
+        <Select.Control>
+          <Select.Trigger>
+            <Select.ValueText placeholder="Select a team" />
+          </Select.Trigger>
+          <Select.IndicatorGroup>
+            <Select.ClearTrigger />
+            <Select.Indicator />
+          </Select.IndicatorGroup>
+        </Select.Control>
+      </Select.Root>
+    </Box>
+    {(['xs', 'sm', 'md', 'lg'] as const).map((size) => (
+      <Select.Root
+        key={size}
+        size={size}
+        collection={frameworkCollection}
+        defaultValue={['react']}
+      >
+        <Select.HiddenSelect />
+        <Select.Label>{`Framework (${size})`}</Select.Label>
+        <Select.Control>
+          <Select.Trigger>
+            <Select.ValueText placeholder="Select a framework" />
+          </Select.Trigger>
+          <Select.IndicatorGroup>
+            <Select.ClearTrigger />
+            <Select.Indicator />
+          </Select.IndicatorGroup>
+        </Select.Control>
+        <Portal>
+          <Select.Positioner>
+            <Select.Content>
+              {frameworkCollection.items.map((item) => (
+                <Select.Item item={item} key={item.value}>
+                  <Select.ItemText>{item.label}</Select.ItemText>
+                  <Select.ItemIndicator />
+                </Select.Item>
+              ))}
+            </Select.Content>
+          </Select.Positioner>
+        </Portal>
+      </Select.Root>
+    ))}
+  </Stack>
+);
+
 /* -------------------------------------------------------------------------
  * Custom children
  *
@@ -771,3 +852,211 @@ export const WithOpenChange = () => {
     </HStack>
   );
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Select.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+type UsageStory = StoryObj;
+
+const LANGUAGES = [
+  { label: '한국어', value: 'ko' },
+  { label: 'English', value: 'en' },
+  { label: '日本語', value: 'ja' },
+];
+
+const GROUPS = [
+  '경영지원팀',
+  '고객성공팀',
+  '데이터팀',
+  '디자인팀',
+  '마케팅팀',
+  '백엔드팀',
+  '법무팀',
+  '보안팀',
+  '사업개발팀',
+  '세일즈팀',
+  '인사팀',
+  '재무팀',
+  '프론트엔드팀',
+].map((name) => ({ label: name, value: name }));
+
+export const DoLabelled: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a visible label',
+  render: () => (
+    <Box maxW="320px">
+      <SelectField label="답변 언어" options={LANGUAGES} defaultValue="ko" />
+    </Box>
+  ),
+};
+
+export const DontNameless: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: no label, ariaLabel or placeholder",
+  render: () => (
+    <Flex maxW="480px" align="center" justify="space-between" gap={4}>
+      <Text fontWeight="semibold">답변 언어</Text>
+      <Box w="180px">
+        <SelectField options={LANGUAGES} defaultValue="ko" />
+      </Box>
+    </Flex>
+  ),
+};
+
+export const DoComboboxForLongList: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ComboboxField for a long list',
+  render: () => (
+    <Box maxW="320px">
+      <ComboboxField
+        label="그룹"
+        placeholder="그룹 이름으로 찾기"
+        options={GROUPS}
+        emptyText="일치하는 그룹이 없습니다"
+      />
+    </Box>
+  ),
+};
+
+export const DontSelectForTwo: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a dropdown for two options",
+  render: () => (
+    <Box maxW="320px">
+      <SelectField
+        label="공개 범위"
+        options={[
+          { label: '전체 공개', value: 'public' },
+          { label: '그룹만', value: 'group' },
+        ]}
+        defaultValue="public"
+      />
+    </Box>
+  ),
+};
+
+export const DoRadioForTwo: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: Radio for two visible options',
+  render: () => (
+    <Stack gap={2} maxW="320px">
+      <Text id="usage-visibility" fontWeight="semibold">
+        공개 범위
+      </Text>
+      <RadioGroup
+        defaultValue="public"
+        aria-labelledby="usage-visibility"
+        display="flex"
+        gap={4}
+      >
+        <Radio value="public">
+          <Radio.Control />
+          <Radio.Text>전체 공개</Radio.Text>
+        </Radio>
+        <Radio value="group">
+          <Radio.Control />
+          <Radio.Text>그룹만</Radio.Text>
+        </Radio>
+      </RadioGroup>
+    </Stack>
+  ),
+};
+
+/**
+ * Tokens the trigger, list and options read, taken from the style objects in
+ * `Select.styles.ts` (shared by Select and Combobox).
+ */
+export const UsageTokens: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: triggerStyles.bg,
+          use: <T en="Trigger background" ko="트리거 배경" />,
+        },
+        {
+          token: triggerStyles.color,
+          use: <T en="Selected value" ko="선택한 값" />,
+        },
+        {
+          token: triggerStyles.borderColor,
+          use: <T en="Trigger border at rest" ko="트리거 평소 테두리" />,
+        },
+        {
+          token: triggerStyles._hover.borderColor,
+          use: <T en="Border on hover" ko="마우스를 올렸을 때 테두리" />,
+        },
+        {
+          token: triggerStyles._focus.borderColor,
+          use: (
+            <T
+              en="Border and ring on focus or open"
+              ko="초점을 받거나 열렸을 때 테두리와 링"
+            />
+          ),
+        },
+        {
+          token: triggerStyles._invalid.borderColor,
+          use: <T en="Border when invalid" ko="오류 상태 테두리" />,
+        },
+        {
+          token: triggerStyles._disabled.bg,
+          use: <T en="Disabled background" ko="비활성 배경" />,
+        },
+        {
+          token: triggerStyles._disabled.color,
+          use: <T en="Disabled text" ko="비활성 글자" />,
+        },
+        {
+          token: indicatorStyles.color,
+          use: <T en="Chevron" ko="펼침 화살표" />,
+        },
+        {
+          token: selectClearTriggerStyles.color,
+          use: <T en="Clear (×) button" ko="선택 지우기(×) 버튼" />,
+        },
+        {
+          token: selectClearTriggerStyles._hover.color,
+          use: (
+            <T en="Clear button on hover" ko="마우스를 올렸을 때 지우기 버튼" />
+          ),
+        },
+        {
+          token: contentStyles.bg,
+          use: <T en="List background" ko="목록 배경" />,
+        },
+        {
+          token: contentStyles.borderColor,
+          use: <T en="List border" ko="목록 테두리" />,
+        },
+        {
+          token: itemStyles._highlighted.bg,
+          use: (
+            <T
+              en="Option under the pointer or keyboard"
+              ko="포인터나 키보드가 가리키는 항목"
+            />
+          ),
+        },
+        {
+          token: itemStyles._checked.bg,
+          use: <T en="Selected option" ko="선택된 항목" />,
+        },
+        {
+          token: itemStyles._disabled.color,
+          use: <T en="Disabled option" ko="선택할 수 없는 항목" />,
+        },
+      ]}
+    />
+  ),
+};