@plumile/router 0.1.9 → 0.1.12

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Plumile/Pounjs and its affiliates.
+Copyright (c) Plumile and its affiliates.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1 +1,682 @@
-# Pounjs router
+# @plumile/router
+
+A modern, type-safe React router built with TypeScript that supports code splitting, data preloading, and React Suspense integration.
+
+## Features
+
+- **Type-safe routing** with full TypeScript support
+- **Code splitting** with dynamic imports and lazy loading
+- **Data preloading** for faster navigation
+- **React Suspense** integration for smooth loading states
+- **Browser history** management with push/replace state
+- **Nested routing** support
+- **Route-based redirects**
+- **Active link detection** with exact/partial matching
+
+## Installation
+
+```bash
+npm install @plumile/router
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install react react-dom react-relay relay-runtime @types/react @types/react-dom @types/react-relay
+```
+
+## Quick Start
+
+### 1. Define Your Routes
+
+```typescript
+import { Route, getResourcePage } from '@plumile/router';
+
+const routes: Route<any, any>[] = [
+  {
+    path: '/',
+    resourcePage: getResourcePage('Home', () => import('./pages/Home')),
+  },
+  {
+    path: '/about',
+    resourcePage: getResourcePage('About', () => import('./pages/About')),
+  },
+  {
+    path: '/users',
+    children: [
+      {
+        path: '/:id',
+        resourcePage: getResourcePage(
+          'UserProfile',
+          () => import('./pages/UserProfile'),
+        ),
+        prepare: ({ variables }) => {
+          // Preload user data
+          return { userId: variables.id };
+        },
+      },
+    ],
+  },
+];
+```
+
+### 2. Create the Router
+
+```typescript
+import createRouter from '@plumile/router';
+
+const { context, cleanup } = createRouter(routes);
+```
+
+### 3. Provide Router Context
+
+```tsx
+import React from 'react';
+import { RoutingContext, RouterRenderer } from '@plumile/router';
+
+function App() {
+  return (
+    <RoutingContext.Provider value={context}>
+      <RouterRenderer fallback={<div>Loading...</div>} />
+    </RoutingContext.Provider>
+  );
+}
+```
+
+### 4. Navigation with Links
+
+```tsx
+import { Link } from '@plumile/router';
+
+function Navigation() {
+  return (
+    <nav>
+      <Link to="/" exact activeClassName="active">
+        Home
+      </Link>
+      <Link to="/about" activeClassName="active">
+        About
+      </Link>
+      <Link to="/users/123" activeClassName="active">
+        User Profile
+      </Link>
+    </nav>
+  );
+}
+```
+
+## API Reference
+
+### Core Components
+
+#### `createRouter(routes: Route[], options?)`
+
+Creates a router instance with the given route configuration.
+
+**Parameters:**
+
+- `routes`: Array of route definitions
+- `options?`: Optional object
+  - `devtools?: boolean` Force enable/disable the global inspector. Defaults to enabled when `NODE_ENV !== 'production'`, disabled otherwise.
+
+**Returns:**
+
+- `context`: Router context object for the React Context Provider
+- `cleanup`: Function to clean up router listeners
+
+#### `RouterRenderer`
+
+Renders the matched route component with Suspense support.
+
+**Props:**
+
+- `fallback?`: ReactNode - Fallback UI while loading components
+- `enableTransition?`: boolean - Enable React 18 transitions
+- `pending?`: ReactNode - UI to show during transitions
+
+#### `Link`
+
+Navigation component that handles client-side routing.
+
+**Props:**
+
+- `to`: string - Destination path
+- `exact?`: boolean - Exact path matching for active state
+- `activeClassName?`: string - CSS class when link is active
+- `className?`: string - Base CSS class
+- `preload?`: boolean - Preload route on hover
+- `replace?`: boolean - Replace current history entry
+
+#### `RoutingContext`
+
+React context that provides router functionality to components.
+
+### Route Configuration
+
+#### `Route<TPrepared, TVariables>`
+
+Route definition interface.
+
+**Properties:**
+
+- `path?`: string - URL path pattern
+- `children?`: Route[] | Redirect[] - Nested routes
+- `resourcePage?`: ResourcePage - Lazy-loaded component
+- `prepare?`: Function to preload data
+- `render?`: Custom render function
+
+#### `Redirect`
+
+Redirect configuration.
+
+**Properties:**
+
+- `path?`: string - Source path
+- `to`: string - Destination path
+- `status?`: 301 | 302 - HTTP status code
+
+### Resource Management
+
+#### `getResourcePage(moduleId: string, loader: ResourcePageLoader)`
+
+Creates a resource for lazy-loading components.
+
+**Parameters:**
+
+- `moduleId`: Unique identifier for caching
+- `loader`: Function that returns dynamic import
+
+**Returns:**
+
+- `ResourcePage` instance
+
+#### `ResourcePage`
+
+Manages lazy-loaded components with Suspense integration.
+
+**Methods:**
+
+- `load()`: Promise - Load the component
+- `get()`: Component | undefined - Get loaded component
+- `read()`: Component - Read with Suspense (throws Promise if loading)
+
+### History Management
+
+#### `BrowserHistory`
+
+Browser history implementation.
+
+**Methods:**
+
+- `push(location)`: Navigate to new location
+- `set(location)`: Replace current location
+- `subscribe(listener)`: Listen for navigation changes
+
+### Utilities
+
+#### `getMatchedRoute(routes, location)`
+
+Finds the matching route for a given location.
+
+#### `prepareMatch(match)`
+
+Prepares route data and components for rendering.
+
+#### `r<TPrepared, TVariables>(route)`
+
+Type helper for strongly-typed route definitions.
+
+## Advanced Usage
+
+### Typed Query Parameters (DSL)
+
+The router provides a lightweight schema DSL for parsing, typing, normalizing and serializing query strings.
+
+#### 1. Define a schema on the deepest route
+
+```ts
+import { q, r } from '@plumile/router';
+
+const routes = [
+  r({
+    path: '/items',
+    // Schema: page = number (default 1), tag(s) = array of strings, flag = optional boolean
+    query: {
+      page: q.default(q.number(), 1),
+      tags: q.array(q.string()),
+      flag: q.optional(q.boolean()),
+    },
+    prepare: ({ query }) => {
+      // query is typed: { page: number; tags: string[]; flag?: boolean }
+      return { page: query.page };
+    },
+    render: () => null,
+  }),
+];
+```
+
+#### 2. Access parsed & typed queries
+
+```tsx
+import { useQuery, useTypedQuery } from '@plumile/router';
+
+function List() {
+  const raw = useQuery(); // Record<string, string | string[]>
+  const typed = useTypedQuery(); // Auto‑inferred from deepest route schema (no generic needed)
+  const [page, setPage] = useQueryState<number>('page'); // Bidirectional state ↔ URL for one param
+  return <pre>{JSON.stringify({ raw, typed }, null, 2)}</pre>;
+}
+```
+
+Referential stability: both `raw` (from `useQuery()`) and `typed` (from `useTypedQuery()`) are memoized per canonical search string. If the URL search part doesn't change semantically (including key order canonicalization), the hook returns the exact same object reference. You can safely list either in React dependency arrays without extra `useMemo` or a hypothetical `useStableQuery` helper (not needed).
+
+Type inference:
+
+- If the matched deepest route has a `query` schema, `useTypedQuery()` returns the inferred `InferQuery<typeof schema>` shape automatically.
+- If no schema exists, it returns the raw parsed object (record of string | string[]) so you can still read values safely.
+- You can still supply a generic manually (`useTypedQuery<MyShape>()`) in edge cases (e.g. incremental migration) but it is usually unnecessary now.
+
+#### 3. Programmatic navigation with typed query
+
+```tsx
+import { useNavigate } from '@plumile/router';
+
+function Pager({ page }: { page: number }) {
+  const navigate = useNavigate();
+  return (
+    <button
+      onClick={() => {
+        navigate({ query: { page: page + 1 } });
+      }}
+    >
+      Next page
+    </button>
+  );
+}
+```
+
+#### 4. Link component with query
+
+```tsx
+import { Link } from '@plumile/router';
+
+<Link to="/items" query={{ page: 2, tags: ['a', 'b'], flag: true }}>
+  Filter
+</Link>;
+```
+
+`Link` & `navigate` automatically serialize using the route schema, applying:
+
+- Schema key order
+- Array repetition (`?tags=a&tags=b`)
+- Omission of default values when `omitDefaults` optimization applies internally
+
+#### 5. Normalization
+
+Built‑in simple normalization currently clamps `page < 1` to `1` and issues a `replaceState` to avoid polluting history.
+
+#### 6. Serialization utility
+
+```ts
+import { buildSearch, q } from '@plumile/router';
+
+const schema = {
+  page: q.default(q.number(), 1),
+  tag: q.array(q.string()),
+} as const;
+const search = buildSearch({ page: 1, tag: ['x', 'y'] }, schema, {
+  omitDefaults: true,
+});
+// => '?tag=x&tag=y'
+```
+
+#### 7. Parsing utility / alias
+
+```ts
+import { parseSearch, q } from '@plumile/router';
+
+const schema = { flag: q.boolean() } as const;
+const typed = parseSearch(schema, '?flag=1'); // { flag: true }
+```
+
+#### 8. Performance and stability
+
+There are two coordinated caching layers:
+
+1. Raw query cache: A process-wide Map keyed by a canonicalized search string (sorted keys, ordered value emission). Produces a frozen empty object for the empty search and reuses prior parsed objects, yielding stable references for unchanged search state.
+2. Typed query cache: A WeakMap keyed by (schema reference → canonical search signature) that parses once and reuses the typed value. Structural deep-equality canonicalization means semantically equivalent searches (e.g. reordered keys) reuse object identity.
+
+Effects:
+
+- Stable object identity for both raw and typed queries eliminates needless renders and removes the need for an extra `useStableQuery` hook.
+- Safe to put `useQuery()` / `useTypedQuery()` results directly in dependency arrays (`useEffect`, `useMemo`, selectors, etc.).
+- Empty query allocations are avoided (shared frozen object).
+
+Guideline: If you need to derive lightweight projections (e.g. `const { page } = typed`), you can still destructure; but avoid spreading into a new object if you rely on reference equality downstream.
+
+#### Devtools / Inspection
+
+In development (`NODE_ENV !== 'production'` by default, or when `createRouter(..., { devtools: true })` is passed), the router exposes a lightweight global inspector.
+
+Optionally you can enable an in‑page overlay panel for quick visual inspection:
+
+```ts
+createRouter(routes, {
+  devtools: { panel: true, global: true, shortcut: 'Alt+Shift+R' },
+});
+```
+
+Devtools option forms:
+
+- `devtools: true | false` (boolean) – legacy form, controls global only.
+- `devtools: { global?: boolean; panel?: boolean; shortcut?: string }` – granular.
+  - `global` (default: NODE_ENV !== 'production') exposes `window.__PLUMILE_ROUTER__`.
+  - `panel` (default: false) mounts an overlay; closed with the close button or page reload.
+  - `shortcut` (default: `Alt+Shift+R`) toggles panel visibility.
+
+The panel displays current path+search, variables, raw query and typed query. It is intentionally framework‑agnostic (no React runtime cost) and uses a shadow root to minimize style collisions.
+
+```js
+window.__PLUMILE_ROUTER__.get(); // current RouteEntry
+const unsub = window.__PLUMILE_ROUTER__.subscribe((entry) =>
+  console.log(entry.typedQuery),
+);
+```
+
+This lets you introspect parsed queries & variables without adding debug code. Neither global nor panel is present in production unless explicitly forced with `devtools: { global: true, panel: true }` (discouraged).
+
+##### Detailed Usage
+
+The global is intentionally tiny to avoid coupling and bundle weight. It only appears when the devtools flag resolves truthy:
+
+1. Explicit: `createRouter(routes, { devtools: true })`
+2. Implicit heuristic: `NODE_ENV !== 'production'`
+3. Disabled explicitly: `createRouter(routes, { devtools: false })`
+
+Always guard in snippets that might be copied to production code:
+
+```js
+if (window.__PLUMILE_ROUTER__) {
+  console.log(window.__PLUMILE_ROUTER__.get());
+}
+```
+
+`get()` returns the current `RouteEntry` (simplified shape):
+
+```ts
+type RouteEntry = {
+  location: Location; // window.location snapshot
+  route: { match; params; path } | null; // current matched route (or null)
+  preparedMatch: { routes: { prepared; render?; resourcePage? }[]; match }; // internal prepared tree
+  forceRerender: boolean; // indicates forced re-render situations
+  rawSearch: string; // '?page=2&tag=a'
+  query: Record<string, string | string[]>; // raw aggregated query params
+  typedQuery: any; // typed query if schema present
+};
+```
+
+Common console patterns:
+
+1. Log every navigation with typed query & params:
+
+```js
+const dev = window.__PLUMILE_ROUTER__;
+if (dev) {
+  const off = dev.subscribe((e) => {
+    console.log('[router]', e.location.pathname + e.location.search, {
+      vars: e.route?.params,
+      typed: e.typedQuery,
+    });
+  });
+  // later: off();
+}
+```
+
+2. Inspect prepared data for the deepest route (last element):
+
+```js
+const entry = window.__PLUMILE_ROUTER__?.get();
+const deepest = entry?.preparedMatch.routes.at(-1);
+deepest?.prepared; // Prepared data returned by deepest prepare()
+```
+
+3. Quick diff watcher for query changes only:
+
+```js
+let last = window.__PLUMILE_ROUTER__?.get().rawSearch;
+const off = window.__PLUMILE_ROUTER__?.subscribe((e) => {
+  if (e.rawSearch !== last) {
+    console.log('query changed', last, '=>', e.rawSearch, e.typedQuery);
+    last = e.rawSearch;
+  }
+});
+```
+
+4. Measuring parse performance (rough dev-only micro‑benchmark):
+
+```js
+const { get } = window.__PLUMILE_ROUTER__;
+const before = performance.now();
+for (let i = 0; i < 200; i++) get().typedQuery; // use cache; ensures no GC
+console.log('elapsed ms', performance.now() - before);
+```
+
+5. Safe optional chaining helper (copy/paste):
+
+```js
+const R = window.__PLUMILE_ROUTER__;
+R && R.subscribe((e) => console.debug('[typedQuery]', e.typedQuery));
+```
+
+Unsubscribing: every `subscribe` returns a disposer function. Always call it if you set up long‑lived listeners in a debugging session to avoid memory leaks during hot reloads.
+
+Extending: if you need more (e.g. trigger navigations) you can wrap `createRouter` in your app and attach additional methods to `window.__PLUMILE_ROUTER__` (e.g. `navigate: context.navigate`) — omitted by default to avoid accidental production reliance.
+
+Production: the symbol is not defined; accessing it will yield `undefined`. Never ship logic depending on it; keep usage inside `if (process.env.NODE_ENV !== 'production')` blocks or guarded optional checks.
+
+### ESLint Rule: no-direct-window-location-search
+
+To encourage consistent usage of the query hooks, a custom rule is provided inside the router package to flag raw `window.location.search` access.
+
+Add to your flat ESLint config:
+
+```js
+import noDirectWindowLocationSearch from '@plumile/router/lib/eslint-rules/no-direct-window-location-search.js';
+
+export default [
+  {
+    plugins: {
+      '@plumile-router/dx': {
+        rules: {
+          'no-direct-window-location-search': noDirectWindowLocationSearch,
+        },
+      },
+    },
+    rules: {
+      '@plumile-router/dx/no-direct-window-location-search': 'warn',
+    },
+  },
+];
+```
+
+Optional configuration:
+
+```js
+// allow some files (e.g. legacy bootstrap) to keep direct access
+rules: {
+  '@plumile-router/dx/no-direct-window-location-search': [
+    'warn',
+    { allowInFiles: ['legacy-entry.ts'] },
+  ],
+},
+```
+
+When triggered, replace patterns like:
+
+```ts
+const qs = window.location.search;
+```
+
+with:
+
+```ts
+const query = useQuery(); // or useTypedQuery()
+```
+
+### Migration Guide (Phases 1 → 5)
+
+1. Phase 1/2: Upgrade — no schema needed. Use `useQuery()` for raw params.
+2. Phase 3: Add `query` schema to your deepest route; adopt `useTypedQuery()` where type safety is desirable.
+3. Phase 4: Replace manual URL building with `navigate({ query })` or `<Link query={...} />`. Remove ad‑hoc serialization logic.
+4. Phase 5: Move lightweight data loading logic that depends on query into `prepare({ query })` (now typed). Rely on built‑in normalization (e.g. page clamp) or add custom normalization inside `prepare` followed by a `navigate({ replace: true, query: normalized })` if needed.
+5. Optional: Use `buildSearch` / `parseSearch` for unit tests & utilities.
+
+### Query Descriptor Reference
+
+| Descriptor                       | Description                                         | Serialize Example                    |
+| -------------------------------- | --------------------------------------------------- | ------------------------------------ |
+| `q.string()`                     | Last occurrence string                              | `{ q: 'x' } -> ?q=x`                 |
+| `q.number()`                     | Number (invalid => undefined)                       | `{ n: 2 } -> ?n=2`                   |
+| `q.boolean()`                    | Presence / true/false/1/0                           | `{ f: true } -> ?f=1`                |
+| `q.enum('a','b')`                | Restricted string                                   | `{ e: 'a' } -> ?e=a`                 |
+| `q.array(inner)`                 | Repeated key multi-values                           | `{ tag: ['x','y'] } -> ?tag=x&tag=y` |
+| `q.optional(d)`                  | Marks descriptor optional                           | omitted if undefined                 |
+| `q.default(d, v)`                | Supplies default + omit on serialize (omitDefaults) | default skipped                      |
+| `q.emptyAsUndefined(q.string())` | Maps empty string '' to undefined                   | omitted                              |
+| `q.custom({ parse, serialize })` | Custom parse/serialize logic                        | depends                              |
+
+Custom: `q.custom({ parse(values), serialize(value) })` lets you wire bespoke formats. Ensure `serialize` outputs an array of raw string values. Use sparingly to keep schemas readable.
+
+### useQueryState Hook
+
+`useQueryState(key, opts?)` creates a controlled binding between a single query parameter and component state.
+
+```tsx
+const [page, setPage] = useQueryState<number>('page');
+// Increment page without pushing a new history entry
+setPage(page! + 1, { replace: true });
+```
+
+Behavior:
+
+- Reads from typedQuery if schema present, else raw query.
+- Respects schema defaults (and `defaultValue` override in options) and omits key when value equals default (with `omitIfDefault: true`).
+- Pass `{ raw: true }` to force raw (string) source for incremental migrations.
+- Uses existing navigation serialization (ordering, omit defaults, arrays).
+
+Options:
+`{ defaultValue?, omitIfDefault?: boolean = true, replace?: boolean, raw?: boolean }`
+
+### Data Preloading
+
+```typescript
+const route: Route<{ user: User }, { id: string }> = {
+  path: '/users/:id',
+  prepare: async ({ variables }) => {
+    const user = await fetchUser(variables.id);
+    return { user };
+  },
+  render: ({ prepared, children }) => {
+    if (!prepared) return null;
+    return <UserLayout user={prepared.user}>{children}</UserLayout>;
+  },
+};
+```
+
+### Custom Route Rendering
+
+```typescript
+const route: Route<any, any> = {
+  path: '/protected',
+  render: ({ children, prepared }) => {
+    if (!userIsAuthenticated()) {
+      return <Redirect to="/login" />;
+    }
+    return <ProtectedLayout>{children}</ProtectedLayout>;
+  },
+};
+```
+
+### Programmatic Navigation
+
+```tsx
+import { useContext } from 'react';
+import { RoutingContext } from '@plumile/router';
+
+function MyComponent() {
+  const router = useContext(RoutingContext);
+
+  const handleClick = () => {
+    router.history.push({ pathname: '/new-path' });
+  };
+
+  return <button onClick={handleClick}>Navigate</button>;
+}
+```
+
+### Route Preloading
+
+```tsx
+import { useContext } from 'react';
+import { RoutingContext } from '@plumile/router';
+
+function MyComponent() {
+  const router = useContext(RoutingContext);
+
+  const handleHover = () => {
+    // Preload code only
+    router.preloadCode('/users/123');
+
+    // Preload code and data
+    router.preload('/users/123');
+  };
+
+  return (
+    <Link to="/users/123" onMouseEnter={handleHover}>
+      User Profile
+    </Link>
+  );
+}
+```
+
+## TypeScript Support
+
+The router is built with TypeScript and provides full type safety:
+
+```typescript
+import { Route, r } from '@plumile/router';
+
+interface UserPageData {
+  user: User;
+  posts: Post[];
+}
+
+interface UserPageParams {
+  id: string;
+}
+
+const userRoute = r<UserPageData, UserPageParams>({
+  path: '/users/:id',
+  prepare: ({ variables }) => {
+    // variables.id is typed as string
+    return fetchUserData(variables.id);
+  },
+  render: ({ prepared }) => {
+    // prepared is typed as UserPageData | undefined
+    if (!prepared) return null;
+    return <UserPage user={prepared.user} posts={prepared.posts} />;
+  },
+});
+```
+
+## Browser Support
+
+- Modern browsers that support ES2021
+- React 18+
+- Node.js 21+
+
+## License
+
+Licensed under the terms specified in the package's LICENSE file.

