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

package/src/components/Card/Card.tsx

@@ -1,10 +1,11 @@
 import { forwardRef } from 'react';
 import { Card as ChakraCard } from '@chakra-ui/react';
 
+import { polymorphic } from '../../types/polymorphic';
 import { clickableStyles, variantStyles } from './Card.styles';
-import { CardProps } from './Card.types';
+import { CardOwnProps } from './Card.types';
 
-export const Card = forwardRef<HTMLDivElement, CardProps>(
+const CardImpl = forwardRef<HTMLDivElement, CardOwnProps>(
   ({ clickable, variant = 'default', _hover, ...rest }, ref) => {
     const mergedHover = clickable
       ? { ...clickableStyles._hover, ..._hover }
@@ -21,12 +22,15 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
         // border.default (gray.300 / gray.1100 _dark) instead of border.subtle:
         // subtle's _dark (gray.1300 #1E2433) is ~invisible on bg.surface in dark,
         // so cards blended into the canvas. default gives the card a discernible
-        // edge in both modes. The `gradient` variant keeps its primary.light border.
+        // edge in both modes. The `wash` variant softens it back to
+        // border.subtle because its `bg.subtle` fill already separates it.
         borderColor="border.default"
         borderRadius="lg"
+        // Was `transitionDuration="normal"` — a Chakra v2 token absent from v3.
+        // It fell through as a literal, `transition-duration: normal` is invalid
+        // CSS, and the whole declaration was dropped, so hover never transitioned.
+        animationStyle="feedback"
         transitionProperty="common"
-        transitionDuration="normal"
-        transitionTimingFunction="ease"
         p={8}
         {...(clickable ? { cursor: clickableStyles.cursor } : {})}
         {...variantStyles[variant]}
@@ -37,4 +41,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
   }
 );
 
-Card.displayName = 'Card';
+/** Type-level polymorphism over the same runtime — see the note on `Button`. */
+CardImpl.displayName = 'Card';
+
+export const Card = polymorphic<CardOwnProps, 'div'>(CardImpl);

package/src/components/Card/Card.types.ts

@@ -1,8 +1,32 @@
+import type { ElementType } from 'react';
 import { CardRootProps as ChakraCardRootProps } from '@chakra-ui/react';
 
-export type CardVariant = 'default' | 'gradient';
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
 
-export type CardProps = ChakraCardRootProps & {
+/**
+ * `gradient` is a deprecated alias of `wash` and renders identically; it stays
+ * so consumers on the alpha line keep compiling while they migrate.
+ */
+export type CardVariant = 'default' | 'wash' | 'gradient' | 'elevated';
+
+export type CardOwnProps = Omit<ChakraCardRootProps, 'as'> & {
   clickable?: boolean;
   variant?: CardVariant;
 };
+
+/**
+ * Props for `Card`, typed for whatever element `as` renders.
+ *
+ * A `clickable` card is the case that needs this: the whole card is one target,
+ * so it should BE the link rather than contain one. Defaults to `'div'`, so
+ * bare `CardProps` is unchanged.
+ *
+ * ```tsx
+ * <Card clickable as={NextLink} href={`/courses/${id}`}>…</Card>
+ * ```
+ */
+export type CardProps<TElement extends ElementType = 'div'> = PolymorphicProps<
+  TElement,
+  CardOwnProps
+>;

package/src/components/Card/index.ts

@@ -1,2 +1,2 @@
 export { Card } from './Card';
-export type { CardProps } from './Card.types';
+export type { CardOwnProps, CardProps, CardVariant } from './Card.types';

package/src/components/Checkbox/Checkbox.styles.ts

@@ -0,0 +1,26 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+import { CHECKMARK_DASH } from '@/theme/motion';
+
+/**
+ * Strokes the checkmark on instead of flashing it in, one `motion.beat` after
+ * the box fills.
+ *
+ * Local rather than part of the shared vocabulary because it is sized to one
+ * icon: the dash is {@link CHECKMARK_DASH} user units, which covers Chakra's
+ * ~22.6-unit tick with a margin. Anything else drawing a path would need its
+ * own length, which is exactly the sign that this is a component's business
+ * rather than a preset everyone chooses from.
+ *
+ * An animation rather than a transition because the polyline only mounts once
+ * the box is checked — there is no previous value for a transition to run from.
+ */
+export const checkmarkDraw: SystemStyleObject = {
+  '& polyline, & path': {
+    strokeDasharray: CHECKMARK_DASH,
+    animation: `checkmark-draw var(--chakra-durations-moderate) var(--chakra-easings-emphasized) var(--chakra-durations-motion-beat) both`,
+  },
+  _motionReduce: {
+    '& polyline, & path': { animation: 'none', strokeDasharray: 'none' },
+  },
+};

package/src/components/Checkbox/CheckboxControl.tsx

@@ -6,6 +6,8 @@ import {
 
 import { focusRing } from '@/utils/focusRing';
 
+import { checkmarkDraw } from './Checkbox.styles';
+
 export const CheckboxControl = forwardRef<HTMLDivElement, CheckboxControlProps>(
   (props, ref) => (
     <ChakraCheckbox.Control
@@ -26,10 +28,17 @@ export const CheckboxControl = forwardRef<HTMLDivElement, CheckboxControlProps>(
         bgColor: { base: 'gray.300', _dark: 'gray.1200' },
         borderColor: 'border.subtle',
       }}
+      // The box fills first, then the tick is stroked on 60ms later. Firing them
+      // together reads as one indistinct flash; the gap makes it two beats —
+      // "pressed", then "confirmed".
+      animationStyle="feedback"
+      transitionProperty="background-color, border-color"
       {...focusRing}
       {...props}
     >
-      <ChakraCheckbox.Indicator />
+      {/* The polyline only mounts once checked, so the draw runs on mount —
+          exactly when we want it. */}
+      <ChakraCheckbox.Indicator css={checkmarkDraw} />
     </ChakraCheckbox.Control>
   )
 );

package/src/components/Chip/Chip.tsx

@@ -3,8 +3,9 @@ import { Badge as ChakraBadge } from '@chakra-ui/react';
 
 import { focusRing } from '@/utils/focusRing';
 
+import { polymorphic } from '../../types/polymorphic';
 import { baseStyles, getChipStyles } from './Chip.styles';
-import { ChipProps } from './Chip.types';
+import { ChipOwnProps } from './Chip.types';
 
 /**
  * A chip component for displaying tags, labels, or status indicators.
@@ -20,9 +21,9 @@ import { ChipProps } from './Chip.types';
  * <Chip colorScheme="success" variant="outline">Completed</Chip>
  * ```
  */
-export const Chip = forwardRef(
+const ChipImpl = forwardRef(
   (
-    { colorScheme = 'primary', variant = 'soft', ...rest }: ChipProps,
+    { colorScheme = 'primary', variant = 'soft', ...rest }: ChipOwnProps,
     ref?: ForwardedRef<HTMLButtonElement>
   ) => {
     const styles = getChipStyles(colorScheme, variant);
@@ -39,4 +40,7 @@ export const Chip = forwardRef(
   }
 );
 
-Chip.displayName = 'Chip';
+ChipImpl.displayName = 'Chip';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Chip = polymorphic<ChipOwnProps, 'span'>(ChipImpl);

package/src/components/Chip/Chip.types.ts

@@ -1,5 +1,9 @@
+import type { ElementType } from 'react';
 import { BadgeProps as ChakraBadgeProps } from '@chakra-ui/react';
 
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+
 /**
  * Chip color schemes - determines the semantic color of the chip.
  *
@@ -34,10 +38,21 @@ export type ChipVariant = 'solid' | 'soft' | 'outline';
  *
  * This matches the Button component's architecture for consistency.
  */
-export interface ChipProps extends Omit<
+export type ChipOwnProps = Omit<
   ChakraBadgeProps,
-  'colorScheme' | 'variant'
-> {
+  'colorScheme' | 'variant' | 'as'
+> & {
   colorScheme?: ChipColorScheme;
   variant?: ChipVariant;
-}
+};
+
+/**
+ * Props for `Chip`, typed for whatever element `as` renders. Defaults to
+ * `'span'`, so the bare type is unchanged. A filter chip that navigates is the
+ * case that needs this — as a real link it keeps middle-click and
+ * open-in-new-tab.
+ */
+export type ChipProps<TElement extends ElementType = 'span'> = PolymorphicProps<
+  TElement,
+  ChipOwnProps
+>;

package/src/components/Chip/index.ts

@@ -5,4 +5,9 @@ export {
   getChipStyles,
   variants,
 } from './Chip.styles';
-export type { ChipColorScheme, ChipProps, ChipVariant } from './Chip.types';
+export type {
+  ChipColorScheme,
+  ChipOwnProps,
+  ChipProps,
+  ChipVariant,
+} from './Chip.types';

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

@@ -0,0 +1,83 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { CollapsibleContent } from './CollapsibleContent';
+import { CollapsibleRoot } from './CollapsibleRoot';
+
+/**
+ * `presence` declares a clock and no `animation-name`, which is the one thing
+ * that lets a single preset sit on six unrelated parts. Collapsible is where
+ * that would break first and most visibly: it does not fade or scale, it
+ * interpolates the `--height` Ark measures, so a preset that also named an
+ * animation would silently turn its expansion into a fade.
+ *
+ * Asserting on the emitted rules rather than on computed style because jsdom
+ * does not run animations — what is being checked is which declarations reach
+ * the element, which is exactly where this can go wrong.
+ */
+const setup = () =>
+  render(
+    <ChakraProvider value={system}>
+      <CollapsibleRoot defaultOpen>
+        <CollapsibleContent>content</CollapsibleContent>
+      </CollapsibleRoot>
+    </ChakraProvider>
+  );
+
+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-'))
+      // `[^{]*` rather than a bare `{`: these declarations live behind the
+      // `_open` / `_closed` conditions, so the class never ends the selector.
+      .flatMap((c) => [
+        ...css.matchAll(new RegExp(`\\.${c}[^{]*\\{([^}]*)\\}`, 'g')),
+      ])
+      .map((m) => m[1])
+      .join('\n')
+  );
+};
+
+describe('Collapsible presence timing', () => {
+  it('runs the enter on the house clock, not the recipe 200ms', () => {
+    const { container } = setup();
+    const rules = rulesFor(container.querySelector('[data-part="content"]')!);
+
+    expect(rules).toContain(
+      'animation-duration:var(--chakra-durations-motion-base)'
+    );
+    expect(rules).toContain(
+      'animation-timing-function:var(--chakra-easings-emphasized)'
+    );
+  });
+
+  it('leaves in half that, on the same ease-out', () => {
+    const { container } = setup();
+    const rules = rulesFor(container.querySelector('[data-part="content"]')!);
+
+    expect(rules).toContain('animation-duration:var(--chakra-durations-fast)');
+    expect(rules).toContain(
+      'animation-timing-function:var(--chakra-easings-emphasized)'
+    );
+  });
+
+  it('never names an animation, so the height keyframes survive', () => {
+    // The failing version of this change reads identically at the call site:
+    // `animationStyle="presence"` either way, and the panel still opens — just
+    // by fading, with no height to interpolate, which is the bug.
+    const applied = system.css({ animationStyle: 'presence' });
+    const declarations = JSON.stringify(applied);
+
+    expect(declarations).not.toContain('expand-height');
+    expect(declarations.match(/"animationName"/g) ?? []).toHaveLength(
+      // Only the two under reduced motion, where losing the height is the point.
+      2
+    );
+  });
+});

package/src/components/Collapsible/CollapsibleContent.tsx

@@ -7,6 +7,18 @@ export const CollapsibleContent = forwardRef<
   HTMLDivElement,
   CollapsibleContentProps
 >((props, ref) => {
-  return <ChakraCollapsible.Content ref={ref} px={4} py={3} {...props} />;
+  // The one presence part that does not fade or scale: it interpolates the
+  // `--height` Ark measures. That is exactly why `presence` declares no
+  // `animation-name` — the recipe's `expand-height` / `collapse-height` survive
+  // and only the clock changes.
+  return (
+    <ChakraCollapsible.Content
+      ref={ref}
+      px={4}
+      py={3}
+      animationStyle="presence"
+      {...props}
+    />
+  );
 });
 CollapsibleContent.displayName = 'CollapsibleContent';

package/src/components/ColorMode/ColorModeToggle.tsx

@@ -1,7 +1,8 @@
 'use client';
 import React, { useEffect, useState } from 'react';
-import { LuMoon, LuSun } from 'react-icons/lu';
+import { Box } from '@chakra-ui/react';
 
+import { MoonIcon, SunIcon } from '@/components/Icon';
 import { IconButton } from '@/components/IconButton';
 import type { IconButtonProps } from '@/components/IconButton/IconButton.types';
 
@@ -35,9 +36,39 @@ export const ColorModeToggle: React.FC<ColorModeToggleProps> = ({
     setMounted(true);
   }, []);
 
+  const isDark = mounted && colorMode === 'dark';
+
   return (
     <IconButton aria-label={ariaLabel} onClick={toggleColorMode} {...rest}>
-      {mounted && colorMode === 'dark' ? <LuSun /> : <LuMoon />}
+      {/* Both icons share one grid cell and cross by rotating out and in, so the
+          toggle reads as one object turning rather than two icons swapping. The
+          page-wide colour flip stays instant on purpose — `ColorModeProvider`
+          sets `disableTransitionOnChange` so the whole UI doesn't wash through
+          an intermediate state — this animates the control only. */}
+      <Box display="grid" placeItems="center">
+        <Box
+          gridArea="1 / 1"
+          display="grid"
+          placeItems="center"
+          opacity={isDark ? 1 : 0}
+          transform={isDark ? undefined : 'rotate(-90deg) scale(0.5)'}
+          animationStyle="spring"
+          transitionProperty="opacity, transform"
+        >
+          <SunIcon />
+        </Box>
+        <Box
+          gridArea="1 / 1"
+          display="grid"
+          placeItems="center"
+          opacity={isDark ? 0 : 1}
+          transform={isDark ? 'rotate(90deg) scale(0.5)' : undefined}
+          animationStyle="spring"
+          transitionProperty="opacity, transform"
+        >
+          <MoonIcon />
+        </Box>
+      </Box>
     </IconButton>
   );
 };

package/src/components/Confetti/Confetti.stories.tsx

@@ -0,0 +1,88 @@
+import { Box, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { Button } from '../Button';
+import { Subtext, Text } from '../Typography';
+import { Confetti } from '.';
+
+/**
+ * A one-shot celebratory burst. One class and one keyframe for every piece —
+ * only the custom properties differ.
+ *
+ * Needs a positioned, clipped parent: it fills its container and measures the
+ * fall against it.
+ */
+const meta = {
+  title: 'Components/Motion/Confetti',
+  component: Confetti,
+} satisfies Meta<typeof Confetti>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const Stage = ({ children }: { children: React.ReactNode }) => (
+  <Box
+    position="relative"
+    overflow="hidden"
+    w="100%"
+    maxW="420px"
+    h="240px"
+    borderRadius="lg"
+    border="1px solid"
+    borderColor="border.subtle"
+    bg="bg.surface"
+    display="grid"
+    placeItems="center"
+  >
+    {children}
+  </Box>
+);
+
+export const Default: Story = {
+  render: () => {
+    const [run, setRun] = useState(0);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button size="sm" onClick={() => setRun((r) => r + 1)}>
+          재생
+        </Button>
+        <Stage>
+          {run > 0 && <Confetti key={run} seed={run} />}
+          <Text fontWeight="700" mb={0}>
+            축하합니다
+          </Text>
+        </Stage>
+      </Stack>
+    );
+  },
+};
+
+
+/** `seed` re-scatters. The generator is seeded so one burst holds still across re-renders. */
+export const Seeded: Story = {
+  render: () => {
+    const [seed, setSeed] = useState(1);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => setSeed((s) => s + 1)}
+        >
+          다시 뿌리기 (seed {seed})
+        </Button>
+        <Stage>
+          <Confetti key={seed} seed={seed} pieceCount={30} />
+        </Stage>
+        <Subtext color="fg.muted" mb={0}>
+          <code>Math.random()</code>이었다면 부모가 리렌더할 때마다 조각이 다시
+          흩어집니다 — 그리고 축하를 띄운 부모는 대개 리렌더 중입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};

package/src/components/Confetti/Confetti.styles.ts

@@ -0,0 +1,57 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * One falling piece.
+ *
+ * ## Why the duration is a token *times a factor*
+ *
+ * The first pass of this pinned every piece to `motion.celebrate.fall` exactly,
+ * on the reasoning that randomising a clock leaves a burst with no known
+ * length. That reasoning was right about sequencing and wrong about confetti:
+ * fifty pieces falling at *identical* speed do not read as fifty pieces. They
+ * read as one sheet, because equal speed is the one thing debris never has —
+ * real pieces differ in mass and in how much air they catch, and that
+ * difference is most of what makes a burst look like a burst.
+ *
+ * So the rate varies, but as a bounded multiple of the token rather than an
+ * open `2 + Math.random()`. The scale still sets the pace, the burst still has
+ * a computable ceiling (`fall × 1.3`, plus the delay spread), and the pieces
+ * still fall at different speeds. What the original had that mattered is kept;
+ * what it had that made the burst unschedulable is not.
+ *
+ * `linear`, and this is one of two places in the library where the curve is not
+ * a preference. The other is the spinner, where easing would put a seam in a
+ * loop; here it is gravity — a piece that decelerates on the way down reads as
+ * being lowered rather than dropped. None of the three house curves is right,
+ * and inventing a fourth for confetti alone would be a preset with one call
+ * site.
+ *
+ * `forwards`, so a piece stays gone. Without it every piece snaps back to the
+ * top of the container on the final frame.
+ */
+export const confettiPiece: SystemStyleObject = {
+  position: 'absolute',
+  top: '0',
+  // No radius, and not a token. `radii.xs` is 4px in this theme — a value
+  // chosen for buttons and cards, which is most of the width of a 10px piece.
+  // The radius scale exists for things a finger touches; a fragment is not one,
+  // and a corner is what makes it read as torn paper rather than a pill.
+  borderRadius: '0',
+  animationName: 'confetti-fall',
+  animationDuration:
+    'calc(var(--chakra-durations-motion-celebrate-fall) * var(--confetti-rate, 1))',
+  animationTimingFunction: 'linear',
+  // `both`, not `forwards`. Each piece waits out a delay of up to
+  // `motion.base`, and with `forwards` alone the element renders in its *own*
+  // CSS state during that wait — parked at `top: 0`, which is the top edge of
+  // the container and fully visible. Forty pieces then sit in a row along the
+  // rim and drop when their delay expires: hanging, not falling. The backwards
+  // half of `both` applies the 0% frame during the delay instead, which is
+  // above the edge and clipped away.
+  animationFillMode: 'both',
+  // Nothing to soften: a burst carries no information, so under reduced motion
+  // the pieces stay where they are and invisible. Done in CSS rather than by
+  // branching in JS so the decision sits on the same media query as every
+  // preset, instead of on a hook that has to guess before hydration.
+  _motionReduce: { animationName: 'none', opacity: 0 },
+};