@soyfri/shared-library 4.0.2 → 4.1.0

package/components/AppBar/AppBar.d.cts

@@ -0,0 +1,38 @@
+import { default as React, ReactNode } from 'react';
+import { AppBarProps as MuiAppBarProps } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+export type AppBarPosition = 'fixed' | 'sticky' | 'static' | 'absolute' | 'relative';
+export type AppBarColor = 'default' | 'primary' | 'secondary' | 'transparent' | 'inherit';
+export interface AppBarProps {
+    /** Contenido del AppBar (típicamente sub-componentes + acciones custom). */
+    children?: ReactNode;
+    /** Posicionamiento. Default: `'sticky'`. */
+    position?: AppBarPosition;
+    /** Color. Default: `'default'`. */
+    color?: AppBarColor;
+    /** Nivel de sombra. Default: 1. */
+    elevation?: number;
+    /** Altura en px. Default: 64. */
+    height?: number;
+    /**
+     * Handler del botón hamburguesa. Se expone vía AppBarContext para que el
+     * sub-componente `<AppBarMenuToggle>` lo consuma sin prop drilling.
+     */
+    onMenuToggle?: () => void;
+    /** Estado del drawer asociado (para que el icono del toggle cambie). */
+    menuOpen?: boolean;
+    /**
+     * Nombre del preset de estilo registrado en `theme.styles.AppBar`.
+     * - `"default"` (o ausente) = estilo built-in del paquete.
+     */
+    preset?: string;
+    /** sx del root (se mergea después del preset). */
+    sx?: SxProps<Theme>;
+    /** sx del Toolbar interno. */
+    toolbarSx?: SxProps<Theme>;
+    className?: string;
+    /** Otras props nativas del MuiAppBar (ej. `enableColorOnDark`). */
+    appBarProps?: Omit<MuiAppBarProps, 'position' | 'color' | 'elevation' | 'sx' | 'children' | 'className'>;
+}
+export declare const AppBar: React.ForwardRefExoticComponent<AppBarProps & React.RefAttributes<HTMLElement>>;
+export default AppBar;

package/components/AppBar/AppBar.d.mts

@@ -0,0 +1,38 @@
+import { default as React, ReactNode } from 'react';
+import { AppBarProps as MuiAppBarProps } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+export type AppBarPosition = 'fixed' | 'sticky' | 'static' | 'absolute' | 'relative';
+export type AppBarColor = 'default' | 'primary' | 'secondary' | 'transparent' | 'inherit';
+export interface AppBarProps {
+    /** Contenido del AppBar (típicamente sub-componentes + acciones custom). */
+    children?: ReactNode;
+    /** Posicionamiento. Default: `'sticky'`. */
+    position?: AppBarPosition;
+    /** Color. Default: `'default'`. */
+    color?: AppBarColor;
+    /** Nivel de sombra. Default: 1. */
+    elevation?: number;
+    /** Altura en px. Default: 64. */
+    height?: number;
+    /**
+     * Handler del botón hamburguesa. Se expone vía AppBarContext para que el
+     * sub-componente `<AppBarMenuToggle>` lo consuma sin prop drilling.
+     */
+    onMenuToggle?: () => void;
+    /** Estado del drawer asociado (para que el icono del toggle cambie). */
+    menuOpen?: boolean;
+    /**
+     * Nombre del preset de estilo registrado en `theme.styles.AppBar`.
+     * - `"default"` (o ausente) = estilo built-in del paquete.
+     */
+    preset?: string;
+    /** sx del root (se mergea después del preset). */
+    sx?: SxProps<Theme>;
+    /** sx del Toolbar interno. */
+    toolbarSx?: SxProps<Theme>;
+    className?: string;
+    /** Otras props nativas del MuiAppBar (ej. `enableColorOnDark`). */
+    appBarProps?: Omit<MuiAppBarProps, 'position' | 'color' | 'elevation' | 'sx' | 'children' | 'className'>;
+}
+export declare const AppBar: React.ForwardRefExoticComponent<AppBarProps & React.RefAttributes<HTMLElement>>;
+export default AppBar;

