US States Visited Map (Developer README)

Developer-focused documentation for the WordPress plugin in this repository. For end-user docs, see readme.txt.

Overview

US States Visited Map is a WordPress plugin that renders an interactive US map and highlights states selected in an admin UI. The map is embedded with the [us_states_visited_map] shortcode and rendered client-side using D3 + TopoJSON (bundled in assets/vendor).

Key behaviors:

• Admin page lets users select states, store visit dates, and optionally override colors per state.
• A global palette and settings (tooltips, show Alaska/Hawaii) are stored as options.
• The shortcode controls display-only settings (size, class, autocolor, palette override).
• Map rendering is client-side via assets/js/usvm-map.js.

Plugin Entry Point

us-states-visited-map.php defines:

• Plugin header metadata.
• Constants: USVM_VERSION, USVM_SLUG, USVM_FILE, USVM_DIR, USVM_URL.
• Autoloads core classes.
• Registers plugin init and textdomain load hooks.

File Structure

.
├─ us-states-visited-map.php      # Plugin bootstrap + constants
├─ uninstall.php                  # Deletes plugin options on uninstall
├─ readme.txt                     # WordPress.org style readme
├─ readme.md                      # This developer README
├─ includes/
│  ├─ class-usvm-plugin.php        # Initializes admin + shortcode classes
│  ├─ class-usvm-admin.php         # Admin UI + save handlers
│  ├─ class-usvm-options.php       # Option getters/setters
│  ├─ class-usvm-sanitize.php      # Sanitizers for input + shortcode atts
│  └─ class-usvm-shortcode.php     # Shortcode handler + asset enqueue
└─ assets/
   ├─ css/admin.css                # Admin UI styles
   ├─ js/admin.js                  # Admin UI behavior
   ├─ js/usvm-map.js               # Frontend map rendering
   ├─ data/states-10m.json         # TopoJSON data (US states)
   └─ vendor/                      # Bundled D3 + TopoJSON

Data Model (Options)

Stored in wp_options:

• usvm_states: associative array keyed by state code (e.g., CA, NY), containing date and optional color.
• usvm_palette: array of hex colors (global auto-color palette).
• usvm_settings: array with tooltips, show_ak, show_hi.

See includes/class-usvm-options.php.

State entries

Each selected state is stored as:

[
  'CA' => [
    'date'  => 'YYYY-MM-DD',
    'color' => '#ffcc00' // optional
  ]
]

The date is validated and normalized in USVM_Sanitize::validate_date(). If invalid/empty, the current date is used when saving.

Admin UI

The admin page is created via USVM_Admin:

• Menu slug: usvm-admin
• Saves are handled via admin_post_usvm_save
• Nonce: usvm_nonce / usvm_save

Admin supports:

• Select/clear/reset states
• Per-state manual color override toggle + color picker
• Per-state visit date
• Palette presets plus persistent custom palette editing
• Global settings (tooltips, show AK/HI)

Shortcode

Shortcode tag: [us_states_visited_map]

Attributes (sanitized in USVM_Sanitize::sanitize_shortcode_atts):

• width (int): default 900, min 200, max 4000
• height (int): default 600, min 200, max 4000
• autocolor (0/1): default 1
• class (string): additional CSS classes; usvm-map is always included
• palette (string): comma-separated hex colors, e.g. #f94144,#f3722c

The shortcode only controls display settings. State selection and visit data are read from saved options.

Example (basic)

[us_states_visited_map]

Example (all options)

[us_states_visited_map width="900" height="600" autocolor="1" class="usvm-map my-class" palette="#f94144,#f3722c,#f9c74f,#90be6d"]

Frontend Rendering

assets/js/usvm-map.js:

• Reads JSON config from data-usvm-config on the container element.
• Loads assets/data/states-10m.json TopoJSON via fetch().
• Filters out Alaska/Hawaii if disabled.
• Auto-colors selected states using a simple neighbor-aware palette assignment.
• Adds <title> tooltips when enabled.
• Resizes responsively with ResizeObserver or window resize fallback.

Styling / Markup

The shortcode output is a single container:

<div class="usvm-map ..." data-usvm-config="..."></div>

usvm-map.js injects an inner wrapper and SVG. The base class usvm-map is always present; use this to target custom styles.

Internationalization

Text domain: us-states-visited-map Domain path: /languages

Strings are wrapped with __() / esc_html__() in PHP.

Uninstall Behavior

uninstall.php deletes:

• usvm_states
• usvm_palette
• usvm_settings

Development Notes

There is no build step. All JS/CSS are plain files committed to the repo. Vendor libraries are bundled.

Recommended test flow:

1. Activate plugin in a WordPress dev site.
2. Use the admin page to save selections, dates, and palette.
3. Insert the shortcode in a page and verify rendering.
4. Toggle tooltips / AK / HI and confirm changes.
5. Test with multiple shortcode instances on a page.

License

Plugin code is GPLv2 or later (see us-states-visited-map.php header). Vendor libraries include their own licenses in assets/vendor/**/LICENSE.