@soyfri/shared-library 1.5.0-beta.4 → 2.0.0-beta.0

package/src/components/Select/Select.sx.ts

@@ -0,0 +1,14 @@
+import type { SelectProps as MuiSelectProps } from '@mui/material';
+
+import { buildFormFieldSx } from '../_shared/formField.sx';
+import type { LabelPosition } from './Select';
+
+/**
+ * Builder de sx para el Select. Usa el builder compartido
+ * `buildFormFieldSx`. El Select no necesita overrides específicos.
+ */
+export const buildSelectSx = (
+  borderRadius: number | string,
+  labelPosition: LabelPosition,
+): MuiSelectProps['sx'] =>
+  buildFormFieldSx({ borderRadius, labelPosition }) as MuiSelectProps['sx'];

package/src/components/Select/Select.tsx

@@ -0,0 +1,429 @@
+import React, {
+    isValidElement,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+    type ReactElement,
+    type ReactNode,
+} from 'react';
+import {
+    Box,
+    CircularProgress,
+    FormControl,
+    FormHelperText,
+    InputLabel,
+    ListSubheader,
+    MenuItem,
+    OutlinedInput,
+    Select as MuiSelect,
+    SelectChangeEvent,
+    Typography,
+    type SelectProps as MuiSelectProps,
+} from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+import { Controller, type Control, type RegisterOptions } from 'react-hook-form';
+
+import { buildSelectSx } from './Select.sx';
+import { resolvePreset } from '../_shared/resolvePreset';
+import {
+    filterOptionsByLabel,
+    groupOptions,
+    isGroupedOptionsEmpty,
+    isSelectValueEmpty,
+    normalizeSelectValue,
+} from './Select.helpers';
+import { SelectSearchHeader } from './_parts/SelectSearchHeader';
+import { SelectValue } from './_parts/SelectValue';
+import { renderSelectMenuItem } from './_parts/SelectMenuItem';
+
+// ── 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 ChipVariant = 'outlined' | 'filled';
+export type SelectSize = 'small' | 'medium';
+
+// ── Render slots ─────────────────────────────────────────────────────────
+export type RenderOptionItem = (item: SelectOption) => ReactNode;
+export type RenderChipLabel = (item: SelectOption) => ReactNode;
+
+// ── Sub-componente declarativo <Option> ──────────────────────────────────
+export interface OptionProps {
+    children: RenderOptionItem;
+}
+
+// ── Props base ───────────────────────────────────────────────────────────
+export interface BaseSelectProps<
+    TValue extends SelectOption['value'] = SelectOption['value'],
+> {
+    label?: string;
+    options?: SelectOption[];
+    defaultValue?: TValue | TValue[];
+    size?: SelectSize;
+    multiple?: boolean;
+    filterable?: boolean;
+    placeholder?: string;
+    children?: ReactElement<{ children: RenderOptionItem }>;
+    maxHeight?: number | string;
+    maxWidth?: number | string;
+    maxChipsToShow?: number;
+    renderChipLabel?: RenderChipLabel;
+    chipVariant?: ChipVariant;
+    loadOptions?: (inputValue: string) => Promise<SelectOption[]>;
+    loadingMessage?: ReactNode;
+    noOptionsMessage?: ReactNode;
+    debounceTimeout?: number;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+    /** Border radius del input (px o string CSS). Default: 10 */
+    borderRadius?: number | string;
+    /**
+     * Posición del label.
+     * - "outside" (default): label arriba del input, sin animación.
+     * - "floating": label clásico de MUI (flota dentro del notched outline).
+     */
+    labelPosition?: LabelPosition;
+    /**
+     * Nombre del preset de estilo registrado en `theme.styles.Select`.
+     * - `"default"` (o ausente) = estilo built-in del paquete.
+     * - Cualquier otro string = mergea el preset encima del estilo built-in.
+     */
+    preset?: string;
+    sx?: MuiSelectProps['sx'];
+    className?: string;
+}
+
+// ── Variantes discriminadas (RHF vs controlado) ──────────────────────────
+export interface RHFSelectProps<
+    TValue extends SelectOption['value'] = SelectOption['value'],
+> extends BaseSelectProps<TValue> {
+    name: string;
+    control: Control<any>;
+    validation?: RegisterOptions;
+    value?: TValue | TValue[];
+    onChange?: (val: TValue | TValue[]) => void;
+}
+
+export interface StandardSelectProps<
+    TValue extends SelectOption['value'] = SelectOption['value'],
+> extends BaseSelectProps<TValue> {
+    name?: string;
+    control?: never;
+    validation?: never;
+    value: TValue | TValue[];
+    onChange: (val: TValue | TValue[]) => void;
+}
+
+// ── API pública final ────────────────────────────────────────────────────
+export type SelectProps<
+    TValue extends SelectOption['value'] = SelectOption['value'],
+> = RHFSelectProps<TValue> | StandardSelectProps<TValue>;
+
+// ── Sub-componente declarativo <Option> ──────────────────────────────────
+export function Option(_props: OptionProps) {
+    return null;
+}
+Option.displayName = 'Option';
+
+// ── Componente ───────────────────────────────────────────────────────────
+export function Select<TValue extends SelectOption['value'] = SelectOption['value']>(
+    props: SelectProps<TValue>,
+) {
+    const {
+        label,
+        options = [],
+        value,
+        onChange,
+        defaultValue,
+        size = 'small',
+        multiple = false,
+        filterable = false,
+        placeholder,
+        children,
+        maxHeight = 300,
+        maxWidth,
+        maxChipsToShow = 3,
+        renderChipLabel,
+        chipVariant = 'outlined',
+        loadOptions,
+        loadingMessage = 'Cargando opciones...',
+        noOptionsMessage = 'No hay opciones',
+        debounceTimeout = 300,
+        disabled = false,
+        error = false,
+        helperText,
+        borderRadius = 10,
+        labelPosition = 'outside',
+        preset,
+        sx,
+        className,
+        ...rest
+    } = props;
+
+    const theme = useTheme();
+    const presetSx = resolvePreset('Select', preset, theme);
+
+    const isRHFMode = 'control' in rest && (rest as any).control !== undefined;
+
+    // Custom render opcional vía <Option>{item => ...}</Option>
+    const customRender: RenderOptionItem | null = useMemo(() => {
+        if (React.Children.count(children) === 1) {
+            const child = React.Children.only(children);
+            if (isValidElement(child) && (child.type as any)?.displayName === 'Option') {
+                return (child.props as OptionProps).children;
+            }
+        }
+        return null;
+    }, [children]);
+
+    // Búsqueda / async
+    const [search, setSearch] = useState('');
+    const [asyncOptions, setAsyncOptions] = useState<SelectOption[]>([]);
+    const [loading, setLoading] = useState(false);
+    const debounceTimerRef = useRef<number | null>(null);
+    const searchInputRef = useRef<HTMLInputElement>(null);
+
+    // Focus/open tracking para el comportamiento del label "outside".
+    const [isOpen, setIsOpen] = useState(false);
+    const [isFocused, setIsFocused] = useState(false);
+
+    const isAsync = typeof loadOptions === 'function';
+    const currentOptions = isAsync ? asyncOptions : options;
+
+    useEffect(() => {
+        if (!isAsync) return;
+
+        if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+
+        if (search) {
+            setLoading(true);
+            debounceTimerRef.current = window.setTimeout(() => {
+                loadOptions!(search)
+                    .then(setAsyncOptions)
+                    .finally(() => {
+                        setLoading(false);
+                        searchInputRef.current?.focus();
+                    });
+            }, debounceTimeout);
+        } else {
+            setAsyncOptions([]);
+            setLoading(false);
+            searchInputRef.current?.focus();
+        }
+    }, [search, isAsync, loadOptions, debounceTimeout]);
+
+    const filteredOptions = useMemo(() => {
+        if (isAsync) return currentOptions;
+        if (!filterable) return currentOptions;
+        return filterOptionsByLabel(currentOptions, search);
+    }, [search, filterable, currentOptions, isAsync]);
+
+    const groupedOptions = useMemo(() => groupOptions(filteredOptions), [filteredOptions]);
+
+    // Items del menu (search header + loading/empty + grupos + opciones)
+    const menuItems = useMemo(() => {
+        const items: React.ReactNode[] = [];
+
+        if (filterable || isAsync) {
+            items.push(
+                <SelectSearchHeader
+                    key="search-header"
+                    value={search}
+                    onChange={setSearch}
+                    inputRef={searchInputRef}
+                />,
+            );
+        }
+
+        const noOptions = isGroupedOptionsEmpty(groupedOptions);
+
+        if (loading) {
+            items.push(
+                <MenuItem key="loading-message" disabled>
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                        <CircularProgress size={20} />
+                        <Typography>{loadingMessage}</Typography>
+                    </Box>
+                </MenuItem>,
+            );
+        } else if (noOptions) {
+            items.push(
+                <MenuItem key="no-options-message" disabled>
+                    <Typography>{noOptionsMessage}</Typography>
+                </MenuItem>,
+            );
+        } else {
+            Object.entries(groupedOptions).forEach(([group, opts]) => {
+                if (group !== '__default') {
+                    items.push(
+                        <ListSubheader key={group} disableSticky>
+                            {group}
+                        </ListSubheader>,
+                    );
+                }
+                opts.forEach((opt) => {
+                    const isSelected = multiple
+                        ? (value as TValue[] | undefined)?.includes(opt.value as TValue) ?? false
+                        : value === opt.value;
+
+                    items.push(
+                        renderSelectMenuItem({
+                            option: opt,
+                            selected: isSelected,
+                            customRender,
+                        }),
+                    );
+                });
+            });
+        }
+        return items;
+    }, [
+        groupedOptions,
+        customRender,
+        filterable,
+        isAsync,
+        search,
+        loading,
+        loadingMessage,
+        noOptionsMessage,
+        multiple,
+        value,
+    ]);
+
+    // Handler de cambio
+    const handleChangeInternal = (
+        event: SelectChangeEvent<any>,
+        rhfOnChange?: (...event: any[]) => void,
+    ) => {
+        const newValue = event.target.value;
+        if (isRHFMode) {
+            rhfOnChange?.(newValue);
+        } else {
+            (onChange as (val: TValue | TValue[]) => void)?.(newValue);
+        }
+    };
+
+    // Sx mergeado (defaults + consumer)
+    const mergedSx = [
+        buildSelectSx(borderRadius, labelPosition),
+        ...(presetSx ? [presetSx] : []),
+        ...(Array.isArray(sx) ? sx : [sx]),
+    ];
+
+    // Render base
+    const renderSelect = (
+        selectValue: any,
+        selectOnChange: any,
+        onBlur?: any,
+        inputRef?: any,
+        rhfError?: boolean,
+        rhfHelperText?: string,
+    ) => {
+        const finalError = rhfError ?? error;
+        const finalHelperText = rhfHelperText ?? helperText;
+
+        const inputElement =
+            labelPosition === 'floating' ? (
+                <OutlinedInput label={label} />
+            ) : (
+                <OutlinedInput />
+            );
+
+        const normalizedValue = normalizeSelectValue(selectValue, multiple);
+        const isEmpty = isSelectValueEmpty(normalizedValue, multiple);
+
+        // Shrink cuando hay valor, foco, o dropdown abierto.
+        const shouldShrink = !isEmpty || isFocused || isOpen;
+        // Placeholder solo cuando el label ya subió.
+        const shouldDisplayPlaceholder = isEmpty && (isFocused || isOpen) && !!placeholder;
+
+        return (
+            <FormControl
+                fullWidth
+                size={size}
+                error={finalError}
+                disabled={disabled}
+                className={className}
+                sx={mergedSx}
+            >
+                {label && <InputLabel shrink={shouldShrink}>{label}</InputLabel>}
+                <MuiSelect
+                    value={normalizedValue}
+                    defaultValue={defaultValue}
+                    multiple={multiple}
+                    onChange={selectOnChange}
+                    onBlur={(e) => {
+                        setIsFocused(false);
+                        onBlur?.(e);
+                    }}
+                    onFocus={() => setIsFocused(true)}
+                    onOpen={() => setIsOpen(true)}
+                    onClose={() => setIsOpen(false)}
+                    renderValue={(selected) => (
+                        <SelectValue<TValue>
+                            selected={selected as TValue | TValue[]}
+                            options={currentOptions}
+                            multiple={multiple}
+                            placeholder={placeholder}
+                            maxChipsToShow={maxChipsToShow}
+                            chipVariant={chipVariant}
+                            renderChipLabel={renderChipLabel}
+                            currentValues={(value as TValue[]) ?? []}
+                            onDeleteChip={(next) =>
+                                (onChange as (v: TValue | TValue[]) => void)?.(next)
+                            }
+                        />
+                    )}
+                    displayEmpty={shouldDisplayPlaceholder}
+                    input={inputElement}
+                    disabled={disabled}
+                    MenuProps={{
+                        PaperProps: {
+                            style: { maxHeight, maxWidth },
+                        },
+                    }}
+                    inputRef={inputRef}
+                    {...(rest as any)}
+                >
+                    {menuItems}
+                </MuiSelect>
+                {finalHelperText && <FormHelperText>{finalHelperText}</FormHelperText>}
+            </FormControl>
+        );
+    };
+
+    // Branch: RHF vs controlado
+    if (isRHFMode) {
+        const rhfProps = rest as RHFSelectProps<TValue>;
+        return (
+            <Controller
+                name={rhfProps.name}
+                control={rhfProps.control}
+                rules={rhfProps.validation}
+                render={({ field, fieldState: { error: fieldError } }) =>
+                    renderSelect(
+                        field.value,
+                        (e: SelectChangeEvent<any>) => handleChangeInternal(e, field.onChange),
+                        field.onBlur,
+                        field.ref,
+                        !!fieldError,
+                        fieldError?.message,
+                    )
+                }
+            />
+        );
+    }
+
+    return renderSelect(value, (e: SelectChangeEvent<any>) => handleChangeInternal(e));
+}
+
+export default Select;

