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

package/src/components/SwapTransition/SwapTransition.test.tsx

@@ -0,0 +1,127 @@
+import { useState } from 'react';
+import { Box, ChakraProvider } from '@chakra-ui/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { SwapTransition } from './SwapTransition';
+
+/**
+ * Two regressions, both found only by looking at a real screen after this
+ * shipped, and both invisible to a render-and-assert test that never re-renders
+ * with new children.
+ *
+ * The component sits between a caller and its own subtree, which is a position
+ * that has to be *transparent*: everything the caller passes has to reach the
+ * element that moves, and every render that is not a swap has to reach the
+ * screen. The first version was neither, so both are pinned here.
+ */
+const wrap = (ui: React.ReactNode) =>
+  render(<ChakraProvider value={system}>{ui}</ChakraProvider>);
+
+describe('SwapTransition', () => {
+  it('renders children that change without a new transitionKey', () => {
+    // The regression: the subtree was copied into state and refreshed from an
+    // effect keyed on `transitionKey`, so a re-render carrying new children
+    // under the SAME key never reached the screen. In the product this was a
+    // radio that would not select — the state changed, the pixels did not.
+    const Harness = () => {
+      const [picked, setPicked] = useState<string | null>(null);
+      return (
+        <SwapTransition transitionKey="step-1">
+          <div>
+            <button onClick={() => setPicked('b')}>pick</button>
+            <span>{picked ?? 'nothing'}</span>
+          </div>
+        </SwapTransition>
+      );
+    };
+
+    wrap(<Harness />);
+    expect(screen.getByText('nothing')).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: 'pick' }));
+
+    expect(screen.getByText('b')).toBeInTheDocument();
+    expect(screen.queryByText('nothing')).not.toBeInTheDocument();
+  });
+
+  it('puts the caller layout props on the element that animates', () => {
+    // The regression: the two states were stacked in a grid cell, which put the
+    // children one element further in than the props. A caller filling a column
+    // — `display="flex" flex={1} minH={0}`, what a full-height pane needs — had
+    // its sizing land on an ancestor of the content, so the pane collapsed to
+    // content height and the action bar below it rode up.
+    //
+    // Asserting on the child's PARENT rather than on a testid: the point is that
+    // no unstyled element got between them.
+    wrap(
+      <SwapTransition
+        transitionKey="a"
+        display="flex"
+        flexDirection="column"
+        flex={1}
+        minH={0}
+      >
+        <Box data-testid="pane">content</Box>
+      </SwapTransition>
+    );
+
+    const wrapper = screen.getByTestId('pane').parentElement!;
+    const style = getComputedStyle(wrapper);
+
+    expect(style.display).toBe('flex');
+    expect(style.flexDirection).toBe('column');
+  });
+
+  it('does not animate its first render unless asked', () => {
+    const { container } = wrap(
+      <SwapTransition transitionKey="a">
+        <div>first</div>
+      </SwapTransition>
+    );
+
+    // Falsy rather than `'none'`: jsdom reports an unset `animation-name` as
+    // the empty string, and the assertion that matters is "no keyframe was
+    // named", not which spelling of nothing came back.
+    expect(
+      getComputedStyle(container.firstElementChild!).animationName
+    ).toBeFalsy();
+  });
+
+  it('animates the first render when animateInitial is set', () => {
+    const { container } = wrap(
+      <SwapTransition transitionKey="a" animateInitial>
+        <div>first</div>
+      </SwapTransition>
+    );
+
+    expect(getComputedStyle(container.firstElementChild!).animationName).toBe(
+      'swap-in'
+    );
+  });
+
+  it('holds the outgoing subtree on screen while it leaves', () => {
+    const Harness = ({ step }: { step: string }) => (
+      <SwapTransition transitionKey={step}>
+        <div>{step}</div>
+      </SwapTransition>
+    );
+
+    const { rerender } = wrap(<Harness step="one" />);
+    expect(screen.getByText('one')).toBeInTheDocument();
+
+    rerender(
+      <ChakraProvider value={system}>
+        <Harness step="two" />
+      </ChakraProvider>
+    );
+
+    // Still the old content, and marked away from assistive tech while it goes.
+    expect(screen.getByText('one')).toBeInTheDocument();
+    expect(screen.queryByText('two')).not.toBeInTheDocument();
+    expect(screen.getByText('one').parentElement).toHaveAttribute(
+      'aria-hidden'
+    );
+  });
+});

