@12-apps/ui 1.0.0

package/src/components/form/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,166 @@
+import { Box, ClickAwayListener } from '@mui/material';
+import React from 'react';
+
+import {
+  defaultGetKey,
+  defaultGetLabel,
+  defaultGetSuggestionType,
+  type MatchMode,
+} from './Autocomplete.helpers';
+import {
+  AutocompleteInput,
+  ChipList,
+  DefaultSuggestion,
+  SuggestionListBox,
+} from './Autocomplete.parts';
+import type { AutocompleteOption, AutocompleteProps, SuggestionType } from './Autocomplete.types';
+import { useAutocomplete, type AutocompleteView } from './useAutocomplete';
+
+/** Presentational props resolved from {@link AutocompleteProps} (defaults applied once). */
+interface RenderConfig<T> {
+  getKey: (item: T) => string;
+  getLabel: (item: T) => string;
+  getSuggestionType: (item: T) => SuggestionType | undefined;
+  getDescription?: (item: T) => string | undefined;
+  renderSuggestion?: (item: T, state: { active: boolean; query: string }) => React.ReactNode;
+  matchMode: MatchMode;
+  multiple: boolean;
+  selectedItems: T[];
+  isLoading: boolean;
+  showGhostText: boolean;
+  placeholder: string;
+  autoFocus: boolean;
+  disabled: boolean;
+  portal: boolean | { container?: HTMLElement };
+  className?: string;
+  chipClassName?: string;
+  inputAriaLabel?: string;
+  inputClassName?: string;
+  listClassName?: string;
+  itemClassName?: string;
+  activeItemClassName?: string;
+}
+
+/** Apply presentational defaults once so the component itself stays branch-light. */
+function resolveRenderConfig<T>(p: AutocompleteProps<T>): RenderConfig<T> {
+  return {
+    getKey: p.getKey ?? defaultGetKey,
+    getLabel: p.getLabel ?? defaultGetLabel,
+    getSuggestionType: p.getSuggestionType ?? defaultGetSuggestionType,
+    getDescription: p.getDescription,
+    renderSuggestion: p.renderSuggestion,
+    matchMode: p.matchMode ?? 'contains',
+    multiple: Boolean(p.multiple),
+    selectedItems: p.selectedItems ?? [],
+    isLoading: Boolean(p.isLoading),
+    showGhostText: p.showGhostText ?? true,
+    placeholder: p.placeholder ?? 'Type to search...',
+    autoFocus: Boolean(p.autoFocus),
+    disabled: Boolean(p.disabled),
+    portal: p.portal ?? false,
+    className: p.className,
+    chipClassName: p.chipClassName,
+    inputAriaLabel: p.inputAriaLabel,
+    inputClassName: p.inputClassName,
+    listClassName: p.listClassName,
+    itemClassName: p.itemClassName,
+    activeItemClassName: p.activeItemClassName,
+  };
+}
+
+/** A single suggestion node: the caller's custom renderer or the default row. */
+function renderSuggestionNode<T>(item: T, active: boolean, query: string, cfg: RenderConfig<T>): React.ReactNode {
+  if (cfg.renderSuggestion) return cfg.renderSuggestion(item, { active, query });
+  return (
+    <DefaultSuggestion
+      item={item}
+      state={{ active, query }}
+      getLabel={cfg.getLabel}
+      getDescription={cfg.getDescription}
+      getSuggestionType={cfg.getSuggestionType}
+      matchMode={cfg.matchMode}
+    />
+  );
+}
+
+/**
+ * ARIA combobox with a popup listbox: local/async filtering, inline ghost
+ * completion (Tab/→), multi-select chips, custom rendering, and typed
+ * `search`/`link` suggestions (a `link` opens its URL instead of filling the
+ * input). State/effects/handlers live in {@link useAutocomplete}; presentational
+ * pieces live in `Autocomplete.parts`.
+ */
+export const Autocomplete = <T = AutocompleteOption>(props: AutocompleteProps<T>): React.JSX.Element => {
+  const cfg = resolveRenderConfig(props);
+  const view: AutocompleteView<T> = useAutocomplete<T>(props);
+  const s = view.state;
+  const showNoResults =
+    !cfg.isLoading && view.visibleSuggestions.length === 0 && Boolean(s.inputValue.trim());
+
+  return (
+    <ClickAwayListener onClickAway={view.onClickAway}>
+      <Box className={cfg.className} data-testid="autocomplete-container">
+        {cfg.multiple && cfg.selectedItems.length > 0 && (
+          <ChipList
+            items={cfg.selectedItems}
+            getKey={cfg.getKey}
+            getLabel={cfg.getLabel}
+            onRemove={view.removeSelectedItem}
+            chipClassName={cfg.chipClassName}
+          />
+        )}
+
+        <AutocompleteInput
+          id={view.id}
+          listId={view.listId}
+          inputRef={s.inputRef}
+          inputValue={s.inputValue}
+          ghost={s.ghost}
+          showGhost={cfg.showGhostText}
+          isInputFocused={s.isInputFocused}
+          open={s.open}
+          activeDescendant={view.activeDescendant}
+          isLoading={cfg.isLoading}
+          disabled={cfg.disabled}
+          autoFocus={cfg.autoFocus}
+          placeholder={cfg.placeholder}
+          startAdornment={props.startAdornment}
+          inputAriaLabel={cfg.inputAriaLabel}
+          inputClassName={cfg.inputClassName}
+          onChange={view.onInputChange}
+          onKeyDown={view.onKeyDown}
+          onFocus={view.onFocus}
+          onBlur={view.onBlur}
+          onCompositionStart={() => s.setComposition(true)}
+          onCompositionEnd={() => s.setComposition(false)}
+        />
+
+        {s.open && (
+          <SuggestionListBox
+            open={s.open}
+            anchorEl={s.inputRef.current}
+            portal={cfg.portal}
+            listRef={s.listRef}
+            listId={view.listId}
+            optionIdPrefix={view.optionIdPrefix}
+            items={view.visibleSuggestions}
+            activeIndex={s.activeIndex}
+            isLoading={cfg.isLoading}
+            showNoResults={showNoResults}
+            getKey={cfg.getKey}
+            onSelect={view.selectItem}
+            onHover={s.setActiveIndex}
+            renderItem={(item, active) => renderSuggestionNode(item, active, s.inputValue, cfg)}
+            listClassName={cfg.listClassName}
+            itemClassName={cfg.itemClassName}
+            activeItemClassName={cfg.activeItemClassName}
+          />
+        )}
+      </Box>
+    </ClickAwayListener>
+  );
+};
+
+Autocomplete.displayName = 'Autocomplete';
+
+export default Autocomplete;