package/src/components/Select/Select.types.ts

@@ -0,0 +1,15 @@
+// Re-export barrel para compatibilidad con imports antiguos.
+// Los tipos ahora viven dentro de Select.tsx.
+export type {
+  SelectOption,
+  LabelPosition,
+  ChipVariant,
+  SelectSize,
+  RenderOptionItem,
+  RenderChipLabel,
+  OptionProps,
+  BaseSelectProps,
+  RHFSelectProps,
+  StandardSelectProps,
+  SelectProps,
+} from './Select';

package/src/components/Select/_parts/SelectMenuItem.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { ListItemIcon, MenuItem } from '@mui/material';
+import CheckIcon from '@mui/icons-material/Check';
+
+import type { SelectOption, RenderOptionItem } from '../Select';
+
+interface RenderSelectMenuItemArgs {
+  option: SelectOption;
+  selected: boolean;
+  customRender?: RenderOptionItem | null;
+}
+
+/**
+ * Render helper (no componente) que devuelve un <MenuItem> listo para
+ * colocarse como hijo directo del <MuiSelect>. Se implementa como función
+ * y no como componente porque MUI Select inspecciona `props.value` de sus
+ * children para resolver la selección, y envolverlo en un componente extra
+ * rompe esa detección.
+ *
+ * Incluye el icono de check a la izquierda cuando `selected` es true. Si el
+ * consumer pasó un `<Option>{(opt) => ...}</Option>`, usa ese render para el
+ * contenido principal; de lo contrario muestra `option.label`.
+ */
+export const renderSelectMenuItem = ({
+  option,
+  selected,
+  customRender,
+}: RenderSelectMenuItemArgs): React.ReactElement => (
+  <MenuItem
+    key={String(option.value)}
+    value={option.value}
+    disabled={option.disabled}
+    selected={selected}
+  >
+    <ListItemIcon sx={{ minWidth: 32 }}>
+      {selected && <CheckIcon color="success" fontSize="small" />}
+    </ListItemIcon>
+    {customRender ? customRender(option) : option.label}
+  </MenuItem>
+);

