@nifrajs/web-solid 0.1.0-alpha.1

package/src/error.ts

@@ -0,0 +1,26 @@
+/**
+ * `errorBoundary` — the Solid error-boundary chain element for nifra's `_error.tsx`. Its own module
+ * (imports only `solid-js`) so the client codegen can import it from `@nifrajs/web-solid/client` (which
+ * re-exports it). No JSX (`createComponent`), so the package builds with plain `tsc`.
+ */
+import { createComponent, ErrorBoundary, type JSX } from "solid-js"
+
+/**
+ * Build an error-boundary chain element bound to `fallback` (a route's `_error` component). nifra's
+ * client codegen inserts it before the page in the matched chain; a render error in the subtree renders
+ * `fallback` with `{ data: { name, message } }` (via Solid's `<ErrorBoundary>`) instead of crashing.
+ * DOM-transparent (renders its children directly — no wrapper element), so it never disturbs hydration.
+ */
+export function errorBoundary(fallback: unknown): unknown {
+  const Fallback = fallback as (props: { data: { name: string; message: string } }) => JSX.Element
+  return (props: { children?: JSX.Element }): JSX.Element =>
+    createComponent(ErrorBoundary, {
+      fallback: (err: unknown) => {
+        const e = err instanceof Error ? err : new Error(String(err))
+        return createComponent(Fallback, { data: { name: e.name, message: e.message } })
+      },
+      get children() {
+        return props.children
+      },
+    })
+}

package/src/fetcher.ts

@@ -0,0 +1,63 @@
+import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
+/**
+ * `@nifrajs/web-solid/fetcher` — Solid bindings for concurrent fetchers. `createFetcher(key)` bridges an
+ * independent {@link Fetcher}'s `subscribe`/`snapshot` store into a Solid signal (the pattern the F16
+ * spike confirmed) and returns its reactive state accessor plus `load`/`submit`; `useFetchers()`
+ * bridges the whole live collection. Imports only `solid-js` (never `solid-js/web`), so route
+ * components can use it on the server *and* client without pulling server/build code into the wrong
+ * bundle. No JSX (the package builds with plain `tsc`).
+ *
+ * The router that owns the fetchers registers itself via `setMountedRouter` from `mountRouter`. On the
+ * server (no mount) the accessors return an idle state — fetchers are client-only — so SSR markup is
+ * unchanged and the first client render after `mountRouter` takes over cleanly.
+ */
+import { type Accessor, createSignal, onCleanup } from "solid-js"
+
+// The active client router (set by `mountRouter`). Module-scoped: one app per page, client-only.
+let mountedRouter: ClientRouter | undefined
+
+/** Register (or clear) the router that owns fetchers — called by `mountRouter`. Not for app use. */
+export function setMountedRouter(router: ClientRouter | undefined): void {
+  mountedRouter = router
+}
+
+const IDLE: FetcherState = { pending: false, data: undefined }
+const noopAsync = async (): Promise<void> => {}
+
+/** A fetcher's reactive state accessor plus its imperative `load`/`submit`. */
+export interface FetcherHandle {
+  /** Reactive accessor for the fetcher's {@link FetcherState} (`pending`/`data`/`actionData`/...). */
+  readonly state: Accessor<FetcherState>
+  /** Load a route path's loader data into this fetcher (concurrent; doesn't touch the active view). */
+  readonly load: (path: string) => Promise<void>
+  /** Submit an action into this fetcher (concurrent); honors `X-Nifra-Revalidate`. */
+  readonly submit: (action: string, body: NonNullable<RequestInit["body"]>) => Promise<void>
+}
+
+/**
+ * Bind the independent fetcher for `key` (created lazily, stable). Returns a reactive `state()`
+ * accessor + `load`/`submit`. Multiple `createFetcher` calls with different keys run concurrently
+ * without disturbing the active route or each other. Call inside a component (owns the subscription).
+ */
+export function createFetcher(key: string): FetcherHandle {
+  const fetcher = mountedRouter?.fetcher(key)
+  const [state, setState] = createSignal<FetcherState>(fetcher ? fetcher.snapshot() : IDLE)
+  if (fetcher !== undefined) {
+    onCleanup(fetcher.subscribe(() => setState(fetcher.snapshot())))
+    return { state, load: fetcher.load, submit: fetcher.submit }
+  }
+  return { state, load: noopAsync, submit: noopAsync }
+}
+
+/**
+ * Bind the whole live fetcher collection — for a global busy view. Returns a reactive accessor; read
+ * each entry's `.snapshot()` for its state. Updates whenever any fetcher transitions or one is created.
+ */
+export function useFetchers(): Accessor<readonly Fetcher[]> {
+  const router = mountedRouter
+  const [list, setList] = createSignal<readonly Fetcher[]>(router ? router.fetchers() : [])
+  if (router !== undefined) {
+    onCleanup(router.subscribeFetchers(() => setList(router.fetchers())))
+  }
+  return list
+}

