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

package/src/components/ExpandableText/ExpandableText.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { Box } from '@chakra-ui/react';
 
 import {
   H1,
@@ -31,32 +32,65 @@ const TEXT_COMPONENTS = {
 export type TextComponentType = keyof typeof TEXT_COMPONENTS;
 
 export type ExpandableTextProps = {
+  /**
+   * How many lines to show while collapsed.
+   * @default 3
+   */
+  lineClamp?: number;
+  /**
+   * @deprecated Truncation is by line, not by character — a character count
+   * cannot be clipped by CSS, and clipping by CSS is what lets the expansion
+   * animate. This prop is ignored; use {@link ExpandableTextProps.lineClamp}.
+   */
   charLimit?: number;
   component?: TextComponentType;
 } & TypographyProps;
 
+/**
+ * Text clipped to a few lines, with a link that opens it.
+ *
+ * Opening animates the height rather than swapping the text, so the content
+ * below slides down instead of jumping — this is text someone is part-way
+ * through reading, and a jump costs them their place.
+ *
+ * @example
+ * ```tsx
+ * <ExpandableText lineClamp={2}>{longDescription}</ExpandableText>
+ * ```
+ */
 export const ExpandableText = ({
-  charLimit = 100,
+  lineClamp = 3,
+  charLimit: _charLimit,
   component = 'Text',
   children,
   ...rest
 }: ExpandableTextProps) => {
   const translate = useTranslate();
-  const { displayText, isLong, isExpanded, handleToggle } = useExpandableText(
-    children,
-    charLimit
-  );
+  const { contentRef, isExpanded, isOverflowing, maxHeight, handleToggle } =
+    useExpandableText(lineClamp);
 
   const Component = TEXT_COMPONENTS[component];
 
   return (
     <Component {...rest}>
-      {displayText}
-      {isLong && (
+      <Box
+        ref={contentRef}
+        overflow="hidden"
+        // `lh` is the line box, so the resting height is a whole number of lines
+        // and the cut always lands between them. Where `lh` is unsupported the
+        // declaration is dropped and the text simply shows in full — degraded,
+        // not broken.
+        maxHeight={maxHeight ?? `${lineClamp}lh`}
+        animationStyle="travel"
+        transitionProperty="max-height"
+      >
+        {children}
+      </Box>
+      {(isOverflowing || isExpanded) && (
         <Link
           as="button"
           textDecor="none"
-          _hover={{ color: 'primary.dark' }}
+          _hover={{ color: 'fg.default' }}
           onClick={handleToggle}
           aria-expanded={isExpanded}
         >

package/src/components/ExpandableText/useExpandableText.ts

@@ -1,114 +1,101 @@
-import { isValidElement, useCallback, useMemo, useState } from 'react';
-
-// Utility function to extract text content from ReactNode
-const getTextContent = (node: React.ReactNode): string => {
-  if (typeof node === 'string' || typeof node === 'number') {
-    return String(node);
-  }
-
-  if (Array.isArray(node)) {
-    return node.map(getTextContent).join('');
-  }
-
-  if (isValidElement(node)) {
-    return getTextContent(node.props.children);
-  }
-
-  return '';
-};
-
-// Utility function to truncate ReactNode content while preserving structure
-const truncateReactNode = (
-  node: React.ReactNode,
-  charLimit: number,
-  currentLength = 0
-): { truncated: React.ReactNode; length: number } => {
-  if (currentLength >= charLimit) {
-    return { truncated: null, length: currentLength };
-  }
-
-  if (typeof node === 'string' || typeof node === 'number') {
-    const text = String(node);
-    const remainingChars = charLimit - currentLength;
-
-    if (text.length <= remainingChars) {
-      return { truncated: node, length: currentLength + text.length };
-    }
-
-    return {
-      truncated: text.slice(0, remainingChars) + '…',
-      length: charLimit,
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+
+import { MOTION_DURATION_MS } from '@/theme/motion';
+
+/**
+ * Whether the OS is asking for less movement, read when it matters rather than
+ * subscribed to — this only decides how long to wait before tidying up, and a
+ * member who flips the setting mid-click is not a case worth a listener for.
+ */
+const prefersReducedMotion = () =>
+  typeof window !== 'undefined' &&
+  window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+/** Two frames, so React has committed the first value before the second lands. */
+const afterPaint = (fn: () => void) =>
+  requestAnimationFrame(() => requestAnimationFrame(fn));
+
+/**
+ * Collapsed/expanded state for text clipped to a number of lines.
+ *
+ * Both states render the same children and the clipping is a `max-height`, which
+ * is what makes the change animatable at all — the previous character-count
+ * version swapped one node tree for another, so there was never anything on the
+ * page for a transition to reveal.
+ *
+ * ## Why not `-webkit-line-clamp`
+ *
+ * The clamp would give the cut line an ellipsis, but it takes the height with
+ * it: under a clamp `scrollHeight` collapses to the clipped height, so there is
+ * no way left to ask whether anything is hidden, and the link that opens the
+ * text can never appear. A `max-height` of whole `lh` units cuts on the same
+ * line boundary, keeps `scrollHeight` honest, and is the thing being animated
+ * anyway.
+ *
+ * ## Why two commits per direction
+ *
+ * `max-height` only animates between two lengths, and each direction begins on a
+ * value that is not one. Opening ends at `none` so a later reflow — a resize, a
+ * font swap — is not trapped under a stale pixel count; closing therefore has to
+ * pin the height it is leaving for one frame before releasing it.
+ */
+export const useExpandableText = (lineClamp: number) => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const settleTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  const [isExpanded, setIsExpanded] = useState(false);
+  /** `undefined` means "rest at the line multiple" — see the component. */
+  const [maxHeight, setMaxHeight] = useState<string>();
+  /** Until we know something is hidden, no link is offered. */
+  const [isOverflowing, setIsOverflowing] = useState(false);
+
+  useLayoutEffect(() => {
+    const el = contentRef.current;
+    if (!el) return;
+
+    // Only meaningful while collapsed; open, the two heights are equal.
+    const check = () => {
+      if (!isExpanded) setIsOverflowing(el.scrollHeight > el.clientHeight + 1);
     };
-  }
-
-  if (Array.isArray(node)) {
-    const truncatedChildren: React.ReactNode[] = [];
-    let totalLength = currentLength;
-
-    for (const child of node) {
-      if (totalLength >= charLimit) break;
-
-      const { truncated, length } = truncateReactNode(
-        child,
-        charLimit,
-        totalLength
-      );
-      if (truncated !== null) {
-        truncatedChildren.push(truncated);
-      }
-      totalLength = length;
-    }
+    check();
 
-    return { truncated: truncatedChildren, length: totalLength };
-  }
+    // How many lines the text takes depends on width, so a resize can create or
+    // remove the overflow entirely.
+    const observer = new ResizeObserver(check);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [lineClamp, isExpanded]);
 
-  if (isValidElement(node)) {
-    const { truncated: truncatedChildren, length } = truncateReactNode(
-      node.props.children,
-      charLimit,
-      currentLength
-    );
+  useEffect(() => () => clearTimeout(settleTimer.current), []);
 
-    if (truncatedChildren === null) {
-      return { truncated: null, length };
-    }
-
-    return {
-      truncated: {
-        ...node,
-        props: {
-          ...node.props,
-          children: truncatedChildren,
-        },
-      },
-      length,
-    };
-  }
-
-  return { truncated: node, length: currentLength };
-};
-
-export const useExpandableText = (
-  children: React.ReactNode,
-  charLimit = 100
-) => {
-  const [isExpanded, setIsExpanded] = useState<boolean>(false);
+  const handleToggle = useCallback((event: React.MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
 
-  const textContent = useMemo(() => getTextContent(children), [children]);
-  const isLong = textContent.length > charLimit;
+    const el = contentRef.current;
+    if (!el) return;
+    clearTimeout(settleTimer.current);
 
-  const displayText = useMemo(() => {
-    if (isExpanded || !isLong) return children;
+    const settle = prefersReducedMotion() ? 0 : MOTION_DURATION_MS.base;
 
-    const { truncated } = truncateReactNode(children, charLimit);
-    return truncated;
-  }, [isExpanded, isLong, children, charLimit]);
+    setIsExpanded((wasExpanded) => {
+      if (wasExpanded) {
+        setMaxHeight(`${el.scrollHeight}px`); // pin the height being left
+        afterPaint(() => setMaxHeight(undefined)); // → line multiple; animates
+        return false;
+      }
 
-  const handleToggle = useCallback((event: React.MouseEvent) => {
-    event.preventDefault();
-    event.stopPropagation();
-    setIsExpanded((prev) => !prev);
+      setMaxHeight(`${el.scrollHeight}px`); // full height; animates open
+      settleTimer.current = setTimeout(() => setMaxHeight('none'), settle);
+      return true;
+    });
   }, []);
 
-  return { isExpanded, isLong, displayText, handleToggle };
+  return { contentRef, isExpanded, isOverflowing, maxHeight, handleToggle };
 };

package/src/components/FileInput/FileInput.tsx

@@ -1,7 +1,7 @@
 import { ChangeEventHandler, forwardRef } from 'react';
 import { Box, Flex, Input } from '@chakra-ui/react';
 
-import { LuUpload } from '@/components/Icon';
+import { UploadIcon } from '@/components/Icon';
 import { Spinner } from '@/components/Spinner';
 import { Text } from '@/components/Typography';
 import { useTranslate } from '@/hooks/useTranslate';
@@ -27,8 +27,12 @@ export const FileInput = forwardRef<HTMLInputElement, FileInputProps>(
     };
 
     return (
+      // No `role="button"` on this wrapper. It is not a button — the `<label>`
+      // inside is what activates the file input — and claiming the role put an
+      // interactive element inside another (axe `nested-interactive`), which is
+      // a state screen readers have no sensible way to announce
+      // (KWCAG 2.1 5.4.2.1 웹 애플리케이션 접근성 준수).
       <Flex
-        role="button"
         w="100%"
         h="100%"
         maxH={32}
@@ -42,8 +46,13 @@ export const FileInput = forwardRef<HTMLInputElement, FileInputProps>(
         borderRadius="md"
         {...containerStyle}
       >
+        {/* `className="group"`, not `role="group"`. The role was doing nothing for
+            assistive tech (a `<label>` may not be a group — axe
+            `aria-allowed-role`) and nothing for the hover effect either: Chakra's
+            `_groupHover` compiles to `.group:hover &`, so it needs the CLASS.
+            The reveal-on-hover below has therefore never fired. */}
         <label
-          role="group"
+          className="group"
           style={{ width: '100%', height: '100%', cursor: 'pointer' }}
         >
           {bgImage && (
@@ -76,7 +85,10 @@ export const FileInput = forwardRef<HTMLInputElement, FileInputProps>(
             align="center"
             bgColor="color-mix(in srgb, var(--chakra-colors-bg-surface) 85%, transparent)"
             opacity={bgImage ? 0 : 1}
-            transition="ease-in"
+            // Was `transition="ease-in"` — a shorthand with only a timing
+            // function resolves to 0s, so the hover fade snapped in one frame.
+            animationStyle="feedback"
+            transitionProperty="opacity"
             _groupHover={{ opacity: 1 }} // Set opacity to 1 on parent hover
           >
             {isLoading ? (
@@ -90,7 +102,7 @@ export const FileInput = forwardRef<HTMLInputElement, FileInputProps>(
                   mb={2}
                   w="fit-content"
                 >
-                  <LuUpload color={bgImage ? 'fg.default' : 'fg.subtle'} />
+                  <UploadIcon color={bgImage ? 'fg.default' : 'fg.subtle'} />
                 </Box>
                 <Text color={bgImage ? 'fg.default' : 'fg.subtle'}>
                   {fileInputLabel || translate('upload_your_file')}

package/src/components/FileItem/FileItem.tsx

@@ -3,11 +3,11 @@ import { Box, Flex } from '@chakra-ui/react';
 
 import { FileItemProps } from '@/components/FileItem/FileItem.types';
 import {
-  CiFileOn,
-  FaRegTrashAlt,
-  IoClose,
-  LuDownload,
-  MdError,
+  AlertCircleFilledIcon,
+  CloseIcon,
+  DownloadIcon,
+  FileIcon,
+  TrashIcon,
 } from '@/components/Icon';
 import { IconButton } from '@/components/IconButton';
 import { ProgressBar } from '@/components/ProgressBar';
@@ -30,7 +30,7 @@ export const FileItem = ({
   ...rest
 }: FileItemProps) => {
   const translate = useTranslate();
-  const errorColor = 'danger.main';
+  const errorColor = 'danger.fg';
 
   const isUploadingFile =
     !error && typeof progress === 'number' && progress >= 0 && progress < 100;
@@ -60,7 +60,7 @@ export const FileItem = ({
     >
       <Flex w="60%" alignItems="center" gap={2}>
         <Box minW={5}>
-          <CiFileOn color={error ? errorColor : 'fg.muted'} />
+          <FileIcon color={error ? errorColor : 'fg.muted'} />
         </Box>
         <Text truncate color={error ? errorColor : undefined}>
           {fileName}
@@ -70,7 +70,7 @@ export const FileItem = ({
         {error ? (
           <Flex w="100%" justify="flex-end" align="center" gap={2}>
             <Tooltip content={error} placement="top">
-              <MdError color={errorColor} />
+              <AlertCircleFilledIcon color={errorColor} />
             </Tooltip>
             {/* TODO: implement retry button */}
           </Flex>
@@ -86,10 +86,9 @@ export const FileItem = ({
                   onClick={onFileDelete}
                   size="2xs"
                   disabled={isDeleting}
-                  colorPalette="neutral"
                   variant="ghost"
                 >
-                  <IoClose color="fg.subtle" boxSize="md" />
+                  <CloseIcon color="fg.subtle" boxSize="md" />
                 </IconButton>
               </Flex>
             )}
@@ -110,10 +109,9 @@ export const FileItem = ({
                       aria-label={translate('download') as string}
                       onClick={onFileDownload}
                       size="2xs"
-                      colorPalette="neutral"
                       variant="ghost"
                     >
-                      <LuDownload color="fg.muted" />
+                      <DownloadIcon color="fg.muted" />
                     </IconButton>
                   </Tooltip>
                 )}
@@ -131,10 +129,9 @@ export const FileItem = ({
                       aria-label={translate('delete') as string}
                       onClick={onFileDelete}
                       size="2xs"
-                      colorPalette="neutral"
                       variant="ghost"
                     >
-                      <FaRegTrashAlt boxSize="sm" color="fg.muted" />
+                      <TrashIcon boxSize="sm" color="fg.muted" />
                     </IconButton>
                   </Tooltip>
                 )}

package/src/components/FileList/FileList.tsx

@@ -3,15 +3,17 @@ import { Box, Button, List } from '@chakra-ui/react';
 
 import { FileItem } from '@/components/FileItem';
 import { FileGroupProps } from '@/components/FileList/FileList.types';
-import { IoChevronDownOutline } from '@/components/Icon';
+import { ChevronDownIcon } from '@/components/Icon';
 import { Subtitle } from '@/components/Typography';
 import { useTranslate } from '@/hooks/useTranslate';
+import { staggerProps } from '@/utils/staggerProps';
 
 export const FileList = ({
   files,
   onFileDelete,
   onFileDownload,
   visibleCount = 3,
+  stagger = false,
 }: FileGroupProps) => {
   const [currentVisibleCount, setCurrentVisibleCount] = useState<number>(
     visibleCount ?? 3
@@ -53,8 +55,15 @@ export const FileList = ({
       overflow="hidden"
     >
       <List.Root>
-        {files?.slice(0, currentVisibleCount).map((file) => (
-          <List.Item key={file.id} listStyle="none">
+        {files?.slice(0, currentVisibleCount).map((file, index) => (
+          // The stagger sits on the row, not on `FileItem`, so a row that is
+          // only revealed by "see more" animates in on its own index rather
+          // than inheriting the delay of the row above it.
+          <List.Item
+            key={file.id}
+            listStyle="none"
+            {...(stagger ? staggerProps(index) : {})}
+          >
             <FileItem
               fileName={file.name}
               onFileDelete={
@@ -87,6 +96,8 @@ export const FileList = ({
           css={{
             all: 'unset',
             display: 'flex',
+            width: '100%',
+            justifyContent: 'center',
             gap: '0.25rem',
             cursor: 'pointer',
           }}
@@ -94,7 +105,7 @@ export const FileList = ({
           <Subtitle color="fg.subtle">
             {translate('see_more')} ({visibleCount}/{files.length})
           </Subtitle>
-          <IoChevronDownOutline color="fg.subtle" />
+          <ChevronDownIcon color="fg.subtle" />
         </Button>
       )}
     </Box>

package/src/components/FileList/FileList.types.ts

@@ -15,4 +15,13 @@ export interface FileGroupProps {
   onFileDelete?: (file: FileItemData) => void;
   onFileDownload?: (file: FileItemData) => void;
   visibleCount?: number;
+  /**
+   * Deal the rows in one after another as they mount — on first render, and
+   * again for each batch revealed by "see more".
+   *
+   * Opt-in because a file list is often *edited* rather than displayed: a list
+   * the reader is uploading into wants each new row to arrive on its own, not
+   * behind six others.
+   */
+  stagger?: boolean;
 }

package/src/components/FlyTo/FlyTo.stories.tsx

@@ -0,0 +1,162 @@
+import { Box, HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useRef, useState } from 'react';
+
+import { Button } from '../Button';
+import { Subtext, Text } from '../Typography';
+import { FlyTo } from '.';
+
+/**
+ * Sends a ghost arcing from one rect to another — "this went there".
+ *
+ * JavaScript measures; CSS animates. The two rects are only knowable at
+ * runtime, so the distance is computed and handed to a keyframe as three custom
+ * properties — the arc itself runs on the compositor with no frame loop.
+ */
+/**
+ * Untyped against the component on purpose: `from` and `to` are `DOMRect`s
+ * measured at runtime, so there is no static `args` to satisfy — every story
+ * here has to render its own instance after laying the two elements out.
+ */
+const meta = {
+  title: 'Components/Motion/FlyTo',
+  component: FlyTo,
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+const Chip = () => (
+  <HStack
+    gap={1}
+    bg="primary.main"
+    color="fg.inverse"
+    px={3}
+    py={1}
+    borderRadius="full"
+    fontSize="sm"
+    fontWeight="700"
+  >
+    <Box>◆</Box>
+    <Box>+50</Box>
+  </HStack>
+);
+
+/**
+ * The caller owns mounting. `onDone` is what advances the sequence — a reward
+ * that landed has to update a balance, and that happens when the ghost arrives
+ * rather than when it left.
+ */
+export const Default: Story = {
+  render: () => {
+    const source = useRef<HTMLButtonElement>(null);
+    const target = useRef<HTMLDivElement>(null);
+    const [flight, setFlight] = useState<{ from: DOMRect; to: DOMRect } | null>(
+      null
+    );
+    const [balance, setBalance] = useState(1250);
+
+    return (
+      <Stack gap={6}>
+        <HStack gap={12} justify="space-between" maxW="480px" align="center">
+          <Button
+            ref={source}
+            size="sm"
+            onClick={() => {
+              const from = source.current?.getBoundingClientRect();
+              const to = target.current?.getBoundingClientRect();
+              if (from && to) setFlight({ from, to });
+            }}
+          >
+            보내기
+          </Button>
+
+          <Box ref={target} textAlign="right">
+            <Subtext color="fg.muted" fontSize="2xs" mb={0}>
+              잔액
+            </Subtext>
+            <Text fontSize="xl" fontWeight="700" mb={0}>
+              {balance.toLocaleString()}
+            </Text>
+          </Box>
+        </HStack>
+
+        {flight && (
+          <FlyTo
+            from={flight.from}
+            to={flight.to}
+            onDone={() => {
+              setFlight(null);
+              setBalance((b) => b + 50);
+            }}
+          >
+            <Chip />
+          </FlyTo>
+        )}
+
+        <Subtext color="fg.muted" mb={0}>
+          잔액은 타이머가 아니라 착지 시점에 오릅니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/** `lift` is how high the arc rises above the straight line between the rects. */
+export const Lift: Story = {
+  render: () => {
+    const source = useRef<HTMLButtonElement>(null);
+    const target = useRef<HTMLDivElement>(null);
+    const [lift, setLift] = useState<number | null>(null);
+
+    const send = (value: number) => {
+      const from = source.current?.getBoundingClientRect();
+      const to = target.current?.getBoundingClientRect();
+      if (from && to) setLift(value);
+    };
+
+    return (
+      <Stack gap={6}>
+        <HStack gap={2}>
+          {[0, 46, 120].map((v) => (
+            <Button
+              key={v}
+              size="xs"
+              variant="secondary"
+              onClick={() => send(v)}
+            >
+              lift {v}
+            </Button>
+          ))}
+        </HStack>
+
+        <HStack gap={12} justify="space-between" maxW="480px" align="center">
+          <Button ref={source} size="sm" variant="ghost">
+            출발
+          </Button>
+          <Box ref={target} px={3} py={2} borderRadius="md" bg="bg.subtle">
+            도착
+          </Box>
+        </HStack>
+
+        {lift !== null && source.current && target.current && (
+          <FlyTo
+            key={lift}
+            from={source.current.getBoundingClientRect()}
+            to={target.current.getBoundingClientRect()}
+            lift={lift}
+            onDone={() => setLift(null)}
+          >
+            <Chip />
+          </FlyTo>
+        )}
+
+        <Subtext color="fg.muted" mb={0}>
+          <b>0이면 직선</b>이고, 직선 보간은 던진 것이 아니라 레이아웃이 바뀐
+          것으로 읽힙니다. 궤적이 이 프리미티브의 전부입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};