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

package/src/components/SeeMoreButton/SeeMoreButton.types.ts

@@ -12,7 +12,15 @@ export type SeeMoreButtonOwnProps = Omit<
   ButtonOwnProps,
   'variant' | 'isDestructive'
 > & {
+  /**
+   * How many items the list shows now. Printed as the first number of
+   * `더보기 (currentCount/maxCount)`.
+   */
   currentCount: number;
+  /**
+   * How many items there are in total. The button does not disable or hide
+   * itself when `currentCount` reaches this; the caller does.
+   */
   maxCount: number;
 };
 

package/src/components/SeeMoreButton/SeeMoreButton.usage.mdx

@@ -0,0 +1,213 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SeeMoreButtonStories from './SeeMoreButton.stories';
+
+<Meta of={SeeMoreButtonStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SeeMoreButton
+
+A full-width button at the end of a list that shows more of the same list in
+place, and says how many are shown out of how many.
+
+## When to use
+
+- A list that grows where it is when the reader asks: reviews, recommended
+  questions, search results in a dropdown. In FactChat the store's reviews,
+  recommended questions and chatbot search use it.
+- When you know the total, so the count `(3/10)` is true.
+
+## When not to use
+
+- Opening the full list on another page → a link-shaped `Button`
+  (`as="a"`, `ghost`) such as 전체 보기, usually next to the section heading.
+- Paging through a long, numbered result set → `Pagination`.
+- Expanding one block of text → `ExpandableText`, which has its own
+  더보기 / 접기.
+- Showing more attached files → `FileList` already renders its own control.
+- You do not know the total → a `subtle` or `ghost` `Button` with your own
+  label, because SeeMoreButton always prints a count.
+
+## Props
+
+SeeMoreButton has no `variant`. It always renders the `ghost` Button recipe
+with a top hairline, takes the full width of its container, and accepts
+Button's other props (`onClick`, `disabled`, `loading`, `size` …).
+
+</En>
+
+<Ko>
+
+# SeeMoreButton
+
+목록 끝에 놓는 전체 너비 버튼입니다. 같은 목록을 그 자리에서 더 보여 주고, 전체 중
+몇 개를 보여 주는지 알려 줍니다.
+
+## 언제 쓰나요
+
+- 읽는 사람이 원할 때 그 자리에서 늘어나는 목록: 리뷰, 추천 질문, 드롭다운 안의 검색
+  결과. FactChat에서는 스토어의 리뷰, 추천 질문, 챗봇 검색에 씁니다.
+- 전체 개수를 알고 있어서 `(3/10)` 같은 개수가 사실일 때.
+
+## 언제 쓰지 않나요
+
+- 다른 화면에서 전체 목록을 연다면 링크 모양의 `Button`(`as="a"`, `ghost`)을 씁니다.
+  "전체 보기"처럼 쓰고, 보통 섹션 제목 옆에 둡니다.
+- 번호가 매겨진 긴 결과를 넘겨 본다면 `Pagination`을 씁니다.
+- 글 한 덩어리를 펼친다면 더보기 / 접기가 들어 있는 `ExpandableText`를 씁니다.
+- 첨부 파일을 더 보여 준다면 `FileList`가 자체 컨트롤을 그립니다.
+- 전체 개수를 모른다면 라벨을 직접 쓰는 `subtle`이나 `ghost` `Button`을 씁니다.
+  SeeMoreButton은 언제나 개수를 함께 표시하기 때문입니다.
+
+## 속성
+
+SeeMoreButton에는 `variant`가 없습니다. 언제나 위쪽 구분선을 더한 `ghost` Button
+레시피로 그려지고, 담긴 영역의 너비를 다 차지하며, Button의 나머지 속성(`onClick`,
+`disabled`, `loading`, `size` 등)을 받습니다.
+
+</Ko>
+
+<ArgTypes of={SeeMoreButtonStories} include={['currentCount', 'maxCount']} />
+
+<En>
+
+The component does not disable or hide itself when `currentCount` reaches
+`maxCount`; that is up to you (see Do / Don't).
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+`currentCount`가 `maxCount`에 닿아도 컴포넌트가 스스로 비활성이 되거나 사라지지
+않습니다. 그 처리는 호출하는 쪽에서 합니다(아래 예시 참고).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SeeMoreButtonStories.DoGrowTheList} />
+<Verdict
+  kind="do"
+  en="Put it right under the list, let each click add items in place, and remove it once everything is shown. FactChat renders it only while there is a next page."
+  ko="목록 바로 아래에 두고, 누를 때마다 그 자리에 항목을 더하며, 모두 보여 준 뒤에는 버튼을 없앱니다. FactChat도 다음 페이지가 있을 때만 버튼을 그립니다."
+/>
+
+<Canvas of={SeeMoreButtonStories.DontNavigate} />
+<Verdict
+  kind="dont"
+  en="Use it to send the reader to a different page with all 128 reviews. It promises more of this list, here."
+  ko="리뷰 128개가 있는 다른 화면으로 보내는 데 쓰지 마세요. 이 버튼은 지금 이 목록을 이 자리에서 더 보여 주겠다는 뜻입니다."
+/>
+
+<Canvas of={SeeMoreButtonStories.DoLinkToFullPage} />
+<Verdict
+  kind="do"
+  en="To open the full list elsewhere, use a link-shaped ghost Button next to the heading."
+  ko="다른 화면에서 전체 목록을 연다면 제목 옆에 링크 모양의 ghost Button을 둡니다."
+/>
+
+<En>
+
+## Content
+
+- The label is fixed: `더보기 (currentCount/maxCount)` and a chevron.
+  Children are ignored. The text comes from the library's own `see_more`
+  string, which today always resolves to Korean, so an English screen still
+  shows 더보기.
+- Keep the numbers honest. `maxCount` is the real total; if the server only
+  tells you "there is more", use a `Button` instead.
+
+## Accessibility
+
+What SeeMoreButton does for you:
+
+- It is a Button: a native `<button>`, Tab and Enter / Space (WCAG 2.1.1), and
+  the keyboard focus ring (WCAG 2.4.7).
+- The count is part of the visible label, so the accessible name is
+  "더보기 (3/10)" and matches what is on screen (WCAG 2.5.3).
+
+What you still have to do:
+
+- **Keep the keyboard user's place.** When the last click removes the button,
+  focus would fall back to the page. Move focus to the first newly shown item
+  (WCAG 2.4.3).
+- **New items are not announced.** The component has no live region. If the
+  added items are not obvious from the focus move, announce the new count
+  yourself.
+- **Loading.** While the next page loads, pass `loading` with a
+  `loadingText` (불러오는 중) so the button cannot be pressed twice and still
+  has words. Without `loadingText` the label is hidden behind the spinner.
+
+## Tokens
+
+The table is generated from `SeeMoreButton.styles.ts` and the ghost Button
+recipe it renders.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨은 정해져 있습니다. `더보기 (currentCount/maxCount)`와 아래 화살표이며,
+  children은 무시됩니다. 문구는 라이브러리의 `see_more` 문자열에서 오는데 지금은
+  언제나 한국어로 풀리므로, 영어 화면에도 "더보기"가 나옵니다.
+- 숫자는 사실이어야 합니다. `maxCount`는 실제 전체 개수입니다. 서버가 "더 있다"는
+  것만 알려 준다면 `Button`을 씁니다.
+
+## 접근성
+
+SeeMoreButton이 알아서 하는 일
+
+- Button 그대로입니다. 기본 `<button>`이며 Tab, Enter와 Space로 다루고(WCAG 2.1.1),
+  키보드 초점 링을 그립니다(WCAG 2.4.7).
+- 개수가 보이는 라벨에 들어 있어서, 접근 가능한 이름이 화면에 보이는 그대로
+  "더보기 (3/10)"입니다(WCAG 2.5.3).
+
+직접 챙겨야 하는 일
+
+- **키보드 사용자의 위치를 지킵니다.** 마지막으로 눌렀을 때 버튼이 사라지면 초점이
+  페이지 처음으로 돌아갈 수 있습니다. 새로 나온 첫 항목으로 초점을 옮깁니다(WCAG
+  2.4.3).
+- **새 항목은 알려 주지 않습니다.** 컴포넌트에 라이브 영역이 없습니다. 초점을 옮기는
+  것만으로 새 항목이 분명하지 않다면 늘어난 개수를 직접 알립니다.
+- **불러오는 중.** 다음 페이지를 불러오는 동안 `loading`과 `loadingText`(불러오는 중)를
+  함께 주어 두 번 눌리지 않게 하고 글자도 남깁니다. `loadingText`가 없으면 라벨이
+  스피너 뒤로 숨습니다.
+
+## 토큰
+
+아래 표는 `SeeMoreButton.styles.ts`와 이 컴포넌트가 그리는 ghost Button 레시피에서
+자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={SeeMoreButtonStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Button**: a link-shaped `ghost` Button for 전체 보기, or your own label
+  when the total is unknown.
+- **Pagination**: numbered pages.
+- **ExpandableText**: 더보기 / 접기 for one block of text.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Button**: 전체 보기에 쓰는 링크 모양의 `ghost` Button, 또는 전체 개수를 모를 때
+  라벨을 직접 쓰는 버튼.
+- **Pagination**: 번호가 있는 페이지.
+- **ExpandableText**: 글 한 덩어리의 더보기 / 접기.
+
+</Ko>

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

@@ -3,6 +3,8 @@ import { Meta, StoryObj } from '@storybook/react';
 import React, { useState } from 'react';
 import { FiHome, FiSettings, FiUser } from 'react-icons/fi';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { SegmentedControl } from './SegmentedControl';
 
 const meta = {
@@ -202,3 +204,70 @@ export const WithCustomContent = {
     ],
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `SegmentedControl.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`).
+
+export const DoChangeTheView: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: change how the same data is shown',
+  render: () => (
+    <VStack align="start" gap={3}>
+      <Text fontWeight="600">크레딧 사용량</Text>
+      <SegmentedControl
+        aria-label="집계 단위"
+        size="sm"
+        defaultValue="week"
+        options={[
+          { label: '일', value: 'day' },
+          { label: '주', value: 'week' },
+          { label: '월', value: 'month' },
+        ]}
+      />
+    </VStack>
+  ),
+};
+
+export const DontSectionsAsSegments: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: switch between unrelated sections",
+  render: () => (
+    <SegmentedControl
+      defaultValue="credit"
+      options={[
+        { label: '크레딧', value: 'credit' },
+        { label: '보안', value: 'security' },
+        { label: '공지', value: 'notice' },
+        { label: '멤버', value: 'members' },
+        { label: '감사 로그', value: 'audit' },
+      ]}
+    />
+  ),
+};
+
+/** Tokens the track, thumb and labels read, as set in `SegmentedControl.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.subtle', use: <T en="Track" ko="트랙" /> },
+        {
+          token: 'border.default',
+          use: <T en="Track ring (light)" ko="트랙 테두리(라이트)" />,
+        },
+        { token: 'bg.raised', use: <T en="Selected thumb" ko="선택된 칸" /> },
+        { token: 'fg.muted', use: <T en="Label" ko="라벨" /> },
+        {
+          token: 'fg.default',
+          use: <T en="Selected label" ko="선택된 라벨" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/SegmentedControl/SegmentedControl.styles.ts

@@ -1,5 +1,11 @@
 import type { SystemStyleObject } from '@chakra-ui/react';
 
+import {
+  controlHeightVar,
+  type ControlSize,
+  controlSizes,
+} from '@/theme/controlSizes';
+
 /**
  * `travel`, but delivered through custom properties.
  *
@@ -20,3 +26,35 @@ export const indicatorTravel: SystemStyleObject = {
     '--transition-duration': 'var(--chakra-durations-motion-instant)',
   },
 };
+
+/**
+ * The root's padding in px (see `rootPadding` in SegmentedControl.tsx for
+ * why px), per size. Shared with the item-height calc so the two cannot
+ * disagree.
+ *
+ * 4px from `sm` up; 2px at `xs` / `2xs`. A fixed 4px left an `xs` item 20px
+ * tall (28 − 8) inside a 16px `ScaledContext`, shorter than its own 14px type's
+ * 21px line, and the label read squeezed against the indicator (FactChat
+ * coding-agent toolbar, 박상현 2026-11-10). At 2px the item is 24px.
+ */
+export const segmentRootPaddingPx = (size: unknown): number =>
+  size === 'xs' || size === '2xs' ? 2 : 4;
+
+/**
+ * Item height so that the OUTER height (item + 2 × root padding) equals the
+ * Button height for the same size — `controlSizes[size].height`, i.e. 28 /
+ * 31.5 / 35 / 38.5px for xs / sm / md / lg at the 14px root, and 36 / 40 / 44
+ * for sm / md / lg inside a 16px `ScaledContext`.
+ *
+ * A `calc()` on the height token rather than a smaller token: the root padding
+ * is a fixed px value while the sizes tokens are rem (em inside a
+ * ScaledContext), so no single token equals "Button height − padding" at every
+ * font size. The old one-token-smaller table (`6`/`7`/`8`/`9`) was written for
+ * a 16px rem and came out 1px taller than Button at the real 14px root.
+ */
+export const segmentItemHeight = (size: unknown): string =>
+  `calc(${controlHeightVar(
+    (typeof size === 'string' && size in controlSizes
+      ? size
+      : 'md') as ControlSize
+  )} - ${segmentRootPaddingPx(size) * 2}px)`;

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -1,30 +1,19 @@
 import { forwardRef } from 'react';
 import { SegmentGroup } from '@chakra-ui/react';
 
