@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/react/ui/Tooltip/Tooltip.types.ts

@@ -0,0 +1,253 @@
+/**
+ * Type definitions for the Tooltip component.
+ *
+ * Provides all prop interfaces, slot types, context types, and configuration
+ * for the animated tooltip system built on Base UI and Motion.
+ *
+ * @module @mks2508/mks-ui/react/ui/Tooltip/Tooltip.types
+ */
+
+import type * as React from 'react';
+import type { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
+import type { HTMLMotionProps, MotionValue, SpringOptions } from 'motion/react';
+
+import type { SlotOverrides, IBaseConfig } from '@/core/types';
+
+/* -------------------------------------------------------------------------- */
+/*  Slot                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Visual regions available for class-name overrides via the `slots` prop.
+ *
+ * @example
+ * ```tsx
+ * <TooltipPopup slots={{ popup: 'bg-primary text-primary-foreground' }} />
+ * ```
+ */
+export type TooltipSlot =
+  | 'root'
+  | 'popup'
+  | 'trigger'
+  | 'positioner'
+  | 'arrow';
+
+/* -------------------------------------------------------------------------- */
+/*  Config                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Extended configuration for the Tooltip component.
+ * Inherits base animation settings and adds tooltip-specific cursor-following options.
+ *
+ * @example
+ * ```typescript
+ * const config: ITooltipConfig = {
+ *   followCursor: 'x',
+ *   followCursorSpringOptions: { stiffness: 200, damping: 17 },
+ *   animation: { duration: 0.15 },
+ * };
+ * ```
+ */
+export interface ITooltipConfig extends IBaseConfig {
+  /**
+   * Whether the tooltip follows the cursor position.
+   * - `true` — follows on both axes
+   * - `'x'` — follows only horizontal movement
+   * - `'y'` — follows only vertical movement
+   * - `false` — static positioning (default)
+   *
+   * @defaultValue false
+   */
+  followCursor?: boolean | 'x' | 'y';
+
+  /**
+   * Spring physics options for the cursor-following animation.
+   * Only used when `followCursor` is enabled.
+   *
+   * @defaultValue `{ stiffness: 200, damping: 17 }`
+   */
+  followCursorSpringOptions?: SpringOptions;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Internal context type shared between Tooltip sub-components.
+ * Tracks open state, cursor position motion values, and follow-cursor settings.
+ *
+ * @example
+ * ```tsx
+ * const { isOpen, x, y, followCursor } = useTooltip();
+ * ```
+ */
+export type TooltipContextType = {
+  /** Whether the tooltip is currently open. */
+  isOpen: boolean;
+  /** Callback to change the open state. */
+  setIsOpen: ITooltipProps['onOpenChange'];
+  /** Motion value tracking horizontal cursor offset. */
+  x: MotionValue<number>;
+  /** Motion value tracking vertical cursor offset. */
+  y: MotionValue<number>;
+  /** Current follow-cursor mode. */
+  followCursor?: boolean | 'x' | 'y';
+  /** Spring physics options for cursor-following. */
+  followCursorSpringOptions?: SpringOptions;
+};
+
+/* -------------------------------------------------------------------------- */
+/*  Props interfaces                                                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Props for the root `Tooltip` component.
+ * Wraps Base UI Tooltip.Root with controlled-state support, context provider,
+ * and cursor-following motion values.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip followCursor="x">
+ *   <TooltipTrigger>Hover me</TooltipTrigger>
+ *   <TooltipPortal>
+ *     <TooltipPositioner>
+ *       <TooltipPopup>Tooltip content</TooltipPopup>
+ *     </TooltipPositioner>
+ *   </TooltipPortal>
+ * </Tooltip>
+ * ```
+ */
+export interface ITooltipProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Root> {
+  /**
+   * Whether the tooltip follows the cursor position.
+   * @defaultValue false
+   */
+  followCursor?: boolean | 'x' | 'y';
+
+  /**
+   * Spring physics options for the cursor-following animation.
+   * @defaultValue `{ stiffness: 200, damping: 17 }`
+   */
+  followCursorSpringOptions?: SpringOptions;
+
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+
+  /** Component configuration. */
+  config?: ITooltipConfig;
+}
+
+/**
+ * Props for the `TooltipProvider` component.
+ * Wraps Base UI Tooltip.Provider to set shared defaults for a group of tooltips.
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider delay={200}>
+ *   <Tooltip>...</Tooltip>
+ *   <Tooltip>...</Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+export interface ITooltipProviderProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Provider> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}
+
+/**
+ * Props for the `TooltipTrigger` component.
+ * Renders the element that shows the tooltip on hover/focus.
+ *
+ * @example
+ * ```tsx
+ * <TooltipTrigger>
+ *   <Button>Hover me</Button>
+ * </TooltipTrigger>
+ * ```
+ */
+export interface ITooltipTriggerProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Trigger> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}
+
+/**
+ * Props for the `TooltipPortal` component.
+ * Renders children into a React portal with AnimatePresence for exit animations.
+ * The `keepMounted` prop is handled internally and cannot be overridden.
+ *
+ * @example
+ * ```tsx
+ * <TooltipPortal>
+ *   <TooltipPositioner>
+ *     <TooltipPopup>...</TooltipPopup>
+ *   </TooltipPositioner>
+ * </TooltipPortal>
+ * ```
+ */
+export interface ITooltipPortalProps
+  extends Omit<
+    React.ComponentProps<typeof TooltipPrimitive.Portal>,
+    'keepMounted'
+  > {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}
+
+/**
+ * Props for the `TooltipPositioner` component.
+ * Handles automatic positioning relative to the trigger.
+ *
+ * @example
+ * ```tsx
+ * <TooltipPositioner sideOffset={4}>
+ *   <TooltipPopup>Content</TooltipPopup>
+ * </TooltipPositioner>
+ * ```
+ */
+export interface ITooltipPositionerProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Positioner> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}
+
+/**
+ * Props for the `TooltipPopup` component.
+ * The main content container with scale entrance animation.
+ * Supports cursor-following via spring-animated motion values.
+ *
+ * @example
+ * ```tsx
+ * <TooltipPopup className="px-3 py-1.5 text-sm">
+ *   Helpful information
+ * </TooltipPopup>
+ * ```
+ */
+export interface ITooltipPopupProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof TooltipPrimitive.Popup>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}
+
+/**
+ * Props for the `TooltipArrow` component.
+ * Renders a directional arrow pointing toward the trigger.
+ *
+ * @example
+ * ```tsx
+ * <TooltipArrow className="fill-primary" />
+ * ```
+ */
+export interface ITooltipArrowProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Arrow> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<TooltipSlot>;
+}

