npm - @ecopages/react-router - Versions diffs - 0.2.0-alpha.1 - Mend

@ecopages/react-router 0.2.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/CHANGELOG.md +16 -0
package/LICENSE +21 -0
package/README.md +212 -0
package/browser.d.ts +13 -0
package/browser.js +11 -0
package/browser.ts +17 -0
package/package.json +42 -0
package/src/adapter.d.ts +28 -0
package/src/adapter.js +22 -0
package/src/adapter.ts +48 -0
package/src/context.d.ts +16 -0
package/src/context.js +11 -0
package/src/context.ts +25 -0
package/src/head-morpher.d.ts +15 -0
package/src/head-morpher.js +94 -0
package/src/head-morpher.ts +170 -0
package/src/index.d.ts +14 -0
package/src/index.js +13 -0
package/src/index.ts +21 -0
package/src/manage-scroll.d.ts +17 -0
package/src/manage-scroll.js +25 -0
package/src/manage-scroll.ts +47 -0
package/src/navigation.d.ts +65 -0
package/src/navigation.js +120 -0
package/src/navigation.ts +247 -0
package/src/props-script.d.ts +11 -0
package/src/props-script.js +11 -0
package/src/props-script.ts +19 -0
package/src/router.d.ts +73 -0
package/src/router.js +225 -0
package/src/router.ts +348 -0
package/src/scroll-persist.d.ts +40 -0
package/src/scroll-persist.js +57 -0
package/src/scroll-persist.ts +96 -0
package/src/styles.css +200 -0
package/src/types.d.ts +49 -0
package/src/types.js +12 -0
package/src/types.ts +64 -0
package/src/view-transition-manager.d.ts +5 -0
package/src/view-transition-manager.js +16 -0
package/src/view-transition-manager.ts +30 -0
package/src/view-transition-utils.d.ts +13 -0
package/src/view-transition-utils.js +60 -0
package/src/view-transition-utils.ts +95 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,16 @@
+# Changelog
+All notable changes to `@ecopages/react-router` are documented here.
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+## [UNRELEASED] — TBD
+### Bug Fixes
+- Published npm package metadata now includes validated declaration exports for generated dist entrypoints.
+### Refactoring
+- Updated `package.json` dependencies to align with the new core adapter and esbuild build adapter versions.
+- Internal peer dependency declarations updated for React 18+ and the new `@ecopages/core` API surface.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025-present Andrea Zanenghi
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,212 @@
+# @ecopages/react-router
+Client-side SPA router for EcoPages React applications. Enables single-page application navigation while preserving full SSR benefits.
+## Installation
+```bash
+bun add @ecopages/react-router
+```
+## Quick Start
+Add the router adapter to your `eco.config.ts`:
+```typescript
+import { ConfigBuilder } from '@ecopages/core';
+import { reactPlugin } from '@ecopages/react';
+import { ecoRouter } from '@ecopages/react-router';
+const config = await new ConfigBuilder()
+	.setRootDir(import.meta.dir)
+	.setIntegrations([reactPlugin({ router: ecoRouter() })])
+	.build();
+export default config;
+```
+That's it! All pages now have SPA navigation enabled.
+## Features
+- **Opt-in via config** - Single line enables SPA for all pages
+- **SSR preserved** - Full server-side rendering on initial load
+- **Layout persistence** - Layouts stay mounted, only page content swaps
+- **Standard links** - Works with regular `<a>` tags
+- **Head sync** - Automatically updates title, meta, and stylesheets
+- **Pluggable** - Extensible adapter pattern
+## Usage
+### Layouts (Optional)
+Use `config.layout` for persistent UI across navigations:
+```tsx
+// src/layouts/base-layout.tsx
+export const BaseLayout = ({ children }) => (
+	<html>
+		<body>
+			<header>My Site</header>
+			<main>{children}</main>
+		</body>
+	</html>
+);
+// src/pages/index.tsx
+import { BaseLayout } from '../layouts/base-layout';
+const HomePage = () => <h1>Welcome</h1>;
+HomePage.config = { layout: BaseLayout };
+export default HomePage;
+```
+### Links
+```tsx
+// SPA navigation (intercepted)
+<a href="/about">About</a>
+// Force full reload
+<a href="/external" data-eco-reload>External</a>
+```
+### Programmatic Navigation
+```tsx
+import { useRouter } from '@ecopages/react-router';
+const MyComponent = () => {
+	const { navigate, isPending } = useRouter();
+	return (
+		<button onClick={() => navigate('/about')} disabled={isPending}>
+			Go to About
+		</button>
+	);
+};
+```
+### View Transitions
+The router automatically supports the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for smooth page transitions.
+#### Lifecycle
+When a navigation occurs with View Transitions enabled:
+1.  **Snapshot**: The browser captures the current state (screenshot) of the page.
+2.  **Update**: React processes the state change and renders the new page.
+3.  **Animate**: The browser animates from the old snapshot to the new live state.
+The router uses a deferred promise mechanism to ensure React has fully finished rendering the new content before telling the browser to start the animation phase.
+#### Shared Element Transitions
+To animate elements between pages (e.g., a thumbnail becoming a hero image), use the `data-view-transition` attribute. Ensure the value is unique to the specific element being transitioned and matches on both pages.
+```tsx
+// List Page (Source)
+<img
+  src={post.image}
+  data-view-transition={`hero-${post.id}`}
+/>
+// Detail Page (Destination)
+<img
+  src={post.image}
+  data-view-transition={`hero-${post.id}`}
+/>
+```
+By default, the router applies a **clean morph** animation (disabling the default cross-fade ghosting). If you prefer the standard browser cross-fade, you can opt-out:
+```tsx
+<div data-view-transition="my-hero" data-view-transition-animate="fade">
+	...
+</div>
+```
+#### Cross-Fade
+By default, the router provides a smooth cross-fade for the root content. You can customize this by overriding the default view transition CSS:
+```css
+::view-transition-old(root),
+::view-transition-new(root) {
+	animation-duration: 0.5s;
+}
+```
+## How It Works
+The router uses an **HTML-First** navigation strategy to ensure consistency with Server-Side Rendering (SSR).
+1.  **SSR**: Server renders full HTML for the initial page load.
+2.  **Hydration**: Client hydrates, router attaches to the document.
+3.  **Navigation**: On link click:
+    - **Fetch**: Requests the full HTML of the target page (just like a standard browser navigation).
+    - **Parse**: Extracts the page component URL and serialized props from the HTML.
+    - **Preload**: Dynamically imports the new page component.
+    - **Transition**:
+        - Calls `document.startViewTransition()`.
+        - Updates the document head (title, meta, styles).
+        - Updates the React state to render the new page component.
+        - Waits for React commit (useEffect).
+    - **Resolve**: View Transition finishes, browser plays the animation.
+## API
+### `ecoRouter()`
+Creates a router adapter for the React plugin.
+```typescript
+reactPlugin({ router: ecoRouter() });
+```
+### `useRouter()`
+Hook for programmatic navigation.
+```typescript
+const { navigate, isPending } = useRouter();
+```
+### Link Behavior
+Links are **not** intercepted when:
+- Modifier keys held (Ctrl, Cmd, Shift, Alt)
+- Has `target="_blank"` or `download` attribute
+- Has `data-eco-reload` attribute
+- Points to different origin
+- Starts with `#` or `javascript:`
+## Architecture
+The router uses a pluggable adapter pattern:
+```typescript
+interface ReactRouterAdapter {
+	name: string;
+	bundle: { importPath; outputName; externals };
+	importMapKey: string;
+	components: { router; pageContent };
+	getRouterProps(page, props): string;
+}
+```
+This allows custom router implementations while keeping integration simple.
+## Compatibility
+- React 18.x or 19.x
+- Modern browsers with ES modules
+- EcoPages with React integration
+## License
+MIT