package/lib/esm/ResourcePage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResourcePage.d.ts","sourceRoot":"","sources":["../../src/ResourcePage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAczE,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAe;IAE9B,OAAO,CAAC,QAAQ,CAAqB;IAErC,OAAO,CAAC,SAAS,CAAqC;IAEtD,OAAO,CAAC,QAAQ,CAA4B;IAG5C,OAAO,CAAC,UAAU,CAAS;gBAER,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM;IAWlD,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA2BzC,GAAG,IAAI,kBAAkB,GAAG,SAAS;IAgBrC,IAAI,IAAI,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,KAAK;YAazD,MAAM;CAKrB;AAmBD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GACzB,YAAY,GAAG,IAAI,CAOrB"}
+{"version":3,"file":"ResourcePage.d.ts","sourceRoot":"","sources":["../../src/ResourcePage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA2BzE,qBAAa,YAAY;IAEvB,OAAO,CAAC,OAAO,CAAe;IAG9B,OAAO,CAAC,QAAQ,CAAqB;IAGrC,OAAO,CAAC,SAAS,CAAqC;IAGtD,OAAO,CAAC,QAAQ,CAA4B;IAI5C,OAAO,CAAC,UAAU,CAAS;gBAQR,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM;IAclD,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA8BzC,GAAG,IAAI,kBAAkB,GAAG,SAAS;IAmBrC,IAAI,IAAI,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,KAAK;YAkBzD,MAAM;CAKrB;AAsBD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GACzB,YAAY,GAAG,IAAI,CAOrB"}