@mks2508/mks-ui 0.2.1 → 0.3.2

package/src/react-ui/ui/DataCard/DataCard.styles.ts

@@ -0,0 +1,150 @@
+import { cva } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/**
+ * Visual regions for: DataCard component family.
+ * Each slot maps to: customizable visual region.
+ */
+export type DataCardSlot =
+  | 'root'           // Main card container
+  | 'bracket'         // Corner bracket decoration
+  | 'header'          // Top section with title/description
+  | 'value'           // Animated number display
+  | 'label'           // Text labels
+  | 'toggle'           // Switch/checkbox control
+  | 'actions'         // Action buttons container
+  | 'footer';         // Bottom section
+
+/**
+ * Base style slots for: DataCard.
+ * Uses glassmorphism pattern from: Synthwave Dark design system.
+ */
+export const dataCardStyles: StyleSlots<DataCardSlot> = {
+  root: 'group/data-card relative isolate rounded-xl transition-all duration-300',
+
+  bracket: 'absolute pointer-events-none transition-opacity duration-300',
+
+  header: 'flex flex-col gap-1.5 px-5 pt-5 pb-2',
+
+  value: 'flex items-baseline gap-1 tabular-nums tracking-tight',
+
+  label: 'text-sm font-medium',
+
+  toggle: 'flex items-center justify-between gap-3',
+
+  actions: 'flex items-center gap-2',
+
+  footer: 'mt-auto px-5 pb-4 pt-2',
+};
+
+/**
+ * CVA variants for: DataCard root.
+ * Combines glassmorphism with Synthwave Dark color scheme.
+ */
+export const dataCardVariants = cva(dataCardStyles.root, {
+  variants: {
+    // Size variants - control padding and spacing
+    size: {
+      compact: {
+        root: 'p-3',
+        header: 'gap-1 px-3 pt-3 pb-1.5',
+        footer: 'px-3 pb-1.5 pt-1',
+      },
+      default: {
+        root: 'p-4',
+        header: 'gap-1.5 px-4 pt-4 pb-2',
+        footer: 'px-4 pb-2 pt-2',
+      },
+      spacious: {
+        root: 'p-6',
+        header: 'gap-2 px-6 pt-6 pb-3',
+        footer: 'px-6 pb-3 pt-2',
+      },
+    },
+
+    // Visual variants - control colors and borders
+    variant: {
+      default: [
+        'bg-white/5',
+        'backdrop-blur-lg',
+        'border border-white/10',
+        'hover:bg-white/10',
+        'shadow-lg shadow-black/20',
+      ].join(' '),
+
+      accent: [
+        'bg-cyan-500/10',
+        'backdrop-blur-lg',
+        'border border-cyan-400/30',
+        'hover:bg-cyan-500/20',
+        'shadow-cyan-500/20 shadow-lg',
+      ].join(' '),
+
+      success: [
+        'bg-emerald-500/10',
+        'backdrop-blur-lg',
+        'border border-emerald-400/30',
+        'hover:bg-emerald-500/20',
+        'shadow-emerald-500/20 shadow-lg',
+      ].join(' '),
+
+      warning: [
+        'bg-amber-500/10',
+        'backdrop-blur-lg',
+        'border border-amber-400/30',
+        'hover:bg-amber-500/20',
+        'shadow-amber-500/20 shadow-lg',
+      ].join(' '),
+
+      destructive: [
+        'bg-red-500/10',
+        'backdrop-blur-lg',
+        'border border-red-400/30',
+        'hover:bg-red-500/20',
+        'shadow-red-500/20 shadow-lg',
+      ].join(' '),
+    },
+
+    // Glass effect toggle
+    glass: {
+      true: [
+        'backdrop-blur-lg',
+        'bg-white/10',
+        'border border-white/20',
+        'shadow-xl',
+      ].join(' '),
+      false: '',
+    },
+  },
+
+  defaultVariants: {
+    variant: 'default',
+    size: 'default',
+    glass: true,
+  },
+});
+
+/**
+ * CVA variants for bracket visibility animation.
+ */
+export const bracketVariants = cva(dataCardStyles.bracket, {
+  variants: {
+    animate: {
+      true: 'opacity-60 group-hover/data-card:opacity-100 transition-opacity',
+      false: 'opacity-50',
+    },
+  },
+  defaultVariants: {
+    animate: true,
+  },
+});
+
+/**
+ * State-specific styles for DataCard interactions.
+ */
+export const dataCardStateStyles = {
+  hovered: 'scale-[1.02]',
+  pressed: 'scale-[0.98]',
+  disabled: 'opacity-50 pointer-events-none',
+};
+

