@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/ui/TextFlow/index.tsx

@@ -0,0 +1,276 @@
+"use client";
+
+import React, { useMemo, useCallback } from 'react';
+import { SlidingText } from '@/react-ui/primitives/waapi/SlidingText';
+import { Reorder } from '@/react-ui/primitives/waapi/Reorder';
+import { useListFormat } from '@/react-ui/hooks/Formatting/UseListFormat';
+import type {
+  ITextFlowProps,
+  IToken,
+  ISeparatorConfig,
+  IOverflowConfig,
+  ITextAnimationConfig,
+  SeparatorTransitionMode,
+  ListFormatType,
+  ListFormatStyle,
+} from './TextFlow.types';
+import { cn } from '@/react-ui/lib/utils';
+
+// Default configurations
+const DEFAULT_SEPARATOR: Required<Omit<ISeparatorConfig, 'value' | 'locale' | 'className'>> = {
+  listType: 'conjunction',
+  listStyle: 'long',
+  transition: 'none',
+  duration: 200,
+};
+
+const DEFAULT_OVERFLOW: Required<Omit<IOverflowConfig, 'separator' | 'className'>> = {
+  prefix: '+',
+  label: ' more',
+  showSeparator: true,
+};
+
+const DEFAULT_ANIMATION: Required<ITextAnimationConfig> = {
+  mode: 'character',
+  direction: 'vertical',
+  stagger: 15,
+  duration: 200,
+  blur: true,
+  widthAnimation: false,
+};
+
+/**
+ * TextFlow - Locale-aware animated token list component
+ *
+ * Built on the Reorder primitive, provides smooth FLIP animations for token lists
+ * with proper locale-aware separators using Intl.ListFormat.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <TextFlow tokens={tokens} />
+ *
+ * // Spanish multiselect with transition
+ * <TextFlow
+ *   tokens={tokens}
+ *   maxVisible={2}
+ *   inline
+ *   separator={{ locale: 'es', transition: 'fade' }}
+ *   overflow={{ prefix: '+', label: ' más' }}
+ * />
+ * ```
+ */
+export const TextFlow: React.FC<ITextFlowProps> = ({
+  tokens,
+  placeholder = 'No tokens',
+  maxVisible,
+  separator: separatorConfig,
+  overflow: overflowConfig,
+  animation: animationConfig,
+  inline = false,
+  className = '',
+  tokenClassName = '',
+  placeholderClassName = '',
+}) => {
+  // Merge configs with defaults
+  const separator: Required<Omit<ISeparatorConfig, 'value' | 'locale' | 'className'>> & Pick<ISeparatorConfig, 'value' | 'locale' | 'className'> = {
+    ...DEFAULT_SEPARATOR,
+    ...separatorConfig,
+  };
+
+  const overflow: Required<Omit<IOverflowConfig, 'separator' | 'className'>> & Pick<IOverflowConfig, 'separator' | 'className'> = {
+    ...DEFAULT_OVERFLOW,
+    ...overflowConfig,
+  };
+
+  const animation: Required<ITextAnimationConfig> = {
+    ...DEFAULT_ANIMATION,
+    ...animationConfig,
+  };
+
+  // Track exiting token IDs with REF
+  const exitingIdsRef = React.useRef<Set<string>>(new Set());
+
+  // Visible tokens
+  const visibleTokens = useMemo(
+    () => (maxVisible ? tokens.slice(0, maxVisible) : tokens),
+    [tokens, maxVisible]
+  );
+
+  const overflowCount = useMemo(
+    () => (maxVisible ? Math.max(0, tokens.length - maxVisible) : 0),
+    [tokens.length, maxVisible]
+  );
+
+  // Locale-aware list formatting via useListFormat hook
+  const listParts = useListFormat(
+    visibleTokens.map(t => t.text),
+    {
+      locale: separator.locale,
+      type: separator.listType,
+      style: separator.listStyle,
+      separator: separator.value,
+      hasOverflow: overflowCount > 0,
+    }
+  );
+
+  // Separator visibility logic
+  const shouldShowSeparator = useCallback((tokenIndex: number): boolean => {
+    const isLastToken = tokenIndex >= visibleTokens.length - 1;
+    return !isLastToken;
+  }, [visibleTokens.length]);
+
+  const handleItemExit = useCallback((id: string) => {
+    exitingIdsRef.current.add(id);
+  }, []);
+
+  const handleItemEnter = useCallback((id: string) => {
+    // Animation triggered automatically
+  }, []);
+
+  const showPlaceholder = tokens.length === 0 && !!placeholder;
+
+  // Build children from list parts
+  const tokenElements = useMemo(() => {
+    let elementIndex = 0;
+
+    return listParts.map((part, partIndex) => {
+      if (part.type === 'element') {
+        const token = visibleTokens[part.index];
+        if (!token) return null;
+
+        const isExiting = exitingIdsRef.current.has(token.id);
+        elementIndex++;
+
+        return (
+          <span
+            key={token.id}
+            className={cn('waapi-token-wrapper', tokenClassName)}
+            data-reorder-id={token.id}
+          >
+            <SlidingText
+              text={token.text}
+              mode={isExiting ? 'none' : animation.mode}
+              direction={animation.direction}
+              staggerDelay={animation.stagger}
+              duration={animation.duration}
+              blur={animation.blur}
+              widthAnimation={!isExiting && animation.widthAnimation}
+              initial={isExiting ? false : 'initial'}
+              animate="animate"
+            />
+          </span>
+        );
+      }
+
+      // Separator (literal)
+      const prevToken = visibleTokens[part.index];
+      if (!prevToken) return null;
+
+      const tokenIndex = part.index;
+      const showSep = shouldShowSeparator(tokenIndex);
+
+      if (!showSep) return null;
+
+      const separatorKey = `sep-${prevToken.id}`;
+
+      return (
+        <span
+          key={separatorKey}
+          className={cn('waapi-token-separator', separator.className ?? '')}
+        >
+          {part.value}
+        </span>
+      );
+    }).filter(Boolean);
+  }, [listParts, visibleTokens, tokenClassName, animation, separator, shouldShowSeparator]);
+
+  // Overflow element
+  const overflowElement = useMemo(() => {
+    if (overflowCount === 0) return null;
+
+    return (
+      <div
+        key="overflow-counter"
+        data-reorder-id="overflow-counter"
+        className={cn('waapi-token-overflow', overflow.className ?? '')}
+      >
+        {overflow.showSeparator && overflow.separator && (
+          <span className={cn('waapi-token-separator', separator.className ?? '')}>
+            {overflow.separator}
+          </span>
+        )}
+        {overflow.prefix !== '' && (
+          <span className={cn('waapi-token-separator', separator.className ?? '')}>
+            {overflow.prefix}
+          </span>
+        )}
+        <SlidingText
+          text={String(overflowCount)}
+          mode="character"
+          duration={animation.duration}
+          blur={animation.blur}
+          initial="initial"
+          animate="animate"
+        />
+        {overflow.label && overflow.label !== '' && (
+          <SlidingText
+            text={overflow.label}
+            mode={animation.mode}
+            direction={animation.direction}
+            staggerDelay={animation.stagger}
+            duration={animation.duration}
+            blur={animation.blur}
+            initial="initial"
+            animate="animate"
+          />
+        )}
+      </div>
+    );
+  }, [overflowCount, overflow, separator, animation]);
+
+  return (
+    <div
+      role="text"
+      className={cn(
+        'waapi-animated-tokens-container',
+        inline && 'waapi-animated-tokens-container--inline',
+        className
+      )}
+    >
+      {showPlaceholder && (
+        <SlidingText
+          key="placeholder"
+          text={placeholder}
+          mode="word"
+          direction="vertical"
+          blur={true}
+          duration={150}
+          initial="initial"
+          animate="animate"
+          className={cn('waapi-token-placeholder', placeholderClassName)}
+        />
+      )}
+
+      <Reorder
+        layout={inline ? 'inline-horizontal' : 'horizontal'}
+        onItemExit={handleItemExit}
+        onItemEnter={handleItemEnter}
+      >
+        {tokenElements}
+        {overflowElement}
+      </Reorder>
+    </div>
+  );
+};
+
+TextFlow.displayName = 'TextFlow';
+
+export type {
+  ITextFlowProps,
+  IToken,
+  ISeparatorConfig,
+  IOverflowConfig,
+  ITextAnimationConfig,
+  SeparatorTransitionMode,
+};

