### Installing and Configuring Crossroad in React

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This section covers the installation of the Crossroad library using npm and provides a minimal example of how to import and use its core components, Router, Switch, and Route, to define simple routes for a React application.

```javascript
npm i crossroad
```

```javascript
import Router, { Switch, Route } from "crossroad";

export default function App() {
  return (
    <Router>
      <Switch>
        <Route path="/" component={Home} />
        <Route path="/users/:id" component={Profile} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Query Parameter Matching Examples

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how the Route component can match based on the presence and values of query parameters in the URL. It includes examples of matching specific query keys and values, as well as wildcard usage with query parameters.

```javascript
// In /profile?page=settings&filter=abc

// All of these match the current route
<Route path="/profile" component={User} />
<Route path="/profile?page" component={User} />
<Route path="/profile?page=settings" component={User} />
<Route path="/profile/*?page=settings" component={User} />
<Route path="/:id?page=settings" component={User} />
<Route path="/:id/*?page=settings" component={User} />

// These shall not match:
<Route path="/?page" component={User} />  // Wrong path
<Route path="/profile?page2" component={User} />  // Wrong key
<Route path="/profile?page=options" component={User} />  // Wrong value
```

--------------------------------

### React Router Import Examples (for comparison)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

These examples demonstrate various ways to import components from 'react-router' and 'react-router-dom'. The documentation uses these to illustrate the complexity and potential confusion in React Router's import statements.

```javascript
import { Switch, Route, ... } from 'react-router';
import Router from 'react-router-dom';


import Router, { Switch, Route, ... } from 'react-router-dom';

import { Switch, Route, ... } from 'react-router';
import { BrowserRouter } from 'react-router-dom';
```

--------------------------------

### Crossroad Import Example

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This code snippet shows the recommended way to import components from the 'crossroad' library. It highlights a more intuitive and concise import syntax compared to React Router.

```javascript
import Router, { Switch, Route, ... } from 'crossroad';
```

--------------------------------

### Link Behavior Examples with Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Provides various examples of anchor tag usage with Crossroad, illustrating different navigation behaviors such as in-app navigation, external links, and targeted tab opening (`_self`, `_blank`).

```jsx
// In https://example.com/users/25

// React navigation:
<a href="/">Home</a>

// React navigation:
<a href="/users?filter=new">New users</a>

// Page refresh (since it's a full URL)
<a href="https://google.com/">Google it</a>

// Page refresh (a full URL, even in the same domain)
<a href="https://example.com/">Home</a>

// Page refresh (it has a target="_self")
<a href="/update" target="_self">Update</a>

// New tab (it has a target="_blank")
<a href="/terms-of-service" target="_blank">Read terms of service</a>
```

--------------------------------

### Crossroad Router Basic App Example (JavaScript)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

A simple React application example using the Crossroad routing library. It defines routes for Home, Users, and a NotFound component, showcasing how to pass a 'url' prop to the Router for testing purposes.

```javascript
// App.js
import Router, { Switch, Route } from "crossroad";

// Imagine these are your apps and components:
const Home = () => <div>Home</div>;
const Users = () => <div>Users</div>;
const NotFound = () => <div>Website not found</div>;