+import { getControlSize } from '@/theme/controlSizes';
 import { mergeCss } from '@/utils/mergeCss';
 
-import { indicatorTravel } from './SegmentedControl.styles';
+import {
+  indicatorTravel,
+  segmentItemHeight,
+  segmentRootPaddingPx,
+} from './SegmentedControl.styles';
 import {
   SegmentedControlOption,
   SegmentedControlProps,
 } from './SegmentedControl.types';
 
-// Match font sizes to the equivalent Chakra button sizes
-const fontSizeBySize: Record<string, string> = {
-  xs: 'xs',
-  sm: 'sm',
-  md: 'sm',
-  lg: 'md',
-};
-
-// Item heights so that itemHeight + 2×root-padding(p="1") equals the Button height for each size
-const itemHeightBySize: Record<string, string> = {
-  xs: '6', // 32 - 8 = 24px
-  sm: '7', // 36 - 8 = 28px
-  md: '8', // 40 - 8 = 32px
-  lg: '9', // 44 - 8 = 36px
-};
-
 export const SegmentedControl = forwardRef<
   HTMLDivElement,
   SegmentedControlProps
@@ -40,8 +29,16 @@ export const SegmentedControl = forwardRef<
     ...rest
   } = props;
 
-  const fontSize = fontSizeBySize[size as string] ?? 'sm';
-  const itemHeight = itemHeightBySize[size as string] ?? '8';
+  // Same textStyle as every other control at this size (see controlSizes):
+  // the item height is em inside a ScaledContext, so equal type is what keeps
+  // the outer height equal to Button's there too.
+  const spec = getControlSize(size);
+
+  // Root padding in px, not the `1` spacing token: that token is 0.25em, so at
+  // a 14px font it is 3.5px, and Ark positions the indicator from the item's
+  // integer offsetTop/offsetLeft (3.5 rounds to 4). The thumb then sat 0.5px
+  // low and its bottom gap was a pixel narrower than its top.
+  const rootPadding = `${segmentRootPaddingPx(size)}px`;
 
   // Normalize options to the format expected by SegmentGroup.Items
   const items = options.map((option: SegmentedControlOption) => ({
@@ -50,11 +47,14 @@ export const SegmentedControl = forwardRef<
     disabled: option.disabled,
   }));
 
