@mks2508/mks-ui 0.1.4 → 0.2.0

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

@@ -0,0 +1,233 @@
+'use client';
+
+/**
+ * Checkbox component with animated SVG indicator.
+ *
+ * Built on Base UI Checkbox primitives with Motion animations for
+ * tap/hover interactions and an animated checkmark/indeterminate indicator.
+ *
+ * @module @mks2508/mks-ui/react/ui/Checkbox
+ *
+ * @example
+ * ```tsx
+ * import { Checkbox, CheckboxIndicator } from '@mks2508/mks-ui';
+ *
+ * function MyCheckbox() {
+ *   const [checked, setChecked] = useState(false);
+ *   return (
+ *     <Checkbox checked={checked} onCheckedChange={setChecked}>
+ *       <CheckboxIndicator />
+ *     </Checkbox>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';
+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 { checkboxStyles } from './Checkbox.styles';
+import type {
+  CheckboxContextType,
+  ICheckboxProps,
+  ICheckboxIndicatorProps,
+} from './Checkbox.types';
+
+const [CheckboxProvider, useCheckbox] =
+  getStrictContext<CheckboxContextType>('CheckboxContext');
+
+/**
+ * Checkbox root component with animated tap and hover interactions.
+ *
+ * Wraps Base UI `Checkbox.Root` with a `motion.button` render element,
+ * providing spring-based press and hover scale animations. Supports both
+ * controlled and uncontrolled checked state via `useControlledState`.
+ *
+ * @param props - Checkbox props including Base UI root props, motion props, slots, and config
+ * @returns A checkbox button element with animation support
+ *
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   checked={isChecked}
+ *   onCheckedChange={setIsChecked}
+ *   slots={{ root: 'border-2 border-cyan-500 rounded-md' }}
+ * >
+ *   <CheckboxIndicator />
+ * </Checkbox>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Indeterminate state
+ * <Checkbox indeterminate>
+ *   <CheckboxIndicator />
+ * </Checkbox>
+ * ```
+ */
+function Checkbox({
+  name,
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  indeterminate,
+  value,
+  nativeButton,
+  parent,
+  disabled,
+  readOnly,
+  required,
+  inputRef,
+  id,
+  className,
+  slots,
+  config,
+  ...props
+}: ICheckboxProps) {
+  const [isChecked, setIsChecked] = useControlledState({
+    value: checked,
+    defaultValue: defaultChecked,
+    onChange: onCheckedChange,
+  });
+
+  const tapScale = config?.tapScale ?? 0.95;
+  const hoverScale = config?.hoverScale ?? 1.05;
+
+  return (
+    <CheckboxProvider
+      value={{ isChecked, setIsChecked, isIndeterminate: indeterminate }}
+    >
+      <CheckboxPrimitive.Root
+        name={name}
+        defaultChecked={defaultChecked}
+        checked={checked}
+        onCheckedChange={setIsChecked}
+        indeterminate={indeterminate}
+        value={value}
+        nativeButton={nativeButton}
+        parent={parent}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        inputRef={inputRef}
+        id={id}
+        render={
+          <motion.button
+            data-slot="checkbox"
+            whileTap={{ scale: tapScale }}
+            whileHover={{ scale: hoverScale }}
+            className={cn(checkboxStyles.root, slots?.root, className)}
+            {...props}
+          />
+        }
+      />
+    </CheckboxProvider>
+  );
+}
+
+/**
+ * CheckboxIndicator renders an animated SVG checkmark or indeterminate line.
+ *
+ * Uses Motion `pathLength` and `opacity` variants for smooth check/uncheck
+ * transitions. Remains mounted (`keepMounted`) to enable exit animations.
+ *
+ * @param props - SVG motion props plus optional slot overrides
+ * @returns An animated SVG indicator element
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={isChecked} onCheckedChange={setIsChecked}>
+ *   <CheckboxIndicator className="size-4 text-white" />
+ * </Checkbox>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With slot overrides
+ * <CheckboxIndicator slots={{ indicator: 'size-3.5' }} />
+ * ```
+ */
+function CheckboxIndicator({ className, slots, ...props }: ICheckboxIndicatorProps) {
+  const { isChecked, isIndeterminate } = useCheckbox();
+
+  return (
+    <CheckboxPrimitive.Indicator
+      keepMounted
+      render={
+        <motion.svg
+          data-slot="checkbox-indicator"
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth="3.5"
+          stroke="currentColor"
+          initial="unchecked"
+          animate={isChecked ? 'checked' : 'unchecked'}
+          className={cn(checkboxStyles.indicator, slots?.indicator, className)}
+          {...props}
+        >
+          {isIndeterminate ? (
+            <motion.line
+              x1="5"
+              y1="12"
+              x2="19"
+              y2="12"
+              strokeLinecap="round"
+              initial={{ pathLength: 0, opacity: 0 }}
+              animate={{
+                pathLength: 1,
+                opacity: 1,
+                transition: { duration: 0.2 },
+              }}
+            />
+          ) : (
+            <motion.path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M4.5 12.75l6 6 9-13.5"
+              variants={{
+                checked: {
+                  pathLength: 1,
+                  opacity: 1,
+                  transition: {
+                    duration: 0.2,
+                    delay: 0.2,
+                  },
+                },
+                unchecked: {
+                  pathLength: 0,
+                  opacity: 0,
+                  transition: {
+                    duration: 0.2,
+                  },
+                },
+              }}
+            />
+          )}
+        </motion.svg>
+      }
+    />
+  );
+}
+
+export {
+  Checkbox,
+  CheckboxIndicator,
+  useCheckbox,
+};
+
+// Re-exports
+export type {
+  ICheckboxProps,
+  ICheckboxIndicatorProps,
+  ICheckboxConfig,
+  CheckboxContextType,
+  CheckboxSlot,
+} from './Checkbox.types';
+
+export { checkboxStyles } from './Checkbox.styles';

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

