@mks2508/mks-ui 0.5.1 → 0.5.4

package/src/react-ui/ui/DataCard/index.tsx

@@ -1,17 +1,32 @@
 'use client';
 
+/**
+ * DataCard — glassmorphism dashboard metric card.
+ *
+ * Features: animated numbers, corner brackets, toggle, size/variant CVA,
+ * state-based styling, slot overrides, config for animation tuning.
+ *
+ * @module @mks2508/mks-ui/react/ui/DataCard
+ *
+ * @example
+ * ```tsx
+ * <DataCard variant="accent" size="default">
+ *   <DataCardLabel title="Revenue" description="This month" />
+ *   <DataCardValue number={45678} unit="$" />
+ * </DataCard>
+ * ```
+ */
+
 import * as React from 'react';
-import { motion, useMotionValue, useSpring } from 'motion/react';
+import { motion } from 'motion/react';
 import { cn } from '@/react-ui/lib/utils';
 import { getStrictContext } from '@/react-ui/lib/get-strict-context';
-import { useControlledState } from '@/react-ui/hooks/State/UseControlledState';
 
-// Import from existing components
 import { CornerBracket } from '@/react-ui/ui/CornerBracket';
 import { CountingNumber } from '@/react-ui/primitives/CountingNumber';
 import { Switch, SwitchThumb } from '@/react-ui/ui/Switch';
 
