@12-apps/ui 1.0.0

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

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+
+/// <reference types="@types/google.maps" />
+
+export interface AddressDetails {
+  formatted: string;
+  street: string;
+  city: string;
+  state: string;
+  country: string;
+  postalCode: string;
+  coordinates: {
+    lat: number;
+    lng: number;
+  };
+}
+
+export interface AddressAutocompleteProps {
+  variant?: 'glass' | 'outlined' | 'filled';
+  label?: string;
+  placeholder?: string;
+  icon?: ReactNode;
+  onSelect: (address: AddressDetails) => void;
+  googleMapsApiKey: string;
+  floating?: boolean;
+  restrictions?: {
+    country?: string | string[];
+    types?: string[];
+  };
+  error?: boolean;
+  helperText?: string;
+  disabled?: boolean;
+  required?: boolean;
+  fullWidth?: boolean;
+  defaultValue?: string;
+  getCurrentLocation?: boolean;
+}

package/src/components/form/AddressAutocomplete/index.ts

@@ -0,0 +1,2 @@
+export { AddressAutocomplete } from './AddressAutocomplete';
+export type { AddressAutocompleteProps, AddressDetails } from './AddressAutocomplete.types';

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

@@ -0,0 +1,115 @@
+import type { SuggestionType } from './Autocomplete.types';
+
+/** Local filtering strategy. */
+export type MatchMode = 'startsWith' | 'contains' | 'fuzzy';
+
+/** Default key extractor: id/key/value/label, else the item itself stringified. */
+export const defaultGetKey = <T,>(item: T): string => {
+  if (typeof item === 'string') return item;
+  if (typeof item === 'object' && item !== null) {
+    const obj = item as Record<string, unknown>;
+    return String(obj.id ?? obj.key ?? obj.value ?? obj.label ?? obj);
+  }
+  return String(item);
+};
+
+/** Default label extractor: label/name/text, else the item itself stringified. */
+export const defaultGetLabel = <T,>(item: T): string => {
+  if (typeof item === 'string') return item;
+  if (typeof item === 'object' && item !== null) {
+    const obj = item as Record<string, unknown>;
+    return String(obj.label ?? obj.name ?? obj.text ?? obj);
+  }
+  return String(item);
+};
+
+/** Default suggestion-type extractor: reads a `type: 'search' | 'link'` field. */
+export const defaultGetSuggestionType = <T,>(item: T): SuggestionType | undefined => {
+  if (typeof item === 'object' && item !== null) {
+    const { type } = item as { type?: unknown };
+    if (type === 'search' || type === 'link') return type;
+  }
+  return undefined;
+};
+
+/** Default URL extractor for `link` suggestions: reads a `url: string` field. */
+export const defaultGetUrl = <T,>(item: T): string | undefined => {
+  if (typeof item === 'object' && item !== null) {
+    const { url } = item as { url?: unknown };
+    if (typeof url === 'string') return url;
+  }
+  return undefined;
+};
+
+/** Default link opener: a new tab with `noopener,noreferrer`. SSR-guarded. */
+export const defaultOpenLink = (url: string): void => {
+  if (typeof window !== 'undefined') {
+    window.open(url, '_blank', 'noopener,noreferrer');
+  }
+};
+
+/** Fuzzy match: every char of `query` appears in `label`, in order. */
+function fuzzyMatch(label: string, query: string): boolean {
+  let labelIndex = 0;
+  for (let queryIndex = 0; queryIndex < query.length; queryIndex++) {
+    const char = query[queryIndex];
+    if (!char) continue;
+    labelIndex = label.indexOf(char, labelIndex);
+    if (labelIndex === -1) return false;
+    labelIndex++;
+  }
+  return true;
+}
+
+/** True when `label` matches `query` under the given {@link MatchMode} (case-insensitive). */
+function matchesQuery(label: string, query: string, matchMode: MatchMode): boolean {
+  const haystack = label.toLowerCase();
+  const needle = query.toLowerCase();
+  if (matchMode === 'startsWith') return haystack.startsWith(needle);
+  if (matchMode === 'fuzzy') return fuzzyMatch(haystack, needle);
+  return haystack.includes(needle);
+}
+
+/** Filter `suggestions` by `query` under `matchMode`; an empty query returns all. */
+export function filterSuggestions<T>(
+  suggestions: T[],
+  query: string,
+  matchMode: MatchMode,
+  getLabel: (item: T) => string,
+): T[] {
+  if (!query) return suggestions;
+  return suggestions.filter((item) => matchesQuery(getLabel(item), query, matchMode));
+}
+
+/**
+ * The first suggestion eligible for inline ghost completion: a non-`link` item
+ * whose label starts with `inputValue` (case-insensitive) but isn't equal to it.
+ * Shared by the ghost-text effect and ArrowRight completion.
+ */
+export function firstGhostSuggestion<T>(
+  list: T[],
+  inputValue: string,
+  getLabel: (item: T) => string,
+  getSuggestionType: (item: T) => SuggestionType | undefined,
+): T | undefined {
+  const needle = inputValue.toLowerCase();
+  return list.find((item) => {
+    const label = getLabel(item).toLowerCase();
+    return getSuggestionType(item) !== 'link' && label.startsWith(needle) && label !== needle;
+  });
+}
+
+/** Escape a user query for safe use inside a `RegExp`. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Wrap query matches in `<mark>` for the default suggestion renderer. Skipped for
+ * fuzzy mode (non-contiguous matches) and empty queries. Returns HTML.
+ */
+export function highlightLabel(label: string, query: string, matchMode: MatchMode): string {
+  if (!query || matchMode === 'fuzzy') return label;
+  const regex = new RegExp(`(${escapeRegExp(query)})`, 'gi');
+  return label.replace(regex, '<mark>$1</mark>');
+}

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

