@mks2508/mks-ui 0.2.0 → 0.3.1

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

@@ -0,0 +1,155 @@
+'use client';
+
+import * as React from 'react';
+import { Button as ButtonPrimitive } from '@base-ui/react/button';
+
+import { cn } from '@/react-ui/lib/utils';
+import { buttonVariants, buttonStateStyles } from './Button.styles';
+import type { IButtonProps, IButtonState } from './Button.types';
+
+/**
+ * Slot component for the asChild pattern.
+ * Composes the button with another element passing all props and handlers.
+ */
+function Slot({
+  children,
+  ...props
+}: React.HTMLAttributes<HTMLElement> & { children: React.ReactElement }) {
+  const child = React.Children.only(children) as React.ReactElement<{
+    className?: string;
+    style?: React.CSSProperties;
+  }>;
+  return React.cloneElement(child, {
+    ...props,
+    ...child.props,
+    className: cn(props.className, child.props.className),
+    style: { ...props.style, ...child.props.style },
+  });
+}
+
+/**
+ * Button — interactive button built on Base UI with variants and state tracking.
+ *
+ * @param variant - Visual style: default, secondary, destructive, outline, ghost, link, success, warning
+ * @param size - Button size: default, sm, lg, icon
+ * @param asChild - Render as child element using Slot pattern
+ * @param focusableWhenDisabled - Keep button focusable when disabled
+ *
+ * @example
+ * ```tsx
+ * <Button variant="default" size="lg">Click me</Button>
+ * <Button variant="destructive">Delete</Button>
+ * <Button asChild><a href="/link">Link Button</a></Button>
+ * ```
+ */
+function Button({
+  className,
+  variant,
+  size,
+  focusableWhenDisabled,
+  nativeButton,
+  asChild = false,
+  render,
+  style,
+  children,
+  disabled,
+  slots,
+  onPointerDown,
+  onPointerUp,
+  onPointerLeave,
+  ...props
+}: IButtonProps) {
+  const [pressed, setPressed] = React.useState(false);
+
+  const handlePointerDown = React.useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      setPressed(true);
+      onPointerDown?.(e);
+    },
+    [onPointerDown],
+  );
+
+  const handlePointerUp = React.useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      setPressed(false);
+      onPointerUp?.(e);
+    },
+    [onPointerUp],
+  );
+
+  const handlePointerLeave = React.useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      setPressed(false);
+      onPointerLeave?.(e);
+    },
+    [onPointerLeave],
+  );
+
+  const state: IButtonState = {
+    disabled: disabled ?? false,
+    pressed,
+  };
+
+  const baseClassName = cn(
+    buttonVariants({ variant, size }),
+    slots?.root,
+    typeof className === 'function' ? className(state) : className,
+    pressed && buttonStateStyles.pressed,
+  );
+
+  const baseStyle =
+    typeof style === 'function' ? style(state) : style;
+
+  if (asChild && React.isValidElement(children)) {
+    return (
+      <ButtonPrimitive
+        data-slot="button"
+        data-variant={variant}
+        data-size={size}
+        data-pressed={pressed}
+        disabled={disabled}
+        focusableWhenDisabled={focusableWhenDisabled}
+        className={baseClassName}
+        style={baseStyle}
+        onPointerDown={handlePointerDown}
+        onPointerUp={handlePointerUp}
+        onPointerLeave={handlePointerLeave}
+        {...props}
+      >
+        <Slot className={baseClassName} style={baseStyle}>
+          {children}
+        </Slot>
+      </ButtonPrimitive>
+    );
+  }
+
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      data-variant={variant}
+      data-size={size}
+      data-pressed={pressed}
+      disabled={disabled}
+      focusableWhenDisabled={focusableWhenDisabled}
+      nativeButton={nativeButton}
+      render={render as any}
+      className={baseClassName}
+      style={baseStyle}
+      onPointerDown={handlePointerDown}
+      onPointerUp={handlePointerUp}
+      onPointerLeave={handlePointerLeave}
+      {...props}
+    >
+      {children}
+    </ButtonPrimitive>
+  );
+}
+
+export { Button, buttonVariants, buttonStateStyles };
+export type {
+  IButtonProps,
+  IButtonState,
+  ButtonVariant,
+  ButtonSize,
+} from './Button.types';
+export type { ButtonSlot } from './Button.styles';

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