package/src/components/Select/_parts/SelectSearchHeader.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { ListSubheader, TextField } from '@mui/material';
+
+interface SelectSearchHeaderProps {
+  value: string;
+  onChange: (next: string) => void;
+  placeholder?: string;
+  inputRef?: React.Ref<HTMLInputElement>;
+}
+
+/**
+ * Header sticky del menu del Select que contiene el input de búsqueda.
+ * Se usa cuando `filterable` es true o cuando el Select opera en modo async.
+ * Detiene la propagación de click/keydown para que el menu no se cierre ni
+ * intercepte las teclas al tipear.
+ */
+export const SelectSearchHeader: React.FC<SelectSearchHeaderProps> = ({
+  value,
+  onChange,
+  placeholder = 'Buscar...',
+  inputRef,
+}) => {
+  return (
+    <ListSubheader
+      sx={{
+        px: 2,
+        pt: 1,
+        pb: 1,
+        backgroundColor: 'background.paper',
+        zIndex: 1,
+        position: 'sticky',
+        top: 0,
+      }}
+    >
+      <TextField
+        inputRef={inputRef}
+        placeholder={placeholder}
+        variant="standard"
+        size="small"
+        fullWidth
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        slotProps={{ htmlInput: { autoFocus: true } }}
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+      />
+    </ListSubheader>
+  );
+};
+
+export default SelectSearchHeader;

