@soyfri/shared-library 2.0.0-beta.17 → 2.0.0-beta.19

package/src/components/Select/Select.helpers.ts

@@ -0,0 +1,31 @@
+import type { SelectOption } from './Select';
+
+/**
+ * Agrupa opciones por la propiedad `group`. Las opciones sin group caen
+ * bajo la key especial `__default`. Devuelve un Record para iterar en orden
+ * de inserción con Object.entries.
+ */
+export const groupOptions = (
+  options: SelectOption[],
+): Record<string, SelectOption[]> => {
+  const groups: Record<string, SelectOption[]> = {};
+  options.forEach((opt) => {
+    const group = opt.group || '__default';
+    if (!groups[group]) groups[group] = [];
+    groups[group].push(opt);
+  });
+  return groups;
+};
+
+/**
+ * Normaliza el valor single al shape que espera MUI Select: string vacío si
+ * el valor es `null`/`undefined`.
+ */
+export const normalizeSelectValue = <T>(value: T | null | undefined): T | '' =>
+  (value ?? '') as T | '';
+
+/** `true` si el valor está vacío (para shrink del label + placeholder). */
+export const isSelectValueEmpty = (normalizedValue: unknown): boolean =>
+  normalizedValue === '' ||
+  normalizedValue === null ||
+  normalizedValue === undefined;

package/src/components/Select/Select.stories.tsx

