extrojs 0.1.0 → 0.3.0

package/dist/plugin/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { ManifestV3 } from "../../types/index.js";
+export type PluginContextLike = {
+    emitFile(file: {
+        type: "asset";
+        fileName: string;
+        source: string | Uint8Array;
+    }): string;
+    warn(message: string): void;
+};

package/dist/plugin/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/utils/read-json.d.ts

@@ -0,0 +1 @@
+export declare function readJson<T = unknown>(file: string, root: string): T | null;

package/dist/plugin/utils/read-json.js

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+export function readJson(file, root) {
+    const filePath = path.join(root, file);
+    if (!fs.existsSync(filePath))
+        return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}

package/dist/react/env.d.ts

@@ -0,0 +1,13 @@
+export {};
+declare global {
+    interface ImportMetaEnv {
+        readonly MODE: string;
+        readonly DEV: boolean;
+        readonly PROD: boolean;
+        readonly BASE_URL: string;
+        readonly [key: `EXTRO_PUBLIC_${string}`]: string | undefined;
+    }
+    interface ImportMeta {
+        readonly env: ImportMetaEnv;
+    }
+}

package/dist/react/env.js

@@ -0,0 +1 @@
+export {};

package/dist/router/build-tree.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentType, ReactElement } from "react";
+import type { BoundaryKind } from "../types/index.js";
+import type { Router } from "./context.js";
+import type { ErrorProps, LayoutProps, PageProps } from "./types.js";
+/** A boundary already paired with its loaded component (orchestration zips this). */
+export type ResolvedBoundary = {
+    kind: BoundaryKind;
+    component: ComponentType<LayoutProps> | ComponentType<ErrorProps>;
+};
+/**
+ * Every renderable outcome of a navigation. `buildTree` is total over this:
+ * `render()` resolves one of these (with the navToken/load orchestration) and
+ * hands it here; structure lives nowhere else.
+ */
+export type RenderOutcome = {
+    type: "match";
+    page: ComponentType<PageProps>;
+    params: Record<string, string>;
+    boundaries: ResolvedBoundary[];
+} | {
+    type: "not-found";
+    notFound: ComponentType;
+    rootLayout: ComponentType<LayoutProps> | null;
+} | {
+    type: "load-error";
+    error: Error;
+    reset: () => void;
+};
+export type RenderContext = {
+    pathname: string;
+    search: string;
+    router: Router;
+};
+/**
+ * @describe The single, pure home of ADR 0003 §3/§4/§5 structure. Given a
+ * resolved navigation outcome, returns the React element tree to mount:
+ *
+ *   - match:     <Provider><BuiltInEB> L0 <EB user> ... <Page/> ... </Provider>
+ *                (each segment's error nested inside its sibling layout, §3)
+ *   - not-found: <Provider><BuiltInEB> rootLayout? <NotFound/> </Provider> (§4)
+ *   - load-error: bare <DefaultError/> (load failed outside React render, §5)
+ *
+ * Pure and total: same inputs, same tree; no DOM, no effects. The always-on
+ * built-in error boundary (§5) means a match/not-found surface never blanks.
+ */
+export declare function buildTree(outcome: RenderOutcome, ctx: RenderContext): ReactElement;

package/dist/router/build-tree.js

@@ -0,0 +1,56 @@
+import { createElement } from "react";
+import { RouterContext } from "./context.js";
+import { ErrorBoundary } from "./error-boundary.js";
+import { DefaultError } from "./defaults.js";
+/**
+ * @describe The single, pure home of ADR 0003 §3/§4/§5 structure. Given a
+ * resolved navigation outcome, returns the React element tree to mount:
+ *
+ *   - match:     <Provider><BuiltInEB> L0 <EB user> ... <Page/> ... </Provider>
+ *                (each segment's error nested inside its sibling layout, §3)
+ *   - not-found: <Provider><BuiltInEB> rootLayout? <NotFound/> </Provider> (§4)
+ *   - load-error: bare <DefaultError/> (load failed outside React render, §5)
+ *
+ * Pure and total: same inputs, same tree; no DOM, no effects. The always-on
+ * built-in error boundary (§5) means a match/not-found surface never blanks.
+ */
+export function buildTree(outcome, ctx) {
+    if (outcome.type === "load-error") {
+        return createElement(DefaultError, {
+            error: outcome.error,
+            reset: outcome.reset,
+        });
+    }
+    // Router context + the always-on outermost built-in error boundary (§5),
+    // shared by the match and not-found paths so they stay consistent.
+    const provide = (params, inner) => createElement(RouterContext.Provider, {
+        value: {
+            pathname: ctx.pathname,
+            search: ctx.search,
+            params,
+            router: ctx.router,
+        },
+    }, createElement(ErrorBoundary, { fallback: DefaultError, children: inner }));
+    if (outcome.type === "not-found") {
+        let inner = createElement(outcome.notFound);
+        if (outcome.rootLayout) {
+            inner = createElement(outcome.rootLayout, { children: inner });
+        }
+        return provide({}, inner);
+    }
+    // Fold innermost-first so the outermost boundary wraps everything; each
+    // segment's error sits inside its sibling layout (the chain is ordered
+    // layout-before-error per segment). Empty chain = just the page.
+    const composed = outcome.boundaries.reduceRight((child, boundary) => {
+        if (boundary.kind === "error") {
+            return createElement(ErrorBoundary, {
+                fallback: boundary.component,
+                children: child,
+            });
+        }
+        return createElement(boundary.component, {
+            children: child,
+        });
+    }, createElement(outcome.page, { params: outcome.params }));
+    return provide(outcome.params, composed);
+}

