@unimart/unimart-locations-react

React hooks for managing location dropdowns for Costa Rica and Guatemala.

Installation

npm install @unimart/unimart-locations-react
# or
yarn add @unimart/unimart-locations-react

Usage

import React from 'react';
import {
  useLocationsDropdown,
} from '@unimart/unimart-locations-react';

const LocationSelector = () => {
  const {
    level1Options,
    level2Options,
    level3Options,
    handleLevel1Change,
    handleLevel2Change,
    handleLevel3Change,
    selectedValues,
    inputPlaceholders
  } = useLocationsDropdown({ country: 'costa_rica' });

  return (
    <div>
      <select
        value={selectedValues.locationLevel1 || ''}
        onChange={(e) => handleLevel1Change(e.target.value)}
      >
        <option value="">{inputPlaceholders.level1}</option>
        {level1Options.map(option => (
          <option key={option} value={option}>{option}</option>
        ))}
      </select>

      {level2Options.length > 0 && (
        <select
          value={selectedValues.locationLevel2 || ''}
          onChange={(e) => handleLevel2Change(e.target.value)}
        >
          <option value="">{inputPlaceholders.level2}</option>
          {level2Options.map(option => (
            <option key={option} value={option}>{option}</option>
          ))}
        </select>
      )}

      {level3Options.length > 0 && (
        <select
          value={selectedValues.locationLevel3 || ''}
          onChange={(e) => handleLevel3Change(e.target.value)}
        >
          <option value="">{inputPlaceholders.level3}</option>
          {level3Options.map(option => (
            <option key={option} value={option}>{option}</option>
          ))}
        </select>
      )}

      {selectedValues.zipCode && (
        <div>Zip Code: {selectedValues.zipCode}</div>
      )}
    </div>
  );
};

export default LocationSelector;

API

useLocationsDropdown

const {
  level1Options,
  level2Options,
  level3Options,
  handleLevel1Change,
  handleLevel2Change,
  handleLevel3Change,
  selectedValues,
  inputPlaceholders,
  reinitializeOptions
} = useLocationsDropdown({
  initialLocationValues,
  country
});

Parameters

• country: The country code ('costa_rica' or 'guatemala')
• initialLocationValues (optional): Initial values for the dropdowns
• customLocationsDataset (optional): Custom dataset containing hierarchical location information

Returns

• level1Options: Array of options for the first level dropdown
• level2Options: Array of options for the second level dropdown
• level3Options: Array of options for the third level dropdown
• handleLevel1Change: Function to handle changes in the first level dropdown
• handleLevel2Change: Function to handle changes in the second level dropdown
• handleLevel3Change: Function to handle changes in the third level dropdown
• selectedValues: Object containing the currently selected values
• inputPlaceholders: Placeholder texts for the dropdowns (suggested)
• reinitializeOptions: Function to reset the dropdowns with new data

Available Data

The package includes location data for:

• Costa Rica (provinces, cantons, districts)
• Guatemala (departments, municipalities)

The data is automatically selected based on the country parameter passed to useLocationsDropdown.

If you need to access the data directly:

import { COUNTRY_DATASETS } from '@unimart/unimart-locations-react';

// Costa Rica data
const costaRicaData = COUNTRY_DATASETS.costa_rica;

// Guatemala data
const guatemalaData = COUNTRY_DATASETS.guatemala;

Development and Publishing

Git Workflow

This project follows a structured git workflow with two main branches:

• main: Production-ready code. All releases are published from this branch.
• develop: Development and integration branch for new features.

Publishing to npm

The package can only be published from the main branch. Multiple safeguards are in place to enforce this:

1. Local branch check via npm configuration
2. Pre-publish script verification
3. CI/CD pipeline restrictions

Publishing Steps

To publish a new version:

1. Ensure you're on the main branch:

   git checkout main

2. Update the version number:

   npm version patch  # For bug fixes
   npm version minor  # For new features
   npm version major  # For breaking changes

3. Publish to npm:

   npm publish

The npm version command will:

• Update the version in package.json
• Create a git tag
• Build the package
• Commit the changes

After publishing, a GitHub release should be created to document the changes.

Automated Publishing

The package can also be published automatically through GitHub Actions when:

1. A new GitHub Release is created
2. The release is created from the main branch

This ensures consistent versioning and release notes across GitHub and npm.

Testing Before Publishing

To test the package locally before publishing:

npm pack

This creates a .tgz file that can be installed in another project:

npm install /path/to/unimart-locations-react-1.0.0.tgz