@mks2508/mks-ui 0.1.4 → 0.2.1

package/src/react-ui/components/MorphingPopover/index.tsx

@@ -0,0 +1,186 @@
+'use client';
+
+/**
+ * MorphingPopover — a popover that animates from a trigger button to a target position.
+ *
+ * Uses CSS Anchor Positioning + Popover API + @starting-style for smooth morphing animations.
+ *
+ * @example
+ * ```tsx
+ * <MorphingPopover
+ *   trigger="..."
+ *   content={<div>Expanded content</div>}
+ *   targetSize={{ width: 320, height: 200 }}
+ * />
+ * ```
+ */
+
+import {
+  forwardRef,
+  type CSSProperties,
+} from 'react';
+import { cn } from '@/react-ui/lib/utils';
+import styles from './morphing-popover.module.css';
+import type {
+  IMorphingPopoverProps,
+  IMorphingButtonProps,
+  IMorphingPopoverWithTargetProps,
+} from './MorphingPopover.types';
+
+/**
+ * MorphingPopover — animates from a circular trigger to an expanded popover.
+ *
+ * @param content - Content to display in the expanded popover
+ * @param trigger - Trigger button content (default: "...")
+ * @param targetSize - Expanded dimensions { width, height }
+ * @param onOpen - Callback when popover opens
+ * @param onClose - Callback when popover closes
+ *
+ * @example
+ * ```tsx
+ * <MorphingPopover
+ *   trigger="+"
+ *   content={<div>Expanded content</div>}
+ *   targetSize={{ width: 320, height: 200 }}
+ * />
+ * ```
+ */
+const MorphingPopover = forwardRef<HTMLButtonElement, IMorphingPopoverProps>(
+  (
+    {
+      content,
+      trigger = '\u22EF',
+      triggerClassName,
+      popoverClassName,
+      targetSize = { width: 220, height: 120 },
+      onOpen,
+      onClose,
+      popoverId = 'morphing-popover',
+    },
+    ref,
+  ) => {
+    const containerStyle: CSSProperties = {
+      '--target-width': `${targetSize.width}px`,
+      '--target-height': `${targetSize.height}px`,
+    } as CSSProperties;
+
+    const handleToggle = (e: React.MouseEvent<HTMLButtonElement>) => {
+      const isOpen = (e.target as HTMLButtonElement).matches(':popover-open');
+      if (isOpen) {
+        onOpen?.();
+      } else {
+        onClose?.();
+      }
+    };
+
+    return (
+      <div
+        className={styles.morphingPopoverContainer}
+        style={containerStyle}
+      >
+        <button
+          ref={ref}
+          {...({
+            popovertarget: popoverId,
+            popoverTargetAction: 'toggle',
+          } as IMorphingButtonProps)}
+          className={cn(styles.morphingTrigger, triggerClassName)}
+          onClick={handleToggle}
+        >
+          {trigger}
+        </button>
+
+        <div
+          id={popoverId}
+          popover="auto"
+          className={cn(styles.morphingPopover, popoverClassName)}
+        >
+          {content}
+        </div>
+      </div>
+    );
+  },
+);
+
+MorphingPopover.displayName = 'MorphingPopover';
+
+/**
+ * MorphingPopoverWithTarget — variant that animates to a specific target element.
+ *
+ * The target element must have CSS `anchor-name: --target-anchor` set on it.
+ *
+ * @param targetRef - Reference to the target element to anchor to
+ * @param content - Content to display in the expanded popover
+ *
+ * @example
+ * ```tsx
+ * const targetRef = useRef<HTMLDivElement>(null);
+ *
+ * <div ref={targetRef} style={{ anchorName: '--target-anchor' }}>
+ *   Drag me around
+ * </div>
+ *
+ * <MorphingPopoverWithTarget
+ *   targetRef={targetRef}
+ *   content={<div>Content</div>}
+ * />
+ * ```
+ */
+const MorphingPopoverWithTarget = forwardRef<
+  HTMLButtonElement,
+  IMorphingPopoverWithTargetProps
+>(
+  (
+    {
+      content,
+      trigger = '\u22EF',
+      triggerClassName,
+      popoverClassName,
+      onOpen,
+      onClose,
+      popoverId = 'morphing-popover-target',
+    },
+    ref,
+  ) => {
+    const handleToggle = (e: React.MouseEvent<HTMLButtonElement>) => {
+      const isOpen = (e.target as HTMLButtonElement).matches(':popover-open');
+      if (isOpen) {
+        onOpen?.();
+      } else {
+        onClose?.();
+      }
+    };
+
+    return (
+      <div className={styles.morphingPopoverTargetContainer}>
+        <button
+          ref={ref}
+          {...({
+            popovertarget: popoverId,
+            popoverTargetAction: 'toggle',
+          } as IMorphingButtonProps)}
+          className={cn(styles.morphingTrigger, triggerClassName)}
+          onClick={handleToggle}
+        >
+          {trigger}
+        </button>
+
+        <div
+          id={popoverId}
+          popover="auto"
+          className={cn(styles.morphingPopoverTarget, popoverClassName)}
+        >
+          {content}
+        </div>
+      </div>
+    );
+  },
+);
+
+MorphingPopoverWithTarget.displayName = 'MorphingPopoverWithTarget';
+
+export { MorphingPopover, MorphingPopoverWithTarget };
+export type {
+  IMorphingPopoverProps,
+  IMorphingPopoverWithTargetProps,
+} from './MorphingPopover.types';

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