package/src/i18n.ts

@@ -0,0 +1,46 @@
+/**
+ * `@nifrajs/web-solid/i18n` — Solid bindings for `@nifrajs/i18n`. `<I18nProvider locale messages>` builds a
+ * `Formatter` (a `createMemo`, so switching locale rebuilds it) and provides it; `useT()` reads it.
+ * Both `locale` + `messages` are serializable, so a loader returns them, the page renders with the
+ * negotiated catalog on the server, and the client rebuilds the same formatter on hydrate (no
+ * mismatch). Imports only `solid-js` + `@nifrajs/i18n`; no JSX (`createComponent`).
+ */
+import { createFormatter, type Formatter, type Messages } from "@nifrajs/i18n"
+import {
+  type Accessor,
+  createComponent,
+  createContext,
+  createMemo,
+  type JSX,
+  useContext,
+} from "solid-js"
+
+const I18nContext = createContext<Accessor<Formatter>>()
+
+export interface I18nProviderProps {
+  readonly locale: string
+  readonly messages: Messages
+  readonly children?: JSX.Element
+}
+
+/** Provide a {@link Formatter} (built from `locale` + `messages`) to the subtree. Memoized on
+ * `locale`/`messages`, so switching locale rebuilds it. */
+export function I18nProvider(props: I18nProviderProps): JSX.Element {
+  const formatter = createMemo(() => createFormatter(props.locale, props.messages))
+  return createComponent(I18nContext.Provider, {
+    value: formatter,
+    get children() {
+      return props.children
+    },
+  })
+}
+
+/** Read the current {@link Formatter} (`{ locale, t, n, d }`). Throws if no `<I18nProvider>` is above.
+ * nifra switches locale by re-navigating, which re-runs the consuming component with the new catalog. */
+export function useT(): Formatter {
+  const formatter = useContext(I18nContext)
+  if (formatter === undefined) {
+    throw new Error("[nifra/web-solid] useT() must be used within an <I18nProvider>")
+  }
+  return formatter()
+}

package/src/image.ts

