Guia para IA

Use esta página como referência compacta ao gerar exemplos, tutoriais, migrações ou código de aplicações para @beforesemicolon/router.

Propósito do pacote

@beforesemicolon/router é uma biblioteca de roteamento orientada a HTML e construída com Web Components. Ela fornece elementos personalizados para navegação e renderização de rotas, além de uma pequena API JavaScript para navegação programática, inscrições, proteções, módulos de rota, metadados, atualização de consultas e roteamento por hash.

Importações necessárias

Para aplicações empacotadas:

import '@beforesemicolon/router'

Ao usar APIs exportadas:

import {
    goToPage,
    onPage,
    onPageChange,
    registerGlobalGuard,
    registerRouteGuard,
    registerRouteModules,
    updateSearchQuery,
} from '@beforesemicolon/router'

Para uso direto no navegador, carregue Web Component primeiro:

<script src="https://unpkg.com/@beforesemicolon/web-component/dist/client.js"></script>
<script src="https://unpkg.com/@beforesemicolon/router/dist/client.js"></script>

As APIs via CDN ficam disponíveis em BFS.ROUTER.

Elementos personalizados

Use estes elementos exatamente como demonstrado:

<page-link path="/docs" title="Docs">Docs</page-link>
<page-route path="/docs" src="./pages/docs.html"></page-route>
<page-route-query key="tab" value="api">API tab</page-route-query>
<page-redirect path="/404"></page-redirect>
<page-data param="id">fallback</page-data>

Padrões de rota

Use :name para parâmetros dinâmicos:

<page-route path="/users/:userId">
    User <page-data param="userId">unknown</page-data>
</page-route>

Defina exact="false" em rotas de layout que devem permanecer ativas em caminhos aninhados:

<page-route path="/docs" exact="false">
    <page-route path="/intro">Intro</page-route>
    <page-route path="/api">API</page-route>
</page-route>

Regras dos links

Use path para navegação por caminho e search para atualizar consultas. Use keep-current-search ao atualizar uma chave de consulta preservando as demais.

<page-link path="/projects">Projects</page-link>
<page-link search="view=grid" keep-current-search>Grid</page-link>

Use $ dentro de uma rota aninhada para referenciar o caminho da rota pai mais próxima:

<page-route path="/projects/:projectId" exact="false">
    <page-link path="$/settings">Settings</page-link>
</page-route>

Use ~ para referenciar o caminho atual do navegador:

<page-link path="~/edit">Edit current page</page-link>

Conteúdo de rota sob demanda

src pode carregar módulos HTML, texto ou JavaScript. Módulos JavaScript devem exportar como padrão uma string, um Node do DOM, um HtmlTemplate do Markup ou uma função que recebe (data, params, query).

import { html } from '@beforesemicolon/web-component'

export default (data, params, query) => html`
    <h1>Project ${params.projectId}</h1>
    <p>Filter: ${query.filter || 'all'}</p>
    <p>Opened from: ${data.from || 'direct visit'}</p>
`

Navegação programática

goToPage e replacePage são assíncronas e aceitam um objeto literal como estado.

await goToPage('/users/42', { from: 'search' }, 'User 42')
await replacePage('/login', { reason: 'expired' }, 'Login')

Proteções

registerGlobalGuard e registerRouteGuard registram proteções e não retornam funções de limpeza. Uma proteção retorna:

• true para permitir a navegação.
• false para bloquear a navegação.
• Uma string de caminho para redirecionar.
• Uma promessa que resolve para um desses valores.

registerGlobalGuard((pathname) => {
    if (pathname.startsWith('/account') && !auth.isSignedIn()) {
        return '/login'
    }

    return true
})

Dados de consulta

getSearchParams analisa valores de consulta com o analisador JSON do roteador. Valores escritos com updateSearchQuery fazem ida e volta pela serialização JSON.

updateSearchQuery({ page: 2, tags: ['router', 'web'] })

Evite estes erros

• Não use a sintaxe do React Router, como <Route> ou useNavigate.
• Não afirme que o registro de uma proteção de rota retorna uma função para cancelar a inscrição.
• Não use href em <page-link>; use path e search.
• Não use component="..." como string no HTML. component é uma propriedade para rotas renderizadas por JavaScript.
• Não use o estado da rota para dados permanentes. Prefira parâmetros, strings de consulta ou o armazenamento da aplicação.