router

func BuildMetadataNode ¶

func BuildMetadataNode(parseRouterMetadata Metadata) *runtime.Element

BuildMetadataNode renders route-managed metadata as SSR-safe head children.

The generated tags are marked so the client router can reconcile and clean up only framework-owned metadata during hydration and later navigations.

func BuildRouteService ¶

func BuildRouteService() pluginruntime.RouteService

BuildRouteService returns one router-backed route service.

func DecodeQuery ¶

func DecodeQuery[T any](parseValues url.Values) (T, error)

DecodeQuery decodes URL query values into a typed struct T using `query:"name"` tags (falling back to the lowercased field name), then validates the result with the validate package using any `validate:"..."` tags on the same struct. It is the typed-search-params path: read `?page=2&sort=desc` into a struct once, with conversion and validation, instead of scattering `q.Get("page")` + manual strconv + bounds checks across the codebase.

Supported field kinds: string, bool, the sized int/uint kinds, float32/64, and []string (for repeated params). A missing param leaves the field at its zero value — mark it `validate:"required"` to reject that. A malformed value (e.g. page=abc for an int) or an unsupported field kind returns an error; validation failures return the validate.Result (which implements error and carries per-field messages).

type ListQuery struct {
    Page int    `query:"page" validate:"gte=1"`
    Sort string `query:"sort" validate:"omitempty,oneof=asc desc"`
    Tags []string `query:"tag"`
}
q, err := router.DecodeQuery[ListQuery](values) // err is a validate.Result on bad input

func EncodeQuery ¶

func EncodeQuery(parseValue any) url.Values

EncodeQuery renders a typed struct (or a non-nil pointer to one) back into url.Values using the same `query:"name"` tags, skipping zero-valued fields so the resulting URL stays clean. It is the inverse of DecodeQuery, for building links and updating the address bar from typed state. By contract it takes a struct: a non-struct, nil pointer, or other value has no query fields and returns an empty url.Values (it never panics) — DecodeQuery is the validated counterpart, so encoding stays intentionally permissive.

func FragmentHref ¶

func FragmentHref(parseFragment string) string

FragmentHref returns an in-page anchor href (e.g. a "skip to content" link) that is safe under a <base href> (G7). With a <base href> a bare "#main" resolves against the base (navigating to root); embedding the live path keeps the anchor in-page. It returns "<current-path>#<fragment>".

This targets history routers, where the <base href> footgun exists. Hash routers keep the whole route in the URL fragment, so a second in-page fragment cannot be expressed as an href (use programmatic scrolling instead); to avoid a malformed "#path#fragment", FragmentHref does NOT add the hash-router prefix.

The current query string is preserved (e.g. "/list?page=2#main"), so clicking the anchor stays on the exact current location rather than dropping query state.

A(html.Href(router.FragmentHref("main")), "Skip to content")

func GetCurrentPath ¶

func GetCurrentPath() string

GetCurrentPath returns the current route path from the global router.

func Href ¶

func Href(parsePath string) string

Href returns the correct href attribute value for navigating to path under the active router mode (G7). For a hash router it returns "#<path>"; for a history router it returns the normalized path (which the browser resolves against any <base href>). Use it instead of hand-building href strings so links work regardless of router mode or base href.

A(Href(router.Href("/transactions")), "Transactions")

func Navigate ¶

func Navigate(parsePath string)

Navigate updates the URL using the appropriate method for the current router.

package main

import (
	"github.com/monstercameron/GoWebComponents/v4/router"
)

func main() {
	// Navigate to a new path
	// This works with both hash and history routers
	router.Navigate("/about")
}

Output:

func NavigateReplace ¶

func NavigateReplace(parsePath string)

NavigateReplace replaces the current history entry using the appropriate method for the current router.

func OnNavigate ¶

func OnNavigate(parseFn func(Location)) func()

OnNavigate registers fn to run after each navigation with the new Location — the seam for SPA scroll-reset, analytics page views, and title side effects (G28). It returns an unsubscribe func.

Firing semantics: fn runs once on the initial render (the first location is a change from "none", so analytics see the landing page view), then once per subsequent navigation. It does NOT fire when the location is unchanged (a re-render at the same path+query is deduped). Register before mounting if you need the initial fire.

stop := router.OnNavigate(func(loc router.Location) { scrollTop() })
defer stop()

func PreserveReturnTo ¶

func PreserveReturnTo(parsePath string, parseQuery url.Values) string

PreserveReturnTo normalizes an internal path plus query values into a bounded return-target payload suitable for auth or re-auth redirects.

func ReadReturnTo ¶

func ReadReturnTo(parseQuery url.Values, parseFallback string) string

ReadReturnTo reads an internal return-target query value and falls back when the value is empty, oversized, or external.

func RegisterElementRoute ¶

func RegisterElementRoute(parsePath string, parseElemRef js.Value)

RegisterElementRoute renders a route directly to a DOM element and sets up hash listening.

func RegisterLazyRoute ¶

func RegisterLazyRoute(parsePath string, parseComponent interface{}, parseChunk RouteChunk, parseOptions ...Options)

RegisterLazyRoute registers a route on the global router with a route chunk.

func RegisterRoute ¶

func RegisterRoute(parsePath string, parseComponent interface{}, parseOptions ...Options)

RegisterRoute registers a route with the global router.

func RegisteredRoutes ¶

func RegisteredRoutes() []string

RegisteredRoutes returns a sorted, de-duplicated slice of all registered route path strings from the global router. It delegates to GetRouter().RegisteredRoutes() and returns a non-nil empty slice when no routes are registered or the global router is nil.

func RetryLoader ¶

func RetryLoader(parseKey string) error

RetryLoader clears one loader entry by key and re-runs the current route render.

func Revalidate ¶

func Revalidate()

Revalidate clears the current route loader result and runs the route again.