@soyfri/shared-library 2.0.0-beta.16 → 2.0.0-beta.18

package/src/components/RadioGroup/RadioGroup.definitions.ts

@@ -0,0 +1,177 @@
+// RadioGroup.definitions.ts — código fuente para la pestaña Docs de Storybook.
+
+export const BasicRadioGroupDefinition = `
+import React, { useState } from 'react';
+import { RadioGroup } from './RadioGroup';
+import { Box, Typography } from '@mui/material';
+
+const options = [
+  { value: 'a', label: 'Opción A' },
+  { value: 'b', label: 'Opción B' },
+  { value: 'c', label: 'Opción C' },
+];
+
+export const BasicRadioGroupExample = () => {
+  const [value, setValue] = useState('a');
+  return (
+    <Box sx={{ width: 360 }}>
+      <RadioGroup
+        label="Selecciona una opción"
+        options={options}
+        value={value}
+        onChange={setValue}
+      />
+      <Typography sx={{ mt: 2 }}>Valor actual: {value}</Typography>
+    </Box>
+  );
+};
+`;
+
+export const ColumnRadioGroupDefinition = `
+import React, { useState } from 'react';
+import { RadioGroup } from './RadioGroup';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: 'sm', label: 'Pequeño' },
+  { value: 'md', label: 'Mediano' },
+  { value: 'lg', label: 'Grande' },
+];
+
+export const ColumnRadioGroupExample = () => {
+  const [value, setValue] = useState('md');
+  return (
+    <Box sx={{ width: 360 }}>
+      <RadioGroup
+        label="Tamaño"
+        options={options}
+        value={value}
+        onChange={setValue}
+        row={false}
+      />
+    </Box>
+  );
+};
+`;
+
+export const RadioGroupWithErrorDefinition = `
+import React, { useState } from 'react';
+import { RadioGroup } from './RadioGroup';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: 'yes', label: 'Sí' },
+  { value: 'no', label: 'No' },
+];
+
+export const RadioGroupWithErrorExample = () => {
+  const [value, setValue] = useState('');
+  const hasError = !value;
+  return (
+    <Box sx={{ width: 360 }}>
+      <RadioGroup
+        label="¿Aceptas los términos?"
+        options={options}
+        value={value}
+        onChange={setValue}
+        error={hasError}
+        helperText={hasError ? 'Este campo es obligatorio' : ''}
+      />
+    </Box>
+  );
+};
+`;
+
+export const DisabledRadioGroupDefinition = `
+import React, { useState } from 'react';
+import { RadioGroup } from './RadioGroup';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: 'a', label: 'Opción A' },
+  { value: 'b', label: 'Opción B', disabled: true },
+  { value: 'c', label: 'Opción C' },
+];
+
+export const DisabledRadioGroupExample = () => {
+  const [value, setValue] = useState('a');
+  return (
+    <Box sx={{ width: 360 }}>
+      {/* Bloqueo total */}
+      <RadioGroup
+        label="Grupo deshabilitado"
+        options={options}
+        value={value}
+        onChange={setValue}
+        disabled
+      />
+      {/* Bloqueo por opción */}
+      <RadioGroup
+        label="Opción B deshabilitada"
+        options={options}
+        value={value}
+        onChange={setValue}
+        sx={{ mt: 3 }}
+      />
+    </Box>
+  );
+};
+`;
+
+export const UnborderedRadioGroupDefinition = `
+import React, { useState } from 'react';
+import { RadioGroup } from './RadioGroup';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: 'a', label: 'Opción A' },
+  { value: 'b', label: 'Opción B' },
+];
+
+export const UnborderedRadioGroupExample = () => {
+  const [value, setValue] = useState('a');
+  return (
+    <Box sx={{ width: 360 }}>
+      <RadioGroup
+        options={options}
+        value={value}
+        onChange={setValue}
+        bordered={false}
+      />
+    </Box>
+  );
+};
+`;
+
+export const RHFRadioGroupDefinition = `
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { RadioGroup } from './RadioGroup';
+import { Box, Button, Typography } from '@mui/material';
+
+const options = [
+  { value: 'paypal', label: 'PayPal' },
+  { value: 'card', label: 'Tarjeta' },
+  { value: 'transfer', label: 'Transferencia' },
+];
+
+export const RHFRadioGroupExample = () => {
+  const { control, handleSubmit, watch } = useForm({
+    defaultValues: { paymentMethod: 'card' },
+  });
+  const value = watch('paymentMethod');
+  return (
+    <Box sx={{ width: 360 }} component="form" onSubmit={handleSubmit(console.log)}>
+      <RadioGroup
+        label="Método de pago"
+        options={options}
+        name="paymentMethod"
+        control={control}
+        validation={{ required: 'Selecciona un método' }}
+      />
+      <Typography sx={{ mt: 2 }}>Valor en el form: {value}</Typography>
+      <Button type="submit" sx={{ mt: 1 }}>Enviar</Button>
+    </Box>
+  );
+};
+`;