@@ -0,0 +1,34 @@
+import type { StyleSlots } from '@/core/types';
+
+/** Visual regions for the Combobox component family. */
+type ComboboxSlot =
+  | 'root'
+  | 'trigger'
+  | 'content'
+  | 'list'
+  | 'item'
+  | 'label'
+  | 'separator'
+  | 'empty'
+  | 'chips'
+  | 'chip'
+  | 'chipInput';
+
+const comboboxStyles: StyleSlots<ComboboxSlot> = {
+  root: '',
+  trigger: '[&_svg:not([class*=\'size-\'])]:size-4',
+  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 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:border-input/30 overflow-hidden rounded-lg shadow-md ring-1 duration-100 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:shadow-none data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 group/combobox-content relative max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) data-[chips=true]:min-w-(--anchor-width)',
+  list: 'no-scrollbar max-h-[min(calc(--spacing(72)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 p-1 data-empty:p-0 overflow-y-auto overscroll-contain',
+  item: 'data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground gap-2 rounded-md py-1 pr-8 pl-1.5 text-sm [&_svg:not([class*=\'size-\'])]:size-4 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-2 py-1.5 text-xs',
+  separator: 'bg-border -mx-1 my-1 h-px',
+  empty: 'text-muted-foreground hidden w-full justify-center py-2 text-center text-sm group-data-empty/combobox-content:flex',
+  chips:
+    'dark:bg-input/30 border-input focus-within:border-ring focus-within:ring-ring/50 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40 has-aria-invalid:border-destructive dark:has-aria-invalid:border-destructive/50 flex min-h-8 flex-wrap items-center gap-1 rounded-lg border bg-transparent bg-clip-padding px-2.5 py-1 text-sm transition-colors focus-within:ring-3 has-aria-invalid:ring-3 has-data-[slot=combobox-chip]:px-1',
+  chip: 'bg-muted text-foreground flex h-[calc(--spacing(5.25))] w-fit items-center justify-center gap-1 rounded-sm px-1.5 text-xs font-medium whitespace-nowrap has-data-[slot=combobox-chip-remove]:pr-0 has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50',
+  chipInput: 'min-w-16 flex-1 outline-none',
+};
+
+export { comboboxStyles };
+export type { ComboboxSlot };

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

