@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/primitives/Highlight/index.tsx

@@ -0,0 +1,577 @@
+'use client';
+
+import * as React from 'react';
+import { AnimatePresence, motion, type Transition } from 'motion/react';
+
+import { cn } from '@/react-ui/lib/utils';
+import type {
+  Bounds,
+  HighlightContextType,
+  IHighlightProps,
+  IHighlightItemProps,
+  ParentModeHighlightProps,
+  ExtendedChildProps,
+} from './Highlight.types';
+
+const DEFAULT_BOUNDS_OFFSET: Bounds = {
+  top: 0,
+  left: 0,
+  width: 0,
+  height: 0,
+};
+
+const HighlightContext = React.createContext<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  HighlightContextType<any> | undefined
+>(undefined);
+
+/**
+ * Hook to access the Highlight context.
+ * Must be used within a Highlight provider.
+ *
+ * @returns The current highlight context
+ */
+function useHighlight<T extends string>(): HighlightContextType<T> {
+  const context = React.useContext(HighlightContext);
+  if (!context) {
+    throw new Error('useHighlight must be used within a HighlightProvider');
+  }
+  return context as unknown as HighlightContextType<T>;
+}
+
+/**
+ * Highlight primitive — animated background indicator that follows the active item.
+ * Supports two modes: "children" (layoutId-based per item) and "parent" (absolute positioned).
+ *
+ * This is an internal primitive used by Tabs, Menu, and similar components.
+ *
+ * @param mode - Tracking mode: 'children' or 'parent'
+ * @param hover - Activate on hover instead of click
+ * @param click - Activate on click (default: true)
+ * @param transition - Motion transition config
+ *
+ * @example
+ * ```tsx
+ * <Highlight hover>
+ *   <HighlightItem><button>Tab 1</button></HighlightItem>
+ *   <HighlightItem><button>Tab 2</button></HighlightItem>
+ * </Highlight>
+ * ```
+ */
+function Highlight<T extends React.ElementType = 'div'>({
+  ref,
+  ...props
+}: IHighlightProps<T>) {
+  const {
+    as: Component = 'div',
+    children,
+    value,
+    defaultValue,
+    onValueChange,
+    className,
+    style,
+    transition = { type: 'spring', stiffness: 350, damping: 35 },
+    hover = false,
+    click = true,
+    enabled = true,
+    controlledItems,
+    disabled = false,
+    exitDelay = 200,
+    mode = 'children',
+  } = props;
+
+  const localRef = React.useRef<HTMLDivElement>(null);
+  React.useImperativeHandle(ref, () => localRef.current as HTMLDivElement);
+
+  const propsBoundsOffset = (props as ParentModeHighlightProps)?.boundsOffset;
+  const boundsOffset = propsBoundsOffset ?? DEFAULT_BOUNDS_OFFSET;
+  const boundsOffsetTop = boundsOffset.top ?? 0;
+  const boundsOffsetLeft = boundsOffset.left ?? 0;
+  const boundsOffsetWidth = boundsOffset.width ?? 0;
+  const boundsOffsetHeight = boundsOffset.height ?? 0;
+
+  const boundsOffsetRef = React.useRef({
+    top: boundsOffsetTop,
+    left: boundsOffsetLeft,
+    width: boundsOffsetWidth,
+    height: boundsOffsetHeight,
+  });
+
+  React.useEffect(() => {
+    boundsOffsetRef.current = {
+      top: boundsOffsetTop,
+      left: boundsOffsetLeft,
+      width: boundsOffsetWidth,
+      height: boundsOffsetHeight,
+    };
+  }, [
+    boundsOffsetTop,
+    boundsOffsetLeft,
+    boundsOffsetWidth,
+    boundsOffsetHeight,
+  ]);
+
+  const [activeValue, setActiveValue] = React.useState<string | null>(
+    value ?? defaultValue ?? null,
+  );
+  const [boundsState, setBoundsState] = React.useState<Bounds | null>(null);
+  const [activeClassNameState, setActiveClassNameState] =
+    React.useState<string>('');
+
+  const safeSetActiveValue = (id: string | null) => {
+    setActiveValue((prev) => {
+      if (prev !== id) {
+        onValueChange?.(id);
+        return id;
+      }
+      return prev;
+    });
+  };
+
+  const safeSetBoundsRef = React.useRef<
+    ((bounds: DOMRect) => void) | undefined
+  >(undefined);
+
+  React.useEffect(() => {
+    safeSetBoundsRef.current = (bounds: DOMRect) => {
+      if (!localRef.current) return;
+
+      const containerRect = localRef.current.getBoundingClientRect();
+      const offset = boundsOffsetRef.current;
+      const newBounds: Bounds = {
+        top: bounds.top - containerRect.top + offset.top,
+        left: bounds.left - containerRect.left + offset.left,
+        width: bounds.width + offset.width,
+        height: bounds.height + offset.height,
+      };
+
+      setBoundsState((prev) => {
+        if (
+          prev &&
+          prev.top === newBounds.top &&
+          prev.left === newBounds.left &&
+          prev.width === newBounds.width &&
+          prev.height === newBounds.height
+        ) {
+          return prev;
+        }
+        return newBounds;
+      });
+    };
+  });
+
+  const safeSetBounds = (bounds: DOMRect) => {
+    safeSetBoundsRef.current?.(bounds);
+  };
+
+  const clearBounds = React.useCallback(() => {
+    setBoundsState((prev) => (prev === null ? prev : null));
+  }, []);
+
+  React.useEffect(() => {
+    if (value !== undefined) setActiveValue(value);
+    else if (defaultValue !== undefined) setActiveValue(defaultValue);
+  }, [value, defaultValue]);
+
+  const id = React.useId();
+
+  React.useEffect(() => {
+    if (mode !== 'parent') return;
+    const container = localRef.current;
+    if (!container) return;
+
+    const onScroll = () => {
+      if (!activeValue) return;
+      const activeEl = container.querySelector<HTMLElement>(
+        `[data-value="${activeValue}"][data-highlight="true"]`,
+      );
+      if (activeEl)
+        safeSetBoundsRef.current?.(activeEl.getBoundingClientRect());
+    };
+
+    container.addEventListener('scroll', onScroll, { passive: true });
+    return () => container.removeEventListener('scroll', onScroll);
+  }, [mode, activeValue]);
+
+  const render = (children: React.ReactNode) => {
+    if (mode === 'parent') {
+      return (
+        <Component
+          ref={localRef}
+          data-slot="motion-highlight-container"
+          style={{ position: 'relative', zIndex: 1 }}
+          className={(props as ParentModeHighlightProps)?.containerClassName}
+        >
+          <AnimatePresence initial={false} mode="wait">
+            {boundsState && (
+              <motion.div
+                data-slot="motion-highlight"
+                animate={{
+                  top: boundsState.top,
+                  left: boundsState.left,
+                  width: boundsState.width,
+                  height: boundsState.height,
+                  opacity: 1,
+                }}
+                initial={{
+                  top: boundsState.top,
+                  left: boundsState.left,
+                  width: boundsState.width,
+                  height: boundsState.height,
+                  opacity: 0,
+                }}
+                exit={{
+                  opacity: 0,
+                  transition: {
+                    ...transition,
+                    delay: (transition?.delay ?? 0) + (exitDelay ?? 0) / 1000,
+                  },
+                }}
+                transition={transition}
+                style={{ position: 'absolute', zIndex: 0, ...style }}
+                className={cn(className, activeClassNameState)}
+              />
+            )}
+          </AnimatePresence>
+          {children}
+        </Component>
+      );
+    }
+
+    return children;
+  };
+
+  return (
+    <HighlightContext.Provider
+      value={{
+        mode,
+        activeValue,
+        setActiveValue: safeSetActiveValue,
+        id,
+        hover,
+        click,
+        className,
+        style,
+        transition,
+        disabled,
+        enabled,
+        exitDelay,
+        setBounds: safeSetBounds,
+        clearBounds,
+        activeClassName: activeClassNameState,
+        setActiveClassName: setActiveClassNameState,
+        forceUpdateBounds: (props as ParentModeHighlightProps)
+          ?.forceUpdateBounds,
+      }}
+    >
+      {enabled
+        ? controlledItems
+          ? render(children)
+          : render(
+              React.Children.map(children, (child, index) => (
+                <HighlightItem key={index} className={props?.itemsClassName}>
+                  {child}
+                </HighlightItem>
+              )),
+            )
+        : children}
+    </HighlightContext.Provider>
+  );
+}
+
+function getNonOverridingDataAttributes(
+  element: React.ReactElement,
+  dataAttributes: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.keys(dataAttributes).reduce<Record<string, unknown>>(
+    (acc, key) => {
+      if ((element.props as Record<string, unknown>)[key] === undefined) {
+        acc[key] = dataAttributes[key];
+      }
+      return acc;
+    },
+    {},
+  );
+}
+
+/**
+ * HighlightItem — a single item within a Highlight container.
+ * Tracks its own position and renders the animated highlight indicator.
+ *
+ * @param value - Unique identifier for this item
+ * @param activeClassName - Additional class when this item is active
+ * @param asChild - Use the child element directly instead of wrapping
+ *
+ * @example
+ * ```tsx
+ * <HighlightItem value="tab-1">
+ *   <button>Tab 1</button>
+ * </HighlightItem>
+ * ```
+ */
+function HighlightItem<T extends React.ElementType>({
+  ref,
+  as,
+  children,
+  id,
+  value,
+  className,
+  style,
+  transition,
+  disabled = false,
+  activeClassName,
+  exitDelay,
+  asChild = false,
+  forceUpdateBounds,
+  ...props
+}: IHighlightItemProps<T>) {
+  const itemId = React.useId();
+  const {
+    activeValue,
+    setActiveValue,
+    mode,
+    setBounds,
+    clearBounds,
+    hover,
+    click,
+    enabled,
+    className: contextClassName,
+    style: contextStyle,
+    transition: contextTransition,
+    id: contextId,
+    disabled: contextDisabled,
+    exitDelay: contextExitDelay,
+    forceUpdateBounds: contextForceUpdateBounds,
+    setActiveClassName,
+  } = useHighlight();
+
+  const Component = as ?? 'div';
+  const element = children as React.ReactElement<ExtendedChildProps>;
+  const childValue =
+    id ?? value ?? element.props?.['data-value'] ?? element.props?.id ?? itemId;
+  const isActive = activeValue === childValue;
+  const isDisabled = disabled === undefined ? contextDisabled : disabled;
+  const itemTransition = transition ?? contextTransition;
+
+  const localRef = React.useRef<HTMLDivElement>(null);
+  React.useImperativeHandle(ref, () => localRef.current as HTMLDivElement);
+
+  const refCallback = React.useCallback((node: HTMLElement | null) => {
+    localRef.current = node as HTMLDivElement;
+  }, []);
+
+  React.useEffect(() => {
+    if (mode !== 'parent') return;
+    let rafId: number;
+    let previousBounds: Bounds | null = null;
+    const shouldUpdateBounds =
+      forceUpdateBounds === true ||
+      (contextForceUpdateBounds && forceUpdateBounds !== false);
+
+    const updateBounds = () => {
+      if (!localRef.current) return;
+
+      const bounds = localRef.current.getBoundingClientRect();
+
+      if (shouldUpdateBounds) {
+        if (
+          previousBounds &&
+          previousBounds.top === bounds.top &&
+          previousBounds.left === bounds.left &&
+          previousBounds.width === bounds.width &&
+          previousBounds.height === bounds.height
+        ) {
+          rafId = requestAnimationFrame(updateBounds);
+          return;
+        }
+        previousBounds = bounds;
+        rafId = requestAnimationFrame(updateBounds);
+      }
+
+      setBounds(bounds);
+    };
+
+    if (isActive) {
+      updateBounds();
+      setActiveClassName(activeClassName ?? '');
+    } else if (!activeValue) clearBounds();
+
+    if (shouldUpdateBounds) return () => cancelAnimationFrame(rafId);
+  }, [
+    mode,
+    isActive,
+    activeValue,
+    setBounds,
+    clearBounds,
+    activeClassName,
+    setActiveClassName,
+    forceUpdateBounds,
+    contextForceUpdateBounds,
+  ]);
+
+  if (!React.isValidElement(children)) return children;
+
+  const dataAttributes = {
+    'data-active': isActive ? 'true' : 'false',
+    'aria-selected': isActive,
+    'data-disabled': isDisabled,
+    'data-value': childValue,
+    'data-highlight': true,
+  };
+
+  const commonHandlers = hover
+    ? {
+        onMouseEnter: (e: React.MouseEvent<HTMLDivElement>) => {
+          setActiveValue(childValue);
+          element.props.onMouseEnter?.(e);
+        },
+        onMouseLeave: (e: React.MouseEvent<HTMLDivElement>) => {
+          setActiveValue(null);
+          element.props.onMouseLeave?.(e);
+        },
+      }
+    : click
+      ? {
+          onClick: (e: React.MouseEvent<HTMLDivElement>) => {
+            setActiveValue(childValue);
+            element.props.onClick?.(e);
+          },
+        }
+      : {};
+
+  if (asChild) {
+    if (mode === 'children') {
+      return React.cloneElement(
+        element,
+        {
+          key: childValue,
+          ref: refCallback,
+          className: cn('relative', element.props.className),
+          ...getNonOverridingDataAttributes(element, {
+            ...dataAttributes,
+            'data-slot': 'motion-highlight-item-container',
+          }),
+          ...commonHandlers,
+          ...props,
+        },
+        <>
+          <AnimatePresence initial={false} mode="wait">
+            {isActive && !isDisabled && (
+              <motion.div
+                layoutId={`transition-background-${contextId}`}
+                data-slot="motion-highlight"
+                style={{
+                  position: 'absolute',
+                  zIndex: 0,
+                  ...contextStyle,
+                  ...style,
+                }}
+                className={cn(contextClassName, activeClassName)}
+                transition={itemTransition}
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{
+                  opacity: 0,
+                  transition: {
+                    ...itemTransition,
+                    delay:
+                      (itemTransition?.delay ?? 0) +
+                      (exitDelay ?? contextExitDelay ?? 0) / 1000,
+                  },
+                }}
+                {...dataAttributes}
+              />
+            )}
+          </AnimatePresence>
+
+          <Component
+            data-slot="motion-highlight-item"
+            style={{ position: 'relative', zIndex: 1 }}
+            className={className}
+            {...dataAttributes}
+          >
+            {children}
+          </Component>
+        </>,
+      );
+    }
+
+    return React.cloneElement(element, {
+      ref: refCallback,
+      ...getNonOverridingDataAttributes(element, {
+        ...dataAttributes,
+        'data-slot': 'motion-highlight-item',
+      }),
+      ...commonHandlers,
+    });
+  }
+
+  return enabled ? (
+    <Component
+      key={childValue}
+      ref={localRef}
+      data-slot="motion-highlight-item-container"
+      className={cn(mode === 'children' && 'relative', className)}
+      {...dataAttributes}
+      {...props}
+      {...commonHandlers}
+    >
+      {mode === 'children' && (
+        <AnimatePresence initial={false} mode="wait">
+          {isActive && !isDisabled && (
+            <motion.div
+              layoutId={`transition-background-${contextId}`}
+              data-slot="motion-highlight"
+              style={{
+                position: 'absolute',
+                zIndex: 0,
+                ...contextStyle,
+                ...style,
+              }}
+              className={cn(contextClassName, activeClassName)}
+              transition={itemTransition}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{
+                opacity: 0,
+                transition: {
+                  ...itemTransition,
+                  delay:
+                    (itemTransition?.delay ?? 0) +
+                    (exitDelay ?? contextExitDelay ?? 0) / 1000,
+                },
+              }}
+              {...dataAttributes}
+            />
+          )}
+        </AnimatePresence>
+      )}
+
+      {React.cloneElement(element, {
+        style: { position: 'relative', zIndex: 1 },
+        className: element.props.className,
+        ...getNonOverridingDataAttributes(element, {
+          ...dataAttributes,
+          'data-slot': 'motion-highlight-item',
+        }),
+      })}
+    </Component>
+  ) : (
+    children
+  );
+}
+
+export {
+  Highlight,
+  HighlightItem,
+  useHighlight,
+};
+
+// Re-exports
+export type {
+  IHighlightProps,
+  IHighlightItemProps,
+  Bounds,
+  HighlightMode,
+  HighlightContextType,
+} from './Highlight.types';

