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

package/src/components/Confetti/Confetti.types.ts

@@ -0,0 +1,13 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export interface ConfettiProps extends BoxProps {
+  /** How many pieces. Defaults to 50. */
+  pieceCount?: number;
+  /** Colour token names to pick from. Defaults to the palette's five accents. */
+  colors?: string[];
+  /**
+   * Changes the scatter. The generator is seeded rather than `Math.random()` so
+   * one burst holds still across re-renders; pass a new seed to re-scatter.
+   */
+  seed?: number;
+}

package/src/components/Confetti/confettiColors.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { SCHEMES, SYSTEM_HUES } from '../../theme/palette.generated';
+import { DEFAULT_CONFETTI_COLORS } from './confettiColors';
+
+/**
+ * Status colours mean things; a celebratory burst carries no information, so
+ * its defaults must not borrow them (same rule as LineGraph/seriesColors).
+ */
+const STATUS_ROLES = [
+  'danger-solid',
+  'success-solid',
+  'warning-solid',
+  'info-solid',
+];
+const STATUS_HUES = ['red', 'yellow', 'green', 'blue'] as const;
+
+const upper = (hex: string) => hex.toUpperCase();
+const defaults = new Set(DEFAULT_CONFETTI_COLORS.map(upper));
+
+describe('Confetti default colours', () => {
+  it('contain no status solid from any scheme or mode', () => {
+    const hits = Object.entries(SCHEMES).flatMap(([scheme, modes]) =>
+      Object.entries(modes as Record<string, Record<string, string>>).flatMap(
+        ([mode, table]) =>
+          STATUS_ROLES.filter(
+            (role) => table[role] && defaults.has(upper(table[role]))
+          ).map((role) => `${scheme}.${mode}.${role} = ${table[role]}`)
+      )
+    );
+    expect(hits).toEqual([]);
+  });
+
+  it('contain no red, yellow, green or blue system hue value', () => {
+    const hits = STATUS_HUES.flatMap((hue) =>
+      Object.entries(SYSTEM_HUES[hue])
+        .filter(([, hex]) => defaults.has(upper(hex)))
+        .map(([variant, hex]) => `${hue}.${variant} = ${hex}`)
+    );
+    expect(hits).toEqual([]);
+  });
+
+  it('still spans the decorative hues', () => {
+    expect(defaults.has(upper(SYSTEM_HUES.purple.base))).toBe(true);
+    expect(DEFAULT_CONFETTI_COLORS.length).toBeGreaterThanOrEqual(8);
+  });
+});

package/src/components/Confetti/confettiColors.ts

@@ -0,0 +1,41 @@
+import type { SystemHue } from '../../theme/colors';
+import { CORAL, RAMPS, SYSTEM_HUES } from '../../theme/palette.generated';
+
+/**
+ * Hues that carry meaning elsewhere in the system and so never colour a piece
+ * by default: red, yellow and green are the danger, warning and success
+ * solids, and blue is info and links. The same rule as the chart series
+ * defaults (`LineGraph/seriesColors.ts`) — a red piece in a "payment complete"
+ * burst says something the screen does not.
+ */
+export const CONFETTI_EXCLUDED_HUES = [
+  'red',
+  'yellow',
+  'green',
+  'blue',
+] as const;
+
+const DECORATIVE_HUES = (Object.keys(SYSTEM_HUES) as SystemHue[]).filter(
+  (hue) => !(CONFETTI_EXCLUDED_HUES as readonly string[]).includes(hue)
+);
+
+/**
+ * Default piece colours: the house coral (`CORAL.base`, the send/accent coral —
+ * not a status colour), the house beige (`RAMPS.sand.light['8']`, the raw step
+ * behind `secondary.fg`), and the light-mode base of every system hue that
+ * carries no status meaning (brown, orange, mint, teal, cyan, indigo, purple,
+ * pink …).
+ *
+ * Raw hex rather than tokens is a choice, not a constraint. Each piece is a
+ * `<Box bg={…}>`, so a token string would resolve just as well; hex keeps the
+ * default in the same shape as the `colors` prop (any CSS colour string), and
+ * keeps the burst the same in both modes. The cost, stated rather than hidden:
+ * these are the LIGHT-mode values and do not follow dark mode — acceptable for
+ * a two-second burst that carries no information. `colors` is a prop for an
+ * app that needs its own (tokens included).
+ */
+export const DEFAULT_CONFETTI_COLORS: string[] = [
+  CORAL.base,
+  RAMPS.sand.light['8'],
+  ...DECORATIVE_HUES.map((hue) => SYSTEM_HUES[hue].base),
+];