package/browser.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * Browser entry point for @ecopages/react-router.
+ * This file exports only the client-side components needed for hydration.
+ * @module
+ */
+export { EcoRouter, PageContent } from './src/router.js';
+export type { EcoRouterProps } from './src/router.js';
+export { useRouter } from './src/context.js';
+export type { RouterContextValue } from './src/context.js';
+export { EcoPropsScript } from './src/props-script.js';
+export type { EcoPropsScriptProps } from './src/props-script.js';
+export { morphHead } from './src/head-morpher.js';
+export type { PageState } from './src/navigation.js';

package/browser.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { EcoRouter, PageContent } from "./src/router.js";
+import { useRouter } from "./src/context.js";
+import { EcoPropsScript } from "./src/props-script.js";
+import { morphHead } from "./src/head-morpher.js";
+export {
+  EcoPropsScript,
+  EcoRouter,
+  PageContent,
+  morphHead,
+  useRouter
+};

package/browser.ts ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * Browser entry point for @ecopages/react-router.
+ * This file exports only the client-side components needed for hydration.
+ * @module
+ */
+export { EcoRouter, PageContent } from './src/router.ts';
+export type { EcoRouterProps } from './src/router.ts';
+export { useRouter } from './src/context.ts';
+export type { RouterContextValue } from './src/context.ts';
+export { EcoPropsScript } from './src/props-script.ts';
+export type { EcoPropsScriptProps } from './src/props-script.ts';
+export { morphHead } from './src/head-morpher.ts';
+export type { PageState } from './src/navigation.ts';

package/package.json ADDED Viewed

