🌍 Smoothglue Coordinate Entry

A robust 🏗️, type-safe 🛡️ React UI component library for interacting with and parsing geospatial coordinates 🗺️ in various formats. This library provides ready-to-use input fields, poppers, and utility hooks for seamless coordinate management in SmoothGlue applications.

Table of Contents 📑

• 🌍 Smoothglue Coordinate Entry
  • Table of Contents 📑
  • ✨ Features
  • 🚀 Getting Started
    • 📦 Installation
      • Peer Dependencies 🤝
  • Usage 🎮
    • SgCoordinateEntry 🧭
    • SgCoordinateEntry Props ⚙️
    • useCoordinateDispatcher Hook 🪝
  • 📚 Running Storybook
  • Contributing 🤲
    • 📂 Project Structure
    • Available Scripts 📜

✨ Features

• 🗺️ Multi-Format Support: Effortlessly parse and interact with multiple coordinate systems:
  • Decimal Degrees (e.g. 12.4567°S, 14°W)
  • Decimal-Minutes Degrees (e.g. 32°57'S, 032°57'E)
  • Decimal-Minutes-Seconds Degrees (e.g. 32°57'28.08"S, 032°57'28.08"E)
  • Universal Transverse Mercator (UTM) (e.g. 23N330)
  • Military Grid Reference System (MGRS) (e.g. 02QGF100)
  • Global Area Reference System (GARS) (e.g. 004RT23)
• 🛡️ Type-Safe: Built entirely in TypeScript with strict geospatial definitions.
• 🎨 Theming Support: Leverages Material UI (MUI) and ships with theme configurations.
• 🧩 React Hook Form Integration: Components are designed to work seamlessly with complex form state management.
• 🪝 Custom Hooks: Exposes utility hooks like useCoordinateDispatcher for managing dispatch events outside the main input component.

🚀 Getting Started

📦 Installation

Install the package using npm or yarn:

npm install @smoothglue/smoothglue-coordinate-entry

Peer Dependencies 🤝

This library relies on several peer dependencies that must be installed in your project 🔗.

Ensure you have the core React and Material UI packages installed:

npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled lodash

Note: This package requires React 18+ and Material UI @mui/material v6+.

Usage 🎮

SgCoordinateEntry 🧭

The SgCoordinateEntry is the primary UI component. It provides a text input that automatically parses strings into structured coordinate objects, and offers a popper overlay for discrete degree/minute/second editing.

import { useState } from 'react'
import { SgCoordinateEntry, CartographicDegree } from '@smoothglue/smoothglue-coordinate-entry'

export const CoordinateForm = () => {
    const [coordinate, setCoordinate] = useState<CartographicDegree | null>(null)

    const handleChange = (newCoordinate: CartographicDegree) => {
        setCoordinate(newCoordinate)
        console.log('Updated Coordinate:', newCoordinate)
    }

    return (
        <SgCoordinateEntry
            label="Object Location"
            value={coordinate}
            onChange={handleChange}
            placeholder="e.g. 38° 53' 23 N, 77° 0' 32 W"
        />
    )
}

SgCoordinateEntry Props ⚙️

A brief overview of the primary props available on the main component.

| Prop | Type | Description | | :------------- | :------------------------------------ | :-------------------------------------------------------------------- | | value | CartographicDegree | The current coordinate value. | | onChange | (coord: CartographicDegree) => void | Callback fired when the coordinate is successfully parsed or updated. | | label | string | The label for the MUI TextField. | | disabled | boolean | Disables the input field. | | error | boolean | Flags the input in an error state. |

useCoordinateDispatcher Hook 🪝

The useCoordinateDispatcher hook allows you to dispatch custom coordinate events to update the entry state externally.

import { useCoordinateDispatcher } from '@smoothglue/smoothglue-coordinate-entry'
import { Button } from '@mui/material'

const ExternalUpdater = () => {
    const { dispatchCoordinate } = useCoordinateDispatcher()

    const setWashingtonDC = () => {
        dispatchCoordinate({
            latitude: 38.8895,
            longitude: -77.0353,
            height: 0
        })
    }

    return <Button onClick={setWashingtonDC}>Set to Washington D.C.</Button>
}

📚 Running Storybook

This project uses Storybook to develop, document, and test UI components in isolation.

1. Install dependencies:

   npm install

2. Start the Storybook server:

   npm run storybook

3. Open your browser: Navigate to http://localhost:6006 to view the interactive component stories.

Contributing 🤲

📂 Project Structure

• src/components/: Core React UI components, including SgCoordinateEntry and SgDegreeFields.
• src/utilities/: Core business logic for geospatial math, coordinate conversions, and validation.
• src/themes/: Material UI theme definitions specific to SmoothGlue product lines.
• src/types/: Centralized TypeScript type definitions.
• .storybook/: Configuration for the Storybook component explorer.

Available Scripts 📜

In the project directory, you can run:

• npm run storybook: Starts the Storybook development server on port 6006 🎨.
• npm run build: Runs TypeScript type checking (tsc) and builds the library using Vite 📦.
• npm run test: Runs the unit test suite using Vitest (JSDom) 🧪.
• npm run test:all: Runs both unit tests and browser-based component tests via Storybook Playwright integration 🎭.
• npm run lint: Runs ESLint to analyze the code for quality issues 🧹.
• npm run coverage: Runs unit tests and outputs a coverage report 📊.