@mks2508/mks-ui 0.1.3 → 0.2.0

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

@@ -0,0 +1,155 @@
+/**
+ * Type definitions for the Switch component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Switch/Switch.types
+ */
+
+import type { Switch as SwitchPrimitives } from '@base-ui/react/switch';
+import type {
+  HTMLMotionProps,
+  LegacyAnimationControls,
+  TargetAndTransition,
+  VariantLabels,
+} from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+
+/**
+ * Available style slot names for the Switch component.
+ * Each slot maps to a visual region that can be customized via the `slots` prop.
+ *
+ * - `root` - The outer switch track/button element
+ * - `thumb` - The sliding thumb indicator
+ * - `icon` - Icons displayed at left/right/thumb positions
+ *
+ * @example
+ * ```tsx
+ * <Switch slots={{ root: 'bg-zinc-800', thumb: 'bg-white', icon: 'text-zinc-400' }} />
+ * ```
+ */
+export type SwitchSlot = 'root' | 'thumb' | 'icon';
+
+/**
+ * Position of an icon within the Switch component.
+ *
+ * - `left` - Shown when the switch is ON (checked)
+ * - `right` - Shown when the switch is OFF (unchecked)
+ * - `thumb` - Always visible on the thumb
+ */
+export type SwitchIconPosition = 'left' | 'right' | 'thumb';
+
+/**
+ * Internal context type for Switch state management.
+ * Shared between the Switch root and its child components via React context.
+ */
+export type SwitchContextType = {
+  /** Whether the switch is currently checked (on). */
+  isChecked: boolean;
+  /** Callback to update the checked state. */
+  setIsChecked: ISwitchProps['onCheckedChange'];
+  /** Whether the switch is currently being pressed. */
+  isPressed: boolean;
+  /** Callback to update the pressed state. */
+  setIsPressed: (isPressed: boolean) => void;
+};
+
+/**
+ * Configuration options for Switch behavior and animation.
+ * Extends the base config with switch-specific settings.
+ *
+ * @example
+ * ```tsx
+ * <Switch config={{ animation: { duration: 0.3 } }} />
+ * ```
+ */
+export interface ISwitchConfig extends IBaseConfig {
+  /**
+   * Spring stiffness for the thumb animation.
+   * @defaultValue 300
+   */
+  springStiffness?: number;
+  /**
+   * Spring damping for the thumb animation.
+   * @defaultValue 25
+   */
+  springDamping?: number;
+}
+
+/**
+ * Props for the Switch root component.
+ * Combines Base UI Switch.Root props (without `render`) with Motion button props,
+ * plus slot overrides and configuration.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={isOn}
+ *   onCheckedChange={setIsOn}
+ *   slots={{ root: 'w-11 h-6 rounded-full' }}
+ * >
+ *   <SwitchThumb />
+ * </Switch>
+ * ```
+ */
+export type ISwitchProps = Omit<
+  React.ComponentProps<typeof SwitchPrimitives.Root>,
+  'render'
+> &
+  HTMLMotionProps<'button'> & {
+    /** Partial class overrides for each visual slot. */
+    slots?: SlotOverrides<SwitchSlot>;
+    /** Behavioral and animation configuration. */
+    config?: ISwitchConfig;
+  };
+
+/**
+ * Props for the SwitchThumb sub-component.
+ * Combines Base UI Switch.Thumb props (without `render`) with Motion div props,
+ * plus an optional pressed animation target.
+ *
+ * @example
+ * ```tsx
+ * <SwitchThumb
+ *   pressedAnimation={{ width: 28 }}
+ *   className="size-5 rounded-full bg-white"
+ * />
+ * ```
+ */
+export type ISwitchThumbProps = Omit<
+  React.ComponentProps<typeof SwitchPrimitives.Thumb>,
+  'render'
+> &
+  HTMLMotionProps<'div'> & {
+    /**
+     * Animation target applied while the switch is being pressed.
+     * Can be a motion target object, variant labels, or a boolean.
+     */
+    pressedAnimation?:
+      | TargetAndTransition
+      | VariantLabels
+      | boolean
+      | LegacyAnimationControls;
+    /** Partial class overrides for each visual slot. */
+    slots?: SlotOverrides<SwitchSlot>;
+  };
+
+/**
+ * Props for the SwitchIcon sub-component.
+ * Renders an icon at a specified position within the switch track or thumb.
+ *
+ * @example
+ * ```tsx
+ * <SwitchIcon position="left">
+ *   <SunIcon className="size-3" />
+ * </SwitchIcon>
+ * <SwitchIcon position="right">
+ *   <MoonIcon className="size-3" />
+ * </SwitchIcon>
+ * ```
+ */
+export type ISwitchIconProps = HTMLMotionProps<'div'> & {
+  /** Where this icon is positioned within the switch. */
+  position: SwitchIconPosition;
+  /** Partial class overrides for each visual slot. */
+  slots?: SlotOverrides<SwitchSlot>;
+};

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

