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

package/src/components/ErrorFallback/ErrorFallback.tsx

@@ -1,3 +1,4 @@
+import { useId } from 'react';
 import { Box, Flex, VStack } from '@chakra-ui/react';
 
 import { useTranslate } from '@/hooks/useTranslate';
@@ -20,6 +21,8 @@ export function ErrorFallback({
 }: ErrorFallbackProps) {
   const translate = useTranslate();
   const showToast = useToast();
+  // Names the landmark below with the same words the card shows as its title.
+  const titleId = useId();
 
   const errorInfo = {
     errorId:
@@ -61,7 +64,24 @@ User Agent: ${errorInfo.userAgent}`;
   };
 
   return (
-    <Flex minH="100vh" align="center" justify="center" p={8}>
+    // A landmark, and a named one. This card replaces whatever failed — often
+    // the whole page, so the host's `<main>` goes with it — and a screen-reader
+    // user then has nothing to navigate by: axe reports every node under
+    // `region`, and there is no landmark to jump to (KWCAG 2.1 5.2.4.1 반복
+    // 영역 건너뛰기). A `<section>` labelled by the error title is a region
+    // landmark wherever it renders, which `<main>` would not be — a segment-level
+    // boundary leaves the host's `<main>` in place, and two of those is its own
+    // failure.
+    <Flex
+      as="section"
+      aria-labelledby={titleId}
+      // `svh`: `100vh` is the largest mobile viewport and overflows under
+      // the URL bar.
+      minH="100svh"
+      align="center"
+      justify="center"
+      p={8}
+    >
       <Container disableResponsive maxW="container.sm">
         <Card
           p={12}
@@ -83,7 +103,12 @@ User Agent: ${errorInfo.userAgent}`;
 
             {/* Error Title */}
             <VStack gap={3} align="center" w="full">
-              <H1 color="fg.default" textStyle="h2" fontWeight="bold">
+              <H1
+                id={titleId}
+                color="fg.default"
+                textStyle="h2"
+                fontWeight="bold"
+              >
                 {translate('error_boundary_title')}
               </H1>
               <Subtitle color="fg.muted" textStyle="h5" maxW="md">
@@ -115,7 +140,11 @@ User Agent: ${errorInfo.userAgent}`;
               p={6}
               w="full"
             >
-              <H4 color="primary.dark" mb={4} textAlign="center">
+              {/* `as="h2"`: `H4` is the type size wanted here, but this block
+                  sits directly under the card's `<h1>` — an `<h4>` there skips
+                  two levels and tells a screen-reader user there are sections
+                  they missed (KWCAG 5.2.4.2 제목 제공). */}
+              <H4 as="h2" color="primary.dark" mb={4} textAlign="center">
                 {translate('support_information')}
               </H4>
               <VStack gap={2} align="stretch" mb={4}>

package/src/components/ExpandableText/ExpandableText.stories.tsx

@@ -6,11 +6,11 @@ const meta = {
   title: 'Components/ExpandableText',
   component: ExpandableText,
   args: {
-    charLimit: 100,
+    lineClamp: 3,
     component: 'Text',
   },
   argTypes: {
-    charLimit: { control: 'number' },
+    lineClamp: { control: 'number' },
     component: {
       control: 'select',
       options: ['Text', 'Subtitle', 'Subtext', 'H1', 'H2', 'H3', 'H4', 'H5'],
@@ -121,7 +121,7 @@ export const AsHeading: Story = {
     component: 'H3',
     children: `This is a heading (H3) with expandable text that demonstrates how headings
       can also use this functionality`,
-    charLimit: 50,
+    lineClamp: 2,
   },
 };
 
@@ -134,28 +134,28 @@ export const ComponentComparison: Story = {
       <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
         <div>
           <strong>Text Component:</strong>
-          <ExpandableText {...args} component="Text" charLimit={80}>
+          <ExpandableText {...args} component="Text" lineClamp={2}>
             {longText}
           </ExpandableText>
         </div>
 
         <div>
           <strong>Subtitle Component:</strong>
-          <ExpandableText {...args} component="Subtitle" charLimit={80}>
+          <ExpandableText {...args} component="Subtitle" lineClamp={2}>
             {longText}
           </ExpandableText>
         </div>
 
         <div>
           <strong>Subtext Component:</strong>
-          <ExpandableText {...args} component="Subtext" charLimit={80}>
+          <ExpandableText {...args} component="Subtext" lineClamp={2}>
             {longText}
           </ExpandableText>
         </div>
 
         <div>
           <strong>H4 Component:</strong>
-          <ExpandableText {...args} component="H4" charLimit={80}>
+          <ExpandableText {...args} component="H4" lineClamp={2}>
             {longText}
           </ExpandableText>
         </div>

package/src/components/ExpandableText/ExpandableText.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { Box } from '@chakra-ui/react';
 
 import {
   H1,
@@ -31,28 +32,61 @@ 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"

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';
@@ -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>
@@ -89,7 +89,7 @@ export const FileItem = ({
                   colorPalette="neutral"
                   variant="ghost"
                 >
-                  <IoClose color="fg.subtle" boxSize="md" />
+                  <CloseIcon color="fg.subtle" boxSize="md" />
                 </IconButton>
               </Flex>
             )}
@@ -113,7 +113,7 @@ export const FileItem = ({
                       colorPalette="neutral"
                       variant="ghost"
                     >
-                      <LuDownload color="fg.muted" />
+                      <DownloadIcon color="fg.muted" />
                     </IconButton>
                   </Tooltip>
                 )}
@@ -134,7 +134,7 @@ export const FileItem = ({
                       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;
 }