@tempots/ui/renderables/router/location.d.ts

Provides a higher level of renderables to help fast development with Tempo.

import { Provider, Signal, SplitValue } from '@tempots/dom';
import { LocationData } from './location-data';
import { NavigationOptions } from './navigation-options';
export type { NavigationOptions } from './navigation-options';
/**
 * Options that control how `LocationHandle.match` and `matchSignal` interpret URL parts.
 *
 * @public
 */
export type LocationMatchOptions = {
    /**
     * Whether the search parameters should participate in the match. Defaults to `true`.
     */
    includeSearch?: boolean;
    /**
     * Whether the hash fragment should participate in the match. Defaults to `true`.
     */
    includeHash?: boolean;
    /**
     * Keys that should be ignored when comparing search parameters.
     */
    ignoreSearchParams?: string[];
};
export declare const evaluateLocationMatch: (location: LocationData, matcher: string | RegExp | ((location: LocationData) => boolean), options: LocationMatchOptions | undefined) => boolean;
/**
 * A read/write navigation handle exposed by the Location provider.
 *
 * @public
 */
export type LocationHandle = {
    /**
     * Reactive signal containing the structured location (pathname, search, hash).
     */
    readonly location: Signal<LocationData>;
    /**
     * Reactive signal containing the full URL string derived from the location.
     */
    readonly url: Signal<string>;
    /**
     * Reactive signal for the current pathname.
     */
    readonly pathname: Signal<string>;
    /**
     * Reactive signal with the parsed search parameters.
     */
    readonly search: Signal<Record<string, string>>;
    /**
     * Reactive signal for the current hash fragment (without the leading `#`).
     */
    readonly hash: Signal<string | undefined>;
    /**
     * Replaces the entire location with the provided data.
     */
    setLocation: (data: LocationData, options?: NavigationOptions) => void;
    /**
     * Applies a transformer to the current location and commits the result.
     */
    updateLocation: (updater: (curr: LocationData) => LocationData, options?: NavigationOptions) => void;
    /**
     * Navigates to the provided URL string, resolving relative paths when needed.
     */
    navigate: (url: string, options?: NavigationOptions) => void;
    /**
     * Navigates to the URL string, forcing a history replace even if options do not specify it.
     */
    replace: (url: string, options?: NavigationOptions) => void;
    /**
     * Moves backward in history, when supported by the underlying source.
     */
    back: (options?: NavigationOptions) => void;
    /**
     * Moves forward in history, when supported by the underlying source.
     */
    forward: (options?: NavigationOptions) => void;
    /**
     * Performs a relative history navigation offset.
     */
    go: (delta: number, options?: NavigationOptions) => void;
    /**
     * Updates only the pathname portion of the current location.
     */
    setPathname: (pathname: string, options?: NavigationOptions) => void;
    /**
     * Updates the hash fragment, normalising empty values to `undefined`.
     */
    setHash: (hash: string | undefined | null, options?: NavigationOptions) => void;
    /**
     * Removes the current hash fragment.
     */
    clearHash: (options?: NavigationOptions) => void;
    /**
     * Merges the provided entries into the current search parameters (null/undefined removes keys).
     */
    setSearch: (entries: Record<string, string | null | undefined>, options?: NavigationOptions) => void;
    /**
     * Convenience helper for updating a single search parameter.
     */
    setSearchParam: (key: string, value: string | null | undefined, options?: NavigationOptions) => void;
    /**
     * Applies a transformer to the search parameters, committing the result.
     */
    updateSearch: (updater: (curr: Record<string, string>) => Record<string, string>, options?: NavigationOptions) => void;
    /**
     * Returns a derived signal for a single search parameter.
     */
    queryParam: (key: string) => Signal<string | undefined>;
    /**
     * Runs mutations against a draft copy and commits once after the callback finishes.
     */
    run: (mutate: (draft: LocationDraft) => void, options?: NavigationOptions) => void;
    /**
     * Evaluates whether the current location matches the provided matcher, honouring match options.
     */
    match: (matcher: string | RegExp | ((location: LocationData) => boolean), options?: LocationMatchOptions) => boolean;
    /**
     * Returns a reactive signal that mirrors the result of `match`.
     */
    matchSignal: (matcher: SplitValue<string | RegExp | ((location: LocationData) => boolean)>, options?: LocationMatchOptions) => Signal<boolean>;
};
/**
 * Draft object provided inside `LocationHandle.run` for staged updates.
 *
 * @public
 */
export type LocationDraft = {
    readonly location: LocationData;
    setLocation: (data: LocationData) => LocationDraft;
    setPathname: (pathname: string) => LocationDraft;
    setHash: (hash: string | undefined | null) => LocationDraft;
    clearHash: () => LocationDraft;
    setSearch: (entries: Record<string, string | null | undefined>) => LocationDraft;
    setSearchParam: (key: string, value: string | null | undefined) => LocationDraft;
    updateSearch: (updater: (curr: Record<string, string>) => Record<string, string>) => LocationDraft;
};
/**
 * Provider exposing the LocationHandle for navigation and location state.
 *
 * @public
 */
export declare const Location: Provider<LocationHandle>;