package/src/components/RadioGroup/RadioGroup.stories.tsx

@@ -0,0 +1,231 @@
+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 { RadioGroup } from './RadioGroup';
+import {
+  BasicRadioGroupDefinition,
+  ColumnRadioGroupDefinition,
+  RadioGroupWithErrorDefinition,
+  DisabledRadioGroupDefinition,
+  UnborderedRadioGroupDefinition,
+  RHFRadioGroupDefinition,
+} from './RadioGroup.definitions';
+
+// =============================================================================
+// Meta
+// =============================================================================
+const meta: Meta<typeof RadioGroup> = {
+  title: 'Components/RadioGroup',
+  component: RadioGroup,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Un grupo de radio buttons basado en MUI `RadioGroup` + `Radio` + `FormControlLabel`. ' +
+          'Soporta modo controlado (`value` + `onChange`) y modo react-hook-form (`name` + `control`). ' +
+          'Mantiene compatibilidad visual con el legacy `FormRadioGroup` mediante la prop `bordered` (default: true).',
+      },
+    },
+  },
+  argTypes: {
+    label: { control: 'text', description: 'Label superior del grupo.' },
+    options: { control: 'object', description: 'Lista de opciones `{ value, label, disabled?, id? }`.' },
+    row: { control: 'boolean', description: 'Distribuir radios horizontalmente. Default: true.' },
+    size: { control: 'radio', options: ['small', 'medium'], description: 'Tamaño del radio.' },
+    bordered: { control: 'boolean', description: 'Renderizar contenedor con borde estilo "form field". Default: true.' },
+    borderRadius: { control: { type: 'number' }, description: 'Border radius del contenedor cuando `bordered`. Default: 10.' },
+    disabled: { control: 'boolean', description: 'Deshabilitar el grupo entero.' },
+    error: { control: 'boolean', description: 'Estado de error visual.' },
+    helperText: { control: 'text', description: 'Texto auxiliar debajo del grupo.' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof RadioGroup>;
+
+// =============================================================================
+// Stories
+// =============================================================================
+
+const baseOptions = [
+  { value: 'a', label: 'Opción A' },
+  { value: 'b', label: 'Opción B' },
+  { value: 'c', label: 'Opción C' },
+];
+
+export const BasicRadioGroup: Story = {
+  render: () => {
+    const [value, setValue] = useState('a');
+    return (
+      <Box sx={{ width: 360 }}>
+        <RadioGroup
+          label="Selecciona una opción"
+          options={baseOptions}
+          value={value}
+          onChange={setValue}
+        />
+        <Typography sx={{ mt: 2 }}>Valor actual: {value}</Typography>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Uso básico controlado: `value` + `onChange`. Distribución horizontal por defecto.' },
+      source: { code: BasicRadioGroupDefinition.trim() },
+    },
+  },
+};
+
+export const ColumnRadioGroup: Story = {
+  render: () => {
+    const [value, setValue] = useState('md');
+    return (
+      <Box sx={{ width: 360 }}>
+        <RadioGroup
+          label="Tamaño"
+          options={[
+            { value: 'sm', label: 'Pequeño' },
+            { value: 'md', label: 'Mediano' },
+            { value: 'lg', label: 'Grande' },
+          ]}
+          value={value}
+          onChange={setValue}
+          row={false}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Distribución vertical con `row={false}`.' },
+      source: { code: ColumnRadioGroupDefinition.trim() },
+    },
+  },
+};
+
+export const RadioGroupWithError: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    const hasError = !value;
+    return (
+      <Box sx={{ width: 360 }}>
+        <RadioGroup
+          label="¿Aceptas los términos?"
+          options={[
+            { value: 'yes', label: 'Sí' },
+            { value: 'no', label: 'No' },
+          ]}
+          value={value}
+          onChange={setValue}
+          error={hasError}
+          helperText={hasError ? 'Este campo es obligatorio' : ''}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Estado de error con `error` + `helperText`. Equivalente a `errorRequired` + `messageError` del legacy.' },
+      source: { code: RadioGroupWithErrorDefinition.trim() },
+    },
+  },
+};
+
+export const DisabledRadioGroup: Story = {
+  render: () => {
+    const [value, setValue] = useState('a');
+    const opts = [
+      { value: 'a', label: 'Opción A' },
+      { value: 'b', label: 'Opción B', disabled: true },
+      { value: 'c', label: 'Opción C' },
+    ];
+    return (
+      <Box sx={{ width: 360, display: 'flex', flexDirection: 'column', gap: 3 }}>
+        <RadioGroup
+          label="Grupo deshabilitado"
+          options={opts}
+          value={value}
+          onChange={setValue}
+          disabled
+        />
+        <RadioGroup
+          label="Opción B deshabilitada"
+          options={opts}
+          value={value}
+          onChange={setValue}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Bloqueo total con `disabled`, o por opción individual con `option.disabled`.' },
+      source: { code: DisabledRadioGroupDefinition.trim() },
+    },
+  },
+};
+
+export const UnborderedRadioGroup: Story = {
+  render: () => {
+    const [value, setValue] = useState('a');
+    return (
+      <Box sx={{ width: 360 }}>
+        <RadioGroup
+          options={baseOptions}
+          value={value}
+          onChange={setValue}
+          bordered={false}
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Sin contenedor con borde — útil para agrupar inline con otros controles.' },
+      source: { code: UnborderedRadioGroupDefinition.trim() },
+    },
+  },
+};
+
+export const RHFRadioGroup: Story = {
+  render: () => {
+    const { control, handleSubmit, watch } = useForm({
+      defaultValues: { paymentMethod: 'card' },
+    });
+    const value = watch('paymentMethod');
+    return (
+      <Box
+        sx={{ width: 360 }}
+        component="form"
+        onSubmit={handleSubmit((data) => console.log(data))}
+      >
+        <RadioGroup
+          label="Método de pago"
+          options={[
+            { value: 'paypal', label: 'PayPal' },
+            { value: 'card', label: 'Tarjeta' },
+            { value: 'transfer', label: 'Transferencia' },
+          ]}
+          name="paymentMethod"
+          control={control}
+          validation={{ required: 'Selecciona un método' }}
+        />
+        <Typography sx={{ mt: 2 }}>Valor en el form: {value}</Typography>
+        <Button type="submit" sx={{ mt: 1 }}>Enviar</Button>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Modo react-hook-form con `name` + `control`. El error y `helperText` se conectan automáticamente vía el `Controller`.',
+      },
+      source: { code: RHFRadioGroupDefinition.trim() },
+    },
+  },
+};