@@ -0,0 +1,89 @@
+import type { Combobox as ComboboxPrimitive } from '@base-ui/react';
+import type { SlotOverrides } from '@/core/types';
+import type { ComboboxSlot } from './Combobox.styles';
+
+/** Props for the Combobox root. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IComboboxProps = ComboboxPrimitive.Root.Props<any, any>;
+
+/** Props for ComboboxValue. */
+type IComboboxValueProps = ComboboxPrimitive.Value.Props;
+
+/** Props for ComboboxTrigger. */
+type IComboboxTriggerProps = ComboboxPrimitive.Trigger.Props;
+
+/** Props for ComboboxClear. */
+type IComboboxClearProps = ComboboxPrimitive.Clear.Props;
+
+/** Props for ComboboxInput. */
+interface IComboboxInputProps extends ComboboxPrimitive.Input.Props {
+  /** Show the trigger arrow button. */
+  showTrigger?: boolean;
+  /** Show the clear button. */
+  showClear?: boolean;
+  /** Override classes for combobox visual regions. */
+  slots?: SlotOverrides<ComboboxSlot>;
+}
+
+/** Props for ComboboxContent. */
+interface IComboboxContentProps
+  extends ComboboxPrimitive.Popup.Props,
+    Pick<
+      ComboboxPrimitive.Positioner.Props,
+      'side' | 'align' | 'sideOffset' | 'alignOffset' | 'anchor'
+    > {
+  slots?: SlotOverrides<ComboboxSlot>;
+}
+
+/** Props for ComboboxList. */
+type IComboboxListProps = ComboboxPrimitive.List.Props;
+
+/** Props for ComboboxItem. */
+type IComboboxItemProps = ComboboxPrimitive.Item.Props;
+
+/** Props for ComboboxGroup. */
+type IComboboxGroupProps = ComboboxPrimitive.Group.Props;
+
+/** Props for ComboboxLabel. */
+type IComboboxLabelProps = ComboboxPrimitive.GroupLabel.Props;
+
+/** Props for ComboboxCollection. */
+type IComboboxCollectionProps = ComboboxPrimitive.Collection.Props;
+
+/** Props for ComboboxEmpty. */
+type IComboboxEmptyProps = ComboboxPrimitive.Empty.Props;
+
+/** Props for ComboboxSeparator. */
+type IComboboxSeparatorProps = ComboboxPrimitive.Separator.Props;
+
+/** Props for ComboboxChips. */
+type IComboboxChipsProps = React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips> &
+  ComboboxPrimitive.Chips.Props;
+
+/** Props for ComboboxChip. */
+interface IComboboxChipProps extends ComboboxPrimitive.Chip.Props {
+  /** Show the remove button on the chip. */
+  showRemove?: boolean;
+}
+
+/** Props for ComboboxChipsInput. */
+type IComboboxChipsInputProps = ComboboxPrimitive.Input.Props;
+
+export type {
+  IComboboxProps,
+  IComboboxValueProps,
+  IComboboxTriggerProps,
+  IComboboxClearProps,
+  IComboboxInputProps,
+  IComboboxContentProps,
+  IComboboxListProps,
+  IComboboxItemProps,
+  IComboboxGroupProps,
+  IComboboxLabelProps,
+  IComboboxCollectionProps,
+  IComboboxEmptyProps,
+  IComboboxSeparatorProps,
+  IComboboxChipsProps,
+  IComboboxChipProps,
+  IComboboxChipsInputProps,
+};

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

