@mks2508/mks-ui 0.2.1 → 0.3.1

package/src/react-ui/ui/TextFlow/TextFlow.styles.ts

@@ -0,0 +1,36 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/**
+ * Style slots for TextFlow component
+ */
+export type TextFlowSlot = 'root' | 'token' | 'separator' | 'overflow' | 'placeholder';
+
+/**
+ * Base styles for TextFlow component
+ */
+export const textFlowBaseStyles: StyleSlots<TextFlowSlot> = {
+  root: 'waapi-animated-tokens-container',
+  token: 'waapi-token-wrapper',
+  separator: 'waapi-token-separator',
+  overflow: 'waapi-token-overflow',
+  placeholder: 'waapi-token-placeholder',
+};
+
+/**
+ * CVA variants for TextFlow root container
+ */
+export const textFlowVariants = cva({
+  base: 'waapi-animated-tokens-container',
+  variants: {
+    inline: {
+      true: 'waapi-animated-tokens-container--inline',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    inline: false,
+  },
+});
+
+export type TextFlowVariants = VariantProps<typeof textFlowVariants>;

package/src/react-ui/ui/TextFlow/TextFlow.types.ts

@@ -0,0 +1,118 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * Token individual para TextFlow
+ */
+export interface IToken {
+  /** Identificador único del token */
+  id: string;
+  /** Texto a mostrar */
+  text: string;
+}
+
+/**
+ * Modo de transición para cambios de texto en separadores
+ */
+export type SeparatorTransitionMode = 'none' | 'fade' | 'slide';
+
+/**
+ * Tipos de lista para Intl.ListFormat
+ */
+export type ListFormatType = 'conjunction' | 'disjunction' | 'unit';
+
+/**
+ * Estilos de lista para Intl.ListFormat
+ */
+export type ListFormatStyle = 'long' | 'short' | 'narrow';
+
+/**
+ * Configuración de separadores entre tokens
+ */
+export interface ISeparatorConfig {
+  /** Texto del separador. Si se omite, usa Intl.ListFormat */
+  value?: string;
+  /** Locale para Intl.ListFormat */
+  locale?: string;
+  /** Tipo de lista para Intl.ListFormat */
+  listType?: ListFormatType;
+  /** Estilo de lista para Intl.ListFormat */
+  listStyle?: ListFormatStyle;
+  /** Modo de transición cuando el texto del separador cambia */
+  transition?: SeparatorTransitionMode;
+  /** Duración de la transición en ms */
+  duration?: number;
+  /** Clase CSS adicional para separadores */
+  className?: string;
+}
+
+/**
+ * Configuración del indicador de overflow (+N more)
+ */
+export interface IOverflowConfig {
+  /** Prefijo antes del número */
+  prefix?: string;
+  /** Texto después del número */
+  label?: string;
+  /** Separador mostrado antes del overflow */
+  separator?: string;
+  /** Mostrar separador antes del overflow */
+  showSeparator?: boolean;
+  /** Clase CSS adicional para el overflow */
+  className?: string;
+}
+
+/**
+ * Configuración de animación de texto
+ */
+export interface ITextAnimationConfig {
+  /** Modo de animación del texto */
+  mode?: 'character' | 'word';
+  /** Dirección de entrada del texto */
+  direction?: 'vertical' | 'horizontal';
+  /** Delay entre caracteres/palabras en ms */
+  stagger?: number;
+  /** Duración de animación en ms */
+  duration?: number;
+  /** Habilitar efecto blur durante animación */
+  blur?: boolean;
+  /** Animar cambios de ancho del contenedor */
+  widthAnimation?: boolean;
+}
+
+/**
+ * Props for TextFlow component
+ *
+ * TextFlow renders an animated list of tokens with locale-aware separators,
+ * smooth FLIP animations, and overflow handling.
+ */
+export interface ITextFlowProps {
+  /** Array de tokens a mostrar */
+  tokens: IToken[];
+
+  /** Texto placeholder cuando no hay tokens */
+  placeholder?: string;
+
+  /** Máximo de tokens visibles. El resto se muestra como "+N" */
+  maxVisible?: number;
+
+  /** Configuración de separadores */
+  separator?: ISeparatorConfig;
+
+  /** Configuración del indicador de overflow */
+  overflow?: IOverflowConfig;
+
+  /** Configuración de animación de texto */
+  animation?: ITextAnimationConfig;
+
+  /** Modo inline para uso en botones/selects */
+  inline?: boolean;
+
+  /** Clase CSS para el contenedor principal */
+  className?: string;
+
+  /** Clase CSS para cada token */
+  tokenClassName?: string;
+
+  /** Clase CSS para el placeholder */
+  placeholderClassName?: string;
+}

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/index.ts

@@ -31,4 +31,7 @@ export * from './InputGroup';
 export * from './Label';
 export * from './Select';
 export * from './Separator';
-export * from './Textarea';
+export * from './DataCard';
+
+// WAAPI-based components
+export * from './TextFlow';