@ibgib/space-gib 0.0.33 → 0.0.34

package/src/client/ui/router/space-gib-router-service.mts

@@ -0,0 +1,186 @@
+/**
+ * @module client/ui/router/space-gib-router-service
+ *
+ * Singleton HTML5 History API router service for space-gib.
+ * Manages URL updates (pushState/replaceState), browser back/forward (popstate),
+ * internal link click interception, and route change notification.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import {
+    SpaceGibRouteInfo,
+    RouterNavigateOptions,
+    SpaceGibRouteListener,
+} from './space-gib-router-types.mjs';
+import {
+    parseSpaceGibRoute,
+    formatSpaceGibRoute,
+    isSameRoute,
+} from './space-gib-router-helpers.mjs';
+
+export class SpaceGibRouterService {
+    private lc: string = `[SpaceGibRouterService]`;
+    private currentRoute?: SpaceGibRouteInfo;
+    private listeners: SpaceGibRouteListener[] = [];
+    private isNavigating: boolean = false;
+
+    constructor() {
+        if (typeof window !== 'undefined') {
+            this.initBrowserListeners();
+        }
+    }
+
+    private initBrowserListeners(): void {
+        const lc = `${this.lc}[${this.initBrowserListeners.name}]`;
+
+        // 1. Popstate listener (browser back / forward buttons)
+        window.addEventListener('popstate', async () => {
+            try {
+                const newRoute = parseSpaceGibRoute(window.location.pathname);
+                if (isSameRoute(this.currentRoute, newRoute)) {
+                    return;
+                }
+                this.currentRoute = newRoute;
+                await this.notifyListeners(newRoute);
+            } catch (err) {
+                console.error(`${lc} Popstate routing error: ${extractErrorMsg(err)}`);
+            }
+        });
+
+        // 2. Intercept internal anchor link clicks for seamless SPA navigation
+        document.addEventListener('click', (e: MouseEvent) => {
+            if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+                return;
+            }
+
+            const target = e.target as HTMLElement | null;
+            const anchor = target?.closest('a') as HTMLAnchorElement | null;
+            if (!anchor) { return; }
+
+            const href = anchor.getAttribute('href');
+            if (!href || href.startsWith('#') || href.startsWith('javascript:') || href.startsWith('mailto:')) {
+                return;
+            }
+
+            // Exclude external links and target="_blank"
+            if (anchor.target && anchor.target !== '_self') { return; }
+            if (anchor.origin && anchor.origin !== window.location.origin) { return; }
+
+            // Exclude API and asset routes
+            if (href.startsWith('/api/') || href.startsWith('/assets/') || href.startsWith('/css/')) {
+                return;
+            }
+
+            // Intercept internal routing
+            e.preventDefault();
+            this.navigatePath(href);
+        });
+    }
+
+    /**
+     * Subscribes a listener to route change events.
+     * Returns an unsubscribe function.
+     */
+    public subscribe(listener: SpaceGibRouteListener): () => void {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx !== -1) {
+                this.listeners.splice(idx, 1);
+            }
+        };
+    }
+
+    /**
+     * Returns the current active route info, if any.
+     */
+    public getCurrentRoute(): SpaceGibRouteInfo | undefined {
+        return this.currentRoute;
+    }
+
+    /**
+     * Navigates to a given SpaceGibRouteInfo.
+     */
+    public async navigate(route: SpaceGibRouteInfo, opts?: RouterNavigateOptions): Promise<void> {
+        const lc = `${this.lc}[${this.navigate.name}]`;
+        if (this.isNavigating) { return; }
+        this.isNavigating = true;
+
+        try {
+            const targetPath = formatSpaceGibRoute(route);
+
+            if (typeof window !== 'undefined') {
+                if (window.location.pathname !== targetPath) {
+                    if (opts?.replace) {
+                        window.history.replaceState(null, '', targetPath);
+                    } else {
+                        window.history.pushState(null, '', targetPath);
+                    }
+                }
+            }
+
+            const wasSame = isSameRoute(this.currentRoute, route);
+            this.currentRoute = route;
+
+            if (!opts?.silent && !wasSame) {
+                await this.notifyListeners(route);
+            }
+        } catch (err) {
+            console.error(`${lc} Navigation error: ${extractErrorMsg(err)}`);
+        } finally {
+            this.isNavigating = false;
+        }
+    }
+
+    /**
+     * Navigates to a raw pathname string by parsing it into a SpaceGibRouteInfo.
+     */
+    public async navigatePath(pathname: string, opts?: RouterNavigateOptions): Promise<void> {
+        const route = parseSpaceGibRoute(pathname);
+        await this.navigate(route, opts);
+    }
+
+    /**
+     * Reads current window.location.pathname, parses the route, updates internal state,
+     * and notifies all listeners. Call during application bootstrap after Shell is ready.
+     */
+    public async loadCurrentURL(): Promise<SpaceGibRouteInfo> {
+        const lc = `${this.lc}[${this.loadCurrentURL.name}]`;
+        try {
+            const pathname = typeof window !== 'undefined' ? window.location.pathname : '/';
+            const route = parseSpaceGibRoute(pathname);
+            this.currentRoute = route;
+            await this.notifyListeners(route);
+            return route;
+        } catch (err) {
+            console.error(`${lc} loadCurrentURL error: ${extractErrorMsg(err)}`);
+            const fallback: SpaceGibRouteInfo = { kind: 'polycosmos' };
+            this.currentRoute = fallback;
+            return fallback;
+        }
+    }
+
+    private async notifyListeners(route: SpaceGibRouteInfo): Promise<void> {
+        const lc = `${this.lc}[${this.notifyListeners.name}]`;
+        for (const listener of this.listeners) {
+            try {
+                await listener(route);
+            } catch (listenerErr) {
+                console.error(`${lc} Listener error: ${extractErrorMsg(listenerErr)}`);
+            }
+        }
+    }
+}
+
+let routerSingleton: SpaceGibRouterService | undefined;
+
+/**
+ * Returns the singleton SpaceGibRouterService instance.
+ */
+export function getSpaceGibRouterSvc(): SpaceGibRouterService {
+    if (!routerSingleton) {
+        routerSingleton = new SpaceGibRouterService();
+    }
+    return routerSingleton;
+}

