@turtleclub/ui 0.3.0-beta.8 → 0.3.0

package/src/components/ui/collapsible.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import React from "react";
+import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
+
+function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
+}
+
+function CollapsibleTrigger({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+  return <CollapsiblePrimitive.CollapsibleTrigger data-slot="collapsible-trigger" {...props} />;
+}
+
+function CollapsibleContent({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+  return <CollapsiblePrimitive.CollapsibleContent data-slot="collapsible-content" {...props} />;
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/src/components/ui/combobox.tsx

@@ -0,0 +1,617 @@
+import * as React from "react";
+import { CheckIcon, ChevronDown, WandSparkles, XIcon } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Separator } from "@/components/ui/separator";
+import { Button } from "@/components/ui/button";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+
+/**
+ * Option interface for Combobox component
+ */
+interface ComboboxOption {
+  /** The text to display for the option. */
+  label: string;
+  /** The unique value associated with the option. */
+  value: string;
+  /** Optional icon component to display alongside the option. */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Whether this option is disabled */
+  disabled?: boolean;
+  /** Custom styling for the option */
+}
+
+/**
+ * Props for Combobox component
+ */
+interface ComboboxProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "animationConfig"> {
+  /**
+   * An array of option objects or groups to be displayed in the multi-select component.
+   */
+  options: ComboboxOption[];
+  /**
+   * Callback function triggered when the selected values change.
+   * Receives an array of the new selected values.
+   */
+  onValueChange: (value: string) => void;
+
+  /** The default selected values when the component mounts. */
+  defaultValue?: string;
+
+  /**
+   * Placeholder text to be displayed when no values are selected.
+   * Optional, defaults to "Select options".
+   */
+  placeholder?: string;
+
+  /**
+   * Animation duration in seconds for the visual effects (e.g., bouncing badges).
+   * Optional, defaults to 0 (no animation).
+   */
+  animation?: number;
+
+  /**
+   * The modality of the popover. When set to true, interaction with outside elements
+   * will be disabled and only popover content will be visible to screen readers.
+   * Optional, defaults to false.
+   */
+  modalPopover?: boolean;
+
+  /**
+   * If true, renders the multi-select component as a child of another component.
+   * Optional, defaults to false.
+   */
+  asChild?: boolean;
+
+  /**
+   * Additional class names to apply custom styles to the multi-select component.
+   * Optional, can be used to add custom styles.
+   */
+  className?: string;
+
+  /**
+   * If true, shows search functionality in the popover.
+   * If false, hides the search input completely.
+   * Optional, defaults to true.
+   */
+  searchable?: boolean;
+
+  /**
+   * Custom empty state message when no options match search.
+   * Optional, defaults to "No results found."
+   */
+  emptyIndicator?: React.ReactNode;
+
+  /**
+   * If true, allows the component to grow and shrink with its content.
+   * If false, uses fixed width behavior.
+   * Optional, defaults to false.
+   */
+  autoSize?: boolean;
+
+  /**
+   * Custom CSS class for the popover content.
+   * Optional, can be used to customize popover appearance.
+   */
+  popoverClassName?: string;
+
+  /**
+   * If true, disables the component completely.
+   * Optional, defaults to false.
+   */
+  disabled?: boolean;
+
+  /**
+   * Responsive configuration for different screen sizes.
+   * Allows customizing maxCount and other properties based on viewport.
+   * Can be boolean true for default responsive behavior or an object for custom configuration.
+   */
+  responsive?:
+    | boolean
+    | {
+        /** Configuration for mobile devices (< 640px) */
+        mobile?: {
+          maxCount?: number;
+          hideIcons?: boolean;
+          compactMode?: boolean;
+        };
+        /** Configuration for tablet devices (640px - 1024px) */
+        tablet?: {
+          maxCount?: number;
+          hideIcons?: boolean;
+          compactMode?: boolean;
+        };
+        /** Configuration for desktop devices (> 1024px) */
+        desktop?: {
+          maxCount?: number;
+          hideIcons?: boolean;
+          compactMode?: boolean;
+        };
+      };
+
+  /**
+   * Minimum width for the component.
+   * Optional, defaults to auto-sizing based on content.
+   * When set, component will not shrink below this width.
+   */
+  minWidth?: string;
+
+  /**
+   * Maximum width for the component.
+   * Optional, defaults to 100% of container.
+   * Component will not exceed container boundaries.
+   */
+  maxWidth?: string;
+
+  /**
+   * If true, automatically closes the popover after selecting an option.
+   * Useful for single-selection-like behavior or mobile UX.
+   * Optional, defaults to false.
+   */
+  closeOnSelect?: boolean;
+}
+
+/**
+ * Imperative methods exposed through ref
+ */
+export interface ComboboxRef {
+  /**
+   * Programmatically reset the component to its default value
+   */
+  reset: () => void;
+  /**
+   * Clear all selected values
+   */
+  clear: () => void;
+  /**
+   * Focus the component
+   */
+  focus: () => void;
+}
+
+export const Combobox = React.forwardRef<ComboboxRef, ComboboxProps>(
+  (
+    {
+      options,
+      onValueChange,
+      defaultValue = "",
+      placeholder = "Select option",
+      animation = 0,
+      modalPopover = false,
+      className,
+      searchable = true,
+      emptyIndicator,
+      autoSize = false,
+      popoverClassName,
+      disabled = false,
+      responsive,
+      minWidth,
+      maxWidth,
+      closeOnSelect = false,
+      ...props
+    },
+    ref
+  ) => {
+    const [selectedValue, setSelectedValue] = React.useState<string>(defaultValue);
+    const [isPopoverOpen, setIsPopoverOpen] = React.useState(false);
+    const [isAnimating, setIsAnimating] = React.useState(false);
+    const [searchValue, setSearchValue] = React.useState("");
+
+    const [politeMessage, setPoliteMessage] = React.useState("");
+    const [assertiveMessage, setAssertiveMessage] = React.useState("");
+
+    const prevIsOpen = React.useRef(isPopoverOpen);
+    const prevSearchValue = React.useRef(searchValue);
+
+    const toggleOption = (optionValue: string) => {
+      if (disabled) return;
+      const option = getOptionByValue(optionValue);
+      if (option?.disabled) return;
+      setSelectedValue(optionValue);
+      onValueChange(optionValue);
+      if (closeOnSelect) {
+        setIsPopoverOpen(false);
+      }
+    };
+
+    const announce = React.useCallback(
+      (message: string, priority: "polite" | "assertive" = "polite") => {
+        if (priority === "assertive") {
+          setAssertiveMessage(message);
+          setTimeout(() => setAssertiveMessage(""), 100);
+        } else {
+          setPoliteMessage(message);
+          setTimeout(() => setPoliteMessage(""), 100);
+        }
+      },
+      []
+    );
+
+    const multiSelectId = React.useId();
+    const listboxId = `${multiSelectId}-listbox`;
+    const triggerDescriptionId = `${multiSelectId}-description`;
+    const selectedCountId = `${multiSelectId}-count`;
+
+    const resetToDefault = React.useCallback(() => {
+      setSelectedValue(defaultValue);
+      setIsPopoverOpen(false);
+      setSearchValue("");
+      onValueChange(defaultValue);
+    }, [defaultValue, onValueChange]);
+
+    const buttonRef = React.useRef<HTMLButtonElement>(null);
+
+    React.useImperativeHandle(
+      ref,
+      () => ({
+        reset: resetToDefault,
+        clear: () => {
+          setSelectedValue("");
+          onValueChange("");
+        },
+        focus: () => {
+          if (buttonRef.current) {
+            buttonRef.current.focus();
+            const originalOutline = buttonRef.current.style.outline;
+            const originalOutlineOffset = buttonRef.current.style.outlineOffset;
+            buttonRef.current.style.outline = "2px solid hsl(var(--ring))";
+            buttonRef.current.style.outlineOffset = "2px";
+            setTimeout(() => {
+              if (buttonRef.current) {
+                buttonRef.current.style.outline = originalOutline;
+                buttonRef.current.style.outlineOffset = originalOutlineOffset;
+              }
+            }, 1000);
+          }
+        },
+      }),
+      [resetToDefault, selectedValue, onValueChange]
+    );
+
+    const [screenSize, setScreenSize] = React.useState<"mobile" | "tablet" | "desktop">("desktop");
+
+    React.useEffect(() => {
+      if (typeof window === "undefined") return;
+      const handleResize = () => {
+        const width = window.innerWidth;
+        if (width < 640) {
+          setScreenSize("mobile");
+        } else if (width < 1024) {
+          setScreenSize("tablet");
+        } else {
+          setScreenSize("desktop");
+        }
+      };
+      handleResize();
+      window.addEventListener("resize", handleResize);
+      return () => {
+        if (typeof window !== "undefined") {
+          window.removeEventListener("resize", handleResize);
+        }
+      };
+    }, []);
+
+    const getResponsiveSettings = () => {
+      if (!responsive) {
+        return {
+          hideIcons: false,
+          compactMode: false,
+        };
+      }
+      if (responsive === true) {
+        const defaultResponsive = {
+          mobile: { hideIcons: false, compactMode: true },
+          tablet: { hideIcons: false, compactMode: false },
+          desktop: { hideIcons: false, compactMode: false },
+        };
+        const currentSettings = defaultResponsive[screenSize];
+        return {
+          hideIcons: currentSettings?.hideIcons ?? false,
+          compactMode: currentSettings?.compactMode ?? false,
+        };
+      }
+      const currentSettings = responsive[screenSize];
+      return {
+        hideIcons: currentSettings?.hideIcons ?? false,
+        compactMode: currentSettings?.compactMode ?? false,
+      };
+    };
+
+    const responsiveSettings = getResponsiveSettings();
+
+    const getAllOptions = React.useCallback((): ComboboxOption[] => {
+      if (options.length === 0) return [];
+      const allOptions: ComboboxOption[] = options;
+      const valueSet = new Set<string>();
+      const duplicates: string[] = [];
+      const uniqueOptions: ComboboxOption[] = [];
+      allOptions.forEach((option) => {
+        if (valueSet.has(option.value)) {
+          duplicates.push(option.value);
+        } else {
+          valueSet.add(option.value);
+          uniqueOptions.push(option);
+        }
+      });
+      return allOptions;
+    }, [options]);
+
+    const getOptionByValue = React.useCallback(
+      (value: string): ComboboxOption | undefined => {
+        const option = getAllOptions().find((option) => option.value === value);
+        if (!option && process.env.NODE_ENV === "development") {
+          console.warn(`Combobox: Option with value "${value}" not found in options list`);
+        }
+        return option;
+      },
+      [getAllOptions]
+    );
+
+    const filteredOptions = React.useMemo(() => {
+      if (!searchable || !searchValue) return options;
+      if (options.length === 0) return [];
+
+      return options.filter(
+        (option) =>
+          option.label.toLowerCase().includes(searchValue.toLowerCase()) ||
+          option.value.toLowerCase().includes(searchValue.toLowerCase())
+      );
+    }, [options, searchValue, searchable]);
+
+    // const handleInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    //   if (event.key === "Enter") {
+    //     setIsPopoverOpen(true);
+    //   } else if (event.key === "Backspace" && !event.currentTarget.value) {
+    //     const newSelectedValues = [...selectedValue];
+    //     newSelectedValues.pop();
+    //     setSelectedValue(newSelectedValues);
+    //     onValueChange(newSelectedValues);
+    //   }
+    // };
+
+    const handleClear = () => {
+      if (disabled) return;
+      setSelectedValue("");
+      onValueChange("");
+    };
+
+    const handleTogglePopover = () => {
+      if (disabled) return;
+      setIsPopoverOpen((prev) => !prev);
+    };
+
+    const getWidthConstraints = () => {
+      const defaultMinWidth = screenSize === "mobile" ? "0px" : "200px";
+      const effectiveMinWidth = minWidth || defaultMinWidth;
+      const effectiveMaxWidth = maxWidth || "100%";
+      return {
+        minWidth: effectiveMinWidth,
+        maxWidth: effectiveMaxWidth,
+        width: autoSize ? "auto" : "100%",
+      };
+    };
+
+    const widthConstraints = getWidthConstraints();
+
+    React.useEffect(() => {
+      if (!isPopoverOpen) {
+        setSearchValue("");
+      }
+    }, [isPopoverOpen]);
+
+    React.useEffect(() => {
+      const allOptions = getAllOptions();
+      const totalOptions = allOptions.filter((opt) => !opt.disabled).length;
+
+      if (isPopoverOpen !== prevIsOpen.current) {
+        if (isPopoverOpen) {
+          announce(
+            `Dropdown opened. ${totalOptions} options available. Use arrow keys to navigate.`
+          );
+        } else {
+          announce("Dropdown closed.");
+        }
+        prevIsOpen.current = isPopoverOpen;
+      }
+
+      if (searchValue !== prevSearchValue.current && searchValue !== undefined) {
+        if (searchValue && isPopoverOpen) {
+          const filteredCount = allOptions.filter(
+            (opt) =>
+              opt.label.toLowerCase().includes(searchValue.toLowerCase()) ||
+              opt.value.toLowerCase().includes(searchValue.toLowerCase())
+          ).length;
+
+          announce(
+            `${filteredCount} option${filteredCount === 1 ? "" : "s"} found for "${searchValue}"`
+          );
+        }
+        prevSearchValue.current = searchValue;
+      }
+    }, [selectedValue, isPopoverOpen, searchValue, announce, getAllOptions]);
+
+    return (
+      <>
+        <div className="sr-only">
+          <div aria-live="polite" aria-atomic="true" role="status">
+            {politeMessage}
+          </div>
+          <div aria-live="assertive" aria-atomic="true" role="alert">
+            {assertiveMessage}
+          </div>
+        </div>
+
+        <Popover open={isPopoverOpen} onOpenChange={setIsPopoverOpen} modal={modalPopover}>
+          <div id={triggerDescriptionId} className="sr-only">
+            Multi-select dropdown. Use arrow keys to navigate, Enter to select, and Escape to close.
+          </div>
+          <PopoverTrigger asChild>
+            <Button
+              ref={buttonRef}
+              {...props}
+              onClick={handleTogglePopover}
+              disabled={disabled}
+              role="combobox"
+              aria-expanded={isPopoverOpen}
+              aria-haspopup="listbox"
+              aria-controls={isPopoverOpen ? listboxId : undefined}
+              aria-describedby={`${triggerDescriptionId} ${selectedCountId}`}
+              border="plain"
+              className={cn(
+                "flex h-10 items-center justify-between p-1 [&_svg]:pointer-events-auto",
+                "!bg-neutral-alpha-2 text-base !font-normal shadow md:text-sm",
+                autoSize ? "w-auto" : "w-full",
+                responsiveSettings.compactMode && "h-8 text-sm",
+                screenSize === "mobile" && "h-12 text-base",
+                disabled && "cursor-not-allowed opacity-50",
+                className
+              )}
+              style={{
+                ...widthConstraints,
+                maxWidth: `min(${widthConstraints.maxWidth}, 100%)`,
+              }}
+            >
+              {selectedValue ? (
+                <div className="mx-auto flex w-full items-center justify-between">
+                  <span className="text-foreground text-sm">
+                    {options.find((op) => op.value === selectedValue)?.label}
+                  </span>
+                  <div className="flex items-center justify-between">
+                    <div
+                      role="button"
+                      tabIndex={0}
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        handleClear();
+                      }}
+                      onKeyDown={(event) => {
+                        if (event.key === "Enter" || event.key === " ") {
+                          event.preventDefault();
+                          event.stopPropagation();
+                          handleClear();
+                        }
+                      }}
+                      className="text-muted-foreground hover:text-foreground focus:ring-ring mx-2 flex size-3.5 cursor-pointer items-center justify-center rounded-sm focus:ring-2 focus:ring-offset-1 focus:outline-none"
+                    >
+                      <XIcon className="size-3.5" />
+                    </div>
+                    <Separator orientation="vertical" className="flex h-full min-h-6" />
+                    <ChevronDown
+                      className="text-muted-foreground mx-2 h-4 cursor-pointer"
+                      aria-hidden="true"
+                    />
+                  </div>
+                </div>
+              ) : (
+                <div className="mx-auto flex w-full items-center justify-between">
+                  <span className="text-muted-foreground text-sm">{placeholder}</span>
+                  <ChevronDown className="text-muted-foreground mx-2 h-4 cursor-pointer" />
+                </div>
+              )}
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent
+            id={listboxId}
+            role="listbox"
+            aria-multiselectable="true"
+            aria-label="Available options"
+            className={cn(
+              "w-auto p-0",
+              screenSize === "mobile" && "w-[85vw] max-w-[280px]",
+              screenSize === "tablet" && "w-[70vw] max-w-md",
+              screenSize === "desktop" && "min-w-[300px]",
+              popoverClassName
+            )}
+            style={{
+              maxWidth: `min(${widthConstraints.maxWidth}, 85vw)`,
+              maxHeight: screenSize === "mobile" ? "70vh" : "60vh",
+              touchAction: "manipulation",
+            }}
+            align="start"
+            onEscapeKeyDown={() => setIsPopoverOpen(false)}
+          >
+            <Command>
+              {searchable && (
+                <CommandInput
+                  placeholder="Search options..."
+                  // onKeyDown={handleInputKeyDown}
+                  value={searchValue}
+                  onValueChange={setSearchValue}
+                  aria-label="Search through available options"
+                  aria-describedby={`${multiSelectId}-search-help`}
+                />
+              )}
+              {searchable && (
+                <div id={`${multiSelectId}-search-help`} className="sr-only">
+                  Type to filter options. Use arrow keys to navigate results.
+                </div>
+              )}
+              <CommandList
+                className={cn(
+                  "multiselect-scrollbar max-h-[40vh] overflow-y-auto",
+                  screenSize === "mobile" && "max-h-[50vh]",
+                  "overscroll-behavior-y-contain"
+                )}
+              >
+                <CommandEmpty>{emptyIndicator || "No results found."}</CommandEmpty>{" "}
+                <CommandGroup>
+                  {filteredOptions.map((option) => {
+                    const isSelected = selectedValue === option.value;
+                    return (
+                      <CommandItem
+                        key={option.value}
+                        onSelect={() => toggleOption(option.value)}
+                        role="option"
+                        aria-selected={isSelected}
+                        aria-disabled={option.disabled}
+                        aria-label={`${option.label}${
+                          isSelected ? ", selected" : ", not selected"
+                        }${option.disabled ? ", disabled" : ""}`}
+                        className={cn(
+                          "cursor-pointer",
+                          option.disabled && "cursor-not-allowed opacity-50"
+                        )}
+                        disabled={option.disabled}
+                      >
+                        {option.icon && (
+                          <option.icon
+                            className="text-muted-foreground mr-2 size-3.5"
+                            aria-hidden="true"
+                          />
+                        )}
+                        <span className="grow">{option.label}</span>
+                        {isSelected ? (
+                          <CheckIcon className="text-muted-foreground size-3.5" />
+                        ) : null}
+                      </CommandItem>
+                    );
+                  })}
+                </CommandGroup>
+              </CommandList>
+            </Command>
+          </PopoverContent>
+          {animation > 0 && selectedValue && (
+            <WandSparkles
+              className={cn(
+                "text-foreground bg-background my-2 h-3 w-3 cursor-pointer",
+                isAnimating ? "" : "text-muted-foreground"
+              )}
+              onClick={() => setIsAnimating(!isAnimating)}
+            />
+          )}
+        </Popover>
+      </>
+    );
+  }
+);
+
+Combobox.displayName = "Combobox";
+export type { ComboboxOption, ComboboxProps };