@@ -0,0 +1,9 @@
+/**
+ * Complex components barrel export.
+ *
+ * Components that use CSS modules or have complex internal structure.
+ *
+ * @module @mks2508/mks-ui/react/components
+ */
+
+export * from './MorphingPopover';

package/src/{hooks/use-auto-height.tsx → react-ui/hooks/Animation/UseAutoHeight.tsx}

@@ -2,14 +2,33 @@
 
 import * as React from 'react';
 
-type AutoHeightOptions = {
+/**
+ * Options for the useAutoHeight hook.
+ */
+interface IAutoHeightOptions {
+  /** Include parent element box model (padding, border) in measurement. */
   includeParentBox?: boolean;
+  /** Include self element box model in measurement. */
   includeSelfBox?: boolean;
-};
+}
 
+/**
+ * Hook that measures and tracks the height of an element with ResizeObserver.
+ * Returns a ref to attach and the current height value.
+ *
+ * @param deps - Dependency list to trigger re-measurement
+ * @param options - Configuration for box model inclusion
+ * @returns Object with ref and height
+ *
+ * @example
+ * ```tsx
+ * const { ref, height } = useAutoHeight<HTMLDivElement>([content]);
+ * <div style={{ height }}><div ref={ref}>{content}</div></div>
+ * ```
+ */
 export function useAutoHeight<T extends HTMLElement = HTMLDivElement>(
   deps: React.DependencyList = [],
-  options: AutoHeightOptions = {
+  options: IAutoHeightOptions = {
     includeParentBox: true,
     includeSelfBox: false,
   },
@@ -100,3 +119,5 @@ export function useAutoHeight<T extends HTMLElement = HTMLDivElement>(
 
   return { ref, height } as const;
 }
+
+export type { IAutoHeightOptions };

package/src/react-ui/hooks/DOM/UseIsInView.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { useInView, type UseInViewOptions } from 'motion/react';
+
+/**
+ * Options for the useIsInView hook.
+ */
+interface IUseIsInViewOptions {
+  /** Enable intersection observer tracking. */
+  inView?: boolean;
+  /** Only trigger once when element enters viewport. */
+  inViewOnce?: boolean;
+  /** Root margin for intersection observer. */
+  inViewMargin?: UseInViewOptions['margin'];
+}
+
+/**
+ * Hook that tracks whether an element is visible in the viewport
+ * using the Intersection Observer API via motion/react.
+ *
+ * @param ref - Forwarded ref to merge with local ref
+ * @param options - InView configuration options
+ * @returns Object with local ref and isInView boolean
+ *
+ * @example
+ * ```tsx
+ * const { ref, isInView } = useIsInView(forwardedRef, { inView: true, inViewOnce: true });
+ * ```
+ */
+function useIsInView<T extends HTMLElement = HTMLElement>(
+  ref: React.Ref<T>,
+  options: IUseIsInViewOptions = {},
+) {
+  const { inView, inViewOnce = false, inViewMargin = '0px' } = options;
+  const localRef = React.useRef<T>(null);
+  React.useImperativeHandle(ref, () => localRef.current as T);
+  const inViewResult = useInView(localRef, {
+    once: inViewOnce,
+    margin: inViewMargin,
+  });
+  const isInView = !inView || inViewResult;
+  return { ref: localRef, isInView };
+}
+
+export { useIsInView, type IUseIsInViewOptions };

package/src/{hooks/use-controlled-state.tsx → react-ui/hooks/State/UseControlledState.tsx}

@@ -1,13 +1,35 @@
 import * as React from 'react';
 
-interface CommonControlledStateProps<T> {
+/**
+ * Props for useControlledState hook.
+ */
+interface IControlledStateProps<T> {
+  /** Controlled value. */
   value?: T;
+  /** Default value for uncontrolled usage. */
   defaultValue?: T;
 }
 
+/**
+ * Hook for controlled/uncontrolled state management.
+ * Supports both patterns seamlessly — when `value` is provided, it's controlled;
+ * otherwise uses internal state initialized from `defaultValue`.
+ *
+ * @param props - Value, defaultValue, and onChange callback
+ * @returns Tuple of [currentValue, setValue]
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useControlledState({
+ *   value: props.open,
+ *   defaultValue: false,
+ *   onChange: props.onOpenChange,
+ * });
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function useControlledState<T, Rest extends any[] = []>(
-  props: CommonControlledStateProps<T> & {
+  props: IControlledStateProps<T> & {
     onChange?: (value: T, ...args: Rest) => void;
   },
 ): readonly [T, (next: T, ...args: Rest) => void] {
@@ -31,3 +53,5 @@ export function useControlledState<T, Rest extends any[] = []>(
 
   return [state, setState] as const;
 }
+
+export type { IControlledStateProps };

package/src/{hooks/use-data-state.tsx → react-ui/hooks/State/UseDataState.tsx}

@@ -2,8 +2,15 @@
 
 import * as React from 'react';
 
+/** Possible values stored in a data-* attribute. */
 type DataStateValue = string | boolean | null;
 
+/**
+ * Parse a DOM dataset attribute string into a typed value.
+ *
+ * @param value - Raw attribute string
+ * @returns Parsed DataStateValue
+ */
 function parseDatasetValue(value: string | null): DataStateValue {
   if (value === null) return null;
   if (value === '' || value === 'true') return true;
@@ -11,6 +18,21 @@ function parseDatasetValue(value: string | null): DataStateValue {
   return value;
 }
 
+/**
+ * Hook that observes a `data-*` attribute on a DOM element via MutationObserver
+ * and returns the current value reactively.
+ *
+ * @param key - The data attribute key (without `data-` prefix)
+ * @param forwardedRef - Optional forwarded ref to merge
+ * @param onChange - Callback when value changes
+ * @returns Tuple of [currentValue, localRef]
+ *
+ * @example
+ * ```tsx
+ * const [state, ref] = useDataState<HTMLDivElement>('state');
+ * // Reacts to changes in `data-state` attribute on the element
+ * ```
+ */
 function useDataState<T extends HTMLElement = HTMLElement>(
   key: string,
   forwardedRef?: React.Ref<T | null>,

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

@@ -0,0 +1,17 @@
+/**
+ * Custom React hooks barrel export.
+ *
+ * @module @mks2508/mks-ui/react/hooks
+ */
+
+export { useAutoHeight } from './Animation/UseAutoHeight';
+export type { IAutoHeightOptions } from './Animation/UseAutoHeight';
+
+export { useControlledState } from './State/UseControlledState';
+export type { IControlledStateProps } from './State/UseControlledState';
+
+export { useDataState } from './State/UseDataState';
+export type { DataStateValue } from './State/UseDataState';
+
+export { useIsInView } from './DOM/UseIsInView';
+export type { IUseIsInViewOptions } from './DOM/UseIsInView';

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

@@ -0,0 +1,12 @@
+/**
+ * Icons barrel export - Organized by registry.
+ *
+ * @module @mks2508/mks-ui/react/icons
+ */
+
+// Lucide animated icons (preferred for animated icons)
+export * from './lucide-animated';
+
+// HugeIcons - re-exported as namespace to avoid naming conflicts
+// Use: import { HugeIcons } from '@mks2508/mks-ui/react'
+export * as HugeIcons from '@hugeicons/core-free-icons';

package/src/{icons → react-ui/icons}/lucide-animated/activity.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-ui/lib/utils";
 
 export interface ActivityIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/bell-electric.tsx

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface BellElectricIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/bell.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-ui/lib/utils";
 
 export interface BellIconHandle {
   startAnimation: () => void;

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

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface BotIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/box.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-ui/lib/utils";
 
 export interface BoxIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/circle-check.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-ui/lib/utils";
 
 export interface CircleCheckIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/delete.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-ui/lib/utils";
 
 export interface DeleteIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/download.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-ui/lib/utils";
 
 export interface DownloadIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/home.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-ui/lib/utils";
 
 export interface HomeIconHandle {
   startAnimation: () => void;

package/src/react-ui/icons/lucide-animated/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Lucide animated icons barrel export.
+ *
+ * @module @mks2508/mks-ui/react/icons/lucide-animated
+ */
+
+export * from './activity';
+export * from './arrow-down-to-line';
+export * from './arrow-up';
+export * from './bell';
+export * from './bell-electric';
+export * from './bot';
+export * from './box';
+export * from './check';
+export * from './circle-check';
+export * from './delete';
+export * from './download';
+export * from './edit-2';
+export * from './globe';
+export * from './home';
+export * from './layers';
+export * from './layout-panel-top';
+export * from './list';
+export * from './package';
+export * from './palette';
+export * from './plus';
+export * from './refresh-cw';
+export * from './rocket';
+export * from './save';
+export * from './search';
+export * from './settings';
+export * from './terminal';
+export * from './trash-2';
+export * from './trending-down';
+export * from './trending-up';
+export * from './type';
+export * from './upload';
+export * from './x';

package/src/{icons → react-ui/icons}/lucide-animated/layout-panel-top.tsx

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface LayoutPanelTopIconHandle {
   startAnimation: () => void;

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

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface PlusIconHandle {
   startAnimation: () => void;

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

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface SearchIconHandle {
   startAnimation: () => void;

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

@@ -4,7 +4,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-ui/lib/utils";
 
 export interface SettingsIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/icons}/lucide-animated/trending-down.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-ui/lib/utils";
 
 export interface TrendingDownIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/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-ui/lib/utils";
 
 export interface TrendingUpIconHandle {
   startAnimation: () => void;

package/src/{icons → react-ui/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-ui/lib/utils";
 
 export interface XIconHandle {
   startAnimation: () => void;

package/src/react-ui/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-ui/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-ui/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';