@mks2508/mks-ui 0.1.4 → 0.2.0

package/src/index.ts

@@ -1,23 +1,29 @@
 /**
  * @mks2508/mks-ui
  *
- * UI component library - Shadcn/Animate UI based with custom 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, CornerBracket } from '@mks2508/mks-ui';
- * import { useAutoHeight } from '@mks2508/mks-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';
-
-// Hooks
-export * from './hooks';
+// 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/react/hooks/Animation/UseAutoHeight.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * 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: IAutoHeightOptions = {
+    includeParentBox: true,
+    includeSelfBox: false,
+  },
+) {
+  const ref = React.useRef<T | null>(null);
+  const roRef = React.useRef<ResizeObserver | null>(null);
+  const [height, setHeight] = React.useState(0);
+
+  const measure = React.useCallback(() => {
+    const el = ref.current;
+    if (!el) return 0;
+
+    const base = el.getBoundingClientRect().height || 0;
+
+    let extra = 0;
+
+    if (options.includeParentBox && el.parentElement) {
+      const cs = getComputedStyle(el.parentElement);
+      const paddingY =
+        (parseFloat(cs.paddingTop || '0') || 0) +
+        (parseFloat(cs.paddingBottom || '0') || 0);
+      const borderY =
+        (parseFloat(cs.borderTopWidth || '0') || 0) +
+        (parseFloat(cs.borderBottomWidth || '0') || 0);
+      const isBorderBox = cs.boxSizing === 'border-box';
+      if (isBorderBox) {
+        extra += paddingY + borderY;
+      }
+    }
+
+    if (options.includeSelfBox) {
+      const cs = getComputedStyle(el);
+      const paddingY =
+        (parseFloat(cs.paddingTop || '0') || 0) +
+        (parseFloat(cs.paddingBottom || '0') || 0);
+      const borderY =
+        (parseFloat(cs.borderTopWidth || '0') || 0) +
+        (parseFloat(cs.borderBottomWidth || '0') || 0);
+      const isBorderBox = cs.boxSizing === 'border-box';
+      if (isBorderBox) {
+        extra += paddingY + borderY;
+      }
+    }
+
+    const dpr =
+      typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+    const total = Math.ceil((base + extra) * dpr) / dpr;
+
+    return total;
+  }, [options.includeParentBox, options.includeSelfBox]);
+
+  React.useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    setHeight(measure());
+
+    if (roRef.current) {
+      roRef.current.disconnect();
+      roRef.current = null;
+    }
+
+    const ro = new ResizeObserver(() => {
+      const next = measure();
+      requestAnimationFrame(() => setHeight(next));
+    });
+
+    ro.observe(el);
+    if (options.includeParentBox && el.parentElement) {
+      ro.observe(el.parentElement);
+    }
+
+    roRef.current = ro;
+
+    return () => {
+      ro.disconnect();
+      roRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  React.useLayoutEffect(() => {
+    if (height === 0) {
+      const next = measure();
+      if (next !== 0) setHeight(next);
+    }
+  }, [height, measure]);
+
+  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/react/hooks/State/UseControlledState.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+
+/**
+ * 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: IControlledStateProps<T> & {
+    onChange?: (value: T, ...args: Rest) => void;
+  },
+): readonly [T, (next: T, ...args: Rest) => void] {
+  const { value, defaultValue, onChange } = props;
+
+  const [state, setInternalState] = React.useState<T>(
+    value !== undefined ? value : (defaultValue as T),
+  );
+
+  React.useEffect(() => {
+    if (value !== undefined) setInternalState(value);
+  }, [value]);
+
+  const setState = React.useCallback(
+    (next: T, ...args: Rest) => {
+      setInternalState(next);
+      onChange?.(next, ...args);
+    },
+    [onChange],
+  );
+
+  return [state, setState] as const;
+}
+
+export type { IControlledStateProps };

package/src/react/hooks/State/UseDataState.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+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;
+  if (value === 'false') return false;
+  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>,
+  onChange?: (value: DataStateValue) => void,
+): [DataStateValue, React.RefObject<T | null>] {
+  const localRef = React.useRef<T | null>(null);
+  React.useImperativeHandle(forwardedRef, () => localRef.current as T);
+
+  const getSnapshot = (): DataStateValue => {
+    const el = localRef.current;
+    return el ? parseDatasetValue(el.getAttribute(`data-${key}`)) : null;
+  };
+
+  const subscribe = (callback: () => void) => {
+    const el = localRef.current;
+    if (!el) return () => {};
+    const observer = new MutationObserver((records) => {
+      for (const record of records) {
+        if (record.attributeName === `data-${key}`) {
+          callback();
+          break;
+        }
+      }
+    });
+    observer.observe(el, {
+      attributes: true,
+      attributeFilter: [`data-${key}`],
+    });
+    return () => observer.disconnect();
+  };
+
+  const value = React.useSyncExternalStore(subscribe, getSnapshot);
+
+  React.useEffect(() => {
+    if (onChange) onChange(value);
+  }, [value, onChange]);
+
+  return [value, localRef];
+}
+
+export { useDataState, type DataStateValue };

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';