@mks2508/mks-ui 0.1.3 → 0.2.0

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

@@ -0,0 +1,254 @@
+'use client';
+
+/**
+ * Progress component with animated indicator and counting value display.
+ *
+ * Built on Base UI Progress primitives with Motion animations for
+ * spring-based indicator width transitions and CountingNumber for
+ * animated numeric value display.
+ *
+ * @module @mks2508/mks-ui/react/ui/Progress
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   Progress,
+ *   ProgressTrack,
+ *   ProgressIndicator,
+ *   ProgressLabel,
+ *   ProgressValue,
+ * } from '@mks2508/mks-ui';
+ *
+ * function MyProgress() {
+ *   return (
+ *     <Progress value={75}>
+ *       <ProgressLabel>Uploading...</ProgressLabel>
+ *       <ProgressTrack>
+ *         <ProgressIndicator />
+ *       </ProgressTrack>
+ *       <ProgressValue />
+ *     </Progress>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Progress as ProgressPrimitives } from '@base-ui/react/progress';
+import { motion } from 'motion/react';
+
+import { cn } from '@/react/lib/utils';
+import { getStrictContext } from '@/react/lib/get-strict-context';
+import { CountingNumber } from '@/react/primitives/CountingNumber';
+
+import { progressStyles } from './Progress.styles';
+import type {
+  ProgressContextType,
+  IProgressProps,
+  IProgressIndicatorProps,
+  IProgressTrackProps,
+  IProgressLabelProps,
+  IProgressValueProps,
+} from './Progress.types';
+
+const [ProgressProvider, useProgress] =
+  getStrictContext<ProgressContextType>('ProgressContext');
+
+const MotionProgressIndicator = motion.create(ProgressPrimitives.Indicator);
+
+/**
+ * Progress root component that provides progress context to child components.
+ *
+ * Wraps Base UI `Progress.Root` with a context provider that shares the current
+ * progress value with descendant components (indicator, value display, etc.).
+ *
+ * @param props - Progress props including Base UI root props, slots, and config
+ * @returns A progress container element with context provider
+ *
+ * @example
+ * ```tsx
+ * <Progress value={50} slots={{ root: 'w-full max-w-md' }}>
+ *   <ProgressTrack>
+ *     <ProgressIndicator />
+ *   </ProgressTrack>
+ * </Progress>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With label and animated value
+ * <Progress value={loading}>
+ *   <div className="flex justify-between">
+ *     <ProgressLabel>Loading assets</ProgressLabel>
+ *     <ProgressValue />
+ *   </div>
+ *   <ProgressTrack>
+ *     <ProgressIndicator />
+ *   </ProgressTrack>
+ * </Progress>
+ * ```
+ */
+function Progress({ className, slots, config: _config, ...props }: IProgressProps) {
+  return (
+    <ProgressProvider value={{ value: props.value ?? 0 }}>
+      <ProgressPrimitives.Root
+        data-slot="progress"
+        className={cn(progressStyles.root, slots?.root, className)}
+        {...props}
+      />
+    </ProgressProvider>
+  );
+}
+
+/**
+ * ProgressIndicator renders the animated filled bar within the track.
+ *
+ * Uses `motion.create` to wrap the Base UI Indicator with spring-based
+ * width animation that transitions smoothly as the value changes.
+ *
+ * @param props - Indicator props including transition config and slot overrides
+ * @returns A motion-enhanced indicator element
+ *
+ * @example
+ * ```tsx
+ * <ProgressTrack>
+ *   <ProgressIndicator
+ *     transition={{ type: 'spring', stiffness: 120, damping: 20 }}
+ *     slots={{ indicator: 'bg-cyan-500' }}
+ *   />
+ * </ProgressTrack>
+ * ```
+ */
+function ProgressIndicator({
+  transition = { type: 'spring', stiffness: 100, damping: 30 },
+  className,
+  slots,
+  ...props
+}: IProgressIndicatorProps) {
+  const { value } = useProgress();
+
+  return (
+    <MotionProgressIndicator
+      data-slot="progress-indicator"
+      animate={{ width: `${value}%` }}
+      transition={transition}
+      className={cn(progressStyles.indicator, slots?.indicator, className)}
+      {...(props as React.ComponentProps<typeof MotionProgressIndicator>)}
+    />
+  );
+}
+
+/**
+ * ProgressTrack renders the background track bar that contains the indicator.
+ *
+ * @param props - Track props including Base UI Track props and slot overrides
+ * @returns A track element for the progress bar
+ *
+ * @example
+ * ```tsx
+ * <ProgressTrack slots={{ track: 'h-3 rounded-lg bg-zinc-800' }}>
+ *   <ProgressIndicator />
+ * </ProgressTrack>
+ * ```
+ */
+function ProgressTrack({ className, slots, ...props }: IProgressTrackProps) {
+  return (
+    <ProgressPrimitives.Track
+      data-slot="progress-track"
+      className={cn(progressStyles.track, slots?.track, className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * ProgressLabel renders accessible label text for the progress bar.
+ *
+ * @param props - Label props including Base UI Label props and slot overrides
+ * @returns A label element for the progress bar
+ *
+ * @example
+ * ```tsx
+ * <ProgressLabel slots={{ label: 'text-xs uppercase tracking-wide' }}>
+ *   Downloading...
+ * </ProgressLabel>
+ * ```
+ */
+function ProgressLabel({ className, slots, ...props }: IProgressLabelProps) {
+  return (
+    <ProgressPrimitives.Label
+      data-slot="progress-label"
+      className={cn(progressStyles.label, slots?.label, className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * ProgressValue renders the current progress as an animated counting number.
+ *
+ * Uses the CountingNumber primitive for spring-based numeric transitions,
+ * so the displayed value smoothly animates as progress changes.
+ *
+ * @param props - Value props combining Base UI Value with CountingNumber props and slot overrides
+ * @returns An animated numeric value element
+ *
+ * @example
+ * ```tsx
+ * <ProgressValue
+ *   transition={{ stiffness: 80, damping: 20 }}
+ *   slots={{ value: 'font-mono text-cyan-400' }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With decimal places
+ * <ProgressValue decimalPlaces={1} decimalSeparator="." />
+ * ```
+ */
+function ProgressValue({
+  transition = { stiffness: 80, damping: 20 },
+  className,
+  slots,
+  ...props
+}: IProgressValueProps) {
+  const { value } = useProgress();
+
+  return (
+    <ProgressPrimitives.Value
+      data-slot="progress-value"
+      render={
+        <CountingNumber
+          number={value ?? 0}
+          transition={transition}
+          className={cn(progressStyles.value, slots?.value, className)}
+          {...props}
+        />
+      }
+    />
+  );
+}
+
+export {
+  Progress,
+  ProgressIndicator,
+  ProgressTrack,
+  ProgressLabel,
+  ProgressValue,
+  useProgress,
+};
+
+// Re-exports
+export type {
+  IProgressProps,
+  IProgressIndicatorProps,
+  IProgressTrackProps,
+  IProgressLabelProps,
+  IProgressValueProps,
+  IProgressConfig,
+  ProgressContextType,
+  ProgressSlot,
+} from './Progress.types';
+
+export { progressStyles } from './Progress.styles';

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

@@ -0,0 +1,30 @@
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the Select component family. */
+type SelectSlot =
+  | 'root'
+  | 'trigger'
+  | 'content'
+  | 'item'
+  | 'label'
+  | 'separator'
+  | 'group'
+  | 'value'
+  | 'scrollButton';
+
+const selectStyles: StyleSlots<SelectSlot> = {
+  root: '',
+  trigger:
+    'border-input data-placeholder:text-muted-foreground dark:bg-input/30 dark:hover:bg-input/50 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 gap-1.5 rounded-lg border bg-transparent py-2 pr-2 pl-2.5 text-sm transition-colors select-none focus-visible:ring-3 aria-invalid:ring-3 data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded-[min(var(--radius-md),10px)] *:data-[slot=select-value]:gap-1.5 [&_svg:not([class*=\'size-\'])]:size-4 flex w-fit items-center justify-between whitespace-nowrap outline-none disabled:cursor-not-allowed disabled:opacity-50 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  content:
+    'bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 min-w-36 rounded-lg shadow-md ring-1 duration-100 data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 relative isolate z-50 max-h-(--available-height) w-(--anchor-width) origin-(--transform-origin) overflow-x-hidden overflow-y-auto data-[align-trigger=true]:animate-none',
+  item: 'focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm [&_svg:not([class*=\'size-\'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2 relative flex w-full cursor-default items-center outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  label: 'text-muted-foreground px-1.5 py-1 text-xs',
+  separator: 'bg-border -mx-1 my-1 h-px pointer-events-none',
+  group: 'scroll-my-1 p-1',
+  value: 'flex flex-1 text-left',
+  scrollButton: 'bg-popover z-10 flex cursor-default items-center justify-center py-1 [&_svg:not([class*=\'size-\'])]:size-4 w-full',
+};
+
+export { selectStyles };
+export type { SelectSlot };

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

@@ -0,0 +1,51 @@
+import type { Select as SelectPrimitive } from '@base-ui/react/select';
+import type { SlotOverrides } from '@/core/types';
+import type { SelectSlot } from './Select.styles';
+
+/** Props for the Select root. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ISelectProps = SelectPrimitive.Root.Props<any>;
+
+/** Props for SelectGroup. */
+type ISelectGroupProps = SelectPrimitive.Group.Props;
+
+/** Props for SelectValue. */
+type ISelectValueProps = SelectPrimitive.Value.Props;
+
+/** Props for SelectTrigger. */
+interface ISelectTriggerProps extends SelectPrimitive.Trigger.Props {
+  /** Trigger size variant. */
+  size?: 'sm' | 'default';
+  /** Override classes for select visual regions. */
+  slots?: SlotOverrides<SelectSlot>;
+}
+
+/** Props for SelectContent. */
+interface ISelectContentProps
+  extends SelectPrimitive.Popup.Props,
+    Pick<
+      SelectPrimitive.Positioner.Props,
+      'align' | 'alignOffset' | 'side' | 'sideOffset' | 'alignItemWithTrigger'
+    > {
+  slots?: SlotOverrides<SelectSlot>;
+}
+
+/** Props for SelectLabel. */
+type ISelectLabelProps = SelectPrimitive.GroupLabel.Props;
+
+/** Props for SelectItem. */
+type ISelectItemProps = SelectPrimitive.Item.Props;
+
+/** Props for SelectSeparator. */
+type ISelectSeparatorProps = SelectPrimitive.Separator.Props;
+
+export type {
+  ISelectProps,
+  ISelectGroupProps,
+  ISelectValueProps,
+  ISelectTriggerProps,
+  ISelectContentProps,
+  ISelectLabelProps,
+  ISelectItemProps,
+  ISelectSeparatorProps,
+};

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

@@ -0,0 +1,225 @@
+import * as React from 'react';
+import { Select as SelectPrimitive } from '@base-ui/react/select';
+
+import { cn } from '@/react/lib/utils';
+import { HugeiconsIcon } from '@hugeicons/react';
+import {
+  UnfoldMoreIcon,
+  Tick02Icon,
+  ArrowUp01Icon,
+  ArrowDown01Icon,
+} from '@hugeicons/core-free-icons';
+import { selectStyles } from './Select.styles';
+import type {
+  ISelectGroupProps,
+  ISelectValueProps,
+  ISelectTriggerProps,
+  ISelectContentProps,
+  ISelectLabelProps,
+  ISelectItemProps,
+  ISelectSeparatorProps,
+} from './Select.types';
+
+/** Select — root component wrapping Base UI Select. */
+const Select = SelectPrimitive.Root;
+
+/** SelectGroup — groups related select items. */
+function SelectGroup({ className, ...props }: ISelectGroupProps) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn(selectStyles.group, className)}
+      {...props}
+    />
+  );
+}
+
+/** SelectValue — displays the selected value text. */
+function SelectValue({ className, ...props }: ISelectValueProps) {
+  return (
+    <SelectPrimitive.Value
+      data-slot="select-value"
+      className={cn(selectStyles.value, className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SelectTrigger — button that opens the select dropdown.
+ *
+ * @param size - Trigger size: 'default' or 'sm'
+ *
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Choose..." />
+ * </SelectTrigger>
+ * ```
+ */
+function SelectTrigger({
+  className,
+  size = 'default',
+  children,
+  slots,
+  ...props
+}: ISelectTriggerProps) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(selectStyles.trigger, slots?.trigger, className)}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon
+        render={
+          <HugeiconsIcon
+            icon={UnfoldMoreIcon}
+            strokeWidth={2}
+            className="text-muted-foreground size-4 pointer-events-none"
+          />
+        }
+      />
+    </SelectPrimitive.Trigger>
+  );
+}
+
+/** SelectContent — dropdown popup content for the select. */
+function SelectContent({
+  className,
+  children,
+  side = 'bottom',
+  sideOffset = 4,
+  align = 'center',
+  alignOffset = 0,
+  alignItemWithTrigger = true,
+  slots,
+  ...props
+}: ISelectContentProps) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        alignItemWithTrigger={alignItemWithTrigger}
+        className="isolate z-50"
+      >
+        <SelectPrimitive.Popup
+          data-slot="select-content"
+          data-align-trigger={alignItemWithTrigger}
+          className={cn(selectStyles.content, slots?.content, className)}
+          {...props}
+        >
+          <SelectScrollUpButton />
+          <SelectPrimitive.List>{children}</SelectPrimitive.List>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Popup>
+      </SelectPrimitive.Positioner>
+    </SelectPrimitive.Portal>
+  );
+}
+
+/** SelectLabel — label for a group of select items. */
+function SelectLabel({ className, ...props }: ISelectLabelProps) {
+  return (
+    <SelectPrimitive.GroupLabel
+      data-slot="select-label"
+      className={cn(selectStyles.label, className)}
+      {...props}
+    />
+  );
+}
+
+/** SelectItem — a single selectable option. */
+function SelectItem({ className, children, ...props }: ISelectItemProps) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(selectStyles.item, className)}
+      {...props}
+    >
+      <SelectPrimitive.ItemText className="flex flex-1 gap-2 shrink-0 whitespace-nowrap">
+        {children}
+      </SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="pointer-events-none" />
+      </SelectPrimitive.ItemIndicator>
+    </SelectPrimitive.Item>
+  );
+}
+
+/** SelectSeparator — visual divider between select items. */
+function SelectSeparator({ className, ...props }: ISelectSeparatorProps) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn(selectStyles.separator, className)}
+      {...props}
+    />
+  );
+}
+
+/** SelectScrollUpButton — scroll indicator for the top of the list. */
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpArrow>) {
+  return (
+    <SelectPrimitive.ScrollUpArrow
+      data-slot="select-scroll-up-button"
+      className={cn(selectStyles.scrollButton, 'top-0', className)}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowUp01Icon} strokeWidth={2} />
+    </SelectPrimitive.ScrollUpArrow>
+  );
+}
+
+/** SelectScrollDownButton — scroll indicator for the bottom of the list. */
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownArrow>) {
+  return (
+    <SelectPrimitive.ScrollDownArrow
+      data-slot="select-scroll-down-button"
+      className={cn(selectStyles.scrollButton, 'bottom-0', className)}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} />
+    </SelectPrimitive.ScrollDownArrow>
+  );
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+};
+
+export type {
+  ISelectProps,
+  ISelectGroupProps,
+  ISelectValueProps,
+  ISelectTriggerProps,
+  ISelectContentProps,
+  ISelectLabelProps,
+  ISelectItemProps,
+  ISelectSeparatorProps,
+} from './Select.types';
+
+export type { SelectSlot } from './Select.styles';

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

@@ -0,0 +1,10 @@
+import type { StyleSlots } from '@/core/types';
+
+type SeparatorSlot = 'root';
+
+const separatorStyles: StyleSlots<SeparatorSlot> = {
+  root: 'bg-border shrink-0 data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch',
+};
+
+export { separatorStyles };
+export type { SeparatorSlot };

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

@@ -0,0 +1,10 @@
+import type { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
+import type { SlotOverrides } from '@/core/types';
+import type { SeparatorSlot } from './Separator.styles';
+
+/** Props for the Separator component. */
+interface ISeparatorProps extends SeparatorPrimitive.Props {
+  slots?: SlotOverrides<SeparatorSlot>;
+}
+
+export type { ISeparatorProps };

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

@@ -0,0 +1,37 @@
+'use client';
+
+import { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
+
+import { cn } from '@/react/lib/utils';
+import { separatorStyles } from './Separator.styles';
+import type { ISeparatorProps } from './Separator.types';
+
+/**
+ * Separator — visual divider wrapping Base UI Separator.
+ *
+ * @param orientation - 'horizontal' or 'vertical'
+ *
+ * @example
+ * ```tsx
+ * <Separator orientation="horizontal" />
+ * ```
+ */
+function Separator({
+  className,
+  orientation = 'horizontal',
+  slots,
+  ...props
+}: ISeparatorProps) {
+  return (
+    <SeparatorPrimitive
+      data-slot="separator"
+      orientation={orientation}
+      className={cn(separatorStyles.root, slots?.root, className)}
+      {...props}
+    />
+  );
+}
+
+export { Separator };
+export type { ISeparatorProps } from './Separator.types';
+export type { SeparatorSlot } from './Separator.styles';

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

@@ -0,0 +1,50 @@
+/**
+ * Style slots and CVA variants for the Switch component.
+ *
+ * @module @mks2508/mks-ui/react/ui/Switch/Switch.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+
+import type { SwitchSlot } from './Switch.types';
+
+/**
+ * Default style slots for the Switch component.
+ * Each key maps to a visual region with its base Tailwind classes.
+ *
+ * - `root` - The outer switch track with rounded shape, background, and focus styles
+ * - `thumb` - The sliding thumb indicator with sizing and shape
+ * - `icon` - Icons positioned within the switch track or thumb
+ *
+ * @example
+ * ```typescript
+ * import { switchStyles } from './Switch.styles';
+ *
+ * // Access the root slot classes
+ * const rootClasses = switchStyles.root;
+ * // 'group inline-flex items-center ...'
+ * ```
+ */
+export const switchStyles: StyleSlots<SwitchSlot> = {
+  root: [
+    'group inline-flex items-center',
+    'h-6 w-11 shrink-0',
+    'cursor-pointer rounded-full',
+    'border-2 border-transparent',
+    'bg-input',
+    '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',
+  ].join(' '),
+  thumb: [
+    'pointer-events-none block',
+    'size-5 rounded-full',
+    'bg-background',
+    'shadow-lg ring-0',
+  ].join(' '),
+  icon: [
+    'pointer-events-none',
+    'flex items-center justify-center',
+  ].join(' '),
+};