@hypoth-ui/cli 0.0.1 → 0.1.1

package/templates/combobox/combobox-input.tsx

@@ -0,0 +1,159 @@
+/**
+ * Combobox Input component - text input with autocomplete.
+ */
+
+import { type InputHTMLAttributes, forwardRef, useCallback, useRef } from "react";
+import { useComboboxContext } from "./combobox-context.js";
+
+export interface ComboboxInputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange"> {
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
+}
+
+/**
+ * Text input for the combobox.
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Input placeholder="Search..." />
+ * ```
+ */
+export const ComboboxInput = forwardRef<HTMLInputElement, ComboboxInputProps>(
+  ({ onKeyDown, onFocus, ...restProps }, ref) => {
+    const {
+      behavior,
+      open,
+      setOpen,
+      inputValue,
+      setInputValue,
+      highlightedValue,
+      setHighlightedValue,
+    } = useComboboxContext("Combobox.Input");
+    const internalRef = useRef<HTMLInputElement>(null);
+
+    // Handle input change
+    const handleChange = useCallback(
+      (event: React.ChangeEvent<HTMLInputElement>) => {
+        const value = event.target.value;
+        behavior.setInputValue(value);
+        setInputValue(value);
+
+        // Auto-open on input
+        if (value && !open) {
+          behavior.open();
+          setOpen(true);
+        }
+      },
+      [behavior, open, setOpen, setInputValue]
+    );
+
+    // Handle keyboard navigation
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLInputElement>) => {
+        if (!open) {
+          if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            behavior.open();
+            setOpen(true);
+          }
+          onKeyDown?.(event);
+          return;
+        }
+
+        switch (event.key) {
+          case "Enter":
+            event.preventDefault();
+            if (highlightedValue) {
+              behavior.select(highlightedValue);
+            }
+            break;
+          case "Escape":
+            event.preventDefault();
+            behavior.close();
+            setOpen(false);
+            break;
+          case "ArrowDown":
+            event.preventDefault();
+            behavior.highlightNext();
+            setHighlightedValue(behavior.state.highlightedValue);
+            break;
+          case "ArrowUp":
+            event.preventDefault();
+            behavior.highlightPrev();
+            setHighlightedValue(behavior.state.highlightedValue);
+            break;
+          case "Home":
+            if (event.currentTarget.selectionStart === 0) {
+              event.preventDefault();
+              behavior.highlightFirst();
+              setHighlightedValue(behavior.state.highlightedValue);
+            }
+            break;
+          case "End":
+            if (event.currentTarget.selectionEnd === event.currentTarget.value.length) {
+              event.preventDefault();
+              behavior.highlightLast();
+              setHighlightedValue(behavior.state.highlightedValue);
+            }
+            break;
+          case "Tab":
+            behavior.close();
+            setOpen(false);
+            break;
+        }
+
+        onKeyDown?.(event);
+      },
+      [behavior, open, setOpen, highlightedValue, setHighlightedValue, onKeyDown]
+    );
+
+    // Handle focus
+    const handleFocus = useCallback(
+      (event: React.FocusEvent<HTMLInputElement>) => {
+        onFocus?.(event);
+      },
+      [onFocus]
+    );
+
+    // Get input props from behavior
+    const inputProps = behavior.getInputProps();
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLInputElement | null) => {
+        (internalRef as React.MutableRefObject<HTMLInputElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLInputElement | null>).current = element;
+        }
+      },
+      [ref]
+    );
+
+    return (
+      <input
+        ref={mergedRef}
+        type="text"
+        role={inputProps.role}
+        aria-expanded={open}
+        aria-haspopup={inputProps["aria-haspopup"]}
+        aria-controls={inputProps["aria-controls"]}
+        aria-activedescendant={
+          open && highlightedValue ? `combobox-option-${highlightedValue}` : undefined
+        }
+        aria-autocomplete={inputProps["aria-autocomplete"]}
+        aria-busy={inputProps["aria-busy"]}
+        value={inputValue}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+        data-state={open ? "open" : "closed"}
+        {...restProps}
+      />
+    );
+  }
+);
+
+ComboboxInput.displayName = "Combobox.Input";

package/templates/combobox/combobox-loading.tsx