package/src/client/ui/router/space-gib-router-types.mts

@@ -0,0 +1,93 @@
+/**
+ * @module client/ui/router/space-gib-router-types
+ *
+ * Types for the Phase 1.5 Space-Gib Client Router.
+ * Supports dual routing mechanisms:
+ * 1. Space-Qualified Raw Addr (Content-Addressed & Space-Scoped):
+ *    - Snapshot / Immutable point-in-time: /:cosmos/:spaceId/addr/:ibGibAddr
+ *    - Living Timeline Tip: /:cosmos/:spaceId/tjp/:tjpAddr
+ * 2. Workspace / Galaxy Projections (Human-Readable & Timeline-Aware):
+ *    - Polycosmos: / or /polycosmos or /@:siteUsername or /keystone/:keystoneTjp
+ *    - Cosmos: /:cosmos or /@:siteUsername/:cosmos
+ *    - Code Galaxy: /:cosmos/code/:galaxyId[/:branch[/*filePath]]
+ *    - Notes Galaxy: /:cosmos/notes/:galaxyId[/:topicTjp]
+ * 3. Special Routes:
+ *    - Admin Review: /admin/review[/:tjpGib]
+ */
+
+export type SpaceGibTenant =
+    | { type: 'username'; siteUsername: string }
+    | { type: 'keystone'; keystoneTjp: string };
+
+export interface SpaceGibRouteBase {
+    tenant?: SpaceGibTenant;
+}
+
+export interface PolycosmosRouteInfo extends SpaceGibRouteBase {
+    kind: 'polycosmos';
+}
+
+export interface CosmosRouteInfo extends SpaceGibRouteBase {
+    kind: 'cosmos';
+    cosmos: string;
+}
+
+export interface CodeGalaxyRouteInfo extends SpaceGibRouteBase {
+    kind: 'code-galaxy';
+    cosmos: string;
+    galaxyId: string;
+    branch?: string;
+    filePath?: string;
+}
+
+export interface NotesGalaxyRouteInfo extends SpaceGibRouteBase {
+    kind: 'notes-galaxy';
+    cosmos: string;
+    galaxyId: string;
+    trailMode?: 'tjp' | 'addr';
+    trail?: string[];
+    topicTjp?: string;
+    query?: {
+        inspect?: string;
+        lens?: string;
+        tag?: string;
+        [key: string]: string | undefined;
+    };
+}
+
+export interface RawAddrRouteInfo extends SpaceGibRouteBase {
+    kind: 'raw-addr';
+    cosmos: string;
+    spaceId: string;
+    ibGibAddr: string;
+}
+
+export interface RawTjpRouteInfo extends SpaceGibRouteBase {
+    kind: 'raw-tjp';
+    cosmos: string;
+    spaceId: string;
+    tjpAddr: string;
+}
+
+export interface AdminReviewRouteInfo {
+    kind: 'admin-review';
+    tjpGib?: string;
+}
+
+export type SpaceGibRouteInfo =
+    | PolycosmosRouteInfo
+    | CosmosRouteInfo
+    | CodeGalaxyRouteInfo
+    | NotesGalaxyRouteInfo
+    | RawAddrRouteInfo
+    | RawTjpRouteInfo
+    | AdminReviewRouteInfo;
+
+export interface RouterNavigateOptions {
+    /** If true, uses history.replaceState instead of pushState */
+    replace?: boolean;
+    /** If true, does not fire route change listeners */
+    silent?: boolean;
+}
+
+export type SpaceGibRouteListener = (route: SpaceGibRouteInfo) => Promise<void> | void;