@soyfri/shared-library 1.5.0 → 2.0.0-beta.1

package/src/components/Autocomplete/Autocomplete.tsx

@@ -1,15 +1,31 @@
-import React from "react";
+import React, {
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type SyntheticEvent,
+} from 'react';
 import {
-  Autocomplete,
+  Autocomplete as MuiAutocomplete,
   TextField,
-  Chip,
-  Avatar,
-  Box,
-  Typography,
-  CircularProgress,
-} from "@mui/material";
-import ClearIcon from "@mui/icons-material/Clear";
+  type TextFieldProps,
+} from '@mui/material';
+import { useTheme, type SxProps, type Theme } from '@mui/material/styles';
+import { Controller, type Control, type RegisterOptions } from 'react-hook-form';
 
+import { buildAutocompleteSx } from './Autocomplete.sx';
+import {
+  areResolvedValuesEqual,
+  isResolvedValueEmpty,
+  resolveMultipleValue,
+  resolveSingleValue,
+} from './Autocomplete.helpers';
+import { resolvePreset } from '../_shared/resolvePreset';
+import { AutocompleteOption } from './_parts/AutocompleteOption';
+import { AutocompleteChips } from './_parts/AutocompleteChips';
+import { AutocompleteLoader } from './_parts/AutocompleteLoader';
+
+// ── Tipos de dominio ─────────────────────────────────────────────────────
 export interface SelectOption {
   value: string | number;
   label: string;
@@ -19,121 +35,327 @@ export interface SelectOption {
   [key: string]: any;
 }
 
-type RenderOptionItem = (item: SelectOption) => React.ReactNode;
-type RenderChipLabel = (item: SelectOption) => React.ReactNode;
+export type LabelPosition = 'outside' | 'floating';
+export type AutocompleteSize = 'small' | 'medium';
+
+// ── Render slots ─────────────────────────────────────────────────────────
+export type RenderOptionItem = (item: SelectOption) => ReactNode;
+export type RenderChipLabel = (item: SelectOption) => ReactNode;
 
-interface AutocompleteProps<
-  TValue extends SelectOption["value"] = SelectOption["value"],
-> {
+// ── Props base ───────────────────────────────────────────────────────────
+export type BaseAutocompleteProps<
+  _TValue extends SelectOption['value'] = SelectOption['value'],
+> = {
   label?: string;
-  value: TValue | TValue[];
-  onChange: (val: TValue | TValue[]) => void;
-  options?: SelectOption[];
+  options: SelectOption[];
   placeholder?: string;
   multiple?: boolean;
   disabled?: boolean;
+  readOnly?: boolean;
   loading?: boolean;
   error?: boolean;
   helperText?: string;
   maxChipsToShow?: number;
   renderOptionItem?: RenderOptionItem;
   renderChipLabel?: RenderChipLabel;
+  /** Border radius del input. Default: 10. */
+  borderRadius?: number | string;
+  /** "outside" (default) = label arriba del input; "floating" = comportamiento nativo MUI. */
+  labelPosition?: LabelPosition;
+  /** Tamaño del TextField. Default: 'small'. */
+  size?: AutocompleteSize;
+  /** Texto cuando no hay coincidencias. */
+  noOptionsText?: ReactNode;
+  /** Texto cuando está cargando. */
+  loadingText?: ReactNode;
+  sx?: SxProps<Theme>;
+  className?: string;
+  /**
+   * Nombre del preset de estilo registrado en `theme.styles.Autocomplete`.
+   * - `"default"` (o ausente) = estilo built-in del paquete.
+   * - Cualquier otro string = mergea el preset encima del estilo built-in.
+   */
+  preset?: string;
+  /** Props para el TextField subyacente. */
+  textFieldProps?: Partial<TextFieldProps>;
+
+  // ── Búsqueda asíncrona / remota ──────────────────────────────────────
+  /** Se dispara cada vez que el usuario escribe. Útil para llamadas a servicios
+   *  (debounce recomendado en el consumer). */
+  onInputChange?: (
+    event: SyntheticEvent,
+    value: string,
+    reason: 'input' | 'reset' | 'clear' | 'blur' | 'selectOption' | 'removeOption',
+  ) => void;
+  /** Valor controlado del texto de búsqueda. */
+  inputValue?: string;
+  /** Filtro custom. Para búsqueda remota pasar `(x) => x` y confiar sólo en el servicio. */
+  filterOptions?: (options: SelectOption[], state: any) => SelectOption[];
+  /** Permite valores arbitrarios (no solo de la lista). */
+  freeSolo?: boolean;
+  open?: boolean;
+  onOpen?: (event: SyntheticEvent) => void;
+  onClose?: (event: SyntheticEvent, reason: string) => void;
+};
+
+// ── Variantes discriminadas (RHF vs controlado) ──────────────────────────
+export interface ControlledAutocompleteProps<
+  TValue extends SelectOption['value'] = SelectOption['value'],
+> extends BaseAutocompleteProps<TValue> {
+  value: TValue | TValue[] | null;
+  onChange: (val: TValue | TValue[] | null) => void;
+  name?: string;
+  control?: never;
+  validation?: never;
 }
 
-export function AutocompleteSelect<
-  TValue extends SelectOption["value"] = SelectOption["value"],
+export interface RHFAutocompleteProps<
+  TValue extends SelectOption['value'] = SelectOption['value'],
+> extends BaseAutocompleteProps<TValue> {
+  name: string;
+  control: Control<any>;
+  validation?: RegisterOptions;
+  value?: never;
+  onChange?: never;
+}
+
+// ── API pública final ────────────────────────────────────────────────────
+export type AutocompleteProps<
+  TValue extends SelectOption['value'] = SelectOption['value'],
+> = ControlledAutocompleteProps<TValue> | RHFAutocompleteProps<TValue>;
+
+export function Autocomplete<
+  TValue extends SelectOption['value'] = SelectOption['value'],
 >(props: AutocompleteProps<TValue>) {
   const {
     label,
-    options = [],
-    value,
-    onChange,
+    options,
     placeholder,
     multiple = false,
     disabled = false,
+    readOnly = false,
     loading = false,
-    error = false,
+    error: errorProp = false,
     helperText,
+    maxChipsToShow = 3,
     renderOptionItem,
     renderChipLabel,
-    maxChipsToShow = 3,
-  } = props;
+    borderRadius = 10,
+    labelPosition = 'outside',
+    size = 'small',
+    noOptionsText = 'No hay opciones',
+    loadingText,
+    sx,
+    className,
+    preset,
+    textFieldProps,
+    onInputChange,
+    inputValue,
+    filterOptions,
+    freeSolo,
+    open,
+    onOpen,
+    onClose,
+  } = props as BaseAutocompleteProps<TValue>;
 
-  const renderTags = (value: SelectOption[], getTagProps: any) => {
-    const displayed = value.slice(0, maxChipsToShow);
-    const hidden = value.length - maxChipsToShow;
+  // Focus tracking para mostrar placeholder solo cuando el label sube.
+  const [isFocused, setIsFocused] = useState(false);
 
-    return (
-      <>
-        {displayed.map((option, index) => (
-          <Chip
-            {...getTagProps({ index })}
-            key={option.value}
-            label={renderChipLabel ? renderChipLabel(option) : option.label}
-            avatar={option.img ? <Avatar src={option.img} /> : undefined}
-            deleteIcon={<ClearIcon />}
-          />
-        ))}
+  // Cache interno de opciones vistas (indexado por value). Crítico para async
+  // multiple: cuando `options` cambian por un nuevo search, los items ya
+  // seleccionados no desaparecen de los chips porque los recordamos acá.
+  const seenOptionsRef = useRef<Map<SelectOption['value'], SelectOption>>(
+    new Map(),
+  );
+  for (const opt of options) {
+    seenOptionsRef.current.set(opt.value, opt);
+  }
 
-        {hidden > 0 && <Chip label={`+${hidden} más`} />}
-      </>
-    );
-  };
+  // Pool de opciones para resolver values (merge de options + vistas).
+  const resolvePool = useMemo<SelectOption[]>(() => {
+    const merged = new Map(seenOptionsRef.current);
+    for (const opt of options) merged.set(opt.value, opt);
+    return Array.from(merged.values());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options]);
 
-  const renderOption = (propsLi: any, option: SelectOption) => (
-    <li {...propsLi} key={option.value}>
-      {renderOptionItem ? renderOptionItem(option) : option.label}
-    </li>
+  // Estabiliza la referencia del resolvedValue que pasamos a MUI Autocomplete.
+  // MUI compara value con `!==`: una referencia nueva con mismo contenido
+  // dispara resetInputValue() y borra el texto que el usuario está escribiendo.
+  const prevResolvedRef = useRef<SelectOption[] | SelectOption | null>(
+    multiple ? [] : null,
   );
 
-  const renderAutocomplete = (value: any, onChange: any) => (
-    <Autocomplete
-      multiple={multiple}
-      options={options}
-      value={
-        multiple
-          ? (options.filter((o) =>
-              (value as string[] | undefined)?.includes(o.value as string),
-            ) ?? [])
-          : (options.find((o) => o.value === value) ?? null)
-      }
-      disabled={disabled}
-      loading={loading}
-      getOptionLabel={(opt) => opt?.label ?? ""}
-      isOptionEqualToValue={(a, b) => a.value === b.value}
-      onChange={onChange}
-      renderOption={renderOption}
-      renderTags={multiple ? renderTags : undefined}
-      noOptionsText="No hay opciones"
-      loadingText={
-        <Box sx={{ display: "flex", alignItems: "center", gap: 1 }}>
-          <CircularProgress size={20} />
-          <Typography>Cargando...</Typography>
-        </Box>
-      }
-      renderInput={(params) => (
-        <TextField
-          {...params}
-          label={label}
-          placeholder={placeholder}
-          error={error}
-          helperText={helperText}
-        />
-      )}
-    />
-  );
+  const stabilizeResolved = (
+    newVal: SelectOption[] | SelectOption | null,
+  ): any => {
+    if (areResolvedValuesEqual(prevResolvedRef.current, newVal, multiple)) {
+      return prevResolvedRef.current;
+    }
+    prevResolvedRef.current = newVal;
+    return newVal;
+  };
 
-  const handleChangeInternal = (event: any, newValue: any) => {
+  const theme = useTheme();
+  const presetSx = resolvePreset('Autocomplete', preset, theme);
+
+  const mergedSx = [
+    buildAutocompleteSx(borderRadius, labelPosition),
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  const renderAutocomplete = (
+    resolvedValue: any,
+    handleChange: (event: any, newValue: any) => void,
+    onBlur?: () => void,
+    inputRef?: React.Ref<any>,
+    rhfError?: boolean,
+    rhfHelperText?: string,
+  ) => {
+    const finalError = !!rhfError || !!errorProp;
+    const finalHelperText = rhfHelperText || helperText;
+
+    const isEmpty = isResolvedValueEmpty(resolvedValue, multiple);
+    const showPlaceholder = isEmpty && isFocused && !!placeholder;
+
+    return (
+      <MuiAutocomplete
+        multiple={multiple}
+        options={options}
+        value={resolvedValue}
+        disabled={disabled}
+        readOnly={readOnly}
+        loading={loading}
+        className={className}
+        sx={mergedSx}
+        freeSolo={freeSolo as any}
+        open={open}
+        onOpen={onOpen}
+        onClose={onClose}
+        inputValue={inputValue}
+        onInputChange={onInputChange}
+        filterOptions={filterOptions as any}
+        getOptionLabel={(opt) =>
+          typeof opt === 'string' ? opt : (opt?.label ?? '')
+        }
+        isOptionEqualToValue={(a, b) => a?.value === b?.value}
+        getOptionDisabled={(opt) => !!opt?.disabled}
+        onChange={handleChange}
+        onFocus={() => setIsFocused(true)}
+        onBlur={() => {
+          setIsFocused(false);
+          onBlur?.();
+        }}
+        renderOption={(liProps, option) => (
+          <AutocompleteOption
+            liProps={liProps as any}
+            option={option}
+            customRender={renderOptionItem}
+          />
+        )}
+        renderTags={
+          multiple
+            ? (value, getTagProps) => (
+                <AutocompleteChips
+                  value={value}
+                  getTagProps={getTagProps}
+                  size={size}
+                  maxChipsToShow={maxChipsToShow}
+                  renderChipLabel={renderChipLabel}
+                />
+              )
+            : undefined
+        }
+        noOptionsText={noOptionsText}
+        loadingText={loadingText ?? <AutocompleteLoader />}
+        renderInput={(params) => (
+          <TextField
+            {...params}
+            label={label}
+            size={size}
+            variant="outlined"
+            placeholder={showPlaceholder ? placeholder : undefined}
+            error={finalError}
+            helperText={finalHelperText}
+            inputRef={inputRef}
+            {...textFieldProps}
+            InputLabelProps={{
+              ...(params.InputLabelProps as Record<string, any>),
+              ...(textFieldProps?.InputLabelProps as Record<string, any> | undefined),
+              shrink:
+                labelPosition === 'outside'
+                  ? !isEmpty || isFocused
+                  : (params.InputLabelProps as any)?.shrink,
+            }}
+          />
+        )}
+      />
+    );
+  };
+
+  const handleControlledChange = (_event: any, newValue: any) => {
+    const onChange = (props as ControlledAutocompleteProps<TValue>).onChange;
     if (multiple) {
-      const values = (newValue ?? []).map((opt: any) => opt.value);
-      (onChange as (val: TValue[]) => void)?.(values);
+      const values = (newValue ?? []).map((opt: SelectOption) => opt.value as TValue);
+      onChange(values);
     } else {
-      const value = newValue?.value ?? "";
-      (onChange as (val: TValue) => void)?.(value);
+      onChange((newValue?.value ?? null) as TValue | null);
     }
   };
 
-  return renderAutocomplete(value, handleChangeInternal);
+  // --- RHF mode ---
+  if ('control' in props && props.control) {
+    const { name, control, validation } = props as RHFAutocompleteProps<TValue>;
+    return (
+      <Controller
+        name={name}
+        control={control}
+        rules={validation}
+        render={({ field, fieldState: { error: fieldError } }) => {
+          const resolvedValue = stabilizeResolved(
+            multiple
+              ? resolveMultipleValue(resolvePool, field.value)
+              : resolveSingleValue(resolvePool, field.value),
+          );
+
+          const handleChange = (_event: any, newValue: any) => {
+            if (multiple) {
+              field.onChange(
+                (newValue ?? []).map((opt: SelectOption) => opt.value),
+              );
+            } else {
+              field.onChange(newValue?.value ?? null);
+            }
+          };
+
+          return renderAutocomplete(
+            resolvedValue,
+            handleChange,
+            field.onBlur,
+            field.ref,
+            !!fieldError,
+            fieldError?.message,
+          );
+        }}
+      />
+    );
+  }
+
+  // --- Controlled mode ---
+  const controlledValue = (props as ControlledAutocompleteProps<TValue>).value;
+  const resolvedValue = stabilizeResolved(
+    multiple
+      ? resolveMultipleValue(resolvePool, controlledValue as SelectOption['value'][])
+      : resolveSingleValue(resolvePool, controlledValue as SelectOption['value']),
+  );
+
+  return renderAutocomplete(resolvedValue, handleControlledChange);
 }
 
-export default AutocompleteSelect;
+/**
+ * @deprecated Usar `Autocomplete` en su lugar. Alias mantenido para retro-compatibilidad.
+ */
+export const AutocompleteSelect = Autocomplete;
+
+export default Autocomplete;

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

@@ -0,0 +1,13 @@
+// Re-export barrel para compatibilidad con imports antiguos.
+// Los tipos ahora viven dentro de Autocomplete.tsx.
+export type {
+  SelectOption,
+  LabelPosition,
+  AutocompleteSize,
+  RenderOptionItem,
+  RenderChipLabel,
+  BaseAutocompleteProps,
+  ControlledAutocompleteProps,
+  RHFAutocompleteProps,
+  AutocompleteProps,
+} from './Autocomplete';

package/src/components/Autocomplete/_parts/AutocompleteChips.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { Avatar, Chip } from '@mui/material';
+import ClearIcon from '@mui/icons-material/Clear';
+
+import type {
+  SelectOption,
+  RenderChipLabel,
+  AutocompleteSize,
+} from '../Autocomplete';
+
+interface AutocompleteChipsProps {
+  value: SelectOption[];
+  getTagProps: (args: { index: number }) => Record<string, any>;
+  size: AutocompleteSize;
+  maxChipsToShow: number;
+  renderChipLabel?: RenderChipLabel;
+}
+
+/**
+ * Render de los chips del Autocomplete en modo multiple.
+ * Trunca después de `maxChipsToShow` con un chip "+N más".
+ * El `getTagProps({ index })` viene de MUI y contiene el handler de delete,
+ * la key, etc. — se spreadea tal cual al Chip.
+ */
+export const AutocompleteChips: React.FC<AutocompleteChipsProps> = ({
+  value,
+  getTagProps,
+  size,
+  maxChipsToShow,
+  renderChipLabel,
+}) => {
+  const displayed = value.slice(0, maxChipsToShow);
+  const hidden = value.length - maxChipsToShow;
+
+  return (
+    <>
+      {displayed.map((option, index) => {
+        const tagProps = getTagProps({ index });
+        return (
+          <Chip
+            {...tagProps}
+            key={option.value}
+            size={size}
+            label={renderChipLabel ? renderChipLabel(option) : option.label}
+            avatar={option.img ? <Avatar src={option.img} /> : undefined}
+            deleteIcon={<ClearIcon />}
+          />
+        );
+      })}
+      {hidden > 0 && <Chip size={size} label={`+${hidden} más`} />}
+    </>
+  );
+};
+
+export default AutocompleteChips;

package/src/components/Autocomplete/_parts/AutocompleteLoader.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { Box, CircularProgress, Typography } from '@mui/material';
+
+/**
+ * Loader por defecto para el `loadingText` del Autocomplete.
+ * El consumer puede sobrescribirlo pasando `loadingText` al componente padre.
+ */
+export const AutocompleteLoader: React.FC<{ text?: string }> = ({
+  text = 'Cargando...',
+}) => (
+  <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+    <CircularProgress size={16} />
+    <Typography variant="body2">{text}</Typography>
+  </Box>
+);
+
+export default AutocompleteLoader;

package/src/components/Autocomplete/_parts/AutocompleteOption.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import type { SelectOption, RenderOptionItem } from '../Autocomplete';
+
+interface AutocompleteOptionProps {
+  liProps: React.HTMLAttributes<HTMLLIElement> & { key?: React.Key };
+  option: SelectOption;
+  customRender?: RenderOptionItem;
+}
+
+/**
+ * Render por defecto de un <li> del dropdown del Autocomplete.
+ * Se expone como componente para testear y extender fácilmente, pero MUI
+ * lo llama desde `renderOption={(props, option) => ...}` en el padre.
+ *
+ * El `key` lo manejamos nosotros (no spreadeamos junto al resto) porque MUI
+ * lo inyecta como parte de `propsLi` y React exige que sea prop directo.
+ */
+export const AutocompleteOption: React.FC<AutocompleteOptionProps> = ({
+  liProps,
+  option,
+  customRender,
+}) => {
+  const { key: _ignored, ...liRest } = liProps;
+  return (
+    <li key={option.value} {...liRest}>
+      {customRender ? customRender(option) : option.label}
+    </li>
+  );
+};
+
+export default AutocompleteOption;

package/src/components/Autocomplete/index.ts

@@ -1 +1,12 @@
-export { default as Autocomplete} from './Autocomplete'
+export { Autocomplete, AutocompleteSelect, default } from './Autocomplete';
+export type {
+  AutocompleteProps,
+  SelectOption,
+  BaseAutocompleteProps,
+  ControlledAutocompleteProps,
+  RHFAutocompleteProps,
+  RenderOptionItem,
+  RenderChipLabel,
+  LabelPosition,
+  AutocompleteSize,
+} from './Autocomplete.types';