@djangocfg/ui-nextjs 1.4.45

package/src/components/multi-select-pro/async.tsx

@@ -0,0 +1,608 @@
+/**
+ * MultiSelectProAsync - Extended MultiSelectPro with async search support
+ *
+ * Based on MultiSelectPro with added features:
+ * - Async search through external API
+ * - Debounced search queries
+ * - Loading states
+ * - Controlled search value from parent
+ *
+ * All original MultiSelectPro features preserved:
+ * - Animations, variants, responsive, groups, etc.
+ */
+
+"use client"
+
+import * as React from "react"
+import { Check, ChevronsUpDown, X, XCircle, Loader2 } from "lucide-react"
+import { cva } from "class-variance-authority"
+import { cn } from "@djangocfg/ui-core/lib"
+import {
+  Button,
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Badge,
+  Separator,
+} from "@djangocfg/ui-core/components"
+
+// ==================== TYPES ====================
+
+export interface MultiSelectProAsyncOption {
+  label: string
+  value: string
+  description?: string  // Optional subtitle/description text shown below label
+  icon?: React.ComponentType<{ className?: string }>
+  disabled?: boolean
+  style?: {
+    badgeColor?: string
+    iconColor?: string
+    gradient?: string
+  }
+}
+
+export interface MultiSelectProAsyncGroup {
+  heading: string
+  options: MultiSelectProAsyncOption[]
+}
+
+export interface AnimationConfig {
+  badgeAnimation?: "bounce" | "pulse" | "wiggle" | "fade" | "slide" | "none"
+  popoverAnimation?: "scale" | "slide" | "fade" | "flip" | "none"
+  optionHoverAnimation?: "highlight" | "scale" | "glow" | "none"
+  duration?: number
+  delay?: number
+}
+
+export interface MultiSelectProAsyncRef {
+  reset: () => void
+  getSelectedValues: () => string[]
+  setSelectedValues: (values: string[]) => void
+  clear: () => void
+  focus: () => void
+}
+
+export interface MultiSelectProAsyncProps {
+  // Options from API
+  options: MultiSelectProAsyncOption[] | MultiSelectProAsyncGroup[]
+
+  // Selection
+  onValueChange?: (value: string[]) => void
+  defaultValue?: string[]
+
+  // Async Search
+  searchValue: string
+  onSearchChange: (value: string) => void
+  isLoading?: boolean
+
+  // UI
+  placeholder?: string
+  searchPlaceholder?: string
+  emptyText?: string
+  loadingText?: string
+  variant?: "default" | "secondary" | "destructive" | "inverted"
+  animation?: number
+  animationConfig?: AnimationConfig
+  maxCount?: number
+  modalPopover?: boolean
+  className?: string
+  popoverClassName?: string
+  disabled?: boolean
+
+  // Behavior
+  hideSelectAll?: boolean
+  searchable?: boolean
+  closeOnSelect?: boolean
+  resetOnDefaultValueChange?: boolean
+
+  // Advanced
+  autoSize?: boolean
+  singleLine?: boolean
+  minWidth?: string
+  maxWidth?: string
+  deduplicateOptions?: boolean
+}
+
+// ==================== VARIANTS ====================
+
+const multiSelectVariants = cva(
+  "w-full justify-between min-h-10 h-auto py-2",
+  {
+    variants: {
+      variant: {
+        default: "border-input bg-background hover:bg-accent/50",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        inverted: "bg-primary text-primary-foreground hover:bg-primary/90",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+const badgeAnimations = {
+  bounce: "animate-bounce",
+  pulse: "animate-pulse",
+  wiggle: "animate-wiggle",
+  fade: "animate-fadeIn",
+  slide: "animate-slideIn",
+  none: "",
+}
+
+const popoverAnimations = {
+  scale: "data-[state=open]:animate-scaleIn data-[state=closed]:animate-scaleOut",
+  slide: "data-[state=open]:animate-slideDown data-[state=closed]:animate-slideUp",
+  fade: "data-[state=open]:animate-fadeIn data-[state=closed]:animate-fadeOut",
+  flip: "data-[state=open]:animate-flipIn data-[state=closed]:animate-flipOut",
+  none: "",
+}
+
+// ==================== HELPERS ====================
+
+function isGroupedOptions(options: MultiSelectProAsyncOption[] | MultiSelectProAsyncGroup[]): options is MultiSelectProAsyncGroup[] {
+  return options.length > 0 && 'heading' in options[0]
+}
+
+function flattenOptions(options: MultiSelectProAsyncOption[] | MultiSelectProAsyncGroup[]): MultiSelectProAsyncOption[] {
+  if (isGroupedOptions(options)) {
+    return options.flatMap((group) => group.options)
+  }
+  return options
+}
+
+function deduplicateOptions(options: MultiSelectProAsyncOption[]): MultiSelectProAsyncOption[] {
+  const seen = new Set<string>()
+  return options.filter((option) => {
+    if (seen.has(option.value)) {
+      return false
+    }
+    seen.add(option.value)
+    return true
+  })
+}
+
+// ==================== COMPONENT ====================
+
+export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, MultiSelectProAsyncProps>(
+  (
+    {
+      options,
+      onValueChange,
+      defaultValue = [],
+      searchValue,
+      onSearchChange,
+      isLoading = false,
+      placeholder = "Select options",
+      searchPlaceholder = "Search...",
+      emptyText = "No results found.",
+      loadingText = "Loading...",
+      variant = "default",
+      animation = 0,
+      animationConfig,
+      maxCount = 3,
+      modalPopover = false,
+      className,
+      popoverClassName,
+      disabled = false,
+      hideSelectAll = false,
+      searchable = true,
+      closeOnSelect = false,
+      resetOnDefaultValueChange = true,
+      autoSize = false,
+      singleLine = false,
+      minWidth,
+      maxWidth,
+      deduplicateOptions: shouldDeduplicate = false,
+    },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+    const [selectedValues, setSelectedValues] = React.useState<string[]>(defaultValue)
+    const buttonRef = React.useRef<HTMLButtonElement>(null)
+    const [announcements, setAnnouncements] = React.useState<string>("")
+    // Cache selected options to persist them when they disappear from current options
+    const [selectedOptionsCache, setSelectedOptionsCache] = React.useState<Map<string, MultiSelectProAsyncOption>>(new Map())
+
+    // Process options
+    const flatOptions = React.useMemo(() => {
+      const flat = flattenOptions(options)
+      return shouldDeduplicate ? deduplicateOptions(flat) : flat
+    }, [options, shouldDeduplicate])
+
+    // Update cache whenever new options appear
+    React.useEffect(() => {
+      setSelectedOptionsCache(prev => {
+        const updated = new Map(prev)
+        flatOptions.forEach(option => {
+          if (selectedValues.includes(option.value)) {
+            updated.set(option.value, option)
+          }
+        })
+        return updated
+      })
+    }, [flatOptions, selectedValues])
+
+    // Animation configuration
+    const animConfig = React.useMemo(
+      (): AnimationConfig => ({
+        badgeAnimation: animationConfig?.badgeAnimation || (animation > 0 ? "bounce" : "none"),
+        popoverAnimation: animationConfig?.popoverAnimation || "scale",
+        optionHoverAnimation: animationConfig?.optionHoverAnimation || "highlight",
+        duration: animationConfig?.duration || animation || 0.3,
+        delay: animationConfig?.delay || 0,
+      }),
+      [animation, animationConfig]
+    )
+
+    // Reset on defaultValue change
+    React.useEffect(() => {
+      if (resetOnDefaultValueChange) {
+        setSelectedValues(defaultValue)
+      }
+    }, [JSON.stringify(defaultValue), resetOnDefaultValueChange])
+
+    // Announce changes for screen readers
+    const announce = React.useCallback((message: string) => {
+      setAnnouncements(message)
+      setTimeout(() => setAnnouncements(""), 1000)
+    }, [])
+
+    // Toggle selection
+    const toggleOption = React.useCallback(
+      (value: string) => {
+        const isRemoving = selectedValues.includes(value)
+        const newValues = isRemoving
+          ? selectedValues.filter((v) => v !== value)
+          : [...selectedValues, value]
+
+        setSelectedValues(newValues)
+        onValueChange?.(newValues)
+
+        const option = flatOptions.find((o) => o.value === value)
+        if (option) {
+          // Add to cache when selecting
+          if (!isRemoving) {
+            setSelectedOptionsCache(prev => new Map(prev).set(value, option))
+          }
+
+          announce(
+            isRemoving
+              ? `Removed ${option.label}`
+              : `Added ${option.label}`
+          )
+        }
+
+        if (closeOnSelect) {
+          setOpen(false)
+        }
+      },
+      [selectedValues, onValueChange, flatOptions, announce, closeOnSelect]
+    )
+
+    // Select all
+    const handleSelectAll = React.useCallback(() => {
+      const allValues = flatOptions.filter((o) => !o.disabled).map((o) => o.value)
+      setSelectedValues(allValues)
+      onValueChange?.(allValues)
+
+      // Cache all selected options
+      setSelectedOptionsCache(prev => {
+        const updated = new Map(prev)
+        flatOptions.forEach(option => {
+          if (!option.disabled) {
+            updated.set(option.value, option)
+          }
+        })
+        return updated
+      })
+
+      announce(`Selected all ${allValues.length} options`)
+    }, [flatOptions, onValueChange, announce])
+
+    // Clear all
+    const handleClearAll = React.useCallback(() => {
+      setSelectedValues([])
+      onValueChange?.([])
+      announce("Cleared all selections")
+    }, [onValueChange, announce])
+
+    // Imperative methods
+    React.useImperativeHandle(ref, () => ({
+      reset: () => {
+        setSelectedValues(defaultValue)
+        announce("Reset to default values")
+      },
+      getSelectedValues: () => selectedValues,
+      setSelectedValues: (values: string[]) => {
+        setSelectedValues(values)
+        onValueChange?.(values)
+      },
+      clear: handleClearAll,
+      focus: () => buttonRef.current?.focus(),
+    }))
+
+    // Selected options for display - use cache as fallback
+    const selectedOptions = React.useMemo(
+      () => selectedValues.map(value => {
+        // First try to find in current options
+        const option = flatOptions.find(o => o.value === value)
+        // If not found, fallback to cache
+        return option || selectedOptionsCache.get(value)
+      }).filter((option): option is MultiSelectProAsyncOption => option !== undefined),
+      [flatOptions, selectedValues, selectedOptionsCache]
+    )
+
+    // Render badge with custom styles
+    const renderBadge = (option: MultiSelectProAsyncOption, index: number) => {
+      const { style, icon: Icon } = option
+      const badgeStyle: React.CSSProperties = {}
+
+      if (style?.gradient) {
+        badgeStyle.background = style.gradient
+        badgeStyle.color = style.iconColor || "white"
+      } else if (style?.badgeColor) {
+        badgeStyle.backgroundColor = style.badgeColor
+        badgeStyle.color = style.iconColor || "white"
+      }
+
+      const animationClass = animConfig.badgeAnimation
+        ? badgeAnimations[animConfig.badgeAnimation]
+        : ""
+
+      return (
+        <Badge
+          key={option.value}
+          variant={variant === "default" ? "secondary" : "outline"}
+          className={cn(
+            "mr-1 mb-1 text-xs gap-1 flex items-center",
+            animationClass
+          )}
+          style={{
+            ...badgeStyle,
+            animationDelay: `${(animConfig.delay || 0) * index}s`,
+            animationDuration: `${animConfig.duration}s`,
+          }}
+        >
+          {Icon && <Icon className="h-3 w-3" />}
+          <span>{option.label}</span>
+          {!disabled && (
+            <button
+              className="ml-1 rounded-full hover:bg-muted-foreground/20 focus:outline-none focus:ring-2 focus:ring-ring"
+              onClick={(e) => {
+                e.stopPropagation()
+                toggleOption(option.value)
+              }}
+              aria-label={`Remove ${option.label}`}
+            >
+              <X className="h-3 w-3" />
+            </button>
+          )}
+        </Badge>
+      )
+    }
+
+    // Display value
+    const displayValue = React.useMemo(() => {
+      if (selectedOptions.length === 0) {
+        return <span className="text-muted-foreground">{placeholder}</span>
+      }
+
+      const displayed = selectedOptions.slice(0, maxCount)
+      const remaining = selectedOptions.length - maxCount
+
+      return (
+        <div className={cn("flex gap-1", singleLine ? "flex-nowrap overflow-x-auto" : "flex-wrap")}>
+          {displayed.map((option, index) => renderBadge(option, index))}
+          {remaining > 0 && (
+            <Badge variant="outline" className="text-xs">
+              +{remaining} more
+            </Badge>
+          )}
+        </div>
+      )
+    }, [selectedOptions, maxCount, placeholder, singleLine, variant, disabled, animConfig])
+
+    // Render options
+    const renderOptions = () => {
+      if (isGroupedOptions(options)) {
+        return options.map((group, groupIndex) => (
+          <React.Fragment key={group.heading}>
+            {groupIndex > 0 && <CommandSeparator />}
+            <CommandGroup heading={group.heading}>
+              {group.options.map((option) => {
+                const isSelected = selectedValues.includes(option.value)
+                const Icon = option.icon
+
+                return (
+                  <CommandItem
+                    key={option.value}
+                    value={option.value}
+                    onSelect={() => !option.disabled && toggleOption(option.value)}
+                    disabled={option.disabled}
+                    className={cn(
+                      "cursor-pointer",
+                      option.disabled && "opacity-50 cursor-not-allowed"
+                    )}
+                  >
+                    <Check
+                      className={cn(
+                        "mr-2 h-4 w-4 shrink-0",
+                        isSelected ? "opacity-100" : "opacity-0"
+                      )}
+                    />
+                    {Icon && <Icon className="mr-2 h-4 w-4" />}
+                    <div className="flex-1 flex flex-col gap-0.5">
+                      <span>{option.label}</span>
+                      {option.description && (
+                        <span className="text-xs text-muted-foreground">{option.description}</span>
+                      )}
+                    </div>
+                  </CommandItem>
+                )
+              })}
+            </CommandGroup>
+          </React.Fragment>
+        ))
+      }
+
+      return (
+        <CommandGroup>
+          {(options as MultiSelectProAsyncOption[]).map((option) => {
+            const isSelected = selectedValues.includes(option.value)
+            const Icon = option.icon
+
+            return (
+              <CommandItem
+                key={option.value}
+                value={option.value}
+                onSelect={() => !option.disabled && toggleOption(option.value)}
+                disabled={option.disabled}
+                className={cn(
+                  "cursor-pointer",
+                  option.disabled && "opacity-50 cursor-not-allowed"
+                )}
+              >
+                <Check
+                  className={cn(
+                    "mr-2 h-4 w-4 shrink-0",
+                    isSelected ? "opacity-100" : "opacity-0"
+                  )}
+                />
+                {Icon && <Icon className="mr-2 h-4 w-4" />}
+                <div className="flex-1 flex flex-col gap-0.5">
+                  <span>{option.label}</span>
+                  {option.description && (
+                    <span className="text-xs text-muted-foreground">{option.description}</span>
+                  )}
+                </div>
+              </CommandItem>
+            )
+          })}
+        </CommandGroup>
+      )
+    }
+
+    const containerStyle: React.CSSProperties = {}
+    if (minWidth) containerStyle.minWidth = minWidth
+    if (maxWidth) containerStyle.maxWidth = maxWidth
+
+    return (
+      <div style={containerStyle} className="relative">
+        {/* ARIA Live Region for announcements */}
+        <div
+          role="status"
+          aria-live="polite"
+          aria-atomic="true"
+          className="sr-only"
+        >
+          {announcements}
+        </div>
+
+        <Popover
+          open={open}
+          onOpenChange={(isOpen) => {
+            if (!disabled) {
+              setOpen(isOpen)
+              if (isOpen) {
+                announce(`Dropdown opened. ${flatOptions.length} options available`)
+              } else {
+                onSearchChange("") // Clear search when closing
+                announce("Dropdown closed")
+              }
+            }
+          }}
+          modal={modalPopover}
+        >
+          <PopoverTrigger asChild>
+            <Button
+              ref={buttonRef}
+              variant="outline"
+              role="combobox"
+              aria-expanded={open}
+              aria-label={placeholder}
+              className={cn(multiSelectVariants({ variant }), className)}
+              disabled={disabled}
+            >
+              <div className={cn("flex-1 text-left", autoSize ? "" : "overflow-hidden")}>
+                {displayValue}
+              </div>
+              <div className="flex items-center gap-1 ml-2">
+                {selectedValues.length > 0 && !disabled && (
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      handleClearAll()
+                    }}
+                    className="rounded-full hover:bg-muted-foreground/20 focus:outline-none focus:ring-2 focus:ring-ring"
+                    aria-label="Clear all selections"
+                  >
+                    <XCircle className="h-4 w-4 shrink-0 opacity-50" />
+                  </button>
+                )}
+                <ChevronsUpDown className="h-4 w-4 shrink-0 opacity-50" />
+              </div>
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent
+            className={cn(
+              "w-[var(--radix-popover-trigger-width)] p-0",
+              animConfig.popoverAnimation ? popoverAnimations[animConfig.popoverAnimation] : "",
+              popoverClassName
+            )}
+            align="start"
+            style={{
+              animationDuration: `${animConfig.duration}s`,
+            }}
+          >
+            <Command shouldFilter={false}>
+              {searchable && (
+                <CommandInput
+                  placeholder={searchPlaceholder}
+                  value={searchValue}
+                  onValueChange={onSearchChange}
+                />
+              )}
+              <CommandList>
+                {!hideSelectAll && !isGroupedOptions(options) && (
+                  <>
+                    <CommandGroup>
+                      <CommandItem
+                        onSelect={handleSelectAll}
+                        className="cursor-pointer justify-center font-medium"
+                      >
+                        Select All
+                      </CommandItem>
+                    </CommandGroup>
+                    <Separator />
+                  </>
+                )}
+
+                {isLoading ? (
+                  <div className="py-6 text-center text-sm">
+                    <Loader2 className="h-4 w-4 animate-spin mx-auto mb-2" />
+                    {loadingText}
+                  </div>
+                ) : options.length === 0 ? (
+                  <CommandEmpty>{emptyText}</CommandEmpty>
+                ) : (
+                  renderOptions()
+                )}
+              </CommandList>
+            </Command>
+          </PopoverContent>
+        </Popover>
+      </div>
+    )
+  }
+)
+
+MultiSelectProAsync.displayName = "MultiSelectProAsync"

package/src/components/multi-select-pro/helpers.tsx

@@ -0,0 +1,84 @@
+/**
+ * Helper utilities for MultiSelectPro components
+ */
+
+import type { MultiSelectProOption } from './index'
+import type { MultiSelectProAsyncOption } from './async'
+
+// ==================== TYPES ====================
+
+/**
+ * Generic option builder config
+ */
+export interface OptionBuilderConfig<T = any> {
+  /** Extract unique ID/value from item */
+  getValue: (item: T) => string
+  /** Extract main label text */
+  getLabel: (item: T) => string
+  /** Optional: Extract description/subtitle text */
+  getDescription?: (item: T) => string | undefined
+  /** Optional: Check if item is disabled */
+  isDisabled?: (item: T) => boolean
+  /** Optional: Custom icon component */
+  getIcon?: (item: T) => React.ComponentType<{ className?: string }> | undefined
+  /** Optional: Custom styling */
+  getStyle?: (item: T) => {
+    badgeColor?: string
+    iconColor?: string
+    gradient?: string
+  } | undefined
+}
+
+// ==================== HELPERS ====================
+
+/**
+ * Generic option builder for MultiSelectPro components
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * const options = items.map(createOption({
+ *   getValue: (item) => item.id,
+ *   getLabel: (item) => item.name,
+ * }))
+ *
+ * // With description
+ * const options = channels.map(createOption({
+ *   getValue: (ch) => ch.id,
+ *   getLabel: (ch) => ch.title,
+ *   getDescription: (ch) => `📱 ${ch.phone}`,
+ * }))
+ * ```
+ */
+export function createOption<T>(
+  config: OptionBuilderConfig<T>
+): (item: T) => MultiSelectProOption | MultiSelectProAsyncOption {
+  return (item: T) => ({
+    value: config.getValue(item),
+    label: config.getLabel(item),
+    description: config.getDescription?.(item),
+    disabled: config.isDisabled?.(item) ?? false,
+    icon: config.getIcon?.(item),
+    style: config.getStyle?.(item),
+  })
+}
+
+/**
+ * Batch create options from array
+ *
+ * @example
+ * ```tsx
+ * const options = createOptions(channels, {
+ *   getValue: (ch) => ch.id,
+ *   getLabel: (ch) => ch.title,
+ *   getDescription: (ch) => ch.phone,
+ * })
+ * ```
+ */
+export function createOptions<T>(
+  items: T[],
+  config: OptionBuilderConfig<T>
+): (MultiSelectProOption | MultiSelectProAsyncOption)[] {
+  const builder = createOption(config)
+  return items.map(builder)
+}