@avstantso/react-router-utils 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.1] - 2026-02-05
+
+### Fixed
+
+- Excluded leaked dependency declarations (`_global/`, `_std-ext/`, `export.d.ts`) from build output
+
+## [0.1.0] - 2026-04-02
+
+### Changed
+
+- Initial release

package/README.md

@@ -0,0 +1,466 @@
+# @avstantso/react-router-utils
+
+[![npm version](https://img.shields.io/npm/v/@avstantso/react-router-utils.svg)](https://www.npmjs.com/package/@avstantso/react-router-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Type-safe `react-router-dom` enhancement package that generates pre-bound route components, navigation utilities, and URL matchers from a declarative URL tree.
+
+## Features
+
+- **Pre-bound Link trees** - `<Link>` and `<NavLink>` components bound to specific routes with automatic `href` resolution
+- **Navigate trees** - `<Navigate>` components and `useNavigate` hook proxy bound to routes
+- **URL matching** - Type-safe `isUrl` / `isSubUrl` functions for pathname comparison
+- **Route creator** - Factory for building `RouteObject` definitions from the URL tree
+- **Dynamic params** - Full support for parameterized routes (`:userId`) with type-safe `params` props
+- **Preserve option** - Navigate components can preserve `search` and `hash` from the current location
+- **Auto-generated IDs** - Link components receive HTML-safe `id` attributes derived from route paths
+
+## Installation
+
+```bash
+npm install @avstantso/react-router-utils
+```
+
+or
+
+```bash
+yarn add @avstantso/react-router-utils
+```
+
+## Peer Dependencies
+
+- `react` >= 18.0
+- `react-dom` >= 18.0
+- `react-router-dom` >= 7.0
+
+## Quick Start
+
+### 1. Define your URL tree
+
+```typescript
+import { NamesTree } from '@avstantso/utils-names-tree';
+
+const UrlsSource = {
+  profile: {
+    settings: 1,
+    ':userId': {
+      posts: 1
+    }
+  },
+  about: 1
+} as const;
+
+const urlsTree = NamesTree.Urls(UrlsSource, { rootAlias: 'Home' } as const);
+```
+
+### 2. Create route utilities
+
+```typescript
+import { ReactRouterTree } from '@avstantso/react-router-utils';
+
+const { Links, NavLinks, Navigates, isUrl, isSubUrl, RouteCreator } = ReactRouterTree(urlsTree);
+```
+
+### 3. Use in your app
+
+```tsx
+function App() {
+  return (
+    <nav>
+      <Links.Home>Home</Links.Home>
+      <Links.Profile.Settings>Settings</Links.Profile.Settings>
+      <Links.Profile.$UserId params={{ userId: '42' }}>User Profile</Links.Profile.$UserId>
+      <Links.About>About</Links.About>
+    </nav>
+  );
+}
+```
+
+## Table of Contents
+
+- [ReactRouterTree](#reactroutertree)
+- [Links & NavLinks](#links--navlinks)
+- [Navigates](#navigates)
+  - [Navigate Components](#navigate-components)
+  - [useNavigate Hook](#usenavigate-hook)
+- [isUrl & isSubUrl](#isurl--issuburl)
+- [RouteCreator](#routecreator)
+
+---
+
+## ReactRouterTree
+
+Main factory function that generates all route utilities from a URL tree.
+
+```typescript
+import { ReactRouterTree } from '@avstantso/react-router-utils';
+
+const {
+  Links,        // Tree of <Link> components
+  NavLinks,     // Tree of <NavLink> components
+  Navigates,    // Tree of <Navigate> components + useNavigate hook
+  isUrl,        // Strict URL matching functions
+  isSubUrl,     // Prefix URL matching functions
+  RouteCreator  // Route object factory
+} = ReactRouterTree(urlsTree);
+```
+
+### Tree Key Naming
+
+Route keys are transformed to PascalCase. Dynamic parameters (`:param`) are prefixed with `$` and converted to PascalCase:
+
+| URL Tree Key | Generated Key |
+|-------------|---------------|
+| `profile` | `Profile` |
+| `settings` | `Settings` |
+| `:userId` | `$UserId` |
+| `:post-id` | `$PostId` |
+| `rootAlias: 'Home'` | `Home` |
+
+---
+
+## Links & NavLinks
+
+Pre-bound `<Link>` and `<NavLink>` components from `react-router-dom`, organized as a tree matching your URL structure. Each link component has its `to` prop pre-set to the corresponding route path.
+
+### Static Routes
+
+```tsx
+import { ReactRouterTree } from '@avstantso/react-router-utils';
+
+const { Links, NavLinks } = ReactRouterTree(urlsTree);
+
+// Renders <a href="/about">About</a>
+<Links.About>About</Links.About>
+
+// Renders <a href="/profile/settings">Settings</a>
+<Links.Profile.Settings>Go to settings</Links.Profile.Settings>
+
+// NavLink with active class support
+<NavLinks.About>About</NavLinks.About>
+```
+
+### Parameterized Routes
+
+Pass `params` prop to resolve dynamic segments:
+
+```tsx
+// Renders <a href="/profile/42">User</a>
+<Links.Profile.$UserId params={{ userId: '42' }}>User</Links.Profile.$UserId>
+
+// Renders <a href="/profile/99/posts">Posts</a>
+<Links.Profile.$UserId.Posts params={{ userId: '99' }}>Posts</Links.Profile.$UserId.Posts>
+
+// Unresolved params are kept as-is
+<Links.Profile.$UserId params={{}}>User</Links.Profile.$UserId>
+// Renders <a href="/profile/:userId">User</a>
+```
+
+### Additional Props
+
+Links accept all standard `Link`/`NavLink` props except `to` (which is pre-bound). You can pass `search` and `hash` via the `to` object form:
+
+```tsx
+<Links.About to={{ search: '?tab=info', hash: '#section' }}>
+  About
+</Links.About>
+```
+
+### HTML ID
+
+Each link component has an `id` property derived from the route path, useful for targeting with CSS or scroll anchoring:
+
+```typescript
+console.log(Links.Profile.Settings.id); // HTML-safe id derived from "profile/settings"
+```
+
+---
+
+## Navigates
+
+### Navigate Components
+
+Pre-bound `<Navigate>` components that redirect to specific routes on mount.
+
+```tsx
+const { Navigates } = ReactRouterTree(urlsTree);
+
+// Redirects to /about
+<Navigates.About />
+
+// Redirects to /profile/settings
+<Navigates.Profile.Settings />
+```
+
+#### With Params
+
+```tsx
+// Redirects to /profile/42
+<Navigates.Profile.$UserId params={{ userId: '42' }} />
+
+// Redirects to /profile/99/posts
+<Navigates.Profile.$UserId.Posts params={{ userId: '99' }} />
+```
+
+#### Preserve Option
+
+The `preserve` prop saves the current `search` and `hash` when redirecting:
+
+```tsx
+// If current URL is /old-page?tab=1#section
+// Redirects to /about?tab=1#section
+<Navigates.About preserve />
+```
+
+### useNavigate Hook
+
+A proxy-enhanced `useNavigate` hook that provides the same tree-based navigation as the components, but as callable functions.
+
+```tsx
+function MyComponent() {
+  const nav = Navigates.useNavigate();
+
+  return (
+    <div>
+      {/* Navigate to static routes */}
+      <button onClick={() => nav.About()}>Go to About</button>
+      <button onClick={() => nav.Profile.Settings()}>Go to Settings</button>
+
+      {/* Navigate with params */}
+      <button onClick={() => nav.Profile.$UserId({ userId: '42' })}>
+        Go to User 42
+      </button>
+
+      {/* Navigate to nested parameterized route */}
+      <button onClick={() => nav.Profile.$UserId.Posts({ userId: '99' })}>
+        Go to User 99 Posts
+      </button>
+
+      {/* Falls through to original navigate for direct paths */}
+      <button onClick={() => nav('/about')}>Direct navigate</button>
+    </div>
+  );
+}
+```
+
+#### Intermediate References
+
+The hook proxy is stateless - you can save intermediate references:
+
+```tsx
+function MyComponent() {
+  const nav = Navigates.useNavigate();
+
+  const profileNav = nav.Profile;
+  profileNav.Settings();   // navigates to /profile/settings
+  profileNav.$UserId({ userId: '1' }); // navigates to /profile/1
+}
+```
+
+---
+
+## isUrl & isSubUrl
+
+Functions for checking if a pathname matches a specific route. Both accept a string pathname or a location object `{ pathname: string }`.
+
+### isUrl (Strict Match)
+
+Matches only when the pathname has the exact same segments as the route:
+
+```typescript
+const { isUrl } = ReactRouterTree(urlsTree);
+
+isUrl.Home('/');                              // true
+isUrl.About('/about');                        // true
+isUrl.Profile.Settings('/profile/settings');  // true
+
+// Rejects extra or fewer segments
+isUrl.Profile('/profile/settings');           // false
+isUrl.Profile.Settings('/profile');           // false
+
+// Rejects non-matching
+isUrl.Profile.Settings('/profile/other');     // false
+
+// Rejects without leading slash
+isUrl.About('about');                         // false
+
+// Accepts location objects
+isUrl.About({ pathname: '/about' });          // true
+```
+
+### isUrl with Dynamic Params
+
+Without `params`, dynamic segments match any value (wildcard). With `params`, they match the specific value:
+
+```typescript
+// Wildcard - matches any userId
+isUrl.Profile.$UserId('/profile/123');                          // true
+isUrl.Profile.$UserId('/profile/abc');                          // true
+
+// With params - matches specific userId
+isUrl.Profile.$UserId('/profile/123', { userId: '123' });      // true
+isUrl.Profile.$UserId('/profile/123', { userId: '456' });      // false
+
+// Nested parameterized routes
+isUrl.Profile.$UserId.Posts('/profile/42/posts');               // true
+```
+
+### isSubUrl (Prefix Match)
+
+Matches when the pathname starts with the route:
+
+```typescript
+const { isSubUrl } = ReactRouterTree(urlsTree);
+
+// Matches exact and extended paths
+isSubUrl.Profile('/profile');                 // true
+isSubUrl.Profile('/profile/settings');        // true
+isSubUrl.Profile('/profile/123/posts');       // true
+
+// Rejects completely different paths
+isSubUrl.Profile('/about');                   // false
+
+// Root matches everything
+isSubUrl.Home('/anything');                   // true
+```
+
+---
+
+## RouteCreator
+
+Factory for building `RouteObject` definitions from the URL tree. Useful for defining routes in a type-safe, tree-structured way.
+
+```typescript
+import { ReactRouterTree } from '@avstantso/react-router-utils';
+
+const { RouteCreator } = ReactRouterTree(urlsTree);
+const createRoute = RouteCreator(urlsTree);
+```
+
+### Type: `'url'` (Full Path)
+
+Creates routes with full URL paths:
+
+```typescript
+const route = createRoute('url');
+
+route.About({ element: <AboutPage /> });
+// { element: <AboutPage />, path: '/about' }
+
+route.Profile.Settings({ element: <SettingsPage /> });
+// { element: <SettingsPage />, path: '/profile/settings' }
+
+route.Home({ element: <HomePage /> });
+// { element: <HomePage />, path: '/' }
+
+route.Profile[':userId'].Posts({ element: <PostsPage /> });
+// { element: <PostsPage />, path: '/profile/:userId/posts' }
+```
+
+### Type: `'name'` (Segment Only)
+
+Creates routes with just the segment name (for nested route definitions):
+
+```typescript
+const route = createRoute('name');
+
+route.Profile({ element: <ProfilePage /> });
+// { element: <ProfilePage />, path: 'profile' }
+
+route.Profile.Settings({ element: <SettingsPage /> });
+// { element: <SettingsPage />, path: 'settings' }
+```
+
+### Common Props
+
+Pass shared properties to all routes via the second argument:
+
+```typescript
+const route = createRoute('url', { errorElement: <ErrorPage /> });
+
+route.About({ element: <AboutPage /> });
+// { errorElement: <ErrorPage />, element: <AboutPage />, path: '/about' }
+
+// Route-specific props override common props
+const route2 = createRoute('url', { element: <DefaultPage /> });
+route2.About({ element: <AboutPage /> });
+// { element: <AboutPage />, path: '/about' }
+```
+
+---
+
+## Type Definitions
+
+### UrlsTree
+
+```typescript
+import type { UrlsTree } from '@avstantso/react-router-utils';
+
+// The URL tree type - built from NamesTree.Urls()
+type MyTree = typeof urlsTree;
+```
+
+### LinksTree
+
+```typescript
+import type { LinksTree, BindedLink, BindedNavLink } from '@avstantso/react-router-utils';
+
+// Full Links tree type
+type MyLinks = LinksTree<BindedLink.Props, MyTree>;
+
+// Full NavLinks tree type
+type MyNavLinks = LinksTree<BindedNavLink.Props, MyTree>;
+```
+
+### NavigatesTree
+
+```typescript
+import type { NavigatesTree } from '@avstantso/react-router-utils';
+
+// Full Navigates tree type (components + useNavigate)
+type MyNavigates = NavigatesTree<MyTree>;
+```
+
+### IsUrlTree
+
+```typescript
+import type { IsUrlTree } from '@avstantso/react-router-utils';
+
+// Full isUrl/isSubUrl tree type
+type MyIsUrl = IsUrlTree<MyTree>;
+```
+
+### RouteCreator
+
+```typescript
+import type { RouteCreator } from '@avstantso/react-router-utils';
+
+// Route creator function type
+type MyRouteCreator = RouteCreator<MyTree>;
+```
+
+---
+
+## Requirements
+
+- React >= 18.0
+- react-router-dom >= 7.0
+- TypeScript >= 5.0
+
+## Dependencies
+
+- [@avstantso/utils-misc](https://www.npmjs.com/package/@avstantso/utils-misc) - Miscellaneous utilities (Cases, HTMLUtils)
+- [@avstantso/utils-names-tree](https://www.npmjs.com/package/@avstantso/utils-names-tree) - Hierarchical name tree builder
+- [react-router-dom](https://www.npmjs.com/package/react-router-dom) - React Router
+
+## License
+
+MIT - See [LICENSE](https://gitlab.com/avstantso-js/react-utils/-/blob/main/LICENSE.md) file for details
+
+## Repository
+
+[GitLab - avstantso-js/react-utils](https://gitlab.com/avstantso-js/react-utils/-/tree/main/packages/react-router-utils)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or merge requests to the repository.

package/dist/core/binded-path.d.ts

@@ -0,0 +1,12 @@
+import TS = AVStantso.TS;
+import { Path, To } from 'react-router-dom';
+export type BindedPath = Omit<Path, 'pathname'>;
+export type BindProps<T extends {
+    to?: To;
+}> = TS.ReplaceKeyOpt<'to', T, Partial<BindedPath>>;
+export declare function resolveParams(url: string, params?: object): string;
+export declare function BindProps<P extends string, T extends {
+    to?: To;
+}>(pathname: P, props: {
+    to?: To;
+}, params?: object): T;

package/dist/core/index.d.ts

@@ -0,0 +1 @@
+export * from './binded-path';