Feature: add reusable link-to-waypoint API for content cards

[acodebeard]

Summary

Add a reusable Waypoints API for content cards and other site content to link directly into the planner with a preselected waypoint.

DKC now has a theme-level prototype for this behavior on beach cards: a user clicks Add to Design Your Day, lands on the planner page, and the selected beach is already in the trip as a waypoint. This should move into the standalone Waypoints plugin so other pages, themes, blocks, and content types can use the same contract.

Desired behavior

• External content can request a planner URL for a known Google Place ID.
• The generated URL opens the Waypoints planner page with that place preselected.
• Optional category context can be included when available.
• URLs are generated at render time, not saved as local/staging/production URLs in post content.
• Link labels remain accessible when many cards use the same visible label.

Example target URL shape:

/planner-page/?category=beaches&waypoints[]=GOOGLE_PLACE_ID#planner-section-id

Proposed plugin responsibilities

• Own the canonical Place ID sanitizer.
• Own the planner page URL/permalink lookup.
• Own the planner section hash/id.
• Own the category registry or category validation.
• Expose a narrow PHP helper, for example:

waypoints_build_planner_link( $place_id, $args );

or separate URL/markup helpers if cleaner:

waypoints_build_planner_url( $place_id, $args );
waypoints_build_planner_cta( $place_id, $args );

Acceptance criteria

• A consumer can pass a Google Place ID and receive a valid planner URL.
• Empty or invalid Place IDs produce no usable link.
• Unknown categories are omitted or rejected consistently.
• The helper works on local subdirectory installs, staging, and production without hardcoded paths.
• The URL remains compatible with the planner’s no-JS query contract.
• CTA markup uses a real <a> element, not a button.
• Repeated visible labels such as “Add to Design Your Day” get unique accessible names, for example hidden “for {place/card title}” context.
• Existing DKC card behavior can be converted from theme-owned helpers to this plugin API.

Notes from DKC prototype

The DKC prototype stores only intent fields on the card: enabled, Google Place ID, optional category, and optional label. The final URL is built in PHP at render time so environment-specific URLs are not saved into content.