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

package/src/components/Autocomplete/Autocomplete.helpers.ts

@@ -0,0 +1,60 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { SelectOption } from './Autocomplete';
+
+/** Resuelve un value único a su SelectOption dentro del pool. */
+export const resolveSingleValue = (
+  options: SelectOption[],
+  value: SelectOption['value'] | null | undefined,
+): SelectOption | null => options.find((o) => o.value === value) ?? null;
+
+/** Resuelve un array de values a sus SelectOption dentro del pool. */
+export const resolveMultipleValue = (
+  options: SelectOption[],
+  value: SelectOption['value'][] | null | undefined,
+): SelectOption[] => {
+  if (!Array.isArray(value)) return [];
+  return options.filter((o) => value.includes(o.value));
+};
+
+/** Merge de sx base + extra del consumer, respetando el contrato de MUI. */
+export const mergeSx = (
+  base: SxProps<Theme>,
+  extra?: SxProps<Theme>,
+): SxProps<Theme> => {
+  if (!extra) return base;
+  return [base, ...(Array.isArray(extra) ? extra : [extra])] as SxProps<Theme>;
+};
+
+/**
+ * Compara dos valores resueltos (single o multiple) por value para decidir
+ * si son estructuralmente iguales. Se usa para estabilizar la referencia que
+ * se pasa a MUI Autocomplete (MUI compara value por referencia con `!==`,
+ * y una nueva referencia — aunque el contenido sea igual — dispara
+ * `resetInputValue` y borra el texto mientras el usuario tipea).
+ */
+export const areResolvedValuesEqual = (
+  prev: SelectOption | SelectOption[] | null,
+  next: SelectOption | SelectOption[] | null,
+  multiple: boolean,
+): boolean => {
+  if (multiple) {
+    if (!Array.isArray(prev) || !Array.isArray(next)) return false;
+    if (prev.length !== next.length) return false;
+    return prev.every((o, i) => o.value === next[i]?.value);
+  }
+  return (
+    (prev as SelectOption | null)?.value ===
+    (next as SelectOption | null)?.value
+  );
+};
+
+/** Determina si un valor resuelto está vacío (para placeholder/shrink). */
+export const isResolvedValueEmpty = (
+  resolvedValue: unknown,
+  multiple: boolean,
+): boolean => {
+  if (multiple) {
+    return !Array.isArray(resolvedValue) || resolvedValue.length === 0;
+  }
+  return !resolvedValue;
+};

package/src/components/Autocomplete/Autocomplete.stories.tsx

@@ -1,6 +1,7 @@
+import { useState, useEffect, useMemo } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
-import React, { useState } from "react";
-import { Box, Typography, Avatar } from "@mui/material";
+import { Box, Typography, Avatar, Stack, Button } from "@mui/material";
+import { useForm } from "react-hook-form";
 
 import Autocomplete, { SelectOption } from "./Autocomplete";
 import {
@@ -12,6 +13,12 @@ import {
   MultipleWithLimitAutocompleteDefinition,
   SimpleAutocompleteDefinition,
   WithPlaceholderAutocompleteDefinition,
+  WithErrorAutocompleteDefinition,
+  LabelPositionAutocompleteDefinition,
+  CustomBorderRadiusAutocompleteDefinition,
+  EmptyWithPlaceholderAutocompleteDefinition,
+  RHFAutocompleteDefinition,
+  AsyncServiceAutocompleteDefinition,
 } from "./Autocomplete.definitions";
 
 // =============================================================================
@@ -385,3 +392,357 @@ export const ManyOptions: Story = {
     },
   },
 };