package/dist/router/context.d.ts

@@ -0,0 +1,13 @@
+export interface Router {
+    push: (to: string) => void;
+    replace: (to: string) => void;
+    back: () => void;
+    forward: () => void;
+}
+export interface RouterContextValue {
+    pathname: string;
+    search: string;
+    params: Record<string, string>;
+    router: Router;
+}
+export declare const RouterContext: import("react").Context<RouterContextValue | null>;

package/dist/router/context.js

@@ -0,0 +1,2 @@
+import { createContext } from "react";
+export const RouterContext = createContext(null);

package/dist/router/create-router.d.ts

@@ -0,0 +1,10 @@
+import type { CreateRouterOptions, Route, RouterSurfaceOptions } from "./types.js";
+/**
+ * @describe Mounts a surface (popup | options | sidepanel) and wires hash-based
+ * client-side routing into the given routes array. Called once per surface by
+ * the virtual runtime module emitted by @extrojs/vite-plugin.
+ */
+export interface ExtroRouterHandle {
+    update: (newRoutes: Route[], opts?: RouterSurfaceOptions) => void;
+}
+export declare const createExtroRouter: (routes: Route[], options?: CreateRouterOptions) => ExtroRouterHandle;

package/dist/router/create-router.js

@@ -0,0 +1,126 @@
+import { createRoot } from "react-dom/client";
+import { matchRoutes } from "./match.js";
+import { DefaultNotFound } from "./defaults.js";
+import { buildTree } from "./build-tree.js";
+const toError = (err) => err instanceof Error ? err : new Error(String(err));
+export const createExtroRouter = (routes, options = {}) => {
+    const { rootId = "root" } = options;
+    const el = document.getElementById(rootId);
+    if (!el) {
+        throw new Error(`Extro: #${rootId} element not found`);
+    }
+    const root = createRoot(el);
+    const router = createRouter();
+    let currentRoutes = routes;
+    let notFound = options.notFound ?? null;
+    let rootLayout = options.rootLayout ?? null;
+    let navToken = 0;
+    // Built-in fallback when the surface has no not-found.tsx (ADR 0003 §5).
+    const loadNotFound = () => notFound ? notFound() : Promise.resolve({ default: DefaultNotFound });
+    // Pure orchestration: resolve the navigation outcome (with the navToken
+    // guard + load failure handling) and hand it to `buildTree`. No structure
+    // lives here — every renderable shape is in build-tree.ts (ADR 0006).
+    const render = async () => {
+        const token = ++navToken;
+        const { pathname, search } = parseLocation();
+        const ctx = { pathname, search, router };
+        const matches = matchRoutes(pathname, currentRoutes);
+        if (!matches) {
+            // No Route matched: not-found inside the surface-root layout only
+            // (ADR 0003 §4). Nothing matched, so no deeper layout is in scope.
+            let nf;
+            let rl;
+            try {
+                ;
+                [nf, rl] = await Promise.all([
+                    loadNotFound(),
+                    rootLayout ? rootLayout() : Promise.resolve(null),
+                ]);
+            }
+            catch (err) {
+                if (token !== navToken)
+                    return;
+                root.render(buildTree({ type: "load-error", error: toError(err), reset: () => void render() }, ctx));
+                return;
+            }
+            if (token !== navToken)
+                return;
+            root.render(buildTree({
+                type: "not-found",
+                notFound: nf.default,
+                rootLayout: rl ? rl.default : null,
+            }, ctx));
+            return;
+        }
+        const leaf = matches[matches.length - 1];
+        // Page + ancestor boundaries load in parallel, in route order
+        // (outermost first). A missing/broken module rejects here — outside
+        // React render, so no boundary can catch it; surface the built-in
+        // error instead of blanking the surface (ADR 0003 §5).
+        let mod;
+        let boundaryMods;
+        try {
+            ;
+            [mod, ...boundaryMods] = await Promise.all([
+                leaf.route.load(),
+                ...leaf.route.boundaries.map((b) => b.load()),
+            ]);
+        }
+        catch (err) {
+            if (token !== navToken)
+                return;
+            root.render(buildTree({ type: "load-error", error: toError(err), reset: () => void render() }, ctx));
+            return;
+        }
+        if (token !== navToken)
+            return;
+        // Zip each boundary's kind with its loaded component; structure (the
+        // §3 nesting) is buildTree's job, not this orchestrator's.
+        const boundaries = leaf.route.boundaries.map((b, i) => ({
+            kind: b.kind,
+            component: boundaryMods[i].default,
+        }));
+        root.render(buildTree({
+            type: "match",
+            page: mod.default,
+            params: leaf.params,
+            boundaries,
+        }, ctx));
+    };
+    window.addEventListener("hashchange", render);
+    render();
+    return {
+        update: (newRoutes, opts) => {
+            currentRoutes = newRoutes;
+            if (opts) {
+                notFound = opts.notFound ?? null;
+                rootLayout = opts.rootLayout ?? null;
+            }
+            render();
+        },
+    };
+};
+/**
+ * @describe Normalizes `window.location.hash` into a pathname + search string.
+ */
+const parseLocation = () => {
+    const [rawPath = "", search = ""] = window.location.hash.replace(/^#/, "").split("?");
+    return { pathname: rawPath || "/", search };
+};
+const stripHash = (to) => (to.startsWith("#") ? to.slice(1) : to);
+/**
+ * @describe Builds the stable router object passed through context. `replace`
+ * uses history.replaceState + a manual hashchange dispatch because
+ * replaceState alone doesn't fire the event.
+ */
+const createRouter = () => ({
+    push: (to) => {
+        window.location.hash = stripHash(to);
+    },
+    replace: (to) => {
+        window.history.replaceState(null, "", `#${stripHash(to)}`);
+        window.dispatchEvent(new HashChangeEvent("hashchange"));
+    },
+    back: () => window.history.back(),
+    forward: () => window.history.forward(),
+});

package/dist/router/defaults.d.ts

@@ -0,0 +1,24 @@
+import type { ErrorProps } from "./types.js";
+/**
+ * @describe Built-in error fallback (ADR 0003 §5). Always the outermost
+ * boundary so a thrown render never blanks the surface. Deliberately
+ * unstyled and minimal; shows `error.message` always (the extension error
+ * surface is seen by the developer far more than end users in v0.x).
+ */
+export declare const DefaultError: ({ error, reset }: ErrorProps) => import("react").DetailedReactHTMLElement<{
+    style: {
+        padding: number;
+        fontFamily: "system-ui, sans-serif";
+    };
+}, HTMLElement>;
+/**
+ * @describe Built-in not-found fallback (ADR 0003 §4/§5). Rendered when a
+ * hash matches no Route. Takes no props per the user contract; reads the
+ * unmatched path from the router context it is mounted within.
+ */
+export declare const DefaultNotFound: () => import("react").DetailedReactHTMLElement<{
+    style: {
+        padding: number;
+        fontFamily: "system-ui, sans-serif";
+    };
+}, HTMLElement>;

package/dist/router/defaults.js

@@ -0,0 +1,25 @@
+import { createElement } from "react";
+import { useLocation } from "./hooks.js";
+/**
+ * @describe Built-in error fallback (ADR 0003 §5). Always the outermost
+ * boundary so a thrown render never blanks the surface. Deliberately
+ * unstyled and minimal; shows `error.message` always (the extension error
+ * surface is seen by the developer far more than end users in v0.x).
+ */
+export const DefaultError = ({ error, reset }) => createElement("div", { style: { padding: 16, fontFamily: "system-ui, sans-serif" } }, createElement("p", { style: { margin: "0 0 8px", fontWeight: 600 } }, "Something went wrong"), createElement("pre", {
+    style: {
+        margin: "0 0 12px",
+        whiteSpace: "pre-wrap",
+        fontSize: 12,
+        color: "#b00",
+    },
+}, error.message), createElement("button", { onClick: reset }, "Try again"));
+/**
+ * @describe Built-in not-found fallback (ADR 0003 §4/§5). Rendered when a
+ * hash matches no Route. Takes no props per the user contract; reads the
+ * unmatched path from the router context it is mounted within.
+ */
+export const DefaultNotFound = () => {
+    const { pathname } = useLocation();
+    return createElement("div", { style: { padding: 16, fontFamily: "system-ui, sans-serif" } }, createElement("p", { style: { margin: "0 0 4px", fontWeight: 600 } }, "404"), createElement("p", { style: { margin: 0, fontSize: 13, color: "#666" } }, `No route for ${pathname}`));
+};

package/dist/router/error-boundary.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ErrorProps } from "./types.js";
+import { Component } from "react";
+interface ErrorBoundaryProps {
+    fallback: ComponentType<ErrorProps>;
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * @describe Catches render errors in its subtree and shows `fallback` with
+ * `{ error, reset }`. Composed inside its sibling layout (ADR 0003 §3), so a
+ * caught error never tears the layout down, and `reset()` only re-renders the
+ * boundary's own contents.
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    reset: () => void;
+    render(): ReactNode;
+}
+export {};