@@ -0,0 +1,134 @@
+import type React from 'react';
+
+import { firstGhostSuggestion } from './Autocomplete.helpers';
+import type { SuggestionType } from './Autocomplete.types';
+
+/**
+ * Everything a key handler needs. Kept as a flat context object so each handler
+ * stays a small pure function and the component's `onKeyDown` is a thin dispatch.
+ */
+export interface KeyContext<T> {
+  open: boolean;
+  activeIndex: number;
+  filteredSuggestions: T[];
+  maxVisibleItems: number;
+  allowFreeText: boolean;
+  inputValue: string;
+  ghost: string;
+  isInputFocused: boolean;
+  multiple: boolean;
+  selectedItems: T[];
+  getLabel: (item: T) => string;
+  getSuggestionType: (item: T) => SuggestionType | undefined;
+  setOpen: (open: boolean) => void;
+  setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+  setUserClosedDropdown: (closed: boolean) => void;
+  setInputValue: (value: string) => void;
+  setGhost: (ghost: string) => void;
+  setJustCompletedGhost: (done: boolean) => void;
+  debouncedOnChange: (value: string) => void;
+  selectItem: (item: T) => void;
+  onSelectedItemsChange?: (items: T[]) => void;
+}
+
+type KeyHandler<T> = (event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>) => void;
+
+/** True when there's a ghost remainder that can be accepted right now. */
+function canAcceptGhost<T>(ctx: KeyContext<T>): boolean {
+  return Boolean(ctx.ghost) && ctx.isInputFocused && ctx.filteredSuggestions.length > 0;
+}
+
+/** Commit a completed value: mark the ghost-complete flag, set + propagate, and close. */
+function commitCompletion<T>(ctx: KeyContext<T>, newValue: string): void {
+  ctx.setJustCompletedGhost(true);
+  ctx.setInputValue(newValue);
+  ctx.debouncedOnChange(newValue);
+  ctx.setGhost('');
+  ctx.setOpen(false);
+  ctx.setActiveIndex(-1);
+}
+
+const onArrowDown = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  event.preventDefault();
+  if (!ctx.open && ctx.filteredSuggestions.length > 0) {
+    ctx.setOpen(true);
+    ctx.setUserClosedDropdown(false);
+  }
+  const max = Math.min(ctx.filteredSuggestions.length - 1, ctx.maxVisibleItems - 1);
+  ctx.setActiveIndex((prev) => (prev < max ? prev + 1 : prev));
+};
+
+const onArrowUp = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  event.preventDefault();
+  ctx.setActiveIndex((prev) => (prev > 0 ? prev - 1 : -1));
+};
+
+const onEnter = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  event.preventDefault();
+  const inRange = ctx.open && ctx.activeIndex >= 0 && ctx.activeIndex < ctx.filteredSuggestions.length;
+  if (inRange) {
+    const selected = ctx.filteredSuggestions[ctx.activeIndex];
+    if (selected) ctx.selectItem(selected);
+  } else if (ctx.allowFreeText && ctx.inputValue.trim()) {
+    ctx.setOpen(false);
+  }
+};
+
+const onTab = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  // Tab completion preserves the user's typed case (input + ghost remainder).
+  if (!canAcceptGhost(ctx)) return;
+  event.preventDefault();
+  commitCompletion(ctx, ctx.inputValue + ctx.ghost);
+};
+
+const onArrowRight = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  // ArrowRight completion uses the suggestion's original case.
+  if (!canAcceptGhost(ctx)) return;
+  event.preventDefault();
+  const first = firstGhostSuggestion(
+    ctx.filteredSuggestions,
+    ctx.inputValue,
+    ctx.getLabel,
+    ctx.getSuggestionType,
+  );
+  commitCompletion(ctx, first ? ctx.getLabel(first) : ctx.inputValue);
+};
+
+const onEscape = <T,>(event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  event.preventDefault();
+  ctx.setOpen(false);
+  ctx.setActiveIndex(-1);
+  ctx.setUserClosedDropdown(true);
+  if (event.detail === 2) {
+    // Double escape clears the value.
+    ctx.setInputValue('');
+    ctx.debouncedOnChange('');
+  }
+};
+
+const onBackspace = <T,>(_event: React.KeyboardEvent<HTMLInputElement>, ctx: KeyContext<T>): void => {
+  if (ctx.multiple && ctx.inputValue === '' && ctx.selectedItems.length > 0) {
+    ctx.onSelectedItemsChange?.(ctx.selectedItems.slice(0, -1));
+  }
+};
+
+const KEY_HANDLERS: Record<string, KeyHandler<unknown>> = {
+  ArrowDown: onArrowDown,
+  ArrowUp: onArrowUp,
+  Enter: onEnter,
+  Tab: onTab,
+  ArrowRight: onArrowRight,
+  Escape: onEscape,
+  Backspace: onBackspace,
+};
+
+/** Dispatch a keydown to its handler (no-op during IME composition or unmapped keys). */
+export function handleAutocompleteKey<T>(
+  event: React.KeyboardEvent<HTMLInputElement>,
+  composition: boolean,
+  ctx: KeyContext<T>,
+): void {
+  if (composition) return;
+  const handler = KEY_HANDLERS[event.key] as KeyHandler<T> | undefined;
+  handler?.(event, ctx);
+}

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