@@ -0,0 +1,42 @@
+{
+  "name": "@ecopages/react-router",
+  "version": "0.2.0-alpha.1",
+  "description": "Client-side SPA router for EcoPages React applications",
+  "keywords": [
+    "ecopages",
+    "react",
+    "router",
+    "spa",
+    "navigation",
+    "ssr"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./browser.js"
+    },
+    "./browser.ts": {
+      "types": "./browser.d.ts",
+      "default": "./browser.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/react-router"
+  },
+  "peerDependencies": {
+    "@ecopages/react": "0.2.0-alpha.1"
+  },
+  "dependencies": {
+    "react": "^19",
+    "react-dom": "^19.2.4"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/adapter.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Router adapter for React integration.
+ * @module
+ */
+import type { ReactRouterAdapter } from '@ecopages/react/router-adapter';
+import type { EcoRouterOptions } from './types.js';
+/**
+ * Creates a ReactRouterAdapter for EcoPages React Router.
+ * Use this with the React plugin to enable SPA navigation.
+ *
+ * @param options - Router configuration options
+ * @example
+ * ```ts
+ * import { reactPlugin } from '@ecopages/react';
+ * import { ecoRouter } from '@ecopages/react-router';
+ *
+ * export default {
+ *   integrations: [reactPlugin({ router: ecoRouter() })],
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Disable view transitions
+ * reactPlugin({ router: ecoRouter({ viewTransitions: false }) })
+ * ```
+ */
+export declare function ecoRouter(options?: EcoRouterOptions): ReactRouterAdapter;

package/src/adapter.js ADDED Viewed

@@ -0,0 +1,22 @@
+function ecoRouter(options) {
+  return {
+    name: "eco-router",
+    bundle: {
+      importPath: "@ecopages/react-router/browser.ts",
+      outputName: "react-router-esm",
+      externals: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime"]
+    },
+    importMapKey: "@ecopages/react-router",
+    components: {
+      router: "EcoRouter",
+      pageContent: "PageContent"
+    },
+    getRouterProps(page, props) {
+      const optionsStr = options ? `, options: ${JSON.stringify(options)}` : "";
+      return `{ page: ${page}, pageProps: ${props}${optionsStr} }`;
+    }
+  };
+}
+export {
+  ecoRouter
+};

package/src/adapter.ts ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * Router adapter for React integration.
+ * @module
+ */
+import type { ReactRouterAdapter } from '@ecopages/react/router-adapter';
+import type { EcoRouterOptions } from './types.ts';
+/**
+ * Creates a ReactRouterAdapter for EcoPages React Router.
+ * Use this with the React plugin to enable SPA navigation.
+ *
+ * @param options - Router configuration options
+ * @example
+ * ```ts
+ * import { reactPlugin } from '@ecopages/react';
+ * import { ecoRouter } from '@ecopages/react-router';
+ *
+ * export default {
+ *   integrations: [reactPlugin({ router: ecoRouter() })],
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Disable view transitions
+ * reactPlugin({ router: ecoRouter({ viewTransitions: false }) })
+ * ```
+ */
+export function ecoRouter(options?: EcoRouterOptions): ReactRouterAdapter {
+	return {
+		name: 'eco-router',
+		bundle: {
+			importPath: '@ecopages/react-router/browser.ts',
+			outputName: 'react-router-esm',
+			externals: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+		},
+		importMapKey: '@ecopages/react-router',
+		components: {
+			router: 'EcoRouter',
+			pageContent: 'PageContent',
+		},
+		getRouterProps(page: string, props: string): string {
+			const optionsStr = options ? `, options: ${JSON.stringify(options)}` : '';
+			return `{ page: ${page}, pageProps: ${props}${optionsStr} }`;
+		},
+	};
+}

package/src/context.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+/**
+ * Router context and hook for accessing navigation state.
+ * @module
+ */
+export type RouterContextValue = {
+    navigate: (url: string) => void;
+    isNavigating: boolean;
+};
+export declare const RouterContext: import("react").Context<RouterContextValue | null>;
+/**
+ * Hook to access the router's navigate function and navigation state.
+ * Must be used within an EcoRouter.
+ *
+ * @throws Error if used outside of EcoRouter
+ */
+export declare const useRouter: () => RouterContextValue;

package/src/context.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { createContext, useContext } from "react";
+const RouterContext = createContext(null);
+const useRouter = () => {
+  const context = useContext(RouterContext);
+  if (!context) throw new Error("useRouter must be used within EcoRouter");
+  return context;
+};
+export {
+  RouterContext,
+  useRouter
+};

package/src/context.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Router context and hook for accessing navigation state.
+ * @module
+ */
+import { createContext, useContext } from 'react';
+export type RouterContextValue = {
+	navigate: (url: string) => void;
+	isNavigating: boolean;
+};
+export const RouterContext = createContext<RouterContextValue | null>(null);
+/**
+ * Hook to access the router's navigate function and navigation state.
+ * Must be used within an EcoRouter.
+ *
+ * @throws Error if used outside of EcoRouter
+ */
+export const useRouter = (): RouterContextValue => {
+	const context = useContext(RouterContext);
+	if (!context) throw new Error('useRouter must be used within EcoRouter');
+	return context;
+};

package/src/head-morpher.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Head morphing utilities for client-side navigation.
+ * Intelligently syncs head elements between pages using key-based diffing.
+ * @module
+ */
+/**
+ * Morphs the current document head to match the new document's head.
+ * Now splits the process into adding new elements and returning a cleanup function
+ * to remove old ones. This is crucial for View Transitions to ensure styles
+ * don't disappear before the "old" snapshot is taken.
+ *
+ * @param newDocument - The parsed document from the navigation target
+ * @returns Promise that resolves to a cleanup function when new stylesheets have loaded
+ */
+export declare function morphHead(newDocument: Document): Promise<() => void>;

package/src/head-morpher.js ADDED Viewed

@@ -0,0 +1,94 @@
+const PRESERVE_SELECTORS = ['script[type="importmap"]', "meta[charset]", "[data-eco-persist]"];
+function getHeadElementKey(el) {
+  const tag = el.tagName.toLowerCase();
+  switch (tag) {
+    case "title":
+      return "title";
+    case "meta": {
+      const name = el.getAttribute("name") || el.getAttribute("property") || el.getAttribute("http-equiv");
+      return name ? `meta:${name}` : null;
+    }
+    case "link": {
+      const rel = el.getAttribute("rel");
+      const href = el.getAttribute("href");
+      if (rel === "stylesheet" && href) return `stylesheet:${href}`;
+      if (rel === "icon" || rel === "shortcut icon") return "favicon";
+      if (rel === "canonical") return "canonical";
+      return href ? `link:${href}` : null;
+    }
+    case "script": {
+      if (el.getAttribute("type") === "importmap") return "importmap";
+      const src = el.src;
+      return src ? `script:${src}` : null;
+    }
+    case "style": {
+      const dataId = el.getAttribute("data-eco-style");
+      return dataId ? `style:${dataId}` : null;
+    }
+    default:
+      return null;
+  }
+}
+async function morphHead(newDocument) {
+  const currentHead = document.head;
+  const newHead = newDocument.head;
+  const currentElements = /* @__PURE__ */ new Map();
+  const newElements = /* @__PURE__ */ new Map();
+  const stylesheetPromises = [];
+  const elementsToRemove = [];
+  for (const el of Array.from(currentHead.children)) {
+    const key = getHeadElementKey(el);
+    if (key) currentElements.set(key, el);
+  }
+  for (const el of Array.from(newHead.children)) {
+    const key = getHeadElementKey(el);
+    if (key) newElements.set(key, el);
+  }
+  for (const [key, newEl] of newElements) {
+    const currentEl = currentElements.get(key);
+    if (!currentEl) {
+      const src = newEl.getAttribute("src");
+      if (newEl.tagName === "SCRIPT" && src && src.includes("hydration.js") && src.includes("ecopages-react")) {
+        continue;
+      }
+      const cloned = newEl.cloneNode(true);
+      if (cloned.tagName === "LINK" && cloned.rel === "stylesheet") {
+        const loadPromise = new Promise((resolve) => {
+          cloned.onload = () => resolve();
+          cloned.onerror = () => resolve();
+        });
+        stylesheetPromises.push(loadPromise);
+      }
+      currentHead.appendChild(cloned);
+    } else if (key === "title" && currentEl.textContent !== newEl.textContent) {
+      currentEl.textContent = newEl.textContent;
+    } else if (key.startsWith("style:") && currentEl.textContent !== newEl.textContent) {
+      currentEl.textContent = newEl.textContent;
+    }
+  }
+  for (const newEl of Array.from(newHead.children)) {
+    const key = getHeadElementKey(newEl);
+    if (!key) {
+      currentHead.appendChild(newEl.cloneNode(true));
+    }
+  }
+  if (stylesheetPromises.length > 0) {
+    await Promise.all(stylesheetPromises);
+  }
+  for (const [key, el] of currentElements) {
+    if (!newElements.has(key)) {
+      const shouldPreserve = PRESERVE_SELECTORS.some((sel) => el.matches(sel));
+      if (!shouldPreserve) {
+        elementsToRemove.push(el);
+      }
+    }
+  }
+  return () => {
+    for (const el of elementsToRemove) {
+      el.remove();
+    }
+  };
+}
+export {
+  morphHead
+};