=== Mapfolia – Project Portfolio Map & Local SEO ===
Contributors: highbridge
Tags: portfolio, projects, map, local seo, contractor
Requires at least: 5.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Showcase completed projects with an interactive map, filterable photo grid, and built-in local SEO structured data.

== Description ==

Mapfolia is a portfolio plugin built for businesses whose work happens at a location: contractors, remodelers, builders, landscapers, roofers, pool builders, architects, and similar trades.

Every project gets a location, a photo gallery, key details, and optional client review — and the plugin turns that into the structured data, meta tags, and keyword-rich image alt text that help local search engines understand what you do and where you do it.

**Frontend**

* Filterable project grid with staggered animations and a details lightbox
* Interactive map of all project locations with marker clustering (no API key needed)
* Full-page single project template: hero gallery, details sidebar, location map, previous/next navigation
* Dark, premium look out of the box; every color and font is a CSS variable you can override
* Works with classic and block (full site editing) themes
* Fully responsive, keyboard accessible

**Project management**

* Custom post type with Project Type and Location taxonomies
* Gallery uploader with drag-to-reorder
* Value range, square footage, dates, status (Planning / In Progress / Completed / Featured)
* Key features, case study, and an optional real client review
* Click-to-set map location picker

**Local SEO**

* Service, CreativeWork, ImageObject, FAQ, Breadcrumb and ItemList structured data per project
* Optional LocalBusiness structured data with service areas and social profile links
* Geo meta tags, Open Graph tags, and auto-generated keyword-rich alt text for photos
* Settings to avoid duplicate output when you also run Yoast, Rank Math, AIOSEO, SEOPress, or The SEO Framework

**Optional AI drafting**

The plugin can draft a project's description, features, case study, and SEO fields from a photo. On WordPress 7.0+ it uses the core AI Client, so a provider configured once under Settings → Connectors powers the feature with no extra setup. On older WordPress versions (or as a fallback), add your own Anthropic (Claude) or OpenAI (ChatGPT) API key in the plugin's settings. Nothing is sent unless you click the button.

= Shortcodes =

* `[lpsc_showcase]` — full showcase: header, filters, grid, map, lightbox
* `[lpsc_map height="550px" zoom="10"]` — map only
* `[lpsc_grid limit="6" columns="3" type="kitchen-remodel"]` — simple grid

All three accept `type`, `location`, and `status` filters. The showcase also accepts `title`, `subtitle`, `eyebrow`, `show_header`, `show_filters`, and `show_map`.

== Third-party services ==

This plugin uses the following external services:

**OpenStreetMap tiles** — maps are drawn with tiles from tile.openstreetmap.org. Visitors' browsers request these tiles directly when a map is displayed. See the [OpenStreetMap tile usage policy](https://operations.osmfoundation.org/policies/tiles/) and [privacy policy](https://wiki.osmfoundation.org/wiki/Privacy_Policy). High-traffic sites should consider a commercial tile provider (the tile URL is filterable).

**Google Fonts** (optional, on by default) — DM Serif Display and Plus Jakarta Sans are loaded from fonts.googleapis.com. Disable this in Settings → Display if you prefer to self-host fonts or must avoid third-party requests. See the [Google Fonts privacy FAQ](https://developers.google.com/fonts/faq/privacy).

**AI providers** (optional, off by default) — clicking "Generate" on a project sends that project's cover photo, title, and any context you type to an AI provider to draft content. On WordPress 7.0+ with a provider configured under Settings → Connectors, the request goes through the WordPress core AI Client to the provider the site owner chose there. Otherwise, the plugin calls Anthropic or OpenAI directly using the API key from its settings; that key is stored in your WordPress database. See [Anthropic's privacy policy](https://www.anthropic.com/legal/privacy) and [OpenAI's privacy policy](https://openai.com/policies/privacy-policy). API usage is billed by the provider.

The bundled Leaflet (BSD-2-Clause) and Leaflet.markercluster (MIT) libraries are served from your own site.

== Installation ==

1. Upload the `mapfolia` folder to `/wp-content/plugins/`, or install the zip via Plugins → Add New.
2. Activate the plugin.
3. Go to **Projects → Settings** and enter your business information.
4. Add Project Types (e.g. Kitchen Remodel, New Construction) under **Projects → Project Types**.
5. Add projects with a cover image, gallery photos, and a map location.
6. Place `[lpsc_showcase]` on a page, or send visitors to `/projects/`.

== Frequently Asked Questions ==

= Does the map need a Google Maps API key? =

No. Maps use Leaflet with OpenStreetMap tiles, which are free for normal website use.

= Can I change the colors and fonts? =

Yes. Add overrides to your theme's stylesheet or the Customizer's Additional CSS:

`:root {
  --lpsc-primary: #1a2332;      /* page background */
  --lpsc-accent: #c8956c;       /* accent color */
  --lpsc-accent-light: #e0b892;
  --lpsc-surface: #1e2a3a;      /* card background */
  --lpsc-text: #e8eaed;
  --lpsc-font-display: Georgia, serif;
  --lpsc-font-body: system-ui, sans-serif;
}`

= Can I customize the templates? =

Copy any file from the plugin's `templates/` folder into `your-theme/mapfolia/` and edit it there. Your copy is used instead of the plugin's and survives plugin updates. You can also uncheck "Use built-in templates" in Settings to let your theme render project pages entirely.

= I already use Yoast / Rank Math. Will this conflict? =

On activation the plugin detects common SEO plugins and turns off its own meta tag output so you don't get duplicate description and Open Graph tags. Project structured data is still output because SEO plugins don't generate it. Leave "LocalBusiness structured data" off if your SEO plugin already outputs an Organization or LocalBusiness block.

= The /projects/ page shows a 404 =

Go to Settings → Permalinks and click Save (no changes needed). This refreshes WordPress's rewrite rules.

= Is the AI feature required? =

No. It is entirely optional and does nothing until an AI backend is available (a provider under Settings → Connectors on WordPress 7.0+, or an API key in the plugin's settings). The plugin never sends data anywhere on its own.

== Screenshots ==

1. Showcase grid with filters
2. Map view with clustered markers
3. Project details lightbox
4. Single project page
5. Project edit screen with gallery, map picker and AI box
6. Settings page

== Changelog ==

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