package/dist/router/error-boundary.js

@@ -0,0 +1,21 @@
+import { Component, createElement } from "react";
+/**
+ * @describe Catches render errors in its subtree and shows `fallback` with
+ * `{ error, reset }`. Composed inside its sibling layout (ADR 0003 §3), so a
+ * caught error never tears the layout down, and `reset()` only re-renders the
+ * boundary's own contents.
+ */
+export class ErrorBoundary extends Component {
+    state = { error: null };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    reset = () => this.setState({ error: null });
+    render() {
+        const { error } = this.state;
+        if (error) {
+            return createElement(this.props.fallback, { error, reset: this.reset });
+        }
+        return this.props.children;
+    }
+}

package/dist/router/hooks.d.ts

@@ -0,0 +1,18 @@
+import type { Router } from "./context.js";
+export declare const useLocation: () => {
+    pathname: string;
+    search: string;
+};
+export declare const useParams: <T extends Record<string, string> = Record<string, string>>() => T;
+export declare const useRouter: () => Router;
+type SearchInit = URLSearchParams | string | Record<string, string>;
+interface UseSearchParamsResult {
+    params: URLSearchParams;
+    setParams: (next: SearchInit) => void;
+}
+/**
+ * @describe Reads + writes the URL search string. Updates use `router.replace`
+ * so query edits don't pile up history entries.
+ */
+export declare const useSearchParams: () => UseSearchParamsResult;
+export {};

