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

package/src/components/Shake/Shake.stories.tsx

@@ -0,0 +1,155 @@
+import { Box, Grid, HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { Button } from '../Button';
+import { Chip } from '../Chip';
+import { Input } from '../Input';
+import { Subtext } from '../Typography';
+import { Shake } from '.';
+
+/**
+ * The house "no, not that" gesture — a rejected answer, an invalid field, a
+ * refused action. Replays whenever `trigger` changes.
+ */
+const meta = {
+  title: 'Components/Motion/Shake',
+  component: Shake,
+  args: { trigger: 0 },
+} satisfies Meta<typeof Shake>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [attempts, setAttempts] = useState(0);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => setAttempts((a) => a + 1)}
+        >
+          틀린 답 제출
+        </Button>
+        <Shake trigger={attempts}>
+          <Chip colorScheme="danger" variant="soft">
+            ✕ 다시 시도해 주세요
+          </Chip>
+        </Shake>
+        <Subtext color="fg.muted" mb={0}>
+          같은 답을 두 번 내도 두 번 흔들립니다 — 값이 아니라 사건을 셉니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/** `distance` is the peak travel. Past ~10px it reads as broken rather than as "no". */
+export const Distance: 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={6}>
+          {[4, 6, 12].map((d) => (
+            <Stack key={d} gap={2} align="center">
+              <Shake trigger={run} distance={d}>
+                <Box
+                  px={3}
+                  py={2}
+                  borderRadius="md"
+                  bg="bg.subtle"
+                  fontSize="sm"
+                >
+                  거절
+                </Box>
+              </Shake>
+              <Subtext fontFamily="mono" fontSize="2xs" color="fg.muted" mb={0}>
+                {d}px
+              </Subtext>
+            </Stack>
+          ))}
+        </HStack>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * What a reader who asked for less motion actually gets.
+ *
+ * The shake is `animationName: none` under `prefers-reduced-motion`, which
+ * makes the wrapper a no-op — so the right-hand column, rendered without it, is
+ * literally what those readers see. If the refusal is not legible there, the
+ * component is carrying meaning it cannot deliver.
+ */
+export const ReducedMotion: Story = {
+  name: '동작 줄이기에서 남는 것',
+  render: () => {
+    const [n, setN] = useState(0);
+
+    // The real form primitives, so the demo shows what an invalid field
+    // actually looks like rather than an approximation of one.
+    const Field = ({ signalled }: { signalled: boolean }) => (
+      <Stack gap={1} w="100%">
+        <Input
+          value={signalled ? '1998' : ''}
+          readOnly
+          aria-invalid={signalled || undefined}
+          placeholder="답을 입력하세요"
+        />
+        {signalled && (
+          <Chip colorScheme="danger" variant="soft">
+            ✕ 다시 시도해 주세요
+          </Chip>
+        )}
+      </Stack>
+    );
+
+    return (
+      <Stack gap={5} align="flex-start" maxW="620px">
+        <Button size="sm" variant="outline" onClick={() => setN((a) => a + 1)}>
+          틀린 답 제출
+        </Button>
+
+        <Grid templateColumns={{ base: '1fr', md: '1fr 1fr' }} gap={6} w="100%">
+          {[
+            { label: '보통', reduced: false },
+            { label: '동작 줄이기 켠 사람이 보는 것', reduced: true },
+          ].map((col) => (
+            <Stack key={col.label} gap={2}>
+              <Subtext
+                fontSize="2xs"
+                color={col.reduced ? 'warning.main' : 'fg.muted'}
+                mb={0}
+              >
+                {col.label}
+              </Subtext>
+              {col.reduced ? (
+                <Field signalled={n > 0} />
+              ) : (
+                <Shake trigger={n} display="block">
+                  <Field signalled={n > 0} />
+                </Shake>
+              )}
+            </Stack>
+          ))}
+        </Grid>
+
+        <Subtext color="fg.muted" mb={0}>
+          오른쪽에서도 거절이 읽히는 이유는 <b>테두리 색 · ✕ 아이콘 · 문구</b>가
+          같이 바뀌기 때문입니다. 흔들림만 있었다면 저 사람에게는 아무 일도
+          일어나지 않은 화면입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};

package/src/components/Shake/Shake.styles.ts

@@ -0,0 +1,31 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * The refusal gesture.
+ *
+ * `motion.base` rather than FactChat's literal 360ms — 60ms adrift and on the
+ * scale. Its own comment names the ceiling this has to stay under: past ~450ms
+ * a shake stops saying "no" and starts saying "broken".
+ *
+ * `standard`, deliberately not `overshoot`. Overshoot passes the target and
+ * comes back, which reads as bounce, and a bouncy refusal reads as playful.
+ * The decay is in the keyframe instead, where it settles *to* centre rather
+ * than through it.
+ *
+ * Removed entirely under reduced motion — and that is why a shake must never be
+ * the only signal. Pair it with colour, an icon, or copy that says the same
+ * thing, because for some readers this simply will not happen.
+ */
+/**
+ * A function of the play count — see `pulsePop` for why. The stake is higher
+ * here: a shake fires on a refusal, so the remount the earlier version used to
+ * replay it would drop the keyboard focus of the person who just got told no.
+ */
+export const shakeX = (play: number): SystemStyleObject => ({
+  animationName: play % 2 === 0 ? 'shake-x-alt' : 'shake-x',
+  animationDuration: 'motion.base',
+  animationTimingFunction: 'standard',
+  animationFillMode: 'both',
+  transformOrigin: 'center',
+  _motionReduce: { animationName: 'none' },
+});

package/src/components/Shake/Shake.tsx

@@ -0,0 +1,79 @@
+import { ForwardedRef, forwardRef, useRef } from 'react';
+import { Box } from '@chakra-ui/react';
+
+import { mergeCss } from '@/utils/mergeCss';
+
+import { shakeX } from './Shake.styles';
+import { ShakeProps } from './Shake.types';
+
+/**
+ * Shakes once whenever `trigger` changes — the house "no, not that" gesture,
+ * for a rejected answer, an invalid field, a refused action.
+ *
+ * The counterpart to `Pulse`, and the pair has to be kept apart: both replay on
+ * a trigger, but a pulse draws the eye to something *good* that landed, and a
+ * shake refuses. A shake used as emphasis reads as an error the reader then goes
+ * looking for.
+ *
+ * Replays the same way `Pulse` does — two byte-identical keyframes alternating
+ * by play count, because a CSS animation restarts when its name changes. The
+ * DOM is left alone, which matters more here than anywhere: a shake fires on a
+ * refusal, so the earlier `key`-driven replay took the keyboard focus of the
+ * person who had just been told no. The first render never shakes.
+ *
+ * **Never let this be the only signal.** It is removed entirely under reduced
+ * motion, so for some readers nothing happens at all; pair it with colour, an
+ * icon, or copy that says the same thing.
+ *
+ * **Adds 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
+ * <Shake trigger={attempts}>
+ *   <Input aria-invalid={invalid} />
+ * </Shake>
+ * ```
+ */
+export const Shake = forwardRef(
+  (
+    { trigger, distance, children, css, ...rest }: ShakeProps,
+    ref?: ForwardedRef<HTMLDivElement>
+  ) => {
+    // A play counter rather than the trigger itself, so a value that returns to
+    // one it held before still fires — two rejections of the same answer are
+    // two events, and keying on the value would swallow the second.
+    const plays = useRef(0);
+    const previous = useRef(trigger);
+    if (previous.current !== trigger) {
+      previous.current = trigger;
+      plays.current += 1;
+    }
+
+    return (
+      <Box
+        ref={ref}
+        display="inline-flex"
+        {...rest}
+        css={
+          plays.current === 0
+            ? css
+            : mergeCss(
+                shakeX(plays.current),
+                distance === undefined
+                  ? undefined
+                  : { '--shake-distance': `${distance}px` },
+                css
+              )
+        }
+      >
+        {children}
+      </Box>
+    );
+  }
+);
+
+Shake.displayName = 'Shake';

package/src/components/Shake/Shake.types.ts

@@ -0,0 +1,11 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export interface ShakeProps extends Omit<BoxProps, 'translate'> {
+  /**
+   * Change this to fire one shake. Any changing value works — an attempt
+   * counter, a verdict, a timestamp. The first render never shakes.
+   */
+  trigger: string | number;
+  /** Peak horizontal travel in px. Defaults to 6. */
+  distance?: number;
+}

package/src/components/Shake/index.ts

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

package/src/components/Slider/Slider.tsx

@@ -15,7 +15,14 @@ import { SliderControl } from './SliderControl';
  */
 export const Slider = forwardRef(
   (
-    { value, defaultValue, onValueChange, children, ...rest }: SliderProps,
+    {
+      value,
+      defaultValue,
+      onValueChange,
+      ariaLabel,
+      children,
+      ...rest
+    }: SliderProps,
     ref?: ForwardedRef<HTMLDivElement>
   ) => {
     // Check if children already contains SliderControl
@@ -42,6 +49,14 @@ export const Slider = forwardRef(
         onValueChange={onValueChange}
         {...rest}
       >
+        {/* The label part is what each thumb's `aria-labelledby` points at, and
+            the reference is emitted whether or not the part is rendered — so a
+            slider composed without one is not merely unlabelled, it is unnamed
+            (KWCAG 5.3.4.1 레이블 제공). Hidden, because these call sites carry
+            their label as an adjacent icon or time display. */}
+        {ariaLabel && (
+          <ChakraSlider.Label srOnly>{ariaLabel}</ChakraSlider.Label>
+        )}
         {wrappedChildren}
       </ChakraSlider.Root>
     );

package/src/components/Slider/Slider.types.ts

@@ -11,5 +11,20 @@ export interface SliderProps extends Omit<
   defaultValue?: number[];
   /** Callback when slider value changes */
   onValueChange?: Slider.RootProps['onValueChange'];
+  /**
+   * Accessible name for the slider, when no visible `Slider.Label` is composed
+   * in — a seek bar next to a time display, a volume control beside a mute
+   * button.
+   *
+   * Without it the thumb has **no accessible name**: Zag points each thumb's
+   * `aria-labelledby` at a label part, and a composition that does not render
+   * one leaves that reference dangling — the control announces as a bare
+   * "slider" (KWCAG 2.1 5.3.4.1 레이블 제공, axe `aria-input-field-name`).
+   *
+   * Rendered as a visually hidden label rather than an `aria-label` array so it
+   * works the same whether the slider has one thumb or several, and so the name
+   * is in the server-rendered markup.
+   */
+  ariaLabel?: string;
   children?: ReactNode;
 }

package/src/components/Spinner/Spinner.styles.ts

@@ -0,0 +1,32 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * The spinner's turn.
+ *
+ * Lives here rather than in `theme/animationStyles` because a rotation on a
+ * loop is this component's business and nothing else's — the shared vocabulary
+ * is for the intents more than one component reaches for. The tokens it reads
+ * (`motion.loop.*`) are still the global scale; it is the *composition* that is
+ * local.
+ *
+ * `linear`, and this is the one place where the curve is not a preference: an
+ * eased rotation decelerates into 360° and accelerates out of 0°, but those are
+ * the same position, so the eye sees a stutter once per turn. A loop that
+ * returns to its own start has no seam only if the rate is constant.
+ *
+ * Under reduced motion it keeps turning, at roughly a third of the speed.
+ * Reduced motion for a loop is not `duration: 0` — a finite transition can be
+ * zeroed because its end state survives, but a frozen spinner reads as a hung
+ * request rather than a working one, and it is the only thing on screen
+ * asserting the request is still alive. Slower is the concession.
+ */
+export const spinAnimation: SystemStyleObject = {
+  // Chakra's `spin` keyframe (0deg → 360deg) rather than one of ours: it is
+  // already exactly right, and redefining a keyframe we did not author would
+  // silently retime every Chakra component that reaches for it.
+  animationName: 'spin',
+  animationDuration: 'motion.loop.turn',
+  animationTimingFunction: 'linear',
+  animationIterationCount: 'infinite',
+  _motionReduce: { animationDuration: 'motion.loop.sweep' },
+};

package/src/components/Spinner/Spinner.tsx

@@ -3,6 +3,7 @@ import { Spinner as ChakraSpinner } from '@chakra-ui/react';
 
 import { mergeCss } from '@/utils/mergeCss';
 
+import { spinAnimation } from './Spinner.styles';
 import { SpinnerProps } from './Spinner.types';
 
 export const Spinner = forwardRef(
@@ -10,7 +11,6 @@ export const Spinner = forwardRef(
     return (
       <ChakraSpinner
         color="primary.main"
-        animationDuration="0.65s"
         ref={ref}
         {...rest}
         // The track ring is the only non-animated affordance and can't take a
@@ -18,7 +18,14 @@ export const Spinner = forwardRef(
         // bg.muted (gray.100) is ~1.03:1 against the bg.sunken page wash
         // (gray.50) and vanishes there; bg.track (gray.300) reads on any
         // background and stays mode-aware.
-        css={mergeCss({ '--spinner-track-color': 'colors.bg.track' }, css)}
+        // Was a literal `animationDuration="0.65s"`. `spinAnimation` keeps that
+        // period exactly and adds the two things the literal could not say:
+        // `linear`, and a reduced-motion branch that slows the turn instead of
+        // stopping it.
+        css={mergeCss(
+          { ...spinAnimation, '--spinner-track-color': 'colors.bg.track' },
+          css
+        )}
       />
     );
   }

package/src/components/SwapTransition/SwapTransition.stories.tsx

@@ -0,0 +1,229 @@
+import { Box, HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { Button } from '../Button';
+import { Card } from '../Card';
+import { Subtext, Text } from '../Typography';
+import { SwapTransition } from '.';
+
+/**
+ * Swaps one piece of content for another with a directional slide — moving
+ * between steps of a sequence, or between records in the same frame.
+ *
+ * The only primitive here that keeps React state: the outgoing subtree has to
+ * stay on screen long enough to leave, and React has already been told to
+ * render the new one.
+ */
+const meta = {
+  title: 'Components/Motion/SwapTransition',
+  component: SwapTransition,
+  args: { transitionKey: 0 },
+} satisfies Meta<typeof SwapTransition>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const STEPS = [
+  { title: '주장 확인', body: '검증할 문장을 고릅니다.' },
+  { title: '출처 대조', body: '세 곳 이상의 출처와 맞춰 봅니다.' },
+  { title: '판정', body: '사실 · 허위 · 부분으로 나눕니다.' },
+];
+
+export const Default: Story = {
+  render: () => {
+    const [step, setStep] = useState(0);
+
+    return (
+      <Stack gap={4} align="flex-start" maxW="420px">
+        <HStack gap={2}>
+          <Button
+            size="xs"
+            variant="outline"
+            disabled={step === 0}
+            onClick={() => setStep((s) => s - 1)}
+          >
+            이전
+          </Button>
+          <Button
+            size="xs"
+            disabled={step === STEPS.length - 1}
+            onClick={() => setStep((s) => s + 1)}
+          >
+            다음
+          </Button>
+        </HStack>
+
+        <SwapTransition
+          transitionKey={step}
+          w="100%"
+          minH="96px"
+          overflow="hidden"
+        >
+          <Card p={4}>
+            <Text fontWeight="700" mb={1}>
+              {step + 1}. {STEPS[step].title}
+            </Text>
+            <Subtext color="fg.muted" mb={0}>
+              {STEPS[step].body}
+            </Subtext>
+          </Card>
+        </SwapTransition>
+
+        <Subtext color="fg.muted" mb={0}>
+          퇴장(150ms)이 끝난 뒤 진입(200ms)이 시작합니다. 직렬이라 합이 곧 체감
+          지연이고, 그래서 presence(300/150)보다 짧게 잡았습니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/** Negative `distance` runs the swap backwards — for going back a step. */
+export const Direction: Story = {
+  render: () => {
+    const [step, setStep] = useState(0);
+    const [back, setBack] = useState(false);
+
+    return (
+      <Stack gap={4} align="flex-start" maxW="420px">
+        <HStack gap={2}>
+          <Button
+            size="xs"
+            variant="outline"
+            onClick={() => {
+              setBack(true);
+              setStep((s) => (s + STEPS.length - 1) % STEPS.length);
+            }}
+          >
+            ← 뒤로
+          </Button>
+          <Button
+            size="xs"
+            onClick={() => {
+              setBack(false);
+              setStep((s) => (s + 1) % STEPS.length);
+            }}
+          >
+            앞으로 →
+          </Button>
+        </HStack>
+
+        <SwapTransition
+          transitionKey={step}
+          distance={back ? -24 : 24}
+          w="100%"
+          minH="64px"
+          overflow="hidden"
+        >
+          <Card p={3} variant="default">
+            <Text fontWeight="600" mb={0}>
+              {STEPS[step].title}
+            </Text>
+          </Card>
+        </SwapTransition>
+
+        <Subtext color="fg.muted" mb={0}>
+          나가는 쪽은 이동 방향의 <b>반대로</b> 빠집니다 — 그래야 둘이 스쳐
+          지나가는 게 아니라 하나의 움직임으로 읽힙니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * The two shapes that broke in the product, side by side — click both.
+ *
+ * Neither was reachable from the demos above, which is why they shipped. Those
+ * change the key on every click and sit in ordinary flow; the app did neither.
+ * A story is the author's idea of how a component is used, and these two are
+ * what the call sites actually did.
+ *
+ * **Left — content that changes without a new key.** `transitionKey` is fixed,
+ * and picking an option only re-renders. The first version rendered a *copy* of
+ * `children` held in state and refreshed it from an effect keyed on
+ * `transitionKey`, so a render like this never reached the screen: the option
+ * stayed unpicked and the panel read as dead.
+ *
+ * **Right — a full-height pane with a bar pinned under it.** The wrapper is told
+ * to fill (`display="flex" flex={1} minH={0}`) so the bar sits on the bottom
+ * edge. The first version put the content one element further in than those
+ * props, so the fill stopped short, the pane sized to its content, and the bar
+ * rode up with dead space beneath it.
+ *
+ * Both should now behave: the option fills in, and the bar stays at the bottom
+ * through a swap.
+ */
+export const CallSiteShapes: Story = {
+  render: () => {
+    const [picked, setPicked] = useState<string | null>(null);
+    const [step, setStep] = useState(0);
+
+    return (
+      <HStack align="stretch" gap={8} p={4} h="360px">
+        <Stack flex={1} gap={3} minW={0}>
+          <Subtext color="fg.muted" mb={0}>
+            키 고정 · 내용만 변경
+          </Subtext>
+          <SwapTransition transitionKey="fixed">
+            <Card p={4} variant="default">
+              <Text fontWeight="600" mb={3}>
+                딥러닝 기반 AI의 특징은?
+              </Text>
+              <Stack gap={2}>
+                {['많은 데이터를 학습한다', '인터넷 없이 작동한다'].map((o) => (
+                  <Button
+                    key={o}
+                    size="sm"
+                    variant={picked === o ? 'solid' : 'outline'}
+                    colorPalette={picked === o ? 'primary' : 'neutral'}
+                    onClick={() => setPicked(o)}
+                  >
+                    {o}
+                  </Button>
+                ))}
+              </Stack>
+            </Card>
+          </SwapTransition>
+        </Stack>
+
+        <Stack
+          flex={1}
+          minW={0}
+          gap={0}
+          borderWidth="1px"
+          borderColor="border.default"
+          borderRadius="md"
+          overflow="hidden"
+        >
+          <Box p={3} borderBottomWidth="1px" borderColor="border.subtle">
+            <Subtext mb={0}>전체 높이 페인 · 바닥에 붙은 액션 바</Subtext>
+          </Box>
+          <SwapTransition
+            transitionKey={step}
+            display="flex"
+            flexDirection="column"
+            flex={1}
+            minH={0}
+          >
+            <Box p={4} flex={1} minH={0}>
+              <Text fontWeight="600" mb={1}>
+                {STEPS[step % STEPS.length].title}
+              </Text>
+              <Subtext color="fg.muted" mb={0}>
+                {STEPS[step % STEPS.length].body}
+              </Subtext>
+            </Box>
+          </SwapTransition>
+          <Box p={3} borderTopWidth="1px" borderColor="border.subtle">
+            <Button size="sm" w="100%" onClick={() => setStep((s) => s + 1)}>
+              다음 단계
+            </Button>
+          </Box>
+        </Stack>
+      </HStack>
+    );
+  },
+};

package/src/components/SwapTransition/SwapTransition.styles.ts

@@ -0,0 +1,38 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * The two halves of a directional swap, run in series.
+ *
+ * `moderate` in and `fast` out — 200 and 150 against FactChat's 220 and 160, so
+ * the ratio and the feel survive and both numbers are on the scale.
+ *
+ * Out is quicker than in, the same asymmetry `presence` enforces and for the
+ * same reason: the outgoing content is already understood and only has to clear
+ * the stage, while the incoming content is what has to be read.
+ *
+ * But the pair is 350ms rather than `presence`'s 450ms, because here the two
+ * halves run *in series* — the reader waits out both before the new content is
+ * on screen, so the sum is the latency they actually feel. That is why this is
+ * its own timing rather than the presence preset.
+ *
+ * Under reduced motion both halves collapse to nothing. The swap still happens,
+ * instantly, which is the correct answer for a change the reader asked for.
+ */
+export const swapIn: SystemStyleObject = {
+  animationName: 'swap-in',
+  animationDuration: 'moderate',
+  animationTimingFunction: 'emphasized',
+  animationFillMode: 'both',
+  _motionReduce: { animationDuration: 'motion.instant' },
+};
+
+export const swapOut: SystemStyleObject = {
+  animationName: 'swap-out',
+  animationDuration: 'fast',
+  animationTimingFunction: 'standard',
+  animationFillMode: 'both',
+  _motionReduce: { animationDuration: 'motion.instant' },
+};
+
+/** Matches `swapOut`'s duration — the JS timer and the CSS clock are one value. */
+export const SWAP_OUT_MS = 150;