@webtypen/webframez-react 0.0.1

package/README.md

@@ -0,0 +1,227 @@
+# webframez-react
+
+React Server Components (RSC) extension for `@webtypen/webframez-core`.
+
+`webframez-react` provides:
+- seamless `webframez-core` integration via `initWebframezReact(Route)`
+- file-based routing for `pages/**/index.tsx`
+- layout/error handling with `RouteChildren`
+- client-side navigation (`Link`, `Redirect`, `useRouter`) and cookies (`useCookie`)
+- server-rendered initial HTML plus RSC streaming
+
+## Requirements
+
+- Node.js `>= 20`
+- `@webtypen/webframez-core`
+- React Experimental (matching the package peer dependencies)
+
+## Installation
+
+```bash
+npm i @webtypen/webframez-react @webtypen/webframez-core react react-dom react-server-dom-webpack
+```
+
+## Quick Start with webframez-core
+
+```ts
+// server.ts
+import { WebApplication, Route } from "@webtypen/webframez-core";
+import { initWebframezReact } from "@webtypen/webframez-react/webframez-core";
+
+initWebframezReact(Route);
+
+Route.renderReact("/react", {
+  distRootDir: `${process.cwd()}/dist`,
+});
+
+WebApplication.boot();
+```
+
+Notes:
+- `"/react"` is automatically registered as a catch-all route (`/react/*`).
+- `basePath`, `assetsPrefix`, `rscPath`, and `clientScriptUrl` are derived automatically from the mount path.
+
+## Page Structure (File-Based Routing)
+
+Example:
+
+```txt
+pages/
+  layout.tsx
+  errors.tsx
+  index.tsx
+  about/index.tsx
+  accounts/[username]/index.tsx
+```
+
+`pages/layout.tsx`:
+
+```tsx
+"use server";
+
+import React from "react";
+import { RouteChildren } from "webframez-react/router";
+
+export default function Layout() {
+  return (
+    <main>
+      <nav>...</nav>
+      <RouteChildren />
+    </main>
+  );
+}
+```
+
+`RouteChildren` marks where the currently resolved page should be rendered.
+
+## Error Handling with `abort()`
+
+Every server page gets `abort()` via `RouteContext`.
+
+```tsx
+"use server";
+
+import type { PageProps } from "webframez-react/types";
+
+export default function AccountPage({ params, abort }: PageProps) {
+  if (params.username !== "jane") {
+    abort({
+      status: 404,
+      message: `Account \"${params.username}\" not found`,
+      payload: { attemptedUsername: params.username },
+    });
+  }
+
+  return <section>...</section>;
+}
+```
+
+Behavior:
+- default without options: `404` + `"Page not found"`
+- rendered through `pages/errors.tsx` (same behavior as unmatched routes)
+- `pathname` is provided automatically by context
+- optional `payload` is forwarded to `errors.tsx`
+
+## Client Entry
+
+```tsx
+// src/client.tsx
+import { mountWebframezClient } from "webframez-react/client";
+
+mountWebframezClient();
+```
+
+Optional:
+
+```tsx
+mountWebframezClient({
+  rootId: "root",
+  rscEndpoint: "/react/rsc",
+});
+```
+
+## Navigation
+
+```tsx
+"use client";
+
+import React from "react";
+import { Link, Redirect } from "webframez-react/navigation";
+
+export function Nav() {
+  return (
+    <>
+      <Link to="/">Home</Link>
+      <Link to="/about">About</Link>
+    </>
+  );
+}
+
+export function Guard({ loggedIn }: { loggedIn: boolean }) {
+  if (!loggedIn) {
+    return <Redirect to="/login" replace />;
+  }
+
+  return null;
+}
+```
+
+Note:
+- `Link` and `Redirect` automatically use the basename from `Route.renderReact()`.
+- You can override it per usage via `basename`.
+
+## Router and Cookies in Client Components
+
+```tsx
+"use client";
+
+import React from "react";
+import { useCookie, useRouter } from "webframez-react/client";
+
+export default function LoginAction() {
+  const cookie = useCookie();
+  const router = useRouter();
+
+  return (
+    <button
+      onClick={() => {
+        cookie.set("logged_in", "1", { path: "/react", sameSite: "Lax" });
+        router.refresh();
+      }}
+    >
+      Login
+    </button>
+  );
+}
+```
+
+## Public Entrypoints
+
+- `webframez-react`
+  - `createNodeRequestHandler`, `createFileRouter`, `createHTMLShell`, `sendRSC`, `createRSCHandler`
+- `webframez-react/webframez-core`
+  - `initWebframezReact`
+- `webframez-react/router`
+  - `RouteChildren`
+- `webframez-react/client`
+  - `mountWebframezClient`, `useRouter`, `useCookie`
+- `webframez-react/navigation`
+  - `Link`, `Redirect`
+- `webframez-react/types`
+  - all public types (`RouteContext`, `PageProps`, `ErrorPageProps`, ...)
+
+## package.json Scripts
+
+Example scripts for a `webframez-react` app:
+
+```json
+{
+  "scripts": {
+    "build:server": "tsc -p tsconfig.server.json",
+    "build:client": "webpack --config webpack.client.cjs",
+    "build": "npm run build:server && npm run build:client",
+    "start": "node --conditions react-server start-server.cjs",
+    "watch:server": "tsc -p tsconfig.server.json --watch --preserveWatchOutput",
+    "watch:client": "webpack --config webpack.client.cjs --watch",
+    "serve:watch": "node --watch --conditions react-server start-server.cjs",
+    "dev": "sh -c 'npm run watch:server & npm run watch:client & npm run serve:watch & wait'"
+  }
+}
+```
+
+Notes:
+- `build` compiles server output (`pages`, `server.ts`) and client output (`client.tsx` bundle + RSC manifests).
+- `start` runs the built app in React Server mode.
+- `dev` enables watch mode for TypeScript and webpack and restarts Node automatically on server output changes.
+
+## Build
+
+```bash
+npm run build
+```
+
+Watch mode:
+
+```bash
+npm run build:watch
+```

package/dist/client.cjs

@@ -0,0 +1 @@
+var _=Object.create;var d=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var S=Object.getPrototypeOf,U=Object.prototype.hasOwnProperty;var b=(e,n)=>{for(var t in n)d(e,t,{get:n[t],enumerable:!0})},g=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of O(n))!U.call(e,r)&&r!==t&&d(e,r,{get:()=>n[r],enumerable:!(o=k(n,r))||o.enumerable});return e};var A=(e,n,t)=>(t=e!=null?_(S(e)):{},g(n||!e||!e.__esModule?d(t,"default",{value:e,enumerable:!0}):t,e)),L=e=>g(d({},"__esModule",{value:!0}),e);var B={};b(B,{mountWebframezClient:()=>W,useCookie:()=>T,useRouter:()=>F});module.exports=L(B);var a=A(require("react"),1),x=require("react-dom/client"),v=require("react-server-dom-webpack/client"),i=require("react/jsx-runtime"),$={push:()=>{},replace:()=>{},refresh:()=>{}},l=typeof a.default.createContext=="function"?a.default.createContext(null):null,E="__WEBFRAMEZ_ROUTER__";function I(){return typeof window>"u"?null:window[E]??null}function P(e){typeof window>"u"||(window[E]=e)}function w(){let e={},n=typeof document>"u"?"":document.cookie;if(!n||n.trim()==="")return e;for(let t of n.split(";")){let o=t.trim();if(!o)continue;let r=o.indexOf("="),c=r>=0?o.slice(0,r).trim():o,u=r>=0?o.slice(r+1):"";c&&(e[c]=decodeURIComponent(u))}return e}function h(e,n,t={}){let o=[`${e}=${encodeURIComponent(n)}`];return t.path&&o.push(`Path=${t.path}`),t.domain&&o.push(`Domain=${t.domain}`),typeof t.maxAge=="number"&&o.push(`Max-Age=${Math.floor(t.maxAge)}`),t.expires&&o.push(`Expires=${t.expires.toUTCString()}`),t.sameSite&&o.push(`SameSite=${t.sameSite}`),t.secure&&o.push("Secure"),o.join("; ")}function T(){return a.default.useMemo(()=>({all:()=>w(),get:e=>w()[e],set:(e,n,t)=>{typeof document>"u"||(document.cookie=h(e,n,t))},remove:(e,n)=>{typeof document>"u"||(document.cookie=h(e,"",{...n??{},maxAge:0}))}}),[])}function F(){let e=l?a.default.useContext(l):null;if(!e){let n=I();if(n)return n;if(typeof window>"u")return $;throw new Error("useRouter must be used inside mountWebframezClient()")}return e}function C({active:e}){return(0,i.jsx)("div",{style:{position:"fixed",top:0,left:0,width:"100%",height:3,zIndex:9999,transformOrigin:"left",transform:e?"scaleX(1)":"scaleX(0)",transition:"transform 180ms ease",background:"linear-gradient(90deg, #0ea5e9, #22c55e)"}})}function M(e){return function(){let[t,o]=(0,a.useState)(null),[r,c]=(0,a.useState)(!1);async function u(s,f="push"){c(!0);try{let y=await(0,v.createFromFetch)(fetch(`${e}?path=${encodeURIComponent(s.pathname)}&search=${encodeURIComponent(s.search)}`,{headers:{Accept:"text/x-component"}}));o(y);let R=`${s.pathname}${s.search}`;f==="replace"?history.replaceState(null,"",R):f==="push"&&history.pushState(null,"",R)}catch(m){console.error("[webframez-react] Failed to render route",m),o((0,i.jsx)("p",{children:"Failed to load route."}))}finally{c(!1)}}(0,a.useEffect)(()=>{let s=()=>{u(new URL(window.location.href),"none")};return window.addEventListener("popstate",s),u(new URL(window.location.href),"none"),()=>{window.removeEventListener("popstate",s)}},[]);let p=a.default.useMemo(()=>({push:s=>{u(new URL(s,window.location.origin),"push")},replace:s=>{u(new URL(s,window.location.origin),"replace")},refresh:()=>{u(new URL(window.location.href),"none")}}),[]);return P(p),l?(0,i.jsxs)(l.Provider,{value:p,children:[(0,i.jsx)(C,{active:r}),t??(0,i.jsx)("p",{style:{padding:24},children:"Loading..."})]}):(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(C,{active:r}),t??(0,i.jsx)("p",{style:{padding:24},children:"Loading..."})]})}}function W(e={}){let n=e.rootId??"root",t=document.getElementById(n);if(!t)throw new Error(`Missing #${n} element`);let o=typeof window<"u"&&window.__RSC_ENDPOINT,r=e.rscEndpoint??o??"/rsc",c=M(r),u=(0,x.createRoot)(t);return u.render((0,i.jsx)(c,{})),u}

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { Root } from "react-dom/client";
+
+export type ClientOptions = {
+  rootId?: string;
+  rscEndpoint?: string;
+};
+
+export type RouterClient = {
+  push: (href: string) => void;
+  replace: (href: string) => void;
+  refresh: () => void;
+};
+
+export type CookieOptions = {
+  path?: string;
+  domain?: string;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+  maxAge?: number;
+  expires?: Date;
+};
+
+export type CookieClient = {
+  all: () => Record<string, string>;
+  get: (name: string) => string | undefined;
+  set: (name: string, value: string, options?: CookieOptions) => void;
+  remove: (name: string, options?: Omit<CookieOptions, "maxAge" | "expires">) => void;
+};
+
+export function mountWebframezClient(options?: ClientOptions): Root;
+export function useRouter(): RouterClient;
+export function useCookie(): CookieClient;

