@mks2508/mks-ui 0.1.4 → 0.2.0

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

@@ -0,0 +1,421 @@
+'use client';
+
+/**
+ * Tabs component -- animated tab navigation built on base-ui Tabs
+ * with motion transitions, highlight tracking, auto-height panels,
+ * and the v0.2.0 slot system.
+ *
+ * Provides sub-components for the tab list, individual tabs, panels,
+ * animated highlight indicators, and a panels container with two modes:
+ * auto-height (ResizeObserver) and layout (Motion layout animation).
+ *
+ * @module @mks2508/mks-ui/react/ui/Tabs
+ *
+ * @example
+ * ```tsx
+ * <Tabs defaultValue="general" slots={{ list: 'flex gap-1 border-b' }}>
+ *   <TabsList>
+ *     <TabsHighlight className="rounded-md bg-white/10">
+ *       <TabsHighlightItem value="general">
+ *         <TabsTab value="general">General</TabsTab>
+ *       </TabsHighlightItem>
+ *       <TabsHighlightItem value="advanced">
+ *         <TabsTab value="advanced">Advanced</TabsTab>
+ *       </TabsHighlightItem>
+ *     </TabsHighlight>
+ *   </TabsList>
+ *   <TabsPanels>
+ *     <TabsPanel value="general">General content</TabsPanel>
+ *     <TabsPanel value="advanced">Advanced content</TabsPanel>
+ *   </TabsPanels>
+ * </Tabs>
+ * ```
+ */
+
+import * as React from 'react';
+import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
+import {
+  motion,
+  AnimatePresence,
+  type Transition,
+} from 'motion/react';
+
+import {
+  Highlight,
+  HighlightItem,
+} from '@/react/primitives/Highlight';
+import { AutoHeight } from '@/react/primitives/AutoHeight';
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { useControlledState } from '@/react/hooks/State/UseControlledState';
+import { cn } from '@/react/lib/utils';
+import { tabsStyles } from './Tabs.styles';
+
+import type {
+  TabsContextType,
+  ITabsProps,
+  ITabsHighlightProps,
+  ITabsHighlightItemProps,
+  ITabsListProps,
+  ITabsTabProps,
+  ITabsPanelProps,
+  ITabsPanelsProps,
+  ITabsPanelsAutoProps,
+} from './Tabs.types';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const [TabsProvider, useTabs] =
+  getStrictContext<TabsContextType>('TabsContext');
+
+// ---------------------------------------------------------------------------
+// Tabs (Root)
+// ---------------------------------------------------------------------------
+
+/**
+ * Root Tabs component -- provides active tab value context and
+ * controlled/uncontrolled state management.
+ *
+ * @param value - Controlled active tab value
+ * @param defaultValue - Uncontrolled initial active tab value
+ * @param onValueChange - Callback when active tab changes
+ * @param slots - Partial class overrides per slot
+ * @param config - Tabs behavior / animation configuration
+ *
+ * @example
+ * ```tsx
+ * <Tabs defaultValue="general" slots={{ root: 'w-full' }}>
+ *   <TabsList>...</TabsList>
+ *   <TabsPanels>...</TabsPanels>
+ * </Tabs>
+ * ```
+ */
+function Tabs({ slots, config, className, ...props }: ITabsProps) {
+  const [value, setValue] = useControlledState({
+    value: props.value,
+    defaultValue: props.defaultValue,
+    onChange: props.onValueChange,
+  });
+
+  return (
+    <TabsProvider value={{ value, setValue }}>
+      <TabsPrimitive.Root
+        data-slot="tabs"
+        className={cn(tabsStyles.root, slots?.root, className)}
+        {...props}
+        onValueChange={setValue}
+      />
+    </TabsProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsHighlight
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsHighlight -- animated background indicator that follows the active tab.
+ * Wraps the Highlight primitive with tab-specific defaults (spring transition,
+ * no click activation since tabs manage their own active state).
+ *
+ * @param transition - Motion transition config (default: spring 200/25)
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlight className="rounded-md bg-white/10">
+ *   <TabsHighlightItem value="tab1">
+ *     <TabsTab value="tab1">Tab 1</TabsTab>
+ *   </TabsHighlightItem>
+ * </TabsHighlight>
+ * ```
+ */
+function TabsHighlight({
+  transition = { type: 'spring', stiffness: 200, damping: 25 },
+  slots,
+  className,
+  ...props
+}: ITabsHighlightProps) {
+  const { value } = useTabs();
+
+  return (
+    <Highlight
+      data-slot="tabs-highlight"
+      controlledItems
+      value={value}
+      transition={transition}
+      click={false}
+      className={cn(tabsStyles.highlight, slots?.highlight, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsList
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsList -- the container holding tab trigger buttons.
+ * Renders a base-ui Tabs.List with the `list` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsList className="flex gap-1 border-b border-white/10 pb-1">
+ *   <TabsTab value="general">General</TabsTab>
+ *   <TabsTab value="advanced">Advanced</TabsTab>
+ * </TabsList>
+ * ```
+ */
+function TabsList({ slots, className, ...props }: ITabsListProps) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      className={cn(tabsStyles.list, slots?.list, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsHighlightItem
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsHighlightItem -- wraps a TabsTab for highlight position tracking.
+ * Must be placed inside a TabsHighlight context. The `value` prop should
+ * match the corresponding TabsTab value.
+ *
+ * @param value - Tab value this highlight item corresponds to
+ * @param slots - Partial class overrides per slot
+ *
+ * @example
+ * ```tsx
+ * <TabsHighlightItem value="general">
+ *   <TabsTab value="general">General</TabsTab>
+ * </TabsHighlightItem>
+ * ```
+ */
+function TabsHighlightItem({ slots, ...props }: ITabsHighlightItemProps) {
+  return <HighlightItem data-slot="tabs-highlight-item" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// TabsTab
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsTab -- a single tab trigger button that activates its panel.
+ * Renders a base-ui Tabs.Tab with the `tab` slot classes.
+ *
+ * @param value - The value this tab represents
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsTab value="general" className="px-3 py-1.5 text-sm font-medium">
+ *   General
+ * </TabsTab>
+ * ```
+ */
+function TabsTab({ slots, className, ...props }: ITabsTabProps) {
+  return (
+    <TabsPrimitive.Tab
+      data-slot="tabs-tab"
+      className={cn(tabsStyles.tab, slots?.tab, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsPanel
+// ---------------------------------------------------------------------------
+
+/**
+ * TabsPanel -- an animated content panel associated with a tab.
+ * Uses Motion for blur + opacity enter/exit transitions wrapped in
+ * AnimatePresence for smooth unmount animations.
+ *
+ * @param value - The tab value this panel corresponds to
+ * @param keepMounted - Keep the panel in DOM when inactive
+ * @param transition - Motion transition config (default: 0.5s easeInOut)
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <TabsPanel value="general" className="p-4">
+ *   <h2>General Settings</h2>
+ *   <p>Configure your preferences here.</p>
+ * </TabsPanel>
+ * ```
+ */
+function TabsPanel({
+  value,
+  keepMounted,
+  transition = { duration: 0.5, ease: 'easeInOut' },
+  slots,
+  className,
+  ...props
+}: ITabsPanelProps) {
+  return (
+    <AnimatePresence mode="wait">
+      <TabsPrimitive.Panel
+        render={
+          <motion.div
+            data-slot="tabs-panel"
+            layout
+            layoutDependency={value}
+            initial={{ opacity: 0, filter: 'blur(4px)' }}
+            animate={{ opacity: 1, filter: 'blur(0px)' }}
+            exit={{ opacity: 0, filter: 'blur(4px)' }}
+            transition={transition}
+            className={cn(tabsStyles.panel, slots?.panel, className)}
+            {...(props as any)}
+          />
+        }
+        keepMounted={keepMounted}
+        value={value}
+      />
+    </AnimatePresence>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TabsPanels
+// ---------------------------------------------------------------------------
+
+/** Default spring transition for the panels container. */
+const defaultPanelsTransition: Transition = {
+  type: 'spring',
+  stiffness: 200,
+  damping: 30,
+};
+
+/**
+ * Type guard to distinguish auto-height mode from layout mode.
+ *
+ * @param props - TabsPanels props union
+ * @returns True if auto-height mode (default)
+ */
+function isAutoMode(props: ITabsPanelsProps): props is ITabsPanelsAutoProps {
+  return !props.mode || props.mode === 'auto-height';
+}
+
+/**
+ * TabsPanels -- container for tab panels with animated height transitions.
+ * Supports two modes:
+ *
+ * - **auto-height** (default): Uses ResizeObserver to animate container
+ *   height when panels have different content sizes.
+ * - **layout**: Uses Motion layout animation for size transitions,
+ *   with overflow hidden.
+ *
+ * @param mode - Animation mode: 'auto-height' (default) or 'layout'
+ * @param transition - Motion transition config
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * // Auto-height mode (default)
+ * <TabsPanels>
+ *   <TabsPanel value="short">Short content</TabsPanel>
+ *   <TabsPanel value="long">Much longer content with many paragraphs...</TabsPanel>
+ * </TabsPanels>
+ *
+ * // Layout mode
+ * <TabsPanels mode="layout" className="rounded-lg">
+ *   <TabsPanel value="a">Content A</TabsPanel>
+ *   <TabsPanel value="b">Content B</TabsPanel>
+ * </TabsPanels>
+ * ```
+ */
+function TabsPanels(props: ITabsPanelsProps) {
+  const { value } = useTabs();
+
+  if (isAutoMode(props)) {
+    const {
+      children,
+      transition = defaultPanelsTransition,
+      slots,
+      className,
+      mode: _mode,
+      ...autoProps
+    } = props;
+
+    return (
+      <AutoHeight
+        data-slot="tabs-panels"
+        deps={[value]}
+        transition={transition}
+        className={cn(tabsStyles.panels, slots?.panels, className)}
+        {...autoProps}
+      >
+        <React.Fragment key={value}>{children}</React.Fragment>
+      </AutoHeight>
+    );
+  }
+
+  const {
+    children,
+    style,
+    transition = defaultPanelsTransition,
+    slots,
+    className,
+    mode: _mode,
+    ...layoutProps
+  } = props;
+
+  return (
+    <motion.div
+      data-slot="tabs-panels"
+      layout="size"
+      layoutDependency={value}
+      transition={{ layout: transition }}
+      style={{ overflow: 'hidden', ...style }}
+      className={cn(tabsStyles.panels, slots?.panels, className)}
+      {...layoutProps}
+    >
+      <React.Fragment key={value}>{children}</React.Fragment>
+    </motion.div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export {
+  Tabs,
+  TabsHighlight,
+  TabsHighlightItem,
+  TabsList,
+  TabsTab,
+  TabsPanel,
+  TabsPanels,
+};
+
+// Re-export all types
+export type {
+  ITabsProps,
+  ITabsHighlightProps,
+  ITabsHighlightItemProps,
+  ITabsListProps,
+  ITabsTabProps,
+  ITabsPanelProps,
+  ITabsPanelsProps,
+  ITabsPanelsAutoProps,
+  ITabsPanelsLayoutProps,
+  ITabsConfig,
+  TabsContextType,
+} from './Tabs.types';
+
+export type { TabsSlot } from './Tabs.styles';

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

@@ -0,0 +1,10 @@
+import type { StyleSlots } from '@/core/types';
+
+type TextareaSlot = 'root';
+
+const textareaStyles: StyleSlots<TextareaSlot> = {
+  root: 'border-input dark:bg-input/30 focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 disabled:bg-input/50 dark:disabled:bg-input/80 rounded-lg border bg-transparent px-2.5 py-2 text-base transition-colors focus-visible:ring-3 aria-invalid:ring-3 md:text-sm placeholder:text-muted-foreground flex field-sizing-content min-h-16 w-full outline-none disabled:cursor-not-allowed disabled:opacity-50',
+};
+
+export { textareaStyles };
+export type { TextareaSlot };

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

@@ -0,0 +1,9 @@
+import type { SlotOverrides } from '@/core/types';
+import type { TextareaSlot } from './Textarea.styles';
+
+/** Props for the Textarea component. */
+interface ITextareaProps extends React.ComponentProps<'textarea'> {
+  slots?: SlotOverrides<TextareaSlot>;
+}
+
+export type { ITextareaProps };

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

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+import { cn } from '@/react/lib/utils';
+import { textareaStyles } from './Textarea.styles';
+import type { ITextareaProps } from './Textarea.types';
+
+/**
+ * Textarea — styled multi-line text input.
+ *
+ * @example
+ * ```tsx
+ * <Textarea placeholder="Enter description..." />
+ * ```
+ */
+function Textarea({ className, slots, ...props }: ITextareaProps) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(textareaStyles.root, slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+export { Textarea };
+export type { ITextareaProps } from './Textarea.types';
+export type { TextareaSlot } from './Textarea.styles';

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

@@ -0,0 +1,43 @@
+/**
+ * Style definitions for the Tooltip component.
+ *
+ * Provides StyleSlots for each visual region. Uses only CSS variable
+ * utilities; never hard-coded color values.
+ *
+ * @module @mks2508/mks-ui/react/ui/Tooltip/Tooltip.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+import type { TooltipSlot } from './Tooltip.types';
+
+/**
+ * Default Tailwind classes for each Tooltip visual region.
+ * Consumers override via the `slots` prop; the merge order is:
+ * `base -> slots -> className`.
+ *
+ * @example
+ * ```typescript
+ * import { tooltipStyles } from './Tooltip.styles';
+ * // tooltipStyles.popup => 'z-50 overflow-hidden rounded-md ...'
+ * ```
+ */
+export const tooltipStyles: StyleSlots<TooltipSlot> = {
+  /** Root wrapper — no visual styling by default. */
+  root: '',
+
+  /** Popup content container. */
+  popup: [
+    'z-50 overflow-hidden rounded-md',
+    'border border-border bg-popover px-3 py-1.5',
+    'text-sm text-popover-foreground shadow-md',
+  ].join(' '),
+
+  /** Trigger element — no default styling. */
+  trigger: '',
+
+  /** Positioner wrapper — handles absolute placement. */
+  positioner: '',
+
+  /** Directional arrow pointing toward the trigger. */
+  arrow: 'fill-popover',
+};