@mks2508/mks-ui 0.1.4 → 0.2.0

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

@@ -0,0 +1,63 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { SlotOverrides } from '@/core/types';
+import type { buttonVariants, ButtonSlot } from './Button.styles';
+
+/** Button interaction state. */
+interface IButtonState {
+  /** Whether the button is disabled. */
+  disabled: boolean;
+  /** Whether the button is being pressed. */
+  pressed: boolean;
+}
+
+/**
+ * Props for the Button component.
+ *
+ * Supports state-based className/style functions, asChild composition,
+ * and custom render elements via Base UI.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="destructive" size="lg">Delete</Button>
+ * <Button asChild><a href="/link">Link</a></Button>
+ * <Button className={(state) => state.pressed ? 'scale-95' : ''}>Press</Button>
+ * ```
+ */
+interface IButtonProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'style'>,
+    VariantProps<typeof buttonVariants> {
+  /** Keep button focusable when disabled. */
+  focusableWhenDisabled?: boolean;
+  /** Whether the rendered element is a native button. */
+  nativeButton?: boolean;
+  /** Render as child element (Slot pattern). */
+  asChild?: boolean;
+  /** Custom render element or function. */
+  render?:
+    | React.ReactElement
+    | ((props: React.HTMLProps<HTMLElement>, state: IButtonState) => React.ReactElement);
+  /** CSS class or function returning class based on button state. */
+  className?: string | ((state: IButtonState) => string | undefined);
+  /** CSS styles or function returning styles based on button state. */
+  style?:
+    | React.CSSProperties
+    | ((state: IButtonState) => React.CSSProperties | undefined);
+  /** Override classes for button visual regions. */
+  slots?: SlotOverrides<ButtonSlot>;
+}
+
+/** Available button variants. */
+type ButtonVariant =
+  | 'default'
+  | 'secondary'
+  | 'destructive'
+  | 'outline'
+  | 'ghost'
+  | 'link'
+  | 'success'
+  | 'warning';
+
+/** Available button sizes. */
+type ButtonSize = 'default' | 'sm' | 'lg' | 'icon';
+
+export type { IButtonProps, IButtonState, ButtonVariant, ButtonSize };

package/src/react/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/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/Card/Card.styles.ts