-  // Use theme borderRadius token directly via CSS variable
+  // Concentric with the root: inner radius = outer radius − root padding
+  // (rootPadding), floored at 0, so the gap between the two curves stays even.
   const indicatorRadius =
     typeof borderRadius === 'string'
-      ? `var(--chakra-radii-${borderRadius})`
-      : borderRadius;
+      ? `max(0px, calc(var(--chakra-radii-${borderRadius}) - ${rootPadding}))`
+      : typeof borderRadius === 'number'
+        ? `max(0px, calc(${borderRadius}px - ${rootPadding}))`
+        : borderRadius;
 
   return (
     <SegmentGroup.Root
@@ -67,18 +67,18 @@ export const SegmentedControl = forwardRef<
         }
       }}
       size={size}
-      // Track is bg.subtle (gray.50 light) and the selected indicator rides on
-      // `bg.raised` — a raised neutral surface that resolves white in light and
-      // the lightest neutral (gray.1100) in dark, so the thumb reads as lifted
-      // above the track in both modes (`bg.surface` could not: its dark value is
-      // darker than the track). The indicator also gains a shadow: an md drop
-      // shadow in light, and in dark — where a drop shadow is invisible on a
+      // Track is bg.subtle and the selected indicator rides on `bg.raised` — a
+      // raised neutral surface that resolves white in light and a lighter
+      // neutral than the track in dark, so the thumb reads as lifted
+      // above the track in both modes. The indicator also gains a shadow: an xs drop
+      // shadow in light (md's 4px/8px drop filled the 4px track padding below the
+      // thumb and made it read as sagging), and in dark — where a drop shadow is invisible on a
       // dark canvas — a soft ambient shadow + a translucent-white hairline edge.
       //
       // The track itself only contrasts where the page wash is darker (light) or
       // lighter (dark) than the fill. It vanishes when the page matches the
