dubalu-address-form

Dubalu Address Form Library

Requisitos

• tailwindcss
• flowbite
• flowbite-react
• react-hook-form

Importante

Para usar, importa los estilos globales en tu aplicación:

import 'dubalu-address-form/dist/index.css';

Instalación

npm install dubalu-address-form

Ejecutar localmente

Clonar:

git clone https://github.com/Dubalu-Development-Team/dubalu-address-form.git

Ir al proyecto:

cd dubalu-address-form

Instalar dependencias:

npm install

Iniciar el servidor:

npm run dev

Correr tests:

npm run test

Props

| Prop | Type | Default | Descripción | | ------------------------- | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | initialValues | object | — | Valores iniciales para el formulario. Requiere id para mostrar textos de actualización. | | onSubmit | function | — | Función que se ejecuta al enviar el formulario. | | getPostalCodeAddresses | function | — | Función para obtener direcciones desde un código postal. | | setPostalData | function | — | Setter del estado de resultados de código postal. | | defaultCountryCode | CountryCode | 'MX' | País por defecto para el formulario de domicilios. | | postalCodeAddresses | IPostalCodeState | — | Objeto con resultados de búsqueda: { results: [], matchesEstimated: 0, loading: boolean }. | | postalCodeSearch | boolean | true | Habilita la búsqueda por código postal con autocompletado. | | postalCodeField | React.ComponentType<PostalCodeFieldBaseProps>| — | Componente personalizado para el campo de código postal. | | hideName | boolean | false | Oculta el campo de nombre. | | hideTitle | boolean | false | Oculta el título del formulario. | | hideContact | boolean | false | Oculta los campos de email y teléfono. | | hideCountry | boolean | false | Oculta el campo de país. | | customer | boolean | false | Cambia la etiqueta del campo de nombre (modo cliente vs. empresa). | | enabledExtAdress | boolean | false | Activa campos específicos para direcciones en Argentina y cambia etiquetas. | | withJurisdictionField | boolean | false | Muestra campo de documento o jurisdicción en direcciones de Argentina. | | withInstructionsFields | boolean | true | Muestra los campos de instrucciones de entrega (instrucciones, seguridad y fin de semana). | | lang | 'es' \| 'en' | 'es' | Idioma de los textos del formulario. | | submitButtonClassName | string | '' | Clase CSS adicional para el botón de submit. | | disableFields | boolean | false | Deshabilita todos los campos y el botón de submit. Se combina con el estado isSubmitting interno. |

Exports

La librería exporta los siguientes elementos:

import {
  AddressForm,          // Formulario completo
  AddressFields,        // Solo los campos (requiere FormProvider de react-hook-form)
} from 'dubalu-address-form';

import type {
  IPostalCodeState,             // Tipo del estado de resultados de código postal
  IFormValues,                  // Tipo de los valores del formulario
  ILang,                        // Tipo del idioma ('es' | 'en')
  PostalCodeFieldBaseProps,     // Props base para campo de código postal personalizado
  CountryCode,                  // Tipo de código de país
} from 'dubalu-address-form';

// Utilidades
import { getCountryNameByCode, getStateNameByCode } from 'dubalu-address-form';

Uso

Uso básico con AddressForm

import { useState } from 'react';
import { AddressForm } from 'dubalu-address-form';
import type { IPostalCodeState } from 'dubalu-address-form';

import 'dubalu-address-form/dist/index.css';

export default function App() {
  const [postalData, setPostalData] = useState<IPostalCodeState>({
    results: [],
    matchesEstimated: 0,
    loading: false,
  });

  const getPostalCodeAddresses = async (postalCode: string, offset = 0) => {
    // Implementar la llamada a tu API
  };

  return (
    <AddressForm
      initialValues={{ country_code: 'MX' }}
      postalCodeAddresses={postalData}
      setPostalData={setPostalData}
      onSubmit={(values) => console.log(values)}
      getPostalCodeAddresses={getPostalCodeAddresses}
      defaultCountryCode="MX"
      postalCodeSearch
      lang="es"
    />
  );
}

Deshabilitar todos los campos

Usa disableFields para bloquear todo el formulario externamente. El formulario también se deshabilita automáticamente mientras se está enviando (isSubmitting).

const [isLoading, setIsLoading] = useState(false);

<AddressForm
  // ...props requeridas
  disableFields={isLoading}
/>

Ocultar secciones del formulario

<AddressForm
  // ...props requeridas
  hideTitle             // Oculta el título "Nueva dirección / Actualizar dirección"
  hideName              // Oculta el campo de nombre/razón social
  hideContact           // Oculta email y teléfono
  hideCountry           // Oculta el selector de país
  withInstructionsFields={false} // Oculta los campos de instrucciones
  submitButtonClassName="w-full" // Clase extra para el botón
/>

Uso de AddressFields (solo campos, sin formulario)

AddressFields debe usarse dentro de un FormProvider de react-hook-form.

import { useForm, FormProvider } from 'react-hook-form';
import { AddressFields } from 'dubalu-address-form';
import type { IFormValues, IPostalCodeState } from 'dubalu-address-form';

export default function MyForm() {
  const methods = useForm<IFormValues>({ defaultValues: { country_code: 'MX' } });
  const [postalData, setPostalData] = useState<IPostalCodeState>({
    results: [],
    matchesEstimated: 0,
    loading: false,
  });

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(console.log)}>
        <AddressFields
          postalCodeSearch
          postalCodeAddresses={postalData}
          getPostalCodeAddresses={getPostalCodeAddresses}
          setPostalData={setPostalData}
          defaultCountryCode="MX"
        />
        <button type="submit">Guardar</button>
      </form>
    </FormProvider>
  );
}

Campo de código postal personalizado

Puedes reemplazar el campo de código postal con tu propio componente usando la prop postalCodeField:

import type { PostalCodeFieldBaseProps } from 'dubalu-address-form';

const MiCampoCodigo = ({
  label,
  register,
  setValue,
  errors,
  setDisabledByCP,
  setPostalData,
  changeFieldFocus,
}: PostalCodeFieldBaseProps) => {
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setValue('postal_code', value, { shouldValidate: true });
    if (value.length < 5) {
      setDisabledByCP(true);
    } else {
      changeFieldFocus();
    }
  };

  return (
    <input
      {...register('postal_code', { required: 'Requerido' })}
      onChange={handleChange}
      placeholder={label}
    />
  );
};

// Uso
<AddressForm
  // ...
  postalCodeField={MiCampoCodigo}
/>

Utilidades

import { getCountryNameByCode, getStateNameByCode } from 'dubalu-address-form';

const countryName = getCountryNameByCode('MX');         // 'Mexico'
const stateName = getStateNameByCode('Mexico', 'MEX');  // 'Estado de México'

Authors

• @dubalu

License

MIT