package/dist/router/hooks.js

@@ -0,0 +1,34 @@
+import { useContext, useMemo } from "react";
+import { RouterContext } from "./context.js";
+const useRouterContext = () => {
+    const ctx = useContext(RouterContext);
+    if (!ctx) {
+        throw new Error("Extro: router hooks must be used inside a page rendered by createExtroRouter.");
+    }
+    return ctx;
+};
+export const useLocation = () => {
+    const { pathname, search } = useRouterContext();
+    return { pathname, search };
+};
+export const useParams = () => {
+    return useRouterContext().params;
+};
+export const useRouter = () => useRouterContext().router;
+/**
+ * @describe Reads + writes the URL search string. Updates use `router.replace`
+ * so query edits don't pile up history entries.
+ */
+export const useSearchParams = () => {
+    const { search, pathname, router } = useRouterContext();
+    const params = useMemo(() => new URLSearchParams(search), [search]);
+    const setParams = (next) => {
+        const nextSearch = next instanceof URLSearchParams
+            ? next.toString()
+            : typeof next === "string"
+                ? next
+                : new URLSearchParams(next).toString();
+        router.replace(nextSearch ? `${pathname}?${nextSearch}` : pathname);
+    };
+    return { params, setParams };
+};

package/dist/router/index.d.ts

@@ -0,0 +1,8 @@
+import "../react/env.js";
+export { createExtroRouter } from "./create-router.js";
+export type { ExtroRouterHandle } from "./create-router.js";
+export { matchRoutes } from "./match.js";
+export { Link } from "./link.js";
+export { useLocation, useParams, useRouter, useSearchParams, } from "./hooks.js";
+export type { Router, RouterContextValue } from "./context.js";
+export type { CreateRouterOptions, DynamicRoute, ErrorProps, LayoutProps, PageProps, Route, RouteMatch, StaticRoute, } from "./types.js";

package/dist/router/index.js

@@ -0,0 +1,7 @@
+// Pulls in the ambient env typing so importing a routing subpath is enough to
+// type `import.meta.env` with no extra setup.
+import "../react/env.js";
+export { createExtroRouter } from "./create-router.js";
+export { matchRoutes } from "./match.js";
+export { Link } from "./link.js";
+export { useLocation, useParams, useRouter, useSearchParams, } from "./hooks.js";