package/src/react-ui/ui/Textarea/index.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+import { cn } from '@/react-ui/lib/utils';
+import { textareaStyles } from './Textarea.styles';
+import type { ITextareaProps } from './Textarea.types';
+
+/**
+ * Textarea — styled multi-line text input.
+ *
+ * @example
+ * ```tsx
+ * <Textarea placeholder="Enter description..." />
+ * ```
+ */
+function Textarea({ className, slots, ...props }: ITextareaProps) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(textareaStyles.root, slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+export { Textarea };
+export type { ITextareaProps } from './Textarea.types';
+export type { TextareaSlot } from './Textarea.styles';

package/src/react-ui/ui/Tooltip/index.tsx

@@ -0,0 +1,394 @@
+'use client';
+
+/**
+ * Animated Tooltip component built on Base UI Tooltip and Motion.
+ *
+ * Provides a positioned tooltip with scale entrance animation,
+ * optional cursor-following via spring-animated motion values,
+ * arrow support, and full AnimatePresence exit transitions.
+ * All sub-components accept a `slots` prop for class-name overrides
+ * following the StyleSlots pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui/Tooltip
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   TooltipProvider,
+ *   Tooltip,
+ *   TooltipTrigger,
+ *   TooltipPortal,
+ *   TooltipPositioner,
+ *   TooltipPopup,
+ *   TooltipArrow,
+ * } from '@mks2508/mks-ui';
+ *
+ * function Example() {
+ *   return (
+ *     <TooltipProvider>
+ *       <Tooltip followCursor="x">
+ *         <TooltipTrigger>
+ *           <button>Hover me</button>
+ *         </TooltipTrigger>
+ *         <TooltipPortal>
+ *           <TooltipPositioner sideOffset={4}>
+ *             <TooltipPopup>
+ *               <TooltipArrow />
+ *               Helpful information
+ *             </TooltipPopup>
+ *           </TooltipPositioner>
+ *         </TooltipPortal>
+ *       </Tooltip>
+ *     </TooltipProvider>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
+import {
+  AnimatePresence,
+  motion,
+  useMotionValue,
+  useSpring,
+} from 'motion/react';
+
+import { getStrictContext } from '@/react-ui/lib/get-strict-context';
+import { useControlledState } from '@/react-ui/hooks/State/UseControlledState';
+import { cn } from '@/react-ui/lib/utils';
+
+import { tooltipStyles } from './Tooltip.styles';
+import type {
+  TooltipContextType,
+  ITooltipProps,
+  ITooltipProviderProps,
+  ITooltipTriggerProps,
+  ITooltipPortalProps,
+  ITooltipPositionerProps,
+  ITooltipPopupProps,
+  ITooltipArrowProps,
+} from './Tooltip.types';
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const [LocalTooltipProvider, useTooltip] =
+  getStrictContext<TooltipContextType>('TooltipContext');
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipProvider                                                           */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Shared configuration provider for a group of tooltips.
+ * Sets defaults like delay, skip-delay, and close-delay for all nested Tooltips.
+ *
+ * @param props - Provider props forwarded to Base UI Tooltip.Provider
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider delay={200}>
+ *   <Tooltip>...</Tooltip>
+ *   <Tooltip>...</Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+function TooltipProvider({ slots: _slots, ...props }: ITooltipProviderProps) {
+  return (
+    <TooltipPrimitive.Provider data-slot="tooltip-provider" {...props} />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Tooltip (Root)                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Root Tooltip component.
+ * Manages controlled/uncontrolled open state, cursor-following motion values,
+ * and provides context to children.
+ *
+ * @param props - Tooltip root props including `followCursor` and spring options
+ *
+ * @example
+ * ```tsx
+ * <Tooltip followCursor="x" followCursorSpringOptions={{ stiffness: 300 }}>
+ *   <TooltipTrigger>Hover</TooltipTrigger>
+ *   <TooltipPortal>
+ *     <TooltipPositioner>
+ *       <TooltipPopup>Content</TooltipPopup>
+ *     </TooltipPositioner>
+ *   </TooltipPortal>
+ * </Tooltip>
+ * ```
+ */
+function Tooltip({
+  followCursor = false,
+  followCursorSpringOptions = { stiffness: 200, damping: 17 },
+  slots,
+  config: _config,
+  ...props
+}: ITooltipProps) {
+  const [isOpen, setIsOpen] = useControlledState({
+    value: props?.open,
+    defaultValue: props?.defaultOpen,
+    onChange: props?.onOpenChange,
+  });
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+
+  return (
+    <LocalTooltipProvider
+      value={{
+        isOpen,
+        setIsOpen,
+        x,
+        y,
+        followCursor,
+        followCursorSpringOptions,
+      }}
+    >
+      <TooltipPrimitive.Root
+        data-slot="tooltip"
+        {...props}
+        onOpenChange={setIsOpen}
+      />
+    </LocalTooltipProvider>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipTrigger                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Trigger element that shows the tooltip on hover/focus.
+ * Tracks mouse position when `followCursor` is enabled on the parent Tooltip.
+ *
+ * @param props - Trigger props forwarded to Base UI Tooltip.Trigger
+ *
+ * @example
+ * ```tsx
+ * <TooltipTrigger>
+ *   <button>Hover me</button>
+ * </TooltipTrigger>
+ * ```
+ */
+function TooltipTrigger({
+  onMouseMove,
+  slots,
+  className,
+  ...props
+}: ITooltipTriggerProps) {
+  const { x, y, followCursor } = useTooltip();
+
+  const handleMouseMove = (
+    event: Parameters<NonNullable<ITooltipTriggerProps['onMouseMove']>>[0],
+  ) => {
+    onMouseMove?.(event);
+
+    const target = event.currentTarget.getBoundingClientRect();
+
+    if (followCursor === 'x' || followCursor === true) {
+      const eventOffsetX = event.clientX - target.left;
+      const offsetXFromCenter = (eventOffsetX - target.width / 2) / 2;
+      x.set(offsetXFromCenter);
+    }
+
+    if (followCursor === 'y' || followCursor === true) {
+      const eventOffsetY = event.clientY - target.top;
+      const offsetYFromCenter = (eventOffsetY - target.height / 2) / 2;
+      y.set(offsetYFromCenter);
+    }
+  };
+
+  return (
+    <TooltipPrimitive.Trigger
+      data-slot="tooltip-trigger"
+      className={cn(tooltipStyles.trigger, slots?.trigger, className)}
+      onMouseMove={handleMouseMove}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPortal                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Portal wrapper with AnimatePresence for coordinated enter/exit animations.
+ * Internally sets `keepMounted` so motion exit animations play correctly.
+ *
+ * @param props - Portal props (without keepMounted)
+ *
+ * @example
+ * ```tsx
+ * <TooltipPortal>
+ *   <TooltipPositioner>
+ *     <TooltipPopup>...</TooltipPopup>
+ *   </TooltipPositioner>
+ * </TooltipPortal>
+ * ```
+ */
+function TooltipPortal({ slots: _slots, ...props }: ITooltipPortalProps) {
+  const { isOpen } = useTooltip();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <TooltipPrimitive.Portal
+          keepMounted
+          data-slot="tooltip-portal"
+          {...props}
+        />
+      )}
+    </AnimatePresence>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPositioner                                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Positioning wrapper that automatically places the popup relative to the trigger.
+ *
+ * @param props - Positioner props forwarded to Base UI Tooltip.Positioner
+ *
+ * @example
+ * ```tsx
+ * <TooltipPositioner sideOffset={4}>
+ *   <TooltipPopup>Content</TooltipPopup>
+ * </TooltipPositioner>
+ * ```
+ */
+function TooltipPositioner({
+  slots,
+  className,
+  ...props
+}: ITooltipPositionerProps) {
+  return (
+    <TooltipPrimitive.Positioner
+      data-slot="tooltip-positioner"
+      className={cn(tooltipStyles.positioner, slots?.positioner, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPopup                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Main tooltip content container with scale entrance animation.
+ * Supports spring-animated cursor-following when `followCursor` is enabled
+ * on the parent Tooltip.
+ *
+ * @param props - Popup props including motion transition overrides
+ *
+ * @example
+ * ```tsx
+ * <TooltipPopup slots={{ popup: 'bg-primary text-primary-foreground' }}>
+ *   Helpful information
+ * </TooltipPopup>
+ * ```
+ */
+function TooltipPopup({
+  transition = { type: 'spring', stiffness: 300, damping: 25 },
+  style,
+  slots,
+  className,
+  ...props
+}: ITooltipPopupProps) {
+  const { x, y, followCursor, followCursorSpringOptions } = useTooltip();
+  const translateX = useSpring(x, followCursorSpringOptions);
+  const translateY = useSpring(y, followCursorSpringOptions);
+
+  return (
+    <TooltipPrimitive.Popup
+      render={
+        <motion.div
+          key="tooltip-popup"
+          data-slot="tooltip-popup"
+          className={cn(tooltipStyles.popup, slots?.popup, className)}
+          initial={{ opacity: 0, scale: 0.5 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.5 }}
+          transition={transition}
+          style={{
+            x:
+              followCursor === 'x' || followCursor === true
+                ? translateX
+                : undefined,
+            y:
+              followCursor === 'y' || followCursor === true
+                ? translateY
+                : undefined,
+            ...style,
+          }}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipArrow                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Directional arrow pointing toward the trigger element.
+ *
+ * @param props - Arrow props forwarded to Base UI Tooltip.Arrow
+ *
+ * @example
+ * ```tsx
+ * <TooltipArrow slots={{ arrow: 'fill-primary' }} />
+ * ```
+ */
+function TooltipArrow({ slots, className, ...props }: ITooltipArrowProps) {
+  return (
+    <TooltipPrimitive.Arrow
+      data-slot="tooltip-arrow"
+      className={cn(tooltipStyles.arrow, slots?.arrow, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Exports                                                                   */
+/* -------------------------------------------------------------------------- */
+
+export {
+  TooltipProvider,
+  Tooltip,
+  TooltipTrigger,
+  TooltipPortal,
+  TooltipPositioner,
+  TooltipPopup,
+  TooltipArrow,
+  useTooltip,
+};
+
+// Re-exports from types
+export type {
+  ITooltipProviderProps,
+  ITooltipProps,
+  ITooltipTriggerProps,
+  ITooltipPortalProps,
+  ITooltipPositionerProps,
+  ITooltipPopupProps,
+  ITooltipArrowProps,
+  TooltipContextType,
+  TooltipSlot,
+  ITooltipConfig,
+} from './Tooltip.types';
+
+// Re-exports from styles
+export { tooltipStyles } from './Tooltip.styles';