@mks2508/mks-ui 0.1.4 → 0.2.0

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

@@ -0,0 +1,422 @@
+'use client';
+
+/**
+ * Animated Popover component built on Base UI Popover and Motion.
+ *
+ * Provides a positioned popover overlay with scale entrance animation,
+ * optional backdrop, arrow, and full AnimatePresence exit support.
+ * All sub-components accept a `slots` prop for class-name overrides
+ * following the StyleSlots pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui/Popover
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   Popover,
+ *   PopoverTrigger,
+ *   PopoverPortal,
+ *   PopoverPositioner,
+ *   PopoverPopup,
+ *   PopoverArrow,
+ *   PopoverTitle,
+ *   PopoverDescription,
+ *   PopoverClose,
+ * } from '@mks2508/mks-ui';
+ *
+ * function InfoPopover() {
+ *   return (
+ *     <Popover>
+ *       <PopoverTrigger>
+ *         <button>Info</button>
+ *       </PopoverTrigger>
+ *       <PopoverPortal>
+ *         <PopoverPositioner sideOffset={8}>
+ *           <PopoverPopup>
+ *             <PopoverArrow />
+ *             <PopoverTitle>Quick Info</PopoverTitle>
+ *             <PopoverDescription>Details about this feature.</PopoverDescription>
+ *             <PopoverClose><button>Got it</button></PopoverClose>
+ *           </PopoverPopup>
+ *         </PopoverPositioner>
+ *       </PopoverPortal>
+ *     </Popover>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Popover as PopoverPrimitive } from '@base-ui/react/popover';
+import { AnimatePresence, motion } 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 { popoverStyles } from './Popover.styles';
+import type {
+  PopoverContextType,
+  IPopoverProps,
+  IPopoverTriggerProps,
+  IPopoverPortalProps,
+  IPopoverPositionerProps,
+  IPopoverPopupProps,
+  IPopoverBackdropProps,
+  IPopoverArrowProps,
+  IPopoverTitleProps,
+  IPopoverDescriptionProps,
+  IPopoverCloseProps,
+} from './Popover.types';
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const [PopoverProvider, usePopover] =
+  getStrictContext<PopoverContextType>('PopoverContext');
+
+/* -------------------------------------------------------------------------- */
+/*  Popover (Root)                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Root Popover component.
+ * Manages controlled/uncontrolled open state and provides context to children.
+ *
+ * @param props - Popover root props including `open`, `defaultOpen`, and `onOpenChange`
+ *
+ * @example
+ * ```tsx
+ * <Popover open={isOpen} onOpenChange={setIsOpen}>
+ *   {children}
+ * </Popover>
+ * ```
+ */
+function Popover(props: IPopoverProps) {
+  const { slots, config: _config, ...rest } = props;
+
+  const [isOpen, setIsOpen] = useControlledState({
+    value: rest?.open,
+    defaultValue: rest?.defaultOpen,
+    onChange: rest?.onOpenChange,
+  });
+
+  return (
+    <PopoverProvider value={{ isOpen, setIsOpen }}>
+      <PopoverPrimitive.Root
+        data-slot="popover"
+        {...rest}
+        onOpenChange={setIsOpen}
+      />
+    </PopoverProvider>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverTrigger                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Trigger element that toggles the popover on interaction.
+ *
+ * @param props - Trigger props forwarded to Base UI Popover.Trigger
+ *
+ * @example
+ * ```tsx
+ * <PopoverTrigger>
+ *   <button>Show info</button>
+ * </PopoverTrigger>
+ * ```
+ */
+function PopoverTrigger({
+  slots,
+  className,
+  ...props
+}: IPopoverTriggerProps) {
+  return (
+    <PopoverPrimitive.Trigger
+      data-slot="popover-trigger"
+      className={cn(popoverStyles.trigger, slots?.trigger, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverPortal                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * 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
+ * <PopoverPortal>
+ *   <PopoverPositioner>
+ *     <PopoverPopup>...</PopoverPopup>
+ *   </PopoverPositioner>
+ * </PopoverPortal>
+ * ```
+ */
+function PopoverPortal({ slots: _slots, ...props }: IPopoverPortalProps) {
+  const { isOpen } = usePopover();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <PopoverPrimitive.Portal
+          keepMounted
+          data-slot="popover-portal"
+          {...props}
+        />
+      )}
+    </AnimatePresence>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverPositioner                                                         */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Positioning wrapper that automatically places the popup relative to the trigger.
+ *
+ * @param props - Positioner props forwarded to Base UI Popover.Positioner
+ *
+ * @example
+ * ```tsx
+ * <PopoverPositioner sideOffset={8} align="start">
+ *   <PopoverPopup>Content</PopoverPopup>
+ * </PopoverPositioner>
+ * ```
+ */
+function PopoverPositioner({
+  slots,
+  className,
+  ...props
+}: IPopoverPositionerProps) {
+  return (
+    <PopoverPrimitive.Positioner
+      data-slot="popover-positioner"
+      className={cn(popoverStyles.positioner, slots?.positioner, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverPopup                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Main popover content container with scale entrance animation.
+ * Uses Motion for spring-based scale + opacity transitions.
+ *
+ * @param props - Popup props including motion transition overrides
+ *
+ * @example
+ * ```tsx
+ * <PopoverPopup slots={{ popup: 'rounded-xl shadow-xl' }}>
+ *   <p>Popover content</p>
+ * </PopoverPopup>
+ * ```
+ */
+function PopoverPopup({
+  initialFocus,
+  finalFocus,
+  slots,
+  className,
+  transition = { type: 'spring', stiffness: 300, damping: 25 },
+  ...props
+}: IPopoverPopupProps) {
+  return (
+    <PopoverPrimitive.Popup
+      initialFocus={initialFocus}
+      finalFocus={finalFocus}
+      render={
+        <motion.div
+          key="popover-popup"
+          data-slot="popover-popup"
+          className={cn(popoverStyles.popup, slots?.popup, className)}
+          initial={{ opacity: 0, scale: 0.5 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.5 }}
+          transition={transition}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverBackdrop                                                           */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Optional overlay backdrop behind the popover.
+ *
+ * @param props - Backdrop props forwarded to Base UI Popover.Backdrop
+ *
+ * @example
+ * ```tsx
+ * <PopoverBackdrop slots={{ backdrop: 'bg-black/20' }} />
+ * ```
+ */
+function PopoverBackdrop({
+  slots,
+  className,
+  ...props
+}: IPopoverBackdropProps) {
+  return (
+    <PopoverPrimitive.Backdrop
+      data-slot="popover-backdrop"
+      className={cn(popoverStyles.backdrop, slots?.backdrop, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverArrow                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Directional arrow pointing toward the trigger element.
+ *
+ * @param props - Arrow props forwarded to Base UI Popover.Arrow
+ *
+ * @example
+ * ```tsx
+ * <PopoverArrow slots={{ arrow: 'fill-popover' }} />
+ * ```
+ */
+function PopoverArrow({ slots, className, ...props }: IPopoverArrowProps) {
+  return (
+    <PopoverPrimitive.Arrow
+      data-slot="popover-arrow"
+      className={cn(popoverStyles.arrow, slots?.arrow, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverTitle                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Accessible title for the popover.
+ *
+ * @param props - Title props forwarded to Base UI Popover.Title
+ *
+ * @example
+ * ```tsx
+ * <PopoverTitle>Quick Info</PopoverTitle>
+ * ```
+ */
+function PopoverTitle({ slots, className, ...props }: IPopoverTitleProps) {
+  return (
+    <PopoverPrimitive.Title
+      data-slot="popover-title"
+      className={cn(popoverStyles.title, slots?.title, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverDescription                                                        */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Accessible description for the popover.
+ *
+ * @param props - Description props forwarded to Base UI Popover.Description
+ *
+ * @example
+ * ```tsx
+ * <PopoverDescription>Additional details about this item.</PopoverDescription>
+ * ```
+ */
+function PopoverDescription({
+  slots,
+  className,
+  ...props
+}: IPopoverDescriptionProps) {
+  return (
+    <PopoverPrimitive.Description
+      data-slot="popover-description"
+      className={cn(popoverStyles.description, slots?.description, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  PopoverClose                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Button that closes the popover when clicked.
+ *
+ * @param props - Close props forwarded to Base UI Popover.Close
+ *
+ * @example
+ * ```tsx
+ * <PopoverClose>
+ *   <button>Dismiss</button>
+ * </PopoverClose>
+ * ```
+ */
+function PopoverClose({ slots, className, ...props }: IPopoverCloseProps) {
+  return (
+    <PopoverPrimitive.Close
+      data-slot="popover-close"
+      className={cn(popoverStyles.close, slots?.close, className)}
+      {...props}
+    />
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Exports                                                                   */
+/* -------------------------------------------------------------------------- */
+
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverPortal,
+  PopoverPositioner,
+  PopoverPopup,
+  PopoverBackdrop,
+  PopoverArrow,
+  PopoverTitle,
+  PopoverDescription,
+  PopoverClose,
+  usePopover,
+};
+
+// Re-exports from types
+export type {
+  IPopoverProps,
+  IPopoverTriggerProps,
+  IPopoverPortalProps,
+  IPopoverPositionerProps,
+  IPopoverPopupProps,
+  IPopoverBackdropProps,
+  IPopoverArrowProps,
+  IPopoverTitleProps,
+  IPopoverDescriptionProps,
+  IPopoverCloseProps,
+  PopoverContextType,
+  PopoverSlot,
+  IPopoverConfig,
+} from './Popover.types';
+
+// Re-exports from styles
+export { popoverStyles } from './Popover.styles';

package/src/react/ui/Progress/Progress.styles.ts

@@ -0,0 +1,36 @@
+/**
+ * Style slots and CVA variants for the Progress component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Progress/Progress.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+
+import type { ProgressSlot } from './Progress.types';
+
+/**
+ * Default style slots for the Progress component.
+ * Each key maps to a visual region with its base Tailwind classes.
+ *
+ * - `root` - The outer container with flex column layout
+ * - `track` - The background track with rounded shape and overflow hidden
+ * - `indicator` - The filled bar that animates to current percentage
+ * - `label` - Optional descriptive label text
+ * - `value` - Optional animated numeric value
+ *
+ * @example
+ * ```typescript
+ * import { progressStyles } from './Progress.styles';
+ *
+ * // Access the track slot classes
+ * const trackClasses = progressStyles.track;
+ * // 'relative h-2 w-full overflow-hidden rounded-full bg-secondary'
+ * ```
+ */
+export const progressStyles: StyleSlots<ProgressSlot> = {
+  root: 'flex flex-col gap-2',
+  track: 'relative h-2 w-full overflow-hidden rounded-full bg-secondary',
+  indicator: 'h-full bg-primary rounded-full',
+  label: 'text-sm font-medium leading-none',
+  value: 'text-sm tabular-nums text-muted-foreground',
+};

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

@@ -0,0 +1,162 @@
+/**
+ * Type definitions for the Progress component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Progress/Progress.types
+ */
+
+import type { Progress as ProgressPrimitives } from '@base-ui/react/progress';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+import type { ICountingNumberProps } from '@/react/primitives/CountingNumber';
+
+/**
+ * Available style slot names for the Progress component.
+ * Each slot maps to a visual region that can be customized via the `slots` prop.
+ *
+ * - `root` - The outer progress container
+ * - `track` - The background track bar
+ * - `indicator` - The filled indicator bar that animates to the current value
+ * - `label` - Optional label text (e.g., "Uploading...")
+ * - `value` - Optional animated numeric value display
+ *
+ * @example
+ * ```tsx
+ * <Progress
+ *   value={75}
+ *   slots={{
+ *     root: 'w-full',
+ *     track: 'h-3 bg-zinc-800 rounded-full',
+ *     indicator: 'bg-cyan-500 rounded-full',
+ *     label: 'text-sm text-zinc-400',
+ *     value: 'text-sm font-mono',
+ *   }}
+ * />
+ * ```
+ */
+export type ProgressSlot = 'root' | 'track' | 'indicator' | 'label' | 'value';
+
+/**
+ * Internal context type for Progress state management.
+ * Shared between the Progress root and its child components via React context.
+ */
+export type ProgressContextType = {
+  /** Current progress value (0-100). */
+  value: number;
+};
+
+/**
+ * Configuration options for Progress behavior and animation.
+ * Extends the base config with progress-specific settings.
+ *
+ * @example
+ * ```tsx
+ * <Progress
+ *   value={75}
+ *   config={{ animation: { duration: 0.5 }, springStiffness: 120 }}
+ * />
+ * ```
+ */
+export interface IProgressConfig extends IBaseConfig {
+  /**
+   * Spring stiffness for the indicator animation.
+   * @defaultValue 100
+   */
+  springStiffness?: number;
+  /**
+   * Spring damping for the indicator animation.
+   * @defaultValue 30
+   */
+  springDamping?: number;
+}
+
+/**
+ * Props for the Progress root component.
+ * Wraps Base UI Progress.Root with context provider, slot overrides, and configuration.
+ *
+ * @example
+ * ```tsx
+ * <Progress value={75} slots={{ root: 'flex flex-col gap-2' }}>
+ *   <ProgressLabel>Uploading...</ProgressLabel>
+ *   <ProgressTrack>
+ *     <ProgressIndicator />
+ *   </ProgressTrack>
+ *   <ProgressValue />
+ * </Progress>
+ * ```
+ */
+export type IProgressProps = React.ComponentProps<typeof ProgressPrimitives.Root> & {
+  /** Partial class overrides for each visual slot. */
+  slots?: SlotOverrides<ProgressSlot>;
+  /** Behavioral and animation configuration. */
+  config?: IProgressConfig;
+};
+
+/**
+ * Props for the ProgressIndicator sub-component.
+ * Uses `motion.create` for spring-animated width transitions.
+ *
+ * @example
+ * ```tsx
+ * <ProgressIndicator className="h-full rounded-full" />
+ * ```
+ */
+export type IProgressIndicatorProps = React.ComponentProps<typeof ProgressPrimitives.Indicator> &
+  React.ComponentProps<'div'> & {
+    /** Spring transition config for the indicator animation. */
+    transition?: {
+      type?: 'spring' | 'tween' | 'keyframes' | 'decay' | 'inertia';
+      stiffness?: number;
+      damping?: number;
+      [key: string]: unknown;
+    };
+    /** Partial class overrides for each visual slot. */
+    slots?: SlotOverrides<ProgressSlot>;
+  };
+
+/**
+ * Props for the ProgressTrack sub-component.
+ * Wraps Base UI Progress.Track with slot overrides.
+ *
+ * @example
+ * ```tsx
+ * <ProgressTrack className="h-2 rounded-full overflow-hidden">
+ *   <ProgressIndicator />
+ * </ProgressTrack>
+ * ```
+ */
+export type IProgressTrackProps = React.ComponentProps<typeof ProgressPrimitives.Track> & {
+  /** Partial class overrides for each visual slot. */
+  slots?: SlotOverrides<ProgressSlot>;
+};
+
+/**
+ * Props for the ProgressLabel sub-component.
+ * Wraps Base UI Progress.Label with slot overrides.
+ *
+ * @example
+ * ```tsx
+ * <ProgressLabel>Uploading files...</ProgressLabel>
+ * ```
+ */
+export type IProgressLabelProps = React.ComponentProps<typeof ProgressPrimitives.Label> & {
+  /** Partial class overrides for each visual slot. */
+  slots?: SlotOverrides<ProgressSlot>;
+};
+
+/**
+ * Props for the ProgressValue sub-component.
+ * Combines Base UI Progress.Value with CountingNumber for animated numeric display.
+ *
+ * @example
+ * ```tsx
+ * <ProgressValue transition={{ stiffness: 80, damping: 20 }} />
+ * ```
+ */
+export type IProgressValueProps = Omit<
+  React.ComponentProps<typeof ProgressPrimitives.Value>,
+  'render'
+> &
+  Omit<ICountingNumberProps, 'number'> & {
+    /** Partial class overrides for each visual slot. */
+    slots?: SlotOverrides<ProgressSlot>;
+  };