package/src/components/RadioGroup/RadioGroup.sx.ts

@@ -0,0 +1,75 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface BuildRadioGroupSxOptions {
+  bordered: boolean;
+  borderRadius: number | string;
+  error: boolean;
+}
+
+const toRadius = (borderRadius: number | string) =>
+  typeof borderRadius === 'number' ? `${borderRadius}px` : borderRadius;
+
+/**
+ * Transición compartida (matchea el InputGroup).
+ */
+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 RadioGroup. Reproduce el estilo del antiguo
+ * `FormRadioGroup` legacy: contenedor con borde + padding vertical.
+ *
+ * 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`, devuelve un sx mínimo (sólo helper text reset).
+ */
+export const buildRadioGroupSx = ({
+  bordered,
+  borderRadius,
+  error,
+}: BuildRadioGroupSxOptions): SxProps<Theme> => {
+  const radius = toRadius(borderRadius);
+
+  if (!bordered) {
+    return {
+      '& .MuiFormHelperText-root': { marginLeft: 0 },
+    };
+  }
+
+  return (theme) => ({
+    '& .MuiRadioGroup-root': {
+      paddingTop: 1.25,
+      paddingBottom: 1.25,
+      paddingX: 1.5,
+      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 cualquier radio 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
+        }`,
+      },
+    },
+    '& .MuiFormHelperText-root': {
+      marginLeft: 0,
+    },
+    '& .MuiFormLabel-root': {
+      marginBottom: 0.5,
+    },
+  });
+};