package/components/AppBar/AppBar.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { default as React, ReactNode } from 'react';
 import { AppBarProps as MuiAppBarProps } from '@mui/material';
 import { SxProps, Theme } from '@mui/material/styles';
 export type AppBarPosition = 'fixed' | 'sticky' | 'static' | 'absolute' | 'relative';
@@ -34,22 +34,5 @@ export interface AppBarProps {
     /** Otras props nativas del MuiAppBar (ej. `enableColorOnDark`). */
     appBarProps?: Omit<MuiAppBarProps, 'position' | 'color' | 'elevation' | 'sx' | 'children' | 'className'>;
 }
-/**
- * AppBar (header superior) del paquete. Se diseñó como un shell compositivo
- * — el consumer arma el contenido libremente (logo, título, menú de usuario,
- * etc.) y puede usar `<AppBarMenuToggle>` para el botón hamburguesa
- * integrado con el contexto.
- *
- * Patrón recomendado para navegación en dashboards:
- *
- * ```tsx
- * <AppBar onMenuToggle={toggleDrawer}>
- *   <AppBarMenuToggle />
- *   <MyBrand />
- *   <Box sx={{ flex: 1 }} />
- *   <MyUserMenu />
- * </AppBar>
- * ```
- */
-export declare function AppBar({ children, position, color, elevation, height, onMenuToggle, menuOpen, preset, sx, toolbarSx, appBarProps, }: AppBarProps): import("react/jsx-runtime").JSX.Element;
+export declare const AppBar: React.ForwardRefExoticComponent<AppBarProps & React.RefAttributes<HTMLElement>>;
 export default AppBar;

package/components/AppBar/AppBar.sx.d.cts

@@ -0,0 +1,21 @@
+import { CSSObject, SxProps, Theme } from '@mui/material/styles';
+export interface BuildAppBarSxArgs {
+    /** Altura en px. Default: 64. */
+    height?: number;
+    /** Color del AppBar (se pasa al MuiAppBar). */
+    transparent?: boolean;
+}
+/**
+ * Estilo de fábrica del AppBar, en CSS real (para `styled()`). Define altura
+ * fija y layout del Toolbar interno; color/elevación quedan en las props
+ * nativas de MuiAppBar.
+ *
+ * `gap` pasa por `theme.spacing`: en `sx` un `1.5` son 12px, en CSS plano
+ * serían "1.5px".
+ */
+export declare function buildAppBarStyles(theme: Theme, { height, transparent }: BuildAppBarSxArgs): CSSObject;
+/**
+ * @deprecated El componente ya no lo usa: su estilo de fábrica vive en el
+ * `styled()`. Preferir `buildAppBarStyles`.
+ */
+export declare function buildAppBarSx({ height, transparent, }: BuildAppBarSxArgs): SxProps<Theme>;

package/components/AppBar/AppBar.sx.d.mts

@@ -0,0 +1,21 @@
+import { CSSObject, SxProps, Theme } from '@mui/material/styles';
+export interface BuildAppBarSxArgs {
+    /** Altura en px. Default: 64. */
+    height?: number;
+    /** Color del AppBar (se pasa al MuiAppBar). */
+    transparent?: boolean;
+}
+/**
+ * Estilo de fábrica del AppBar, en CSS real (para `styled()`). Define altura
+ * fija y layout del Toolbar interno; color/elevación quedan en las props
+ * nativas de MuiAppBar.
+ *
+ * `gap` pasa por `theme.spacing`: en `sx` un `1.5` son 12px, en CSS plano
+ * serían "1.5px".
+ */
+export declare function buildAppBarStyles(theme: Theme, { height, transparent }: BuildAppBarSxArgs): CSSObject;
+/**
+ * @deprecated El componente ya no lo usa: su estilo de fábrica vive en el
+ * `styled()`. Preferir `buildAppBarStyles`.
+ */
+export declare function buildAppBarSx({ height, transparent, }: BuildAppBarSxArgs): SxProps<Theme>;

package/components/AppBar/AppBar.sx.d.ts