@@ -0,0 +1,32 @@
+import { cva } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the Card component. */
+type CardSlot = 'root' | 'header' | 'title' | 'description' | 'action' | 'content' | 'footer';
+
+const cardStyles: StyleSlots<CardSlot> = {
+  root: 'flex flex-col gap-6 rounded-xl border transition-all',
+  header: '@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6',
+  title: 'leading-none font-semibold',
+  description: 'text-muted-foreground text-sm',
+  action: 'col-start-2 row-span-2 row-start-1 self-start justify-self-end',
+  content: 'px-6',
+  footer: 'flex items-center px-6 [.border-t]:pt-6',
+};
+
+/** CVA variants for the Card root. */
+const cardVariants = cva(cardStyles.root, {
+  variants: {
+    variant: {
+      default: 'bg-card text-card-foreground py-6 shadow-sm',
+      glass: 'bg-card/70 backdrop-blur-md border-border shadow-[0_4px_20px_rgba(0,0,0,0.19)]',
+      'glass-accent': 'bg-card/70 backdrop-blur-md border-border-primary shadow-[0_4px_20px_rgba(212,12,103,0.25)]',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+export { cardStyles, cardVariants };
+export type { CardSlot };

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

@@ -0,0 +1,39 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { SlotOverrides } from '@/core/types';
+import type { cardVariants, CardSlot } from './Card.styles';
+
+/** Props for the Card component. */
+interface ICardProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof cardVariants> {
+  /** Override classes for card visual regions. */
+  slots?: SlotOverrides<CardSlot>;
+}
+
+/** Props for CardHeader. */
+type ICardHeaderProps = React.ComponentProps<'div'>;
+
+/** Props for CardTitle. */
+type ICardTitleProps = React.ComponentProps<'div'>;
+
+/** Props for CardDescription. */
+type ICardDescriptionProps = React.ComponentProps<'div'>;
+
+/** Props for CardAction. */
+type ICardActionProps = React.ComponentProps<'div'>;
+
+/** Props for CardContent. */
+type ICardContentProps = React.ComponentProps<'div'>;
+
+/** Props for CardFooter. */
+type ICardFooterProps = React.ComponentProps<'div'>;
+
+export type {
+  ICardProps,
+  ICardHeaderProps,
+  ICardTitleProps,
+  ICardDescriptionProps,
+  ICardActionProps,
+  ICardContentProps,
+  ICardFooterProps,
+};

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

@@ -0,0 +1,130 @@
+import * as React from 'react';
+
+import { cn } from '@/react/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/Checkbox/Checkbox.styles.ts

@@ -0,0 +1,40 @@
+/**
+ * Style slots and CVA variants for the Checkbox component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Checkbox/Checkbox.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+
+import type { CheckboxSlot } from './Checkbox.types';
+
+/**
+ * Default style slots for the Checkbox component.
+ * Each key maps to a visual region with its base Tailwind classes.
+ *
+ * - `root` - The outer checkbox button with border, sizing, and focus styles
+ * - `indicator` - The SVG indicator element with sizing
+ *
+ * @example
+ * ```typescript
+ * import { checkboxStyles } from './Checkbox.styles';
+ *
+ * // Access the root slot classes
+ * const rootClasses = checkboxStyles.root;
+ * // 'inline-flex items-center justify-center ...'
+ * ```
+ */
+export const checkboxStyles: StyleSlots<CheckboxSlot> = {
+  root: [
+    'inline-flex items-center justify-center',
+    'size-5 shrink-0 rounded-sm',
+    'border border-input',
+    'shadow-xs',
+    'transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'disabled:cursor-not-allowed disabled:opacity-50',
+    'data-[checked]:bg-primary data-[checked]:text-primary-foreground data-[checked]:border-primary',
+    'data-[indeterminate]:bg-primary data-[indeterminate]:text-primary-foreground data-[indeterminate]:border-primary',
+  ].join(' '),
+  indicator: 'size-4',
+};

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

@@ -0,0 +1,98 @@
+/**
+ * Type definitions for the Checkbox component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Checkbox/Checkbox.types
+ */
+
+import type { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';
+import type { HTMLMotionProps, SVGMotionProps } from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+
+/**
+ * Available style slot names for the Checkbox component.
+ * Each slot maps to a visual region that can be customized via the `slots` prop.
+ *
+ * - `root` - The outer checkbox button element
+ * - `indicator` - The SVG checkmark/indeterminate indicator
+ *
+ * @example
+ * ```tsx
+ * <Checkbox slots={{ root: 'border-cyan-400', indicator: 'text-cyan-400' }} />
+ * ```
+ */
+export type CheckboxSlot = 'root' | 'indicator';
+
+/**
+ * Internal context type for Checkbox state management.
+ * Shared between the Checkbox root and its child components via React context.
+ */
+export type CheckboxContextType = {
+  /** Whether the checkbox is currently checked. */
+  isChecked: boolean;
+  /** Callback to update the checked state. */
+  setIsChecked: ICheckboxProps['onCheckedChange'];
+  /** Whether the checkbox is in an indeterminate state. */
+  isIndeterminate: boolean | undefined;
+};
+
+/**
+ * Configuration options for Checkbox behavior and animation.
+ * Extends the base config with checkbox-specific settings.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox config={{ animation: { duration: 0.2 } }} />
+ * ```
+ */
+export interface ICheckboxConfig extends IBaseConfig {
+  /**
+   * Scale factor applied when the checkbox is tapped.
+   * @defaultValue 0.95
+   */
+  tapScale?: number;
+  /**
+   * Scale factor applied when the checkbox is hovered.
+   * @defaultValue 1.05
+   */
+  hoverScale?: number;
+}
+
+/**
+ * Props for the Checkbox root component.
+ * Combines Base UI Checkbox.Root props (without `render`) with Motion button props,
+ * plus slot overrides and configuration.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   checked={isChecked}
+ *   onCheckedChange={setIsChecked}
+ *   slots={{ root: 'rounded-md border-2 border-zinc-600' }}
+ * />
+ * ```
+ */
+export type ICheckboxProps = Omit<
+  React.ComponentProps<typeof CheckboxPrimitive.Root>,
+  'render'
+> &
+  HTMLMotionProps<'button'> & {
+    /** Partial class overrides for each visual slot. */
+    slots?: SlotOverrides<CheckboxSlot>;
+    /** Behavioral and animation configuration. */
+    config?: ICheckboxConfig;
+  };
+
+/**
+ * Props for the CheckboxIndicator sub-component.
+ * Extends SVG motion props for the animated checkmark/indeterminate indicator.
+ *
+ * @example
+ * ```tsx
+ * <CheckboxIndicator className="size-4" />
+ * ```
+ */
+export type ICheckboxIndicatorProps = SVGMotionProps<SVGSVGElement> & {
+  /** Partial class overrides for each visual slot. */
+  slots?: SlotOverrides<CheckboxSlot>;
+};