package/src/components/Confetti/index.ts

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

package/src/components/Container/Container.stories.tsx

@@ -7,7 +7,7 @@ const meta = {
   component: Container,
   args: {
     children: 'Container',
-    bg: 'primary.lighter',
+    bg: 'primary.washActive',
     p: 32,
     textAlign: 'center',
   },

package/src/components/Container/Container.tsx

@@ -1,13 +1,15 @@
 'use client';
-import { Container as ChakraContainer, ContainerProps } from '@chakra-ui/react';
+import { Container as ChakraContainer } from '@chakra-ui/react';
 
+import { polymorphic } from '../../types/polymorphic';
+import { ContainerOwnProps } from './Container.types';
 import useContainerSize from './useContainerSize';
 
-export const Container = ({
+const ContainerImpl = ({
   style,
   disableResponsive,
   ...rest
-}: ContainerProps & { disableResponsive?: boolean }) => {
+}: ContainerOwnProps) => {
   const containerSize = useContainerSize();
   return (
     <ChakraContainer
@@ -19,3 +21,8 @@ export const Container = ({
     />
   );
 };
+
+ContainerImpl.displayName = 'Container';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Container = polymorphic<ContainerOwnProps, 'div'>(ContainerImpl);

package/src/components/Container/Container.types.ts

@@ -0,0 +1,20 @@
+import type { ElementType } from 'react';
+import { ContainerProps as ChakraContainerProps } from '@chakra-ui/react';
+
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+
+export type ContainerOwnProps = Omit<ChakraContainerProps, 'as'> & {
+  /** Skip the responsive `minWidth` this component otherwise applies. */
+  disableResponsive?: boolean;
+};
+
+/**
+ * Props for `Container`, typed for whatever element `as` renders.
+ *
+ * Defaults to `'div'`, so the bare type is unchanged. A page container is
+ * often a landmark — `as="main"` / `as="section"` / `as="nav"` is how it says
+ * so, and KWCAG 반복 영역 건너뛰기 grades that structure.
+ */
+export type ContainerProps<TElement extends ElementType = 'div'> =
+  PolymorphicProps<TElement, ContainerOwnProps>;

package/src/components/Container/index.ts

@@ -1,2 +1,3 @@
 export { Container } from './Container';
+export type { ContainerOwnProps, ContainerProps } from './Container.types';
 export * from './useContainerSize';

package/src/components/CopyableCode/CopyableCode.tsx

@@ -1,14 +1,81 @@
+import { useEffect, useRef, useState } from 'react';
 import { Box, Flex } from '@chakra-ui/react';
 
 import { useTranslate } from '@/hooks/useTranslate';
 
 import { Button } from '../Button';
 import { Card } from '../Card';
-import { FaRegCopy } from '../Icon';
+import { FaCheck, FaRegCopy } from '../Icon';
 import { CopyableCodeProps } from './CopyableCode.types';
+
+/** How long the button stays in its confirmed state before reverting, in ms. */
+const CONFIRM_HOLD_MS = 1600;
+
+/** How far the label sits from the window when it is not the one showing. */
+const LABEL_OFFSET = '8px';
+
+/**
+ * The two clocks a label swap needs: the outgoing label clears fast so the
+ * incoming one is not read through it, while the travel is slow enough to read
+ * as one thing replacing another rather than a flicker.
+ */
+const LABEL_TRANSITION = [
+  'opacity var(--chakra-durations-fast) var(--chakra-easings-standard)',
+  'translate var(--chakra-durations-motion-base) var(--chakra-easings-emphasized)',
+].join(', ');
+
+/**
+ * One of the button's two labels, stacked in the same grid cell as the other.
+ *
+ * Both labels are always in the layout, so the button is as wide as the longer
+ * of them and stops resizing when the state flips. That is the whole point
+ * here: this button is absolutely positioned against the right edge, and
+ * "복사" → "복사 완료" is two characters wider, so growing walked the button
+ * leftwards over the code the moment it was clicked (measured: 59px → 87px).
+ *
+ * Sizing this way rather than with a hand-tuned `minW` means the lock survives
+ * translation, where the longest string is not the one you measured.
+ *
+ * `past` decides which way the label leaves: the idle label has already
+ * happened by the time the confirmation shows, so it leaves upward and the
+ * confirmation rises into its place.
+ */
+const SwapLabel = ({
+  show,
+  past,
+  children,
+}: {
+  show: boolean;
+  past: boolean;
+  children: React.ReactNode;
+}) => (
+  <Box
+    gridArea="1 / 1"
+    display="inline-flex"
+    alignItems="center"
+    justifyContent="center"
+    gap="1.5"
+    whiteSpace="nowrap"
+    opacity={show ? 1 : 0}
+    translate={show ? '0 0' : `0 ${past ? '-' : ''}${LABEL_OFFSET}`}
+    pointerEvents={show ? undefined : 'none'}
+    aria-hidden={!show || undefined}
+    transition={LABEL_TRANSITION}
+    animationStyle="composite"
+  >
+    {children}
+  </Box>
+);
+
 /**
  * Intended for a quick one-click copy of one-liner code snippets.
  *
+ * The button answers for itself: on click the copy icon crosses into a check and
+ * the label flips to "copied", then reverts. Copying is otherwise invisible —
+ * without a reply the member has no way to know it worked and clicks again — and
+ * a global toast is too much ceremony for something this small, so the control
+ * that was pressed is the thing that confirms.
+ *
  * @example
  * <CopyableCode onCopy={() => {}}>
  *   {`const example = 'This is a code example';
@@ -21,6 +88,20 @@ export const CopyableCode = ({
   containerProps,
 }: CopyableCodeProps) => {
   const translate = useTranslate();
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  // The revert fires 1.6s after the click; unmounting in between would leave it
+  // writing into a gone component.
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const handleCopy = () => {
+    onCopy?.();
+    setCopied(true);
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => setCopied(false), CONFIRM_HOLD_MS);
+  };
+
   return (
     <Flex position="relative" width="100%" {...containerProps}>
       <Card overflow="hidden" maxW="100%" p={0} width="100%">
@@ -40,17 +121,30 @@ export const CopyableCode = ({
         />
       </Card>
       <Button
-        colorPalette="primary"
-        variant="solid"
+        variant="primary"
         size="xs"
-        onClick={onCopy}
+        onClick={handleCopy}
         position="absolute"
         right={4}
         top="50%"
         transform="translateY(-50%)"
         zIndex={1}
       >
-        <FaRegCopy boxSize="xs" /> {translate('copy')}
+        {/* Icon *and* label cross together, in one cell — see SwapLabel. The
+            window is what keeps the outgoing label from showing above the
+            button while it fades. */}
+        <Box display="inline-grid" placeItems="center" overflow="hidden">
+          {/* Idle is the earlier state, so it leaves upward and the
+              confirmation rises from below into its place. */}
+          <SwapLabel show={!copied} past>
+            <FaRegCopy boxSize="xs" />
+            {translate('copy')}
+          </SwapLabel>
+          <SwapLabel show={copied} past={false}>
+            <FaCheck boxSize="xs" />
+            {translate('copied')}
+          </SwapLabel>
+        </Box>
       </Button>
     </Flex>
   );

package/src/components/CountBadge/CountBadge.stories.tsx

@@ -0,0 +1,109 @@
+import { Flex, HStack, Text } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+
+import { BellIcon } from '../Icon';
+import { IconButton } from '../IconButton';
+import { CountBadge } from '.';
+
+const meta = {
+  title: 'Components/CountBadge',
+  component: CountBadge,
+  tags: ['autodocs'],
+  args: {
+    count: 5,
+  },
+  argTypes: {
+    count: { control: 'number' },
+    max: { control: 'number' },
+    dot: { control: 'boolean' },
+    showZero: { control: 'boolean' },
+    label: { control: 'text' },
+    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
+  },
+} satisfies Meta<typeof CountBadge>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {};
+
+/** Above `max` (default 99) the badge reads `99+`. */
+export const Capped: Story = {
+  args: { count: 120, label: '읽지 않은 알림 120개' },
+};
+
+/** Count 0 renders nothing unless `showZero`. */
+export const Zero: Story = {
+  render: () => (
+    <HStack gap={4}>
+      <Text textStyle="subtext">count=0 →</Text>
+      <CountBadge count={0} />
+      <Text textStyle="subtext">showZero →</Text>
+      <CountBadge count={0} showZero />
+    </HStack>
+  ),
+};
+
+/** Dot mode: no number. `aria-hidden` unless a `label` is given. */
+export const Dot: Story = {
+  render: () => (
+    <HStack gap={4}>
+      <CountBadge dot size="sm" />
+      <CountBadge dot />
+      <CountBadge dot size="lg" label="새 소식" />
+    </HStack>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <Flex gap={4} align="center">
+      {(['sm', 'md', 'lg'] as const).map((size) => (
+        <HStack key={size} gap={2}>
+          <CountBadge size={size} count={3} />
+          <CountBadge size={size} count={42} />
+          <CountBadge size={size} count={1000} />
+        </HStack>
+      ))}
+    </Flex>
+  ),
+};
+
+/** Next to a label, as in a nav item. */
+export const InContext: Story = {
+  render: () => (
+    <HStack gap={2}>
+      <Text>받은 편지함</Text>
+      <CountBadge count={12} label="읽지 않은 메시지 12개" />
+    </HStack>
+  ),
+};
+
+/**
+ * On an icon-only button the count belongs in the BUTTON's `aria-label`:
+ * that label replaces the button's whole subtree as its accessible name, so a
+ * `label` on the badge would never be announced. The badge stays unlabelled
+ * and is only the visible number.
+ */
+export const OnIconButton: Story = {
+  render: () => {
+    const unread = 5;
+    return (
+      <IconButton
+        aria-label={`알림, 읽지 않음 ${unread}개`}
+        variant="ghost"
+        position="relative"
+      >
+        <BellIcon />
+        <CountBadge
+          count={unread}
+          size="sm"
+          position="absolute"
+          top="-2px"
+          right="-2px"
+        />
+      </IconButton>
+    );
+  },
+};

package/src/components/CountBadge/CountBadge.styles.ts

@@ -0,0 +1,40 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+import type { CountBadgeSize } from './CountBadge.types';
+
+/**
+ * Shared look: the `count.*` pair (coral-red fill, white number), a pill whose
+ * min-width equals its height so a single digit is a circle, and tabular
+ * figures so the width does not jitter as the number changes.
+ */
+export const countBadgeBaseStyles: BoxProps = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  flexShrink: 0,
+  bgColor: 'count.bg',
+  color: 'count.fg',
+  borderRadius: 'full',
+  fontWeight: 'bold',
+  lineHeight: '1',
+  whiteSpace: 'nowrap',
+  fontVariantNumeric: 'tabular-nums',
+};
+
+export const countBadgeSizeStyles: Record<CountBadgeSize, BoxProps> = {
+  sm: { h: '16px', minW: '16px', px: '4px', fontSize: '10px' },
+  md: { h: '18px', minW: '18px', px: '5px', fontSize: '11px' },
+  lg: { h: '22px', minW: '22px', px: '6px', fontSize: '12px' },
+};
+
+export const countBadgeDotSizes: Record<CountBadgeSize, string> = {
+  sm: '6px',
+  md: '8px',
+  lg: '10px',
+};
+
+/** `120, 99 → "99+"`; negative / non-finite → `"0"`. */
+export const formatCount = (count: number, max: number): string => {
+  const safe = Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+  return safe > max ? `${max}+` : String(safe);
+};

package/src/components/CountBadge/CountBadge.test.tsx

@@ -0,0 +1,57 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { CountBadge } from './CountBadge';
+
+const wrap = (ui: React.ReactNode) =>
+  render(<ChakraProvider value={system}>{ui}</ChakraProvider>);
+
+describe('CountBadge', () => {
+  it('renders the count as text', () => {
+    wrap(<CountBadge count={5} data-testid="b" />);
+    expect(screen.getByTestId('b').textContent).toBe('5');
+  });
+
+  it('caps above max (default 99) as "99+"', () => {
+    wrap(<CountBadge count={120} data-testid="b" />);
+    expect(screen.getByTestId('b').textContent).toBe('99+');
+  });
+
+  it('honours a custom max', () => {
+    wrap(<CountBadge count={12} max={9} data-testid="b" />);
+    expect(screen.getByTestId('b').textContent).toBe('9+');
+  });
+
+  it('renders nothing for 0 unless showZero', () => {
+    const { container } = wrap(<CountBadge count={0} />);
+    expect(container.querySelector('[data-count-badge]')).toBeNull();
+
+    wrap(<CountBadge count={0} showZero data-testid="z" />);
+    expect(screen.getByTestId('z').textContent).toBe('0');
+  });
+
+  it('reads the label instead of the bare number', () => {
+    wrap(<CountBadge count={120} label="읽지 않은 알림 120개" />);
+    expect(screen.getByText('읽지 않은 알림 120개')).toBeTruthy();
+    expect(screen.getByText('99+').getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('dot mode renders a hidden dot with no number', () => {
+    wrap(<CountBadge dot count={3} data-testid="d" />);
+    const dot = screen.getByTestId('d');
+    expect(dot.textContent).toBe('');
+    expect(dot.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('dot mode with a label is a named image', () => {
+    wrap(<CountBadge dot label="새 소식" />);
+    expect(screen.getByRole('img', { name: '새 소식' })).toBeTruthy();
+  });
+
+  it('dot mode hides at count 0', () => {
+    const { container } = wrap(<CountBadge dot count={0} />);
+    expect(container.querySelector('[data-count-badge]')).toBeNull();
+  });
+});

package/src/components/CountBadge/CountBadge.tsx

@@ -0,0 +1,112 @@
+import { ForwardedRef, forwardRef } from 'react';
+import { Box } from '@chakra-ui/react';
+
+import {
+  countBadgeBaseStyles,
+  countBadgeDotSizes,
+  countBadgeSizeStyles,
+  formatCount,
+} from './CountBadge.styles';
+import { CountBadgeProps } from './CountBadge.types';
+
+/**
+ * CountBadge — an unread / notification count (moved into the design system
+ * from FactChat's `UnreadCountBadge`).
+ *
+ * - Numeric: `count` as text, capped at `max` (default 99 → `"99+"`). Renders
+ *   nothing for 0 unless `showZero`.
+ * - Dot (`dot`): a small circle with no number. `aria-hidden` unless it is
+ *   given a `label` — then it is an `img` with that name.
+ *
+ * Give it a `label` whenever the number alone would not make sense out of
+ * context and the badge sits in readable content — next to a nav item's
+ * text, in a list row.
+ *
+ * NOT on an icon-only button: the button's `aria-label` replaces its whole
+ * subtree as the accessible name, so the badge's hidden label is never
+ * announced. Put the count in the button's `aria-label` instead and leave
+ * the badge unlabelled (it is then only the visible number):
+ *
+ * ```tsx
+ * <IconButton aria-label={`알림, 읽지 않음 ${n}개`} variant="ghost">
+ *   <BellIcon />
+ *   <CountBadge count={n} position="absolute" top={0} right={0} />
+ * </IconButton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <CountBadge count={5} />
+ * <CountBadge count={120} label="읽지 않은 알림 120개" />   // shows 99+
+ * <CountBadge dot label="새 소식" />
+ * ```
+ */
+export const CountBadge = forwardRef(
+  (
+    {
+      count,
+      max = 99,
+      dot = false,
+      showZero = false,
+      label,
+      size = 'md',
+      'aria-label': ariaLabel,
+      ...rest
+    }: CountBadgeProps,
+    ref?: ForwardedRef<HTMLSpanElement>
+  ) => {
+    const name = label ?? ariaLabel;
+    const isEmpty = (count ?? 0) <= 0;
+
+    if (dot) {
+      if (count !== undefined && isEmpty && !showZero) return null;
+      const dotSize = countBadgeDotSizes[size];
+      return (
+        <Box
+          as="span"
+          display="inline-block"
+          flexShrink={0}
+          boxSize={dotSize}
+          borderRadius="full"
+          bgColor="count.bg"
+          {...(name
+            ? { role: 'img', 'aria-label': name }
+            : { 'aria-hidden': true })}
+          data-count-badge="dot"
+          {...rest}
+          ref={ref}
+        />
+      );
+    }
+
+    if (isEmpty && !showZero) return null;
+
+    const text = formatCount(count ?? 0, max);
+
+    return (
+      <Box
+        as="span"
+        {...countBadgeBaseStyles}
+        {...countBadgeSizeStyles[size]}
+        data-count-badge="count"
+        {...rest}
+        ref={ref}
+      >
+        {name ? (
+          <>
+            <Box as="span" aria-hidden>
+              {text}
+            </Box>
+            <Box as="span" srOnly>
+              {name}
+            </Box>
+          </>
+        ) : (
+          text
+        )}
+      </Box>
+    );
+  }
+);
+
+CountBadge.displayName = 'CountBadge';

package/src/components/CountBadge/CountBadge.types.ts

@@ -0,0 +1,34 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export type CountBadgeSize = 'sm' | 'md' | 'lg';
+
+export type CountBadgeProps = Omit<BoxProps, 'children'> & {
+  /**
+   * The number to show. In numeric mode a count of 0 (or less, or missing)
+   * renders nothing unless `showZero`. In dot mode a count is optional — pass
+   * one to hide the dot when it reaches 0.
+   */
+  count?: number;
+  /**
+   * Largest number shown as-is; anything above renders as `"{max}+"`.
+   * @default 99
+   */
+  max?: number;
+  /** Dot mode: a small circle with no number ("something new"). */
+  dot?: boolean;
+  /** Render `0` (numeric) / the dot (dot mode) even when `count` is 0. */
+  showZero?: boolean;
+  /**
+   * Accessible name. In numeric mode it is read INSTEAD of the bare number
+   * (e.g. "읽지 않은 알림 120개" rather than "99+"); in dot mode it is what
+   * makes the dot visible to assistive tech at all — without it the dot is
+   * `aria-hidden`. `aria-label` is accepted as an alias.
+   *
+   * Inside an element that has its own `aria-label` (an icon-only button) it
+   * is never announced — that `aria-label` replaces the subtree. Put the
+   * count in the button's `aria-label` there instead.
+   */
+  label?: string;
+  /** @default 'md' */
+  size?: CountBadgeSize;
+};

package/src/components/CountBadge/index.ts

@@ -0,0 +1,2 @@
+export { CountBadge } from './CountBadge';
+export type { CountBadgeProps, CountBadgeSize } from './CountBadge.types';