@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/{icons → react/icons}/lucide-animated/trending-up.tsx

@@ -5,7 +5,7 @@ import { motion, useAnimation } from "framer-motion";
 import type { HTMLAttributes } from "react";
 import { forwardRef, useCallback, useImperativeHandle, useRef } from "react";
 
-import { cn } from "@/lib/utils";
+import { cn } from "@/react/lib/utils";
 
 export interface TrendingUpIconHandle {
   startAnimation: () => void;

package/src/{icons → react/icons}/lucide-animated/x.tsx

@@ -5,7 +5,7 @@ import { motion, useAnimation } from "framer-motion";
 import type { HTMLAttributes } from "react";
 import { forwardRef, useCallback, useImperativeHandle, useRef } from "react";
 
-import { cn } from "@/lib/utils";
+import { cn } from "@/react/lib/utils";
 
 export interface XIconHandle {
   startAnimation: () => void;

package/src/react/index.ts

@@ -0,0 +1,30 @@
+/**
+ * React components, hooks, icons, and utilities barrel export.
+ *
+ * @module @mks2508/mks-ui/react
+ *
+ * @example
+ * ```tsx
+ * import { Button, Card, Dialog, CornerBracket } from '@mks2508/mks-ui/react';
+ * import { useAutoHeight, useControlledState } from '@mks2508/mks-ui/react';
+ * import { cn } from '@mks2508/mks-ui/react';
+ * ```
+ */
+
+// Primitives (internal building blocks, re-exported for advanced use)
+export * from './primitives';
+
+// UI components (primary public API)
+export * from './ui';
+
+// Complex components (CSS modules, advanced patterns)
+export * from './components';
+
+// Custom hooks
+export * from './hooks';
+
+// Icons
+export * from './icons';
+
+// Utilities
+export * from './lib';

package/src/{lib → react/lib}/get-strict-context.tsx

@@ -1,5 +1,25 @@
 import * as React from 'react';
 
+/**
+ * Creates a strict context pair — a Provider and a hook that throws
+ * if used outside the Provider.
+ *
+ * @param name - Display name for error messages
+ * @returns A tuple of [Provider, useSafeContext]
+ *
+ * @example
+ * ```tsx
+ * const [ThemeProvider, useTheme] = getStrictContext<IThemeContext>('ThemeProvider');
+ *
+ * function App() {
+ *   return (
+ *     <ThemeProvider value={{ mode: 'dark' }}>
+ *       <MyComponent />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
 function getStrictContext<T>(
   name?: string,
 ): readonly [

package/src/react/lib/index.ts

@@ -0,0 +1,8 @@
+/**
+ * React-specific utility functions barrel export.
+ *
+ * @module @mks2508/mks-ui/react/lib
+ */
+
+export { cn } from './utils';
+export { getStrictContext } from './get-strict-context';

package/src/{lib → react/lib}/utils.ts

@@ -1,7 +1,7 @@
 /**
- * Utility functions for UI components.
+ * React-specific utility functions.
  *
- * @module @mks2508/mks-ui/lib/utils
+ * @module @mks2508/mks-ui/react/lib/utils
  */
 
 import { type ClassValue, clsx } from 'clsx';

package/src/{components/animate-ui/primitives/effects/auto-height.tsx → react/primitives/AutoHeight/index.tsx}

@@ -9,18 +9,37 @@ import {
   type Transition,
 } from 'motion/react';
 
-import { useAutoHeight } from '@/hooks/use-auto-height';
-import { Slot, WithAsChild } from '@/components/animate-ui/primitives/animate/slot';
+import { useAutoHeight } from '@/react/hooks/Animation/UseAutoHeight';
+import { Slot, type WithAsChild } from '@/react/primitives/Slot';
 
-type AutoHeightProps = WithAsChild<
+/** Props for the AutoHeight primitive component. */
+type IAutoHeightProps = WithAsChild<
   {
     children: React.ReactNode;
+    /** Dependency list to trigger re-measurement. */
     deps?: React.DependencyList;
+    /** Motion animate target. */
     animate?: TargetAndTransition | LegacyAnimationControls;
+    /** Motion transition config. */
     transition?: Transition;
   } & Omit<HTMLMotionProps<'div'>, 'animate'>
 >;
 
+/**
+ * AutoHeight primitive — animates height changes of dynamic content.
+ * Uses ResizeObserver internally to track content height and Motion for animation.
+ *
+ * @param deps - Dependency list to trigger re-measurement
+ * @param transition - Motion spring/tween transition config
+ * @param asChild - Render as child element using Slot pattern
+ *
+ * @example
+ * ```tsx
+ * <AutoHeight deps={[content]}>
+ *   <div>{content}</div>
+ * </AutoHeight>
+ * ```
+ */
 function AutoHeight({
   children,
   deps = [],
@@ -35,7 +54,7 @@ function AutoHeight({
   animate,
   asChild = false,
   ...props
-}: AutoHeightProps) {
+}: IAutoHeightProps) {
   const { ref, height } = useAutoHeight<HTMLDivElement>(deps);
 
   const Comp = asChild ? Slot : motion.div;
@@ -52,4 +71,4 @@ function AutoHeight({
   );
 }
 
-export { AutoHeight, type AutoHeightProps };
+export { AutoHeight, type IAutoHeightProps };

package/src/{components/animate-ui/primitives/texts/counting-number.tsx → react/primitives/CountingNumber/index.tsx}

@@ -5,20 +5,48 @@ import { useMotionValue, useSpring, type SpringOptions } from 'motion/react';
 
 import {
   useIsInView,
-  type UseIsInViewOptions,
-} from '@/hooks/use-is-in-view';
+  type IUseIsInViewOptions,
+} from '@/react/hooks/DOM/UseIsInView';
 
-type CountingNumberProps = Omit<React.ComponentProps<'span'>, 'children'> & {
+/** Props for the CountingNumber primitive. */
+type ICountingNumberProps = Omit<React.ComponentProps<'span'>, 'children'> & {
+  /** Target number to animate to. */
   number: number;
+  /** Starting number (default: 0). */
   fromNumber?: number;
+  /** Pad integer part with leading zeros. */
   padStart?: boolean;
+  /** Decimal separator character. */
   decimalSeparator?: string;
+  /** Number of decimal places to show. */
   decimalPlaces?: number;
+  /** Spring transition options. */
   transition?: SpringOptions;
+  /** Delay in ms before animation starts. */
   delay?: number;
+  /** Start at target number instead of fromNumber. */
   initiallyStable?: boolean;
-} & UseIsInViewOptions;
-
+} & IUseIsInViewOptions;
+
+/**
+ * CountingNumber primitive — animates a number from one value to another
+ * using spring physics. Supports decimal places, padding, and in-view triggers.
+ *
+ * @param number - Target number to animate to
+ * @param fromNumber - Starting number (default: 0)
+ * @param transition - Spring physics options
+ * @param inView - Only animate when in viewport
+ *
+ * @example
+ * ```tsx
+ * <CountingNumber number={1234} transition={{ stiffness: 90, damping: 50 }} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <CountingNumber number={99.99} decimalPlaces={2} decimalSeparator="," inView inViewOnce />
+ * ```
+ */
 function CountingNumber({
   ref,
   number,
@@ -33,7 +61,7 @@ function CountingNumber({
   delay = 0,
   initiallyStable = false,
   ...props
-}: CountingNumberProps) {
+}: ICountingNumberProps) {
   const { ref: localRef, isInView } = useIsInView(
     ref as React.Ref<HTMLElement>,
     {
@@ -116,4 +144,4 @@ function CountingNumber({
   );
 }
 
-export { CountingNumber, type CountingNumberProps };
+export { CountingNumber, type ICountingNumberProps };

package/src/react/primitives/Highlight/Highlight.types.ts

@@ -0,0 +1,136 @@
+import type { Transition } from 'motion/react';
+
+/** Mode for highlight tracking. */
+export type HighlightMode = 'children' | 'parent';
+
+/** Bounding rectangle offsets. */
+export type Bounds = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+};
+
+/** Internal context type for Highlight state. */
+export type HighlightContextType<T extends string> = {
+  as?: keyof HTMLElementTagNameMap;
+  mode: HighlightMode;
+  activeValue: T | null;
+  setActiveValue: (value: T | null) => void;
+  setBounds: (bounds: DOMRect) => void;
+  clearBounds: () => void;
+  id: string;
+  hover: boolean;
+  click: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  activeClassName?: string;
+  setActiveClassName: (className: string) => void;
+  transition?: Transition;
+  disabled?: boolean;
+  enabled?: boolean;
+  exitDelay?: number;
+  forceUpdateBounds?: boolean;
+};
+
+/** Base props shared by all Highlight variants. */
+export type BaseHighlightProps<T extends React.ElementType = 'div'> = {
+  as?: T;
+  ref?: React.Ref<HTMLDivElement>;
+  mode?: HighlightMode;
+  value?: string | null;
+  defaultValue?: string | null;
+  onValueChange?: (value: string | null) => void;
+  className?: string;
+  style?: React.CSSProperties;
+  transition?: Transition;
+  hover?: boolean;
+  click?: boolean;
+  disabled?: boolean;
+  enabled?: boolean;
+  exitDelay?: number;
+};
+
+/** Props specific to parent mode. */
+export type ParentModeHighlightProps = {
+  boundsOffset?: Partial<Bounds>;
+  containerClassName?: string;
+  forceUpdateBounds?: boolean;
+};
+
+/** Controlled parent mode highlight props. */
+export type ControlledParentModeHighlightProps<T extends React.ElementType = 'div'> =
+  BaseHighlightProps<T> &
+    ParentModeHighlightProps & {
+      mode: 'parent';
+      controlledItems: true;
+      children: React.ReactNode;
+    };
+
+/** Controlled children mode highlight props. */
+export type ControlledChildrenModeHighlightProps<T extends React.ElementType = 'div'> =
+  BaseHighlightProps<T> & {
+    mode?: 'children' | undefined;
+    controlledItems: true;
+    children: React.ReactNode;
+  };
+
+/** Uncontrolled parent mode highlight props. */
+export type UncontrolledParentModeHighlightProps<T extends React.ElementType = 'div'> =
+  BaseHighlightProps<T> &
+    ParentModeHighlightProps & {
+      mode: 'parent';
+      controlledItems?: false;
+      itemsClassName?: string;
+      children: React.ReactElement | React.ReactElement[];
+    };
+
+/** Uncontrolled children mode highlight props. */
+export type UncontrolledChildrenModeHighlightProps<
+  T extends React.ElementType = 'div',
+> = BaseHighlightProps<T> & {
+  mode?: 'children';
+  controlledItems?: false;
+  itemsClassName?: string;
+  children: React.ReactElement | React.ReactElement[];
+};
+
+/**
+ * Props for the Highlight component.
+ * Discriminated union supporting controlled/uncontrolled + children/parent modes.
+ */
+export type IHighlightProps<T extends React.ElementType = 'div'> =
+  | ControlledParentModeHighlightProps<T>
+  | ControlledChildrenModeHighlightProps<T>
+  | UncontrolledParentModeHighlightProps<T>
+  | UncontrolledChildrenModeHighlightProps<T>;
+
+/** Extended child props used internally by HighlightItem. */
+export type ExtendedChildProps = React.ComponentProps<'div'> & {
+  id?: string;
+  ref?: React.Ref<HTMLElement>;
+  'data-active'?: string;
+  'data-value'?: string;
+  'data-disabled'?: boolean;
+  'data-highlight'?: boolean;
+  'data-slot'?: string;
+};
+
+/**
+ * Props for a HighlightItem within a Highlight container.
+ */
+export type IHighlightItemProps<T extends React.ElementType = 'div'> =
+  React.ComponentProps<T> & {
+    as?: T;
+    children: React.ReactElement;
+    id?: string;
+    value?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    transition?: Transition;
+    activeClassName?: string;
+    disabled?: boolean;
+    exitDelay?: number;
+    asChild?: boolean;
+    forceUpdateBounds?: boolean;
+  };

package/src/{components/animate-ui/primitives/effects/highlight.tsx → react/primitives/Highlight/index.tsx}

@@ -3,16 +3,15 @@
 import * as React from 'react';
 import { AnimatePresence, motion, type Transition } from 'motion/react';
 
-import { cn } from '@/lib/utils';
-
-type HighlightMode = 'children' | 'parent';
-
-type Bounds = {
-  top: number;
-  left: number;
-  width: number;
-  height: number;
-};
+import { cn } from '@/react/lib/utils';
+import type {
+  Bounds,
+  HighlightContextType,
+  IHighlightProps,
+  IHighlightItemProps,
+  ParentModeHighlightProps,
+  ExtendedChildProps,
+} from './Highlight.types';
 
 const DEFAULT_BOUNDS_OFFSET: Bounds = {
   top: 0,
@@ -21,32 +20,17 @@ const DEFAULT_BOUNDS_OFFSET: Bounds = {
   height: 0,
 };
 
-type HighlightContextType<T extends string> = {
-  as?: keyof HTMLElementTagNameMap;
-  mode: HighlightMode;
-  activeValue: T | null;
-  setActiveValue: (value: T | null) => void;
-  setBounds: (bounds: DOMRect) => void;
-  clearBounds: () => void;
-  id: string;
-  hover: boolean;
-  click: boolean;
-  className?: string;
-  style?: React.CSSProperties;
-  activeClassName?: string;
-  setActiveClassName: (className: string) => void;
-  transition?: Transition;
-  disabled?: boolean;
-  enabled?: boolean;
-  exitDelay?: number;
-  forceUpdateBounds?: boolean;
-};
-
 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) {
@@ -55,72 +39,29 @@ function useHighlight<T extends string>(): HighlightContextType<T> {
   return context as unknown as HighlightContextType<T>;
 }
 
-type BaseHighlightProps<T extends React.ElementType = 'div'> = {
-  as?: T;
-  ref?: React.Ref<HTMLDivElement>;
-  mode?: HighlightMode;
-  value?: string | null;
-  defaultValue?: string | null;
-  onValueChange?: (value: string | null) => void;
-  className?: string;
-  style?: React.CSSProperties;
-  transition?: Transition;
-  hover?: boolean;
-  click?: boolean;
-  disabled?: boolean;
-  enabled?: boolean;
-  exitDelay?: number;
-};
-
-type ParentModeHighlightProps = {
-  boundsOffset?: Partial<Bounds>;
-  containerClassName?: string;
-  forceUpdateBounds?: boolean;
-};
-
-type ControlledParentModeHighlightProps<T extends React.ElementType = 'div'> =
-  BaseHighlightProps<T> &
-    ParentModeHighlightProps & {
-      mode: 'parent';
-      controlledItems: true;
-      children: React.ReactNode;
-    };
-
-type ControlledChildrenModeHighlightProps<T extends React.ElementType = 'div'> =
-  BaseHighlightProps<T> & {
-    mode?: 'children' | undefined;
-    controlledItems: true;
-    children: React.ReactNode;
-  };
-
-type UncontrolledParentModeHighlightProps<T extends React.ElementType = 'div'> =
-  BaseHighlightProps<T> &
-    ParentModeHighlightProps & {
-      mode: 'parent';
-      controlledItems?: false;
-      itemsClassName?: string;
-      children: React.ReactElement | React.ReactElement[];
-    };
-
-type UncontrolledChildrenModeHighlightProps<
-  T extends React.ElementType = 'div',
-> = BaseHighlightProps<T> & {
-  mode?: 'children';
-  controlledItems?: false;
-  itemsClassName?: string;
-  children: React.ReactElement | React.ReactElement[];
-};
-
-type HighlightProps<T extends React.ElementType = 'div'> =
-  | ControlledParentModeHighlightProps<T>
-  | ControlledChildrenModeHighlightProps<T>
-  | UncontrolledParentModeHighlightProps<T>
-  | UncontrolledChildrenModeHighlightProps<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
-}: HighlightProps<T>) {
+}: IHighlightProps<T>) {
   const {
     as: Component = 'div',
     children,
@@ -353,32 +294,21 @@ function getNonOverridingDataAttributes(
   );
 }
 
-type ExtendedChildProps = React.ComponentProps<'div'> & {
-  id?: string;
-  ref?: React.Ref<HTMLElement>;
-  'data-active'?: string;
-  'data-value'?: string;
-  'data-disabled'?: boolean;
-  'data-highlight'?: boolean;
-  'data-slot'?: string;
-};
-
-type HighlightItemProps<T extends React.ElementType = 'div'> =
-  React.ComponentProps<T> & {
-    as?: T;
-    children: React.ReactElement;
-    id?: string;
-    value?: string;
-    className?: string;
-    style?: React.CSSProperties;
-    transition?: Transition;
-    activeClassName?: string;
-    disabled?: boolean;
-    exitDelay?: number;
-    asChild?: boolean;
-    forceUpdateBounds?: boolean;
-  };
-
+/**
+ * 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,
@@ -394,7 +324,7 @@ function HighlightItem<T extends React.ElementType>({
   asChild = false,
   forceUpdateBounds,
   ...props
-}: HighlightItemProps<T>) {
+}: IHighlightItemProps<T>) {
   const itemId = React.useId();
   const {
     activeValue,
@@ -635,6 +565,13 @@ export {
   Highlight,
   HighlightItem,
   useHighlight,
-  type HighlightProps,
-  type HighlightItemProps,
 };
+
+// Re-exports
+export type {
+  IHighlightProps,
+  IHighlightItemProps,
+  Bounds,
+  HighlightMode,
+  HighlightContextType,
+} from './Highlight.types';

package/src/{components/animate-ui/primitives/animate/slot.tsx → react/primitives/Slot/index.tsx}

@@ -2,7 +2,8 @@
 
 import * as React from 'react';
 import { motion, isMotionComponent, type HTMLMotionProps } from 'motion/react';
-import { cn } from '@/lib/utils';
+
+import { cn } from '@/react/lib/utils';
 
 type AnyProps = Record<string, unknown>;
 
@@ -15,10 +16,24 @@ type WithAsChild<Base extends object> =
   | (Base & { asChild: true; children: React.ReactElement })
   | (Base & { asChild?: false | undefined });
 
-type SlotProps<T extends HTMLElement = HTMLElement> = {
+/**
+ * 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;
-} & DOMMotionProps<T>;
+}
+
+type SlotProps<T extends HTMLElement = HTMLElement> = ISlotProps<T>;
 
 function mergeRefs<T>(
   ...refs: (React.Ref<T> | undefined)[]
@@ -58,7 +73,30 @@ function mergeProps<T extends HTMLElement>(
   return merged;
 }
 
-function Slot<T extends HTMLElement = HTMLElement>({
+/**
+ * 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
@@ -87,10 +125,4 @@ function Slot<T extends HTMLElement = HTMLElement>({
   );
 }
 
-export {
-  Slot,
-  type SlotProps,
-  type WithAsChild,
-  type DOMMotionProps,
-  type AnyProps,
-};
+export type { WithAsChild, DOMMotionProps, AnyProps };

package/src/react/primitives/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';