@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 5.0.0-alpha.0

package/src/components/Appear/Appear.stories.tsx

@@ -0,0 +1,212 @@
+import { Box, Grid, HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { Badge } from '../Badge';
+import { Button } from '../Button';
+import { Card } from '../Card';
+import { Tag } from '../Tag';
+import { Collapsible } from '../Collapsible';
+import { Menu } from '../Menu';
+import { Subtext, Text } from '../Typography';
+import { staggerProps } from '../../utils/staggerProps';
+import { Appear } from '.';
+
+/**
+ * Brings an element in on mount — a fade, plus an optional scale (a *stamp*) or
+ * vertical travel (an *arrival*).
+ *
+ * One of three entrances in this library, and they are not interchangeable —
+ * see **어느 것을 쓸까**.
+ */
+const meta = {
+  title: 'Components/Motion/Appear',
+  component: Appear,
+} satisfies Meta<typeof Appear>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [run, setRun] = useState(0);
+
+    return (
+      <Stack gap={5} align="flex-start">
+        <Button size="sm" onClick={() => setRun((r) => r + 1)}>
+          셋 동시 재생
+        </Button>
+        <HStack gap={8} align="flex-start" minH="90px">
+          {[
+            { label: '페이드', props: {} },
+            { label: '스탬프', props: { scaleFrom: 0.5 } },
+            { label: '도착', props: { rise: 10 } },
+          ].map((v) => (
+            <Stack key={v.label} gap={2} align="center" w="110px">
+              <Appear key={`${v.label}-${run}`} {...v.props}>
+                <Tag>{v.label}</Tag>
+              </Appear>
+              <Subtext fontFamily="mono" fontSize="2xs" color="fg.muted" mb={0}>
+                {v.label === '페이드'
+                  ? '기본'
+                  : v.label === '스탬프'
+                    ? 'scaleFrom=0.5'
+                    : 'rise=10'}
+              </Subtext>
+            </Stack>
+          ))}
+        </HStack>
+      </Stack>
+    );
+  },
+};
+
+/** `delayMs` is hand-set per call site — there is no list to derive it from. */
+export const Sequenced: Story = {
+  render: () => {
+    const [run, setRun] = useState(0);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button size="sm" onClick={() => setRun((r) => r + 1)}>
+          재생
+        </Button>
+        <HStack gap={3} align="center" minH="60px">
+          <Appear key={`a-${run}`} scaleFrom={0.5}>
+            <Badge variant="success">✓ 정답</Badge>
+          </Appear>
+          <Appear key={`b-${run}`} rise={6} delayMs={140}>
+            <Text fontWeight="600" mb={0}>
+              정답입니다
+            </Text>
+          </Appear>
+        </HStack>
+        <Subtext color="fg.muted" mb={0}>
+          도장이 먼저 찍히고 문구가 따라옵니다. 두 박자로 나뉘어야 하나의
+          제스처로 읽힙니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * The three entrances, played together.
+ *
+ * They overlap enough that picking the wrong one is silent, and the difference
+ * is easier to see than to read: only one of them can close, and only one of
+ * them has a rhythm.
+ */
+export const WhichOne: Story = {
+  name: '어느 것을 쓸까',
+  render: () => {
+    const [run, setRun] = useState(0);
+    const [open, setOpen] = useState(false);
+
+    return (
+      <Stack gap={6} align="flex-start" maxW="720px">
+        <HStack gap={2}>
+          <Button size="sm" onClick={() => setRun((r) => r + 1)}>
+            셋 동시 재생
+          </Button>
+          <Button
+            size="sm"
+            variant="secondary"
+            onClick={() => setOpen((v) => !v)}
+          >
+            {open ? '닫기' : '열기'} — presence만 가능
+          </Button>
+        </HStack>
+
+        <Grid
+          templateColumns={{ base: '1fr', md: 'repeat(3, 1fr)' }}
+          gap={6}
+          w="100%"
+          alignItems="start"
+        >
+          {/* presence — 유일하게 닫힐 수 있는 것 */}
+          <Stack gap={2}>
+            <Text fontFamily="mono" fontSize="xs" fontWeight="700" mb={0}>
+              presence
+            </Text>
+            <Subtext fontSize="2xs" color="fg.muted" mb={0}>
+              두 상태를 다 가진 파트. <b>나갈 때도 애니메이션됩니다.</b>
+            </Subtext>
+            <Menu>
+              <Menu.Trigger asChild>
+                <Button size="xs" variant="secondary">
+                  메뉴 열기
+                </Button>
+              </Menu.Trigger>
+              <Menu.List>
+                <Menu.Item value="a">이름 바꾸기</Menu.Item>
+                <Menu.Item value="b">삭제</Menu.Item>
+              </Menu.List>
+            </Menu>
+            <Collapsible.Root open={open}>
+              <Collapsible.Content>
+                <Box
+                  px={3}
+                  py={2}
+                  borderRadius="md"
+                  bg="bg.subtle"
+                  fontSize="xs"
+                >
+                  닫기를 눌러 보세요
+                </Box>
+              </Collapsible.Content>
+            </Collapsible.Root>
+          </Stack>
+
+          {/* stagger — 리듬이 요점 */}
+          <Stack gap={2}>
+            <Text fontFamily="mono" fontSize="xs" fontWeight="700" mb={0}>
+              stagger
+            </Text>
+            <Subtext fontSize="2xs" color="fg.muted" mb={0}>
+              한 목록. index가 곧 <b>리듬</b>입니다.
+            </Subtext>
+            <Stack key={run} gap="2px">
+              {['첫째 줄', '둘째 줄', '셋째 줄', '넷째 줄'].map((t, i) => (
+                <Tag key={t} {...staggerProps(i)}>
+                  {t}
+                </Tag>
+              ))}
+            </Stack>
+          </Stack>
+
+          {/* Appear — 혼자 한 번 */}
+          <Stack gap={2}>
+            <Text fontFamily="mono" fontSize="xs" fontWeight="700" mb={0}>
+              Appear
+            </Text>
+            <Subtext fontSize="2xs" color="fg.muted" mb={0}>
+              혼자 한 번. 지연을 <b>손으로</b> 정합니다.
+            </Subtext>
+            <HStack gap={2} align="center" minH="44px">
+              <Appear key={`a-${run}`} scaleFrom={0.5}>
+                <Badge variant="success">✓</Badge>
+              </Appear>
+              <Appear key={`b-${run}`} rise={6} delayMs={140}>
+                <Text fontSize="sm" fontWeight="600" mb={0}>
+                  정답입니다
+                </Text>
+              </Appear>
+            </HStack>
+          </Stack>
+        </Grid>
+
+        <Subtext color="fg.muted" mb={0}>
+          <b>
+            닫힐 수 있으면 presence, 같이 도착하는 형제가 있으면 stagger, 아니면
+            Appear.
+          </b>{' '}
+          「열기/닫기」를 눌러 보면 왼쪽만 반응합니다 — <code>Appear</code>는
+          나가지 않습니다. CSS는 DOM에서 제거되는 요소를 애니메이션할 수 없고,
+          그 자리를 메우는 게 presence입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};

package/src/components/Appear/Appear.styles.ts

@@ -0,0 +1,28 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * A mount entrance.
+ *
+ * `overshoot`, and that is the whole reason this is not just a fade: an entrance
+ * that settles slightly past its resting state reads as something *landing*,
+ * which is what a stamp is. On `standard` the same scale reads as a rendering
+ * hiccup — the curve is doing more work here than the amplitude.
+ *
+ * `motion.base`, the default for anything arriving.
+ *
+ * Under reduced motion the fade stays and the movement goes. The element still
+ * has to become visible — it was not there a moment ago — but neither the scale
+ * nor the travel carries information, so both are dropped by resetting their
+ * custom properties to identity rather than by killing the animation.
+ */
+export const appearIn: SystemStyleObject = {
+  animationName: 'appear-in',
+  animationDuration: 'motion.base',
+  animationTimingFunction: 'overshoot',
+  animationFillMode: 'both',
+  _motionReduce: {
+    '--appear-scale': '1',
+    '--appear-rise': '0px',
+    animationTimingFunction: 'standard',
+  },
+};

package/src/components/Appear/Appear.tsx

@@ -0,0 +1,85 @@
+import { ForwardedRef, forwardRef } from 'react';
+import { Box } from '@chakra-ui/react';
+
+import { mergeCss } from '@/utils/mergeCss';
+
+import { appearIn } from './Appear.styles';
+import { AppearProps } from './Appear.types';
+
+/**
+ * Brings an element in on mount — a fade, plus an optional scale (a *stamp*
+ * landing on something) or vertical travel (content *arriving*).
+ *
+ * ## Which of the three entrances this is
+ *
+ * The library has three, and they are not interchangeable:
+ *
+ * - `animationStyle="presence"` — a part that **has both states**. Menus,
+ *   popovers, modals: the node stays mounted and Chakra flips `_open` /
+ *   `_closed`, so it can animate *out* as well as in.
+ * - `staggerProps(index)` — items of **one list**, where the index is the
+ *   cadence and the whole point is the rhythm between siblings.
+ * - `Appear` — a **single element entering once**, on its own schedule, usually
+ *   as a response to something the reader just did. The delay is hand-set per
+ *   call site because there is no list to derive it from.
+ *
+ * The rule of thumb: if the element can close, use `presence`; if it has
+ * siblings arriving with it, use `stagger`; otherwise this.
+ *
+ * ## What it does not do
+ *
+ * It does not animate out. CSS cannot animate an element that is being removed
+ * from the DOM, which is exactly the gap `presence` fills by keeping the node
+ * mounted. FactChat's version accepts an `exit` too, but only inside an
+ * `AnimatePresence` ancestor — standalone it is a no-op there as well, so
+ * nothing that actually ran is lost in the port.
+ *
+ * ## What it puts in the DOM
+ *
+ * **One `div` around `children`**, and layout props land on that wrapper rather
+ * than on the child. Usually the same result — but the child is no longer a
+ * *direct* child of what surrounds it, so animate the inner element instead of
+ * wrapping when the parent needs its children directly: a `<tr>` needs `<td>`s,
+ * and Ark parts (`Menu.List`, `Tree`) walk their own children for focus and
+ * typeahead.
+ *
+ * ```tsx
+ * <Appear scaleFrom={0.5}>✓</Appear>
+ * <Appear rise={6} delayMs={120}>정답입니다</Appear>
+ * ```
+ */
+export const Appear = forwardRef(
+  (
+    {
+      scaleFrom,
+      rise,
+      delayMs,
+      durationMs,
+      children,
+      css,
+      ...rest
+    }: AppearProps,
+    ref?: ForwardedRef<HTMLDivElement>
+  ) => (
+    <Box
+      ref={ref}
+      {...rest}
+      css={mergeCss(
+        appearIn,
+        // Omitted props leave the keyframe's identity defaults in place, so one
+        // keyframe serves a plain fade, a stamp, an arrival, or all three.
+        scaleFrom === undefined ? undefined : { '--appear-scale': scaleFrom },
+        rise === undefined ? undefined : { '--appear-rise': `${rise}px` },
+        delayMs === undefined ? undefined : { animationDelay: `${delayMs}ms` },
+        durationMs === undefined
+          ? undefined
+          : { animationDuration: `${durationMs}ms` },
+        css
+      )}
+    >
+      {children}
+    </Box>
+  )
+);
+
+Appear.displayName = 'Appear';

package/src/components/Appear/Appear.types.ts

@@ -0,0 +1,18 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export interface AppearProps extends Omit<BoxProps, 'scale' | 'translate'> {
+  /**
+   * Scale to grow from — for a **stamp**: a mark that lands on something, like a
+   * ✓ on a correct answer or a reward medallion. Omit for a plain fade.
+   */
+  scaleFrom?: number;
+  /**
+   * Vertical travel in px — for content **arriving**: a row, a card, a banner.
+   * Positive values rise from below.
+   */
+  rise?: number;
+  /** Delay before it appears. */
+  delayMs?: number;
+  /** Defaults to `motion.base` (300ms). */
+  durationMs?: number;
+}

package/src/components/Appear/index.ts

@@ -0,0 +1,2 @@
+export { Appear } from './Appear';
+export type { AppearProps } from './Appear.types';

package/src/components/Avatar/Avatar.hue.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { SYSTEM_HUE_NAMES } from '@/theme/colors';
+
+import { avatarFallbackColors, hueForName } from './Avatar';
+
+describe('hueForName', () => {
+  it('is stable for the same name', () => {
+    expect(hueForName('Jaeho Shin')).toBe(hueForName('Jaeho Shin'));
+    expect(hueForName('정빈')).toBe(hueForName('정빈'));
+  });
+
+  it('only ever returns a declared system hue', () => {
+    for (const name of ['A', 'Sean Park', '김민재', 'z'.repeat(50)]) {
+      expect(SYSTEM_HUE_NAMES).toContain(hueForName(name));
+    }
+  });
+
+  it('has no hue for an empty/undefined name', () => {
+    expect(hueForName(undefined)).toBeUndefined();
+    expect(hueForName('')).toBeUndefined();
+  });
+
+  it('a nameless avatar falls back to the neutral pair, not red', () => {
+    // 4.x/early 5.0 picked SYSTEM_HUE_NAMES[0] — red — for every placeholder
+    // avatar, which reads as an error state.
+    for (const name of [undefined, '']) {
+      expect(avatarFallbackColors(name)).toEqual({
+        bg: 'bg.muted',
+        color: 'secondary.fgStrong',
+      });
+    }
+  });
+
+  it('a named avatar and an explicit colorHue still get their hue', () => {
+    const hue = hueForName('Sean Park');
+    expect(avatarFallbackColors('Sean Park')).toEqual({
+      bg: `category.${hue}.surface`,
+      color: `category.${hue}.fg`,
+    });
+    expect(avatarFallbackColors(undefined, 'blue')).toEqual({
+      bg: 'category.blue.surface',
+      color: 'category.blue.fg',
+    });
+  });
+
+  it('spreads different names across more than one hue', () => {
+    const names = [
+      'Jaeho Shin',
+      'Jeongbin Kim',
+      'Sean Park',
+      'Kunyoung Park',
+      'Namkyung Jo',
+      'Taehoon Kim',
+      'Minjae Kim',
+      'Hyungjoon Yang',
+      'Hyunwoo Kim',
+      'Joonpyo Lee',
+      'Seungwook Kim',
+      'WonJoon Shin',
+    ];
+    const hues = new Set(names.map(hueForName));
+    // Not a cryptographic hash — just enough spread that the wheel is
+    // visibly in use rather than every name landing on one hue.
+    expect(hues.size).toBeGreaterThan(1);
+  });
+});

package/src/components/Avatar/Avatar.stories.tsx

@@ -1,6 +1,8 @@
 import { Box, Flex, VStack, HStack, Text } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { SYSTEM_HUE_NAMES } from '@/theme/colors';
+
 import { Avatar } from '.';
 
 const meta = {
@@ -50,13 +52,13 @@ export const Sizes: Story = {
       <VStack gap={8} align="stretch">
         {/* Sizes with name fallback */}
         <Box>
-          <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+          <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
             Sizes with Name Fallback
           </Text>
           <Flex gap={4} wrap="wrap" align="center">
             {sizes.map((size) => (
               <VStack key={size} gap={2} align="center">
-                <Text fontSize="sm" color="gray.600" fontWeight="medium">
+                <Text fontSize="sm" color="fg.muted" fontWeight="medium">
                   {size}
                 </Text>
                 <Avatar name="John Doe" size={size} />
@@ -67,13 +69,13 @@ export const Sizes: Story = {
 
         {/* Sizes with image */}
         <Box>
-          <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+          <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
             Sizes with Image
           </Text>
           <Flex gap={4} wrap="wrap" align="center">
             {sizes.map((size) => (
               <VStack key={size} gap={2} align="center">
-                <Text fontSize="sm" color="gray.600" fontWeight="medium">
+                <Text fontSize="sm" color="fg.muted" fontWeight="medium">
                   {size}
                 </Text>
                 <Avatar
@@ -88,7 +90,7 @@ export const Sizes: Story = {
 
         {/* Sizes comparison */}
         <Box>
-          <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+          <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
             Size Comparison
           </Text>
           <HStack gap={4} align="flex-end">
@@ -99,7 +101,7 @@ export const Sizes: Story = {
                   src="https://i.pravatar.cc/150?img=2"
                   size={size}
                 />
-                <Text fontSize="xs" color="gray.600">
+                <Text fontSize="xs" color="fg.muted">
                   {size}
                 </Text>
               </VStack>
@@ -120,7 +122,7 @@ export const WithImage: Story = {
     <VStack gap={8} align="stretch">
       {/* Regular image */}
       <Box>
-        <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+        <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
           Regular Image
         </Text>
         <HStack gap={4}>
@@ -143,7 +145,7 @@ export const WithImage: Story = {
       </Box>
       {/* Custom background override */}
       <Box>
-        <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+        <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
           Custom Background (bg prop)
         </Text>
         <HStack gap={4}>
@@ -154,7 +156,7 @@ export const WithImage: Story = {
               size="lg"
               bg="white"
             />
-            <Text fontSize="xs" color="gray.600">
+            <Text fontSize="xs" color="fg.muted">
               bg="white"
             </Text>
           </VStack>
@@ -163,10 +165,10 @@ export const WithImage: Story = {
               name="React"
               src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg"
               size="lg"
-              bg="blue.100"
+              bg="category.blue.surface"
             />
-            <Text fontSize="xs" color="gray.600">
-              bg="blue.100"
+            <Text fontSize="xs" color="fg.muted">
+              bg="category.blue.surface"
             </Text>
           </VStack>
         </HStack>
@@ -202,7 +204,7 @@ export const Group: Story = {
     <VStack gap={8} align="stretch">
       {/* Small group */}
       <Box>
-        <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+        <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
           Small Group (md size)
         </Text>
         <HStack gap={-2}>
@@ -214,7 +216,7 @@ export const Group: Story = {
 
       {/* Large group with size variation */}
       <Box>
-        <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+        <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
           Large Group (sm size)
         </Text>
         <HStack gap={-2}>
@@ -244,7 +246,7 @@ export const Group: Story = {
 
       {/* Extra large group */}
       <Box>
-        <Text fontSize="lg" fontWeight="bold" mb={4} color="gray.700">
+        <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
           Extra Large Group (lg size)
         </Text>
         <HStack gap={-3}>
@@ -276,31 +278,31 @@ export const Group: Story = {
 export const Initials: Story = {
   render: () => (
     <VStack gap={4} align="stretch">
-      <Text fontSize="lg" fontWeight="bold" mb={2} color="gray.700">
+      <Text fontSize="lg" fontWeight="bold" mb={2} color="fg.default">
         Different Name Formats
       </Text>
       <Flex gap={4} wrap="wrap">
         <VStack gap={1}>
           <Avatar name="John Doe" size="lg" />
-          <Text fontSize="sm" color="gray.600">
+          <Text fontSize="sm" color="fg.muted">
             John Doe
           </Text>
         </VStack>
         <VStack gap={1}>
           <Avatar name="Jane" size="lg" />
-          <Text fontSize="sm" color="gray.600">
+          <Text fontSize="sm" color="fg.muted">
             Jane
           </Text>
         </VStack>
         <VStack gap={1}>
           <Avatar name="A B C" size="lg" />
-          <Text fontSize="sm" color="gray.600">
+          <Text fontSize="sm" color="fg.muted">
             A B C
           </Text>
         </VStack>
         <VStack gap={1}>
           <Avatar name="김철수" size="lg" />
-          <Text fontSize="sm" color="gray.600">
+          <Text fontSize="sm" color="fg.muted">
             김철수
           </Text>
         </VStack>
@@ -328,7 +330,7 @@ export const SizeMatrix: Story = {
           <Box w="120px" />
           {sizes.map((size) => (
             <Box key={size} w="80px" textAlign="center">
-              <Text fontWeight="bold" color="gray.600">
+              <Text fontWeight="bold" color="fg.muted">
                 {size}
               </Text>
             </Box>
@@ -339,7 +341,7 @@ export const SizeMatrix: Story = {
         {users.map((user, idx) => (
           <HStack key={idx} gap={4} align="center">
             <Box w="120px">
-              <Text fontWeight="medium" color="gray.600">
+              <Text fontWeight="medium" color="fg.muted">
                 {user.name}
               </Text>
             </Box>
@@ -354,7 +356,7 @@ export const SizeMatrix: Story = {
         {/* Fallback row */}
         <HStack gap={4} align="center">
           <Box w="120px">
-            <Text fontWeight="medium" color="gray.600">
+            <Text fontWeight="medium" color="fg.muted">
               Fallback
             </Text>
           </Box>
@@ -368,3 +370,57 @@ export const SizeMatrix: Story = {
     );
   },
 };
+
+/**
+ * No image, no `src` that loads — the fallback initials tint by a stable hash
+ * of `name` over the 12 `category.*` hues, so the same person reads as the
+ * same colour everywhere and different people spread across the wheel
+ * instead of all landing on one colour.
+ */
+export const FallbackHues: Story = {
+  render: () => {
+    const names = [
+      'Jaeho Shin',
+      'Jeongbin Kim',
+      'Sean Park',
+      'Kunyoung Park',
+      'Namkyung Jo',
+      'Taehoon Kim',
+      'Minjae Kim',
+      'Hyungjoon Yang',
+      'Hyunwoo Kim',
+      'Joonpyo Lee',
+      'Seungwook Kim',
+      'WonJoon Shin',
+    ];
+
+    return (
+      <Flex gap={4} wrap="wrap">
+        {names.map((name) => (
+          <VStack key={name} gap={2} align="center">
+            <Avatar name={name} size="lg" />
+            <Text fontSize="xs" color="fg.muted">
+              {name}
+            </Text>
+          </VStack>
+        ))}
+      </Flex>
+    );
+  },
+};
+
+/** `colorHue` overrides the hashed hue when a caller needs a specific one. */
+export const ExplicitHue: Story = {
+  render: () => (
+    <Flex gap={4} wrap="wrap">
+      {SYSTEM_HUE_NAMES.map((hue) => (
+        <VStack key={hue} gap={2} align="center">
+          <Avatar name="Same Name" colorHue={hue} size="lg" />
+          <Text fontSize="xs" color="fg.muted">
+            {hue}
+          </Text>
+        </VStack>
+      ))}
+    </Flex>
+  ),
+};