package/src/components/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,207 @@
+import type { FC } from 'react';
+import { useTheme } from '@mui/material/styles';
+import {
+  FormControl,
+  FormControlLabel,
+  FormHelperText,
+  FormLabel,
+  Radio,
+  RadioGroup as MuiRadioGroup,
+  type RadioGroupProps as MuiRadioGroupProps,
+  type SxProps,
+  type Theme,
+} from '@mui/material';
+import { Controller, type Control, type RegisterOptions } from 'react-hook-form';
+
+import { buildRadioGroupSx } from './RadioGroup.sx';
+import { resolvePreset } from '../_shared/resolvePreset';
+
+// ── Tipos de dominio ─────────────────────────────────────────────────────
+export interface RadioOption {
+  /** Valor que se emite cuando se selecciona la opción. */
+  value: string;
+  /** Texto mostrado al lado del radio. */
+  label: string;
+  /** Deshabilitar opción individualmente. */
+  disabled?: boolean;
+  /** ID custom del input (default: prefijo + value). */
+  id?: string;
+}
+
+export type RadioGroupSize = 'small' | 'medium';
+
+// ── Props base (todo lo común entre RHF y controlado) ────────────────────
+export interface BaseRadioGroupProps
+  extends Omit<MuiRadioGroupProps, 'value' | 'onChange' | 'defaultValue'> {
+  options: RadioOption[];
+  /** Label superior del grupo. */
+  label?: string;
+  /** Distribución horizontal (default: true — replica el comportamiento legacy). */
+  row?: boolean;
+  size?: RadioGroupSize;
+  disabled?: boolean;
+  error?: boolean;
+  helperText?: string;
+  /** Renderiza un contenedor con borde estilo "form field". Default: true. */
+  bordered?: boolean;
+  /** Border radius del contenedor (cuando bordered). Default: 10. */
+  borderRadius?: number | string;
+  defaultValue?: string;
+  /**
+   * Nombre del preset de estilo registrado en `theme.styles.RadioGroup`.
+   * - `"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 RHFRadioGroupProps extends BaseRadioGroupProps {
+  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?: (value: string) => void;
+  value?: never;
+  onChange?: never;
+}
+
+export interface ControlledRadioGroupProps extends BaseRadioGroupProps {
+  name?: string;
+  control?: never;
+  validation?: never;
+  value: string;
+  onChange: (value: string) => void;
+}
+
+// ── API pública final ────────────────────────────────────────────────────
+export type RadioGroupProps = RHFRadioGroupProps | ControlledRadioGroupProps;
+
+export const RadioGroup: FC<RadioGroupProps> = (props) => {
+  const {
+    options,
+    label,
+    row = true,
+    size = 'small',
+    disabled = false,
+    error = false,
+    helperText,
+    bordered = true,
+    borderRadius = 10,
+    defaultValue,
+    preset,
+    sx,
+    ...rest
+  } = props as ControlledRadioGroupProps & {
+    control?: Control<any>;
+    validation?: RegisterOptions;
+  };
+
+  const theme = useTheme();
+  const presetSx = resolvePreset('RadioGroup', 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) => [
+    buildRadioGroupSx({ bordered, borderRadius, error: effectiveError }),
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  const renderOptions = (fieldName?: string) =>
+    options.map((opt) => {
+      const inputId = opt.id ?? `${fieldName ?? 'radio'}-${opt.value}`;
+      return (
+        <FormControlLabel
+          key={inputId}
+          value={opt.value}
+          control={
+            <Radio
+              id={inputId}
+              size={size}
+              disabled={disabled || opt.disabled}
+            />
+          }
+          label={opt.label}
+          disabled={disabled || opt.disabled}
+        />
+      );
+    });
+
+  // ── RHF mode ──────────────────────────────────────────────────────────
+  if ('control' in props && props.control) {
+    const { name, control, validation, onValueChange } = props as RHFRadioGroupProps;
+    return (
+      <Controller
+        name={name}
+        control={control}
+        rules={validation}
+        defaultValue={defaultValue}
+        render={({ field, fieldState: { error: fieldError } }) => {
+          const finalError = !!fieldError || error;
+          const finalHelperText = fieldError?.message ?? helperText;
+          return (
+            <FormControl
+              error={finalError}
+              disabled={disabled}
+              sx={buildSx(finalError)}
+              fullWidth
+            >
+              {label && <FormLabel>{label}</FormLabel>}
+              <MuiRadioGroup
+                {...rest}
+                row={row}
+                name={field.name}
+                value={field.value ?? ''}
+                onBlur={field.onBlur}
+                onChange={(_e, value) => {
+                  field.onChange(value);
+                  onValueChange?.(value);
+                }}
+              >
+                {renderOptions(field.name)}
+              </MuiRadioGroup>
+              {finalHelperText && <FormHelperText>{finalHelperText}</FormHelperText>}
+            </FormControl>
+          );
+        }}
+      />
+    );
+  }
+
+  // ── Controlled mode ───────────────────────────────────────────────────
+  const { value, onChange, name } = props as ControlledRadioGroupProps;
+  return (
+    <FormControl
+      error={error}
+      disabled={disabled}
+      sx={buildSx(error)}
+      fullWidth
+    >
+      {label && <FormLabel>{label}</FormLabel>}
+      <MuiRadioGroup
+        {...rest}
+        row={row}
+        name={name}
+        value={value ?? ''}
+        onChange={(_e, next) => onChange(next)}
+      >
+        {renderOptions(name)}
+      </MuiRadioGroup>
+      {helperText && <FormHelperText>{helperText}</FormHelperText>}
+    </FormControl>
+  );
+};
+
+export default RadioGroup;

package/src/components/RadioGroup/index.ts

@@ -0,0 +1,10 @@
+export { RadioGroup, default } from './RadioGroup';
+export type {
+  RadioOption,
+  RadioGroupSize,
+  BaseRadioGroupProps,
+  RHFRadioGroupProps,
+  ControlledRadioGroupProps,
+  RadioGroupProps,
+} from './RadioGroup';
+