@@ -0,0 +1,68 @@
+/**
+ * `@nifrajs/web-solid/image` — a CLS-safe responsive Solid `<Image>`. A thin wrapper over `resolveImage`
+ * from `@nifrajs/image`: it computes the responsive `<img>` attributes (`src`/`srcset`/`sizes`/`width`/
+ * `height`/`loading`/`decoding`/`fetchpriority` via `toHtmlAttrs`) and renders an `<img>` through
+ * Solid's `<Dynamic>`. Extra DOM props (`class`, `style`, `id`, `data-*`, handlers) pass through
+ * reactively (`splitProps`/`mergeProps`). Resizing is delegated to the `loader`; nifra bundles no codec.
+ * No JSX (`createComponent`/`Dynamic`), so the package builds with plain `tsc`.
+ */
+import { type ImageLoader, type ImageProps, resolveImage, toHtmlAttrs } from "@nifrajs/image"
+import { createComponent, type JSX, mergeProps, splitProps } from "solid-js"
+import { Dynamic } from "solid-js/web"
+
+/** Attributes `resolveImage` computes — callers can't override them via DOM passthrough. */
+type ComputedAttrs =
+  | "src"
+  | "srcset"
+  | "sizes"
+  | "width"
+  | "height"
+  | "alt"
+  | "loading"
+  | "decoding"
+  | "fetchpriority"
+
+export interface ImageComponentProps
+  extends ImageProps,
+    Omit<JSX.ImgHTMLAttributes<HTMLImageElement>, ComputedAttrs | keyof ImageProps> {
+  /** CDN URL builder. Defaults to the identity loader (no transform — still CLS-safe + lazy). */
+  readonly loader?: ImageLoader
+}
+
+/**
+ * Render a responsive, CLS-safe `<img>`. `width`+`height` are required (reserve layout space);
+ * `priority` marks the LCP image (`eager` + `fetchpriority="high"`). Extra DOM props pass through.
+ */
+export function Image(props: ImageComponentProps): JSX.Element {
+  // Separate the nifra-only props (not valid DOM attributes) from the DOM passthrough (`rest`), keeping
+  // both reactive. `rest` carries class/style/id/handlers; the computed attrs are layered over it.
+  const [, rest] = splitProps(props, [
+    "loader",
+    "widths",
+    "quality",
+    "priority",
+    "src",
+    "width",
+    "height",
+    "alt",
+    "sizes",
+    "loading",
+  ])
+  const attrs = (): ReturnType<typeof toHtmlAttrs> => {
+    // Build ImageProps via conditional spreads (exactOptionalPropertyTypes: an unset optional is
+    // absent, not `undefined`). resolveImage validates width/height > 0 (CLS contract).
+    const input: ImageProps = {
+      src: props.src,
+      width: props.width,
+      height: props.height,
+      alt: props.alt,
+      ...(props.sizes !== undefined ? { sizes: props.sizes } : {}),
+      ...(props.widths !== undefined ? { widths: props.widths } : {}),
+      ...(props.quality !== undefined ? { quality: props.quality } : {}),
+      ...(props.loading !== undefined ? { loading: props.loading } : {}),
+      ...(props.priority !== undefined ? { priority: props.priority } : {}),
+    }
+    return toHtmlAttrs(resolveImage(input, props.loader))
+  }
+  return createComponent(Dynamic, mergeProps(rest, attrs, { component: "img" }))
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @nifrajs/web-solid — the Solid render adapter for @nifrajs/web (server side) + the Solid Babel
+ * Bun-plugin. Streaming SSR via `renderToStream` + `generateHydrationScript`; the layout-chain
+ * fold is in `./compose`. Client hydration lives in `@nifrajs/web-solid/client` (Solid's browser
+ * build).
+ */
+import { transformAsync } from "@babel/core"
+// @ts-expect-error — no type declarations published
+import presetTypeScript from "@babel/preset-typescript"
+import type { RenderAdapter } from "@nifrajs/web"
+// @ts-expect-error — no type declarations published
+import presetSolid from "babel-preset-solid"
+import type { BunPlugin } from "bun"
+import {
+  generateHydrationScript,
+  renderToStream as solidRenderToStream,
+  renderToString as solidRenderToString,
+} from "solid-js/web"
+import { compose } from "./compose.ts"
+
+const HYDRATION_HEAD = generateHydrationScript()
+
+/** The Solid server render adapter — pass to @nifrajs/web's `renderPage`. */
+export const solidAdapter: RenderAdapter = {
+  // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). Solid's
+  // `renderToString` emits the same hydratable markup (same `data-hk` keys seeded by
+  // `generateHydrationScript()`) as `renderToStream`, but skips the TransformStream + Solid's
+  // streaming machinery — the heaviest of the five renderers on Bun. A page that defer()s/Suspends
+  // takes `renderToStream` below (progressive resolution needs it).
+  renderToString(chain, props) {
+    return solidRenderToString(compose(chain, props))
+  },
+  renderToStream(chain, props) {
+    // Solid's `renderToStream` streams `Uint8Array` chunks into a Web `WritableStream` via
+    // `pipeTo` (fire-and-forget — returns void); pipe into a TransformStream and hand back the
+    // readable side. Suspense boundaries stream as they resolve; `generateHydrationScript()` (in
+    // <head>) seeds client hydration. A render failure errors `ts.readable`, which `renderPage`
+    // surfaces on the response body.
+    const ts = new TransformStream<Uint8Array, Uint8Array>()
+    solidRenderToStream(compose(chain, props)).pipeTo(ts.writable)
+    return ts.readable
+  },
+  hydrationHead() {
+    return HYDRATION_HEAD
+  },
+}
+
+/**
+ * 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.
+ */
+export function solidBunPlugin(generate: "dom" | "ssr"): BunPlugin {
+  return {
+    name: `nifra-solid-${generate}`,
+    setup(build) {
+      // 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 = args.path.split("?")[0] ?? 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 }],
+          ],
+        })
+        return { contents: result?.code ?? "", loader: "js" }
+      })
+    },
+  }
+}