@@ -0,0 +1,130 @@
+import * as React from 'react';
+
+import { cn } from '@/react-ui/lib/utils';
+import { cardStyles, cardVariants } from './Card.styles';
+import type {
+  ICardProps,
+  ICardHeaderProps,
+  ICardTitleProps,
+  ICardDescriptionProps,
+  ICardActionProps,
+  ICardContentProps,
+  ICardFooterProps,
+} from './Card.types';
+
+/**
+ * Card — container with variants for default, glass, and glass-accent styles.
+ *
+ * @param variant - Visual style: 'default', 'glass', or 'glass-accent'
+ * @param slots - Override classes for card visual regions
+ *
+ * @example
+ * ```tsx
+ * <Card variant="glass">
+ *   <CardHeader>
+ *     <CardTitle>Title</CardTitle>
+ *     <CardDescription>Description</CardDescription>
+ *   </CardHeader>
+ *   <CardContent>Content</CardContent>
+ * </Card>
+ * ```
+ */
+function Card({ className, variant, slots, ...props }: ICardProps) {
+  return (
+    <div
+      data-slot="card"
+      data-variant={variant}
+      className={cn(cardVariants({ variant }), slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card header section with grid layout for title/action. */
+function CardHeader({ className, ...props }: ICardHeaderProps) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(cardStyles.header, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card title text. */
+function CardTitle({ className, ...props }: ICardTitleProps) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(cardStyles.title, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card description text. */
+function CardDescription({ className, ...props }: ICardDescriptionProps) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn(cardStyles.description, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card action slot positioned in the header. */
+function CardAction({ className, ...props }: ICardActionProps) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(cardStyles.action, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card content area. */
+function CardContent({ className, ...props }: ICardContentProps) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn(cardStyles.content, className)}
+      {...props}
+    />
+  );
+}
+
+/** Card footer area. */
+function CardFooter({ className, ...props }: ICardFooterProps) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(cardStyles.footer, className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+  cardVariants,
+};
+
+export type {
+  ICardProps,
+  ICardHeaderProps,
+  ICardTitleProps,
+  ICardDescriptionProps,
+  ICardActionProps,
+  ICardContentProps,
+  ICardFooterProps,
+} from './Card.types';
+
+export type { CardSlot } from './Card.styles';

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

@@ -0,0 +1,233 @@
+'use client';
+
+/**
+ * Checkbox component with animated SVG indicator.
+ *
+ * Built on Base UI Checkbox primitives with Motion animations for
+ * tap/hover interactions and an animated checkmark/indeterminate indicator.
+ *
+ * @module @mks2508/mks-ui/react/ui/Checkbox
+ *
+ * @example
+ * ```tsx
+ * import { Checkbox, CheckboxIndicator } from '@mks2508/mks-ui';
+ *
+ * function MyCheckbox() {
+ *   const [checked, setChecked] = useState(false);
+ *   return (
+ *     <Checkbox checked={checked} onCheckedChange={setChecked}>
+ *       <CheckboxIndicator />
+ *     </Checkbox>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';
+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 { checkboxStyles } from './Checkbox.styles';
+import type {
+  CheckboxContextType,
+  ICheckboxProps,
+  ICheckboxIndicatorProps,
+} from './Checkbox.types';
+
+const [CheckboxProvider, useCheckbox] =
+  getStrictContext<CheckboxContextType>('CheckboxContext');
+
+/**
+ * Checkbox root component with animated tap and hover interactions.
+ *
+ * Wraps Base UI `Checkbox.Root` with a `motion.button` render element,
+ * providing spring-based press and hover scale animations. Supports both
+ * controlled and uncontrolled checked state via `useControlledState`.
+ *
+ * @param props - Checkbox props including Base UI root props, motion props, slots, and config
+ * @returns A checkbox button element with animation support
+ *
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   checked={isChecked}
+ *   onCheckedChange={setIsChecked}
+ *   slots={{ root: 'border-2 border-cyan-500 rounded-md' }}
+ * >
+ *   <CheckboxIndicator />
+ * </Checkbox>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Indeterminate state
+ * <Checkbox indeterminate>
+ *   <CheckboxIndicator />
+ * </Checkbox>
+ * ```
+ */
+function Checkbox({
+  name,
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  indeterminate,
+  value,
+  nativeButton,
+  parent,
+  disabled,
+  readOnly,
+  required,
+  inputRef,
+  id,
+  className,
+  slots,
+  config,
+  ...props
+}: ICheckboxProps) {
+  const [isChecked, setIsChecked] = useControlledState({
+    value: checked,
+    defaultValue: defaultChecked,
+    onChange: onCheckedChange,
+  });
+
+  const tapScale = config?.tapScale ?? 0.95;
+  const hoverScale = config?.hoverScale ?? 1.05;
+
+  return (
+    <CheckboxProvider
+      value={{ isChecked, setIsChecked, isIndeterminate: indeterminate }}
+    >
+      <CheckboxPrimitive.Root
+        name={name}
+        defaultChecked={defaultChecked}
+        checked={checked}
+        onCheckedChange={setIsChecked}
+        indeterminate={indeterminate}
+        value={value}
+        nativeButton={nativeButton}
+        parent={parent}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        inputRef={inputRef}
+        id={id}
+        render={
+          <motion.button
+            data-slot="checkbox"
+            whileTap={{ scale: tapScale }}
+            whileHover={{ scale: hoverScale }}
+            className={cn(checkboxStyles.root, slots?.root, className)}
+            {...props}
+          />
+        }
+      />
+    </CheckboxProvider>
+  );
+}
+
+/**
+ * CheckboxIndicator renders an animated SVG checkmark or indeterminate line.
+ *
+ * Uses Motion `pathLength` and `opacity` variants for smooth check/uncheck
+ * transitions. Remains mounted (`keepMounted`) to enable exit animations.
+ *
+ * @param props - SVG motion props plus optional slot overrides
+ * @returns An animated SVG indicator element
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={isChecked} onCheckedChange={setIsChecked}>
+ *   <CheckboxIndicator className="size-4 text-white" />
+ * </Checkbox>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With slot overrides
+ * <CheckboxIndicator slots={{ indicator: 'size-3.5' }} />
+ * ```
+ */
+function CheckboxIndicator({ className, slots, ...props }: ICheckboxIndicatorProps) {
+  const { isChecked, isIndeterminate } = useCheckbox();
+
+  return (
+    <CheckboxPrimitive.Indicator
+      keepMounted
+      render={
+        <motion.svg
+          data-slot="checkbox-indicator"
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth="3.5"
+          stroke="currentColor"
+          initial="unchecked"
+          animate={isChecked ? 'checked' : 'unchecked'}
+          className={cn(checkboxStyles.indicator, slots?.indicator, className)}
+          {...props}
+        >
+          {isIndeterminate ? (
+            <motion.line
+              x1="5"
+              y1="12"
+              x2="19"
+              y2="12"
+              strokeLinecap="round"
+              initial={{ pathLength: 0, opacity: 0 }}
+              animate={{
+                pathLength: 1,
+                opacity: 1,
+                transition: { duration: 0.2 },
+              }}
+            />
+          ) : (
+            <motion.path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M4.5 12.75l6 6 9-13.5"
+              variants={{
+                checked: {
+                  pathLength: 1,
+                  opacity: 1,
+                  transition: {
+                    duration: 0.2,
+                    delay: 0.2,
+                  },
+                },
+                unchecked: {
+                  pathLength: 0,
+                  opacity: 0,
+                  transition: {
+                    duration: 0.2,
+                  },
+                },
+              }}
+            />
+          )}
+        </motion.svg>
+      }
+    />
+  );
+}
+
+export {
+  Checkbox,
+  CheckboxIndicator,
+  useCheckbox,
+};
+
+// Re-exports
+export type {
+  ICheckboxProps,
+  ICheckboxIndicatorProps,
+  ICheckboxConfig,
+  CheckboxContextType,
+  CheckboxSlot,
+} from './Checkbox.types';
+
+export { checkboxStyles } from './Checkbox.styles';