@@ -0,0 +1,38 @@
+/**
+ * Combobox Loading component - shown during async loading.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+import { useComboboxContext } from "./combobox-context.js";
+
+export interface ComboboxLoadingProps extends HTMLAttributes<HTMLOutputElement> {
+  /** Loading indicator content */
+  children?: ReactNode;
+}
+
+/**
+ * Loading state shown during async search.
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Loading>Searching...</Combobox.Loading>
+ * ```
+ */
+export const ComboboxLoading = forwardRef<HTMLOutputElement, ComboboxLoadingProps>(
+  ({ children, className, ...restProps }, ref) => {
+    const { loading } = useComboboxContext("Combobox.Loading");
+
+    // Only show if loading
+    if (!loading) {
+      return null;
+    }
+
+    return (
+      <output ref={ref} aria-live="polite" className={className} {...restProps}>
+        {children}
+      </output>
+    );
+  }
+);
+
+ComboboxLoading.displayName = "Combobox.Loading";

package/templates/combobox/combobox-option.tsx

@@ -0,0 +1,99 @@
+/**
+ * Combobox Option component - individual option in the combobox.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef, useCallback } from "react";
+import { useComboboxContext } from "./combobox-context.js";
+
+export interface ComboboxOptionProps extends Omit<HTMLAttributes<HTMLDivElement>, "value"> {
+  /** Option value */
+  value: string;
+  /** Display label (uses children if not specified) */
+  label?: string;
+  /** Whether the option is disabled */
+  disabled?: boolean;
+  /** Option content */
+  children?: ReactNode;
+}
+
+/**
+ * Individual option in the combobox.
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Option value="apple">Apple</Combobox.Option>
+ * <Combobox.Option value="banana" disabled>Banana</Combobox.Option>
+ * ```
+ */
+export const ComboboxOption = forwardRef<HTMLDivElement, ComboboxOptionProps>(
+  (
+    {
+      value: optionValue,
+      label,
+      disabled = false,
+      children,
+      className,
+      onClick,
+      onMouseEnter,
+      ...restProps
+    },
+    ref
+  ) => {
+    const { behavior, value, highlightedValue, setHighlightedValue, setOpen, multiple } =
+      useComboboxContext("Combobox.Option");
+
+    const isSelected = multiple ? (value as string[]).includes(optionValue) : value === optionValue;
+    const isHighlighted = highlightedValue === optionValue;
+
+    // Handle click to select
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled) return;
+        behavior.select(optionValue);
+        if (!multiple) {
+          behavior.close();
+          setOpen(false);
+        }
+        onClick?.(event);
+      },
+      [behavior, optionValue, disabled, multiple, setOpen, onClick]
+    );
+
+    // Handle mouse enter to highlight
+    const handleMouseEnter = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled) return;
+        setHighlightedValue(optionValue);
+        onMouseEnter?.(event);
+      },
+      [optionValue, disabled, setHighlightedValue, onMouseEnter]
+    );
+
+    const optionProps = behavior.getOptionProps(
+      optionValue,
+      label || String(children) || optionValue
+    );
+
+    return (
+      <div
+        ref={ref}
+        role={optionProps.role}
+        id={optionProps.id}
+        aria-selected={isSelected}
+        aria-disabled={disabled || undefined}
+        data-value={optionValue}
+        data-selected={isSelected || undefined}
+        data-highlighted={isHighlighted || undefined}
+        data-disabled={disabled || undefined}
+        className={className}
+        onClick={handleClick}
+        onMouseEnter={handleMouseEnter}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+ComboboxOption.displayName = "Combobox.Option";

package/templates/combobox/combobox-root.tsx

@@ -0,0 +1,207 @@
+/**
+ * Combobox Root component - provides context to all Combobox compound components.
+ */
+
+import { type Option, type Placement, createComboboxBehavior } from "@hypoth-ui/primitives-dom";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { ComboboxProvider } from "./combobox-context.js";
+
+export interface ComboboxRootProps<Multi extends boolean = false> {
+  /** Combobox content */
+  children?: ReactNode;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state (uncontrolled) */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Controlled value (single-select) */
+  value?: Multi extends true ? string[] : string | null;
+  /** Default value (uncontrolled) */
+  defaultValue?: Multi extends true ? string[] : string | null;
+  /** Called when value changes */
+  onValueChange?: (value: Multi extends true ? string[] : string | null) => void;
+  /** Called when input value changes */
+  onInputChange?: (query: string) => void;
+  /** Enable multi-select mode */
+  multiple?: Multi;
+  /** Allow creating new values */
+  creatable?: boolean;
+  /** Called when new value is created */
+  onCreateValue?: (value: string) => void;
+  /** Async item loader */
+  loadItems?: (query: string) => Promise<Option<string>[]>;
+  /** Static items */
+  items?: Option<string>[];
+  /** Debounce delay for async (ms) */
+  debounce?: number;
+  /** Virtualization threshold */
+  virtualizationThreshold?: number;
+  /** Placement relative to input */
+  placement?: Placement;
+  /** Offset from input in pixels */
+  offset?: number;
+  /** Whether to flip placement on viewport edge */
+  flip?: boolean;
+  /** Whether combobox is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Root component for Combobox compound pattern.
+ * Provides context to Input, Content, Option, and Tag.
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Root onValueChange={(value) => console.log(value)}>
+ *   <Combobox.Input placeholder="Search..." />
+ *   <Combobox.Content>
+ *     <Combobox.Option value="apple">Apple</Combobox.Option>
+ *     <Combobox.Option value="banana">Banana</Combobox.Option>
+ *   </Combobox.Content>
+ * </Combobox.Root>
+ * ```
+ */
+export function ComboboxRoot<Multi extends boolean = false>({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+  onInputChange,
+  multiple = false as Multi,
+  creatable = false,
+  onCreateValue,
+  loadItems,
+  items: staticItems = [],
+  debounce = 300,
+  virtualizationThreshold = 100,
+  placement: _placement = "bottom-start",
+  offset: _offset = 4,
+  flip: _flip = true,
+  disabled = false,
+}: ComboboxRootProps<Multi>) {
+  // Compute default based on multiple mode
+  const computedDefaultValue = useMemo(() => {
+    if (defaultValue !== undefined) return defaultValue;
+    return (multiple ? [] : null) as Multi extends true ? string[] : string | null;
+  }, [defaultValue, multiple]);
+
+  // Support both controlled and uncontrolled modes for open
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isOpenControlled = controlledOpen !== undefined;
+  const open = isOpenControlled ? controlledOpen : internalOpen;
+
+  // Support both controlled and uncontrolled modes for value
+  const [internalValue, setInternalValue] =
+    useState<Multi extends true ? string[] : string | null>(computedDefaultValue);
+  const isValueControlled = controlledValue !== undefined;
+  const value = isValueControlled ? controlledValue : internalValue;
+
+  // Input value
+  const [inputValue, setInputValueState] = useState("");
+
+  // Highlighted value for keyboard navigation
+  const [highlightedValue, setHighlightedValue] = useState<string | null>(null);
+
+  // Filtered options
+  const [filteredOptions, setFilteredOptions] = useState<Option<string>[]>(staticItems);
+
+  // Loading state
+  const [loading, _setLoading] = useState(false);
+
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      if (!isOpenControlled) {
+        setInternalOpen(nextOpen);
+      }
+      onOpenChange?.(nextOpen);
+    },
+    [isOpenControlled, onOpenChange]
+  );
+
+  const setValue = useCallback(
+    (nextValue: Multi extends true ? string[] : string | null) => {
+      if (!isValueControlled) {
+        setInternalValue(nextValue);
+      }
+      onValueChange?.(nextValue);
+    },
+    [isValueControlled, onValueChange]
+  );
+
+  const setInputValue = useCallback(
+    (nextValue: string) => {
+      setInputValueState(nextValue);
+      onInputChange?.(nextValue);
+    },
+    [onInputChange]
+  );
+
+  // Create behavior instance
+  // biome-ignore lint/correctness/useExhaustiveDependencies: behavior is created once
+  const behavior = useMemo(
+    () =>
+      createComboboxBehavior<string, Multi>({
+        defaultValue: value as Multi extends true ? string[] : string | null,
+        multiple,
+        creatable,
+        onCreateValue,
+        loadItems,
+        items: staticItems,
+        debounce,
+        virtualizationThreshold,
+        disabled,
+        onValueChange: (v) => setValue(v as Multi extends true ? string[] : string | null),
+        onInputChange: (query) => {
+          setInputValue(query);
+          // Filter static items if no async loader
+          if (!loadItems) {
+            const lowerQuery = query.toLowerCase();
+            const filtered = staticItems.filter((item) =>
+              item.label.toLowerCase().includes(lowerQuery)
+            );
+            setFilteredOptions(filtered);
+          }
+        },
+      }),
+    []
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      behavior: behavior as unknown as typeof behavior,
+      open,
+      setOpen,
+      value,
+      setValue,
+      inputValue,
+      setInputValue,
+      highlightedValue,
+      setHighlightedValue,
+      multiple,
+      filteredOptions,
+      loading,
+    }),
+    [
+      behavior,
+      open,
+      setOpen,
+      value,
+      setValue,
+      inputValue,
+      setInputValue,
+      highlightedValue,
+      filteredOptions,
+      loading,
+      multiple,
+    ]
+  );
+
+  // biome-ignore lint/suspicious/noExplicitAny: Generic context type requires cast for conditional Multi type
+  return <ComboboxProvider value={contextValue as any}>{children}</ComboboxProvider>;
+}
+
+ComboboxRoot.displayName = "Combobox.Root";