package/src/components/SwapTransition/SwapTransition.tsx

@@ -0,0 +1,130 @@
+import {
+  ForwardedRef,
+  forwardRef,
+  ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { Box } from '@chakra-ui/react';
+
+import { mergeCss } from '@/utils/mergeCss';
+
+import { SWAP_OUT_MS, swapIn, swapOut } from './SwapTransition.styles';
+import { SwapTransitionProps } from './SwapTransition.types';
+
+/**
+ * Swaps one piece of content for another with a directional slide — the house
+ * gesture for moving between steps of a sequence, or between records in the
+ * same frame.
+ *
+ * The outgoing content leaves *against* the travel direction, so the pair reads
+ * as one movement rather than as two things passing each other.
+ *
+ * ## One element, and the children are yours
+ *
+ * Two rules this has to keep, both learned by breaking them:
+ *
+ * **It renders a single box.** Everything the caller passes lands on the element
+ * that actually animates, so a wrapper told to fill — `display="flex" flex={1}
+ * minH={0}`, the shape a full-height pane needs — still fills. An earlier
+ * version stacked the two states in a grid cell and put the children one level
+ * further in; the sizing props stopped reaching them, and a pane that should
+ * have filled its column collapsed to content height with the action bar riding
+ * up under it. The two states are mutually exclusive anyway — only ever one of
+ * them is on screen — so the cell they were sharing bought nothing.
+ *
+ * **It renders `children` directly, never a copy.** The same earlier version
+ * held the subtree in state and rendered that instead, refreshing it from an
+ * effect keyed on `transitionKey` — so content that changed *without* a new key
+ * never reached the screen. A radio that was picked stayed unpicked, and the
+ * interface read as dead. A component that stands between a caller and its own
+ * children has to be transparent to every render that is not a swap.
+ *
+ * What it does keep is one snapshot of the outgoing subtree, for as long as the
+ * exit takes. That is unavoidable without an animation library: React has
+ * already been told to render the new content, and the old content still has to
+ * leave. It is fifteen lines and one `setTimeout`, and it is the only reason
+ * `framer-motion` looked necessary for this file.
+ *
+ * ```tsx
+ * <SwapTransition transitionKey={step}>
+ *   {STEPS[step]}
+ * </SwapTransition>
+ * ```
+ */
+export const SwapTransition = forwardRef(
+  (
+    {
+      transitionKey,
+      distance = 24,
+      animateInitial = false,
+      children,
+      css,
+      ...rest
+    }: SwapTransitionProps,
+    ref?: ForwardedRef<HTMLDivElement>
+  ) => {
+    const [phase, setPhase] = useState<{
+      key: string | number;
+      leaving: ReactNode | null;
+      // Counts plays rather than reusing the key, so swapping A → B → A still
+      // animates the second arrival at A.
+      play: number;
+    }>({ key: transitionKey, leaving: null, play: animateInitial ? 1 : 0 });
+
+    // The subtree as last committed, held only to hand to the exit. It is never
+    // rendered in place of `children` — see the note above.
+    const committed = useRef<ReactNode>(children);
+
+    // Derived during render rather than in an effect, deliberately: the exit has
+    // to begin in the same commit the key changed, or the incoming content
+    // paints for a frame before the outgoing has started to leave.
+    if (phase.key !== transitionKey) {
+      setPhase({
+        key: transitionKey,
+        leaving: committed.current,
+        play: phase.play + 1,
+      });
+    }
+
+    // No dependency array: this has to see every commit, because the snapshot it
+    // keeps is "whatever was on screen last", not "whatever was there when the
+    // key last changed".
+    useEffect(() => {
+      if (phase.leaving === null) {
+        committed.current = children;
+        return;
+      }
+      const timer = setTimeout(
+        () => setPhase((p) => ({ ...p, leaving: null })),
+        SWAP_OUT_MS
+      );
+      return () => clearTimeout(timer);
+    });
+
+    const exiting = phase.leaving !== null;
+
+    return (
+      <Box
+        ref={ref}
+        {...rest}
+        // Unkeyed on purpose. The animation restarts because the *name* changes
+        // — `swap-out` and `swap-in` always alternate, since every key change
+        // plays an exit before its enter — so there is no need to remount, and
+        // the caller keeps a stable DOM node and a stable ref across swaps.
+        aria-hidden={exiting || undefined}
+        pointerEvents={exiting ? 'none' : undefined}
+        css={mergeCss(
+          { '--swap-distance': `${distance}px` },
+          exiting ? swapOut : phase.play === 0 ? undefined : swapIn,
+          css
+        )}
+      >
+        {exiting ? phase.leaving : children}
+      </Box>
+    );
+  }
+);
+
+SwapTransition.displayName = 'SwapTransition';

package/src/components/SwapTransition/SwapTransition.types.ts

@@ -0,0 +1,22 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export interface SwapTransitionProps extends Omit<BoxProps, 'translate'> {
+  /**
+   * Identity of the content on screen. Changing it swaps: the old subtree
+   * leaves, the new one enters. Use what genuinely identifies the content — a
+   * step index, a record id — never a value that changes on unrelated
+   * re-renders, or the content swaps with itself.
+   */
+  transitionKey: string | number;
+  /**
+   * Horizontal travel in px. Positive means the new content enters from the
+   * right (going forward); pass a negative value to run the swap backwards.
+   * Defaults to 24.
+   */
+  distance?: number;
+  /**
+   * Animate the first render too. Off by default — a stepper mounting on step 1
+   * should already be there, not slide in from nowhere.
+   */
+  animateInitial?: boolean;
+}

package/src/components/SwapTransition/index.ts

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

package/src/components/Switch/SwitchControl.tsx

@@ -14,10 +14,20 @@ export const SwitchControl = forwardRef<HTMLSpanElement, SwitchControlProps>(
       // The checked state is the self-defining primary.main fill.
       bg="bg.track"
       _checked={{ bg: 'primary.main' }}
+      animationStyle="feedback"
+      transitionProperty="background-color"
       {...focusRing}
       {...props}
     >
-      <ChakraSwitch.Thumb />
+      <ChakraSwitch.Thumb
+        // A toggle is the metaphor of a physical switch, so the thumb settles
+        // slightly past its stop rather than easing to a halt. Chakra's default
+        // is `translate` over `fast` on a plain curve; `overshoot` is the one
+        // curve that stays legible over the thumb's ~16px of travel, because it
+        // reverses direction — `standard` vs `emphasized` would not.
+        animationStyle="spring"
+        transitionProperty="translate"
+      />
     </ChakraSwitch.Control>
   )
 );