@@ -0,0 +1,331 @@
+import * as React from 'react';
+import { Combobox as ComboboxPrimitive } from '@base-ui/react';
+
+import { cn } from '@/react/lib/utils';
+import { Button } from '@/react/ui/Button';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from '@/react/ui/InputGroup';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { ArrowDown01Icon, Cancel01Icon, Tick02Icon } from '@hugeicons/core-free-icons';
+import { comboboxStyles } from './Combobox.styles';
+import type {
+  IComboboxTriggerProps,
+  IComboboxClearProps,
+  IComboboxInputProps,
+  IComboboxContentProps,
+  IComboboxListProps,
+  IComboboxItemProps,
+  IComboboxGroupProps,
+  IComboboxLabelProps,
+  IComboboxCollectionProps,
+  IComboboxEmptyProps,
+  IComboboxSeparatorProps,
+  IComboboxChipsProps,
+  IComboboxChipProps,
+  IComboboxChipsInputProps,
+  IComboboxValueProps,
+} from './Combobox.types';
+
+/** Combobox — root component wrapping Base UI Combobox. */
+const Combobox = ComboboxPrimitive.Root;
+
+/** ComboboxValue — displays the selected value. */
+function ComboboxValue({ ...props }: IComboboxValueProps) {
+  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />;
+}
+
+/** ComboboxTrigger — trigger button with arrow icon. */
+function ComboboxTrigger({ className, children, ...props }: IComboboxTriggerProps) {
+  return (
+    <ComboboxPrimitive.Trigger
+      data-slot="combobox-trigger"
+      className={cn(comboboxStyles.trigger, className)}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon
+        icon={ArrowDown01Icon}
+        strokeWidth={2}
+        className="text-muted-foreground size-4 pointer-events-none"
+      />
+    </ComboboxPrimitive.Trigger>
+  );
+}
+
+/** ComboboxClear — clears the combobox selection. */
+function ComboboxClear({ className, ...props }: IComboboxClearProps) {
+  return (
+    <ComboboxPrimitive.Clear
+      data-slot="combobox-clear"
+      render={<InputGroupButton size="icon-xs" />}
+      className={cn(className)}
+      {...props}
+    >
+      <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="pointer-events-none" />
+    </ComboboxPrimitive.Clear>
+  );
+}
+
+/**
+ * ComboboxInput — text input with optional trigger and clear buttons.
+ *
+ * @param showTrigger - Show dropdown arrow button
+ * @param showClear - Show clear button
+ *
+ * @example
+ * ```tsx
+ * <Combobox>
+ *   <ComboboxInput showClear placeholder="Search..." />
+ *   <ComboboxContent>
+ *     <ComboboxList>
+ *       <ComboboxItem>Option 1</ComboboxItem>
+ *     </ComboboxList>
+ *   </ComboboxContent>
+ * </Combobox>
+ * ```
+ */
+function ComboboxInput({
+  className,
+  children,
+  disabled = false,
+  showTrigger = true,
+  showClear = false,
+  ...props
+}: IComboboxInputProps) {
+  return (
+    <InputGroup className={cn('w-auto', className)}>
+      <ComboboxPrimitive.Input
+        render={<InputGroupInput disabled={disabled} />}
+        {...props}
+      />
+      <InputGroupAddon align="inline-end">
+        {showTrigger && (
+          <InputGroupButton
+            size="icon-xs"
+            data-slot="input-group-button"
+            className="group-has-data-[slot=combobox-clear]/input-group:hidden data-pressed:bg-transparent"
+            disabled={disabled}
+          >
+            <ComboboxTrigger />
+          </InputGroupButton>
+        )}
+        {showClear && <ComboboxClear disabled={disabled} />}
+      </InputGroupAddon>
+      {children}
+    </InputGroup>
+  );
+}
+
+/** ComboboxContent — popup content area for the combobox. */
+function ComboboxContent({
+  className,
+  side = 'bottom',
+  sideOffset = 6,
+  align = 'start',
+  alignOffset = 0,
+  anchor,
+  slots,
+  ...props
+}: IComboboxContentProps) {
+  return (
+    <ComboboxPrimitive.Portal>
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="isolate z-50"
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          data-chips={!!anchor}
+          className={cn(comboboxStyles.content, slots?.content, className)}
+          {...props}
+        />
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  );
+}
+
+/** ComboboxList — scrollable list of combobox items. */
+function ComboboxList({ className, ...props }: IComboboxListProps) {
+  return (
+    <ComboboxPrimitive.List
+      data-slot="combobox-list"
+      className={cn(comboboxStyles.list, className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxItem — a single selectable item with check indicator. */
+function ComboboxItem({ className, children, ...props }: IComboboxItemProps) {
+  return (
+    <ComboboxPrimitive.Item
+      data-slot="combobox-item"
+      className={cn(comboboxStyles.item, className)}
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.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" />
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  );
+}
+
+/** ComboboxGroup — groups related combobox items. */
+function ComboboxGroup({ className, ...props }: IComboboxGroupProps) {
+  return (
+    <ComboboxPrimitive.Group
+      data-slot="combobox-group"
+      className={cn(className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxLabel — label for a group of combobox items. */
+function ComboboxLabel({ className, ...props }: IComboboxLabelProps) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="combobox-label"
+      className={cn(comboboxStyles.label, className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxCollection — collection for combobox items. */
+function ComboboxCollection({ ...props }: IComboboxCollectionProps) {
+  return <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />;
+}
+
+/** ComboboxEmpty — displayed when no items match the query. */
+function ComboboxEmpty({ className, ...props }: IComboboxEmptyProps) {
+  return (
+    <ComboboxPrimitive.Empty
+      data-slot="combobox-empty"
+      className={cn(comboboxStyles.empty, className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxSeparator — visual divider between combobox items. */
+function ComboboxSeparator({ className, ...props }: IComboboxSeparatorProps) {
+  return (
+    <ComboboxPrimitive.Separator
+      data-slot="combobox-separator"
+      className={cn(comboboxStyles.separator, className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxChips — container for multi-select chips. */
+function ComboboxChips({ className, ...props }: IComboboxChipsProps) {
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="combobox-chips"
+      className={cn(comboboxStyles.chips, className)}
+      {...props}
+    />
+  );
+}
+
+/** ComboboxChip — individual chip with optional remove button. */
+function ComboboxChip({
+  className,
+  children,
+  showRemove = true,
+  ...props
+}: IComboboxChipProps) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(comboboxStyles.chip, className)}
+      {...props}
+    >
+      {children}
+      {showRemove && (
+        <ComboboxPrimitive.ChipRemove
+          render={<Button variant="ghost" size="sm" className="h-5 w-5 p-0" />}
+          className="-ml-1 opacity-50 hover:opacity-100"
+          data-slot="combobox-chip-remove"
+        >
+          <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="pointer-events-none" />
+        </ComboboxPrimitive.ChipRemove>
+      )}
+    </ComboboxPrimitive.Chip>
+  );
+}
+
+/** ComboboxChipsInput — input within the chips container for multi-select. */
+function ComboboxChipsInput({ className, ...props }: IComboboxChipsInputProps) {
+  return (
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chip-input"
+      className={cn(comboboxStyles.chipInput, className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Hook to create an anchor ref for the combobox chips.
+ *
+ * @returns A ref to be used as the anchor for ComboboxContent
+ */
+function useComboboxAnchor() {
+  return React.useRef<HTMLDivElement | null>(null);
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxCollection,
+  ComboboxEmpty,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  useComboboxAnchor,
+};
+
+export type {
+  IComboboxProps,
+  IComboboxValueProps,
+  IComboboxTriggerProps,
+  IComboboxClearProps,
+  IComboboxInputProps,
+  IComboboxContentProps,
+  IComboboxListProps,
+  IComboboxItemProps,
+  IComboboxGroupProps,
+  IComboboxLabelProps,
+  IComboboxCollectionProps,
+  IComboboxEmptyProps,
+  IComboboxSeparatorProps,
+  IComboboxChipsProps,
+  IComboboxChipProps,
+  IComboboxChipsInputProps,
+} from './Combobox.types';
+
+export type { ComboboxSlot } from './Combobox.styles';