package/templates/combobox/combobox-tag.tsx

@@ -0,0 +1,62 @@
+/**
+ * Combobox Tag component - selected value tag for multi-select.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef, useCallback } from "react";
+import { useComboboxContext } from "./combobox-context.js";
+
+export interface ComboboxTagProps extends Omit<HTMLAttributes<HTMLDivElement>, "value"> {
+  /** Tag value */
+  value: string;
+  /** Display label */
+  label?: string;
+  /** Tag content */
+  children?: ReactNode;
+}
+
+/**
+ * Tag for displaying selected value in multi-select mode.
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Tag value="apple">
+ *   Apple
+ *   <button onClick={() => remove("apple")}>×</button>
+ * </Combobox.Tag>
+ * ```
+ */
+export const ComboboxTag = forwardRef<HTMLDivElement, ComboboxTagProps>(
+  ({ value: tagValue, label, children, className, onKeyDown, ...restProps }, ref) => {
+    const { behavior } = useComboboxContext("Combobox.Tag");
+
+    // Handle keyboard to remove
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === "Delete" || event.key === "Backspace") {
+          event.preventDefault();
+          behavior.remove(tagValue);
+        }
+        onKeyDown?.(event);
+      },
+      [behavior, tagValue, onKeyDown]
+    );
+
+    const tagProps = behavior.getTagProps(tagValue, label || String(children) || tagValue);
+
+    return (
+      <div
+        ref={ref}
+        role={tagProps.role}
+        aria-label={tagProps["aria-label"]}
+        data-value={tagValue}
+        className={className}
+        onKeyDown={handleKeyDown}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+ComboboxTag.displayName = "Combobox.Tag";

package/templates/combobox/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Combobox compound component exports.
+ *
+ * @example
+ * ```tsx
+ * import { Combobox } from "@/components/ui";
+ *
+ * <Combobox.Root onValueChange={(value) => console.log(value)}>
+ *   <Combobox.Input placeholder="Search fruits..." />
+ *   <Combobox.Content>
+ *     <Combobox.Option value="apple">Apple</Combobox.Option>
+ *     <Combobox.Option value="banana">Banana</Combobox.Option>
+ *     <Combobox.Empty>No results found</Combobox.Empty>
+ *   </Combobox.Content>
+ * </Combobox.Root>
+ *
+ * // Multi-select with tags
+ * <Combobox.Root multiple onValueChange={(values) => console.log(values)}>
+ *   {values.map(v => (
+ *     <Combobox.Tag key={v} value={v}>{v}</Combobox.Tag>
+ *   ))}
+ *   <Combobox.Input placeholder="Add tags..." />
+ *   <Combobox.Content>
+ *     <Combobox.Option value="react">React</Combobox.Option>
+ *     <Combobox.Option value="vue">Vue</Combobox.Option>
+ *   </Combobox.Content>
+ * </Combobox.Root>
+ * ```
+ */
+
+import { ComboboxContent, type ComboboxContentProps } from "./combobox-content.js";
+import { ComboboxEmpty, type ComboboxEmptyProps } from "./combobox-empty.js";
+import { ComboboxInput, type ComboboxInputProps } from "./combobox-input.js";
+import { ComboboxLoading, type ComboboxLoadingProps } from "./combobox-loading.js";
+import { ComboboxOption, type ComboboxOptionProps } from "./combobox-option.js";
+import { ComboboxRoot, type ComboboxRootProps } from "./combobox-root.js";
+import { ComboboxTag, type ComboboxTagProps } from "./combobox-tag.js";
+
+// Compound component
+export const Combobox = {
+  Root: ComboboxRoot,
+  Input: ComboboxInput,
+  Content: ComboboxContent,
+  Option: ComboboxOption,
+  Tag: ComboboxTag,
+  Empty: ComboboxEmpty,
+  Loading: ComboboxLoading,
+};
+
+// Type exports
+export type {
+  ComboboxContentProps,
+  ComboboxEmptyProps,
+  ComboboxInputProps,
+  ComboboxLoadingProps,
+  ComboboxOptionProps,
+  ComboboxRootProps,
+  ComboboxTagProps,
+};
+
+// Re-export Placement and Option from primitives-dom
+export type { Placement, Option } from "@hypoth-ui/primitives-dom";