@@ -1,4 +1,4 @@
-import { SxProps, Theme } from '@mui/material/styles';
+import { CSSObject, SxProps, Theme } from '@mui/material/styles';
 export interface BuildAppBarSxArgs {
     /** Altura en px. Default: 64. */
     height?: number;
@@ -6,7 +6,16 @@ export interface BuildAppBarSxArgs {
     transparent?: boolean;
 }
 /**
- * sx del root del MuiAppBar. Define altura fija y layout flex del Toolbar
- * interno. El color/elevación se dejan a las props nativas de MuiAppBar.
+ * Estilo de fábrica del AppBar, en CSS real (para `styled()`). Define altura
+ * fija y layout del Toolbar interno; color/elevación quedan en las props
+ * nativas de MuiAppBar.
+ *
+ * `gap` pasa por `theme.spacing`: en `sx` un `1.5` son 12px, en CSS plano
+ * serían "1.5px".
+ */
+export declare function buildAppBarStyles(theme: Theme, { height, transparent }: BuildAppBarSxArgs): CSSObject;
+/**
+ * @deprecated El componente ya no lo usa: su estilo de fábrica vive en el
+ * `styled()`. Preferir `buildAppBarStyles`.
  */
 export declare function buildAppBarSx({ height, transparent, }: BuildAppBarSxArgs): SxProps<Theme>;

package/components/AppBar/AppBarContext.d.cts

@@ -0,0 +1,18 @@
+/**
+ * Context interno del AppBar. Permite que sub-componentes (MenuToggle, etc.)
+ * consuman callbacks registrados en el AppBar padre sin tener que pasarlos
+ * por props explícitas.
+ */
+export interface AppBarContextValue {
+    /** Handler del botón hamburguesa. Si es undefined, el toggle se oculta. */
+    onMenuToggle?: () => void;
+    /** Estado actual del drawer asociado (usado por el icono del toggle). */
+    menuOpen?: boolean;
+}
+export declare const AppBarContext: import('react').Context<AppBarContextValue | null>;
+/**
+ * Hook para leer el contexto del AppBar. Si se llama fuera de un `<AppBar>`,
+ * devuelve un objeto vacío — los sub-componentes caen en modo "standalone"
+ * con sus defaults en lugar de romper.
+ */
+export declare function useAppBarContext(): AppBarContextValue;

package/components/AppBar/AppBarContext.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Context interno del AppBar. Permite que sub-componentes (MenuToggle, etc.)
+ * consuman callbacks registrados en el AppBar padre sin tener que pasarlos
+ * por props explícitas.
+ */
+export interface AppBarContextValue {
+    /** Handler del botón hamburguesa. Si es undefined, el toggle se oculta. */
+    onMenuToggle?: () => void;
+    /** Estado actual del drawer asociado (usado por el icono del toggle). */
+    menuOpen?: boolean;
+}
+export declare const AppBarContext: import('react').Context<AppBarContextValue | null>;
+/**
+ * Hook para leer el contexto del AppBar. Si se llama fuera de un `<AppBar>`,
+ * devuelve un objeto vacío — los sub-componentes caen en modo "standalone"
+ * con sus defaults en lugar de romper.
+ */
+export declare function useAppBarContext(): AppBarContextValue;

package/components/AppBar/AppBarMenuToggle.d.cts

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+import { SxProps, Theme } from '@mui/material/styles';
+export interface AppBarMenuToggleProps {
+    /**
+     * Callback explícito. Si se omite, se consume del `AppBarContext`. Útil para
+     * usar el toggle fuera de un `<AppBar>` (p.ej. en un header custom).
+     */
+    onClick?: () => void;
+    /** Estado del drawer asociado. Si se omite, se lee del `AppBarContext`. */
+    menuOpen?: boolean;
+    /** Icono custom cuando el drawer está cerrado. Default: `<MenuIcon />`. */
+    closedIcon?: ReactNode;
+    /** Icono custom cuando el drawer está abierto. Default: `<MenuOpenIcon />`. */
+    openIcon?: ReactNode;
+    /** Texto de tooltip. Default: "Menú". */
+    tooltip?: string;
+    /** aria-label del botón. Default: el mismo tooltip. */
+    ariaLabel?: string;
+    /** Tamaño del IconButton. Default: `'medium'`. */
+    size?: 'small' | 'medium' | 'large';
+    /** Oculta el botón cuando no hay handler disponible. Default: true. */
+    hideIfNoHandler?: boolean;
+    sx?: SxProps<Theme>;
+    className?: string;
+}
+/**
+ * Botón hamburguesa del AppBar. Por default consume `onMenuToggle` y
+ * `menuOpen` del `AppBarContext` (pattern composicional), pero permite
+ * overrides explícitos si se usa fuera de un `<AppBar>`.
+ *
+ * ```tsx
+ * <AppBar onMenuToggle={toggleDrawer} menuOpen={open}>
+ *   <AppBarMenuToggle />
+ *   ...
+ * </AppBar>
+ * ```
+ */
+export declare function AppBarMenuToggle({ onClick, menuOpen, closedIcon, openIcon, tooltip, ariaLabel, size, hideIfNoHandler, sx, className, }: AppBarMenuToggleProps): import("react/jsx-runtime").JSX.Element | null;
+export default AppBarMenuToggle;

package/components/AppBar/AppBarMenuToggle.d.mts

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+import { SxProps, Theme } from '@mui/material/styles';
+export interface AppBarMenuToggleProps {
+    /**
+     * Callback explícito. Si se omite, se consume del `AppBarContext`. Útil para
+     * usar el toggle fuera de un `<AppBar>` (p.ej. en un header custom).
+     */
+    onClick?: () => void;
+    /** Estado del drawer asociado. Si se omite, se lee del `AppBarContext`. */
+    menuOpen?: boolean;
+    /** Icono custom cuando el drawer está cerrado. Default: `<MenuIcon />`. */
+    closedIcon?: ReactNode;
+    /** Icono custom cuando el drawer está abierto. Default: `<MenuOpenIcon />`. */
+    openIcon?: ReactNode;
+    /** Texto de tooltip. Default: "Menú". */
+    tooltip?: string;
+    /** aria-label del botón. Default: el mismo tooltip. */
+    ariaLabel?: string;
+    /** Tamaño del IconButton. Default: `'medium'`. */
+    size?: 'small' | 'medium' | 'large';
+    /** Oculta el botón cuando no hay handler disponible. Default: true. */
+    hideIfNoHandler?: boolean;
+    sx?: SxProps<Theme>;
+    className?: string;
+}
+/**
+ * Botón hamburguesa del AppBar. Por default consume `onMenuToggle` y
+ * `menuOpen` del `AppBarContext` (pattern composicional), pero permite
+ * overrides explícitos si se usa fuera de un `<AppBar>`.
+ *
+ * ```tsx
+ * <AppBar onMenuToggle={toggleDrawer} menuOpen={open}>
+ *   <AppBarMenuToggle />
+ *   ...
+ * </AppBar>
+ * ```
+ */
+export declare function AppBarMenuToggle({ onClick, menuOpen, closedIcon, openIcon, tooltip, ariaLabel, size, hideIfNoHandler, sx, className, }: AppBarMenuToggleProps): import("react/jsx-runtime").JSX.Element | null;
+export default AppBarMenuToggle;

package/components/AppBar/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const AppBarMenuToggle = require("../../chunks/AppBarMenuToggle-BsN5zZTv.cjs");
+exports.AppBar = AppBarMenuToggle.AppBar;
+exports.AppBarContext = AppBarMenuToggle.AppBarContext;
+exports.AppBarMenuToggle = AppBarMenuToggle.AppBarMenuToggle;
+exports.default = AppBarMenuToggle.AppBar;
+exports.useAppBarContext = AppBarMenuToggle.useAppBarContext;
+//# sourceMappingURL=index.cjs.map

package/components/AppBar/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/components/AppBar/index.d.cts

@@ -0,0 +1,6 @@
+export { AppBar, default } from './AppBar';
+export type { AppBarProps, AppBarPosition, AppBarColor, } from './AppBar';
+export { AppBarMenuToggle } from './AppBarMenuToggle';
+export type { AppBarMenuToggleProps } from './AppBarMenuToggle';
+export { AppBarContext, useAppBarContext } from './AppBarContext';
+export type { AppBarContextValue } from './AppBarContext';

package/components/AppBar/index.d.mts

@@ -0,0 +1,6 @@
+export { AppBar, default } from './AppBar.mjs';
+export type { AppBarProps, AppBarPosition, AppBarColor, } from './AppBar.mjs';
+export { AppBarMenuToggle } from './AppBarMenuToggle.mjs';
+export type { AppBarMenuToggleProps } from './AppBarMenuToggle.mjs';
+export { AppBarContext, useAppBarContext } from './AppBarContext.mjs';
+export type { AppBarContextValue } from './AppBarContext.mjs';

package/components/AppBar/index.mjs

@@ -0,0 +1,9 @@
+import { A, b, a, A as A2, u } from "../../chunks/AppBarMenuToggle-DN_dFthr.mjs";
+export {
+  A as AppBar,
+  b as AppBarContext,
+  a as AppBarMenuToggle,
+  A2 as default,
+  u as useAppBarContext
+};
+//# sourceMappingURL=index.mjs.map

package/components/AppBar/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/components/AppBar.d.cts

@@ -0,0 +1,6 @@
+export * from './AppBar/index'
+export {}
+import _default from './AppBar/index'
+export default _default
+export * from './AppBar/index'
+export {}

package/components/AppBar.d.mts

@@ -0,0 +1,6 @@
+export * from './AppBar/index.mjs'
+export {}
+import _default from './AppBar/index.mjs'
+export default _default
+export * from './AppBar/index.mjs'
+export {}

package/components/Autocomplete/Autocomplete.d.cts

@@ -0,0 +1,102 @@
+import { ReactNode, SyntheticEvent } from 'react';
+import { TextFieldProps } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+import { RegisterOptions } from 'react-hook-form';
+/** Key estable usada para comparar values, indexar caches y como React key. */
+export type AutocompleteValueKey = string | number;
+export interface SelectOption<TValue = AutocompleteValueKey> {
+    value: TValue;
+    label: string;
+    img?: string;
+    disabled?: boolean;
+    group?: string;
+    [key: string]: any;
+}
+export type LabelPosition = 'outside' | 'floating';
+export type AutocompleteSize = 'small' | 'medium';
+export type RenderOptionItem<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderChipLabel<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderSingleValue<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type BaseAutocompleteProps<TValue = AutocompleteValueKey> = {
+    label?: string;
+    options: SelectOption<TValue>[];
+    placeholder?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    loading?: boolean;
+    error?: boolean;
+    helperText?: string;
+    maxChipsToShow?: number;
+    renderOptionItem?: RenderOptionItem<TValue>;
+    renderChipLabel?: RenderChipLabel<TValue>;
+    /**
+     * Renderiza JSX custom como `startAdornment` del input en single mode.
+     * Recibe la `SelectOption` seleccionada. Útil para mostrar avatars, iconos,
+     * etc. junto al texto del label. En `multiple` no aplica (se usa `renderChipLabel`).
+     */
+    renderSingleValue?: RenderSingleValue<TValue>;
+    /**
+     * Extrae una key estable (string | number) desde el `value`. Obligatorio
+     * cuando `TValue` es un objeto: se usa para comparar values (`isOptionEqualToValue`,
+     * resolución desde el value del form), indexar el cache interno de opciones
+     * vistas y como React key en chips/options del dropdown. Para primitivos se
+     * puede omitir (default: identidad, o sea `===`).
+     */
+    getOptionKey?: (value: TValue) => AutocompleteValueKey;
+    /** 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>;
+    /** 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<TValue>[], state: any) => SelectOption<TValue>[];
+    /** Permite valores arbitrarios (no solo de la lista). */
+    freeSolo?: boolean;
+    open?: boolean;
+    onOpen?: (event: SyntheticEvent) => void;
+    onClose?: (event: SyntheticEvent, reason: string) => void;
+};
+export interface ControlledAutocompleteProps<TValue = AutocompleteValueKey> extends BaseAutocompleteProps<TValue> {
+    value: TValue | TValue[] | null;
+    onChange: (val: TValue | TValue[] | null) => void;
+    name?: string;
+    control?: never;
+    validation?: never;
+}
+export interface RHFAutocompleteProps<TValue = AutocompleteValueKey> extends BaseAutocompleteProps<TValue> {
+    name: string;
+    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;
+}
+export type AutocompleteProps<TValue = AutocompleteValueKey> = ControlledAutocompleteProps<TValue> | RHFAutocompleteProps<TValue>;
+export declare function Autocomplete<TValue = AutocompleteValueKey>(props: AutocompleteProps<TValue>): import("react/jsx-runtime").JSX.Element;
+/** Alias de `Autocomplete`. Ambos nombres son equivalentes. */
+export declare const AutocompleteSelect: typeof Autocomplete;
+export default Autocomplete;

package/components/Autocomplete/Autocomplete.d.mts

@@ -0,0 +1,102 @@
+import { ReactNode, SyntheticEvent } from 'react';
+import { TextFieldProps } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+import { RegisterOptions } from 'react-hook-form';
+/** Key estable usada para comparar values, indexar caches y como React key. */
+export type AutocompleteValueKey = string | number;
+export interface SelectOption<TValue = AutocompleteValueKey> {
+    value: TValue;
+    label: string;
+    img?: string;
+    disabled?: boolean;
+    group?: string;
+    [key: string]: any;
+}
+export type LabelPosition = 'outside' | 'floating';
+export type AutocompleteSize = 'small' | 'medium';
+export type RenderOptionItem<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderChipLabel<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderSingleValue<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type BaseAutocompleteProps<TValue = AutocompleteValueKey> = {
+    label?: string;
+    options: SelectOption<TValue>[];
+    placeholder?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    loading?: boolean;
+    error?: boolean;
+    helperText?: string;
+    maxChipsToShow?: number;
+    renderOptionItem?: RenderOptionItem<TValue>;
+    renderChipLabel?: RenderChipLabel<TValue>;
+    /**
+     * Renderiza JSX custom como `startAdornment` del input en single mode.
+     * Recibe la `SelectOption` seleccionada. Útil para mostrar avatars, iconos,
+     * etc. junto al texto del label. En `multiple` no aplica (se usa `renderChipLabel`).
+     */
+    renderSingleValue?: RenderSingleValue<TValue>;
+    /**
+     * Extrae una key estable (string | number) desde el `value`. Obligatorio
+     * cuando `TValue` es un objeto: se usa para comparar values (`isOptionEqualToValue`,
+     * resolución desde el value del form), indexar el cache interno de opciones
+     * vistas y como React key en chips/options del dropdown. Para primitivos se
+     * puede omitir (default: identidad, o sea `===`).
+     */
+    getOptionKey?: (value: TValue) => AutocompleteValueKey;
+    /** 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>;
+    /** 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<TValue>[], state: any) => SelectOption<TValue>[];
+    /** Permite valores arbitrarios (no solo de la lista). */
+    freeSolo?: boolean;
+    open?: boolean;
+    onOpen?: (event: SyntheticEvent) => void;
+    onClose?: (event: SyntheticEvent, reason: string) => void;
+};
+export interface ControlledAutocompleteProps<TValue = AutocompleteValueKey> extends BaseAutocompleteProps<TValue> {
+    value: TValue | TValue[] | null;
+    onChange: (val: TValue | TValue[] | null) => void;
+    name?: string;
+    control?: never;
+    validation?: never;
+}
+export interface RHFAutocompleteProps<TValue = AutocompleteValueKey> extends BaseAutocompleteProps<TValue> {
+    name: string;
+    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;
+}
+export type AutocompleteProps<TValue = AutocompleteValueKey> = ControlledAutocompleteProps<TValue> | RHFAutocompleteProps<TValue>;
+export declare function Autocomplete<TValue = AutocompleteValueKey>(props: AutocompleteProps<TValue>): import("react/jsx-runtime").JSX.Element;
+/** Alias de `Autocomplete`. Ambos nombres son equivalentes. */
+export declare const AutocompleteSelect: typeof Autocomplete;
+export default Autocomplete;

package/components/Autocomplete/Autocomplete.d.ts

@@ -2,8 +2,10 @@ import { ReactNode, SyntheticEvent } from 'react';
 import { TextFieldProps } from '@mui/material';
 import { SxProps, Theme } from '@mui/material/styles';
 import { RegisterOptions } from 'react-hook-form';
-export interface SelectOption {
-    value: string | number;
+/** Key estable usada para comparar values, indexar caches y como React key. */
+export type AutocompleteValueKey = string | number;
+export interface SelectOption<TValue = AutocompleteValueKey> {
+    value: TValue;
     label: string;
     img?: string;
     disabled?: boolean;
@@ -12,11 +14,12 @@ export interface SelectOption {
 }
 export type LabelPosition = 'outside' | 'floating';
 export type AutocompleteSize = 'small' | 'medium';
-export type RenderOptionItem = (item: SelectOption) => ReactNode;
-export type RenderChipLabel = (item: SelectOption) => ReactNode;
-export type BaseAutocompleteProps<_TValue extends SelectOption['value'] = SelectOption['value']> = {
+export type RenderOptionItem<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderChipLabel<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type RenderSingleValue<TValue = AutocompleteValueKey> = (item: SelectOption<TValue>) => ReactNode;
+export type BaseAutocompleteProps<TValue = AutocompleteValueKey> = {
     label?: string;
-    options: SelectOption[];
+    options: SelectOption<TValue>[];
     placeholder?: string;
     multiple?: boolean;
     disabled?: boolean;
@@ -25,8 +28,22 @@ export type BaseAutocompleteProps<_TValue extends SelectOption['value'] = Select
     error?: boolean;
     helperText?: string;
     maxChipsToShow?: number;
-    renderOptionItem?: RenderOptionItem;
-    renderChipLabel?: RenderChipLabel;
+    renderOptionItem?: RenderOptionItem<TValue>;
+    renderChipLabel?: RenderChipLabel<TValue>;
+    /**
+     * Renderiza JSX custom como `startAdornment` del input en single mode.
+     * Recibe la `SelectOption` seleccionada. Útil para mostrar avatars, iconos,
+     * etc. junto al texto del label. En `multiple` no aplica (se usa `renderChipLabel`).
+     */
+    renderSingleValue?: RenderSingleValue<TValue>;
+    /**
+     * Extrae una key estable (string | number) desde el `value`. Obligatorio
+     * cuando `TValue` es un objeto: se usa para comparar values (`isOptionEqualToValue`,
+     * resolución desde el value del form), indexar el cache interno de opciones
+     * vistas y como React key en chips/options del dropdown. Para primitivos se
+     * puede omitir (default: identidad, o sea `===`).
+     */
+    getOptionKey?: (value: TValue) => AutocompleteValueKey;
     /** Border radius del input. Default: 10. */
     borderRadius?: number | string;
     /** "outside" (default) = label arriba del input; "floating" = comportamiento nativo MUI. */
@@ -52,21 +69,21 @@ export type BaseAutocompleteProps<_TValue extends SelectOption['value'] = Select
     /** 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[];
+    filterOptions?: (options: SelectOption<TValue>[], state: any) => SelectOption<TValue>[];
     /** Permite valores arbitrarios (no solo de la lista). */
     freeSolo?: boolean;
     open?: boolean;
     onOpen?: (event: SyntheticEvent) => void;
     onClose?: (event: SyntheticEvent, reason: string) => void;
 };
-export interface ControlledAutocompleteProps<TValue extends SelectOption['value'] = SelectOption['value']> extends BaseAutocompleteProps<TValue> {
+export interface ControlledAutocompleteProps<TValue = AutocompleteValueKey> 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> {
+export interface RHFAutocompleteProps<TValue = AutocompleteValueKey> extends BaseAutocompleteProps<TValue> {
     name: string;
     control: any;
     validation?: RegisterOptions;
@@ -78,8 +95,8 @@ export interface RHFAutocompleteProps<TValue extends SelectOption['value'] = Sel
     value?: never;
     onChange?: never;
 }
-export type AutocompleteProps<TValue extends SelectOption['value'] = SelectOption['value']> = ControlledAutocompleteProps<TValue> | RHFAutocompleteProps<TValue>;
-export declare function Autocomplete<TValue extends SelectOption['value'] = SelectOption['value']>(props: AutocompleteProps<TValue>): import("react/jsx-runtime").JSX.Element;
+export type AutocompleteProps<TValue = AutocompleteValueKey> = ControlledAutocompleteProps<TValue> | RHFAutocompleteProps<TValue>;
+export declare function Autocomplete<TValue = AutocompleteValueKey>(props: AutocompleteProps<TValue>): import("react/jsx-runtime").JSX.Element;
 /** Alias de `Autocomplete`. Ambos nombres son equivalentes. */
 export declare const AutocompleteSelect: typeof Autocomplete;
 export default Autocomplete;