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

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

@@ -0,0 +1,784 @@
+import { useState, useEffect, useMemo } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Box, Typography, Avatar, Stack, Button } from "@mui/material";
+import { useForm } from "react-hook-form";
+
+import Autocomplete, { SelectOption } from "./Autocomplete";
+import {
+  CustomChipRenderAutocompleteDefinition,
+  CustomRenderOptionAutocompleteDefinition,
+  EmptyOptionsAutocompleteDefinition,
+  LoadingAutocompleteDefinition,
+  MultipleAutocompleteDefinition,
+  MultipleWithLimitAutocompleteDefinition,
+  SimpleAutocompleteDefinition,
+  WithPlaceholderAutocompleteDefinition,
+  WithErrorAutocompleteDefinition,
+  LabelPositionAutocompleteDefinition,
+  CustomBorderRadiusAutocompleteDefinition,
+  EmptyWithPlaceholderAutocompleteDefinition,
+  RHFAutocompleteDefinition,
+  AsyncServiceAutocompleteDefinition,
+} from "./Autocomplete.definitions";
+
+// =============================================================================
+// Datos de ejemplo
+// =============================================================================
+const basicOptions: SelectOption[] = [
+  { value: "10", label: "10" },
+  { value: "25", label: "25" },
+  { value: "50", label: "50" },
+  { value: "100", label: "100" },
+];
+
+const userOptions: SelectOption[] = [
+  {
+    value: "admin",
+    label: "Administrador",
+    img: "https://placehold.co/40x40?text=A",
+  },
+  { value: "user", label: "Usuario", img: "https://placehold.co/40x40?text=U" },
+  {
+    value: "moderator",
+    label: "Moderador",
+    img: "https://placehold.co/40x40?text=M",
+  },
+];
+
+const manyOptions = Array.from({ length: 50 }, (_, i) => ({
+  value: `option-${i}`,
+  label: `Opción ${i + 1}`,
+}));
+
+// =============================================================================
+// META
+// =============================================================================
+const meta: Meta<typeof Autocomplete> = {
+  title: "Components/Autocomplete",
+  component: Autocomplete,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "Autocomplete personalizado basado en MUI con soporte para selección múltiple, chips, render custom y async.",
+      },
+    },
+  },
+  argTypes: {
+    label: {
+      control: "text",
+      description: "Etiqueta para el campo de selección.",
+    },
+    options: {
+      control: "object",
+      description:
+        "Array de objetos `SelectOption` para las opciones del menú.",
+    },
+    value: {
+      control: "object",
+      description: "Valor(es) seleccionado(s) del select.",
+    },
+    onChange: {
+      action: "changed",
+      description:
+        "Función de callback que se llama cuando el valor del select cambia.",
+    },
+    multiple: {
+      control: "boolean",
+      description:
+        "Si es verdadero, permite la selección de múltiples opciones.",
+    },
+    placeholder: {
+      control: "text",
+      description: "Texto que se muestra cuando no hay nada seleccionado.",
+    },
+    maxChipsToShow: {
+      control: "number",
+      description:
+        "Número máximo de chips a mostrar en selección múltiple antes de agrupar.",
+      if: { arg: "multiple", eq: true },
+    },
+    renderChipLabel: {
+      control: false,
+      description:
+        "Función para personalizar el contenido del label de cada chip seleccionado (para múltiple) o del valor mostrado (para individual).",
+    },
+    labelPosition: {
+      control: { type: "radio" },
+      options: ["outside", "floating"],
+      description:
+        "`outside` = label siempre arriba del input (default del paquete). `floating` = comportamiento nativo de MUI (label dentro del input hasta que se enfoca o hay valor).",
+      table: { defaultValue: { summary: "outside" } },
+    },
+  },
+  args: {
+    labelPosition: "outside",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Autocomplete>;
+
+// =============================================================================
+// STORIES
+// =============================================================================
+
+export const Simple: Story = {
+  args: {
+    label: "Registros por página",
+    options: basicOptions,
+    placeholder: "Seleccione...",
+  },
+  render: (args) => {
+    const [value, setValue] = useState<string | null>("25");
+
+    return (
+      <Box sx={{ width: 250 }}>
+        <Autocomplete
+          label={args.label}
+          options={args.options}
+          placeholder={args.placeholder}
+          labelPosition={args.labelPosition}
+          multiple={args.multiple}
+          disabled={args.disabled}
+          size={args.size}
+          borderRadius={args.borderRadius}
+          value={value}
+          onChange={(val) => setValue(val as string | null)}
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {String(value)}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete simple. Usá el panel de Controls (en la vista Canvas) para cambiar `labelPosition`, `placeholder`, etc. en vivo. Tip: borrá el valor y abrí el input para ver la diferencia entre `outside` y `floating`.",
+      },
+      source: { code: SimpleAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const WithPlaceholder: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Seleccione una opción"
+          options={basicOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string);
+          }}
+          placeholder="Ninguna opción seleccionada"
+          labelPosition={args.labelPosition}
+        />
+        <Typography sx={{ mt: 2 }}>{value || "Ninguno"}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete sin valor inicial que muestra un placeholder cuando no hay selección.",
+      },
+      source: { code: WithPlaceholderAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const Multiple: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string[]>([]);
+
+    return (
+      <Box sx={{ width: 400 }}>
+        <Autocomplete
+          label="Seleccionar valores"
+          multiple
+          options={basicOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string[]);
+          }}
+          labelPosition={args.labelPosition}
+        />
+        <Typography sx={{ mt: 2 }}>
+          Valor seleccionado: {JSON.stringify(value)}
+        </Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete en modo múltiple que permite seleccionar varias opciones y las muestra como chips.",
+      },
+      source: { code: MultipleAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const MultipleWithLimit: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string[]>(
+      manyOptions.slice(0, 5).map((opt) => opt.value),
+    );
+
+    return (
+      <Box sx={{ width: 400 }}>
+        <Autocomplete
+          label="Muchas selecciones"
+          multiple
+          maxChipsToShow={2}
+          options={manyOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string[]);
+          }}
+          labelPosition={args.labelPosition}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete múltiple con límite de chips visibles, agrupando el resto en un contador.",
+      },
+      source: { code: MultipleWithLimitAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const CustomRenderOption: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string[]>([]);
+
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Usuarios"
+          multiple
+          options={userOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string[]);
+          }}
+          labelPosition={args.labelPosition}
+          renderOptionItem={(item) => (
+            <Box sx={{ display: "flex", gap: 1, alignItems: "center" }}>
+              <Avatar src={item.img} sx={{ width: 24, height: 24 }} />
+              {item.label}
+            </Box>
+          )}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete con renderizado personalizado de opciones, incluyendo avatar e información adicional.",
+      },
+      source: { code: CustomRenderOptionAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const CustomChipRender: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string[]>([]);
+
+    return (
+      <Box sx={{ width: 400 }}>
+        <Autocomplete
+          label="Usuarios seleccionados"
+          multiple
+          options={userOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string[]);
+          }}
+          maxChipsToShow={2}
+          labelPosition={args.labelPosition}
+          renderChipLabel={(item) => (
+            <Typography variant="caption" fontWeight="bold">
+              {item.label.charAt(0)}
+            </Typography>
+          )}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete múltiple con renderizado personalizado de chips, mostrando solo la inicial del label.",
+      },
+      source: { code: CustomChipRenderAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const Loading: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Cargando..."
+          options={[]}
+          loading
+          value={value}
+          onChange={(val) => {
+            setValue(val as string);
+          }}
+          labelPosition={args.labelPosition}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete en estado de carga, útil para integraciones con APIs o búsquedas asíncronas.",
+      },
+      source: { code: LoadingAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const EmptyOptions: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Sin opciones"
+          options={[]}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string);
+          }}
+          placeholder="No hay opciones"
+          labelPosition={args.labelPosition}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete sin opciones disponibles, mostrando mensaje vacío al usuario.",
+      },
+      source: { code: EmptyOptionsAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+export const ManyOptions: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+      <Box sx={{ width: 300 }}>
+        <Autocomplete
+          label="Muchas opciones"
+          options={manyOptions}
+          value={value}
+          onChange={(val) => {
+            setValue(val as string);
+          }}
+          labelPosition={args.labelPosition}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Autocomplete sin opciones disponibles, mostrando mensaje vacío al usuario.",
+      },
+      source: { code: EmptyOptionsAutocompleteDefinition.trim() },
+    },
+  },
+};
+
+// =============================================================================
+// NUEVAS STORIES — API refactorizada
+// =============================================================================
+
+export const WithError: Story = {
+  render: (args) => {
+    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" : " "}
+          labelPosition={args.labelPosition}
+        />
+      </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: (args) => {
+    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)}
+          labelPosition={args.labelPosition}
+        />
+        <Autocomplete
+          label="10 (default)"
+          borderRadius={10}
+          options={basicOptions}
+          value={b}
+          onChange={(v) => setB(v as string | null)}
+          labelPosition={args.labelPosition}
+        />
+        <Autocomplete
+          label="24 (pill)"
+          borderRadius={24}
+          options={basicOptions}
+          value={c}
+          onChange={(v) => setC(v as string | null)}
+          labelPosition={args.labelPosition}
+        />
+      </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: (args) => {
+    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)}
+          labelPosition={args.labelPosition}
+        />
+        <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: (args) => {
+    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}
+            labelPosition={args.labelPosition}
+          />
+          <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: (args) => {
+    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}
+          labelPosition={args.labelPosition}
+          // 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: (args) => {
+    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}
+          labelPosition={args.labelPosition}
+          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() },
+    },
+  },
+};