@mks2508/mks-ui 0.2.0 → 0.3.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/hooks/Formatting/UseListFormat.ts

@@ -0,0 +1,134 @@
+import { useMemo } from 'react';
+
+/** Intl.ListFormat conjunction/disjunction/unit type */
+export type ListFormatType = 'conjunction' | 'disjunction' | 'unit';
+
+/** Intl.ListFormat style: long, short, or narrow */
+export type ListFormatStyle = 'long' | 'short' | 'narrow';
+
+/** Options for useListFormat hook */
+export interface IUseListFormatOptions {
+  locale?: string;
+  type?: ListFormatType;
+  style?: ListFormatStyle;
+  separator?: string;
+  /** If true, format as if there's one more item (avoids "and" before overflow counter) */
+  hasOverflow?: boolean;
+}
+
+/** A single part of a formatted list (element or separator) */
+export interface IListPart {
+  type: 'element' | 'literal';
+  value: string;
+  index: number;
+}
+
+const getDefaultLocale = (): string => {
+  if (typeof navigator !== 'undefined' && navigator.language) {
+    return navigator.language;
+  }
+  return 'en';
+};
+
+/**
+ * Hook for locale-aware list formatting using Intl.ListFormat.
+ *
+ * Provides parts that can be rendered individually with animations.
+ * Uses the browser's Intl.ListFormat API for proper locale handling.
+ *
+ * @param items - Array of strings to format
+ * @param options - Locale, type, style, separator override, overflow flag
+ * @returns Array of list parts (elements and literals)
+ *
+ * @example
+ * ```tsx
+ * // Automatic locale detection
+ * const parts = useListFormat(['Apple', 'Banana', 'Cherry']);
+ * // en: [{ type: 'element', value: 'Apple' }, { type: 'literal', value: ', ' }, ...]
+ *
+ * // Spanish
+ * const parts = useListFormat(['Apple', 'Banana'], { locale: 'es' });
+ *
+ * // Disjunction ("or")
+ * const parts = useListFormat(['A', 'B', 'C'], { type: 'disjunction' });
+ * // en: "A, B, or C"
+ *
+ * // Manual separator override
+ * const parts = useListFormat(['A', 'B', 'C'], { separator: ' | ' });
+ * // "A | B | C"
+ * ```
+ */
+export function useListFormat(
+  items: string[],
+  options: IUseListFormatOptions = {}
+): IListPart[] {
+  const {
+    locale,
+    type = 'conjunction',
+    style = 'long',
+    separator,
+    hasOverflow
+  } = options;
+
+  return useMemo(() => {
+    if (items.length === 0) return [];
+
+    // Manual override mode: use fixed separator
+    if (separator !== undefined) {
+      const parts: IListPart[] = [];
+      items.forEach((item, i) => {
+        parts.push({ type: 'element', value: item, index: i });
+        if (i < items.length - 1) {
+          parts.push({ type: 'literal', value: separator, index: i });
+        }
+      });
+      return parts;
+    }
+
+    // Use Intl.ListFormat for locale-aware formatting
+    const resolvedLocale = locale ?? getDefaultLocale();
+
+    try {
+      const formatter = new Intl.ListFormat(resolvedLocale, { type, style });
+
+      // If hasOverflow, add a placeholder to make Intl.ListFormat use commas
+      // instead of "and" before the overflow counter
+      const itemsToFormat = (hasOverflow && items.length > 1)
+        ? [...items, '']
+        : items;
+
+      const formatted = formatter.formatToParts(itemsToFormat);
+
+      // If hasOverflow, remove the last part (placeholder and its separator)
+      const partsToProcess = hasOverflow
+        ? formatted.slice(0, -2)
+        : formatted;
+
+      let elementIndex = 0;
+      return partsToProcess.map((part): IListPart => {
+        if (part.type === 'element') {
+          return {
+            type: 'element',
+            value: part.value,
+            index: elementIndex++
+          };
+        }
+        return {
+          type: 'literal',
+          value: part.value,
+          index: Math.max(0, elementIndex - 1)
+        };
+      });
+    } catch {
+      // Fallback if Intl.ListFormat fails
+      const parts: IListPart[] = [];
+      items.forEach((item, i) => {
+        parts.push({ type: 'element', value: item, index: i });
+        if (i < items.length - 1) {
+          parts.push({ type: 'literal', value: ', ', index: i });
+        }
+      });
+      return parts;
+    }
+  }, [items, locale, type, style, separator, hasOverflow]);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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';
+
+export { useListFormat } from './Formatting/UseListFormat';
+export type { IUseListFormatOptions, IListPart, ListFormatType, ListFormatStyle } from './Formatting/UseListFormat';

package/src/react-ui/icons/lucide-animated/activity.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import type { Variants } from "framer-motion";
+import { motion, useAnimation } from "framer-motion";
+import type { HTMLAttributes } from "react";
+import { forwardRef, useCallback, useImperativeHandle, useRef } from "react";
+
+import { cn } from "@/react-ui/lib/utils";
+
+export interface ActivityIconHandle {
+  startAnimation: () => void;
+  stopAnimation: () => void;
+}
+
+interface ActivityIconProps extends HTMLAttributes<HTMLDivElement> {
+  size?: number;
+}
+
+const VARIANTS: Variants = {
+  normal: {
+    opacity: 1,
+    pathLength: 1,
+    pathOffset: 0,
+    transition: {
+      duration: 0.4,
+      opacity: { duration: 0.1 },
+    },
+  },
+  animate: {
+    opacity: [0, 1],
+    pathLength: [0, 1],
+    pathOffset: [1, 0],
+    transition: {
+      duration: 0.6,
+      ease: "linear",
+      opacity: { duration: 0.1 },
+    },
+  },
+};
+
+const ActivityIcon = forwardRef<ActivityIconHandle, ActivityIconProps>(
+  ({ onMouseEnter, onMouseLeave, className, size = 28, ...props }, ref) => {
+    const controls = useAnimation();
+    const isControlledRef = useRef(false);
+
+    useImperativeHandle(ref, () => {
+      isControlledRef.current = true;
+
+      return {
+        startAnimation: () => controls.start("animate"),
+        stopAnimation: () => controls.start("normal"),
+      };
+    });
+
+    const handleMouseEnter = useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        if (isControlledRef.current) {
+          onMouseEnter?.(e);
+        } else {
+          controls.start("animate");
+        }
+      },
+      [controls, onMouseEnter]
+    );
+
+    const handleMouseLeave = useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        if (isControlledRef.current) {
+          onMouseLeave?.(e);
+        } else {
+          controls.start("normal");
+        }
+      },
+      [controls, onMouseLeave]
+    );
+
+    return (
+      <div
+        className={cn(className)}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        {...props}
+      >
+        <svg
+          fill="none"
+          height={size}
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2"
+          viewBox="0 0 24 24"
+          width={size}
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <motion.path
+            animate={controls}
+            d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2"
+            initial="normal"
+            variants={VARIANTS}
+          />
+        </svg>
+      </div>
+    );
+  }
+);
+
+ActivityIcon.displayName = "ActivityIcon";
+
+export { ActivityIcon };

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