package/src/mdx-runtime.ts

@@ -0,0 +1,54 @@
+/**
+ * Solid MDX runtime — the `useMDXComponents` provider that `@nifrajs/web-solid/mdx`'s compiled MDX imports
+ * (via `@mdx-js`'s `providerImportSource`). MDX emits intrinsic elements (`h1`, `p`, …) as *string*
+ * component references, but Solid can't `createComponent("h1")` — its JSX is compile-time. So we map
+ * each Markdown-output tag to a Solid component that renders it via `<Dynamic component={tag}>`.
+ */
+import { createComponent } from "solid-js"
+import { Dynamic } from "solid-js/web"
+
+// The HTML element set CommonMark + GFM produce. An explicit map (not a Proxy): `@mdx-js` *spreads* the
+// provider's result into a plain object, so only own-enumerable keys survive.
+const MARKDOWN_TAGS = [
+  "a",
+  "blockquote",
+  "br",
+  "code",
+  "del",
+  "em",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "img",
+  "input",
+  "li",
+  "ol",
+  "p",
+  "pre",
+  "section",
+  "span",
+  "strong",
+  "sup",
+  "table",
+  "tbody",
+  "td",
+  "th",
+  "thead",
+  "tr",
+  "ul",
+] as const
+
+const components: Record<string, (props: Record<string, unknown>) => unknown> = {}
+for (const tag of MARKDOWN_TAGS) {
+  components[tag] = (props) => createComponent(Dynamic, Object.assign({ component: tag }, props))
+}
+
+/** Returns the intrinsic-element → Solid-component map MDX content uses. Merge in your own overrides by
+ * passing `components` to the MDX content component (they take precedence). */
+export function useMDXComponents(): Record<string, (props: Record<string, unknown>) => unknown> {
+  return components
+}

package/src/mdx.ts

@@ -0,0 +1,60 @@
+/**
+ * `solidMdxBunPlugin` — compile `.mdx` routes/files to **Solid** components. MDX is JSX-oriented but
+ * Solid's JSX is compile-time, so this: (1) compiles MDX → JSX with `@mdx-js` (keeping JSX), pointing
+ * intrinsic elements at `@nifrajs/web-solid/mdx-runtime` (which renders them via Solid's `<Dynamic>`), then
+ * (2) runs `babel-preset-solid` — the same transform `solidBunPlugin` applies to `.tsx`. Pass it to
+ * `buildClient`/`buildServer`'s `plugins` (`"dom"` for the client, `"ssr"` for the server), like
+ * `solidBunPlugin`. `@mdx-js/mdx` is an optional peer (lazy-loaded at build time).
+ */
+import { transformAsync } from "@babel/core"
+// @ts-expect-error — no type declarations published
+import presetTypeScript from "@babel/preset-typescript"
+// @ts-expect-error — no type declarations published
+import presetSolid from "babel-preset-solid"
+import type { BunPlugin } from "bun"
+
+// Non-literal so tsc/consumers don't need `@mdx-js/mdx`'s types to typecheck this file (optional peer).
+const MDX_MODULE = "@mdx-js/mdx"
+
+interface MdxCompiler {
+  compile(source: string, options?: Record<string, unknown>): Promise<{ toString(): string }>
+}
+
+/** Build a `Bun.build` plugin that loads `.mdx` files as Solid components. `generate`: `"ssr"` for the
+ * server build, `"dom"` for the client (matches `solidBunPlugin`). */
+export function solidMdxBunPlugin(generate: "dom" | "ssr"): BunPlugin {
+  return {
+    name: `nifra-solid-mdx-${generate}`,
+    async setup(build) {
+      let compile: MdxCompiler["compile"]
+      try {
+        compile = ((await import(MDX_MODULE)) as MdxCompiler).compile
+      } catch {
+        throw new Error(
+          "@nifrajs/web-solid/mdx: compiling `.mdx` needs the `@mdx-js/mdx` package — install it (`bun add @mdx-js/mdx`).",
+        )
+      }
+      build.onLoad({ filter: /\.mdx(\?|$)/ }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        // 1. MDX → JSX, with intrinsics provided by the Solid runtime (rendered via `<Dynamic>`).
+        const jsx = String(
+          await compile(await Bun.file(path).text(), {
+            jsx: true,
+            providerImportSource: "@nifrajs/web-solid/mdx-runtime",
+          }),
+        )
+        // 2. babel-preset-solid (TS stripped first), exactly like `solidBunPlugin`.
+        const result = await transformAsync(jsx, {
+          filename: `${path}.tsx`,
+          presets: [
+            [presetSolid, { generate, hydratable: true }],
+            [presetTypeScript, { onlyRemoveTypeImports: true }],
+          ],
+          babelrc: false,
+          configFile: false,
+        })
+        return { contents: result?.code ?? "", loader: "js" }
+      })
+    },
+  }
+}