@@ -0,0 +1,253 @@
+'use client';
+
+/**
+ * Switch component with animated thumb and icon transitions.
+ *
+ * Built on Base UI Switch primitives with Motion animations for
+ * spring-based thumb movement, press interactions, and icon visibility.
+ *
+ * @module @mks2508/mks-ui/react/ui/Switch
+ *
+ * @example
+ * ```tsx
+ * import { Switch, SwitchThumb } from '@mks2508/mks-ui';
+ *
+ * function MySwitch() {
+ *   const [checked, setChecked] = useState(false);
+ *   return (
+ *     <Switch checked={checked} onCheckedChange={setChecked}>
+ *       <SwitchThumb />
+ *     </Switch>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icons
+ * import { Switch, SwitchThumb, SwitchIcon } from '@mks2508/mks-ui';
+ *
+ * <Switch checked={darkMode} onCheckedChange={setDarkMode}>
+ *   <SwitchIcon position="left"><SunIcon /></SwitchIcon>
+ *   <SwitchThumb />
+ *   <SwitchIcon position="right"><MoonIcon /></SwitchIcon>
+ * </Switch>
+ * ```
+ */
+
+import * as React from 'react';
+import { Switch as SwitchPrimitives } from '@base-ui/react/switch';
+import { motion } from 'motion/react';
+
+import { cn } from '@/react/lib/utils';
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { useControlledState } from '@/react/hooks/State/UseControlledState';
+
+import { switchStyles } from './Switch.styles';
+import type {
+  SwitchContextType,
+  ISwitchProps,
+  ISwitchThumbProps,
+  ISwitchIconProps,
+} from './Switch.types';
+
+const [SwitchProvider, useSwitch] =
+  getStrictContext<SwitchContextType>('SwitchContext');
+
+/**
+ * Switch root component with animated tap interactions.
+ *
+ * Wraps Base UI `Switch.Root` with a `motion.button` render element,
+ * providing tap start/end tracking for press animation support on the thumb.
+ * Supports both controlled and uncontrolled checked state via `useControlledState`.
+ *
+ * @param props - Switch props including Base UI root props, motion props, slots, and config
+ * @returns A switch button element with press tracking
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={isEnabled}
+ *   onCheckedChange={setIsEnabled}
+ *   slots={{ root: 'w-14 h-7 rounded-full bg-zinc-700' }}
+ * >
+ *   <SwitchThumb />
+ * </Switch>
+ * ```
+ */
+function Switch({
+  name,
+  defaultChecked,
+  checked,
+  onCheckedChange,
+  nativeButton,
+  disabled,
+  readOnly,
+  required,
+  inputRef,
+  id,
+  className,
+  slots,
+  config: _config,
+  ...props
+}: ISwitchProps) {
+  const [isPressed, setIsPressed] = React.useState(false);
+  const [isChecked, setIsChecked] = useControlledState({
+    value: checked,
+    defaultValue: defaultChecked,
+    onChange: onCheckedChange,
+  });
+
+  return (
+    <SwitchProvider
+      value={{ isChecked, setIsChecked, isPressed, setIsPressed }}
+    >
+      <SwitchPrimitives.Root
+        name={name}
+        defaultChecked={defaultChecked}
+        checked={checked}
+        onCheckedChange={setIsChecked}
+        nativeButton={nativeButton}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        inputRef={inputRef}
+        id={id}
+        render={
+          <motion.button
+            data-slot="switch"
+            whileTap="tap"
+            initial={false}
+            onTapStart={() => setIsPressed(true)}
+            onTapCancel={() => setIsPressed(false)}
+            onTap={() => setIsPressed(false)}
+            className={cn(switchStyles.root, slots?.root, className)}
+            {...props}
+          />
+        }
+      />
+    </SwitchProvider>
+  );
+}
+
+/**
+ * SwitchThumb renders the sliding thumb indicator with spring-based layout animation.
+ *
+ * Uses Motion `layout` for smooth position transitions between checked/unchecked states.
+ * Optionally accepts a `pressedAnimation` target applied while the switch is being pressed.
+ *
+ * @param props - Thumb props including motion props, pressed animation, and slot overrides
+ * @returns An animated thumb div element
+ *
+ * @example
+ * ```tsx
+ * <SwitchThumb
+ *   pressedAnimation={{ width: 28 }}
+ *   slots={{ thumb: 'bg-white shadow-md' }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Default spring animation
+ * <SwitchThumb />
+ * ```
+ */
+function SwitchThumb({
+  pressedAnimation,
+  transition = { type: 'spring', stiffness: 300, damping: 25 },
+  className,
+  slots,
+  ...props
+}: ISwitchThumbProps) {
+  const { isPressed } = useSwitch();
+
+  return (
+    <SwitchPrimitives.Thumb
+      render={
+        <motion.div
+          data-slot="switch-thumb"
+          whileTap="tab"
+          layout
+          transition={transition}
+          animate={isPressed ? pressedAnimation : undefined}
+          className={cn(switchStyles.thumb, slots?.thumb, className)}
+          {...props}
+        />
+      }
+    />
+  );
+}
+
+/**
+ * SwitchIcon renders an animated icon at a specified position within the switch.
+ *
+ * - `left` position: visible when the switch is ON (checked)
+ * - `right` position: visible when the switch is OFF (unchecked)
+ * - `thumb` position: always visible on the thumb element
+ *
+ * Uses spring-based scale and opacity transitions for smooth show/hide animations.
+ *
+ * @param props - Icon props including position, motion props, and slot overrides
+ * @returns An animated icon container div
+ *
+ * @example
+ * ```tsx
+ * <SwitchIcon position="left">
+ *   <CheckIcon className="size-3 text-white" />
+ * </SwitchIcon>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <SwitchIcon position="thumb">
+ *   <GripIcon className="size-2.5 text-zinc-400" />
+ * </SwitchIcon>
+ * ```
+ */
+function SwitchIcon({
+  position,
+  transition = { type: 'spring', bounce: 0 },
+  className,
+  slots,
+  ...props
+}: ISwitchIconProps) {
+  const { isChecked } = useSwitch();
+
+  const isAnimated = React.useMemo(() => {
+    if (position === 'right') return !isChecked;
+    if (position === 'left') return isChecked;
+    if (position === 'thumb') return true;
+    return false;
+  }, [position, isChecked]);
+
+  return (
+    <motion.div
+      data-slot={`switch-${position}-icon`}
+      animate={isAnimated ? { scale: 1, opacity: 1 } : { scale: 0, opacity: 0 }}
+      transition={transition}
+      className={cn(switchStyles.icon, slots?.icon, className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Switch,
+  SwitchThumb,
+  SwitchIcon,
+  useSwitch,
+};
+
+// Re-exports
+export type {
+  ISwitchProps,
+  ISwitchThumbProps,
+  ISwitchIconProps,
+  ISwitchConfig,
+  SwitchContextType,
+  SwitchIconPosition,
+  SwitchSlot,
+} from './Switch.types';
+
+export { switchStyles } from './Switch.styles';

package/src/react/ui/Tabs/Tabs.styles.ts

@@ -0,0 +1,60 @@
+/**
+ * Style slots and defaults for the Tabs component.
+ *
+ * Each slot maps to a visual region of the Tabs. Consumers override
+ * individual slots via the `slots` prop without touching internals.
+ *
+ * @module @mks2508/mks-ui/react/ui/Tabs/Tabs.styles
+ *
+ * @example
+ * ```tsx
+ * import { tabsStyles } from './Tabs.styles';
+ * // tabsStyles.root => default root classes
+ * ```
+ */
+
+import type { StyleSlots } from '@/core/types';
+
+/**
+ * Union of all visual regions (slots) in the Tabs component tree.
+ *
+ * @example
+ * ```typescript
+ * const overrides: SlotOverrides<TabsSlot> = {
+ *   root: 'w-full',
+ *   list: 'flex gap-1 border-b border-white/10',
+ *   tab: 'px-3 py-1.5 text-sm',
+ * };
+ * ```
+ */
+export type TabsSlot =
+  | 'root'
+  | 'list'
+  | 'tab'
+  | 'panel'
+  | 'panels'
+  | 'highlight'
+  | 'highlightItem';
+
+/**
+ * Default style map for every Tabs slot.
+ *
+ * Base classes are intentionally minimal so consumers can fully
+ * control the visual appearance through `slots` overrides.
+ * No colors are hardcoded -- all visuals come from consumer styles.
+ *
+ * @example
+ * ```typescript
+ * import { tabsStyles } from './Tabs.styles';
+ * cn(tabsStyles.list, slots?.list, className);
+ * ```
+ */
+export const tabsStyles: StyleSlots<TabsSlot> = {
+  root: '',
+  list: '',
+  tab: '',
+  panel: '',
+  panels: '',
+  highlight: '',
+  highlightItem: '',
+};

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

@@ -0,0 +1,250 @@
+/**
+ * Type definitions for the Tabs component.
+ *
+ * All interfaces use the IPrefix convention. Type aliases do not.
+ * Supports two panel modes: auto-height (animated resize) and layout (motion layout).
+ *
+ * @module @mks2508/mks-ui/react/ui/Tabs/Tabs.types
+ */
+
+import type * as React from 'react';
+import type { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
+import type { HTMLMotionProps, Transition } from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+import type { IHighlightProps, IHighlightItemProps } from '@/react/primitives/Highlight';
+import type { IAutoHeightProps } from '@/react/primitives/AutoHeight';
+import type { TabsSlot } from './Tabs.styles';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration interface for Tabs behavior and animation.
+ *
+ * @example
+ * ```tsx
+ * const config: ITabsConfig = {
+ *   animation: { duration: 0.3 },
+ * };
+ * ```
+ */
+export interface ITabsConfig extends IBaseConfig {
+  /** Default motion transition for panel enter/exit. */
+  panelTransition?: Transition;
+  /** Default motion transition for the highlight indicator. */
+  highlightTransition?: Transition;
+}
+
+// ---------------------------------------------------------------------------
+// Context type (type alias -- no IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal context carrying the active tab value and its setter.
+ *
+ * @example
+ * ```typescript
+ * const ctx: TabsContextType = {
+ *   value: 'settings',
+ *   setValue: (v) => {},
+ * };
+ * ```
+ */
+export type TabsContextType = {
+  /** Currently active tab value, or undefined if none. */
+  value: string | undefined;
+  /** Setter matching base-ui's onValueChange signature. */
+  setValue: ITabsProps['onValueChange'];
+};
+
+// ---------------------------------------------------------------------------
+// Root
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the root Tabs component.
+ * Extends base-ui Tabs.Root with slot overrides and config.
+ *
+ * @example
+ * ```tsx
+ * <Tabs
+ *   defaultValue="general"
+ *   slots={{ list: 'gap-2', tab: 'text-sm' }}
+ * >
+ *   ...
+ * </Tabs>
+ * ```
+ */
+export interface ITabsProps extends React.ComponentProps<typeof TabsPrimitive.Root> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+  /** Tabs behavior / animation configuration. */
+  config?: ITabsConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Highlight
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for TabsHighlight -- animated background that follows the active tab.
+ * Wraps the Highlight primitive; `controlledItems` and `value` are managed internally.
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlight className="rounded-md bg-white/10" />
+ * ```
+ */
+export interface ITabsHighlightProps
+  extends Omit<IHighlightProps, 'controlledItems' | 'value'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+/**
+ * Props for TabsHighlightItem -- wraps a tab for highlight position tracking.
+ * Requires a `value` prop matching the corresponding tab value.
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlightItem value="general">
+ *   <TabsTab value="general">General</TabsTab>
+ * </TabsHighlightItem>
+ * ```
+ */
+export interface ITabsHighlightItemProps extends IHighlightItemProps {
+  /** Tab value this highlight item corresponds to. */
+  value: string;
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for TabsList -- the container holding tab triggers.
+ *
+ * @example
+ * ```tsx
+ * <TabsList className="flex gap-1 border-b border-white/10">
+ *   <TabsTab value="general">General</TabsTab>
+ *   <TabsTab value="advanced">Advanced</TabsTab>
+ * </TabsList>
+ * ```
+ */
+export interface ITabsListProps
+  extends React.ComponentProps<typeof TabsPrimitive.List> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Tab
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for TabsTab -- a single tab trigger button.
+ *
+ * @example
+ * ```tsx
+ * <TabsTab value="general" className="px-3 py-1.5">
+ *   General
+ * </TabsTab>
+ * ```
+ */
+export interface ITabsTabProps
+  extends React.ComponentProps<typeof TabsPrimitive.Tab> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Panel
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for TabsPanel -- animated content panel with blur transitions.
+ * Combines base-ui Panel with motion HTML props for enter/exit animations.
+ *
+ * @example
+ * ```tsx
+ * <TabsPanel value="general" className="p-4">
+ *   <p>General settings content...</p>
+ * </TabsPanel>
+ * ```
+ */
+export interface ITabsPanelProps
+  extends Omit<React.ComponentProps<typeof TabsPrimitive.Panel>, keyof HTMLMotionProps<'div'>>,
+    HTMLMotionProps<'div'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Panels (auto-height | layout mode)
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for TabsPanels in auto-height mode.
+ * Uses the AutoHeight primitive to animate container height changes.
+ *
+ * @example
+ * ```tsx
+ * <TabsPanels mode="auto-height">
+ *   <TabsPanel value="general">Short content</TabsPanel>
+ *   <TabsPanel value="advanced">Much longer content...</TabsPanel>
+ * </TabsPanels>
+ * ```
+ */
+export interface ITabsPanelsAutoProps extends Omit<IAutoHeightProps, 'children'> {
+  /** Panel animation mode (default). */
+  mode?: 'auto-height';
+  /** Tab panel children. */
+  children: React.ReactNode;
+  /** Motion transition for height animation. */
+  transition?: Transition;
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+/**
+ * Props for TabsPanels in layout mode.
+ * Uses Motion layout animation to transition between panels.
+ *
+ * @example
+ * ```tsx
+ * <TabsPanels mode="layout" className="overflow-hidden">
+ *   <TabsPanel value="general">Content A</TabsPanel>
+ *   <TabsPanel value="advanced">Content B</TabsPanel>
+ * </TabsPanels>
+ * ```
+ */
+export interface ITabsPanelsLayoutProps extends Omit<HTMLMotionProps<'div'>, 'children'> {
+  /** Panel animation mode. */
+  mode: 'layout';
+  /** Tab panel children. */
+  children: React.ReactNode;
+  /** Motion transition for layout animation. */
+  transition?: Transition;
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<TabsSlot>;
+}
+
+/**
+ * Discriminated union of TabsPanels props.
+ * Defaults to auto-height mode when `mode` is omitted.
+ *
+ * @example
+ * ```tsx
+ * // Auto-height (default)
+ * <TabsPanels>...</TabsPanels>
+ *
+ * // Layout mode
+ * <TabsPanels mode="layout">...</TabsPanels>
+ * ```
+ */
+export type ITabsPanelsProps = ITabsPanelsAutoProps | ITabsPanelsLayoutProps;