@@ -0,0 +1,124 @@
+"use client";
+
+import { motion, useAnimation } from "framer-motion";
+import type { HTMLAttributes } from "react";
+import { forwardRef, useCallback, useImperativeHandle, useRef } from "react";
+
+import { cn } from "@/react-ui/lib/utils";
+
+export interface BellElectricIconHandle {
+  startAnimation: () => void;
+  stopAnimation: () => void;
+}
+
+interface BellElectricIconProps extends HTMLAttributes<HTMLDivElement> {
+  size?: number;
+}
+
+const BellElectricIcon = forwardRef<
+  BellElectricIconHandle,
+  BellElectricIconProps
+>(({ onMouseEnter, onMouseLeave, className, size = 28, ...props }, ref) => {
+  const controls = useAnimation();
+  const isControlledRef = useRef(false);
+
+  useImperativeHandle(ref, () => {
+    isControlledRef.current = true;
+    return {
+      startAnimation: () => controls.start("animate"),
+      stopAnimation: () => controls.start("normal"),
+    };
+  });
+
+  const handleMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (isControlledRef.current) {
+        onMouseEnter?.(e);
+      } else {
+        controls.start("animate");
+      }
+    },
+    [controls, onMouseEnter]
+  );
+
+  const handleMouseLeave = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (isControlledRef.current) {
+        onMouseLeave?.(e);
+      } else {
+        controls.start("normal");
+      }
+    },
+    [controls, onMouseLeave]
+  );
+
+  return (
+    <div
+      className={cn(className)}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      {...props}
+    >
+      <motion.svg
+        animate={controls}
+        fill="none"
+        height={size}
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+        style={{ transformBox: "fill-box", transformOrigin: "50% 50%" }}
+        transition={{ duration: 0.9 }}
+        variants={{
+          normal: { rotate: 0, translateX: 0, translateY: 0 },
+          animate: {
+            rotate: [0, -12, 12, -8, 8, 0],
+            translateX: [0, -1.5, 1.5, -1, 1, 0],
+            translateY: [0, -1, 1, -0.5, 0.5, 0],
+          },
+        }}
+        viewBox="0 0 24 24"
+        width={size}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path d="M18.518 17.347A7 7 0 0 1 14 19" />
+        <motion.path
+          animate={controls}
+          d="M18.8 4A11 11 0 0 1 20 9"
+          style={{ transformBox: "fill-box", originX: "50%", originY: "50%" }}
+          transition={{ duration: 0.9 }}
+          variants={{
+            normal: { translateX: 0, translateY: 0, rotate: 0 },
+            animate: {
+              translateX: [0, -0.8, 0.8, -0.6, 0.6, 0],
+              translateY: [0, -0.5, 0.5, -0.3, 0.3, 0],
+              rotate: [0, -6, 6, -4, 4, 0],
+            },
+          }}
+        />
+        <motion.path
+          animate={controls}
+          d="M9 9h.01"
+          style={{ transformBox: "fill-box", originX: "50%", originY: "50%" }}
+          transition={{ duration: 0.75 }}
+          variants={{
+            normal: { translateX: 0, translateY: 0, rotate: 0, scale: 1 },
+            animate: {
+              translateX: [0, -1.6, 1.6, -1.2, 1.2, 0],
+              translateY: [0, -1.2, 1.2, -0.8, 0.8, 0],
+              rotate: [0, -10, 10, -7, 7, 0],
+              scale: [1, 1.08, 0.95, 1.06, 0.98, 1],
+            },
+          }}
+        />
+        <circle cx="9" cy="9" r="7" />
+        <rect height="6" rx="2" width="10" x="4" y="16" />
+        <circle cx="20" cy="16" r="2" />
+      </motion.svg>
+    </div>
+  );
+});
+
+BellElectricIcon.displayName = "BellElectricIcon";
+
+export { BellElectricIcon };

