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

package/src/components/Stepper/_parts/StepperScrollArrow.tsx

@@ -0,0 +1,50 @@
+import { IconButton } from '@mui/material';
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+
+interface StepperScrollArrowProps {
+  direction: 'left' | 'right';
+  /** Cuando `false`, el botón está deshabilitado (por ejemplo, ya estás al inicio). */
+  enabled: boolean;
+  /**
+   * Cuando `false`, el botón queda con `visibility: hidden` (reserva su
+   * espacio pero no se ve). Útil para que el área de scroll no se corra
+   * horizontalmente cuando no hay overflow en ningún lado.
+   */
+  visible: boolean;
+  onClick: () => void;
+}
+
+/**
+ * Flecha de scroll (`<` / `>`) del Stepper horizontal. Se muestra a los
+ * costados del área scrollable cuando hay overflow. Componente privado —
+ * no se exporta del barrel.
+ */
+export const StepperScrollArrow = ({
+  direction,
+  enabled,
+  visible,
+  onClick,
+}: StepperScrollArrowProps) => {
+  const isLeft = direction === 'left';
+  const Icon = isLeft ? ChevronLeftIcon : ChevronRightIcon;
+  const ariaLabel = isLeft ? 'Anterior' : 'Siguiente';
+
+  return (
+    <IconButton
+      aria-label={ariaLabel}
+      size="small"
+      onClick={onClick}
+      disabled={!enabled}
+      sx={{
+        flex: '0 0 auto',
+        // Reservamos el slot siempre que haya overflow en algún lado,
+        // así el área scroll tiene un ancho estable (no saltan los
+        // steps cuando aparece/desaparece la flecha).
+        visibility: visible ? 'visible' : 'hidden',
+      }}
+    >
+      <Icon fontSize="small" />
+    </IconButton>
+  );
+};

package/src/components/Stepper/index.ts

@@ -0,0 +1,15 @@
+export { Stepper, default } from './Stepper';
+export type { StepperProps } from './Stepper';
+
+export { Step } from './Step';
+export type { StepProps } from './Step';
+
+export {
+  StepperProvider,
+  StepperContext,
+  useStepper,
+} from './StepperContext';
+export type {
+  StepperContextValue,
+  StepperProviderProps,
+} from './StepperContext';

package/src/components/Switch/Switch.definitions.ts

@@ -0,0 +1,134 @@
+// Switch.definitions.ts — código fuente para la pestaña Docs de Storybook.
+
+export const BasicSwitchDefinition = `
+import React, { useState } from 'react';
+import { Switch } from './Switch';
+import { Box, Typography } from '@mui/material';
+
+export const BasicSwitchExample = () => {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Box sx={{ width: 280 }}>
+      <Switch checked={checked} onChange={setChecked} />
+      <Typography sx={{ mt: 2 }}>Estado: {checked ? 'ON' : 'OFF'}</Typography>
+    </Box>
+  );
+};
+`;
+
+export const SwitchWithLabelDefinition = `
+import React, { useState } from 'react';
+import { Switch } from './Switch';
+import { Box } from '@mui/material';
+
+export const SwitchWithLabelExample = () => {
+  const [checked, setChecked] = useState(true);
+  return (
+    <Box sx={{ width: 280 }}>
+      <Switch
+        label="Notificaciones por email"
+        checked={checked}
+        onChange={setChecked}
+      />
+    </Box>
+  );
+};
+`;
+
+export const BorderedSwitchDefinition = `
+import React, { useState } from 'react';
+import { Switch } from './Switch';
+import { Box } from '@mui/material';
+
+export const BorderedSwitchExample = () => {
+  const [checked, setChecked] = useState(true);
+  return (
+    <Box sx={{ width: 360 }}>
+      <Switch
+        label="Recibir reportes diarios"
+        checked={checked}
+        onChange={setChecked}
+        bordered
+      />
+    </Box>
+  );
+};
+`;
+
+export const SwitchSizesDefinition = `
+import React, { useState } from 'react';
+import { Switch } from './Switch';
+import { Box } from '@mui/material';
+
+export const SwitchSizesExample = () => {
+  const [a, setA] = useState(false);
+  const [b, setB] = useState(true);
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, width: 280 }}>
+      <Switch label="Pequeño" size="small" checked={a} onChange={setA} />
+      <Switch label="Mediano (default)" size="medium" checked={b} onChange={setB} />
+    </Box>
+  );
+};
+`;
+
+export const SwitchWithErrorDefinition = `
+import React, { useState } from 'react';
+import { Switch } from './Switch';
+import { Box } from '@mui/material';
+
+export const SwitchWithErrorExample = () => {
+  const [checked, setChecked] = useState(false);
+  const hasError = !checked;
+  return (
+    <Box sx={{ width: 320 }}>
+      <Switch
+        label="Aceptar términos y condiciones"
+        checked={checked}
+        onChange={setChecked}
+        error={hasError}
+        helperText={hasError ? 'Debes aceptar los términos para continuar' : ''}
+      />
+    </Box>
+  );
+};
+`;
+
+export const DisabledSwitchDefinition = `
+import React from 'react';
+import { Switch } from './Switch';
+import { Box } from '@mui/material';
+
+export const DisabledSwitchExample = () => (
+  <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, width: 280 }}>
+    <Switch label="Off bloqueado" checked={false} onChange={() => {}} disabled />
+    <Switch label="On bloqueado" checked={true} onChange={() => {}} disabled />
+  </Box>
+);
+`;
+
+export const RHFSwitchDefinition = `
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { Switch } from './Switch';
+import { Box, Button, Typography } from '@mui/material';
+
+export const RHFSwitchExample = () => {
+  const { control, handleSubmit, watch } = useForm({
+    defaultValues: { darkMode: false },
+  });
+  const value = watch('darkMode');
+  return (
+    <Box sx={{ width: 320 }} component="form" onSubmit={handleSubmit(console.log)}>
+      <Switch
+        label="Modo oscuro"
+        name="darkMode"
+        control={control}
+        bordered
+      />
+      <Typography sx={{ mt: 2 }}>Valor en el form: {String(value)}</Typography>
+      <Button type="submit" sx={{ mt: 1 }}>Enviar</Button>
+    </Box>
+  );
+};
+`;