package/src/react/ui/Tooltip/index.tsx

@@ -0,0 +1,394 @@
+'use client';
+
+/**
+ * Animated Tooltip component built on Base UI Tooltip and Motion.
+ *
+ * Provides a positioned tooltip with scale entrance animation,
+ * optional cursor-following via spring-animated motion values,
+ * arrow support, and full AnimatePresence exit transitions.
+ * All sub-components accept a `slots` prop for class-name overrides
+ * following the StyleSlots pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui/Tooltip
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   TooltipProvider,
+ *   Tooltip,
+ *   TooltipTrigger,
+ *   TooltipPortal,
+ *   TooltipPositioner,
+ *   TooltipPopup,
+ *   TooltipArrow,
+ * } from '@mks2508/mks-ui';
+ *
+ * function Example() {
+ *   return (
+ *     <TooltipProvider>
+ *       <Tooltip followCursor="x">
+ *         <TooltipTrigger>
+ *           <button>Hover me</button>
+ *         </TooltipTrigger>
+ *         <TooltipPortal>
+ *           <TooltipPositioner sideOffset={4}>
+ *             <TooltipPopup>
+ *               <TooltipArrow />
+ *               Helpful information
+ *             </TooltipPopup>
+ *           </TooltipPositioner>
+ *         </TooltipPortal>
+ *       </Tooltip>
+ *     </TooltipProvider>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
+import {
+  AnimatePresence,
+  motion,
+  useMotionValue,
+  useSpring,
+} from 'motion/react';
+
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { useControlledState } from '@/react/hooks/State/UseControlledState';
+import { cn } from '@/react/lib/utils';
+
+import { tooltipStyles } from './Tooltip.styles';
+import type {
+  TooltipContextType,
+  ITooltipProps,
+  ITooltipProviderProps,
+  ITooltipTriggerProps,
+  ITooltipPortalProps,
+  ITooltipPositionerProps,
+  ITooltipPopupProps,
+  ITooltipArrowProps,
+} from './Tooltip.types';
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const [LocalTooltipProvider, useTooltip] =
+  getStrictContext<TooltipContextType>('TooltipContext');
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipProvider                                                           */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Shared configuration provider for a group of tooltips.
+ * Sets defaults like delay, skip-delay, and close-delay for all nested Tooltips.
+ *
+ * @param props - Provider props forwarded to Base UI Tooltip.Provider
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider delay={200}>
+ *   <Tooltip>...</Tooltip>
+ *   <Tooltip>...</Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+function TooltipProvider({ slots: _slots, ...props }: ITooltipProviderProps) {
+  return (
+    <TooltipPrimitive.Provider data-slot="tooltip-provider" {...props} />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Tooltip (Root)                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Root Tooltip component.
+ * Manages controlled/uncontrolled open state, cursor-following motion values,
+ * and provides context to children.
+ *
+ * @param props - Tooltip root props including `followCursor` and spring options
+ *
+ * @example
+ * ```tsx
+ * <Tooltip followCursor="x" followCursorSpringOptions={{ stiffness: 300 }}>
+ *   <TooltipTrigger>Hover</TooltipTrigger>
+ *   <TooltipPortal>
+ *     <TooltipPositioner>
+ *       <TooltipPopup>Content</TooltipPopup>
+ *     </TooltipPositioner>
+ *   </TooltipPortal>
+ * </Tooltip>
+ * ```
+ */
+function Tooltip({
+  followCursor = false,
+  followCursorSpringOptions = { stiffness: 200, damping: 17 },
+  slots,
+  config: _config,
+  ...props
+}: ITooltipProps) {
+  const [isOpen, setIsOpen] = useControlledState({
+    value: props?.open,
+    defaultValue: props?.defaultOpen,
+    onChange: props?.onOpenChange,
+  });
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+
+  return (
+    <LocalTooltipProvider
+      value={{
+        isOpen,
+        setIsOpen,
+        x,
+        y,
+        followCursor,
+        followCursorSpringOptions,
+      }}
+    >
+      <TooltipPrimitive.Root
+        data-slot="tooltip"
+        {...props}
+        onOpenChange={setIsOpen}
+      />
+    </LocalTooltipProvider>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipTrigger                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Trigger element that shows the tooltip on hover/focus.
+ * Tracks mouse position when `followCursor` is enabled on the parent Tooltip.
+ *
+ * @param props - Trigger props forwarded to Base UI Tooltip.Trigger
+ *
+ * @example
+ * ```tsx
+ * <TooltipTrigger>
+ *   <button>Hover me</button>
+ * </TooltipTrigger>
+ * ```
+ */
+function TooltipTrigger({
+  onMouseMove,
+  slots,
+  className,
+  ...props
+}: ITooltipTriggerProps) {
+  const { x, y, followCursor } = useTooltip();
+
+  const handleMouseMove = (
+    event: Parameters<NonNullable<ITooltipTriggerProps['onMouseMove']>>[0],
+  ) => {
+    onMouseMove?.(event);
+
+    const target = event.currentTarget.getBoundingClientRect();
+
+    if (followCursor === 'x' || followCursor === true) {
+      const eventOffsetX = event.clientX - target.left;
+      const offsetXFromCenter = (eventOffsetX - target.width / 2) / 2;
+      x.set(offsetXFromCenter);
+    }
+
+    if (followCursor === 'y' || followCursor === true) {
+      const eventOffsetY = event.clientY - target.top;
+      const offsetYFromCenter = (eventOffsetY - target.height / 2) / 2;
+      y.set(offsetYFromCenter);
+    }
+  };
+
+  return (
+    <TooltipPrimitive.Trigger
+      data-slot="tooltip-trigger"
+      className={cn(tooltipStyles.trigger, slots?.trigger, className)}
+      onMouseMove={handleMouseMove}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPortal                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Portal wrapper with AnimatePresence for coordinated enter/exit animations.
+ * Internally sets `keepMounted` so motion exit animations play correctly.
+ *
+ * @param props - Portal props (without keepMounted)
+ *
+ * @example
+ * ```tsx
+ * <TooltipPortal>
+ *   <TooltipPositioner>
+ *     <TooltipPopup>...</TooltipPopup>
+ *   </TooltipPositioner>
+ * </TooltipPortal>
+ * ```
+ */
+function TooltipPortal({ slots: _slots, ...props }: ITooltipPortalProps) {
+  const { isOpen } = useTooltip();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <TooltipPrimitive.Portal
+          keepMounted
+          data-slot="tooltip-portal"
+          {...props}
+        />
+      )}
+    </AnimatePresence>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPositioner                                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Positioning wrapper that automatically places the popup relative to the trigger.
+ *
+ * @param props - Positioner props forwarded to Base UI Tooltip.Positioner
+ *
+ * @example
+ * ```tsx
+ * <TooltipPositioner sideOffset={4}>
+ *   <TooltipPopup>Content</TooltipPopup>
+ * </TooltipPositioner>
+ * ```
+ */
+function TooltipPositioner({
+  slots,
+  className,
+  ...props
+}: ITooltipPositionerProps) {
+  return (
+    <TooltipPrimitive.Positioner
+      data-slot="tooltip-positioner"
+      className={cn(tooltipStyles.positioner, slots?.positioner, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipPopup                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Main tooltip content container with scale entrance animation.
+ * Supports spring-animated cursor-following when `followCursor` is enabled
+ * on the parent Tooltip.
+ *
+ * @param props - Popup props including motion transition overrides
+ *
+ * @example
+ * ```tsx
+ * <TooltipPopup slots={{ popup: 'bg-primary text-primary-foreground' }}>
+ *   Helpful information
+ * </TooltipPopup>
+ * ```
+ */
+function TooltipPopup({
+  transition = { type: 'spring', stiffness: 300, damping: 25 },
+  style,
+  slots,
+  className,
+  ...props
+}: ITooltipPopupProps) {
+  const { x, y, followCursor, followCursorSpringOptions } = useTooltip();
+  const translateX = useSpring(x, followCursorSpringOptions);
+  const translateY = useSpring(y, followCursorSpringOptions);
+
+  return (
+    <TooltipPrimitive.Popup
+      render={
+        <motion.div
+          key="tooltip-popup"
+          data-slot="tooltip-popup"
+          className={cn(tooltipStyles.popup, slots?.popup, className)}
+          initial={{ opacity: 0, scale: 0.5 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.5 }}
+          transition={transition}
+          style={{
+            x:
+              followCursor === 'x' || followCursor === true
+                ? translateX
+                : undefined,
+            y:
+              followCursor === 'y' || followCursor === true
+                ? translateY
+                : undefined,
+            ...style,
+          }}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  TooltipArrow                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Directional arrow pointing toward the trigger element.
+ *
+ * @param props - Arrow props forwarded to Base UI Tooltip.Arrow
+ *
+ * @example
+ * ```tsx
+ * <TooltipArrow slots={{ arrow: 'fill-primary' }} />
+ * ```
+ */
+function TooltipArrow({ slots, className, ...props }: ITooltipArrowProps) {
+  return (
+    <TooltipPrimitive.Arrow
+      data-slot="tooltip-arrow"
+      className={cn(tooltipStyles.arrow, slots?.arrow, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Exports                                                                   */
+/* -------------------------------------------------------------------------- */
+
+export {
+  TooltipProvider,
+  Tooltip,
+  TooltipTrigger,
+  TooltipPortal,
+  TooltipPositioner,
+  TooltipPopup,
+  TooltipArrow,
+  useTooltip,
+};
+
+// Re-exports from types
+export type {
+  ITooltipProviderProps,
+  ITooltipProps,
+  ITooltipTriggerProps,
+  ITooltipPortalProps,
+  ITooltipPositionerProps,
+  ITooltipPopupProps,
+  ITooltipArrowProps,
+  TooltipContextType,
+  TooltipSlot,
+  ITooltipConfig,
+} from './Tooltip.types';
+
+// Re-exports from styles
+export { tooltipStyles } from './Tooltip.styles';

package/src/react/ui/index.ts

@@ -0,0 +1,34 @@
+/**
+ * UI components barrel export.
+ *
+ * All public UI components built on Base UI primitives with StyleSlots/CVA pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui
+ */
+
+// Animate UI components
+export * from './Accordion';
+export * from './AlertDialog';
+export * from './Checkbox';
+export * from './Dialog';
+export * from './Menu';
+export * from './Popover';
+export * from './Progress';
+export * from './Switch';
+export * from './Tabs';
+export * from './Tooltip';
+
+// Base UI components
+export * from './Badge';
+export * from './Button';
+export * from './Card';
+export * from './Combobox';
+export * from './CornerBracket';
+export * from './DropdownMenu';
+export * from './Field';
+export * from './Input';
+export * from './InputGroup';
+export * from './Label';
+export * from './Select';
+export * from './Separator';
+export * from './Textarea';

package/dist/components/animate-ui/primitives/animate/slot.d.ts

@@ -1,18 +0,0 @@
-import * as React from 'react';
-import { type HTMLMotionProps } from 'motion/react';
-type AnyProps = Record<string, unknown>;
-type DOMMotionProps<T extends HTMLElement = HTMLElement> = Omit<HTMLMotionProps<keyof HTMLElementTagNameMap>, 'ref'> & {
-    ref?: React.Ref<T>;
-};
-type WithAsChild<Base extends object> = (Base & {
-    asChild: true;
-    children: React.ReactElement;
-}) | (Base & {
-    asChild?: false | undefined;
-});
-type SlotProps<T extends HTMLElement = HTMLElement> = {
-    children?: any;
-} & DOMMotionProps<T>;
-declare function Slot<T extends HTMLElement = HTMLElement>({ children, ref, ...props }: SlotProps<T>): import("react/jsx-runtime").JSX.Element | null;
-export { Slot, type SlotProps, type WithAsChild, type DOMMotionProps, type AnyProps, };
-//# sourceMappingURL=slot.d.ts.map

package/dist/components/animate-ui/primitives/animate/slot.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"slot.d.ts","sourceRoot":"","sources":["../../../../../src/components/animate-ui/primitives/animate/slot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/E,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC,KAAK,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,IAAI,IAAI,CAC7D,eAAe,CAAC,MAAM,qBAAqB,CAAC,EAC5C,KAAK,CACN,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAE3B,KAAK,WAAW,CAAC,IAAI,SAAS,MAAM,IAChC,CAAC,IAAI,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAA;CAAE,CAAC,GACxD,CAAC,IAAI,GAAG;IAAE,OAAO,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC,CAAC;AAE7C,KAAK,SAAS,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,IAAI;IAEpD,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;AAwCtB,iBAAS,IAAI,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,EACjD,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,CAAC,CAAC,CAAC,kDAuBd;AAED,OAAO,EACL,IAAI,EACJ,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACd,CAAC"}