@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/index.ts

@@ -1,20 +1,29 @@
 /**
  * @mks2508/mks-ui
  *
- * UI component library - Shadcn/Animate UI based with DevEnv components.
+ * UI component library - Framework-agnostic core types and React components.
+ *
+ * ## Entry Points
+ *
+ * ### Main Entry (Core Types)
+ * ```typescript
+ * import type { StyleSlots, SlotOverrides, IBaseConfig } from '@mks2508/mks-ui';
+ * ```
+ *
+ * ### React Entry (Components, Hooks, Icons, Utils)
+ * ```typescript
+ * import { Button, Card, CornerBracket } from '@mks2508/mks-ui/react';
+ * import { useAutoHeight } from '@mks2508/mks-ui/react';
+ * import { Check, Search } from '@mks2508/mks-ui/react';
+ * import { cn } from '@mks2508/mks-ui/react';
+ * ```
  *
  * @example
  * ```tsx
- * import { Button, Card } from '@mks2508/mks-ui';
- * import { DevEnvBracket } from '@mks2508/mks-ui/components/ui';
+ * import type { StyleSlots } from '@mks2508/mks-ui';
+ * import { Button, Card, CornerBracket } from '@mks2508/mks-ui/react';
  * ```
  */
 
-// Utilities
-export * from './lib/utils';
-
-// UI Components
-export * from './components/ui';
-
-// Icons
-export * from './icons';
+// Core types (framework-agnostic)
+export * from './core';

package/src/react/components/MorphingPopover/MorphingPopover.types.ts

@@ -0,0 +1,49 @@
+/**
+ * Props for the MorphingPopover component.
+ *
+ * @interface IMorphingPopoverProps
+ */
+interface IMorphingPopoverProps {
+  /** Content to display in popover. */
+  content: React.ReactNode;
+  /** Trigger button text or icon. */
+  trigger?: React.ReactNode;
+  /** Additional CSS classes for trigger button. */
+  triggerClassName?: string;
+  /** Additional CSS classes for popover. */
+  popoverClassName?: string;
+  /** Target dimensions for the expanded popover. */
+  targetSize?: { width?: number; height?: number };
+  /** Callback when popover opens. */
+  onOpen?: () => void;
+  /** Callback when popover closes. */
+  onClose?: () => void;
+  /** Popover HTML ID. */
+  popoverId?: string;
+}
+
+/** Extended button props to support the Popover API attributes. */
+interface IMorphingButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  popovertarget?: string;
+  popoverTargetAction?: 'toggle' | 'show' | 'hide';
+}
+
+/**
+ * Props for the MorphingPopoverWithTarget variant.
+ *
+ * @interface IMorphingPopoverWithTargetProps
+ */
+interface IMorphingPopoverWithTargetProps
+  extends Omit<IMorphingPopoverProps, 'popoverId' | 'targetSize'> {
+  /** Reference to target element to anchor to. */
+  targetRef: React.RefObject<HTMLElement>;
+  /** Popover HTML ID. */
+  popoverId?: string;
+}
+
+export type {
+  IMorphingPopoverProps,
+  IMorphingButtonProps,
+  IMorphingPopoverWithTargetProps,
+};

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

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

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

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

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

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

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

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

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

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

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

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

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

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