@tempots/ui 9.0.0 → 10.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "9.0.0",
+  "version": "10.1.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -41,6 +41,6 @@
   },
   "peerDependencies": {
     "@tempots/std": "0.24.0",
-    "@tempots/dom": "30.1.0"
+    "@tempots/dom": "31.0.0"
   }
 }

package/renderables/anchor.d.ts

@@ -1,4 +1,5 @@
 import { TNode, Value, Renderable } from '@tempots/dom';
+import { NavigationOptions } from './router/location';
 import { HandleAnchorClickOptions } from '../dom/handle-anchor-click';
 import { Merge } from '@tempots/std';
 /**
@@ -11,11 +12,7 @@ export type AnchorOptions = Merge<{
      * Can be a string or a Signal containing a string.
      */
     href: Value<string>;
-    /**
-     * Whether to use a view transition when navigating to the anchor.
-     */
-    withViewTransition?: boolean;
-}, HandleAnchorClickOptions>;
+} & NavigationOptions, HandleAnchorClickOptions>;
 /**
  * Represents either a string value (or Signal of string) for the href,
  * or a full AnchorOptions object.

package/renderables/router/browser-location.d.ts

@@ -1,12 +1,15 @@
+import { Prop } from '@tempots/dom';
+import { NavigationOptions } from './navigation-options';
 import { LocationData } from './location-data';
-/**
- * Creates a location prop that represents the current browser location.
- * The location prop is updated whenever the browser location changes.
- *
- * @returns The location prop.
- * @internal
- */
-export declare const makeBrowserLocationProp: () => {
-    value: import('@tempots/dom').Prop<LocationData>;
+type HistoryAction = 'pushState' | 'replaceState';
+export type BrowserLocationSource = {
+    location: Prop<LocationData>;
     dispose: () => void;
+    commit: (data: LocationData, options: NavigationOptions | undefined, action: HistoryAction) => void;
+    go: (delta: number, options?: NavigationOptions) => void;
+    back: (options?: NavigationOptions) => void;
+    forward: (options?: NavigationOptions) => void;
+    resolve: (url: string) => LocationData;
 };
+export declare const makeBrowserLocationSource: () => BrowserLocationSource;
+export {};

package/renderables/router/headless-location.d.ts

@@ -1,13 +1,14 @@
-import { HeadlessContext } from '@tempots/dom';
+import { HeadlessContext, Prop } from '@tempots/dom';
+import { NavigationOptions } from './navigation-options';
 import { LocationData } from './location-data';
-export declare const isAbsoluteURL: (url: string) => boolean;
-/**
- * Provides the location context to the child component.
- * @param child - The child component to be wrapped with the location context.
- * @returns The wrapped component with the location context.
- * @public
- */
-export declare const makeHeadlessLocationProp: (ctx: HeadlessContext) => {
-    value: import('@tempots/dom').Prop<LocationData>;
+export type HeadlessLocationSource = {
+    location: Prop<LocationData>;
     dispose: () => void;
+    commit: (data: LocationData, options: NavigationOptions | undefined, action: 'pushState' | 'replaceState') => void;
+    go: (delta: number, options?: NavigationOptions) => void;
+    back: (options?: NavigationOptions) => void;
+    forward: (options?: NavigationOptions) => void;
+    resolve: (url: string) => LocationData;
 };
+export declare const isAbsoluteURL: (url: string) => boolean;
+export declare const makeHeadlessLocationSource: (ctx: HeadlessContext) => HeadlessLocationSource;

package/renderables/router/location-data.d.ts

@@ -1,4 +1,3 @@
-import { Prop } from '@tempots/dom';
 /**
  * Represents the data for a location.
  *
@@ -33,14 +32,6 @@ export declare const areLocationsEqual: (a: LocationData, b: LocationData) => bo
  * @public
  */
 export declare const locationFromURL: (url: string, baseUrl?: string) => LocationData;
-/**
- * Sets the location from the given URL and updates the specified property.
- * @param prop - The property to update with the new location.
- * @param url - The URL from which to extract the location.
- * @returns The updated property.
- * @public
- */
-export declare const setLocationFromUrl: (prop: Prop<LocationData>, url: string) => Prop<LocationData>;
 /**
  * Returns the full URL based on the provided location data.
  *

package/renderables/router/location.d.ts

@@ -1,77 +1,140 @@
-import { Prop, Provider } from '@tempots/dom';
+import { Provider, Signal, Value } from '@tempots/dom';
 import { LocationData } from './location-data';
+import { NavigationOptions } from './navigation-options';
+export type { NavigationOptions } from './navigation-options';
 /**
- * Provider for browser location and navigation functionality.
+ * Options that control how `LocationHandle.match` and `matchSignal` interpret URL parts.
  *
- * The Location provider gives components access to the current URL and provides
- * methods for programmatic navigation. It automatically detects whether it's
- * running in a browser or headless environment and provides the appropriate
- * implementation.
- *
- * @example
- * ```typescript
- * // Use location in a component
- * const CurrentPath = () =>
- *   Use(Location, location => html.div(
- *     'Current path: ', location.$.pathname,
- *     html.br(),
- *     'Search params: ', location.$.search,
- *     html.br(),
- *     'Hash: ', location.$.hash
- *   ))
- * ```
- *
- * @example
- * ```typescript
- * // Navigation buttons
- * const Navigation = () =>
- *   Use(Location, location => html.nav(
- *     html.button(
- *       on.click(() => location.navigate('/')),
- *       'Home'
- *     ),
- *     html.button(
- *       on.click(() => location.navigate('/about')),
- *       'About'
- *     ),
- *     html.button(
- *       on.click(() => location.back()),
- *       'Back'
- *     ),
- *     html.button(
- *       on.click(() => location.forward()),
- *       'Forward'
- *     )
- *   ))
- * ```
- *
- * @example
- * ```typescript
- * // Conditional rendering based on path
- * const ConditionalContent = () =>
- *   Use(Location, location =>
- *     When(location.map(loc => loc.pathname.startsWith('/admin')),
- *       () => AdminPanel(),
- *       () => PublicContent()
- *     )
- *   )
- * ```
+ * @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.
  *
- * @example
- * ```typescript
- * // URL parameter extraction
- * const ProductPage = () =>
- *   Use(Location, location => {
- *     const searchParams = location.map(loc => new URLSearchParams(loc.search))
- *     const productId = searchParams.map(params => params.get('id'))
+ * @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: Value<string | RegExp | ((location: LocationData) => boolean)>, options?: LocationMatchOptions) => Signal<boolean>;
+};
+/**
+ * Draft object provided inside `LocationHandle.run` for staged updates.
  *
- *     return Ensure(productId,
- *       (id) => ProductDetail({ id }),
- *       () => html.div('Product ID required')
- *     )
- *   })
- * ```
+ * @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<Prop<LocationData>>;
+export declare const Location: Provider<LocationHandle>;

package/renderables/router/navigation-options.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration applied when committing a navigation update.
+ *
+ * @public
+ */
+export type NavigationOptions = {
+    /**
+     * Optional history state to associate with the navigation entry.
+     */
+    state?: unknown;
+    /**
+     * Scroll behaviour after navigation. Defaults to preserving the current scroll position.
+     */
+    scroll?: 'preserve' | 'auto';
+    /**
+     * Enable view transitions when supported by the browser.
+     */
+    viewTransition?: boolean;
+    /**
+     * Force replacement of the current history entry instead of pushing a new one.
+     */
+    replace?: boolean;
+};

package/renderables/router/route-info.d.ts

@@ -68,6 +68,10 @@ export type RouteCatchAll = {
      * The type of the catch-all
      */
     type: 'catch-all';
+    /**
+     * Optional parameter name that captures the remaining path.
+     */
+    name?: string;
 };
 /**
  * Represents a segment of a route.
@@ -101,7 +105,7 @@ export type MakeParams<P> = P extends string[] ? {
  * @returns An array of parameter names extracted from the tuple type.
  * @public
  */
-export type ExtractParamsFromTuple<S extends unknown[]> = S extends [] ? [] : S extends [infer H, ...infer R] ? H extends `:${infer P}` ? [P, ...ExtractParamsFromTuple<R>] : ExtractParamsFromTuple<R> : never;
+export type ExtractParamsFromTuple<S extends unknown[]> = S extends [] ? [] : S extends [infer H, ...infer R] ? H extends `:${infer P}` ? [P, ...ExtractParamsFromTuple<R>] : H extends `*${infer C}` ? C extends '' ? ExtractParamsFromTuple<R> : [C, ...ExtractParamsFromTuple<R>] : ExtractParamsFromTuple<R> : never;
 /**
  * Extracts the parameters from a string literal representing a route path.
  * @typeParam S - The string literal representing the route path.