package/src/components/Switch/Switch.stories.tsx

@@ -0,0 +1,213 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React, { useState } from 'react';
+import { Box, Button, Typography } from '@mui/material';
+import { useForm } from 'react-hook-form';
+
+import { Switch } from './Switch';
+import {
+  BasicSwitchDefinition,
+  SwitchWithLabelDefinition,
+  BorderedSwitchDefinition,
+  SwitchSizesDefinition,
+  SwitchWithErrorDefinition,
+  DisabledSwitchDefinition,
+  RHFSwitchDefinition,
+} from './Switch.definitions';
+
+// =============================================================================
+// Meta
+// =============================================================================
+const meta: Meta<typeof Switch> = {
+  title: 'Components/Switch',
+  component: Switch,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Un toggle/switch basado en MUI `Switch`. Soporta modo controlado (`checked` + `onChange`) ' +
+          'y modo react-hook-form (`name` + `control`). Mantiene compatibilidad visual con el legacy ' +
+          '`FormToggleInput` mediante la prop `bordered` (label a la izquierda, switch a la derecha).',
+      },
+    },
+  },
+  argTypes: {
+    label: { control: 'text', description: 'Texto al lado del switch. Si está ausente, se renderiza solo el switch.' },
+    labelPlacement: {
+      control: 'radio',
+      options: ['start', 'end', 'top', 'bottom'],
+      description: 'Posición del label respecto al switch. Default: `end`.',
+    },
+    size: { control: 'radio', options: ['small', 'medium'], description: 'Tamaño del switch. Default: `medium`.' },
+    bordered: { control: 'boolean', description: 'Renderizar contenedor con borde estilo "form field". Default: false.' },
+    borderRadius: { control: { type: 'number' }, description: 'Border radius del contenedor cuando `bordered`. Default: 10.' },
+    disabled: { control: 'boolean', description: 'Deshabilitar el switch.' },
+    error: { control: 'boolean', description: 'Estado de error visual.' },
+    helperText: { control: 'text', description: 'Texto auxiliar debajo del switch.' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Switch>;
+
+// =============================================================================
+// Stories
+// =============================================================================
+
+export const BasicSwitch: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return (
+      <Box sx={{ width: 280 }}>
+        <Switch checked={checked} onChange={setChecked} />
+        <Typography sx={{ mt: 2 }}>Estado: {checked ? 'ON' : 'OFF'}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Uso mínimo, sin label. Equivalente al legacy `ToggleInputReport`.' },
+      source: { code: BasicSwitchDefinition.trim() },
+    },
+  },
+};
+
+export const SwitchWithLabel: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return (
+      <Box sx={{ width: 280 }}>
+        <Switch
+          label="Notificaciones por email"
+          checked={checked}
+          onChange={setChecked}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Switch con label a la derecha (default `labelPlacement="end"`).' },
+      source: { code: SwitchWithLabelDefinition.trim() },
+    },
+  },
+};
+
+export const BorderedSwitch: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return (
+      <Box sx={{ width: 360 }}>
+        <Switch
+          label="Recibir reportes diarios"
+          checked={checked}
+          onChange={setChecked}
+          bordered
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Variante con `bordered`: contenedor con borde, label a la izquierda y switch al borde opuesto. ' +
+          'Replica el estilo del legacy `FormToggleInput`.',
+      },
+      source: { code: BorderedSwitchDefinition.trim() },
+    },
+  },
+};
+
+export const SwitchSizes: Story = {
+  render: () => {
+    const [a, setA] = useState(false);
+    const [b, setB] = useState(true);
+    return (
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, width: 280 }}>
+        <Switch label="Pequeño" size="small" checked={a} onChange={setA} />
+        <Switch label="Mediano (default)" size="medium" checked={b} onChange={setB} />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Tamaños disponibles: `small` y `medium` (default).' },
+      source: { code: SwitchSizesDefinition.trim() },
+    },
+  },
+};
+
+export const SwitchWithError: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    const hasError = !checked;
+    return (
+      <Box sx={{ width: 320 }}>
+        <Switch
+          label="Aceptar términos y condiciones"
+          checked={checked}
+          onChange={setChecked}
+          error={hasError}
+          helperText={hasError ? 'Debes aceptar los términos para continuar' : ''}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Estado de error con `error` + `helperText`.' },
+      source: { code: SwitchWithErrorDefinition.trim() },
+    },
+  },
+};
+
+export const DisabledSwitch: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, width: 280 }}>
+      <Switch label="Off bloqueado" checked={false} onChange={() => {}} disabled />
+      <Switch label="On bloqueado" checked={true} onChange={() => {}} disabled />
+    </Box>
+  ),
+  parameters: {
+    docs: {
+      description: { story: 'Switch deshabilitado en ambos estados.' },
+      source: { code: DisabledSwitchDefinition.trim() },
+    },
+  },
+};
+
+export const RHFSwitch: Story = {
+  render: () => {
+    const { control, handleSubmit, watch } = useForm({
+      defaultValues: { darkMode: false },
+    });
+    const value = watch('darkMode');
+    return (
+      <Box
+        sx={{ width: 320 }}
+        component="form"
+        onSubmit={handleSubmit((data) => console.log(data))}
+      >
+        <Switch
+          label="Modo oscuro"
+          name="darkMode"
+          control={control}
+          bordered
+        />
+        <Typography sx={{ mt: 2 }}>Valor en el form: {String(value)}</Typography>
+        <Button type="submit" sx={{ mt: 1 }}>Enviar</Button>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Modo react-hook-form con `name` + `control`. El valor `true`/`false` viaja directo al form state.',
+      },
+      source: { code: RHFSwitchDefinition.trim() },
+    },
+  },
+};