@@ -0,0 +1,337 @@
+import LinkIcon from '@mui/icons-material/Link';
+import SearchIcon from '@mui/icons-material/Search';
+import {
+  Box,
+  Chip,
+  CircularProgress,
+  List,
+  ListItem,
+  ListItemText,
+  Paper,
+  Popper,
+  TextField,
+  Typography,
+} from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import { highlightLabel, type MatchMode } from './Autocomplete.helpers';
+import type { SuggestionItemState, SuggestionType } from './Autocomplete.types';
+
+const StyledPopper = styled(Popper)(({ theme }) => ({
+  zIndex: theme.zIndex.tooltip,
+  width: '100%',
+  maxHeight: 300,
+  overflow: 'auto',
+  // Popper.js writes the computed position (and stamps `data-popper-placement`)
+  // in a layout effect that can land AFTER the first paint. Until it does, the
+  // element would paint once unpositioned — at the offset-parent origin, far
+  // left and full width — then jump under the input, a visible per-keystroke
+  // flash as the list re-renders. Hide that unpositioned first frame; it becomes
+  // visible the instant popper assigns a placement.
+  '&:not([data-popper-placement])': { visibility: 'hidden' },
+}));
+
+const InlineSuggestionDisplay = styled('div')(() => ({
+  position: 'absolute',
+  pointerEvents: 'none',
+  left: '14px', // Match TextField padding
+  top: '50%',
+  transform: 'translateY(-50%)',
+  fontSize: 'inherit',
+  fontFamily: 'inherit',
+  whiteSpace: 'nowrap',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  zIndex: 1,
+}));
+
+const UserTextTwin = styled('span')({
+  visibility: 'hidden',
+});
+
+const GhostText = styled('span')(({ theme }) => ({
+  color: theme.palette.text.secondary,
+  opacity: 0.6,
+}));
+
+const ChipContainer = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: theme.spacing(0.5),
+  marginBottom: theme.spacing(1),
+}));
+
+/** Leading icon for a typed suggestion (search vs. link); null for untyped items. */
+export function suggestionTypeIcon(type: SuggestionType | undefined): React.ReactNode {
+  const sx = { color: 'text.secondary', flexShrink: 0 } as const;
+  if (type === 'link') return <LinkIcon fontSize="small" sx={sx} />;
+  if (type === 'search') return <SearchIcon fontSize="small" sx={sx} />;
+  return null;
+}
+
+/** The inline ghost-text overlay: an invisible twin of the typed text + the grey remainder. */
+function GhostOverlay({ inputValue, ghost }: { inputValue: string; ghost: string }): React.JSX.Element {
+  return (
+    <InlineSuggestionDisplay>
+      <UserTextTwin>{inputValue}</UserTextTwin>
+      <GhostText>{ghost}</GhostText>
+    </InlineSuggestionDisplay>
+  );
+}
+
+export interface AutocompleteInputProps {
+  id: string;
+  listId: string;
+  inputRef: React.RefObject<HTMLInputElement | null>;
+  inputValue: string;
+  ghost: string;
+  showGhost: boolean;
+  isInputFocused: boolean;
+  open: boolean;
+  activeDescendant: string | undefined;
+  isLoading: boolean;
+  disabled: boolean;
+  autoFocus: boolean;
+  placeholder: string;
+  startAdornment?: React.ReactNode;
+  inputAriaLabel?: string;
+  inputClassName?: string;
+  onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+  onFocus: () => void;
+  onBlur: () => void;
+  onCompositionStart: () => void;
+  onCompositionEnd: () => void;
+}
+
+/** The combobox text field plus its inline ghost-text overlay. */
+export function AutocompleteInput(props: AutocompleteInputProps): React.JSX.Element {
+  const showOverlay = Boolean(props.ghost) && props.showGhost && props.isInputFocused;
+  return (
+    <Box sx={{ position: 'relative' }}>
+      {showOverlay && <GhostOverlay inputValue={props.inputValue} ghost={props.ghost} />}
+      <TextField
+        ref={props.inputRef}
+        fullWidth
+        value={props.inputValue}
+        onChange={props.onChange}
+        onKeyDown={props.onKeyDown}
+        onFocus={props.onFocus}
+        onBlur={props.onBlur}
+        onCompositionStart={props.onCompositionStart}
+        onCompositionEnd={props.onCompositionEnd}
+        placeholder={props.placeholder}
+        disabled={props.disabled}
+        autoFocus={props.autoFocus}
+        className={props.inputClassName}
+        InputProps={{
+          startAdornment: props.startAdornment,
+          endAdornment: props.isLoading ? <CircularProgress size={20} /> : undefined,
+        }}
+        inputProps={{
+          role: 'combobox',
+          'aria-expanded': props.open,
+          'aria-controls': props.open ? props.listId : undefined,
+          'aria-activedescendant': props.activeDescendant,
+          'aria-autocomplete': 'list',
+          'aria-label': props.inputAriaLabel,
+          id: props.id,
+        }}
+      />
+    </Box>
+  );
+}
+
+/** Selected-item chips (multiple mode). */
+export function ChipList<T>({
+  items,
+  getKey,
+  getLabel,
+  onRemove,
+  chipClassName,
+}: {
+  items: T[];
+  getKey: (item: T) => string;
+  getLabel: (item: T) => string;
+  onRemove: (item: T) => void;
+  chipClassName?: string;
+}): React.JSX.Element {
+  return (
+    <ChipContainer data-testid="selected-items-container">
+      {items.map((item, index) => (
+        <Chip
+          key={`${getKey(item)}-${index}`}
+          label={getLabel(item)}
+          onDelete={() => onRemove(item)}
+          size="small"
+          className={chipClassName}
+          data-testid={`selected-chip-${index}`}
+        />
+      ))}
+    </ChipContainer>
+  );
+}
+
+/** Default suggestion row: per-type icon + highlighted label + optional description. */
+export function DefaultSuggestion<T>({
+  item,
+  state,
+  getLabel,
+  getDescription,
+  getSuggestionType,
+  matchMode,
+}: {
+  item: T;
+  state: SuggestionItemState;
+  getLabel: (item: T) => string;
+  getDescription?: (item: T) => string | undefined;
+  getSuggestionType: (item: T) => SuggestionType | undefined;
+  matchMode: MatchMode;
+}): React.JSX.Element {
+  const label = getLabel(item);
+  const description = getDescription?.(item);
+  const displayLabel = highlightLabel(label, state.query, matchMode);
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 1,
+        width: '100%',
+        // Bold the matched prefix (not a yellow <mark> highlight).
+        '& mark': { backgroundColor: 'transparent', color: 'inherit', fontWeight: 700 },
+      }}
+    >
+      {suggestionTypeIcon(getSuggestionType(item))}
+      <ListItemText
+        primary={<span dangerouslySetInnerHTML={{ __html: displayLabel }} />}
+        secondary={description}
+      />
+    </Box>
+  );
+}
+
+/** A "Loading…" row shown while async suggestions resolve. */
+export function LoadingRow(): React.JSX.Element {
+  return (
+    <ListItem>
+      <Box display="flex" alignItems="center" gap={1}>
+        <CircularProgress size={16} />
+        <Typography variant="body2" color="text.secondary">
+          Loading...
+        </Typography>
+      </Box>
+    </ListItem>
+  );
+}
+
+/** The empty "No results found" row. */
+export function NoResultsRow(): React.JSX.Element {
+  return (
+    <ListItem>
+      <Typography variant="body2" color="text.secondary">
+        No results found
+      </Typography>
+    </ListItem>
+  );
+}
+
+/** Keep the Popper the same width as its anchor input. */
+const SAME_WIDTH_MODIFIER = {
+  name: 'sameWidth',
+  enabled: true,
+  fn: ({ state }: { state: { elements: { reference?: unknown }; styles: { popper?: Record<string, string> }; rects: { reference: { width: number } } } }) => {
+    if (state.elements.reference && state.styles.popper) {
+      state.styles.popper.width = `${state.rects.reference.width}px`;
+    }
+  },
+  phase: 'beforeWrite' as const,
+  requires: ['computeStyles'],
+};
+
+export interface SuggestionListBoxProps<T> {
+  open: boolean;
+  anchorEl: HTMLElement | null;
+  portal: boolean | { container?: HTMLElement };
+  listRef: React.RefObject<HTMLUListElement | null>;
+  listId: string;
+  optionIdPrefix: string;
+  items: T[];
+  activeIndex: number;
+  isLoading: boolean;
+  showNoResults: boolean;
+  getKey: (item: T) => string;
+  onSelect: (item: T) => void;
+  onHover: (index: number) => void;
+  renderItem: (item: T, active: boolean) => React.ReactNode;
+  listClassName?: string;
+  itemClassName?: string;
+  activeItemClassName?: string;
+}
+
+/** The suggestions dropdown: a same-width Popper with the option list + loading/empty rows. */
+export function SuggestionListBox<T>({
+  open,
+  anchorEl,
+  portal,
+  listRef,
+  listId,
+  optionIdPrefix,
+  items,
+  activeIndex,
+  isLoading,
+  showNoResults,
+  getKey,
+  onSelect,
+  onHover,
+  renderItem,
+  listClassName,
+  itemClassName,
+  activeItemClassName,
+}: SuggestionListBoxProps<T>): React.JSX.Element {
+  return (
+    <StyledPopper
+      open={open}
+      anchorEl={anchorEl}
+      placement="bottom-start"
+      disablePortal={!portal}
+      modifiers={[SAME_WIDTH_MODIFIER]}
+    >
+      <Paper elevation={8} className={listClassName} data-testid="suggestions-dropdown">
+        <List
+          ref={listRef}
+          role="listbox"
+          id={listId}
+          dense
+          sx={{ maxHeight: 300, overflow: 'auto' }}
+          data-testid="suggestions-list"
+        >
+          {items.map((item, index) => (
+            <ListItem
+              key={getKey(item)}
+              id={`${optionIdPrefix}-${index}`}
+              role="option"
+              component="div"
+              sx={{
+                cursor: 'pointer',
+                backgroundColor: index === activeIndex ? 'action.hover' : 'transparent',
+                '&:hover': { backgroundColor: 'action.hover' },
+              }}
+              aria-selected={index === activeIndex}
+              onMouseDown={(e) => e.preventDefault()}
+              onClick={() => onSelect(item)}
+              onMouseEnter={() => onHover(index)}
+              className={`${itemClassName} ${index === activeIndex ? activeItemClassName : ''}`}
+              data-testid={`suggestion-item-${index}`}
+            >
+              {renderItem(item, index === activeIndex)}
+            </ListItem>
+          ))}
+          {isLoading && <LoadingRow />}
+          {showNoResults && <NoResultsRow />}
+        </List>
+      </Paper>
+    </StyledPopper>
+  );
+}