@mks2508/mks-ui 0.2.0 → 0.3.1

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

@@ -0,0 +1,421 @@
+'use client';
+
+/**
+ * Tabs component -- animated tab navigation built on base-ui Tabs
+ * with motion transitions, highlight tracking, auto-height panels,
+ * and the v0.2.0 slot system.
+ *
+ * Provides sub-components for the tab list, individual tabs, panels,
+ * animated highlight indicators, and a panels container with two modes:
+ * auto-height (ResizeObserver) and layout (Motion layout animation).
+ *
+ * @module @mks2508/mks-ui/react/ui/Tabs
+ *
+ * @example
+ * ```tsx
+ * <Tabs defaultValue="general" slots={{ list: 'flex gap-1 border-b' }}>
+ *   <TabsList>
+ *     <TabsHighlight className="rounded-md bg-white/10">
+ *       <TabsHighlightItem value="general">
+ *         <TabsTab value="general">General</TabsTab>
+ *       </TabsHighlightItem>
+ *       <TabsHighlightItem value="advanced">
+ *         <TabsTab value="advanced">Advanced</TabsTab>
+ *       </TabsHighlightItem>
+ *     </TabsHighlight>
+ *   </TabsList>
+ *   <TabsPanels>
+ *     <TabsPanel value="general">General content</TabsPanel>
+ *     <TabsPanel value="advanced">Advanced content</TabsPanel>
+ *   </TabsPanels>
+ * </Tabs>
+ * ```
+ */
+
+import * as React from 'react';
+import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
+import {
+  motion,
+  AnimatePresence,
+  type Transition,
+} from 'motion/react';
+
+import {
+  Highlight,
+  HighlightItem,
+} from '@/react-ui/primitives/Highlight';
+import { AutoHeight } from '@/react-ui/primitives/AutoHeight';
+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 { tabsStyles } from './Tabs.styles';
+
+import type {
+  TabsContextType,
+  ITabsProps,
+  ITabsHighlightProps,
+  ITabsHighlightItemProps,
+  ITabsListProps,
+  ITabsTabProps,
+  ITabsPanelProps,
+  ITabsPanelsProps,
+  ITabsPanelsAutoProps,
+} from './Tabs.types';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const [TabsProvider, useTabs] =
+  getStrictContext<TabsContextType>('TabsContext');
+
+// ---------------------------------------------------------------------------
+// Tabs (Root)
+// ---------------------------------------------------------------------------
+
+/**
+ * Root Tabs component -- provides active tab value context and
+ * controlled/uncontrolled state management.
+ *
+ * @param value - Controlled active tab value
+ * @param defaultValue - Uncontrolled initial active tab value
+ * @param onValueChange - Callback when active tab changes
+ * @param slots - Partial class overrides per slot
+ * @param config - Tabs behavior / animation configuration
+ *
+ * @example
+ * ```tsx
+ * <Tabs defaultValue="general" slots={{ root: 'w-full' }}>
+ *   <TabsList>...</TabsList>
+ *   <TabsPanels>...</TabsPanels>
+ * </Tabs>
+ * ```
+ */
+function Tabs({ slots, config, className, ...props }: ITabsProps) {
+  const [value, setValue] = useControlledState({
+    value: props.value,
+    defaultValue: props.defaultValue,
+    onChange: props.onValueChange,
+  });
+
+  return (
+    <TabsProvider value={{ value, setValue }}>
+      <TabsPrimitive.Root
+        data-slot="tabs"
+        className={cn(tabsStyles.root, slots?.root, className)}
+        {...props}
+        onValueChange={setValue}
+      />
+    </TabsProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsHighlight
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsHighlight -- animated background indicator that follows the active tab.
+ * Wraps the Highlight primitive with tab-specific defaults (spring transition,
+ * no click activation since tabs manage their own active state).
+ *
+ * @param transition - Motion transition config (default: spring 200/25)
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlight className="rounded-md bg-white/10">
+ *   <TabsHighlightItem value="tab1">
+ *     <TabsTab value="tab1">Tab 1</TabsTab>
+ *   </TabsHighlightItem>
+ * </TabsHighlight>
+ * ```
+ */
+function TabsHighlight({
+  transition = { type: 'spring', stiffness: 200, damping: 25 },
+  slots,
+  className,
+  ...props
+}: ITabsHighlightProps) {
+  const { value } = useTabs();
+
+  return (
+    <Highlight
+      data-slot="tabs-highlight"
+      controlledItems
+      value={value}
+      transition={transition}
+      click={false}
+      className={cn(tabsStyles.highlight, slots?.highlight, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsList
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsList -- the container holding tab trigger buttons.
+ * Renders a base-ui Tabs.List with the `list` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsList className="flex gap-1 border-b border-white/10 pb-1">
+ *   <TabsTab value="general">General</TabsTab>
+ *   <TabsTab value="advanced">Advanced</TabsTab>
+ * </TabsList>
+ * ```
+ */
+function TabsList({ slots, className, ...props }: ITabsListProps) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      className={cn(tabsStyles.list, slots?.list, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsHighlightItem
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsHighlightItem -- wraps a TabsTab for highlight position tracking.
+ * Must be placed inside a TabsHighlight context. The `value` prop should
+ * match the corresponding TabsTab value.
+ *
+ * @param value - Tab value this highlight item corresponds to
+ * @param slots - Partial class overrides per slot
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlightItem value="general">
+ *   <TabsTab value="general">General</TabsTab>
+ * </TabsHighlightItem>
+ * ```
+ */
+function TabsHighlightItem({ slots, ...props }: ITabsHighlightItemProps) {
+  return <HighlightItem data-slot="tabs-highlight-item" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// TabsTab
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsTab -- a single tab trigger button that activates its panel.
+ * Renders a base-ui Tabs.Tab with the `tab` slot classes.
+ *
+ * @param value - The value this tab represents
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsTab value="general" className="px-3 py-1.5 text-sm font-medium">
+ *   General
+ * </TabsTab>
+ * ```
+ */
+function TabsTab({ slots, className, ...props }: ITabsTabProps) {
+  return (
+    <TabsPrimitive.Tab
+      data-slot="tabs-tab"
+      className={cn(tabsStyles.tab, slots?.tab, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsPanel
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsPanel -- an animated content panel associated with a tab.
+ * Uses Motion for blur + opacity enter/exit transitions wrapped in
+ * AnimatePresence for smooth unmount animations.
+ *
+ * @param value - The tab value this panel corresponds to
+ * @param keepMounted - Keep the panel in DOM when inactive
+ * @param transition - Motion transition config (default: 0.5s easeInOut)
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsPanel value="general" className="p-4">
+ *   <h2>General Settings</h2>
+ *   <p>Configure your preferences here.</p>
+ * </TabsPanel>
+ * ```
+ */
+function TabsPanel({
+  value,
+  keepMounted,
+  transition = { duration: 0.5, ease: 'easeInOut' },
+  slots,
+  className,
+  ...props
+}: ITabsPanelProps) {
+  return (
+    <AnimatePresence mode="wait">
+      <TabsPrimitive.Panel
+        render={
+          <motion.div
+            data-slot="tabs-panel"
+            layout
+            layoutDependency={value}
+            initial={{ opacity: 0, filter: 'blur(4px)' }}
+            animate={{ opacity: 1, filter: 'blur(0px)' }}
+            exit={{ opacity: 0, filter: 'blur(4px)' }}
+            transition={transition}
+            className={cn(tabsStyles.panel, slots?.panel, className)}
+            {...(props as any)}
+          />
+        }
+        keepMounted={keepMounted}
+        value={value}
+      />
+    </AnimatePresence>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsPanels
+// ---------------------------------------------------------------------------
+
+/** Default spring transition for the panels container. */
+const defaultPanelsTransition: Transition = {
+  type: 'spring',
+  stiffness: 200,
+  damping: 30,
+};
+
+/**
+ * Type guard to distinguish auto-height mode from layout mode.
+ *
+ * @param props - TabsPanels props union
+ * @returns True if auto-height mode (default)
+ */
+function isAutoMode(props: ITabsPanelsProps): props is ITabsPanelsAutoProps {
+  return !props.mode || props.mode === 'auto-height';
+}
+
+/**
+ * TabsPanels -- container for tab panels with animated height transitions.
+ * Supports two modes:
+ *
+ * - **auto-height** (default): Uses ResizeObserver to animate container
+ *   height when panels have different content sizes.
+ * - **layout**: Uses Motion layout animation for size transitions,
+ *   with overflow hidden.
+ *
+ * @param mode - Animation mode: 'auto-height' (default) or 'layout'
+ * @param transition - Motion transition config
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * // Auto-height mode (default)
+ * <TabsPanels>
+ *   <TabsPanel value="short">Short content</TabsPanel>
+ *   <TabsPanel value="long">Much longer content with many paragraphs...</TabsPanel>
+ * </TabsPanels>
+ *
+ * // Layout mode
+ * <TabsPanels mode="layout" className="rounded-lg">
+ *   <TabsPanel value="a">Content A</TabsPanel>
+ *   <TabsPanel value="b">Content B</TabsPanel>
+ * </TabsPanels>
+ * ```
+ */
+function TabsPanels(props: ITabsPanelsProps) {
+  const { value } = useTabs();
+
+  if (isAutoMode(props)) {
+    const {
+      children,
+      transition = defaultPanelsTransition,
+      slots,
+      className,
+      mode: _mode,
+      ...autoProps
+    } = props;
+
+    return (
+      <AutoHeight
+        data-slot="tabs-panels"
+        deps={[value]}
+        transition={transition}
+        className={cn(tabsStyles.panels, slots?.panels, className)}
+        {...autoProps}
+      >
+        <React.Fragment key={value}>{children}</React.Fragment>
+      </AutoHeight>
+    );
+  }
+
+  const {
+    children,
+    style,
+    transition = defaultPanelsTransition,
+    slots,
+    className,
+    mode: _mode,
+    ...layoutProps
+  } = props;
+
+  return (
+    <motion.div
+      data-slot="tabs-panels"
+      layout="size"
+      layoutDependency={value}
+      transition={{ layout: transition }}
+      style={{ overflow: 'hidden', ...style }}
+      className={cn(tabsStyles.panels, slots?.panels, className)}
+      {...layoutProps}
+    >
+      <React.Fragment key={value}>{children}</React.Fragment>
+    </motion.div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export {
+  Tabs,
+  TabsHighlight,
+  TabsHighlightItem,
+  TabsList,
+  TabsTab,
+  TabsPanel,
+  TabsPanels,
+};
+
+// Re-export all types
+export type {
+  ITabsProps,
+  ITabsHighlightProps,
+  ITabsHighlightItemProps,
+  ITabsListProps,
+  ITabsTabProps,
+  ITabsPanelProps,
+  ITabsPanelsProps,
+  ITabsPanelsAutoProps,
+  ITabsPanelsLayoutProps,
+  ITabsConfig,
+  TabsContextType,
+} from './Tabs.types';
+
+export type { TabsSlot } from './Tabs.styles';

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;
+}