package/src/react-ui/ui/DataCard/DataCard.types.ts

@@ -0,0 +1,146 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { SlotOverrides } from '@/core/types';
+import type { dataCardVariants, DataCardSlot } from './DataCard.styles';
+export type { DataCardSlot } from './DataCard.styles';
+
+/**
+ * Available visual variants for DataCard.
+ * - 'default' - Standard glassmorphism with neutral borders
+ * - 'accent' - Cyan accent with primary glow
+ * - 'success' - Green accent for positive data
+ * - 'warning' - Amber accent for warnings
+ * - 'destructive' - Red accent for critical data
+ */
+export type DataCardVariant = 'default' | 'accent' | 'success' | 'warning' | 'destructive';
+
+/**
+ * Size variants affecting padding and spacing.
+ * - 'compact' - Dense layout for dashboards
+ * - 'default' - Standard balanced spacing
+ * - 'spacious' - More breathing room
+ */
+export type DataCardSize = 'compact' | 'default' | 'spacious';
+
+/**
+ * Interaction state for state-based styling.
+ * Similar to Button's IButtonState pattern.
+ */
+export interface IDataCardState {
+  /** Whether card content is hovered. */
+  hovered: boolean;
+  /** Whether card is pressed/active. */
+  pressed: boolean;
+  /** Whether card is disabled. */
+  disabled: boolean;
+}
+
+/**
+ * Configuration for DataCard behavior and animation.
+ * Extends IBaseConfig with card-specific settings.
+ */
+export interface IDataCardConfig {
+  /** Enable/disable corner bracket animations. */
+  animateBrackets?: boolean;
+  /** Spring stiffness for number counter. */
+  counterStiffness?: number;
+  /** Spring damping for number counter. */
+  counterDamping?: number;
+}
+
+/**
+ * Props for DataCard root component.
+ *
+ * @example
+ * ```tsx
+ * <DataCard variant="accent" size="default">
+ *   <DataCardValue number={1234} />
+ *   <DataCardToggle />
+ * </DataCard>
+ * ```
+ */
+export interface IDataCardProps
+  extends VariantProps<typeof dataCardVariants> {
+  /** Visual style variant. */
+  variant?: DataCardVariant;
+  /** Size variant affecting spacing. */
+  size?: DataCardSize;
+  /** Whether card is disabled. */
+  disabled?: boolean;
+  /** Override classes for card visual regions. */
+  slots?: SlotOverrides<DataCardSlot>;
+  /** Behavioral and animation configuration. */
+  config?: IDataCardConfig;
+  /** CSS class or function returning class based on card state. */
+  className?: string | ((state: IDataCardState) => string | undefined);
+  /** CSS styles or function returning styles based on card state. */
+  style?: React.CSSProperties | ((state: IDataCardState) => React.CSSProperties | undefined);
+  /** Enable glassmorphism effect (default: true). */
+  glass?: boolean;
+  /** Show corner brackets (default: true). */
+  showBrackets?: boolean;
+  /** Child elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * Props for DataCardValue - displays animated number.
+ */
+export interface IDataCardValueProps {
+  /** Target number to animate to. */
+  number: number;
+  /** Label displayed above: number. */
+  label?: string;
+  /** Unit/suffix displayed after: number. */
+  unit?: string;
+  /** Decimal places for precision. */
+  decimalPlaces?: number;
+  /** Pad number with leading zeros. */
+  padStart?: boolean;
+}
+
+/**
+ * Props for DataCardLabel - title/description text.
+ */
+export interface IDataCardLabelProps extends React.ComponentProps<'div'> {
+  /** Primary title text. */
+  title?: string;
+  /** Secondary description text. */
+  description?: string;
+}
+
+/**
+ * Props for DataCardToggle - interactive switch element.
+ */
+export interface IDataCardToggleProps {
+  /** Whether toggle is checked. */
+  checked?: boolean;
+  /** Callback when toggle state changes. */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Icon to show when checked (on). */
+  checkedIcon?: React.ReactNode;
+  /** Icon to show when unchecked (off). */
+  uncheckedIcon?: React.ReactNode;
+  /** Label for: toggle. */
+  label?: string;
+  /** Override classes for toggle regions. */
+  slots?: SlotOverrides<DataCardSlot>;
+}
+
+/**
+ * Props for DataCardActions - action button container.
+ */
+export interface IDataCardActionsProps extends React.ComponentProps<'div'> {
+  /** Alignment of action buttons. */
+  align?: 'start' | 'center' | 'end';
+}
+
+/**
+ * Props for DataCardBracket - decorative corner element.
+ */
+export interface IDataCardBracketProps extends React.ComponentProps<'div'> {
+  /** Position of: bracket. */
+  position: 'tl' | 'tr' | 'bl' | 'br';
+  /** Optional variant override for: this bracket. */
+  variant?: 'default' | 'accent';
+}
+

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

@@ -0,0 +1,406 @@
+'use client';
+
+import * as React from 'react';
+import { motion, useMotionValue, useSpring } 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 type { SlotOverrides } from '@/core/types';
+import type {
+  IDataCardProps,
+  IDataCardValueProps,
+  IDataCardLabelProps,
+  IDataCardToggleProps,
+  IDataCardActionsProps,
+  IDataCardBracketProps,
+  IDataCardState,
+  DataCardSlot,
+} from './DataCard.types';
+
+/**
+ * Context type for DataCard state management.
+ */
+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. */
+  slots?: SlotOverrides<DataCardSlot>;
+  /** Update interaction state. */
+  setState: React.Dispatch<React.SetStateAction<IDataCardState>>;
+};
+
+const [DataCardProvider, useDataCard] =
+  getStrictContext<DataCardContextType>('DataCardContext');
+
+/**
+ * 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
+ *
+ * @example
+ * ```tsx
+ * <DataCard variant="accent" size="default">
+ *   <DataCardValue number={1234} />
+ *   <DataCardToggle />
+ * </DataCard>
+ * ```
+ */
+function DataCard({
+  variant = 'default',
+  size = 'default',
+  disabled = false,
+  glass = true,
+  showBrackets = true,
+  className,
+  style,
+  slots,
+  config,
+  children,
+  ...props
+}: IDataCardProps) {
+  const [state, setState] = React.useState<IDataCardState>({
+    hovered: false,
+    pressed: false,
+    disabled: disabled ?? false,
+  });
+
+  const contextValue: DataCardContextType = React.useMemo(
+    () => ({ variant, size, disabled: disabled ?? false, glass, slots, setState }),
+    [variant, size, disabled, glass, 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]);
+
+  return (
+    <DataCardProvider value={contextValue}>
+      <motion.div
+        data-slot="data-card"
+        data-variant={variant}
+        data-size={size}
+        data-disabled={disabled || undefined}
+        aria-disabled={disabled || undefined}
+        className={cn(
+          dataCardVariants({ variant, size, glass }),
+          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}
+      >
+        {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'}
+            />
+          </>
+        )}
+        {children}
+      </motion.div>
+    </DataCardProvider>
+  );
+}
+
+/**
+ * DataCardValue — displays animated number with CountingNumber.
+ *
+ * @example
+ * ```tsx
+ * <DataCardValue
+ *   number={1234}
+ *   label="Active Users"
+ *   unit="users"
+ * />
+ * ```
+ */
+function DataCardValue({
+  number,
+  label,
+  unit,
+  decimalPlaces = 0,
+  padStart = false,
+}: IDataCardValueProps) {
+  const { variant, size } = useDataCard();
+
+  return (
+    <div data-slot="data-card-value" className={cn(dataCardStyles.value)}>
+      {label && (
+        <span className="text-muted-foreground text-xs uppercase tracking-wider font-mono">
+          {label}
+        </span>
+      )}
+      <CountingNumber
+        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'
+        }
+      />
+      {unit && (
+        <span className="text-muted-foreground text-lg ml-1">{unit}</span>
+      )}
+    </div>
+  );
+}
+
+/**
+ * DataCardLabel — displays title and description.
+ *
+ * @example
+ * ```tsx
+ * <DataCardLabel
+ *   title="Revenue"
+ *   description="This month"
+ * />
+ * ```
+ */
+function DataCardLabel({
+  title,
+  description,
+  className,
+  ...props
+}: IDataCardLabelProps) {
+  const { slots } = useDataCard();
+
+  return (
+    <div
+      data-slot="data-card-label"
+      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>
+      )}
+    </div>
+  );
+}
+
+/**
+ * DataCardToggle — interactive switch element.
+ *
+ * Uses asChild pattern for composition with Switch component.
+ *
+ * @example
+ * ```tsx
+ * <DataCardToggle
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ *   label="Enable notifications"
+ *   checkedIcon={<BellIcon />}
+ *   uncheckedIcon={<BellOffIcon />}
+ * />
+ * ```
+ */
+function DataCardToggle({
+  checked,
+  onCheckedChange,
+  checkedIcon,
+  uncheckedIcon,
+  label,
+}: IDataCardToggleProps) {
+  const { disabled, variant, size, glass, slots } = useDataCard();
+
+  return (
+    <div data-slot="data-card-toggle" className={cn(dataCardStyles.toggle, slots?.toggle)}>
+      {label && <span className="text-sm text-muted-foreground">{label}</span>}
+      <Switch
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        disabled={disabled}
+      >
+        <SwitchThumb />
+        {checkedIcon && (
+          <div className="text-primary">{checkedIcon}</div>
+        )}
+        {!checkedIcon && (
+          <div className="text-muted-foreground">{uncheckedIcon}</div>
+        )}
+      </Switch>
+    </div>
+  );
+}
+
+/**
+ * DataCardActions — container for action buttons.
+ *
+ * @example
+ * ```tsx
+ * <DataCardActions align="end">
+ *   <Button size="sm">Edit</Button>
+ *   <Button size="sm" variant="ghost">Delete</Button>
+ * </DataCardActions>
+ * ```
+ */
+function DataCardActions({
+  align = 'end',
+  className,
+  children,
+  ...props
+}: IDataCardActionsProps) {
+  const { variant, size, glass, slots } = useDataCard();
+
+  return (
+    <div
+      data-slot="data-card-actions"
+      data-align={align}
+      className={cn(
+        dataCardStyles.actions,
+        align === 'center' && 'justify-center',
+        align === 'start' && 'justify-start',
+        align === 'end' && 'justify-end',
+        slots?.actions,
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * DataCardBracket — decorative corner bracket.
+ *
+ * Wraps CornerBracket with motion animations.
+ *
+ * @example
+ * ```tsx
+ * <DataCardBracket position="tl" variant="accent" />
+ * ```
+ */
+function DataCardBracket({
+  position,
+  variant = 'default',
+  className,
+}: IDataCardBracketProps) {
+  const { size, glass, slots } = useDataCard();
+
+  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>
+  );
+}
+
+/**
+ * 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>;
+ * }
+ * ```
+ */
+export { useDataCard };
+
+export {
+  DataCard,
+  DataCardValue,
+  DataCardLabel,
+  DataCardToggle,
+  DataCardActions,
+  DataCardBracket,
+  dataCardVariants,
+};
+
+// Re-export types
+export type {
+  IDataCardProps,
+  IDataCardValueProps,
+  IDataCardLabelProps,
+  IDataCardToggleProps,
+  IDataCardActionsProps,
+  IDataCardBracketProps,
+  IDataCardState,
+  IDataCardConfig,
+  DataCardVariant,
+  DataCardSize,
+  DataCardSlot,
+} from './DataCard.types';
+
+export { dataCardStyles } from './DataCard.styles';