package/src/components/Select/_parts/SelectValue.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { Avatar, Box, Chip, Typography } from '@mui/material';
+import ClearIcon from '@mui/icons-material/Clear';
+
+import type {
+  SelectOption,
+  RenderChipLabel,
+  ChipVariant,
+} from '../Select';
+
+interface SelectValueProps<TValue extends SelectOption['value']> {
+  selected: TValue | TValue[] | null | undefined;
+  options: SelectOption[];
+  multiple: boolean;
+  placeholder?: string;
+  maxChipsToShow: number;
+  chipVariant: ChipVariant;
+  renderChipLabel?: RenderChipLabel;
+  /** Solo relevante en modo multiple. Recibe el nuevo array de valores. */
+  onDeleteChip?: (nextValues: TValue[]) => void;
+  /** Array de valores actuales (para componer el nuevo array al borrar chips). */
+  currentValues?: TValue[];
+}
+
+/**
+ * Render del valor seleccionado del Select.
+ * - single:   texto (label) o lo que devuelva `renderChipLabel`.
+ * - multiple: chips con delete. Trunca después de `maxChipsToShow` mostrando "+N más".
+ * - empty:    placeholder en color disabled.
+ */
+export function SelectValue<TValue extends SelectOption['value']>(
+  props: SelectValueProps<TValue>,
+) {
+  const {
+    selected,
+    options,
+    multiple,
+    placeholder,
+    maxChipsToShow,
+    chipVariant,
+    renderChipLabel,
+    onDeleteChip,
+    currentValues,
+  } = props;
+
+  const isEmpty =
+    !selected || (Array.isArray(selected) && selected.length === 0);
+
+  if (isEmpty) {
+    return (
+      <Typography sx={{ color: 'text.disabled' }}>{placeholder || ''}</Typography>
+    );
+  }
+
+  if (!multiple) {
+    const item = options.find((opt) => opt.value === selected);
+    if (renderChipLabel && item) return <>{renderChipLabel(item)}</>;
+    return <>{item?.label ?? String(selected)}</>;
+  }
+
+  const selectedValuesArray = selected as TValue[];
+  const displayedChips = selectedValuesArray.slice(0, maxChipsToShow);
+  const hiddenChipsCount = selectedValuesArray.length - maxChipsToShow;
+
+  const handleDelete = (chipValue: TValue) => {
+    if (!onDeleteChip || !currentValues) return;
+    onDeleteChip(currentValues.filter((v) => v !== chipValue));
+  };
+
+  return (
+    <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 0.5 }}>
+      {displayedChips.map((val) => {
+        const item = options.find((o) => o.value === val);
+        if (!item) return null;
+
+        return (
+          <Chip
+            variant={chipVariant}
+            color="primary"
+            size="small"
+            key={String(val)}
+            label={renderChipLabel ? renderChipLabel(item) : item.label}
+            avatar={item.img ? <Avatar src={item.img} /> : undefined}
+            onDelete={() => handleDelete(val)}
+            deleteIcon={<ClearIcon fontSize="small" />}
+          />
+        );
+      })}
+      {hiddenChipsCount > 0 && (
+        <Chip size="small" variant={chipVariant} label={`+${hiddenChipsCount} más`} />
+      )}
+    </Box>
+  );
+}
+
+export default SelectValue;

package/src/components/Select/index.ts

@@ -0,0 +1,14 @@
+export { Select, Option, default } from './Select';
+export type {
+  SelectProps,
+  SelectOption,
+  OptionProps,
+  BaseSelectProps,
+  RHFSelectProps,
+  StandardSelectProps,
+  RenderOptionItem,
+  RenderChipLabel,
+  LabelPosition,
+  ChipVariant,
+  SelectSize,
+} from './Select.types';