package/src/react-ui/primitives/Slot/index.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import * as React from 'react';
+import { motion, isMotionComponent, type HTMLMotionProps } from 'motion/react';
+
+import { cn } from '@/react-ui/lib/utils';
+
+type AnyProps = Record<string, unknown>;
+
+type DOMMotionProps<T extends HTMLElement = HTMLElement> = Omit<
+  HTMLMotionProps<keyof HTMLElementTagNameMap>,
+  'ref'
+> & { ref?: React.Ref<T> };
+
+type WithAsChild<Base extends object> =
+  | (Base & { asChild: true; children: React.ReactElement })
+  | (Base & { asChild?: false | undefined });
+
+/**
+ * Props for the Slot component.
+ *
+ * @example
+ * ```tsx
+ * <Slot asChild>
+ *   <button>Click me</button>
+ * </Slot>
+ * ```
+ */
+export interface ISlotProps<T extends HTMLElement = HTMLElement>
+  extends DOMMotionProps<T> {
+  /** Child element to render with motion enhancements. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  children?: any;
+}
+
+type SlotProps<T extends HTMLElement = HTMLElement> = ISlotProps<T>;
+
+function mergeRefs<T>(
+  ...refs: (React.Ref<T> | undefined)[]
+): React.RefCallback<T> {
+  return (node) => {
+    refs.forEach((ref) => {
+      if (!ref) return;
+      if (typeof ref === 'function') {
+        ref(node);
+      } else {
+        (ref as React.RefObject<T | null>).current = node;
+      }
+    });
+  };
+}
+
+function mergeProps<T extends HTMLElement>(
+  childProps: AnyProps,
+  slotProps: DOMMotionProps<T>,
+): AnyProps {
+  const merged: AnyProps = { ...childProps, ...slotProps };
+
+  if (childProps.className || slotProps.className) {
+    merged.className = cn(
+      childProps.className as string,
+      slotProps.className as string,
+    );
+  }
+
+  if (childProps.style || slotProps.style) {
+    merged.style = {
+      ...(childProps.style as React.CSSProperties),
+      ...(slotProps.style as React.CSSProperties),
+    };
+  }
+
+  return merged;
+}
+
+/**
+ * Slot component - Motion-enhanced composition primitive.
+ *
+ * Wraps a child element with motion capabilities using the asChild pattern.
+ * When the child is already a motion component, it's used directly.
+ * Otherwise, a motion wrapper is created with the child's element type.
+ *
+ * @param children - Child element to render with motion enhancements
+ * @param ref - Ref to the merged element
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Slot asChild>
+ *   <button>Click me</button>
+ * </Slot>
+ *
+ * // With motion props
+ * <Slot asChild>
+ *   <button onClick={handleClick}>Hover me</button>
+ * </Slot>
+ * ```
+ */
+export function Slot<T extends HTMLElement = HTMLElement>({
+  children,
+  ref,
+  ...props
+}: SlotProps<T>) {
+  const isAlreadyMotion =
+    typeof children.type === 'object' &&
+    children.type !== null &&
+    isMotionComponent(children.type);
+
+  const Base = React.useMemo(
+    () =>
+      isAlreadyMotion
+        ? (children.type as React.ElementType)
+        : motion.create(children.type as React.ElementType),
+    [isAlreadyMotion, children.type],
+  );
+
+  if (!React.isValidElement(children)) return null;
+
+  const { ref: childRef, ...childProps } = children.props as AnyProps;
+
+  const mergedProps = mergeProps(childProps, props);
+
+  return (
+    <Base {...mergedProps} ref={mergeRefs(childRef as React.Ref<T>, ref)} />
+  );
+}
+
+export type { WithAsChild, DOMMotionProps, AnyProps };

package/src/react-ui/primitives/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Primitives barrel export.
+ *
+ * Building blocks for components. Not meant to be used directly by consumers.
+ *
+ * @module @mks2508/mks-ui/react/primitives
+ */
+
+// Internal animation primitives
+export * from './Slot';
+export * from './Highlight';
+export * from './AutoHeight';
+export * from './CountingNumber';
+
+// WAAPI Animation Primitives
+export * from './waapi';