+
+// =============================================================================
+// NUEVAS STORIES — API refactorizada
+// =============================================================================
+
+export const WithError: Story = {
+  render: () => {
+    const [value, setValue] = useState<string | null>(null);
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Cantidad"
+          options={basicOptions}
+          value={value}
+          onChange={(val) => setValue(val as string | null)}
+          error={!value}
+          helperText={!value ? "Debes seleccionar una cantidad" : " "}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete en estado de error con `helperText`. Muestra la validación visual (borde + label + texto en rojo).",
+      },
+      source: { code: WithErrorAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const LabelPosition: Story = {
+  render: () => {
+    const [a, setA] = useState<string | null>(null);
+    const [b, setB] = useState<string | null>(null);
+    return (
+      <Stack spacing={3} sx={{ width: 320 }}>
+        <Autocomplete
+          label="Outside (default)"
+          labelPosition="outside"
+          options={basicOptions}
+          value={a}
+          onChange={(val) => setA(val as string | null)}
+        />
+        <Autocomplete
+          label="Floating"
+          labelPosition="floating"
+          options={basicOptions}
+          value={b}
+          onChange={(val) => setB(val as string | null)}
+        />
+      </Stack>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Comparación entre `labelPosition='outside'` (label arriba del input, consistente con Input/Select/DatePicker) y `labelPosition='floating'` (comportamiento nativo MUI dentro del notch).",
+      },
+      source: { code: LabelPositionAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const CustomBorderRadius: Story = {
+  render: () => {
+    const [a, setA] = useState<string | null>(null);
+    const [b, setB] = useState<string | null>(null);
+    const [c, setC] = useState<string | null>(null);
+    return (
+      <Stack spacing={2} sx={{ width: 300 }}>
+        <Autocomplete
+          label="0"
+          borderRadius={0}
+          options={basicOptions}
+          value={a}
+          onChange={(v) => setA(v as string | null)}
+        />
+        <Autocomplete
+          label="10 (default)"
+          borderRadius={10}
+          options={basicOptions}
+          value={b}
+          onChange={(v) => setB(v as string | null)}
+        />
+        <Autocomplete
+          label="24 (pill)"
+          borderRadius={24}
+          options={basicOptions}
+          value={c}
+          onChange={(v) => setC(v as string | null)}
+        />
+      </Stack>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "La prop `borderRadius` permite personalizar el radio del borde sin usar `sx` (acepta number en px o string).",
+      },
+      source: { code: CustomBorderRadiusAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const EmptyWithPlaceholder: Story = {
+  render: () => {
+    const [value, setValue] = useState<string | null>(null);
+    const countries: SelectOption[] = [
+      { value: "mx", label: "México" },
+      { value: "co", label: "Colombia" },
+      { value: "ar", label: "Argentina" },
+    ];
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="País"
+          placeholder="Buscar país..."
+          options={countries}
+          value={value}
+          onChange={(val) => setValue(val as string | null)}
+        />
+        <Typography sx={{ mt: 2 }} variant="caption" color="text.secondary">
+          Al estar vacío y sin foco, solo se ve el label como placeholder. Al
+          enfocar, el label sube y aparece el placeholder real.
+        </Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete vacío con placeholder. El placeholder solo se muestra cuando el campo está enfocado (mismo patrón que Select/Input).",
+      },
+      source: { code: EmptyWithPlaceholderAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const WithReactHookForm: Story = {
+  render: () => {
+    type FormValues = { country: string | null };
+    const { control, handleSubmit, watch } = useForm<FormValues>({
+      defaultValues: { country: null },
+    });
+    const countries: SelectOption[] = [
+      { value: "mx", label: "México" },
+      { value: "co", label: "Colombia" },
+      { value: "ar", label: "Argentina" },
+    ];
+
+    const [submitted, setSubmitted] = useState<FormValues | null>(null);
+
+    return (
+      <Box
+        component="form"
+        onSubmit={handleSubmit((data) => setSubmitted(data))}
+      >
+        <Stack spacing={2} sx={{ width: 320 }}>
+          <Autocomplete
+            name="country"
+            control={control}
+            validation={{ required: "Campo requerido" }}
+            label="País"
+            placeholder="Seleccione..."
+            options={countries}
+          />
+          <Button type="submit" variant="contained">
+            Guardar
+          </Button>
+          <Typography variant="caption" color="text.secondary">
+            Valor actual (watch): {JSON.stringify(watch("country"))}
+          </Typography>
+          {submitted && (
+            <Typography variant="caption" color="success.main">
+              Submit: {JSON.stringify(submitted)}
+            </Typography>
+          )}
+        </Stack>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Integración con React Hook Form usando `name`/`control`/`validation`. El error de validación se renderiza automáticamente como helperText.",
+      },
+      source: { code: RHFAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+// =============================================================================
+// ASYNC — búsqueda remota contra un servicio
+// =============================================================================
+// Simulador de servicio: hace una "llamada" a una API fake con latencia.
+const mockUsersDb: SelectOption[] = [
+  { value: 1, label: "Andrea García" },
+  { value: 2, label: "Andrés Pérez" },
+  { value: 3, label: "Beatriz López" },
+  { value: 4, label: "Carlos Ruiz" },
+  { value: 5, label: "Camila Torres" },
+  { value: 6, label: "Diego Fernández" },
+  { value: 7, label: "Elena Morales" },
+  { value: 8, label: "Fabián Núñez" },
+];
+
+const fakeFetchUsers = (query: string): Promise<SelectOption[]> =>
+  new Promise((resolve) => {
+    setTimeout(() => {
+      if (!query) return resolve([]);
+      const q = query.toLowerCase();
+      resolve(mockUsersDb.filter((u) => u.label.toLowerCase().includes(q)));
+    }, 400);
+  });
+
+// Debounce casero (para no agregar lodash como dep de la story).
+function debounce<T extends (...args: any[]) => void>(fn: T, ms: number) {
+  let t: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+}
+
+export const AsyncService: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(null);
+    const [input, setInput] = useState("");
+    const [options, setOptions] = useState<SelectOption[]>([]);
+    const [loading, setLoading] = useState(false);
+
+    const search = useMemo(
+      () =>
+        debounce(async (q: string) => {
+          if (!q) {
+            setOptions([]);
+            return;
+          }
+          setLoading(true);
+          try {
+            const res = await fakeFetchUsers(q);
+            setOptions(res);
+          } finally {
+            setLoading(false);
+          }
+        }, 300),
+      [],
+    );
+
+    useEffect(() => {
+      search(input);
+    }, [input, search]);
+
+    return (
+      <Box sx={{ width: 320 }}>
+        <Autocomplete<number>
+          label="Usuario"
+          placeholder="Buscar usuario..."
+          options={options}
+          value={value}
+          onChange={(v) => setValue(v as number | null)}
+          inputValue={input}
+          onInputChange={(_, v) => setInput(v)}
+          loading={loading}
+          // Desactiva filtro cliente: confiamos en el servicio.
+          filterOptions={(x) => x}
+        />
+        <Typography sx={{ mt: 2 }} variant="caption" color="text.secondary">
+          {"Escribe para buscar. El servicio se consulta con debounce (300ms). filterOptions={(x) => x} desactiva el filtro cliente."}
+        </Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Búsqueda asíncrona contra un servicio. El consumer maneja el estado de `options`/`loading` y reacciona a `onInputChange` para llamar al servicio. Usar `filterOptions={(x) => x}` para desactivar el filtro cliente.",
+      },
+      source: { code: AsyncServiceAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const AsyncServiceMultiple: Story = {
+  render: () => {
+    const [value, setValue] = useState<number[]>([]);
+    const [input, setInput] = useState("");
+    const [options, setOptions] = useState<SelectOption[]>([]);
+    const [loading, setLoading] = useState(false);
+
+    const search = useMemo(
+      () =>
+        debounce(async (q: string) => {
+          if (!q) {
+            setOptions([]);
+            return;
+          }
+          setLoading(true);
+          try {
+            const res = await fakeFetchUsers(q);
+            setOptions(res);
+          } finally {
+            setLoading(false);
+          }
+        }, 300),
+      [],
+    );
+
+    useEffect(() => {
+      search(input);
+    }, [input, search]);
+
+    return (
+      <Box sx={{ width: 420 }}>
+        <Autocomplete<number>
+          multiple
+          maxChipsToShow={4}
+          label="Usuarios"
+          placeholder="Buscar y seleccionar varios..."
+          options={options}
+          value={value}
+          onChange={(v) => setValue(v as number[])}
+          inputValue={input}
+          onInputChange={(_, v) => setInput(v)}
+          loading={loading}
+          filterOptions={(x) => x}
+        />
+        <Typography sx={{ mt: 2 }} variant="caption" color="text.secondary">
+          Selecciona varios usuarios buscando con diferentes queries. Los chips
+          persisten aunque el search cambie las `options` (cache interno).
+        </Typography>
+        <Typography sx={{ mt: 1 }} variant="caption" display="block">
+          Seleccionados: {JSON.stringify(value)}
+        </Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Búsqueda asíncrona **con selección múltiple**. El componente mantiene un cache interno de opciones ya vistas, así los chips de los items seleccionados NO desaparecen cuando el usuario busca otros términos. Flujo: buscar 'an' → seleccionar Andrea → buscar 'be' → seleccionar Beatriz → los dos chips siguen visibles.",
+      },
+      source: { code: AsyncServiceAutocompleteDefinition.trim() },
+    },
+  },
+};

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