@pixelscriptio/tessera/router

File-based routing on the History API: useRoute(), navigate() and the router. See Pages and routing.

buildRouteManifest

function

Build the routes for a pages folder from the paths of its .tess files (relative to it, forward slashes).

index.tess is its folder's default, [name].tess is a parameter, and a top-level 404.tess is the not-found page. Two files that map to the same route (even if their parameters are named differently) are an error that names both, because it is not clear which one should win.

function buildRouteManifest(files: string[]): RouteManifest

createRouter

function

Not documented yet.

function createRouter(options: RouterOptions): Router

LayoutModule

interface

What a layout module exports: the component, with a default slot where the page goes.

export interface LayoutModule {
  default: Component
}

layoutsFromModules

function

Layouts by name from import.meta.glob('./layouts/*.tess'), the way the generated route module does.

function layoutsFromModules(modules: Record<string, () => Promise<unknown>>, layoutsPrefix: string): Record<string, () => Promise<LayoutModule>>

matchRoute

function

The first route that matches pathname, with the parameters it captured. A trailing slash is ignored.

function matchRoute<T extends { segments: Segment[]; }>(routes: readonly T[], pathname: string): RouteMatch<T> | undefined

navigate

function

Go to another page of the app. Use a normal <a href> for other sites.

function navigate(to: string, options?: NavigateOptions): Promise<void>

NavigateOptions

interface

Not documented yet.

export interface NavigateOptions {
  
  replace?: boolean
}

PageModule

interface

What a page module exports: the component, and the <page> block's metadata.

export interface PageModule {
  default: Component
  page?: { title?: string; layout?: string | false }
}

pagePaths

function

Turn the keys of import.meta.glob('./pages/**\/*.tess') into a manifest, given the pages folder prefix.

function pagePaths(globKeys: string[], pagesPrefix: string): string[]

parsePattern

function

Segments for a route pattern such as /blog/:slug.

function parsePattern(path: string): Segment[]

patternOf

constant

Not documented yet.

const patternOf: (segments: Segment[]) => string

RouteDefinition

interface

Not documented yet.

export interface RouteDefinition {
  
  path: string
  
  load: () => Promise<PageModule>
}

RouteDiagnostic

interface

Not documented yet.

export interface RouteDiagnostic {
  code: 'T6001' | 'T6002'
  message: string
  hint?: string
  
  files: string[]
}

RouteManifest

interface

Not documented yet.

export interface RouteManifest {
  
  routes: RouteRecord[]
  
  notFound?: { file: string }
  diagnostics: RouteDiagnostic[]
}

RouteMatch

interface

Not documented yet.

export interface RouteMatch<T extends { segments: Segment[] }> {
  route: T
  params: Record<string, string>
}

RoutePattern

type

One of the app's route patterns, such as /blog/:slug; any string until the build has generated them.

export type RoutePattern = keyof RouteTypes extends never
  ? string
  : Extract<keyof RouteTypes, string>

Router

class

The router: matches the address to a page, loads it, shows it, keeps the address bar and history in sync, and looks after what a screen reader and keyboard user need on each navigation (a new title, an announcement, focus on the new page, scroll position). History API only: no hash mode.

class Router {}

RouteRecord

interface

Not documented yet.

export interface RouteRecord {
  
  path: string
  
  file: string
  segments: Segment[]
  params: string[]
}

RouterOptions

interface

Not documented yet.

export interface RouterOptions {
  routes: RouteDefinition[]
  
  notFound?: () => Promise<PageModule>
  
  layouts?: Record<string, () => Promise<LayoutModule>>
  
  window?: Window
  
  announce?: boolean
}

routesFromModules

function

Build routes from import.meta.glob('./pages/**\/*.tess'), the way the generated route module does, so a test or a custom setup gets exactly the routes the build would.

function routesFromModules(modules: Record<string, () => Promise<unknown>>, pagesPrefix: string): { routes: RouteDefinition[]; notFound?: (() => Promise<PageModule>) | undefined; }

RouteState

interface

The current location, read reactively: reading a property inside an effect or derived() subscribes to it.

export interface RouteState {
  readonly path: string
  readonly params: Record<string, string>
  readonly query: Record<string, string>
  readonly hash: string
}

RouteTypes

interface

The app's routes by pattern, with their parameters. Empty here; the build fills it in (.tessera/routes.d.ts) so RoutePattern lists the real routes.

export interface RouteTypes {}

Segment

type

Turning a folder of pages into routes, and matching a path against them. Pure and dependency-free, so the compiler, the dev server and the browser runtime all use the same rules.

export type Segment = { kind: 'static'; value: string } | { kind: 'param'; name: string }

shouldHandleClick

function

Should a click on a link be handled by the router? Not when the user meant something else: another mouse button, a modifier key (new tab or window), a download, or a target other than this window.

function shouldHandleClick(event: { defaultPrevented?: boolean | undefined; button?: number | undefined; metaKey?: boolean | undefined; ctrlKey?: boolean | undefined; shiftKey?: boolean | undefined; altKey?: boolean | undefined; currentTarget?: unknown; }): boolean

splitTarget

function

Parse the path, query and hash of a link target, such as /blog/hello?draft=1#top.

function splitTarget(to: string): { path: string; query: string; hash: string; }

useRoute

function

The current route, for pages and components: route.path, route.params.slug, route.query.

function useRoute(): RouteState