@soyfri/shared-library 2.0.0-beta.2 → 2.0.0-beta.20

package/src/components/Autocomplete/Autocomplete.sx.ts

@@ -0,0 +1,30 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+import { buildFormFieldSx } from '../_shared/formField.sx';
+import type { LabelPosition } from './Autocomplete';
+
+/**
+ * Builder del sx del Autocomplete. Reutiliza `buildFormFieldSx` y añade
+ * los paddings propios del Autocomplete (chips + input interno).
+ */
+export const buildAutocompleteSx = (
+  borderRadius: number | string,
+  labelPosition: LabelPosition,
+): SxProps<Theme> =>
+  buildFormFieldSx({
+    borderRadius,
+    labelPosition,
+    extraOutsideSx: {
+      // El input interno del Autocomplete.
+      '& .MuiAutocomplete-input': {
+        paddingTop: '4px',
+        paddingBottom: '4px',
+      },
+
+      // Contenedor del input (donde viven los chips en modo multiple).
+      '& .MuiAutocomplete-inputRoot': {
+        paddingTop: '4px',
+        paddingBottom: '4px',
+      },
+    },
+  });

package/src/components/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,393 @@
+import React, {
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type SyntheticEvent,
+} from 'react';
+import {
+  Autocomplete as MuiAutocomplete,
+  TextField,
+  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;
+  img?: string;
+  disabled?: boolean;
+  group?: string;
+  [key: string]: any; //campos extras que puede tener la opcion
+}
+
+export type LabelPosition = 'outside' | 'floating';
+export type AutocompleteSize = 'small' | 'medium';
+
+// ── Render slots ─────────────────────────────────────────────────────────
+export type RenderOptionItem = (item: SelectOption) => ReactNode;
+export type RenderChipLabel = (item: SelectOption) => ReactNode;
+
+// ── Props base ───────────────────────────────────────────────────────────
+export type BaseAutocompleteProps<
+  _TValue extends SelectOption['value'] = SelectOption['value'],
+> = {
+  label?: string;
+  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>;
+  /**
+   * 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 interface RHFAutocompleteProps<
+  TValue extends SelectOption['value'] = SelectOption['value'],
+> extends BaseAutocompleteProps<TValue> {
+  name: string;
+  // `any` plano (no `Control<any>`): RHF tipa `Control<T>` con generics en
+  // posiciones tanto contravariantes como covariantes (ej. `_subjects.state`).
+  // Cuando el componente o su uso involucra generics adicionales, TS se
+  // confunde narroweando el discriminated union y `Control<any>` no logra
+  // absorber `Control<MyForm>` en la comparación estructural profunda. El
+  // `any` plano elimina ese ruido. RHF adentro sigue teniendo sus tipos
+  // fuertes — solo degradamos la superficie del prop del componente.
+  control: any;
+  validation?: RegisterOptions;
+  /**
+   * Side-effect que corre después de que RHF actualiza el form state.
+   * Útil para cascadas entre campos. NO reemplaza al handler de RHF.
+   */
+  onValueChange?: (val: TValue | TValue[] | null) => void;
+  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,
+    placeholder,
+    multiple = false,
+    disabled = false,
+    readOnly = false,
+    loading = false,
+    error: errorProp = false,
+    helperText,
+    maxChipsToShow = 3,
+    renderOptionItem,
+    renderChipLabel,
+    borderRadius = 10,
+    labelPosition = 'outside',
+    size = 'small',
+    noOptionsText = 'No hay opciones',
+    loadingText,
+    sx,
+    preset,
+    textFieldProps,
+    onInputChange,
+    inputValue,
+    filterOptions,
+    freeSolo,
+    open,
+    onOpen,
+    onClose,
+  } = props as BaseAutocompleteProps<TValue>;
+
+  // Focus tracking para mostrar placeholder solo cuando el label sube.
+  const [isFocused, setIsFocused] = useState(false);
+
+  // 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);
+  }
+
+  // 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());
+  }, [options]);
+
+  // 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 stabilizeResolved = (
+    newVal: SelectOption[] | SelectOption | null,
+  ): SelectOption[] | SelectOption | null => {
+    if (areResolvedValuesEqual(prevResolvedRef.current, newVal, multiple)) {
+      return prevResolvedRef.current;
+    }
+    prevResolvedRef.current = newVal;
+    return newVal;
+  };
+
+  const theme = useTheme();
+  const presetSx = resolvePreset('Autocomplete', preset, theme);
+
+  const mergedSx = [
+    ...(presetSx ? [presetSx] : [buildAutocompleteSx(borderRadius, labelPosition)]),
+    ...(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}
+        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) => {
+          if (typeof a === 'string' || typeof b === 'string') return a === b;
+          return a?.value === b?.value;
+        }}
+        getOptionDisabled={(opt) =>
+          typeof opt === 'string' ? false : !!opt?.disabled
+        }
+        onChange={handleChange}
+        onFocus={() => setIsFocused(true)}
+        onBlur={() => {
+          setIsFocused(false);
+          onBlur?.();
+        }}
+        renderOption={(liProps, option) => {
+          // MUI inyecta la `key` dentro de `liProps`. React necesita la key
+          // en el elemento más externo que devuelve `renderOption` (acá el
+          // wrapper), no en el `<li>` interno. La extraemos acá y se la
+          // pasamos al wrapper; el resto de `liProps` viaja al `<li>`.
+          const { key, ...liRest } = liProps as React.HTMLAttributes<HTMLLIElement> & {
+            key?: React.Key;
+          };
+          return (
+            <AutocompleteOption
+              key={key}
+              liProps={liRest}
+              option={option}
+              customRender={renderOptionItem}
+            />
+          );
+        }}
+        renderValue={
+          multiple
+            ? (value, getItemProps) => (
+              <AutocompleteChips
+                value={value as SelectOption[]}
+                getTagProps={getItemProps}
+                size={size}
+                maxChipsToShow={maxChipsToShow}
+                renderChipLabel={renderChipLabel}
+              />
+            )
+            : undefined
+        }
+        noOptionsText={noOptionsText}
+        loadingText={loadingText ?? <AutocompleteLoader />}
+        renderInput={(params) => (
+          // @ts-ignore — Ref<any> type mismatch between @types/react versions in monorepo
+          <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,
+            }}
+          />
+        )}
+      />
+    );
+  };
+
+  //obtiene el primitivo primero
+  const extractValue = (opt: any) =>
+    typeof opt === 'string' ? opt : (opt?.value ?? null);
+
+  const handleControlledChange = (_event: any, newValue: any) => {
+    const onChange = (props as ControlledAutocompleteProps<TValue>).onChange;
+    if (multiple) {
+      const values = (newValue ?? []).map(
+        (opt: SelectOption | string) => extractValue(opt) as TValue,
+      );
+      onChange(values);
+    } else {
+      onChange(extractValue(newValue) as TValue | null);
+    }
+  };
+
+  // --- RHF mode ---
+  if ('control' in props && props.control) {
+    const { name, control, validation, onValueChange } =
+      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) {
+              const next = (newValue ?? []).map(
+                (opt: SelectOption | string) => extractValue(opt),
+              ) as TValue[];
+              field.onChange(next);
+              onValueChange?.(next);
+            } else {
+              const next = extractValue(newValue) as TValue | null;
+              field.onChange(next);
+              onValueChange?.(next);
+            }
+          };
+
+          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);
+}
+
+/** Alias de `Autocomplete`. Ambos nombres son equivalentes. */
+export const AutocompleteSelect = Autocomplete;
+
+export default 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 { key: _ignored, ...tagProps } = getTagProps({ index });
+        return (
+          <Chip
+            key={option.value}
+            {...tagProps}
+            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,29 @@
+import React from 'react';
+import type { SelectOption, RenderOptionItem } from '../Autocomplete';
+
+interface AutocompleteOptionProps {
+  liProps: React.HTMLAttributes<HTMLLIElement>;
+  option: SelectOption;
+  customRender?: RenderOptionItem;
+}
+
+/**
+ * Render por defecto de un `<li>` del dropdown del Autocomplete.
+ * MUI lo invoca desde `renderOption={(props, option) => ...}` en el padre.
+ *
+ * La `key` la maneja el padre (`renderOption` en Autocomplete.tsx). Este
+ * componente solo recibe los props restantes del `<li>` para spread.
+ */
+export const AutocompleteOption: React.FC<AutocompleteOptionProps> = ({
+  liProps,
+  option,
+  customRender,
+}) => {
+  return (
+    <li {...liProps}>
+      {customRender ? customRender(option) : option.label}
+    </li>
+  );
+};
+
+export default AutocompleteOption;

package/src/components/Autocomplete/index.ts

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

package/src/components/Avatar/Avatar.definitions.ts

@@ -0,0 +1,162 @@
+export const DefaultAvatarDefinition = `
+import { Avatar } from './Avatar';
+
+export const DefaultAvatarExample = () => (
+    <Avatar
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=1' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=2' },
+        ]}
+    />
+);
+`;
+
+export const WithTypeAndTextDefinition = `
+import { Avatar } from './Avatar';
+
+export const WithTypeAndTextExample = () => (
+    <Avatar
+        type="Owner"
+        items={[{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }]}
+        showText
+    />
+);
+`;
+
+export const WithBadgesAndTooltipDefinition = `
+import { Avatar } from './Avatar';
+
+export const WithBadgesAndTooltipExample = () => (
+    <Avatar
+        showTooltip
+        items={[
+            { text: 'John D.', badge: 'JD', backgroundColor: '#EF5350', color: '#fff' },
+            { text: 'Alice B.', badge: 'AB', backgroundColor: '#AB47BC', color: '#fff' },
+        ]}
+    />
+);
+`;
+
+export const SizeSmallDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeSmallExample = () => (
+    <Avatar
+        size="sm"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=11' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=12' },
+            { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=13' },
+        ]}
+    />
+);
+`;
+
+export const SizeMediumDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeMediumExample = () => (
+    <Avatar
+        size="md"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=21' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=22' },
+            { text: 'User Three', imageUrl: 'https://i.pravatar.cc/150?img=23' },
+        ]}
+    />
+);
+`;
+
+export const SizeLargeDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeLargeExample = () => (
+    <Avatar
+        size="lg"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=31' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=32' },
+        ]}
+    />
+);
+`;
+
+export const SizeExtraLargeDefinition = `
+import { Avatar } from './Avatar';
+
+export const SizeExtraLargeExample = () => (
+    <Avatar
+        size="xl"
+        items={[{ text: 'Maria', imageUrl: 'https://i.pravatar.cc/150?img=5' }]}
+        showText={false}
+    />
+);
+`;
+
+export const NumericSizeDefinition = `
+import { Avatar } from './Avatar';
+
+export const NumericSizeExample = () => (
+    <Avatar
+        size={72}
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=41' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=42' },
+        ]}
+        showText={false}
+    />
+);
+`;
+
+export const FallbackIconDefinition = `
+import { Avatar } from './Avatar';
+
+export const FallbackIconExample = () => (
+    <Avatar
+        items={[
+            { text: 'Without image' },
+            { text: 'Broken image', imageUrl: 'https://example.invalid/broken.png' },
+        ]}
+        showTooltip
+    />
+);
+`;
+
+export const DisplayedAvatarsLimitDefinition = `
+import { Avatar } from './Avatar';
+
+export const DisplayedAvatarsLimitExample = () => (
+    <Avatar
+        displayedAvatars={3}
+        items={[
+            { text: 'User 1', imageUrl: 'https://i.pravatar.cc/150?img=51' },
+            { text: 'User 2', imageUrl: 'https://i.pravatar.cc/150?img=52' },
+            { text: 'User 3', imageUrl: 'https://i.pravatar.cc/150?img=53' },
+            { text: 'User 4', imageUrl: 'https://i.pravatar.cc/150?img=54' },
+            { text: 'User 5', imageUrl: 'https://i.pravatar.cc/150?img=55' },
+        ]}
+    />
+);
+`;
+
+export const CustomStylingDefinition = `
+import { Avatar } from './Avatar';
+
+export const CustomStylingExample = () => (
+    <Avatar
+        size="md"
+        items={[
+            { text: 'User One', imageUrl: 'https://i.pravatar.cc/150?img=61' },
+            { text: 'User Two', imageUrl: 'https://i.pravatar.cc/150?img=62' },
+        ]}
+        sx={{
+            p: 1,
+            borderRadius: 2,
+            bgcolor: 'action.hover',
+        }}
+        avatarSx={{
+            border: (theme) => '3px solid ' + theme.palette.primary.main,
+        }}
+    />
+);
+`;