@soyfri/shared-library 2.0.0-beta.3 → 2.0.0-beta.4

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,361 @@
+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;
+}
+
+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>;
+  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 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,
+    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,
+    className,
+    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());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [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,
+  ): any => {
+    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 = [
+    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: SelectOption) => opt.value as TValue);
+      onChange(values);
+    } else {
+      onChange((newValue?.value ?? null) as TValue | null);
+    }
+  };
+
+  // --- 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);
+}
+
+/**
+ * @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

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

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,
+        }}
+    />
+);
+`;