export default function App({ url }) {
  return (
    <Router url={url}>
      <Switch>
        <Route path="/" component={Home} />
        <Route path="/users" component={Users} />
        <Route component={NotFound} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Adding Navigation Links and Route Components in Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This example illustrates how to integrate navigation links with anchor tags and define specific page components for different routes using Crossroad's Route component. It shows a more complete setup with home and user profile routes.

```javascript
import Router, { Switch, Route } from "crossroad";

const Home = () => <main>Home Page</main>;
const Profile = ({ id }) => <main>Hello {id.toUpperCase()}</main>;

export default function App() {
  return (
    <Router>
      <nav>
        <a href="/">Home</a>
        <a href="/users/a">User A</a>
        <a href="/users/b">User B</a>
      </nav>
      <Switch>
        <Route path="/" component={Home} />
        <Route path="/users/:id" component={Profile} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Basic React Router Setup with Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/assets/home.html

This snippet demonstrates the fundamental setup of the Crossroad router. It utilizes Switch and Route components to define navigation paths and associate them with specific components. The main Router component wraps the entire routing structure.

```javascript
import Router, { Switch, Route } from "crossroad";

export default () => (
  <Router>
    <Switch redirect="/">
      <Route path="/" component={Home} />
      <Route path="/users" component={Users} />
      <Route path="/users/:id" component={Profile} />
    </Switch>
  </Router>
);
```

--------------------------------

### Link Navigation in React Router (for comparison)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Shows examples of how links are handled in React Router, highlighting the inconsistencies that Crossroad aims to resolve. This includes using both `<Link>` and `<a>` components for different navigation scenarios.

```html
// React Router

// Normal link
<Link to="/">Hello</Link>

// Open in same page with refresh
<a href="https://example.com/">Hello</Link>
<a href="/">Hello</Link>

// Open in new page
<a href="https://example.com/" target="_blank">Hello</Link>
<Link to="https://example.com/">Hello</Link>  // Broken
```

--------------------------------

### Router Component Setup with Navigation

Source: https://context7.com/franciscop/crossroad/llms.txt

The Router component wraps the application, managing navigation state and history. It intercepts click events on anchor tags for internal routing. This example demonstrates basic navigation to Home, Users, and a specific User Profile.

```javascript
import Router, { Switch, Route } from "crossroad";

const Home = () => <div>Welcome Home</div>;
const Users = () => <div>User List</div>;
const Profile = ({ id }) => <div>User Profile: {id}</div>;

export default function App() {
  return (
    <Router scrollUp>
      <nav>
        <a href="/">Home</a>
        <a href="/users">Users</a>
        <a href="/users/25">User 25</a>
      </nav>

      <Switch redirect="/">
        <Route path="/" component={Home} />
        <Route path="/users" component={Users} />
        <Route path="/users/:id" component={Profile} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Crossroad App: Routing and Navigation Example (JavaScript/React)

Source: https://context7.com/franciscop/crossroad/llms.txt

This JavaScript code defines a complete React application using the Crossroad routing library. It demonstrates setting up routes for home, search with query parameters, category listings with dynamic segments, item details, and a 404 fallback. It utilizes Crossroad's `Router`, `Switch`, `Route`, `useQuery`, `useParams`, and `usePath` hooks for declarative and programmatic navigation.

```javascript
import Router, { Switch, Route, useQuery, useParams, usePath } from "crossroad";
import { useState, useEffect } from "react";

// Home page component
const Home = () => (
  <div>
    <h1>Welcome to Our App</h1>
    <p>Navigate using the menu above</p>
  </div>
);

// Search page with query parameters
const Search = () => {
  const [query, setQuery] = useQuery();
  const [results, setResults] = useState([]);

  useEffect(() => {
    if (query.q) {
      // Simulate API call
      setResults([
        { id: 1, title: `Result for: ${query.q}` },
        { id: 2, title: `Another match for: ${query.q}` }
      ]);
    }
  }, [query.q]);

  const handleSearch = (e) => {
    e.preventDefault();
    setQuery({ q: e.target.search.value });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input name="search" defaultValue={query.q} />
        <button>Search</button>
      </form>

      {results.map(r => (
        <div key={r.id}>
          <a href={`/items/${r.id}`}>{r.title}</a>
        </div>
      ))}
    </div>
  );
};

// Category listing with pagination
const Category = ({ category, page }) => {
  const items = [`${category}-item-${page}-1`, `${category}-item-${page}-2`];

  return (
    <div>
      <h2>{category} - Page {page}</h2>
      <ul>
        {items.map(item => <li key={item}>{item}</li>)}
      </ul>
      <nav>
        {page > 1 && <a href={`/category/${category}/${page - 1}`}>Previous</a>}
        <a href={`/category/${category}/${page + 1}`}>Next</a>
      </nav>
    </div>
  );
};

// Item detail page
const ItemDetail = ({ id }) => {
  const [path, setPath] = usePath();

  const goBack = () => {
    setPath("/search");
  };

  return (
    <div>
      <button onClick={goBack}>← Back to Search</button>
      <h1>Item #{id}</h1>
      <p>Details for item {id}</p>
    </div>
  );
};

// 404 Not Found
const NotFound = () => (
  <div>
    <h1>404 - Page Not Found</h1>
    <a href="/">Go Home</a>
  </div>
);

// Main App
export default function App() {
  return (
    <Router scrollUp>
      <nav style={{ padding: "1rem", background: "#f0f0f0" }}>
        <a href="/" style={{ margin: "0 1rem" }}>Home</a>
        <a href="/search" style={{ margin: "0 1rem" }}>Search</a>
        <a href="/category/tech/1" style={{ margin: "0 1rem" }}>Tech</a>
        <a href="/category/books/1" style={{ margin: "0 1rem" }}>Books</a>
      </nav>

      <main style={{ padding: "2rem" }}>
        <Switch redirect="/">
          <Route path="/" component={Home} />
          <Route path="/search" component={Search} />
          <Route
            path="/category/:category/:page<number>"
            component={Category}
          />
          <Route path="/items/:id<number>" component={ItemDetail} />
          <Route component={NotFound} />
        </Switch>
      </main>
    </Router>
  );
}

```

--------------------------------

### Route Matching Examples with Path and Wildcard

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how the Route component matches different URL paths, including exact matches, partial matches using wildcards, and parameter-based routing. It shows when a component is rendered based on the current URL.

```javascript
/* In https://example.com/ */
<Route path="/" component={Home} /> // Rendered
<Route path="/*" component={Any} />  // Rendered
<Route path="/user" component={User} />  // Not rendered
<Route path="/:page" component={Page} />  // Not rendered

/* In https://example.com/user/ */
<Route path="/" component={Home} /> // Not Rendered
<Route path="/*" component={Any} />  // Rendered
<Route path="/user" component={User} />  // Rendered
<Route path="/:page" component={Page} />  // Rendered
```

--------------------------------

### Wildcard Path Matching Examples

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Shows various scenarios where a wildcard '*' at the end of a path prop enables partial route matching. This allows a route to match a segment of the URL, similar to a 'catch-all' route.

```javascript
// In https://example.com/user/abc

// All of these match the current route
<Route path="*" component={User} />
<Route path="/*" component={User} />
<Route path="/user/*" component={User} />
<Route path="/user/abc/*" component={User} />
<Route path="/user/:id/*" component={User} />
```

--------------------------------

### Basic React App Navigation Setup with Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This snippet demonstrates the fundamental structure for setting up navigation in a React application using Crossroad. It involves importing the Router, Switch, and Route components and defining basic navigation links using anchor tags.

```javascript
import Router, { Switch, Route } from "crossroad";

export default function App() {
  return (
    <Router>
      <nav>
        <a href="/">Home</a>
        <a href="/users">Users</a>
        ...
      </nav>
      <Switch redirect="/">
        <Route path="/" component={Home} />
        <Route path="/users" component={Users} />
        <Route path="/users/:id<number>" component={Profile} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Basic Router Setup

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

The top-level Router component must wrap all other components to manage clicks and history. It's the default export of the library and should be integrated within your main App component.

```javascript
import Router from "crossroad";

export default function App() {
  return <Router>... Your normal App code ...</Router>;
}
```

--------------------------------

### Router with Nested Routes and Switch

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This example demonstrates a common setup where the Router component wraps a Switch component, which in turn contains multiple Route components. This pattern is used to define different pages or views for specific URL paths in a React application.

```javascript
import Router, { Switch, Route } from "crossroad";

import Home from "./pages/Home";
import Dashboard from "./pages/Dashboard";
import Profile from "./pages/Profile";

export default function App() {
  return (
    <Router>
      <Switch>
        <Route path="/" component={Home} />
        <Route path="/dashboard" component={Dashboard} />
        <Route path="/:username" component={Profile} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Express Server-Side Rendering with Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This example illustrates how to integrate Crossroad for server-side rendering within an Express application. It shows how to render a React component (`App`) with a specified URL, enabling dynamic routing on the server. This is useful for pages like '/users' and '/users/:id'.

```javascript
// An express example
const App = ({ url }) => <Router url={url}>...</Router>;

app.get("/users", (req, res) => {
  res.render(<App url="/users" />);
});

app.get("/users/:id", (req, res) => {
  // {...} validate the `id` it here!

  res.render(<App url={req.url} />);
});

```

--------------------------------

### Updating URL with `useUrl` Setter

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Provides examples of how to use the `setUrl` function returned by the `useUrl` hook to navigate to new paths, modify query parameters, and add hashtags. Supports string or object-based updates.

```javascript
const [url, setUrl] = useUrl();

// [Shorthand] Redirect to home with a hashtag
setUrl("/#firsttime");

// Same as above, but specifying the parts
setUrl({ path: "/", hash: "firsttime" });

// Keep everything the same except the path
setUrl({ ...url, path: "/" });

// Set a full search query
setUrl({ ...url, query: { search: "hello" } });

// Modify only one query param
setUrl({ ...url, query: { ...url.query, safe: "no" } });
```

--------------------------------

### Switch with Route Prioritization and 404 Handling

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

The Switch component renders only the first matching Route. This example shows how to handle specific routes before a more general one (like '/:username') and how to define a fallback route for unmatched URLs using a component without a path attribute.

```javascript
// In https://example.com/help, it'll render the Help component only
<Switch>
  <Route path="/help" component={Help} />
  <Route path="/:username" component={User} />
</Switch>
```

```javascript
<Switch>
  <Route path="/path1" component={Comp1} />
  <Route path="/path2" component={Comp2} />
  <Route component={NotFound} />
</Switch>
```

--------------------------------

### Query Routing for Subpages and Tabs in React (JS)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Shows how to define the current page using query parameters instead of the pathname, suitable for subpages or tabs. It includes examples for redirecting to a default home page if no match is found and for handling specific tabs within a dashboard.

```js
<Switch redirect="/?page=home">
  <Route path="/?page=home" component={Tabs.Home} />
  <Route path="/?page=product" component={Tabs.Product} />
  <Route path="/?page=about" component={Tabs.About} />
</Switch>
```

```js
<Switch redirect="/dashboard?tab=home">
  <Route path="/dashboard?tab=home" component={Tabs.Home} />
  <Route path="/dashboard?tab=product" component={Tabs.Product} />
  <Route path="/dashboard?tab=about" component={Tabs.About} />
</Switch>
```

--------------------------------

### Type Conversion for Route Parameters

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates the Route component's ability to attempt type conversion for matched path parameters. It shows examples of converting to 'number' and 'date' types, noting that it does not perform validation.

```javascript
<Route path="/user/:id<number>" render={({ id }) => {
  console.log(id, typeof id);  // 25 number
}} />;

<Route path="/metrics/:time<date>" render={({ time }) => {
  console.log(time, typeof time);  // Jan 25th, 2055 Date
}} />;
```

--------------------------------

### Accessing URL Parts with `useUrl`

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates how to access the different components of the URL (path, query, hash) provided by the `useUrl` hook. It also explains memoization for performance.

```javascript
// In /whatever?filter=hello#world
const [url, setUrl] = useUrl();
console.log(url.path); // /whatever
console.log(url.query); // { filter: hello }
console.log(url.hash); // world
```

--------------------------------

### Define Static Routes with Crossroad Router

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Sets up static routes for a company website, mapping URL paths to corresponding React components. It uses the `Router`, `Switch`, and `Route` components from the 'crossroad' library. Navigation is handled via standard `<a>` tags.

```javascript
import Router, { Switch, Route } from "crossroad";

import Nav from "./Nav";
import Pages from "./Pages";

export default function App() {
  return (
    <Router>
      <Nav />
      <Switch redirect="/">
        <Route path="/" component={Pages.Home} />
        <Route path="/about" component={Pages.AboutUs} />
        <Route path="/product1" component={Pages.MainProduct} />
        <Route path="/product2" component={Pages.AnotherProduct} />
      </Switch>
    </Router>
  );
}
```

```javascript
export default function Nav() {
  return (
    <nav>
      <a href="/">Home</a>
      <a href="/about">About Us</a>
      <a href="/product1">Product 1</a>
      <a href="/product2">Product 2</a>
      <a href="/license.pdf" target="_blank">
        License
      </a>
    </nav>
  );
}
```

--------------------------------

### Flexible URL and Query Manipulation with Crossroad Hooks

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates the flexibility of the setUrl() function for various URL manipulation tasks, including setting hash, modifying paths, and updating query parameters. Also shows how to use useQuery() to manage query parameters, either the entire object or specific parameters.

```javascript
// setUrl() is quite flexible:
const [url, setUrl] = useUrl();

setUrl("/#firsttime"); // [Shorthand] Redirect to home with a hashtag
setUrl({ path: "/", hash: "firsttime" }); // Same as above
setUrl({ ...url, path: "/" }); // Keep everything the same except the path
setUrl({ ...url, query: { search: myQuery } }); // Set a full search query
setUrl({ ...url, query: { ...url.query, safe: 0 } }); // Modify only one query param
```

```javascript
// In /?search=myname&filter=new

// Manipulate the whole query object
const [query, setQuery] = useQuery();
setQuery({ ...query, search: "myname2" });

// Manipulate _only_ the query parameter "search"
const [search, setSearch] = useQuery("search");
setSearch("myname2");
```

--------------------------------

### Basic Navigation Links in React

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how to use standard anchor tags (`<a>`) for navigation within a React application using Crossroad. Crossroad intercepts these links to handle client-side routing.

```jsx
export default () => (
  <nav>
    <a href="/">Home</a>
    <a href="/users">Users</a>
    <a href="/settings">Settings</a>
  </nav>
);
```

--------------------------------

### Core Components

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Crossroad offers essential components for routing and navigation, inspired by React Router.

```APIDOC
## Router Component

### Description
The `<Router />` component is the top-level component that should wrap your entire application to enable routing.

### Method
Component

### Endpoint
N/A

### Parameters
#### Props
- **scrollUp** (boolean) - Optional - If true, automatically scrolls to the top on route change.

### Request Example
```jsx
import Router from "crossroad";

function App() {
  return (
    <Router scrollUp={true}>
      {/* Your app content and routes */}
    </Router>
  );
}
```

### Response
N/A

## Switch Component

### Description
The `<Switch />` component renders only the first child `<Route />` that matches the current URL. It's useful for grouping routes and providing a default redirect.

### Method
Component

### Endpoint
N/A

### Parameters
#### Props
- **redirect** (string) - Optional - Sets a default path to redirect to if no other routes match.

### Request Example
```jsx
import { Switch, Route } from "crossroad";

<Switch redirect="/home">
  <Route path="/" component={HomePage} />
  <Route path="/about" component={AboutPage} />
</Switch>
```

### Response
N/A

## Route Component

### Description
The `<Route />` component filters whether its child component should be rendered based on the current URL. It supports exact path matching and query parameter matching by default.

### Method
Component

### Endpoint
N/A

### Parameters
#### Props
- **path** (string) - Required - The path to match against the current URL. Can include path parameters (e.g., `/users/:id`).
- **component** (ReactComponent) - Required - The component to render when the path matches.

### Request Example
```jsx
import { Route } from "crossroad";

<Route path="/users/:id" component={UserProfile} />
```

### Response
N/A
```

--------------------------------

### Extract Route Parameters with useParams Hook (React)

Source: https://context7.com/franciscop/crossroad/llms.txt

The useParams hook from 'crossroad' extracts typed route parameters from a Route component's path pattern. It can be used to get specific parameters by name or all parameters as an object. This hook is essential for dynamic routing where parts of the URL define the content. Ensure the Router and Route components are correctly configured.

```javascript
import Router, { Switch, Route, useParams } from "crossroad";

// Method 1: Receive params as props (recommended for simple cases)
const UserProfile = ({ username }) => {
  return <div>Profile for @{username}</div>;
};

// Method 2: Use hook with specific key
const BookDetails = () => {
  const userId = useParams("userId");
  const bookId = useParams("bookId");

  return (
    <div>
      <p>User: {userId}</p>
      <p>Book: {bookId}</p>
    </div>
  );
};

// Method 3: Use hook to get all params
const ProductView = () => {
  const params = useParams();

  return (
    <div>
      <p>Category: {params.category}</p>
      <p>Product ID: {params.id}</p>
      <p>Variant: {params.variant || "default"}</p>
    </div>
  );
};

// Method 4: Typed params with number conversion
const MetricsDashboard = () => {
  const year = useParams("year");  // Will be a number
  const month = useParams("month"); // Will be a number

  return (
    <div>
      <p>Showing data for {month}/{year}</p>
      <p>Year type: {typeof year}</p>
    </div>
  );
};

export default function App() {
  return (
    <Router>
      <Switch>
        <Route path="/:username" component={UserProfile} />

        <Route
          path="/users/:userId/books/:bookId"
          component={BookDetails}
        />

        <Route
          path="/shop/:category/:id/:variant?"
          component={ProductView}
        />

        <Route
          path="/metrics/:year<number>/:month<number>"
          component={MetricsDashboard}
        />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Manage Search State with useQuery Hook

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Integrates search functionality by storing state variables (like 'place' and 'max' budget) directly in the URL's query parameters. The `useQuery` hook from 'crossroad' provides a state-like interface, simplifying management of URL-based search criteria.

```javascript
import { useQuery } from "crossroad";

export default function SearchForm() {
  const [place, setPlace] = useQuery("place");
  const [max, setMax] = useQuery("max");

  return (
    <form>
      <TextInput value={place} onChange={setPlace} ... />
      <NumberInput value={max} onChange={setMax} ... />
    </form>
  );
}
```

--------------------------------

### URL Navigation without Dependencies using `useUrl` Setter Callback

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates an advanced usage of the `useUrl` setter where a callback function is used to update the URL, allowing the `useEffect` hook to run without dependencies, thus preventing unnecessary re-renders.

```javascript
const [url, setUrl] = useUrl();
useEffect(() => {
  setUrl((old) => {
    if (old.path === "/base") return "/base/deeper";
    return old;
  });
}, []);
```

--------------------------------

### Manage URL Hash with useHash (JavaScript)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Explains how to read and set the hash part of a URL using the `useHash` hook. It also shows how to control browser history, allowing for new entries or replacing the current one, and how to remove the hash.

```javascript
// In /login#welcome
const [hash, setHash] = useHash();
// welcome

setHash("bye");
// Goto /login#bye

setHash("newhash"); // Default: "push"
setHash("newhash", { mode: "replace" });

// To remove hash:
setHash(null);
```

--------------------------------

### Plain Links with Crossroad

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how to use native anchor `<a>` elements for navigation in Crossroad. This approach is consistent and straightforward, unlike some React Router implementations that mix `<Link>` and `<a>`.

```html
// Crossroad

// Normal link
<a href="/">Hello</a>

// Open in same page with refresh
<a href="https://example.com/">Hello</a> // http(s): links open with refresh
<a href="/" target="_self">Hello</a>  // self to open with refresh

// Open in new page
<a href="/myfile.pdf" target="_blank">Hello</a>  // Traditional target blank
<a href="https://example.com/" target="_blank">Hello</a>
```

--------------------------------

### Conditional Navigation with `useEffect` and `useUrl`

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how to perform navigation based on URL changes using `useEffect` in conjunction with the `useUrl` hook. It shows how to watch for specific URL parts like `url.path`.

```javascript
const [url, setUrl] = useUrl();
useEffect(() => {
  if (url.path === "/base") {
    setUrl("/base/deeper");
  }
}, [url.path, setUrl]);
```

--------------------------------

### Testing React App Navigation with Mocked Location

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This code demonstrates how to use the Mock component to test different routes within a React application using Jest. It wraps the main App component with the Mock component, providing different URLs to simulate navigation and asserts the rendered text for each route.

```javascript
import React from "react";
import $ from "react-test";

import App from "./App";
import Mock from "./Mock";

describe("use the Mock component", () => {
  it("renders the home component on /", () => {
    const $home = $(
      <Mock url="/">
        <App />
      </Mock>
    );
    expect($home.text()).toBe("Home");
  });

  it("renders the user list on /users", () => {
    const $home = $(
      <Mock url="/users">
        <App />
      </Mock>
    );
    expect($home.text()).toBe("Users");
  });

  it("renders not found when in another route", () => {
    const $home = $(
      <Mock url="/bla">
        <App />
      </Mock>
    );
    expect($home.text()).toContain("not found");
  });
});
```

--------------------------------

### Handling 'Not Found' Routes in React (JS)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates how to implement a 'not found' page using the Crossroad routing library. It demonstrates a general 'not found' handler by omitting the 'path' prop, as well as specific 'not found' pages for different sections of an application, emphasizing the importance of route order.

```js
<Switch>
  <Route path="/" component={Home} />
  <Route path="/users" component={Users} />

  {/* Not found page */}
  <Route component={NotFound} />
</Switch>
```

```js
<Switch>
  <Route path="/" component={Home} />
  <Route path="/docs/abc" component={DocsAbc} />
  <Route path="/docs/def" component={DocsDef} />

  {/* Not found page only for the docs */}
  <Route path="/docs/*" component={NotFoundDocs} />

  {/* Not found page only for everything else */}
  <Route component={NotFound} />
</Switch>
```

--------------------------------

### URL Handling with `useUrl` Hook in React

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Shows how to use the `useUrl` hook from Crossroad to read and update the current URL, including path, query parameters, and hash. It utilizes React's hook pattern for state management.

```jsx
import { useUrl } from "crossroad";

export default function Login() {
  const [url, setUrl] = useUrl();

  const login = async () => {
    // ... do some stuff ...
    setUrl("/welcome");
  };

  return <Button onClick={login}>Login</Button>;
}
```

--------------------------------

### Manage Browser History with setQuery (JavaScript)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how to set query parameters in the URL and control browser history behavior. `setQuery` can either push a new history entry or replace the current one. This is useful for state management in single-page applications.

```javascript
setQuery({ search: "abc" }); // Default: "push"
setQuery({ search: "abc" }, { mode: "replace" });
```

--------------------------------

### Set URL using useUrl Hook

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates how to use the useUrl hook and its setter setUrl() to navigate to different paths. This hook replaces the imperative history prop found in React Router, simplifying URL management.

```javascript
import { useUrl } from "crossroad";

export default function LoginButton() {
  const [url, setUrl] = useUrl();
  const login = async (e) => {
    // ... login logic
    setUrl("/welcome");
  };
  return <button onClick={login}>Login</button>;
}
```

--------------------------------

### Dynamic Pagination with Path Parameters in React (TSX)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Demonstrates dynamic pagination by using path parameters with mixed types to track the current page in the URL. This enables bookmarkable, dynamic list navigation where clicking 'Previous' or 'Next' updates the page number.

```tsx
import Router, { Switch, Route, useQuery, useParams } from "crossroad";

const Category = ({ category, page }) => {
  const posts = fetchPosts(category, page); // Simulated API call

  return (
    <div>
      <h1>{category} Posts - Page {page}</h1>
      <ul>{posts.map(post => <li key={post.id}>{post.title}</li>)}</ul>
      <nav>
        {page > 1 ? (
          <a href={`/${category}/${page - 1}`}>Previous</a>
        ) : 'Previous'}
        <a href={`/${category}/${page + 1}`}>Next</a>
      </nav>
    </div>
  );
};

export default function App() {
  return (
    <Router>
      <nav>
        <a href="/tech/1">Tech</a>
        <a href="/lifestyle/1">Lifestyle</a>
      </nav>
      <Switch>
        <Route path="/:category/:page<number>" component={Category} />
        <Route path="/" component={() => <div>Home</div>} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### Handle Vanity URLs with Dynamic Parameters

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Emulates vanity URLs (e.g., Twitter profiles) by defining a wildcard route for usernames. It ensures company-specific routes are defined before the wildcard route to prevent conflicts. Parameters can be accessed via props or the `useParams` hook.

```javascript
<Switch>
  <Route path="/" component={Home} />
  <Route path="/home" component={Home} />
  <Route path="/explore" component={Explore} />

  <Route path="/:username" component={Profile} />
</Switch>
```

```javascript
function Profile({ username }) {
  return <div>Hello {username}</div>;
}
```

```javascript
import { useParams } from "crossroad";

function Profile() {
  const { username } = useParams("/:username");
  return <div>Hello {username}</div>;
}
```

```javascript
import { useParams } from "crossroad";

function Profile() {
  const { username } = useParams();
  return <div>Hello {username}</div>;
}
```

--------------------------------

### Github Pages Redirect Workaround (HTML)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This HTML snippet demonstrates a workaround for Github Pages' lack of generic redirect support. It saves the current URL to localStorage and redirects to the root, allowing for dynamic route restoration in JavaScript.

```html
<!-- 404.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Redirecting...</title>
  </head>
  <body>
    <script>
      const url = JSON.stringify(location.pathname + location.search);
      localStorage.url = url;
      location.replace("/");
    </script>
  </body>
</html>
```

--------------------------------

### Importing Crossroad API Components and Hooks

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This snippet shows the import statement for accessing various components and hooks provided by the Crossroad library. It includes the main Router, Switch, Route components, as well as hooks like useUrl and usePath.

```javascript
import Router, { Switch, Route, useUrl, usePath } from "crossroad";
```

--------------------------------

### Route Parameter Handling with Component and Render Props

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Illustrates how route parameters, defined with a colon (e.g., ':id'), are passed as props to the rendered component or available in the render function. It shows how to handle typed parameters like '<number>'.

```javascript
// In https://example.com/user/25
const User = ({ id }) => <div>Hello {id} ({typeof id})</div>;
const UserList = () => <div>List here</div>;

<Route path="/user/:id" component={User} />;
// <div>Hello 25 (string)</div>

<Route path="/user/:id<number>" component={User} />;
// <div>Hello 25 (number)</div>

<Route path="/user/:id" render={({ id }) => <User id={id} />} />;
// <div>Hello 25 (string)</div>

<Route path="/user/:id<number>" render={({ id }) => <User id={id} />} />;
// <div>Hello 25 (number)</div>

// Avoid when you need the params, since they cannot be passed easily
<Route path="/user/">
  <UserList />
</Route>;
// <div>List here</div>
```

--------------------------------

### Use Query Hook for URL Query Parameters (React)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

Details the `useQuery` hook for managing URL query parameters. It allows reading and setting specific query parameters or the entire query object. When updating, it's important to manage existing parameters to avoid unintended data loss. It also supports aliasing the import.

```javascript
import { useQuery } from "crossroad";

export default function SearchInput() {
  // In /users?search=
  const [query, setQuery] = useQuery();
  // [{ search: "" }, fn]

  // Goes to /users?search={value}
  const onChange = (e) => setQuery({ search: e.target.value });

  return <input value={query.search} onChange={onChange} />;
}

// In /users?search=name&filter=new
const [search, setSearch] = useQuery("search");
// 'name'

setSearch("myname");
// Goto /users?search=myname&filter=new

// In /users?search=name&filter=new
const [query, setQuery] = useQuery();

setQuery({ search: "myname" });
// Goto /users?search=myname  (removes the filter)

setQuery({ ...query, search: "myname" });
// Goto /users?search=myname&filter=new

setQuery((prev) => ({ ...prev, search: "myname" }));
// Goto /users?search=myname&filter=new

const [myname, setMyname] = useQuery("myname");

// ...

setMyname(newName || null);

import { useQuery as useSearch } from 'crossroad';
...
```

--------------------------------

### Crossroad Router Testing with URL Prop (JavaScript)

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This JavaScript code provides unit tests for the Crossroad Router component using a testing library (likely Jest with a DOM simulator like JSDOM, implied by '$'). It verifies that the correct components are rendered based on the 'url' prop passed to the App component.

```javascript
// App.test.js
import React from "react";
import $ from "react-test";

import App from "./App";

describe("use the url prop", () => {
  it("renders the home component on /", () => {
    const $home = $(<App url="/" />);
    expect($home.text()).toBe("Home");
  });

  it("renders the user list on /users", () => {
    const $home = $(<App url="/users" />);
    expect($home.text()).toBe("Users");
  });

  it("renders not found when in another route", () => {
    const $home = $(<App url="/bla" />);
    expect($home.text()).toContain("not found");
  });
});
```

--------------------------------

### Mock window.location in React for Jest Tests

Source: https://github.com/franciscop/crossroad/blob/master/readme.md

This component mocks the global window.location object to control the URL during Jest tests. It sets up a new location based on the provided URL prop and restores the original location when the component unmounts. This allows for testing navigation within an application.

```javascript
import React, { useEffect } from "react";

export default function Mock({ url, children }) {
  const href = "http://localhost:3000" + url;
  const oldLocation = { value: window.location };
  delete global.window.location;
  Object.defineProperty(global.window, "location", {
    value: new URL(href),
    configurable: true,
  });

  // Undo the setup when the component unmounts
  useEffect(() => {
    return () => Object.defineProperty(window, "location", oldLocation);
  }, []);
  return <div>{children}</div>;
}
```

--------------------------------

### Route Component with Query Parameters

Source: https://context7.com/franciscop/crossroad/llms.txt

Routes can be matched based on query string parameters in the URL. This allows for dynamic content loading or state management based on URL parameters. The `redirect` prop on Switch can ensure a default query state.

```javascript
import Router, { Switch, Route } from "crossroad";

const HomeTab = () => <div>Home Tab Content</div>;
const SettingsTab = () => <div>Settings Tab Content</div>;
const ProfileTab = () => <div>Profile Tab Content</div>;

export default function Dashboard() {
  return (
    <Router>
      <nav>
        <a href="/dashboard?tab=home">Home</a>
        <a href="/dashboard?tab=settings">Settings</a>
        <a href="/dashboard?tab=profile">Profile</a>
      </nav>

      <Switch redirect="/dashboard?tab=home">
        <Route path="/dashboard?tab=home" component={HomeTab} />
        <Route path="/dashboard?tab=settings" component={SettingsTab} />
        <Route path="/dashboard?tab=profile" component={ProfileTab} />
      </Switch>
    </Router>
  );
}
```

--------------------------------

### useQuery Hook: Manage Full Query Object

Source: https://context7.com/franciscop/crossroad/llms.txt

This `useQuery` hook allows managing all URL query parameters as a single object. It's ideal for complex scenarios like search forms with multiple filters. Supports merging, clearing, and replacing the entire query object. Dependencies: 'crossroad'.

```javascript
import { useQuery } from "crossroad";

export default function SearchFilters() {
  const [query, setQuery] = useQuery();

  const handleSearch = (e) => {
    e.preventDefault();

    // Replace entire query object
    setQuery({
      search: e.target.search.value,
      category: e.target.category.value,
      sort: "recent"
    });
  };

  const addFilter = (filterKey, filterValue) => {
    // Merge with existing query params
    setQuery({ ...query, [filterKey]: filterValue });
  };

  const clearFilters = () => {
    // Callback style with previous query
    setQuery(prev => ({ search: prev.search })); // Keep only search
  };

  const replaceMode = () => {
    // Don't create new history entry
    setQuery({ search: "updated" }, { mode: "replace" });
  };

  return (
    <div>
      <form onSubmit={handleSearch}>
        <input name="search" defaultValue={query.search} />
        <select name="category" defaultValue={query.category}>
          <option value="all">All</option>
          <option value="books">Books</option>
        </select>
        <button type="submit">Search</button>
      </form>

      <p>Active Filters: {JSON.stringify(query)}</p>
      <button onClick={() => addFilter("verified", "true")}>
        Add Verified Filter
      </button>
      <button onClick={clearFilters}>Clear All Filters</button>
    </div>
  );
}
```

--------------------------------

### Manage URL Hash Fragment with useHash Hook (React)

Source: https://context7.com/franciscop/crossroad/llms.txt

The useHash hook from 'crossroad' allows reading and setting the URL's hash fragment. It's useful for anchor navigation and managing UI state without full page reloads. Dependencies include React. It takes no arguments and returns a stateful value and a function to update it. Limitations may include browser compatibility for hash manipulation.

```javascript
import { useHash } from "crossroad";
import { useEffect } from "react";

export default function TabController() {
  const [hash, setHash] = useHash();

  const activeTab = hash || "overview";

  // Smooth scroll to element on hash change
  useEffect(() => {
    if (hash) {
      const element = document.getElementById(hash);
      element?.scrollIntoView({ behavior: "smooth" });
    }
  }, [hash]);

  const switchTab = (tabName) => {
    setHash(tabName);
  };

  const removeHash = () => {
    setHash(null); // Remove hash from URL
  };

  const replaceHash = () => {
    // Don't create history entry
    setHash("settings", { mode: "replace" });
  };

  return (
    <div>
      <nav>
        <button
          onClick={() => switchTab("overview")}
          style={{ fontWeight: activeTab === "overview" ? "bold" : "normal" }}
        >
          Overview
        </button>
        <button
          onClick={() => switchTab("details")}
          style={{ fontWeight: activeTab === "details" ? "bold" : "normal" }}
        >
          Details
        </button>
        <button onClick={() => switchTab("settings")}>Settings</button>
      </nav>

      <section id="overview">Overview Content</section>
      <section id="details">Details Content</section>
      <section id="settings">Settings Content</section>

      <button onClick={removeHash}>Clear Hash</button>
    </div>
  );
}
```