package/src/components/Table/Table.stories.tsx

@@ -12,6 +12,7 @@ import {
   Thead,
   Tr,
 } from '.';
+import { Button } from '../Button';
 import { IoChevronDownOutline } from '../Icon';
 import { IconButton } from '../IconButton';
 
@@ -430,3 +431,255 @@ export const WithTwoLeftStickyColumns: Story = {
   args: { width: '180%' },
   argTypes: {},
 };
+
+// Three consecutive left-pinned columns + one right-pinned column — the shape of
+// the admin 챗봇 공개 관리 / 전체 멤버 tables (checkbox · name · status pinned
+// left, an action column pinned right, many trailing columns scrolling between).
+const adminColumns: { key: string; label: string }[] = [
+  { key: 'check', label: '' },
+  { key: 'name', label: '이름' },
+  { key: 'status', label: '상태' },
+  { key: 'email', label: '이메일' },
+  { key: 'phone', label: '전화번호' },
+  { key: 'address', label: '주소' },
+  { key: 'company', label: '회사' },
+  { key: 'department', label: '부서' },
+  { key: 'action', label: '' },
+];
+
+const LEFT_STICKY = new Set([0, 1, 2]);
+const RIGHT_STICKY = adminColumns.length - 1;
+
+const adminRow = (
+  i: number,
+  name: string,
+  status: string
+): Record<string, string> => ({
+  check: `${i + 1}`,
+  name,
+  status,
+  email: `user${i + 1}@example.com`,
+  phone: '010-1234-5678',
+  address: '서울특별시 강남구 테헤란로 123',
+  company: '테크 주식회사',
+  department: '프론트엔드 팀',
+  action: '⋯',
+});
+
+/**
+ * Multiple left-pinned columns kept flush during horizontal scroll — the admin
+ * table layout that surfaced the offset bug. Scroll sideways: the three left
+ * columns and the right action column stay pinned and opaque, with the middle
+ * columns scrolling underneath.
+ */
+export const WithMultipleLeftStickyColumns: Story = {
+  render: (args) => {
+    const rows = [
+      adminRow(0, '김철수', '승인됨'),
+      adminRow(1, '이영희', '검토중'),
+      adminRow(2, '박지훈', '거절됨'),
+    ];
+    return (
+      <TableContainer>
+        <Table {...args}>
+          <Thead>
+            <Tr>
+              {adminColumns.map((column, index) => (
+                <Th
+                  key={column.key}
+                  isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                  stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                  stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                >
+                  {column.label}
+                </Th>
+              ))}
+            </Tr>
+          </Thead>
+          <Tbody>
+            {rows.map((item, i) => (
+              <Tr key={i}>
+                {adminColumns.map((column, index) => (
+                  <Td
+                    key={column.key}
+                    isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                    stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                    stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                  >
+                    {item[column.key]}
+                  </Td>
+                ))}
+              </Tr>
+            ))}
+          </Tbody>
+        </Table>
+      </TableContainer>
+    );
+  },
+  args: { width: '220%' },
+  argTypes: {},
+};
+
+/**
+ * Regression coverage for the admin 챗봇 공개 관리 / 전체 멤버 breakage.
+ *
+ * The pinned columns' cumulative offsets used to be measured once at mount and
+ * then frozen, so when a column's width changed afterwards — a web-font swap, a
+ * resize, pagination swapping in wider content, or the columns reflowing as the
+ * table went from fitting to overflowing — the following pinned columns stayed
+ * at the stale offsets and visibly detached (an empty gap opened between them).
+ *
+ * Toggle the button: the second pinned column ("이름") grows/shrinks its
+ * content, so the third pinned column ("상태") must re-pin to the new edge. It
+ * has to stay flush — no empty gap, no overlap. Before the ResizeObserver fix a
+ * gap appeared here after toggling.
+ */
+export const StickyOffsetsTrackWidthChanges: Story = {
+  render: (args) => {
+    const [long, setLong] = useState(false);
+    const longName = '아주 아주 긴 이름 콘텐츠로 컬럼 폭을 넓힙니다';
+    const rows = [
+      adminRow(0, long ? `김철수 — ${longName}` : '김철수', '승인됨'),
+      adminRow(1, long ? `이영희 — ${longName}` : '이영희', '검토중'),
+      adminRow(2, long ? `박지훈 — ${longName}` : '박지훈', '거절됨'),
+    ];
+    return (
+      <Flex direction="column" gap={3} align="start">
+        <Button onClick={() => setLong((v) => !v)}>
+          {long ? '이름 컬럼 짧게' : '이름 컬럼 길게 (폭 변경)'}
+        </Button>
+        <TableContainer>
+          <Table {...args}>
+            <Thead>
+              <Tr>
+                {adminColumns.map((column, index) => (
+                  <Th
+                    key={column.key}
+                    isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                    stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                    stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                  >
+                    {column.label}
+                  </Th>
+                ))}
+              </Tr>
+            </Thead>
+            <Tbody>
+              {rows.map((item, i) => (
+                <Tr key={i}>
+                  {adminColumns.map((column, index) => (
+                    <Td
+                      key={column.key}
+                      isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                      stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                      stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                    >
+                      {item[column.key]}
+                    </Td>
+                  ))}
+                </Tr>
+              ))}
+            </Tbody>
+          </Table>
+        </TableContainer>
+      </Flex>
+    );
+  },
+  args: { width: '220%' },
+  argTypes: {},
+};
+
+// Pages whose pinned "이름" column has a different natural width each page — the
+// real admin case, where paging swaps in rows of different content lengths.
+const PAGES: { name: string; status: string }[][] = [
+  [
+    { name: '김철수', status: '승인됨' },
+    { name: '이영희', status: '검토중' },
+    { name: '박지훈', status: '거절됨' },
+  ],
+  [
+    { name: '남궁민수 — 아주 아주 길어서 컬럼을 넓히는 이름', status: '승인됨' },
+    { name: '황보지훈 — 아주 아주 길어서 컬럼을 넓히는 이름', status: '승인됨' },
+    { name: '독고영희 — 아주 아주 길어서 컬럼을 넓히는 이름', status: '검토중' },
+  ],
+  [
+    { name: '최민', status: '거절됨' },
+    { name: '한수', status: '승인됨' },
+    { name: '오지', status: '검토중' },
+  ],
+];
+
+/**
+ * Regression coverage for the exact admin-page symptom: **pagination didn't
+ * re-pin the sticky columns.**
+ *
+ * Paging swaps only the `<tbody>` rows while the `<thead>` (and its Th cells)
+ * stay mounted. Each page here has a different-width pinned "이름" column. The
+ * old engine measured the pinned widths once and only recalculated on a
+ * scroll/resize event — which paging doesn't fire — so pages 2/3 rendered
+ * pinned to page 1's widths and the following columns overlapped. Step through
+ * the pages: the "상태" column must stay flush against "이름" on every page.
+ */
+export const StickyOffsetsSurvivePagination: Story = {
+  render: (args) => {
+    const [page, setPage] = useState(0);
+    const rows = PAGES[page].map((r, i) => adminRow(i, r.name, r.status));
+    return (
+      <Flex direction="column" gap={3} align="start">
+        <Flex gap={2} align="center">
+          <Button
+            variant="outline"
+            disabled={page === 0}
+            onClick={() => setPage((p) => Math.max(0, p - 1))}
+          >
+            이전
+          </Button>
+          <span>{page + 1} / {PAGES.length} 페이지</span>
+          <Button
+            variant="outline"
+            disabled={page === PAGES.length - 1}
+            onClick={() => setPage((p) => Math.min(PAGES.length - 1, p + 1))}
+          >
+            다음
+          </Button>
+        </Flex>
+        <TableContainer>
+          <Table {...args}>
+            <Thead>
+              <Tr>
+                {adminColumns.map((column, index) => (
+                  <Th
+                    key={column.key}
+                    isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                    stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                    stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                  >
+                    {column.label}
+                  </Th>
+                ))}
+              </Tr>
+            </Thead>
+            <Tbody>
+              {rows.map((item, i) => (
+                <Tr key={i}>
+                  {adminColumns.map((column, index) => (
+                    <Td
+                      key={column.key}
+                      isSticky={LEFT_STICKY.has(index) || index === RIGHT_STICKY}
+                      stickyDirection={index === RIGHT_STICKY ? 'right' : 'left'}
+                      stickyIndex={index === RIGHT_STICKY ? 0 : index}
+                    >
+                      {item[column.key]}
+                    </Td>
+                  ))}
+                </Tr>
+              ))}
+            </Tbody>
+          </Table>
+        </TableContainer>
+      </Flex>
+    );
+  },
+  args: { width: '220%' },
+  argTypes: {},
+};