package/dist/client.js

@@ -0,0 +1 @@
+import c,{useEffect as E,useState as R}from"react";import{createRoot as y}from"react-dom/client";import{createFromFetch as _}from"react-server-dom-webpack/client";import{Fragment as b,jsx as u,jsxs as C}from"react/jsx-runtime";var k={push:()=>{},replace:()=>{},refresh:()=>{}},d=typeof c.createContext=="function"?c.createContext(null):null,x="__WEBFRAMEZ_ROUTER__";function O(){return typeof window>"u"?null:window[x]??null}function S(e){typeof window>"u"||(window[x]=e)}function g(){let e={},o=typeof document>"u"?"":document.cookie;if(!o||o.trim()==="")return e;for(let t of o.split(";")){let n=t.trim();if(!n)continue;let s=n.indexOf("="),a=s>=0?n.slice(0,s).trim():n,i=s>=0?n.slice(s+1):"";a&&(e[a]=decodeURIComponent(i))}return e}function w(e,o,t={}){let n=[`${e}=${encodeURIComponent(o)}`];return t.path&&n.push(`Path=${t.path}`),t.domain&&n.push(`Domain=${t.domain}`),typeof t.maxAge=="number"&&n.push(`Max-Age=${Math.floor(t.maxAge)}`),t.expires&&n.push(`Expires=${t.expires.toUTCString()}`),t.sameSite&&n.push(`SameSite=${t.sameSite}`),t.secure&&n.push("Secure"),n.join("; ")}function I(){return c.useMemo(()=>({all:()=>g(),get:e=>g()[e],set:(e,o,t)=>{typeof document>"u"||(document.cookie=w(e,o,t))},remove:(e,o)=>{typeof document>"u"||(document.cookie=w(e,"",{...o??{},maxAge:0}))}}),[])}function P(){let e=d?c.useContext(d):null;if(!e){let o=O();if(o)return o;if(typeof window>"u")return k;throw new Error("useRouter must be used inside mountWebframezClient()")}return e}function h({active:e}){return u("div",{style:{position:"fixed",top:0,left:0,width:"100%",height:3,zIndex:9999,transformOrigin:"left",transform:e?"scaleX(1)":"scaleX(0)",transition:"transform 180ms ease",background:"linear-gradient(90deg, #0ea5e9, #22c55e)"}})}function U(e){return function(){let[t,n]=R(null),[s,a]=R(!1);async function i(r,p="push"){a(!0);try{let v=await _(fetch(`${e}?path=${encodeURIComponent(r.pathname)}&search=${encodeURIComponent(r.search)}`,{headers:{Accept:"text/x-component"}}));n(v);let m=`${r.pathname}${r.search}`;p==="replace"?history.replaceState(null,"",m):p==="push"&&history.pushState(null,"",m)}catch(f){console.error("[webframez-react] Failed to render route",f),n(u("p",{children:"Failed to load route."}))}finally{a(!1)}}E(()=>{let r=()=>{i(new URL(window.location.href),"none")};return window.addEventListener("popstate",r),i(new URL(window.location.href),"none"),()=>{window.removeEventListener("popstate",r)}},[]);let l=c.useMemo(()=>({push:r=>{i(new URL(r,window.location.origin),"push")},replace:r=>{i(new URL(r,window.location.origin),"replace")},refresh:()=>{i(new URL(window.location.href),"none")}}),[]);return S(l),d?C(d.Provider,{value:l,children:[u(h,{active:s}),t??u("p",{style:{padding:24},children:"Loading..."})]}):C(b,{children:[u(h,{active:s}),t??u("p",{style:{padding:24},children:"Loading..."})]})}}function T(e={}){let o=e.rootId??"root",t=document.getElementById(o);if(!t)throw new Error(`Missing #${o} element`);let n=typeof window<"u"&&window.__RSC_ENDPOINT,s=e.rscEndpoint??n??"/rsc",a=U(s),i=y(t);return i.render(u(a,{})),i}export{T as mountWebframezClient,I as useCookie,P as useRouter};