package/src/components/form/Autocomplete/Autocomplete.types.ts

@@ -0,0 +1,116 @@
+import type React from 'react';
+
+/**
+ * A suggestion's behavior on select:
+ * - `search` (default) — fills the input with the suggestion's label.
+ * - `link` — opens the suggestion's {@link AutocompleteOption.url} in a new tab
+ *   instead of changing the input (Google-style "go to" result).
+ */
+export type SuggestionType = 'search' | 'link';
+
+export interface AutocompleteOption<T = unknown> {
+  id?: string;
+  key?: string;
+  value?: string;
+  label?: string;
+  name?: string;
+  text?: string;
+  description?: string;
+  /** When `link`, selecting the suggestion opens {@link url} instead of filling the input. */
+  type?: SuggestionType;
+  /** Target URL for a `link` suggestion. */
+  url?: string;
+  data?: T;
+}
+
+export interface AutocompleteProps<T = AutocompleteOption> {
+  /** Controlled input value */
+  value: string;
+  /** Input value change */
+  onChange: (val: string) => void;
+
+  /** Suggestion items (generic) */
+  suggestions: T[];
+  /** Unique key extractor */
+  getKey?: (item: T) => string;
+  /** Text label extractor */
+  getLabel?: (item: T) => string;
+  /** Optional description extractor (for SR and UI) */
+  getDescription?: (item: T) => string | undefined;
+  /** Custom row renderer */
+  renderSuggestion?: (item: T, state: { active: boolean; query: string }) => React.ReactNode;
+  /** Called when a suggestion is chosen */
+  onSelect?: (item: T) => void;
+
+  /**
+   * Resolve a suggestion's {@link SuggestionType}. A `link` suggestion opens
+   * {@link getUrl} on select (via {@link openLink}) instead of filling the input,
+   * and the default renderer shows a link icon; a `search` suggestion (default)
+   * shows a search icon and fills the input. Return `undefined` for untyped
+   * suggestions (no icon, classic behavior).
+   */
+  getSuggestionType?: (item: T) => SuggestionType | undefined;
+  /** Resolve the URL for a `link` suggestion. */
+  getUrl?: (item: T) => string | undefined;
+  /**
+   * Open a `link` suggestion. Defaults to
+   * `window.open(url, '_blank', 'noopener,noreferrer')`; override for a router or
+   * to assert the call in tests.
+   */
+  openLink?: (url: string, item: T) => void;
+
+  /** Allow values not in suggestions */
+  allowFreeText?: boolean;
+  /** Enable multiple selection (chips) */
+  multiple?: boolean;
+  /** Selected items in multiple mode */
+  selectedItems?: T[];
+  /** Update selected items in multiple mode */
+  onSelectedItemsChange?: (items: T[]) => void;
+
+  /** Async mode flags */
+  async?: boolean;
+  isLoading?: boolean;
+  /** Debounce in ms for local filtering or remote fetch triggers */
+  debounceMs?: number;
+
+  /** Inline completion remainder visibility */
+  showGhostText?: boolean;
+  /** Optional leading adornment inside the input (e.g. a search icon). */
+  startAdornment?: React.ReactNode;
+  /** Case/fuzzy options (local filtering only) */
+  matchMode?: 'startsWith' | 'contains' | 'fuzzy';
+
+  /** A11y & structure */
+  id?: string;
+  inputAriaLabel?: string;
+  placeholder?: string;
+  autoFocus?: boolean;
+  disabled?: boolean;
+
+  /** Styling hooks */
+  className?: string;
+  inputClassName?: string;
+  listClassName?: string;
+  itemClassName?: string;
+  activeItemClassName?: string;
+  chipClassName?: string;
+
+  /** Portal the popup if desired */
+  portal?: boolean | { container?: HTMLElement };
+  /** Max visible items before scroll */
+  maxVisibleItems?: number;
+}
+
+export interface AutocompleteState {
+  open: boolean;
+  activeIndex: number;
+  ghost: string;
+  inputValue: string;
+  composition: boolean;
+}
+
+export interface SuggestionItemState {
+  active: boolean;
+  query: string;
+}