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

package/dist/utils/mergeCss.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { merge } from 'lodash';
+import merge from 'lodash/merge';
 
 const mergeCss = (...styles) => styles.reduce((acc, style) => {
     if (style && typeof style === 'object') {

package/dist/utils/staggerProps.d.ts

@@ -0,0 +1,52 @@
+/** What `staggerProps` hands back — spreadable onto any Chakra element. */
+export interface StaggerProps {
+    animationStyle: 'stagger';
+    style: Record<string, string | number>;
+}
+/**
+ * Makes one list item arrive `index` beats after the first.
+ *
+ * ```tsx
+ * {options.map((option, i) => (
+ *   <Select.Item key={option.value} item={option} {...staggerProps(i)}>
+ * ))}
+ * ```
+ *
+ * A function rather than a `<Stagger>` wrapper. A wrapper has to render
+ * something to hold the index, and an extra node inside a `Menu.Content` or a
+ * `Select.Content` is not free: Ark walks those children to build its typeahead
+ * and roving-focus collections, and a grid or flex list would gain a layout box
+ * between the container and every row. This adds no DOM at all, and it composes
+ * with a list that is already being mapped rather than asking for the list to be
+ * restructured around it.
+ *
+ * The index rides an inline custom property rather than the `css` prop on
+ * purpose: `css` would compile one class per index and grow the stylesheet with
+ * the length of the longest list ever rendered, while the *only* thing that
+ * varies per item is this one number. Everything else — the keyframe, the
+ * duration, the curve, the cap — lives in the `stagger` preset, which is one
+ * class shared by every item on the page.
+ *
+ * Where **not** to use it, and why the list is short: stagger costs the reader
+ * time in exchange for rhythm, so it is worth it only where the list is short,
+ * arrives once, and is looked at as a whole. `Masonry` and `Table` are the
+ * explicit exclusions — both are long, both are candidates for virtualization
+ * (where "index" means position in a window that scrolls, so items would
+ * re-stagger as they scroll into view), and a sortable table re-orders its rows
+ * on click, which would deal the whole grid out again on every header press.
+ *
+ * @param index - The item's position in its list, from 0.
+ * @returns Props to spread onto the item. Merge `style` by hand if the call
+ *   site already sets one.
+ */
+export declare const staggerProps: (index: number) => StaggerProps;
+/**
+ * The delay `staggerProps(index)` resolves to, in milliseconds.
+ *
+ * Exists for the two callers that cannot read a CSS variable — a test asserting
+ * the cap holds, and JS animation tech sequencing alongside a staggered list.
+ * It has to mirror the `calc()` in the `stagger` preset exactly, which is why
+ * both read the same two constants.
+ */
+export declare const staggerDelayMs: (index: number) => number;
+//# sourceMappingURL=staggerProps.d.ts.map

package/dist/utils/staggerProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staggerProps.d.ts","sourceRoot":"","sources":["../../src/utils/staggerProps.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,SAAS,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,YAM3C,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAEf,CAAC"}

package/dist/utils/staggerProps.js

@@ -0,0 +1,62 @@
+"use client";
+'use strict';
+
+var motion = require('../theme/motion.js');
+
+/**
+ * Makes one list item arrive `index` beats after the first.
+ *
+ * ```tsx
+ * {options.map((option, i) => (
+ *   <Select.Item key={option.value} item={option} {...staggerProps(i)}>
+ * ))}
+ * ```
+ *
+ * A function rather than a `<Stagger>` wrapper. A wrapper has to render
+ * something to hold the index, and an extra node inside a `Menu.Content` or a
+ * `Select.Content` is not free: Ark walks those children to build its typeahead
+ * and roving-focus collections, and a grid or flex list would gain a layout box
+ * between the container and every row. This adds no DOM at all, and it composes
+ * with a list that is already being mapped rather than asking for the list to be
+ * restructured around it.
+ *
+ * The index rides an inline custom property rather than the `css` prop on
+ * purpose: `css` would compile one class per index and grow the stylesheet with
+ * the length of the longest list ever rendered, while the *only* thing that
+ * varies per item is this one number. Everything else — the keyframe, the
+ * duration, the curve, the cap — lives in the `stagger` preset, which is one
+ * class shared by every item on the page.
+ *
+ * Where **not** to use it, and why the list is short: stagger costs the reader
+ * time in exchange for rhythm, so it is worth it only where the list is short,
+ * arrives once, and is looked at as a whole. `Masonry` and `Table` are the
+ * explicit exclusions — both are long, both are candidates for virtualization
+ * (where "index" means position in a window that scrolls, so items would
+ * re-stagger as they scroll into view), and a sortable table re-orders its rows
+ * on click, which would deal the whole grid out again on every header press.
+ *
+ * @param index - The item's position in its list, from 0.
+ * @returns Props to spread onto the item. Merge `style` by hand if the call
+ *   site already sets one.
+ */
+const staggerProps = (index) => ({
+    animationStyle: 'stagger',
+    // Not clamped here even though the preset's `min()` makes it redundant in
+    // CSS: an out-of-range value passed straight through is what makes a wrong
+    // index visible in the DOM instead of silently flattened.
+    style: { '--stagger-index': index },
+});
+/**
+ * The delay `staggerProps(index)` resolves to, in milliseconds.
+ *
+ * Exists for the two callers that cannot read a CSS variable — a test asserting
+ * the cap holds, and JS animation tech sequencing alongside a staggered list.
+ * It has to mirror the `calc()` in the `stagger` preset exactly, which is why
+ * both read the same two constants.
+ */
+const staggerDelayMs = (index) => Math.min(Math.max(index, 0), motion.MOTION_STAGGER_MAX) *
+    motion.MOTION_DURATION_MS.staggerStep;
+
+exports.staggerDelayMs = staggerDelayMs;
+exports.staggerProps = staggerProps;
+//# sourceMappingURL=staggerProps.js.map

package/dist/utils/staggerProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staggerProps.js","sources":["../../src/utils/staggerProps.ts"],"sourcesContent":[null],"names":["MOTION_STAGGER_MAX","MOTION_DURATION_MS"],"mappings":";;;;;AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCG;MACU,YAAY,GAAG,CAAC,KAAa,MAAoB;AAC5D,IAAA,cAAc,EAAE,SAAS;;;;AAIzB,IAAA,KAAK,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE;AACpC,CAAA;AAED;;;;;;;AAOG;MACU,cAAc,GAAG,CAAC,KAAa,KAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAEA,yBAAkB,CAAC;IAChDC,yBAAkB,CAAC;;;;;"}

package/dist/utils/staggerProps.mjs

@@ -0,0 +1,59 @@
+"use client";
+import { MOTION_STAGGER_MAX, MOTION_DURATION_MS } from '../theme/motion.mjs';
+
+/**
+ * Makes one list item arrive `index` beats after the first.
+ *
+ * ```tsx
+ * {options.map((option, i) => (
+ *   <Select.Item key={option.value} item={option} {...staggerProps(i)}>
+ * ))}
+ * ```
+ *
+ * A function rather than a `<Stagger>` wrapper. A wrapper has to render
+ * something to hold the index, and an extra node inside a `Menu.Content` or a
+ * `Select.Content` is not free: Ark walks those children to build its typeahead
+ * and roving-focus collections, and a grid or flex list would gain a layout box
+ * between the container and every row. This adds no DOM at all, and it composes
+ * with a list that is already being mapped rather than asking for the list to be
+ * restructured around it.
+ *
+ * The index rides an inline custom property rather than the `css` prop on
+ * purpose: `css` would compile one class per index and grow the stylesheet with
+ * the length of the longest list ever rendered, while the *only* thing that
+ * varies per item is this one number. Everything else — the keyframe, the
+ * duration, the curve, the cap — lives in the `stagger` preset, which is one
+ * class shared by every item on the page.
+ *
+ * Where **not** to use it, and why the list is short: stagger costs the reader
+ * time in exchange for rhythm, so it is worth it only where the list is short,
+ * arrives once, and is looked at as a whole. `Masonry` and `Table` are the
+ * explicit exclusions — both are long, both are candidates for virtualization
+ * (where "index" means position in a window that scrolls, so items would
+ * re-stagger as they scroll into view), and a sortable table re-orders its rows
+ * on click, which would deal the whole grid out again on every header press.
+ *
+ * @param index - The item's position in its list, from 0.
+ * @returns Props to spread onto the item. Merge `style` by hand if the call
+ *   site already sets one.
+ */
+const staggerProps = (index) => ({
+    animationStyle: 'stagger',
+    // Not clamped here even though the preset's `min()` makes it redundant in
+    // CSS: an out-of-range value passed straight through is what makes a wrong
+    // index visible in the DOM instead of silently flattened.
+    style: { '--stagger-index': index },
+});
+/**
+ * The delay `staggerProps(index)` resolves to, in milliseconds.
+ *
+ * Exists for the two callers that cannot read a CSS variable — a test asserting
+ * the cap holds, and JS animation tech sequencing alongside a staggered list.
+ * It has to mirror the `calc()` in the `stagger` preset exactly, which is why
+ * both read the same two constants.
+ */
+const staggerDelayMs = (index) => Math.min(Math.max(index, 0), MOTION_STAGGER_MAX) *
+    MOTION_DURATION_MS.staggerStep;
+
+export { staggerDelayMs, staggerProps };
+//# sourceMappingURL=staggerProps.mjs.map

package/dist/utils/staggerProps.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"staggerProps.mjs","sources":["../../src/utils/staggerProps.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCG;MACU,YAAY,GAAG,CAAC,KAAa,MAAoB;AAC5D,IAAA,cAAc,EAAE,SAAS;;;;AAIzB,IAAA,KAAK,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE;AACpC,CAAA;AAED;;;;;;;AAOG;MACU,cAAc,GAAG,CAAC,KAAa,KAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,kBAAkB,CAAC;IAChD,kBAAkB,CAAC;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindlogic-ai/logician-ui",
-  "version": "4.0.0-alpha.9",
+  "version": "4.0.0",
   "description": "A comprehensive React design system built on Chakra UI",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -15,6 +15,11 @@
       "types": "./dist/icons.d.ts",
       "import": "./dist/icons.mjs",
       "require": "./dist/icons.js"
+    },
+    "./styles": {
+      "types": "./dist/styles.d.ts",
+      "import": "./dist/styles.mjs",
+      "require": "./dist/styles.js"
     }
   },
   "files": [
@@ -48,6 +53,7 @@
     "check-exports": "node check-component-exports.js"
   },
   "peerDependencies": {
+    "@ark-ui/react": "^5.39.0",
     "@chakra-ui/react": "^3.3.0",
     "@emotion/react": "^11.11.0",
     "next": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0",
@@ -71,7 +77,6 @@
     "next-themes": "^0.4.6",
     "polished": "^4.3.0",
     "react-markdown": "^10.1.0",
-    "react-pin-input": "^1.3.0",
     "recharts": "^3.1.2",
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
@@ -82,6 +87,7 @@
     "shiki": "^1.22.0"
   },
   "devDependencies": {
+    "@ark-ui/react": "5.39.0",
     "@chakra-ui/react": "^3.3.0",
     "@changesets/cli": "^2.27.0",
     "@emotion/react": "^11.11.0",
@@ -104,6 +110,7 @@
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "@vitejs/plugin-react": "^4.0.0",
+    "axe-core": "^4.13.0",
     "eslint": "^8.45.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",

package/src/components/Accordion/Accordion.presence.test.tsx

@@ -0,0 +1,54 @@
+import { Accordion as ChakraAccordion, ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { Accordion } from './Accordion';
+
+/**
+ * Accordion content runs the same height animation as Collapsible, so it gets
+ * the same clock (300 in / 150 out) instead of Chakra's symmetric 200 / 200,
+ * and keeps the recipe's own `expand-height` name.
+ */
+const rulesFor = (el: Element) => {
+  const css = Array.from(document.querySelectorAll('style'))
+    .map((s) => s.textContent ?? '')
+    .join('\n');
+  return el.className
+    .split(' ')
+    .filter((c) => c.startsWith('css-'))
+    .flatMap((c) => [
+      ...css.matchAll(new RegExp(`\\.${c}[^{]*\\{([^}]*)\\}`, 'g')),
+    ])
+    .map((m) => m[1])
+    .join('\n');
+};
+
+describe('Accordion presence timing', () => {
+  it('opens on motion.base and closes on fast, keeping the height keyframes', () => {
+    const { container } = render(
+      <ChakraProvider value={system}>
+        <Accordion defaultValue={['a']}>
+          <ChakraAccordion.Item value="a">
+            <ChakraAccordion.ItemTrigger>A</ChakraAccordion.ItemTrigger>
+            <ChakraAccordion.ItemContent>
+              <ChakraAccordion.ItemBody>body</ChakraAccordion.ItemBody>
+            </ChakraAccordion.ItemContent>
+          </ChakraAccordion.Item>
+        </Accordion>
+      </ChakraProvider>
+    );
+    const rules = rulesFor(
+      container.querySelector('[data-part="item-content"]')!
+    );
+
+    expect(rules).toContain(
+      'animation-duration:var(--chakra-durations-motion-base)'
+    );
+    expect(rules).toContain('animation-duration:var(--chakra-durations-fast)');
+    expect(rules).not.toContain(
+      'animation-duration:var(--chakra-durations-moderate)'
+    );
+    expect(rules).toContain('expand-height');
+  });
+});

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

@@ -0,0 +1,219 @@
+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 { Chip } from '../Chip';
+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}>
+                <Chip colorScheme="primary" variant="soft">
+                  {v.label}
+                </Chip>
+              </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="outline"
+            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="outline">
+                  메뉴 열기
+                </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) => (
+                <Chip
+                  key={t}
+                  colorScheme="neutral"
+                  variant="outline"
+                  {...staggerProps(i)}
+                >
+                  {t}
+                </Chip>
+              ))}
+            </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';