package/src/react-ui/icons/lucide-animated/bell.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import type { Variants } from "framer-motion";
+import { motion, useAnimation } from "framer-motion";
+import type { HTMLAttributes } from "react";
+import { forwardRef, useCallback, useImperativeHandle, useRef } from "react";
+
+import { cn } from "@/react-ui/lib/utils";
+
+export interface BellIconHandle {
+  startAnimation: () => void;
+  stopAnimation: () => void;
+}
+
+interface BellIconProps extends HTMLAttributes<HTMLDivElement> {
+  size?: number;
+}
+
+const SVG_VARIANTS: Variants = {
+  normal: { rotate: 0 },
+  animate: { rotate: [0, -10, 10, -10, 0] },
+};
+
+const BellIcon = forwardRef<BellIconHandle, BellIconProps>(
+  ({ onMouseEnter, onMouseLeave, className, size = 28, ...props }, ref) => {
+    const controls = useAnimation();
+    const isControlledRef = useRef(false);
+
+    useImperativeHandle(ref, () => {
+      isControlledRef.current = true;
+
+      return {
+        startAnimation: () => controls.start("animate"),
+        stopAnimation: () => controls.start("normal"),
+      };
+    });
+
+    const handleMouseEnter = useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        if (isControlledRef.current) {
+          onMouseEnter?.(e);
+        } else {
+          controls.start("animate");
+        }
+      },
+      [controls, onMouseEnter]
+    );
+
+    const handleMouseLeave = useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        if (isControlledRef.current) {
+          onMouseLeave?.(e);
+        } else {
+          controls.start("normal");
+        }
+      },
+      [controls, onMouseLeave]
+    );
+    return (
+      <div
+        className={cn(className)}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        {...props}
+      >
+        <motion.svg
+          animate={controls}
+          fill="none"
+          height={size}
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2"
+          transition={{
+            duration: 0.5,
+            ease: "easeInOut",
+          }}
+          variants={SVG_VARIANTS}
+          viewBox="0 0 24 24"
+          width={size}
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9" />
+          <path d="M10.3 21a1.94 1.94 0 0 0 3.4 0" />
+        </motion.svg>
+      </div>
+    );
+  }
+);
+
+BellIcon.displayName = "BellIcon";
+
+export { BellIcon };