-import { dataCardVariants, dataCardStyles, bracketVariants, dataCardStateStyles } from './DataCard.styles';
+import { dataCardVariants, dataCardStyles, bracketVariants } from './DataCard.styles';
 import type { SlotOverrides } from '@/core/types';
 import type {
   IDataCardProps,
@@ -21,51 +36,35 @@ import type {
   IDataCardActionsProps,
   IDataCardBracketProps,
   IDataCardState,
+  IDataCardConfig,
   DataCardSlot,
 } from './DataCard.types';
 
-/**
- * Context type for DataCard state management.
- */
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
 type DataCardContextType = {
-  /** Current variant of: card. */
   variant: IDataCardProps['variant'];
-  /** Current size of: card. */
   size: IDataCardProps['size'];
-  /** Whether card is disabled. */
   disabled: boolean;
-  /** Whether glass effect is enabled. */
   glass: boolean;
-  /** Slot overrides from parent. */
+  config?: IDataCardConfig;
   slots?: SlotOverrides<DataCardSlot>;
-  /** Update interaction state. */
-  setState: React.Dispatch<React.SetStateAction<IDataCardState>>;
 };
 
 const [DataCardProvider, useDataCard] =
   getStrictContext<DataCardContextType>('DataCardContext');
 
+// ---------------------------------------------------------------------------
+// DataCard (Root)
+// ---------------------------------------------------------------------------
+
 /**
- * DataCard — comprehensive showcase component demonstrating mks-ui patterns.
- *
- * Features:
- * - Slot overrides for customization
- * - State-based styling (hover, pressed, disabled)
- * - CVA variants (size, color variant)
- * - asChild composition pattern
- * - Motion/animation integration
- * - Custom render functions
- * - Form field integration
- * - Icon composition
- * - Glassmorphism effects
+ * Root card container with glassmorphism, corner brackets, and state tracking.
  *
- * @example
- * ```tsx
- * <DataCard variant="accent" size="default">
- *   <DataCardValue number={1234} />
- *   <DataCardToggle />
- * </DataCard>
- * ```
+ * @param props - {@link IDataCardProps}
+ * @returns A motion.div card with context provider
  */
 function DataCard({
   variant = 'default',
@@ -78,32 +77,20 @@ function DataCard({
   slots,
   config,
   children,
-  ...props
 }: IDataCardProps) {
   const [state, setState] = React.useState<IDataCardState>({
     hovered: false,
     pressed: false,
-    disabled: disabled ?? false,
+    disabled,
   });
 
   const contextValue: DataCardContextType = React.useMemo(
-    () => ({ variant, size, disabled: disabled ?? false, glass, slots, setState }),
-    [variant, size, disabled, glass, slots]
+    () => ({ variant, size, disabled, glass, config, slots }),
+    [variant, size, disabled, glass, config, slots],
   );
 
-  const computedClassName = React.useMemo(() => {
-    if (typeof className === 'function') {
-      return className(state);
-    }
-    return className;
-  }, [className, state]);
-
-  const computedStyle = React.useMemo(() => {
-    if (typeof style === 'function') {
-      return style(state);
-    }
-    return style;
-  }, [style, state]);
+  const computedClassName = typeof className === 'function' ? className(state) : className;
+  const computedStyle = typeof style === 'function' ? style(state) : style;
 
   return (
     <DataCardProvider value={contextValue}>
@@ -115,38 +102,23 @@ function DataCard({
         aria-disabled={disabled || undefined}
         className={cn(
           dataCardVariants({ variant, size, glass }),
+          disabled && 'opacity-50 pointer-events-none',
           slots?.root,
           computedClassName,
-          state.hovered && dataCardStateStyles.hovered,
-          state.pressed && dataCardStateStyles.pressed,
-          disabled && dataCardStateStyles.disabled
         )}
         style={computedStyle}
-        onHoverStart={() => setState((prev) => ({ ...prev, hovered: true }))}
-        onHoverEnd={() => setState((prev) => ({ ...prev, hovered: false }))}
-        onTapStart={() => setState((prev) => ({ ...prev, pressed: true }))}
-        onTap={() => setState((prev) => ({ ...prev, pressed: false }))}
-        onTapCancel={() => setState((prev) => ({ ...prev, pressed: false }))}
-        {...props}
+        onHoverStart={() => setState((p) => ({ ...p, hovered: true }))}
+        onHoverEnd={() => setState((p) => ({ ...p, hovered: false }))}
+        onTapStart={() => setState((p) => ({ ...p, pressed: true }))}
+        onTap={() => setState((p) => ({ ...p, pressed: false }))}
+        onTapCancel={() => setState((p) => ({ ...p, pressed: false }))}
       >
         {showBrackets && (
           <>
-            <DataCardBracket
-              position="tl"
-              variant={variant === 'accent' ? 'accent' : 'default'}
-            />
-            <DataCardBracket
-              position="tr"
-              variant={variant === 'accent' ? 'accent' : 'default'}
-            />
-            <DataCardBracket
-              position="bl"
-              variant={variant === 'accent' ? 'accent' : 'default'}
-            />
-            <DataCardBracket
-              position="br"
-              variant={variant === 'accent' ? 'accent' : 'default'}
-            />
+            <DataCardBracket position="tl" variant={variant === 'accent' ? 'accent' : 'default'} />
+            <DataCardBracket position="tr" variant={variant === 'accent' ? 'accent' : 'default'} />
+            <DataCardBracket position="bl" variant={variant === 'accent' ? 'accent' : 'default'} />
+            <DataCardBracket position="br" variant={variant === 'accent' ? 'accent' : 'default'} />
           </>
         )}
         {children}
@@ -155,17 +127,15 @@ function DataCard({
   );
 }
 
+// ---------------------------------------------------------------------------
+// DataCardValue
+// ---------------------------------------------------------------------------
+
 /**
- * DataCardValue — displays animated number with CountingNumber.
+ * Animated number display with optional label and unit.
  *
- * @example
- * ```tsx
- * <DataCardValue
- *   number={1234}
- *   label="Active Users"
- *   unit="users"
- * />
- * ```
+ * @param props - {@link IDataCardValueProps}
+ * @returns Animated number with CountingNumber primitive
  */
 function DataCardValue({
   number,
@@ -174,10 +144,18 @@ function DataCardValue({
   decimalPlaces = 0,
   padStart = false,
 }: IDataCardValueProps) {
-  const { variant, size } = useDataCard();
+  const { size, config, slots } = useDataCard();
+
+  const stiffness = config?.counterStiffness ?? 90;
+  const damping = config?.counterDamping ?? 10;
+
+  const sizeClass =
+    size === 'compact' ? 'text-3xl font-bold'
+    : size === 'spacious' ? 'text-5xl font-bold'
+    : 'text-4xl font-bold';
 
   return (
-    <div data-slot="data-card-value" className={cn(dataCardStyles.value)}>
+    <div data-slot="data-card-value" className={cn(dataCardStyles.value, slots?.value)}>
       {label && (
         <span className="text-muted-foreground text-xs uppercase tracking-wider font-mono">
           {label}
@@ -187,17 +165,8 @@ function DataCardValue({
         number={number}
         decimalPlaces={decimalPlaces}
         padStart={padStart}
-        transition={{
-          stiffness: variant === 'accent' ? 150 : 90,
-          damping: variant === 'accent' ? 20 : 10,
-        }}
-        className={
-          size === 'compact'
-            ? 'text-3xl font-bold'
-            : size === 'spacious'
-              ? 'text-5xl font-bold'
-              : 'text-4xl font-bold'
-        }
+        transition={{ stiffness, damping }}
+        className={sizeClass}
       />
       {unit && (
         <span className="text-muted-foreground text-lg ml-1">{unit}</span>
@@ -206,16 +175,15 @@ function DataCardValue({
   );
 }
 
+// ---------------------------------------------------------------------------
+// DataCardLabel
+// ---------------------------------------------------------------------------
+
 /**
- * DataCardLabel — displays title and description.
+ * Title + description label.
  *
- * @example
- * ```tsx
- * <DataCardLabel
- *   title="Revenue"
- *   description="This month"
- * />
- * ```
+ * @param props - {@link IDataCardLabelProps}
+ * @returns Title and optional description text
  */
 function DataCardLabel({
   title,
@@ -228,47 +196,31 @@ function DataCardLabel({
   return (
     <div
       data-slot="data-card-label"
-      className={cn(
-        dataCardStyles.label,
-        slots?.label,
-        className
-      )}
+      className={cn(dataCardStyles.label, slots?.label, className)}
       {...props}
     >
-      {title && (
-        <h3 className="text-foreground font-semibold">{title}</h3>
-      )}
-      {description && (
-        <p className="text-muted-foreground text-sm">{description}</p>
-      )}
+      {title && <h3 className="text-foreground font-semibold">{title}</h3>}
+      {description && <p className="text-muted-foreground text-sm">{description}</p>}
     </div>
   );
 }
 
+// ---------------------------------------------------------------------------
+// DataCardToggle
+// ---------------------------------------------------------------------------
+
 /**
- * DataCardToggle — interactive switch element.
+ * Switch toggle control inside a DataCard.
  *
- * Uses asChild pattern for composition with Switch component.
- *
- * @example
- * ```tsx
- * <DataCardToggle
- *   checked={enabled}
- *   onCheckedChange={setEnabled}
- *   label="Enable notifications"
- *   checkedIcon={<BellIcon />}
- *   uncheckedIcon={<BellOffIcon />}
- * />
- * ```
+ * @param props - {@link IDataCardToggleProps}
+ * @returns Label + Switch toggle
  */
 function DataCardToggle({
   checked,
   onCheckedChange,
-  checkedIcon,
-  uncheckedIcon,
   label,
 }: IDataCardToggleProps) {
-  const { disabled, variant, size, glass, slots } = useDataCard();
+  const { disabled, slots } = useDataCard();
 
   return (
     <div data-slot="data-card-toggle" className={cn(dataCardStyles.toggle, slots?.toggle)}>
@@ -277,29 +229,23 @@ function DataCardToggle({
         checked={checked}
         onCheckedChange={onCheckedChange}
         disabled={disabled}
+        nativeButton
       >
         <SwitchThumb />
-        {checkedIcon && (
-          <div className="text-primary">{checkedIcon}</div>
-        )}
-        {!checkedIcon && (
-          <div className="text-muted-foreground">{uncheckedIcon}</div>
-        )}
       </Switch>
     </div>
   );
 }
 
+// ---------------------------------------------------------------------------
+// DataCardActions
+// ---------------------------------------------------------------------------
+
 /**
- * DataCardActions — container for action buttons.
+ * Action button container.
  *
- * @example
- * ```tsx
- * <DataCardActions align="end">
- *   <Button size="sm">Edit</Button>
- *   <Button size="sm" variant="ghost">Delete</Button>
- * </DataCardActions>
- * ```
+ * @param props - {@link IDataCardActionsProps}
+ * @returns Flex container for action buttons
  */
 function DataCardActions({
   align = 'end',
@@ -307,7 +253,7 @@ function DataCardActions({
   children,
   ...props
 }: IDataCardActionsProps) {
-  const { variant, size, glass, slots } = useDataCard();
+  const { slots } = useDataCard();
 
   return (
     <div
@@ -319,7 +265,7 @@ function DataCardActions({
         align === 'start' && 'justify-start',
         align === 'end' && 'justify-end',
         slots?.actions,
-        className
+        className,
       )}
       {...props}
     >
@@ -328,54 +274,43 @@ function DataCardActions({
   );
 }
 
+// ---------------------------------------------------------------------------
+// DataCardBracket
+// ---------------------------------------------------------------------------
+
 /**
- * DataCardBracket — decorative corner bracket.
+ * Decorative corner bracket. Rendered directly via CornerBracket
+ * (no wrapper div — the SVG positions itself via absolute positioning).
  *
- * Wraps CornerBracket with motion animations.
- *
- * @example
- * ```tsx
- * <DataCardBracket position="tl" variant="accent" />
- * ```
+ * @param props - {@link IDataCardBracketProps}
+ * @returns CornerBracket SVG at the specified corner
  */
 function DataCardBracket({
   position,
   variant = 'default',
-  className,
 }: IDataCardBracketProps) {
-  const { size, glass, slots } = useDataCard();
+  const { size, config } = useDataCard();
+  const animate = config?.animateBrackets ?? true;
 
-  const sizeMap = {
-    compact: 16,
-    default: 20,
-    spacious: 24,
-  } as const;
+  const sizeMap = { compact: 16, default: 20, spacious: 24 } as const;
 
   return (
-    <div className={cn(dataCardStyles.bracket, slots?.bracket, className)}>
-      <CornerBracket
-        position={position}
-        variant={variant}
-        size={sizeMap[size ?? 'default']}
-      />
-    </div>
+    <CornerBracket
+      position={position}
+      variant={variant}
+      size={sizeMap[size ?? 'default']}
+      className={cn(
+        animate && 'opacity-60 group-hover/data-card:opacity-100 transition-opacity',
+        !animate && 'opacity-50',
+      )}
+    />
   );
 }
 
-/**
- * Hook to access DataCard context.
- * Must be used within DataCard provider.
- *
- * @returns The current DataCard context
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { variant, size, disabled } = useDataCard();
- *   return <div>Current variant: {variant}</div>;
- * }
- * ```
- */
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
 export { useDataCard };
 
 export {
@@ -388,7 +323,6 @@ export {
   dataCardVariants,
 };
 
-// Re-export types
 export type {
   IDataCardProps,
   IDataCardValueProps,