@@ -0,0 +1,393 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useMemo, useState } from 'react';
+import { Avatar, Box, Stack, Typography } from '@mui/material';
+import { useForm, useWatch } from 'react-hook-form';
+
+import Select, { Option, type SelectOption } from './Select';
+
+// =============================================================================
+// Datos de ejemplo
+// =============================================================================
+const basicOptions: SelectOption[] = [
+  { value: '10', label: '10' },
+  { value: '25', label: '25' },
+  { value: '50', label: '50' },
+  { value: '100', label: '100' },
+];
+
+const groupedOptions: SelectOption[] = [
+  { value: 'gt', label: 'Guatemala', group: 'Centroamérica' },
+  { value: 'sv', label: 'El Salvador', group: 'Centroamérica' },
+  { value: 'mx', label: 'México', group: 'Norteamérica' },
+  { value: 'us', label: 'EE.UU.', group: 'Norteamérica' },
+  { value: 'ca', label: 'Canadá', group: 'Norteamérica' },
+  { value: 'br', label: 'Brasil', group: 'Sudamérica' },
+  { value: 'ar', label: 'Argentina', group: 'Sudamérica' },
+];
+
+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' },
+  { value: 'guest', label: 'Invitado', img: 'https://placehold.co/40x40?text=G', disabled: true },
+];
+
+// =============================================================================
+// Meta
+// =============================================================================
+const meta: Meta<typeof Select> = {
+  title: 'Components/Select',
+  component: Select,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Select dropdown para listas cortas/fijas (statuses, roles, prioridades). Para búsqueda, async o multi-select, usar `<Autocomplete>`.',
+      },
+    },
+  },
+  argTypes: {
+    label: { control: 'text' },
+    options: { control: 'object' },
+    size: { control: 'radio', options: ['small', 'medium'] },
+    placeholder: { control: 'text' },
+    maxHeight: { control: 'number' },
+    maxWidth: { control: 'text' },
+    labelPosition: { control: 'radio', options: ['outside', 'floating'] },
+    borderRadius: { control: 'number' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Select>;
+
+// =============================================================================
+// Stories
+// =============================================================================
+
+export const SimpleSelect: Story = {
+  render: () => {
+    const [value, setValue] = useState<string>('25');
+    return (
+      <Box sx={{ width: 200 }}>
+        <Select
+          label="Registros por página"
+          options={basicOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {value}</Typography>
+      </Box>
+    );
+  },
+};
+
+export const WithPlaceholder: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="Seleccione una opción"
+          options={basicOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+          placeholder="Ninguna opción seleccionada"
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {value || 'Ninguno'}</Typography>
+      </Box>
+    );
+  },
+};
+
+export const WithGroup: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="País por región"
+          options={groupedOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {value}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Opciones agrupadas por la propiedad `group` — renderiza `<ListSubheader>` entre grupos.',
+      },
+    },
+  },
+};
+
+export const CustomRenderWithAvatar: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="Usuario"
+          options={userOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+          placeholder="Selecciona un usuario"
+        >
+          <Option>
+            {({ img, label }) => (
+              <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                <Avatar src={img} sx={{ width: 24, height: 24 }} />
+                <Typography variant="body2">{label}</Typography>
+              </Box>
+            )}
+          </Option>
+        </Select>
+        <Typography sx={{ mt: 2 }}>Valor: {value}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Render custom de cada opción del menú via `<Option>{item => ...}</Option>`.',
+      },
+    },
+  },
+};
+
+export const ConstrainedHeight: Story = {
+  render: () => {
+    const manyOptions = Array.from({ length: 30 }, (_, i) => ({
+      value: `opt-${i}`,
+      label: `Opción ${i + 1}`,
+    }));
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="Altura limitada"
+          options={manyOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+          maxHeight={150}
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {value}</Typography>
+      </Box>
+    );
+  },
+};
+
+export const LabelPositionFloating: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="Label flotante (MUI nativo)"
+          options={basicOptions}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+          labelPosition="floating"
+        />
+        <Typography sx={{ mt: 2 }}>Valor: {value || 'Ninguno'}</Typography>
+      </Box>
+    );
+  },
+};
+
+export const CustomBorderRadius: Story = {
+  render: () => {
+    const [a, setA] = useState('25');
+    const [b, setB] = useState('25');
+    const [c, setC] = useState('25');
+    return (
+      <Box sx={{ width: 300, display: 'flex', flexDirection: 'column', gap: 2 }}>
+        <Select label="0" options={basicOptions} value={a} onChange={(v) => setA(v as string)} borderRadius={0} />
+        <Select label="10 (default)" options={basicOptions} value={b} onChange={(v) => setB(v as string)} borderRadius={10} />
+        <Select label="Pill" options={basicOptions} value={c} onChange={(v) => setC(v as string)} borderRadius={999} />
+      </Box>
+    );
+  },
+};
+
+export const EmptyOptions: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    return (
+      <Box sx={{ width: 300 }}>
+        <Select
+          label="Sin opciones"
+          options={[]}
+          value={value}
+          onChange={(val) => setValue(val as string)}
+          placeholder="No hay opciones"
+        />
+      </Box>
+    );
+  },
+};
+
+// =============================================================================
+// Selects dependientes (cascada) — patrón departamento / municipio
+// =============================================================================
+
+const DEPARTAMENTOS: SelectOption[] = [
+  { value: 'gt', label: 'Guatemala' },
+  { value: 'sa', label: 'Sacatepéquez' },
+  { value: 'qz', label: 'Quetzaltenango' },
+];
+
+const MUNICIPIOS_BY_DEPTO: Record<string, SelectOption[]> = {
+  gt: [
+    { value: 'gt-city', label: 'Ciudad de Guatemala' },
+    { value: 'mixco', label: 'Mixco' },
+    { value: 'villa-nueva', label: 'Villa Nueva' },
+  ],
+  sa: [
+    { value: 'antigua', label: 'Antigua Guatemala' },
+    { value: 'jocotenango', label: 'Jocotenango' },
+    { value: 'ciudad-vieja', label: 'Ciudad Vieja' },
+  ],
+  qz: [
+    { value: 'xela', label: 'Quetzaltenango' },
+    { value: 'salcaja', label: 'Salcajá' },
+    { value: 'almolonga', label: 'Almolonga' },
+  ],
+};
+
+type CascadeForm = { departamento: string; municipio: string };
+
+const DependentSelectsExample = () => {
+  const { control, setValue } = useForm<CascadeForm>({
+    defaultValues: { departamento: '', municipio: '' },
+  });
+
+  // Observa el depto para filtrar las opciones de municipio.
+  const departamento = useWatch({ control, name: 'departamento' });
+
+  const municipios = useMemo(
+    () => (departamento ? MUNICIPIOS_BY_DEPTO[departamento] ?? [] : []),
+    [departamento],
+  );
+
+  return (
+    <Stack spacing={2} sx={{ width: 320 }}>
+      <Select
+        label="Departamento"
+        control={control}
+        name="departamento"
+        options={DEPARTAMENTOS}
+        placeholder="Selecciona un departamento"
+        // Cuando cambia el depto, reset del municipio — el side-effect corre
+        // DESPUÉS de que RHF actualizó el form state.
+        onValueChange={() => setValue('municipio', '')}
+      />
+
+      <Select
+        label="Municipio"
+        control={control}
+        name="municipio"
+        options={municipios}
+        placeholder={
+          departamento ? 'Selecciona un municipio' : 'Primero elige departamento'
+        }
+        disabled={!departamento}
+      />
+
+      <Typography variant="caption" color="text.secondary">
+        Observá cómo al cambiar el departamento, el municipio se vacía
+        automáticamente sin usar `useEffect`.
+      </Typography>
+    </Stack>
+  );
+};
+
+export const DependentSelects: Story = {
+  render: () => <DependentSelectsExample />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Patrón **cascading selects** — dos selects dependientes donde el segundo se resetea cuando cambia el primero. Usa `onValueChange` (solo disponible en modo RHF) para disparar el reset **en el momento del onChange**, sin `useEffect` ni subscripciones manuales. El `onValueChange` corre **después** de que RHF actualiza el form state, garantizando orden correcto.',
+      },
+      source: {
+        code: `import { useMemo } from 'react';
+import { useForm, useWatch } from 'react-hook-form';
+import { Stack } from '@soyfri/shared-library';
+import { Select, type SelectOption } from '@soyfri/shared-library/components/Select';
+
+const DEPARTAMENTOS: SelectOption[] = [
+  { value: 'gt', label: 'Guatemala' },
+  { value: 'sa', label: 'Sacatepéquez' },
+  { value: 'qz', label: 'Quetzaltenango' },
+];
+
+const MUNICIPIOS_BY_DEPTO: Record<string, SelectOption[]> = {
+  gt: [
+    { value: 'gt-city', label: 'Ciudad de Guatemala' },
+    { value: 'mixco', label: 'Mixco' },
+    { value: 'villa-nueva', label: 'Villa Nueva' },
+  ],
+  sa: [
+    { value: 'antigua', label: 'Antigua Guatemala' },
+    { value: 'jocotenango', label: 'Jocotenango' },
+    { value: 'ciudad-vieja', label: 'Ciudad Vieja' },
+  ],
+  qz: [
+    { value: 'xela', label: 'Quetzaltenango' },
+    { value: 'salcaja', label: 'Salcajá' },
+    { value: 'almolonga', label: 'Almolonga' },
+  ],
+};
+
+type CascadeForm = { departamento: string; municipio: string };
+
+export const DependentSelects = () => {
+  const { control, setValue } = useForm<CascadeForm>({
+    defaultValues: { departamento: '', municipio: '' },
+  });
+
+  // Observa el depto para filtrar las opciones de municipio.
+  const departamento = useWatch({ control, name: 'departamento' });
+
+  const municipios = useMemo(
+    () => (departamento ? MUNICIPIOS_BY_DEPTO[departamento] ?? [] : []),
+    [departamento],
+  );
+
+  return (
+    <Stack spacing={2} sx={{ width: 320 }}>
+      <Select
+        label="Departamento"
+        control={control}
+        name="departamento"
+        options={DEPARTAMENTOS}
+        placeholder="Selecciona un departamento"
+        // Reset del municipio al cambiar el depto — sin useEffect.
+        onValueChange={() => setValue('municipio', '')}
+      />
+
+      <Select
+        label="Municipio"
+        control={control}
+        name="municipio"
+        options={municipios}
+        placeholder={
+          departamento ? 'Selecciona un municipio' : 'Primero elige departamento'
+        }
+        disabled={!departamento}
+      />
+    </Stack>
+  );
+};`,
+      },
+    },
+  },
+};

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

@@ -0,0 +1,15 @@
+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,
+  layoutOnly = false,
+): MuiSelectProps['sx'] =>
+  buildFormFieldSx({ borderRadius, labelPosition, layoutOnly }) as MuiSelectProps['sx'];