@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/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-ui/lib/utils';
+import { getStrictContext } from '@/react-ui/lib/get-strict-context';
+import { CountingNumber } from '@/react-ui/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/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-ui/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/ui/Separator/index.tsx

@@ -0,0 +1,37 @@
+'use client';
+
+import { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
+
+import { cn } from '@/react-ui/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';