package/src/components/Switch/Switch.sx.ts

@@ -0,0 +1,81 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface BuildSwitchSxOptions {
+  bordered: boolean;
+  borderRadius: number | string;
+  hasLabel: boolean;
+  error: boolean;
+}
+
+const toRadius = (borderRadius: number | string) =>
+  typeof borderRadius === 'number' ? `${borderRadius}px` : borderRadius;
+
+/**
+ * Transición compartida (matchea el InputGroup y el RadioGroup).
+ */
+const FOCUS_TRANSITION =
+  'border-color 200ms cubic-bezier(0.0, 0, 0.2, 1) 0ms, ' +
+  'box-shadow 200ms cubic-bezier(0.0, 0, 0.2, 1) 0ms';
+
+/**
+ * Builder de sx para Switch. Reproduce el estilo del antiguo
+ * `FormToggleInput` legacy cuando `bordered=true`: contenedor con borde,
+ * label a la izquierda y switch a la derecha (vía justify-content: space-between).
+ *
+ * Cuando `bordered=true`, el contenedor gana:
+ * - `:focus-within` → borde + shadow primario (mismo patrón que `InputGroup`).
+ * - `error=true` → borde + shadow de error (palette.error.main).
+ *
+ * El shadow es de 1px, así que no hay shift de layout — sólo se intensifica
+ * visualmente el borde sin empujar nada alrededor.
+ *
+ * Si `bordered=false`, sólo aplica un reset de margin del helper text.
+ */
+export const buildSwitchSx = ({
+  bordered,
+  borderRadius,
+  hasLabel,
+  error,
+}: BuildSwitchSxOptions): SxProps<Theme> => {
+  const radius = toRadius(borderRadius);
+
+  if (!bordered) {
+    return {
+      '& .MuiFormHelperText-root': { marginLeft: 0 },
+    };
+  }
+
+  return (theme) => ({
+    '& .MuiFormControlLabel-root': {
+      marginLeft: 0,
+      marginRight: 0,
+      paddingX: 1.5,
+      paddingY: 1.25,
+      border: `1px solid ${
+        error ? theme.palette.error.main : theme.palette.divider
+      }`,
+      borderRadius: radius,
+      transition: FOCUS_TRANSITION,
+      ...(error && {
+        boxShadow: `0 0 0 1px ${theme.palette.error.main}`,
+      }),
+      // Focus del usuario sobre el switch interno.
+      '&:focus-within': {
+        borderColor: error
+          ? theme.palette.error.main
+          : theme.palette.primary.main,
+        boxShadow: `0 0 0 1px ${
+          error ? theme.palette.error.main : theme.palette.primary.main
+        }`,
+      },
+      // Si hay label, separar el switch al borde opuesto.
+      ...(hasLabel && {
+        width: '100%',
+        justifyContent: 'space-between',
+      }),
+    },
+    '& .MuiFormHelperText-root': {
+      marginLeft: 0,
+    },
+  });
+};

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,188 @@
+import { useTheme } from '@mui/material/styles';
+import {
+  FormControl,
+  FormControlLabel,
+  FormHelperText,
+  Switch as MuiSwitch,
+  type SwitchProps as MuiSwitchProps,
+  type SxProps,
+  type Theme,
+} from '@mui/material';
+import { Controller, type Control, type RegisterOptions } from 'react-hook-form';
+
+import { buildSwitchSx } from './Switch.sx';
+import { resolvePreset } from '../_shared/resolvePreset';
+
+// ── Tipos de dominio ─────────────────────────────────────────────────────
+export type SwitchSize = 'small' | 'medium';
+export type SwitchLabelPlacement = 'start' | 'end' | 'top' | 'bottom';
+
+// ── Props base (todo lo común entre RHF y controlado) ────────────────────
+export interface BaseSwitchProps
+  extends Omit<MuiSwitchProps, 'value' | 'onChange' | 'checked' | 'defaultChecked' | 'size'> {
+  /** Texto al lado del switch. Si está ausente, no se renderiza FormControlLabel. */
+  label?: string;
+  size?: SwitchSize;
+  /** Posición del label. Default: 'end' (legacy `FormToggleInput` lo ponía a la izquierda con su flex-stack). */
+  labelPlacement?: SwitchLabelPlacement;
+  disabled?: boolean;
+  error?: boolean;
+  helperText?: string;
+  /** Renderiza un contenedor con borde alrededor del switch + label. Default: false. */
+  bordered?: boolean;
+  /** Border radius del contenedor (cuando bordered). Default: 10. */
+  borderRadius?: number | string;
+  defaultChecked?: boolean;
+  /**
+   * Nombre del preset de estilo registrado en `theme.styles.Switch`.
+   * - `"default"` (o ausente) = estilo built-in del paquete.
+   * - Cualquier otro string = mergea el preset encima del estilo built-in.
+   */
+  preset?: string;
+  sx?: SxProps<Theme>;
+}
+
+// ── Variantes discriminadas (RHF vs controlado) ──────────────────────────
+export interface RHFSwitchProps extends BaseSwitchProps {
+  name: string;
+  // `any` plano (no `Control<any>`): RHF tipa `Control<T>` con generics en
+  // posiciones tanto contravariantes como covariantes (ej. `_subjects.state`).
+  // Cuando el componente o su uso involucra generics adicionales, TS se
+  // confunde narroweando el discriminated union y `Control<any>` no logra
+  // absorber `Control<MyForm>` en la comparación estructural profunda. El
+  // `any` plano elimina ese ruido. RHF adentro sigue teniendo sus tipos
+  // fuertes — solo degradamos la superficie del prop del componente.
+  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?: (checked: boolean) => void;
+  checked?: never;
+  onChange?: never;
+}
+
+export interface ControlledSwitchProps extends BaseSwitchProps {
+  name?: string;
+  control?: never;
+  validation?: never;
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+}
+
+// ── API pública final ────────────────────────────────────────────────────
+export type SwitchProps = RHFSwitchProps | ControlledSwitchProps;
+
+export const Switch: React.FC<SwitchProps> = (props) => {
+  const {
+    label,
+    size = 'medium',
+    labelPlacement = 'end',
+    disabled = false,
+    error = false,
+    helperText,
+    bordered = false,
+    borderRadius = 10,
+    defaultChecked,
+    preset,
+    sx,
+    ...rest
+  } = props as ControlledSwitchProps & {
+    control?: Control<any>;
+    validation?: RegisterOptions;
+  };
+
+  const theme = useTheme();
+  const presetSx = resolvePreset('Switch', preset, theme);
+
+  // Construye el sx con el estado de error efectivo; se llama por rama
+  // (RHF usa el error del Controller, controlado usa el prop `error`).
+  const buildSx = (effectiveError: boolean) => [
+    buildSwitchSx({
+      bordered,
+      borderRadius,
+      hasLabel: !!label,
+      error: effectiveError,
+    }),
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : [sx]),
+  ];
+
+  const renderSwitch = (
+    checked: boolean,
+    onChange: (next: boolean) => void,
+    onBlur?: () => void,
+    inputRef?: React.Ref<HTMLInputElement>,
+  ) => {
+    const switchEl = (
+      <MuiSwitch
+        {...rest}
+        size={size}
+        checked={!!checked}
+        onChange={(_e, next) => onChange(next)}
+        onBlur={onBlur}
+        // @ts-ignore — Ref<HTMLInputElement> type mismatch between @types/react versions in monorepo
+        inputRef={inputRef}
+        disabled={disabled}
+      />
+    );
+
+    return label ? (
+      <FormControlLabel
+        control={switchEl}
+        label={label}
+        labelPlacement={labelPlacement}
+        disabled={disabled}
+      />
+    ) : (
+      switchEl
+    );
+  };
+
+  // ── RHF mode ──────────────────────────────────────────────────────────
+  if ('control' in props && props.control) {
+    const { name, control, validation, onValueChange } = props as RHFSwitchProps;
+    return (
+      <Controller
+        name={name}
+        control={control}
+        rules={validation}
+        defaultValue={defaultChecked}
+        render={({ field, fieldState: { error: fieldError } }) => {
+          const finalError = !!fieldError || error;
+          const finalHelperText = fieldError?.message ?? helperText;
+          return (
+            <FormControl
+              error={finalError}
+              disabled={disabled}
+              sx={buildSx(finalError)}
+            >
+              {renderSwitch(
+                !!field.value,
+                (next) => {
+                  field.onChange(next);
+                  onValueChange?.(next);
+                },
+                field.onBlur,
+                field.ref,
+              )}
+              {finalHelperText && <FormHelperText>{finalHelperText}</FormHelperText>}
+            </FormControl>
+          );
+        }}
+      />
+    );
+  }
+
+  // ── Controlled mode ───────────────────────────────────────────────────
+  const { checked, onChange } = props as ControlledSwitchProps;
+  return (
+    <FormControl error={error} disabled={disabled} sx={buildSx(error)}>
+      {renderSwitch(checked, onChange)}
+      {helperText && <FormHelperText>{helperText}</FormHelperText>}
+    </FormControl>
+  );
+};
+
+export default Switch;

package/src/components/Switch/Switch.types.ts

@@ -0,0 +1,10 @@
+// Re-export barrel para compatibilidad con imports antiguos.
+// Los tipos viven dentro de Switch.tsx.
+export type {
+  SwitchSize,
+  SwitchLabelPlacement,
+  BaseSwitchProps,
+  RHFSwitchProps,
+  ControlledSwitchProps,
+  SwitchProps,
+} from './Switch';