what-router 0.1.0

package/index.d.ts

@@ -0,0 +1,165 @@
+// What Framework Router - TypeScript Definitions
+
+import { VNode, VNodeChild, Component, Signal, Computed } from '../core';
+
+// --- Route State ---
+
+export interface RouteState {
+  /** Current full URL */
+  readonly url: string;
+  /** Current pathname */
+  readonly path: string;
+  /** Route parameters */
+  readonly params: Record<string, string>;
+  /** Query parameters */
+  readonly query: Record<string, string>;
+  /** URL hash */
+  readonly hash: string;
+  /** Navigation in progress */
+  readonly isNavigating: boolean;
+  /** Navigation error if any */
+  readonly error: Error | null;
+}
+
+export const route: RouteState;
+
+// --- Navigation ---
+
+export interface NavigateOptions {
+  /** Replace current history entry */
+  replace?: boolean;
+  /** History state object */
+  state?: any;
+  /** Use View Transitions API */
+  transition?: boolean;
+}
+
+/** Navigate to a new URL */
+export function navigate(to: string, options?: NavigateOptions): Promise<void>;
+
+// --- Route Configuration ---
+
+export interface RouteConfig {
+  /** URL path pattern */
+  path: string;
+  /** Page component */
+  component: Component<RouteComponentProps>;
+  /** Layout wrapper */
+  layout?: Component<LayoutProps>;
+  /** Loading component */
+  loading?: Component<{}>;
+  /** Error component */
+  error?: Component<{ error: Error }>;
+  /** Route middleware */
+  middleware?: RouteMiddleware[];
+}
+
+export interface RouteComponentProps {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  route: RouteConfig;
+}
+
+export interface LayoutProps {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  children?: VNodeChild;
+}
+
+export type RouteMiddleware = (props: RouteComponentProps) => boolean | Promise<boolean>;
+
+// --- Router Component ---
+
+export interface RouterProps {
+  routes: RouteConfig[];
+  fallback?: Component<{}>;
+  globalLayout?: Component<{ children?: VNodeChild }>;
+}
+
+export function Router(props: RouterProps): VNode;
+
+// --- Link Component ---
+
+export interface LinkProps {
+  href: string;
+  class?: string;
+  className?: string;
+  replace?: boolean;
+  prefetch?: boolean;
+  activeClass?: string;
+  exactActiveClass?: string;
+  transition?: boolean;
+  children?: VNodeChild;
+  [key: string]: any;
+}
+
+export function Link(props: LinkProps): VNode;
+export function NavLink(props: LinkProps): VNode;
+
+// --- Route Helpers ---
+
+/** Define routes from object config */
+export function defineRoutes(config: Record<string, Component | Partial<RouteConfig>>): RouteConfig[];
+
+/** Create nested routes with shared options */
+export function nestedRoutes(
+  basePath: string,
+  children: RouteConfig[],
+  options?: { layout?: Component; loading?: Component; error?: Component }
+): RouteConfig[];
+
+/** Group routes without affecting URLs */
+export function routeGroup(
+  name: string,
+  routes: RouteConfig[],
+  options?: { layout?: Component; middleware?: RouteMiddleware[] }
+): RouteConfig[];
+
+// --- Redirect ---
+
+export function Redirect(props: { to: string }): null;
+
+// --- Guards ---
+
+/** Create a route guard */
+export function guard(
+  check: (props: RouteComponentProps) => boolean,
+  fallback: string | Component
+): <P>(component: Component<P>) => Component<P>;
+
+/** Create an async route guard */
+export function asyncGuard(
+  check: (props: RouteComponentProps) => Promise<boolean>,
+  options?: { fallback?: string | Component; loading?: Component }
+): <P>(component: Component<P>) => Component<P>;
+
+// --- Prefetch ---
+
+export function prefetch(href: string): void;
+
+// --- Scroll Restoration ---
+
+export function enableScrollRestoration(): void;
+
+// --- View Transitions ---
+
+export function viewTransitionName(name: string): { style: { viewTransitionName: string } };
+export function setViewTransition(type: string): void;
+
+// --- useRoute Hook ---
+
+export interface UseRouteResult {
+  path: Computed<string>;
+  params: Computed<Record<string, string>>;
+  query: Computed<Record<string, string>>;
+  hash: Computed<string>;
+  isNavigating: Computed<boolean>;
+  navigate: typeof navigate;
+  prefetch: typeof prefetch;
+}
+
+export function useRoute(): UseRouteResult;
+
+// --- Outlet ---
+
+export function Outlet(props: { children?: VNodeChild }): VNodeChild;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "what-router",
+  "version": "0.1.0",
+  "description": "What Framework - File-based & programmatic router with View Transitions",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "router",
+    "file-based-routing",
+    "view-transitions",
+    "spa",
+    "what-framework"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "what-core": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aspect/what-fw"
+  }
+}

