@nifrajs/web-solid 3.3.0 → 4.0.0

package/src/plugin.ts

@@ -0,0 +1,93 @@
+/**
+ * `@nifrajs/web-solid/plugin` - the Solid Babel Bun plugin, in its OWN module so the adapter root (which
+ * every Solid SSR server and edge worker bundles) never links build-time code. Mirrors
+ * `@nifrajs/web-vue/plugin`: pass `"dom"` for the client bundle and `"ssr"` for the server.
+ */
+import { transformAsync } from "@babel/core"
+// @ts-expect-error - no type declarations published
+import presetTypeScript from "@babel/preset-typescript"
+import { devServerCompile, normalizeFilePath, rewriteSsrImports } from "@nifrajs/web/plugins/kit"
+// @ts-expect-error - no type declarations published
+import presetSolid from "babel-preset-solid"
+import type { BunPlugin } from "bun"
+import solidRefreshBunHot, { SOLID_HOT_MODULE } from "./refresh-babel.ts"
+
+/**
+ * Bun build/runtime plugin that compiles Solid components with Babel - `generate: "ssr"`
+ * for the server, `"dom"` for the client, `hydratable` so SSR and hydrate align. Solid's
+ * reactive-JSX compiler ships only as a Babel plugin (no swc/native port); this runs at
+ * build time, on `.tsx` files only.
+ *
+ * Under a dev server the client half additionally runs `solid-refresh`, which is what makes an edit
+ * patch the running component tree instead of reloading the page - see {@link setupSolidRefresh}.
+ */
+export function solidBunPlugin(generate: "dom" | "ssr"): BunPlugin {
+  return {
+    name: `nifra-solid-${generate}`,
+    setup(build) {
+      const refresh =
+        generate === "dom" && devServerCompile() ? setupSolidRefresh(build) : undefined
+      // Match `.tsx`, tolerating a `?query` suffix (dev servers append one to bust Bun's import
+      // cache); strip it before reading the file off disk.
+      build.onLoad({ filter: /\.tsx(\?|$)/ }, async (args) => {
+        const path = normalizeFilePath(args.path)
+        const source = await Bun.file(path).text()
+        const result = await transformAsync(source, {
+          filename: path,
+          // babel applies presets last→first: strip TS first, then Solid transforms JSX.
+          presets: [
+            [presetSolid, { generate, hydratable: true }],
+            [presetTypeScript, { onlyRemoveTypeImports: true }],
+          ],
+          ...(refresh !== undefined
+            ? { plugins: [[await refresh.babel(), REFRESH_OPTIONS], solidRefreshBunHot] }
+            : {}),
+        })
+        return { contents: rewriteSsrImports(result?.code ?? "", path, generate), loader: "js" }
+      })
+    },
+  }
+}
+
+/**
+ * `"esm"` is the closest of `solid-refresh`'s bundler modes to what Bun implements: one
+ * `accept(mod => …)` per module, falling back to `invalidate()` when a component's signature changed too
+ * much to patch in place. `"vite"` differs only by also calling a bare `accept()` first, which would make
+ * every module self-accepting twice over. The call it emits is still Vite-shaped, and
+ * `solidRefreshBunHot` translates it.
+ *
+ * `jsx: false` turns OFF the pass that lifts a component's returned JSX into a second, nested component.
+ * That extra component is an extra hydration level on the client and none on the server, so with it on,
+ * every hydratable page dies on `Unable to find DOM nodes for hydration key` before a single edit. It buys
+ * finer-grained patching of markup-only edits; correct hydration is worth more.
+ */
+const REFRESH_OPTIONS = { bundler: "esm", jsx: false } as const
+
+/**
+ * Wire `solid-refresh` into a dev-server client compile.
+ *
+ * Solid components are compiled reactive closures, not functions re-run on render, so a new module
+ * version cannot simply replace the old one - `solid-refresh` wraps every component in a registry and, on
+ * an update, patches the live instances, keeping signal state. Without it the update finds no accepting
+ * module, bubbles up to the generated entry, and Bun reloads the whole page.
+ *
+ * The Babel half loads lazily: it is dev-only, and every production build loads this plugin too.
+ *
+ * Both runtime specifiers need pinning, because the transform emits them INTO the app's own files, where
+ * a bare specifier resolves against the app. `solid-refresh` is only a transitive dependency there and
+ * need not be hoisted; `nifra:solid-hot` is this package's own bridge module and has no app-side name at
+ * all. Resolving both here is what keeps the emitted imports working without an app depending on either.
+ */
+function setupSolidRefresh(build: Parameters<BunPlugin["setup"]>[0]): {
+  babel: () => Promise<unknown>
+} {
+  const runtime = Bun.resolveSync("solid-refresh", import.meta.dir)
+  build.onResolve({ filter: /^solid-refresh$/ }, () => ({ path: runtime }))
+  // `.ts` from source (Bun takes the package's `bun` export condition), `.js` from the published build.
+  const bridge = `${import.meta.dir}/refresh-hot${import.meta.path.endsWith(".ts") ? ".ts" : ".js"}`
+  build.onResolve({ filter: new RegExp(`^${SOLID_HOT_MODULE}$`) }, () => ({ path: bridge }))
+  let babel: Promise<unknown> | undefined
+  return {
+    babel: () => (babel ??= import("solid-refresh/babel").then((m) => m.default)),
+  }
+}

package/src/route-props.ts