-      // track: a `bg.sunken` list/overview page is gray.50 in light — identical
-      // to the bg.subtle track — and a `bg.surface` card is lighter than the
+      // track: a `bg.sunken` list/overview page has the same light value as
+      // the bg.subtle track — and a `bg.surface` card is lighter than the
       // track in dark. In either case the control would read as floating text,
       // so a hairline ring defines its bounds on *any* background: a neutral
       // `border.default` ring in light, a translucent-white ring in dark. (The
@@ -88,21 +88,25 @@ export const SegmentedControl = forwardRef<
       // it. `border.default` keeps the edge present but light — `border.strong`
       // reads as a heavy box for a control that normally has no outline.) Both
       // rings are box-shadows (not borders) so the matched item-height math is
-      // preserved.
+      // preserved, and both are inset: an outer ring sits 1px outside the box,
+      // so any `overflow` ancestor flush with the control (a horizontal scroll
+      // row) clipped its straight edges and left only the rounded corners.
+      // Inset, it is drawn inside the root padding, where the indicator never
+      // reaches.
       bg="bg.subtle"
-      p="1"
+      p={rootPadding}
       borderRadius={borderRadius}
       w="fit-content"
       {...rest}
       css={mergeCss(
         {
           '--segment-indicator-bg': `var(--chakra-colors-bg-raised)`,
-          '--segment-indicator-shadow': `var(--chakra-shadows-md)`,
-          boxShadow: '0 0 0 1px var(--chakra-colors-border-default)',
+          '--segment-indicator-shadow': `var(--chakra-shadows-xs)`,
+          boxShadow: 'inset 0 0 0 1px var(--chakra-colors-border-default)',
           '.dark &': {
             '--segment-indicator-shadow':
               '0 1px 2px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(255, 255, 255, 0.08)',
-            boxShadow: '0 0 0 1px rgba(255, 255, 255, 0.12)',
+            boxShadow: 'inset 0 0 0 1px rgba(255, 255, 255, 0.12)',
           },
         },
         css
@@ -121,14 +125,16 @@ export const SegmentedControl = forwardRef<
           disabled={item.disabled}
           cursor={item.disabled ? 'not-allowed' : 'pointer'}
           flex="1"
-          height={itemHeight}
+          height={segmentItemHeight(size)}
+          textStyle={spec.textStyle}
+          px={spec.actionPaddingX}
+          gap={spec.gap}
           _hover={{ bg: 'transparent' }}
         >
           <SegmentGroup.ItemText
             data-text={typeof item.label === 'string' ? item.label : undefined}
             color="fg.muted"
             fontWeight="500"
-            fontSize={fontSize}
             whiteSpace="nowrap"
             display="inline-flex"
             flexDirection="column"