package/src/index.js

@@ -0,0 +1,459 @@
+// What Framework - Router
+// Production-grade file-based routing with nested layouts, loading states,
+// route groups, view transitions, and middleware.
+
+import { signal, effect, computed, batch, h } from 'what-core';
+
+// --- Route State (global singleton) ---
+
+const _url = signal(typeof location !== 'undefined' ? location.pathname + location.search + location.hash : '/');
+const _params = signal({});
+const _query = signal({});
+const _isNavigating = signal(false);
+const _navigationError = signal(null);
+
+export const route = {
+  get url() { return _url(); },
+  get path() { return _url().split('?')[0].split('#')[0]; },
+  get params() { return _params(); },
+  get query() { return _query(); },
+  get hash() {
+    const h = _url().split('#')[1];
+    return h ? '#' + h : '';
+  },
+  get isNavigating() { return _isNavigating(); },
+  get error() { return _navigationError(); },
+};
+
+// --- Navigation with View Transitions ---
+
+export async function navigate(to, opts = {}) {
+  const { replace = false, state = null, transition = true } = opts;
+
+  // Don't navigate if already on the same URL
+  if (to === _url()) return;
+
+  _isNavigating.set(true);
+  _navigationError.set(null);
+
+  const doNavigation = () => {
+    if (replace) {
+      history.replaceState(state, '', to);
+    } else {
+      history.pushState(state, '', to);
+    }
+    _url.set(to);
+    _isNavigating.set(false);
+  };
+
+  // Use View Transitions API if available and enabled
+  if (transition && typeof document !== 'undefined' && document.startViewTransition) {
+    try {
+      await document.startViewTransition(doNavigation).finished;
+    } catch (e) {
+      // Transition failed, navigation still happened
+    }
+  } else {
+    doNavigation();
+  }
+}
+
+// Back/forward support
+if (typeof window !== 'undefined') {
+  window.addEventListener('popstate', () => {
+    _url.set(location.pathname + location.search + location.hash);
+  });
+}
+
+// --- Route Matching ---
+
+function compilePath(path) {
+  // /users/:id -> regex + param names
+  // /posts/* -> catch-all
+  // /[slug] -> dynamic (file-based syntax)
+  // (group) -> route group (ignored in URL)
+
+  // Remove route groups from path (they don't affect URL matching)
+  const normalized = path
+    .replace(/\([\w-]+\)\//g, '') // Remove (group)/ prefixes
+    .replace(/\[\.\.\.(\w+)\]/g, (_, name) => `*:${name}`) // Preserve catch-all name
+    .replace(/\[(\w+)\]/g, ':$1'); // File-based [param] to :param
+
+  const paramNames = [];
+  let catchAll = null;
+
+  const regexStr = normalized
+    .split('/')
+    .map(segment => {
+      if (segment.startsWith('*:')) {
+        catchAll = segment.slice(2);
+        paramNames.push(catchAll);
+        return '(.+)';
+      }
+      if (segment === '*') {
+        catchAll = 'rest';
+        paramNames.push('rest');
+        return '(.+)';
+      }
+      if (segment.startsWith(':')) {
+        paramNames.push(segment.slice(1));
+        return '([^/]+)';
+      }
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('/');
+
+  const regex = new RegExp(`^${regexStr}$`);
+  return { regex, paramNames, catchAll };
+}
+
+function matchRoute(path, routes) {
+  // Sort routes by specificity (more specific first)
+  const sorted = [...routes].sort((a, b) => {
+    const aSpecific = (a.path.match(/:/g) || []).length + (a.path.includes('*') ? 100 : 0);
+    const bSpecific = (b.path.match(/:/g) || []).length + (b.path.includes('*') ? 100 : 0);
+    return aSpecific - bSpecific;
+  });
+
+  for (const route of sorted) {
+    const { regex, paramNames } = compilePath(route.path);
+    const match = path.match(regex);
+    if (match) {
+      const params = {};
+      paramNames.forEach((name, i) => {
+        params[name] = decodeURIComponent(match[i + 1]);
+      });
+      return { route, params };
+    }
+  }
+  return null;
+}
+
+function parseQuery(search) {
+  const params = {};
+  if (!search) return params;
+  const qs = search.startsWith('?') ? search.slice(1) : search;
+  for (const pair of qs.split('&')) {
+    const [key, val] = pair.split('=');
+    if (key) params[decodeURIComponent(key)] = val ? decodeURIComponent(val) : '';
+  }
+  return params;
+}
+
+// --- Nested Layouts ---
+
+// Build the layout chain for a route
+function buildLayoutChain(route, routes) {
+  const layouts = [];
+
+  // Check for nested layouts based on path segments
+  const segments = route.path.split('/').filter(Boolean);
+  let currentPath = '';
+
+  for (const segment of segments) {
+    currentPath += '/' + segment;
+
+    // Find layout for this path level
+    const layoutRoute = routes.find(r =>
+      r.layout && r.path === currentPath + '/_layout'
+    );
+    if (layoutRoute) {
+      layouts.push(layoutRoute.layout);
+    }
+  }
+
+  // Add route's own layout if specified
+  if (route.layout) {
+    layouts.push(route.layout);
+  }
+
+  return layouts;
+}
+
+// --- Router Component ---
+
+export function Router({ routes, fallback, globalLayout }) {
+  const currentUrl = _url();
+  const path = currentUrl.split('?')[0].split('#')[0];
+  const search = currentUrl.split('?')[1]?.split('#')[0] || '';
+  const isNavigating = _isNavigating();
+
+  const matched = matchRoute(path, routes);
+
+  if (matched) {
+    batch(() => {
+      _params.set(matched.params);
+      _query.set(parseQuery(search));
+    });
+
+    const { route: r, params } = matched;
+
+    // Build element with loading state support
+    let element;
+
+    if (r.loading && isNavigating) {
+      element = h(r.loading, {});
+    } else {
+      element = h(r.component, {
+        params,
+        query: parseQuery(search),
+        route: r,
+      });
+    }
+
+    // Wrap with nested layouts (innermost to outermost)
+    const layouts = buildLayoutChain(r, routes);
+    for (const Layout of layouts.reverse()) {
+      element = h(Layout, { params, query: parseQuery(search) }, element);
+    }
+
+    // Global layout wrapper
+    if (globalLayout) {
+      element = h(globalLayout, {}, element);
+    }
+
+    return element;
+  }
+
+  // 404
+  if (fallback) return h(fallback, {});
+  return h('div', { class: 'what-404' },
+    h('h1', null, '404'),
+    h('p', null, 'Page not found')
+  );
+}
+
+// --- Link Component ---
+
+export function Link({
+  href,
+  class: cls,
+  className,
+  children,
+  replace: rep,
+  prefetch: shouldPrefetch = true,
+  activeClass = 'active',
+  exactActiveClass = 'exact-active',
+  transition = true,
+  ...rest
+}) {
+  const currentPath = route.path;
+  const isActive = currentPath.startsWith(href);
+  const isExactActive = currentPath === href;
+
+  const classes = [
+    cls || className,
+    isActive && activeClass,
+    isExactActive && exactActiveClass,
+  ].filter(Boolean).join(' ') || undefined;
+
+  return h('a', {
+    href,
+    class: classes,
+    onClick: (e) => {
+      // Only intercept left-clicks without modifiers
+      if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey || e.button !== 0) return;
+      e.preventDefault();
+      navigate(href, { replace: rep, transition });
+    },
+    onMouseenter: shouldPrefetch ? () => prefetch(href) : undefined,
+    ...rest,
+  }, ...(Array.isArray(children) ? children : [children]));
+}
+
+// --- NavLink with active states ---
+
+export function NavLink(props) {
+  return Link(props);
+}
+
+// --- Define Routes Helper ---
+// Creates route config from a flat object for convenience.
+
+export function defineRoutes(config) {
+  return Object.entries(config).map(([path, value]) => {
+    if (typeof value === 'function') {
+      return { path, component: value };
+    }
+    // Object form with layout, middleware, loading, error, etc.
+    return { path, ...value };
+  });
+}
+
+// --- Nested Route Helper ---
+
+export function nestedRoutes(basePath, children, options = {}) {
+  const { layout, loading, error } = options;
+
+  return children.map(child => ({
+    ...child,
+    path: basePath + child.path,
+    layout: child.layout || layout,
+    loading: child.loading || loading,
+    error: child.error || error,
+  }));
+}
+
+// --- Route Groups ---
+// Group routes without affecting URL structure
+
+export function routeGroup(name, routes, options = {}) {
+  const { layout, middleware } = options;
+
+  return routes.map(route => ({
+    ...route,
+    _group: name,
+    layout: route.layout || layout,
+    middleware: [...(route.middleware || []), ...(middleware || [])],
+  }));
+}
+
+// --- Redirect ---
+
+export function Redirect({ to }) {
+  navigate(to, { replace: true });
+  return null;
+}
+
+// --- Route Guards / Middleware ---
+
+export function guard(check, fallback) {
+  return (Component) => {
+    return function GuardedRoute(props) {
+      const result = check(props);
+
+      // Support async guards
+      if (result instanceof Promise) {
+        // Return loading while checking
+        return h('div', { class: 'what-guard-loading' }, 'Loading...');
+      }
+
+      if (result) {
+        return h(Component, props);
+      }
+
+      if (typeof fallback === 'string') {
+        navigate(fallback, { replace: true });
+        return null;
+      }
+      return h(fallback, props);
+    };
+  };
+}
+
+// Async guard with suspense
+export function asyncGuard(check, options = {}) {
+  const { fallback = '/login', loading = null } = options;
+
+  return (Component) => {
+    return function AsyncGuardedRoute(props) {
+      const status = signal('pending');
+      const checkResult = signal(null);
+
+      effect(() => {
+        Promise.resolve(check(props))
+          .then(result => {
+            checkResult.set(result);
+            status.set(result ? 'allowed' : 'denied');
+          })
+          .catch(() => status.set('denied'));
+      });
+
+      const currentStatus = status();
+
+      if (currentStatus === 'pending') {
+        return loading ? h(loading, {}) : null;
+      }
+
+      if (currentStatus === 'allowed') {
+        return h(Component, props);
+      }
+
+      if (typeof fallback === 'string') {
+        navigate(fallback, { replace: true });
+        return null;
+      }
+      return h(fallback, props);
+    };
+  };
+}
+
+// --- Prefetch ---
+// Hint the browser to prefetch a route's assets.
+
+const prefetchedUrls = new Set();
+
+export function prefetch(href) {
+  if (typeof document === 'undefined') return;
+  if (prefetchedUrls.has(href)) return;
+  prefetchedUrls.add(href);
+
+  const link = document.createElement('link');
+  link.rel = 'prefetch';
+  link.href = href;
+  document.head.appendChild(link);
+}
+
+// --- Scroll Restoration ---
+
+const scrollPositions = new Map();
+
+export function enableScrollRestoration() {
+  if (typeof window === 'undefined') return;
+
+  // Save scroll position before navigation
+  window.addEventListener('beforeunload', () => {
+    scrollPositions.set(location.pathname, window.scrollY);
+  });
+
+  // Restore scroll position after navigation
+  effect(() => {
+    const path = route.path;
+    const savedPosition = scrollPositions.get(path);
+
+    requestAnimationFrame(() => {
+      if (savedPosition !== undefined) {
+        window.scrollTo(0, savedPosition);
+      } else if (route.hash) {
+        const el = document.querySelector(route.hash);
+        el?.scrollIntoView();
+      } else {
+        window.scrollTo(0, 0);
+      }
+    });
+  });
+}
+
+// --- View Transition Helpers ---
+
+export function viewTransitionName(name) {
+  return { style: { viewTransitionName: name } };
+}
+
+// Configure view transition types
+export function setViewTransition(type) {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset.transition = type;
+}
+
+// --- useRoute Hook ---
+
+export function useRoute() {
+  return {
+    path: computed(() => route.path),
+    params: computed(() => route.params),
+    query: computed(() => route.query),
+    hash: computed(() => route.hash),
+    isNavigating: computed(() => route.isNavigating),
+    navigate,
+    prefetch,
+  };
+}
+
+// --- Outlet Component ---
+// For nested route rendering
+
+export function Outlet({ children }) {
+  // Children passed from parent layout
+  return children || null;
+}