@flow-os/router 0.0.47-dev.1772054223

package/README.md

@@ -0,0 +1,7 @@
+# @flow-os/router
+
+Router client-side: file-based routes, lazy load, 404.
+
+## API (`index.ts`)
+
+- `APP_ID`, `App`, `RouteModule`, `RunOptions`, `createRouter`, `run`.

package/config/client/root.tsx

@@ -0,0 +1,6 @@
+import './root.css';
+import { App } from '@flow-os/router';
+
+export default function Root() {
+  return <App />;
+}

package/config/client/routes/404.tsx

@@ -0,0 +1,23 @@
+export default function NotFound(path: string) {
+  return (
+    <div
+      role="alert"
+      style={{
+        minHeight: '100vh',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: '0.5rem',
+      }}
+    >
+      <h1 style={{ margin: 0, fontSize: '2rem' }}>404</h1>
+      <p style={{ margin: 0, color: 'var(--muted, #666)' }}>
+        {path ? `Page not found: ${path}` : 'Page not found'}
+      </p>
+      <a href="/" style={{ marginTop: '1rem' }}>
+        Back to home
+      </a>
+    </div>
+  );
+}

package/config/client/routes/index.tsx

@@ -0,0 +1,10 @@
+export default function Home() {
+  return (
+    <div>
+      <h1>Welcome</h1>
+      <p>
+        <a href="/about">About</a>
+      </p>
+    </div>
+  );
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@flow-os/router",
+  "version": "0.0.47-dev.1772054223",
+  "license": "PolyForm-Shield-1.0.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime/index.ts",
+      "import": "./src/jsx-runtime/index.ts",
+      "default": "./src/jsx-runtime/index.ts"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./src/jsx-runtime/index.ts",
+      "import": "./src/jsx-runtime/index.ts",
+      "default": "./src/jsx-runtime/index.ts"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// ========== Core ==========
+// App = root component (one <App /> in layout). run = call once in entry: run(App, import.meta.glob('./routes/**/*.{ts,tsx}'))
+export { App, run } from './router';
+
+// ========== Utilities ==========
+export { go, params } from './router';
+export { base, path, href, query, setQuery } from './router/utils';
+/*
+base() => 'https://localhost:5173'
+
+path() => '/posts/123'
+
+href() => 'https://localhost:5173/posts/123'
+
+params() => ['posts', '123']
+
+query() => URLSearchParams { page: '2' }
+
+setQuery({ page: '2' }) => 'https://localhost:5173/posts/123?page=2'
+*/

package/src/jsx-runtime/index.ts

@@ -0,0 +1,78 @@
+/** Minimal JSX runtime: creates DOM nodes. No React. */
+export const Fragment = Symbol.for('flow.fragment');
+
+type Props = Record<string, unknown> & { children?: unknown };
+type JsxType = string | ((props: Props) => Node | null) | typeof Fragment;
+
+function normalizeChild(c: unknown): Node | string | null {
+  if (c == null) return null;
+  if (typeof c === 'string' || typeof c === 'number') return String(c);
+  if (c instanceof Node) return c;
+  if (Array.isArray(c)) {
+    const frag = document.createDocumentFragment();
+    for (const x of c) {
+      const n = normalizeChild(x);
+      if (n !== null) frag.appendChild(typeof n === 'string' ? document.createTextNode(n) : n);
+    }
+    return frag;
+  }
+  return null;
+}
+
+function appendChildren(el: Node, children: unknown): void {
+  const c = normalizeChild(children);
+  if (c === null) return;
+  if (typeof c === 'string') {
+    el.appendChild(document.createTextNode(c));
+    return;
+  }
+  el.appendChild(c);
+}
+
+function applyProps(el: HTMLElement, props: Props): void {
+  const { children, class: classProp, className: classNameProp, style: styleProp, ...rest } = props;
+  if (classProp != null) el.className = Array.isArray(classProp) ? classProp.join(' ') : String(classProp);
+  if (classNameProp != null) el.className = String(classNameProp);
+  if (styleProp != null && typeof styleProp === 'object') {
+    for (const [k, v] of Object.entries(styleProp)) {
+      if (v != null) (el.style as Record<string, string>)[k] = String(v);
+    }
+  }
+  for (const [k, v] of Object.entries(rest)) {
+    if (v == null) continue;
+    if (k === 'href' && typeof v === 'string') (el as HTMLAnchorElement).href = v;
+    else if (k.startsWith('on') && typeof v === 'function') (el as unknown as Record<string, unknown>)[k.toLowerCase()] = v;
+    else el.setAttribute(k, String(v));
+  }
+  if (children !== undefined) appendChildren(el, children);
+}
+
+export function jsxs(type: JsxType, props: Props, _key?: string | number): Node {
+  return jsx(type, props, _key);
+}
+
+export function jsx(type: JsxType, props: Props, _key?: string | number): Node {
+  if (type === Fragment) {
+    const frag = document.createDocumentFragment();
+    if (props.children !== undefined) appendChildren(frag, props.children);
+    return frag;
+  }
+  if (typeof type === 'function') {
+    const out = type(props);
+    return out ?? document.createDocumentFragment();
+  }
+  const el = document.createElement(type as string);
+  applyProps(el, props);
+  return el;
+}
+
+export function jsxDEV(
+  type: JsxType,
+  props: Props,
+  key: string | number | undefined,
+  _isStatic: boolean,
+  _source: unknown,
+  _self: unknown
+): Node {
+  return jsx(type, props, key as string | undefined);
+}

package/src/jsx-runtime/types.d.ts

@@ -0,0 +1,19 @@
+declare global {
+  namespace JSX {
+    type Element = Node;
+    type ElementType = keyof IntrinsicElements | ((props: Record<string, unknown>) => Element | null);
+
+    interface IntrinsicElements {
+      [tag: string]: {
+        class?: string;
+        className?: string;
+        style?: Record<string, string | number>;
+        href?: string;
+        children?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  }
+}
+
+export {};

package/src/router/index.ts

@@ -0,0 +1,2 @@
+export { App, run, go, params, createRouter, type RouterAPI } from './router';
+export { base, path, href, query, setQuery } from './utils';

package/src/router/matcher.ts

@@ -0,0 +1,105 @@
+import type { RouteEntry } from './types';
+
+const CATCH_ALL_PREFIX = ':*';
+
+/**
+ * Converts a file-path key (e.g. from import.meta.glob) to a route pattern.
+ * - `routes/index.ts` → ''
+ * - `routes/about.ts` → 'about'
+ * - `routes/posts/[id].ts` → 'posts/:id'
+ * - `routes/docs/[...slug].ts` → 'docs/:*slug'
+ */
+export function pathToPattern(key: string): string {
+  const afterRoutes = key.replace(/^.*[/\\]routes[/\\]?/i, '').replace(/\.tsx?$/i, '');
+  const segments = afterRoutes.split(/[/\\]/).filter(Boolean);
+  if (segments.length === 0 || segments[0] === 'index') return '';
+
+  const patternParts = segments.map((seg) => {
+    if (seg.startsWith('[...') && seg.endsWith(']')) {
+      const name = seg.slice(4, -1);
+      return name ? `${CATCH_ALL_PREFIX}${name}` : `${CATCH_ALL_PREFIX}rest`;
+    }
+    if (seg.startsWith('[') && seg.endsWith(']')) {
+      return ':' + seg.slice(1, -1);
+    }
+    return seg;
+  });
+
+  return patternParts.join('/');
+}
+
+/**
+ * Returns true if the pattern string contains a catch-all segment.
+ */
+export function isCatchAllPattern(pattern: string): boolean {
+  return pattern.includes(CATCH_ALL_PREFIX);
+}
+
+/**
+ * Counts static (non-param) segments for route sort order.
+ */
+export function countStaticSegments(pattern: string): number {
+  if (!pattern) return 0;
+  return pattern.split('/').filter((s) => s && !s.startsWith(':') && !s.startsWith(CATCH_ALL_PREFIX)).length;
+}
+
+/**
+ * Matches a path against a pattern. Supports :param and :*catchAll.
+ * - :param matches one segment.
+ * - :*name matches the rest of the path (one param with path segments joined by '/').
+ * Returns params object or null if no match.
+ */
+export function match(pattern: string, path: string): Record<string, string> | null {
+  const patternSegs = pattern ? pattern.split('/').filter(Boolean) : [];
+  const pathSegs = path.replace(/^\//, '').split('/').filter(Boolean);
+
+  const params: Record<string, string> = {};
+  let pi = 0;
+
+  for (let i = 0; i < patternSegs.length; i++) {
+    const seg = patternSegs[i]!;
+    if (seg.startsWith(CATCH_ALL_PREFIX)) {
+      const name = seg.slice(CATCH_ALL_PREFIX.length) || 'rest';
+      params[name] = pathSegs.slice(pi).join('/');
+      return params;
+    }
+    if (pi >= pathSegs.length) return null;
+    if (seg.startsWith(':')) {
+      params[seg.slice(1)] = pathSegs[pi] ?? '';
+      pi++;
+      continue;
+    }
+    if (seg !== pathSegs[pi]) return null;
+    pi++;
+  }
+
+  return pi === pathSegs.length ? params : null;
+}
+
+/**
+ * Builds sorted route entries: more specific first (static > dynamic > catch-all),
+ * then by segment count descending.
+ */
+export function buildRouteEntries(
+  modules: Record<string, () => Promise<import('./types').RouteModule>>
+): RouteEntry[] {
+  const entries: RouteEntry[] = Object.entries(modules).map(([key, loader]) => {
+    const pattern = pathToPattern(key);
+    return {
+      pattern,
+      loader,
+      staticSegments: countStaticSegments(pattern),
+      catchAll: isCatchAllPattern(pattern),
+    };
+  });
+
+  entries.sort((a, b) => {
+    if (a.catchAll !== b.catchAll) return a.catchAll ? 1 : -1;
+    if (a.staticSegments !== b.staticSegments) return b.staticSegments - a.staticSegments;
+    const lenA = a.pattern.split('/').filter(Boolean).length;
+    const lenB = b.pattern.split('/').filter(Boolean).length;
+    return lenB - lenA;
+  });
+
+  return entries;
+}

package/src/router/router.ts

@@ -0,0 +1,184 @@
+import type { RouteModule, RouterOptions, RunOptions } from './types';
+import { buildRouteEntries, match } from './matcher';
+
+let currentRouter: RouterAPI | null = null;
+let currentParams: Record<string, string> = {};
+
+export const APP_ID = 'flow-app';
+
+/** Root container where the router mounts the current page. Use once in root as <App />. */
+export function App(): HTMLDivElement {
+  const el = document.createElement('div');
+  el.id = APP_ID;
+  el.setAttribute('role', 'main');
+  return el;
+}
+
+function setContent(container: HTMLElement, content: Node | string): void {
+  container.innerHTML = '';
+  if (typeof content === 'string') container.textContent = content;
+  else container.appendChild(content);
+}
+
+function defaultNotFound(path: string): Node {
+  const wrap = document.createElement('div');
+  wrap.setAttribute('role', 'alert');
+  const h = document.createElement('h1');
+  h.textContent = '404';
+  const p = document.createElement('p');
+  p.textContent = `Page not found: ${path || '/'}`;
+  wrap.append(h, p);
+  return wrap;
+}
+
+export interface RouterAPI {
+  /** Navigate to a path. Use replace=true to avoid adding a history entry. */
+  go(path: string, replace?: boolean): void;
+  /** Start listening to popstate and link clicks. Call once after mounting App. */
+  start(): void;
+}
+
+const NOT_FOUND_PATTERN = '404';
+
+export function createRouter(
+  modules: Record<string, () => Promise<RouteModule>>,
+  container: HTMLElement,
+  options: RouterOptions = {}
+): RouterAPI {
+  const allEntries = buildRouteEntries(modules);
+  const routes = allEntries.filter((e) => e.pattern !== NOT_FOUND_PATTERN);
+  const notFoundLoader = allEntries.find((e) => e.pattern === NOT_FOUND_PATTERN)?.loader ?? null;
+
+  const notFound: Node | ((path: string) => Node | Promise<Node>) =
+    options.notFound ??
+    (notFoundLoader
+      ? (path) =>
+          notFoundLoader().then((mod) => {
+            const def = mod.default;
+            return typeof def === 'function' ? (def as (p: string) => Node)(path) : (def as unknown as Node);
+          })
+      : defaultNotFound);
+  const fullPageNotFound = Boolean(
+    options.appRoot && options.getLayout && (options.notFound != null || notFoundLoader != null)
+  );
+
+  function getContainer(): HTMLElement | null {
+    return document.getElementById(APP_ID);
+  }
+
+  async function render(pathname: string): Promise<boolean> {
+    const path = pathname === '/' ? '' : pathname.slice(1);
+
+    for (const { pattern, loader } of routes) {
+      const routeParams = match(pattern, path);
+      if (routeParams === null) continue;
+
+      currentParams = routeParams;
+      let target = getContainer();
+      if (fullPageNotFound && !target) {
+        options.appRoot!.innerHTML = '';
+        options.appRoot!.appendChild(options.getLayout!());
+        target = getContainer();
+      }
+      if (!target) continue;
+
+      const fallbackNode =
+        options.fallback != null
+          ? typeof options.fallback === 'function'
+            ? options.fallback()
+            : options.fallback
+          : null;
+      if (fallbackNode) setContent(target, fallbackNode);
+
+      const mod = await loader();
+      const def = mod.default;
+      if (typeof def === 'function') {
+        const out = def.length
+          ? (def as (p: Record<string, string>) => Node)(routeParams)
+          : (def as () => Node | string)();
+        if (out instanceof Node) setContent(target, out);
+        else if (typeof out === 'string') target.innerHTML = out;
+        else target.innerHTML = '';
+      } else {
+        setContent(target, typeof def === 'string' ? def : (def as unknown as Node));
+      }
+      return true;
+    }
+
+    currentParams = {};
+    const nfRaw = typeof notFound === 'function' ? notFound(pathname) : notFound;
+    const nfNode = nfRaw && typeof (nfRaw as Promise<unknown>).then === 'function' ? await (nfRaw as Promise<Node>) : (nfRaw as Node);
+    if (fullPageNotFound) {
+      options.appRoot!.innerHTML = '';
+      options.appRoot!.appendChild(nfNode);
+    } else {
+      setContent(container, nfNode);
+    }
+    return false;
+  }
+
+  function go(path: string, replace = false): void {
+    const p = path.startsWith('/') ? path : `/${path}`;
+    render(p).then((ok) => {
+      if (ok) (replace ? history.replaceState : history.pushState).call(history, null, '', p);
+    });
+  }
+
+  function start(): void {
+    render(location.pathname || '/');
+    window.addEventListener('popstate', () => render(location.pathname || '/'));
+    document.addEventListener('click', (e) => {
+      const a = (e.target as Element).closest('a');
+      if (a?.getAttribute('href')?.startsWith('/') && !a.href.startsWith('//')) {
+        e.preventDefault();
+        go(a.getAttribute('href')!);
+      }
+    });
+  }
+
+  const api: RouterAPI = { go, start };
+  currentRouter = api;
+  return api;
+}
+
+/**
+ * Navigate to a path. Import and use anywhere; works after run() (or createRouter().start()) has been called.
+ * No-op if the router is not started yet.
+ */
+export function go(path: string, replace = false): void {
+  currentRouter?.go(path, replace);
+}
+
+/** Current route params. params() → all, params('id') → one. */
+export function params(): Record<string, string>;
+export function params(name: string): string | undefined;
+export function params(name?: string): Record<string, string> | string | undefined {
+  if (name === undefined) return { ...currentParams };
+  return currentParams[name] ?? undefined;
+}
+
+/**
+ * Mounts App and starts the router. Use in your virtual entry.
+ * Returns the router API so you can call go() (and start()) from outside.
+ */
+export function run(
+  AppFactory: () => Node,
+  modules: Record<string, () => Promise<RouteModule>>,
+  options?: RunOptions
+): RouterAPI {
+  const app = document.getElementById('app')!;
+  app.appendChild(AppFactory());
+  const appContainer = document.getElementById(APP_ID);
+  if (!appContainer) {
+    throw new Error(`#${APP_ID} not found: use <App /> from @flow-os/router in your root layout.`);
+  }
+  const routerOptions: RouterOptions = {
+    fallback: options?.fallback,
+    notFound: options?.notFound,
+    appRoot: app,
+    getLayout: () => AppFactory(),
+  };
+  const api = createRouter(modules, appContainer as HTMLElement, routerOptions);
+  api.start();
+  return api;
+}

package/src/router/types.ts

@@ -0,0 +1,34 @@
+/** Route module: default can be a component (with optional params), a factory, or raw string/Node. */
+export type RouteModule = {
+  default:
+    | (() => Node)
+    | ((params: Record<string, string>) => Node)
+    | (() => string)
+    | string;
+};
+
+/** Options for run(): fallback while loading, custom 404. */
+export type RunOptions = {
+  /** Node (or factory) shown while the lazy route is loading. */
+  fallback?: Node | (() => Node);
+  /** 404 page: if provided, shown full-page (replaces entire #app, no shared layout). */
+  notFound?: Node | ((path: string) => Node);
+};
+
+/** Internal router options (fallback, notFound, full-page 404 wiring). */
+export type RouterOptions = {
+  fallback?: Node | (() => Node);
+  notFound?: Node | ((path: string) => Node | Promise<Node>);
+  appRoot?: HTMLElement;
+  getLayout?: () => Node;
+};
+
+/** Internal: normalized route entry for matching. */
+export type RouteEntry = {
+  pattern: string;
+  loader: () => Promise<RouteModule>;
+  /** Number of static segments (for sort order). */
+  staticSegments: number;
+  /** True if pattern ends with catch-all. */
+  catchAll: boolean;
+};

package/src/router/utils.ts

@@ -0,0 +1,45 @@
+/** Origin: protocol + host (e.g. https://localhost:5173 or https://example.com). */
+export function base(): string {
+  return typeof location !== 'undefined' ? location.origin : '';
+}
+
+/** Current pathname (e.g. /posts/123). */
+export function path(p?: string): string {
+  const raw = p ?? (typeof location !== 'undefined' ? location.pathname || '/' : '/');
+  return raw.startsWith('/') ? raw : `/${raw}`;
+}
+
+/** Full path + search + hash. No args = current. */
+export function href(p?: string): string {
+  const basePath = path(p);
+  if (typeof location === 'undefined') return basePath;
+  return basePath + (location.search ?? '') + (location.hash ?? '');
+}
+
+/** Query (after ?). query() → all as object, query('key') → one value. */
+export function query(): Record<string, string>;
+export function query(name: string): string | null;
+export function query(name?: string): Record<string, string> | string | null {
+  const s = typeof location !== 'undefined' ? location.search : '';
+  const p = new URLSearchParams(s);
+  if (name !== undefined) return p.get(name);
+  const out: Record<string, string> = {};
+  p.forEach((v, k) => (out[k] = v));
+  return out;
+}
+
+/** New path with query updated. go(setQuery({ page: '2' })) to navigate. */
+export function setQuery(
+  obj: Record<string, string | number | boolean | undefined | null>,
+  p?: string
+): string {
+  const basePath = path(p);
+  const current = query();
+  const next = { ...current };
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined || value === null) delete next[key];
+    else next[key] = String(value);
+  }
+  const search = new URLSearchParams(next).toString();
+  return search ? `${basePath}?${search}` : basePath;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@flow-os/router"
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "config/**/*.tsx"],
+  "exclude": ["node_modules"]
+}