@flight-framework/router 0.0.1

package/README.md

@@ -0,0 +1,144 @@
+# @flight-framework/router
+
+Agnostic client-side routing primitives for Flight Framework.
+
+## Philosophy
+
+- Zero external runtime dependencies
+- Works with React, Vue, Svelte, or vanilla JS
+- SSR-safe (works on server and client)
+- No vendor lock-in
+
+## Installation
+
+```bash
+npm install @flight-framework/router
+```
+
+## Usage
+
+### With React
+
+```tsx
+import { RouterProvider, Link, useRouter } from '@flight-framework/router';
+
+// Wrap your app
+function App() {
+    return (
+        <RouterProvider initialPath={url}>
+            <Navigation />
+            <Content />
+        </RouterProvider>
+    );
+}
+
+// Use Link for navigation
+function Navigation() {
+    return (
+        <nav>
+            <Link href="/">Home</Link>
+            <Link href="/docs" prefetch>Docs</Link>
+            <Link href="/about">About</Link>
+        </nav>
+    );
+}
+
+// Use hooks to access router state
+function Content() {
+    const { path, navigate } = useRouter();
+    
+    return (
+        <main>
+            <p>Current path: {path}</p>
+            <button onClick={() => navigate('/dashboard')}>
+                Go to Dashboard
+            </button>
+        </main>
+    );
+}
+```
+
+### Hooks
+
+```tsx
+// Get current path and navigation functions
+const { path, searchParams, navigate, back, forward } = useRouter();
+
+// Get route parameters (from dynamic routes like [slug])
+const { slug } = useParams<{ slug: string }>();
+
+// Get and set search params
+const [searchParams, setSearchParams] = useSearchParams();
+
+// Get current pathname
+const pathname = usePathname();
+```
+
+### Programmatic Navigation
+
+```ts
+import { navigate, prefetch } from '@flight-framework/router';
+
+// Navigate to a path
+navigate('/docs');
+
+// Replace history instead of push
+navigate('/login', { replace: true });
+
+// Navigate without scrolling to top
+navigate('/next-page', { scroll: false });
+
+// Pass state data
+navigate('/dashboard', { state: { from: '/login' } });
+
+// Prefetch a route
+prefetch('/heavy-page');
+```
+
+### Route Matching
+
+```ts
+import { matchRoute, parseParams, generatePath } from '@flight-framework/router';
+
+// Check if a path matches a pattern
+const { matched, params } = matchRoute('/docs/routing', '/docs/:slug');
+// matched: true, params: { slug: 'routing' }
+
+// Parse params from a path
+const params = parseParams('/blog/2024/my-post', '/blog/:year/:slug');
+// { year: '2024', slug: 'my-post' }
+
+// Generate a path from pattern and params
+const path = generatePath('/docs/:slug', { slug: 'api-routes' });
+// '/docs/api-routes'
+```
+
+### Link Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `string` | required | Target URL path |
+| `prefetch` | `boolean` | `false` | Prefetch target on hover |
+| `replace` | `boolean` | `false` | Replace history entry |
+| `scroll` | `boolean` | `true` | Scroll to top on navigate |
+| `target` | `string` | - | Link target (_blank, etc) |
+| `className` | `string` | - | CSS class |
+
+## SSR Support
+
+The router is SSR-safe. Pass the initial path from your server:
+
+```tsx
+// entry-server.tsx
+export function render(url: string) {
+    return renderToString(
+        <RouterProvider initialPath={url}>
+            <App />
+        </RouterProvider>
+    );
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Type definitions for @flight-framework/router
+ */
+/**
+ * Router context value provided to all components
+ */
+interface RouterContextValue {
+    /** Current pathname (e.g., '/docs/routing') */
+    path: string;
+    /** URL search params as object */
+    searchParams: URLSearchParams;
+    /** Navigate to a new path */
+    navigate: (to: string, options?: NavigateOptions) => void;
+    /** Go back in history */
+    back: () => void;
+    /** Go forward in history */
+    forward: () => void;
+}
+/**
+ * Props for RouterProvider component
+ */
+interface RouterProviderProps {
+    /** Child components */
+    children: unknown;
+    /** Initial path for SSR (server passes request URL) */
+    initialPath?: string;
+    /** Base path for the router (e.g., '/app') */
+    basePath?: string;
+}
+/**
+ * Props for Link component
+ */
+interface LinkProps {
+    /** Target URL path */
+    href: string;
+    /** Child content */
+    children: unknown;
+    /** CSS class name */
+    className?: string;
+    /** Open in new tab */
+    target?: string;
+    /** Link relationship */
+    rel?: string;
+    /** Prefetch the target page */
+    prefetch?: boolean;
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** Aria label for accessibility */
+    'aria-label'?: string;
+    /** Click handler */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * Options for programmatic navigation
+ */
+interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** State data to pass to the new route */
+    state?: unknown;
+}
+/**
+ * Dynamic route parameters extracted from URL
+ */
+type RouteParams<T extends string = string> = Record<T, string>;
+/**
+ * Search params as key-value pairs
+ */
+type SearchParams = Record<string, string | string[]>;
+
+/**
+ * Router Context and Provider
+ *
+ * Provides routing state to the component tree.
+ * SSR-safe: works on both server and client.
+ */
+
+/**
+ * React Context for router
+ * Only used if React is available
+ */
+declare let RouterContext: unknown;
+declare let RouterProvider: unknown;
+declare let useRouter: () => RouterContextValue;
+
+/**
+ * Link Component
+ *
+ * Client-side navigation link with prefetching support.
+ * Works with React or as a vanilla function.
+ */
+
+declare let Link: unknown;
+
+/**
+ * Router Hooks
+ *
+ * React hooks for accessing router state.
+ * These require React to be available.
+ */
+
+declare let useParams: <T extends RouteParams = RouteParams>() => T;
+declare let useSearchParams: () => [URLSearchParams, (params: SearchParams | URLSearchParams) => void];
+declare let usePathname: () => string;
+
+/**
+ * Navigation Utilities
+ *
+ * Programmatic navigation and route matching utilities.
+ */
+
+/**
+ * Navigate programmatically to a new path
+ *
+ * @example
+ * ```ts
+ * navigate('/docs');
+ * navigate('/login', { replace: true });
+ * navigate('/dashboard', { scroll: false, state: { from: '/home' } });
+ * ```
+ */
+declare function navigate(to: string, options?: NavigateOptions): void;
+/**
+ * Prefetch a route's assets
+ * Creates a prefetch link for the target URL
+ *
+ * @example
+ * ```ts
+ * prefetch('/docs'); // Prefetch when user hovers
+ * ```
+ */
+declare function prefetch(href: string): void;
+/**
+ * Match a pathname against a route pattern
+ *
+ * @example
+ * ```ts
+ * matchRoute('/docs/routing', '/docs/:slug');
+ * // Returns: { params: { slug: 'routing' }, matched: true }
+ * ```
+ */
+declare function matchRoute(pathname: string, pattern: string): {
+    matched: boolean;
+    params: RouteParams;
+};
+/**
+ * Parse parameters from a matched route
+ *
+ * @example
+ * ```ts
+ * parseParams('/blog/2024/my-post', '/blog/:year/:slug');
+ * // Returns: { year: '2024', slug: 'my-post' }
+ * ```
+ */
+declare function parseParams(pathname: string, pattern: string): RouteParams;
+
+export { Link, type LinkProps, type NavigateOptions, type RouteParams, RouterContext, type RouterContextValue, RouterProvider, type RouterProviderProps, type SearchParams, matchRoute, navigate, parseParams, prefetch, useParams, usePathname, useRouter, useSearchParams };

package/dist/index.js

@@ -0,0 +1,323 @@
+// src/context.ts
+var isBrowser = typeof window !== "undefined";
+var currentContext = {
+  path: "/",
+  searchParams: new URLSearchParams(),
+  navigate: () => {
+  },
+  back: () => {
+  },
+  forward: () => {
+  }
+};
+var subscribers = /* @__PURE__ */ new Set();
+function subscribe(callback) {
+  subscribers.add(callback);
+  return () => subscribers.delete(callback);
+}
+function getRouterContext() {
+  return currentContext;
+}
+function updateContext(updates) {
+  currentContext = { ...currentContext, ...updates };
+  subscribers.forEach((cb) => cb(currentContext));
+}
+function navigateTo(to, options = {}) {
+  if (!isBrowser) return;
+  const { replace = false, scroll = true, state } = options;
+  if (replace) {
+    window.history.replaceState(state ?? null, "", to);
+  } else {
+    window.history.pushState(state ?? null, "", to);
+  }
+  const url = new URL(to, window.location.origin);
+  updateContext({
+    path: url.pathname,
+    searchParams: url.searchParams
+  });
+  if (scroll) {
+    window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+  }
+}
+var RouterContext = null;
+var RouterProvider = null;
+var useRouter = getRouterContext;
+if (typeof globalThis !== "undefined") {
+  try {
+    const React = globalThis.React;
+    if (React?.createContext) {
+      const { createContext, useState, useEffect, useContext } = React;
+      const ReactRouterContext = createContext(currentContext);
+      RouterContext = ReactRouterContext;
+      RouterProvider = function FlightRouterProvider({
+        children,
+        initialPath,
+        basePath = ""
+      }) {
+        const [routerState, setRouterState] = useState(() => {
+          const path = isBrowser ? window.location.pathname : initialPath || "/";
+          const searchParams = isBrowser ? new URLSearchParams(window.location.search) : new URLSearchParams();
+          return {
+            path: basePath && path.startsWith(basePath) ? path.slice(basePath.length) || "/" : path,
+            searchParams,
+            navigate: navigateTo,
+            back: () => isBrowser && window.history.back(),
+            forward: () => isBrowser && window.history.forward()
+          };
+        });
+        useEffect(() => {
+          if (!isBrowser) return;
+          const handlePopState = () => {
+            let path = window.location.pathname;
+            if (basePath && path.startsWith(basePath)) {
+              path = path.slice(basePath.length) || "/";
+            }
+            setRouterState((prev) => ({
+              ...prev,
+              path,
+              searchParams: new URLSearchParams(window.location.search)
+            }));
+          };
+          window.addEventListener("popstate", handlePopState);
+          return () => window.removeEventListener("popstate", handlePopState);
+        }, [basePath]);
+        useEffect(() => {
+          return subscribe((ctx) => {
+            setRouterState((prev) => ({
+              ...prev,
+              path: ctx.path,
+              searchParams: ctx.searchParams
+            }));
+          });
+        }, []);
+        return React.createElement(
+          ReactRouterContext.Provider,
+          { value: routerState },
+          children
+        );
+      };
+      useRouter = function useFlightRouter() {
+        return useContext(ReactRouterContext);
+      };
+    }
+  } catch {
+  }
+}
+
+// src/link.ts
+var isBrowser2 = typeof window !== "undefined";
+function handleLinkClick(href, options, event) {
+  if (event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)) {
+    return;
+  }
+  event?.preventDefault();
+  const { navigate: navigate2 } = getRouterContext();
+  navigate2(href, options);
+}
+function isExternalUrl(href) {
+  if (!href) return false;
+  return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:");
+}
+function prefetchRoute(href) {
+  if (!isBrowser2) return;
+  const link = document.createElement("link");
+  link.rel = "prefetch";
+  link.href = href;
+  document.head.appendChild(link);
+}
+var Link = null;
+if (typeof globalThis !== "undefined") {
+  try {
+    const React = globalThis.React;
+    if (React?.createElement) {
+      const { useCallback, useEffect, useRef } = React;
+      Link = function FlightLink({
+        href,
+        children,
+        className,
+        target,
+        rel,
+        prefetch: prefetch2 = false,
+        replace = false,
+        scroll = true,
+        onClick,
+        ...props
+      }) {
+        const linkRef = useRef(null);
+        const isExternal = isExternalUrl(href);
+        const handleClick = useCallback((e) => {
+          if (onClick) {
+            onClick(e);
+            if (e.defaultPrevented) return;
+          }
+          if (isExternal || target === "_blank") return;
+          handleLinkClick(href, { replace, scroll }, e);
+        }, [href, isExternal, target, replace, scroll, onClick]);
+        useEffect(() => {
+          if (!prefetch2 || isExternal || !isBrowser2) return;
+          const link = linkRef.current;
+          if (!link) return;
+          let prefetched = false;
+          const doPrefetch = () => {
+            if (!prefetched) {
+              prefetched = true;
+              prefetchRoute(href);
+            }
+          };
+          link.addEventListener("mouseenter", doPrefetch);
+          link.addEventListener("focus", doPrefetch);
+          return () => {
+            link.removeEventListener("mouseenter", doPrefetch);
+            link.removeEventListener("focus", doPrefetch);
+          };
+        }, [href, prefetch2, isExternal]);
+        const computedRel = isExternal && target === "_blank" ? rel || "noopener noreferrer" : rel;
+        return React.createElement("a", {
+          ref: linkRef,
+          href,
+          className,
+          target,
+          rel: computedRel,
+          onClick: handleClick,
+          ...props
+        }, children);
+      };
+    }
+  } catch {
+  }
+}
+
+// src/hooks.ts
+var isBrowser3 = typeof window !== "undefined";
+var useParams = () => ({});
+var useSearchParams = () => [new URLSearchParams(), () => {
+}];
+var usePathname = () => "/";
+if (typeof globalThis !== "undefined") {
+  try {
+    const React = globalThis.React;
+    if (React?.useState) {
+      const { useState, useEffect, useCallback, useMemo } = React;
+      useParams = function useFlightParams() {
+        const [params, setParams] = useState({});
+        useEffect(() => {
+          const storedParams = window.__FLIGHT_PARAMS__;
+          if (storedParams) {
+            setParams(storedParams);
+          }
+        }, []);
+        return params;
+      };
+      useSearchParams = function useFlightSearchParams() {
+        const [searchParams, setSearchParamsState] = useState(
+          () => isBrowser3 ? new URLSearchParams(window.location.search) : new URLSearchParams()
+        );
+        useEffect(() => {
+          if (!isBrowser3) return;
+          const handleChange = () => {
+            setSearchParamsState(new URLSearchParams(window.location.search));
+          };
+          window.addEventListener("popstate", handleChange);
+          return () => window.removeEventListener("popstate", handleChange);
+        }, []);
+        const setSearchParams = useCallback((newParams) => {
+          if (!isBrowser3) return;
+          let params;
+          if (newParams instanceof URLSearchParams) {
+            params = newParams;
+          } else {
+            params = new URLSearchParams();
+            Object.entries(newParams).forEach(([key, value]) => {
+              if (Array.isArray(value)) {
+                value.forEach((v) => params.append(key, v));
+              } else {
+                params.set(key, value);
+              }
+            });
+          }
+          const newUrl = `${window.location.pathname}?${params.toString()}`;
+          window.history.pushState(null, "", newUrl);
+          setSearchParamsState(params);
+        }, []);
+        return [searchParams, setSearchParams];
+      };
+      usePathname = function useFlightPathname() {
+        const { path } = getRouterContext();
+        const [pathname, setPathname] = useState(path);
+        useEffect(() => {
+          if (!isBrowser3) return;
+          const handleChange = () => {
+            setPathname(window.location.pathname);
+          };
+          window.addEventListener("popstate", handleChange);
+          return () => window.removeEventListener("popstate", handleChange);
+        }, []);
+        return pathname;
+      };
+    }
+  } catch {
+  }
+}
+
+// src/navigate.ts
+var isBrowser4 = typeof window !== "undefined";
+function navigate(to, options = {}) {
+  const { navigate: routerNavigate } = getRouterContext();
+  routerNavigate(to, options);
+}
+function prefetch(href) {
+  if (!isBrowser4) return;
+  const existing = document.querySelector(`link[rel="prefetch"][href="${href}"]`);
+  if (existing) return;
+  const link = document.createElement("link");
+  link.rel = "prefetch";
+  link.href = href;
+  document.head.appendChild(link);
+}
+function patternToRegex(pattern) {
+  const paramNames = [];
+  let regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\\\[\.\.\.(\w+)\\\]/g, (_, name) => {
+    paramNames.push(name);
+    return "(.+)";
+  }).replace(/\\\[(\w+)\\\]/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  }).replace(/:(\w+)/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+  regexStr = `^${regexStr}$`;
+  return {
+    regex: new RegExp(regexStr),
+    paramNames
+  };
+}
+function matchRoute(pathname, pattern) {
+  const { regex, paramNames } = patternToRegex(pattern);
+  const match = pathname.match(regex);
+  if (!match) {
+    return { matched: false, params: {} };
+  }
+  const params = {};
+  paramNames.forEach((name, index) => {
+    params[name] = match[index + 1] || "";
+  });
+  return { matched: true, params };
+}
+function parseParams(pathname, pattern) {
+  const { params } = matchRoute(pathname, pattern);
+  return params;
+}
+export {
+  Link,
+  RouterContext,
+  RouterProvider,
+  matchRoute,
+  navigate,
+  parseParams,
+  prefetch,
+  useParams,
+  usePathname,
+  useRouter,
+  useSearchParams
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@flight-framework/router",
+    "version": "0.0.1",
+    "description": "Agnostic client-side routing primitives for Flight Framework",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format esm --dts --clean",
+        "dev": "tsup src/index.ts --format esm --dts --watch"
+    },
+    "keywords": [
+        "flight",
+        "router",
+        "spa",
+        "navigation",
+        "ssr"
+    ],
+    "author": "Flight Framework",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/EliosLT/Flight-framework",
+        "directory": "packages/router"
+    },
+    "devDependencies": {
+        "tsup": "^8.0.0",
+        "typescript": "^5.3.0"
+    },
+    "peerDependencies": {
+        "react": ">=18.0.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    }
+}