@@ -0,0 +1,55 @@
+import type { MountRouterOptions, RenderProps, RouterState } from "@nifrajs/web"
+// `/client`, not the root: the root's graph carries the server, and Vite's dev server evaluates it
+// instead of tree-shaking it - which broke hydration before the browser ran a line of app code.
+import { searchOfChain } from "@nifrajs/web/client"
+
+/**
+ * The client half of the server's `RenderProps`, as getters so a settle re-renders only what reads the
+ * changed field. Cast: a getter always exists where `exactOptionalPropertyTypes` expects absence.
+ */
+export function routeProps(
+  snapshot: () => RouterState,
+  searchSchemas: MountRouterOptions["searchSchemas"],
+  matchChains?: MountRouterOptions["matchChains"],
+): RenderProps {
+  return {
+    get data() {
+      return snapshot().data
+    },
+    // Each layout's own loader data. Without it a layout renders `data: null` on the client while the
+    // server rendered it with its data.
+    get layoutData() {
+      return snapshot().layoutData
+    },
+    get actionData() {
+      return snapshot().actionData
+    },
+    get pending() {
+      return snapshot().pending
+    },
+    // The same `params`/`path` the server render received, so `useMatches` reports the same chain.
+    get params() {
+      return snapshot().params
+    },
+    get path() {
+      return snapshot().path
+    },
+    get search() {
+      // The SAME searchOfChain the server ran, over this snapshot's URL - a same-route search change
+      // updates in place (fine-grained), matching the SSR value on hydration.
+      const s = snapshot()
+      const idx = s.path.indexOf("?")
+      return searchOfChain(searchSchemas?.[s.routeId] ?? [], idx === -1 ? "" : s.path.slice(idx))
+    },
+    get submission() {
+      return snapshot().submission
+    },
+    get boundaries() {
+      return snapshot().boundaries
+    },
+    // The chain `useMatches` reports - the server passed the same one to the SSR render.
+    get matchChain() {
+      return matchChains?.[snapshot().routeId]
+    },
+  } as RenderProps
+}

package/src/router.ts

@@ -9,6 +9,8 @@ import type {
   NavigateFunction,
   NavigateOptions,
   NavigateTargetInput,
+  RenderProps,
+  UIMatch,
 } from "@nifrajs/web"
 // `/client`, not the root - these are DOM values, and the root's graph carries the
 // server, which Vite's dev server evaluates rather than tree-shakes.
@@ -18,6 +20,8 @@ import {
   registerBlocker,
   resolveNavigate,
 } from "@nifrajs/web/client"
+// Its own subpath, so an app that never calls `useMatches` never bundles it.
+import { chainMatches } from "@nifrajs/web/internal/matches-runtime"
 /**
  * `@nifrajs/web-solid/router` - Solid routing bindings over the agnostic `@nifrajs/web` history layer:
  * `useNavigate` (programmatic navigation), `useBlocker` (the unsaved-changes guard), and `useSearch`
@@ -29,12 +33,13 @@ import {
   type Accessor,
   type Context,
   createContext,
+  createMemo,
   createSignal,
   onCleanup,
   useContext,
 } from "solid-js"
 
-export type { Blocker, BlockerFunction, BlockerState, NavigateFunction }
+export type { Blocker, BlockerFunction, BlockerState, NavigateFunction, UIMatch }
 
 // Frozen empty search + a stable accessor for a `useSearch` used outside a nifra route tree.
 const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
@@ -55,6 +60,34 @@ export const SearchContext =
   searchContextSlot[SEARCH_CONTEXT_SLOT] ?? createContext<Accessor<Record<string, unknown>>>()
 searchContextSlot[SEARCH_CONTEXT_SLOT] = SearchContext
 
+/** The props `compose` rendered the chain with - getters over the router snapshot on the client - which
+ * {@link useMatches} reads. A `globalThis` singleton for the same reason as {@link SearchContext}. */
+const PROPS_CONTEXT_SLOT = Symbol.for("nifra.web-solid.props-context")
+const propsContextSlot = globalThis as { [PROPS_CONTEXT_SLOT]?: Context<RenderProps | undefined> }
+export const RenderPropsContext =
+  propsContextSlot[PROPS_CONTEXT_SLOT] ?? createContext<RenderProps>()
+propsContextSlot[PROPS_CONTEXT_SLOT] = RenderPropsContext
+
+const NO_MATCHES: readonly UIMatch[] = Object.freeze([])
+
+/**
+ * The rendered chain - each layout, then the page - with the URL prefix, params and loader data each
+ * one owns, plus its `handle` export, as a reactive accessor. The same list on the server render and
+ * the client mount, so a layout can render breadcrumbs from its children's `handle`s without a
+ * hydration mismatch; it updates in place when a same-route navigation settles.
+ *
+ * ```tsx
+ * export const handle = { crumb: "Settings" }
+ * const matches = useMatches()
+ * const crumbs = () => matches().flatMap((m) => (m.handle as { crumb?: string } | undefined)?.crumb ?? [])
+ * ```
+ */
+export function useMatches(): Accessor<readonly UIMatch[]> {
+  const props = useContext(RenderPropsContext)
+  if (props === undefined) return () => NO_MATCHES
+  return createMemo(() => chainMatches(props))
+}
+
 /**
  * The route's typed, validated search params as a reactive accessor - the SAME value the loader received
  * as `ctx.search`. SSR-correct: `compose` provides it from the URL server-side and from the identical