@mks2508/mks-ui 0.2.0 → 0.3.1

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

@@ -1,422 +0,0 @@
-'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.types.ts

@@ -1,162 +0,0 @@
-/**
- * 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>;
-  };