package/src/query.ts

@@ -0,0 +1,63 @@
+import { createQueryClient, type QueryClient, type QueryState } from "@nifrajs/web"
+/**
+ * `@nifrajs/web-solid/query` — Solid bindings for the keyed query-cache. `createQuery(key, fn)` bridges a
+ * query's `subscribe`/`snapshot` store into a Solid signal and fetches on mount; `useQueryClient`
+ * exposes `invalidateQueries` for after a mutation. Imports only `solid-js` + `@nifrajs/web` (never
+ * `solid-js/web`), so route components use it on the server *and* client. No JSX.
+ *
+ * The query client is created lazily **client-side only** (`typeof window`) — on the server the
+ * accessor returns the idle/pending state (queries are client-first; loaders are the SSR data source).
+ * The `key` is captured once (Solid setup runs once); a reactive key is a documented future enhancement.
+ */
+import { type Accessor, createSignal, onCleanup, onMount } from "solid-js"
+
+let client: QueryClient | undefined
+function getClient(): QueryClient | undefined {
+  if (typeof window === "undefined") return undefined // SSR → no client (queries render idle)
+  if (client === undefined) client = createQueryClient({ now: () => Date.now() })
+  return client
+}
+
+/** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
+export function useQueryClient(): Pick<QueryClient, "invalidateQueries"> {
+  return getClient() ?? { invalidateQueries: () => {} }
+}
+
+const IDLE: QueryState<never> = Object.freeze({
+  status: "pending",
+  data: undefined,
+  error: undefined,
+  isFetching: false,
+  updatedAt: Number.NEGATIVE_INFINITY,
+})
+
+/** A query's reactive state accessor plus `refetch`. */
+export interface CreateQueryResult<T> {
+  /** Reactive accessor for the {@link QueryState} (`status`/`data`/`error`/`isFetching`/`updatedAt`). */
+  readonly state: Accessor<QueryState<T>>
+  /** Force a refetch (ignores `staleTime`). */
+  readonly refetch: () => Promise<T>
+}
+
+/**
+ * Bind the keyed query for `key`, fetched via `fn`. Returns a reactive `state()` accessor + `refetch`.
+ * Concurrent `createQuery`s with the same key share one cache entry + one in-flight fetch (dedup).
+ * Fetches on mount; SSR-idle. Call inside a component (owns the subscription).
+ */
+export function createQuery<T>(key: unknown, fn: () => Promise<T>): CreateQueryResult<T> {
+  const handle = getClient()?.query<T>(key, fn)
+  const [state, setState] = createSignal<QueryState<T>>(handle ? handle.snapshot() : IDLE)
+  if (handle !== undefined) {
+    onCleanup(handle.subscribe(() => setState(() => handle.snapshot())))
+    onMount(() => {
+      handle.fetch().catch(() => {})
+    })
+    return { state, refetch: handle.refetch }
+  }
+  return {
+    state,
+    refetch: async () => {
+      throw new Error("[nifra/web-solid] createQuery.refetch called with no query client (server?)")
+    },
+  }
+}