npm - litzjs - Versions diffs - 0.0.0 - Mend

litzjs 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/LICENSE +21 -0
package/README.md +936 -0
package/dist/bindings-B1P6pL93.js +21 -0
package/dist/bindings-BDe-v5i6.mjs +10 -0
package/dist/chunk-8l464Juk.js +28 -0
package/dist/client.d.mts +35 -0
package/dist/client.d.ts +35 -0
package/dist/client.js +1633 -0
package/dist/client.mjs +1625 -0
package/dist/index.d.mts +559 -0
package/dist/index.d.ts +559 -0
package/dist/index.js +360 -0
package/dist/index.mjs +344 -0
package/dist/internal-transport-DR0r68ff.js +161 -0
package/dist/internal-transport-dsMykcNK.mjs +114 -0
package/dist/request-headers-DepZ5tjg.mjs +35 -0
package/dist/request-headers-ZPR3TQs3.js +46 -0
package/dist/server.d.mts +74 -0
package/dist/server.d.ts +74 -0
package/dist/server.js +316 -0
package/dist/server.mjs +315 -0
package/dist/vite.d.mts +10043 -0
package/dist/vite.d.ts +10043 -0
package/dist/vite.js +1481 -0
package/dist/vite.mjs +1474 -0
package/package.json +90 -0

package/README.md ADDED Viewed

@@ -0,0 +1,936 @@
+# Litz
+Litz is a client-first React framework for Vite.
+It gives you:
+- client-side navigation by default
+- explicit server boundaries with `server(...)`
+- route loaders and actions
+- reusable server-backed resources
+- raw API routes
+- `view(...)` responses powered by React Server Components / Flight
+## Status
+Litz is currently a production candidate.
+The core route, resource, API route, and RSC runtime now has deterministic route matching,
+multipart-safe internal actions, and a release gate via `bun run check`.
+## Installation
+Inside a React + Vite app:
+```bash
+bun add litz react react-dom
+```
+## Quick Start
+Add the Litz Vite plugin. By default, Litz discovers:
+- routes from `src/routes/**/*.{ts,tsx}`
+- API routes from `src/routes/api/**/*.{ts,tsx}`
+- resources from `src/routes/resources/**/*.{ts,tsx}`
+- a custom server entry from `src/server.ts`, falling back to `src/server/index.ts`
+`vite.config.ts`
+```ts
+import { defineConfig } from "vite";
+import { litz } from "litz/vite";
+export default defineConfig({
+  plugins: [litz()],
+});
+```
+You can still override discovery explicitly when you need a different project layout:
+```ts
+export default defineConfig({
+  plugins: [
+    litz({
+      routes: ["app/pages/**/*.{ts,tsx}"],
+      resources: ["app/resources/**/*.{ts,tsx}"],
+      api: ["app/api/**/*.{ts,tsx}"],
+      server: "app/server/entry.ts",
+    }),
+  ],
+});
+```
+Mount the Litz app from your browser entry.
+`src/main.tsx`
+```tsx
+import { mountApp } from "litz/client";
+const root = document.getElementById("app");
+if (!root) {
+  throw new Error('Missing "#app" root element.');
+}
+mountApp(root);
+```
+You can optionally provide a wrapper component around the app root:
+```tsx
+import { StrictMode } from "react";
+import { mountApp } from "litz/client";
+mountApp(root, StrictMode);
+```
+For providers or wrappers with props, pass a component:
+```tsx
+import { mountApp } from "litz/client";
+function AppProviders({ children }: React.PropsWithChildren) {
+  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
+}
+mountApp(root, AppProviders);
+```
+`index.html`
+```html
+<!doctype html>
+<html lang="en">
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+Create your first route.
+`src/routes/index.tsx`
+```tsx
+import { defineRoute } from "litz";
+export const route = defineRoute("/", {
+  component: HomePage,
+});
+function HomePage() {
+  return (
+    <main>
+      <h1>Welcome</h1>
+      <p>Your app is running on Litz.</p>
+    </main>
+  );
+}
+```
+## Routes
+Routes are explicit. The path you pass to `defineRoute(...)` is the source of truth.
+Add a loader when you need server data:
+```tsx
+import { data, defineRoute, server } from "litz";
+export const route = defineRoute("/me", {
+  component: ProfilePage,
+  loader: server(async () => {
+    return data({
+      user: {
+        id: "u_123",
+        name: "Ada",
+      },
+    });
+  }),
+});
+function ProfilePage() {
+  const profile = route.useLoaderData();
+  if (!profile) {
+    return null;
+  }
+  return <p>{profile.user.name}</p>;
+}
+```
+Routes and layouts can also define:
+- `pendingComponent` for the first unresolved loader pass
+- `errorComponent` for `error(...)` results and unhandled route faults
+- `middleware` for per-definition request handling
+## Layouts
+Layouts are explicit too. A route opts into a layout by importing it and passing `layout`.
+```tsx
+import type { ReactNode } from "react";
+import { defineLayout, defineRoute } from "litz";
+export const dashboardLayout = defineLayout("/dashboard", {
+  component: DashboardShell,
+});
+export const route = defineRoute("/dashboard/settings", {
+  component: SettingsPage,
+  layout: dashboardLayout,
+});
+function DashboardShell(props: { children: ReactNode }) {
+  return (
+    <div>
+      <aside>Dashboard nav</aside>
+      <section>{props.children}</section>
+    </div>
+  );
+}
+function SettingsPage() {
+  return <h1>Settings</h1>;
+}
+```
+Layouts can declare loaders and use the same route-state hooks:
+- `layout.useLoaderResult()`
+- `layout.useLoaderData()`
+- `layout.useLoaderView()`
+- `layout.useData()`
+- `layout.useView()`
+- `layout.useParams()`
+- `layout.useSearch()`
+- `layout.useStatus()`
+- `layout.usePending()`
+- `layout.useReload()`
+- `layout.useRetry()`
+## `view(...)`
+When you want the server to return UI instead of JSON, return `view(...)`.
+```tsx
+import * as React from "react";
+import { defineRoute, server, view } from "litz";
+export const route = defineRoute("/reports", {
+  component: ReportsPage,
+  loader: server(async () => {
+    return view(<ReportsPanel />);
+  }),
+});
+function ReportsPage() {
+  const view = route.useLoaderView();
+  if (!view) {
+    return <p>Loading reports...</p>;
+  }
+  return <React.Suspense fallback={<p>Loading reports...</p>}>{view}</React.Suspense>;
+}
+function ReportsPanel() {
+  return <section>Rendered on the server.</section>;
+}
+```
+Result hooks are layered:
+- `useLoaderResult()` and `useActionResult()` expose the raw normalized result branches
+- `useLoaderData()` / `useLoaderView()` and `useActionData()` / `useActionView()` / `useActionError()` expose branch-specific values
+- `useData()` / `useView()` / `useError()` expose the latest settled value from either the loader or action
+- unresolved values are `null`
+## Route State Hooks
+Routes expose state and control hooks beyond the result helpers:
+```tsx
+function SaveToolbar() {
+  const status = route.useStatus();
+  const pending = route.usePending();
+  const reload = route.useReload();
+  const retry = route.useRetry();
+  const submit = route.useSubmit({
+    onSuccess(result) {
+      console.log("saved", result.kind);
+    },
+  });
+  return (
+    <div>
+      <p>Status: {status}</p>
+      <button onClick={() => reload()} disabled={pending}>
+        Reload
+      </button>
+      <button onClick={() => retry()} disabled={pending}>
+        Retry
+      </button>
+      <button onClick={() => submit({ name: "Ada" })} disabled={pending}>
+        Save
+      </button>
+    </div>
+  );
+}
+```
+`useStatus()` returns one of:
+- `idle`
+- `loading`
+- `submitting`
+- `revalidating`
+- `offline-stale`
+- `error`
+Use the more specific hooks when you know which source you want:
+- `useLoaderData()` if you only care about loader `data(...)`
+- `useActionError()` if you only care about explicit action `error(...)`
+- `useView()` if you want the latest settled `view(...)` from either side
+## Actions
+Actions handle writes. They can return `data(...)`, `invalid(...)`, `redirect(...)`,
+`error(...)`, or `view(...)`.
+```tsx
+import { useFormStatus } from "react-dom";
+import { data, defineRoute, invalid, server } from "litz";
+export const route = defineRoute("/projects/new", {
+  component: NewProjectPage,
+  action: server(async ({ request }) => {
+    const formData = await request.formData();
+    const name = String(formData.get("name") ?? "").trim();
+    if (!name) {
+      return invalid({
+        fields: { name: "Name is required" },
+      });
+    }
+    return data({ ok: true, name });
+  }),
+});
+function NewProjectPage() {
+  const invalidResult = route.useInvalid();
+  const created = route.useActionData();
+  return (
+    <route.Form>
+      <input name="name" />
+      {invalidResult ? <p>{invalidResult.fields?.name}</p> : null}
+      {created ? <p>Created {created.name}</p> : null}
+      <SubmitButton />
+    </route.Form>
+  );
+}
+function SubmitButton() {
+  const status = useFormStatus();
+  return (
+    <button type="submit" disabled={status.pending}>
+      {status.pending ? "Creating..." : "Create"}
+    </button>
+  );
+}
+```
+`route.Form` uses React 19 form actions under the hood, so nested components can use
+`useFormStatus()` without extra framework wrappers.
+If you need imperative writes instead of a form, use `route.useSubmit()`.
+## Navigation
+Litz ships a small client navigation layer.
+```tsx
+import { Link, useNavigate } from "litz/client";
+function Nav() {
+  const navigate = useNavigate();
+  return (
+    <>
+      <Link href="/reports">Reports</Link>
+      <button onClick={() => navigate("/me")}>Go to profile</button>
+    </>
+  );
+}
+```
+`Link` keeps normal anchor ergonomics:
+- it uses `href`, not `to`
+- only `Link` intercepts same-origin plain clicks for client navigation
+- modifier clicks, external links, and downloads fall back to the browser
+Plain `<a href>` elements stay native and perform normal browser navigations.
+You can also inspect the active route chain:
+```tsx
+import { useMatches } from "litz";
+function Breadcrumbs() {
+  const matches = useMatches();
+  return (
+    <ol>
+      {matches.map((match) => (
+        <li key={match.id}>{match.path}</li>
+      ))}
+    </ol>
+  );
+}
+```
+If you want the current concrete browser location instead of the route pattern chain:
+```tsx
+import { useLocation, usePathname } from "litz";
+function RouteMeta() {
+  const pathname = usePathname();
+  const location = useLocation();
+  return (
+    <>
+      <p>Pathname: {pathname}</p>
+      <p>Hash: {location.hash || "(none)"}</p>
+    </>
+  );
+}
+```
+`useLocation()` returns:
+- `href`
+- `pathname`
+- `search`
+- `hash`
+## Search Params
+Search params are part of the route runtime:
+```tsx
+function ReportsFilters() {
+  const [searchParams, setSearch] = route.useSearch();
+  const tab = searchParams.get("tab") ?? "all";
+  return (
+    <>
+      <p>Current tab: {tab}</p>
+      <button onClick={() => setSearch({ tab: "open", tag: ["bug", "urgent"] })}>
+        Show open bugs
+      </button>
+      <button onClick={() => setSearch({ tag: null }, { replace: true })}>Clear tags</button>
+    </>
+  );
+}
+```
+`setSearch(...)` merges by default:
+- `string` sets a single value
+- `string[]` writes repeated keys
+- `null` or `undefined` deletes a key
+- unchanged updates are ignored
+- updates go through the normal client navigation and revalidation path
+Layouts expose the same `[searchParams, setSearch]` tuple.
+## Resources
+Resources are route-agnostic ways to package client-side and server-side functionality into a
+self-contained component or unit of code.
+They are for cases where something should be reusable across routes, layouts, and app shells
+without becoming a page of its own. A resource can own:
+- its own server loader
+- its own server action
+- its own pending and error state
+- its own params and search input
+- its own client UI
+The mental model is:
+- routes own navigation
+- resources own reusable server-backed UI behavior
+Each rendered `<resource.Component ... />` creates a scoped resource instance. Inside that subtree,
+resource hooks work like route hooks, but against that resource instance.
+### Loader-Only Resource
+A resource always declares a `component`. That component reads resource state through hooks.
+```tsx
+import { data, defineResource, server } from "litz";
+export const resource = defineResource("/resource/user/:id", {
+  component: UserCard,
+  loader: server(async ({ params }) => {
+    return data({
+      user: {
+        id: params.id,
+        name: "Ada",
+      },
+    });
+  }),
+});
+function UserCard() {
+  const user = resource.useLoaderData();
+  const pending = resource.usePending();
+  if (!user) {
+    return <p>{pending ? "Loading..." : "No user"}</p>;
+  }
+  return <p>{user.user.name}</p>;
+}
+```
+Render it anywhere:
+```tsx
+<resource.Component params={{ id: "u_123" }} />
+```
+### Search Params And Params
+Resources receive `params` and optional `search` at the component boundary:
+```tsx
+<resource.Component params={{ id: "u_123" }} search={{ tab: "profile" }} />
+```
+Inside the resource, use the scoped hooks:
+```tsx
+function UserCard() {
+  const params = resource.useParams();
+  const [searchParams, setSearch] = resource.useSearch();
+  const tab = searchParams.get("tab") ?? "profile";
+  return (
+    <>
+      <p>User id: {params.id}</p>
+      <p>Tab: {tab}</p>
+      <button onClick={() => setSearch({ tab: "security" })}>Security</button>
+    </>
+  );
+}
+```
+### View-Based Resource
+Resources can also return `view(...)` from the server and consume it with `resource.useView()`:
+```tsx
+import * as React from "react";
+import { defineResource, server, view } from "litz";
+export const resource = defineResource("/resource/account/:id", {
+  component: AccountMenu,
+  loader: server(async ({ params }) => {
+    return view(<section>Account {params.id}</section>);
+  }),
+});
+function AccountMenu() {
+  const view = resource.useView();
+  if (!view) {
+    return <p>Loading account menu...</p>;
+  }
+  return <React.Suspense fallback={<p>Loading account menu...</p>}>{view}</React.Suspense>;
+}
+```
+### Action-Enabled Resource
+Resources can define actions with the same self-contained form story as routes:
+```tsx
+import * as React from "react";
+import { defineResource, server, view } from "litz";
+import { useFormStatus } from "react-dom";
+export const resource = defineResource("/resource/feed/:id", {
+  component: FeedPanel,
+  loader: server(async ({ params }) => {
+    return view(
+      <ul>
+        <li>Feed {params.id}</li>
+      </ul>,
+    );
+  }),
+  action: server(async ({ params, request }) => {
+    const formData = await request.formData();
+    const message = String(formData.get("message") ?? "");
+    return view(
+      <ul>
+        <li>{params.id}</li>
+        <li>{message}</li>
+      </ul>,
+    );
+  }),
+});
+function FeedPanel() {
+  const view = resource.useView();
+  const pending = resource.usePending();
+  const [message, setMessage] = React.useState("");
+  return (
+    <resource.Form
+      onSubmit={(event) => {
+        if (!message.trim()) {
+          event.preventDefault();
+          return;
+        }
+        setMessage("");
+      }}
+    >
+      <input
+        name="message"
+        value={message}
+        onChange={(event) => setMessage(event.target.value)}
+        disabled={pending}
+      />
+      <SubmitButton />
+      {view ? <React.Suspense fallback={<p>Loading...</p>}>{view}</React.Suspense> : null}
+    </resource.Form>
+  );
+}
+function SubmitButton() {
+  const status = useFormStatus();
+  return (
+    <button type="submit" disabled={status.pending}>
+      {status.pending ? "Sending..." : "Send"}
+    </button>
+  );
+}
+```
+You can also submit imperatively:
+```tsx
+function QuickActions() {
+  const submit = resource.useSubmit();
+  const pending = resource.usePending();
+  return (
+    <button disabled={pending} onClick={() => void submit({ message: "Pinned update" })}>
+      Post preset message
+    </button>
+  );
+}
+```
+### Available Resource Hooks
+Inside a resource component subtree, resources expose the same style of hooks as routes:
+- `resource.useLoaderResult()`
+- `resource.useLoaderData()`
+- `resource.useLoaderView()`
+- `resource.useActionResult()`
+- `resource.useActionData()`
+- `resource.useActionView()`
+- `resource.useActionError()`
+- `resource.useInvalid()`
+- `resource.useData()`
+- `resource.useView()`
+- `resource.useError()`
+- `resource.useStatus()`
+- `resource.usePending()`
+- `resource.useParams()`
+- `resource.useSearch()`
+- `resource.useReload()`
+- `resource.useRetry()`
+- `resource.useSubmit()`
+- `resource.Form`
+The main split to keep in mind:
+- `useLoaderData()` / `useLoaderView()` read loader-only state
+- `useActionData()` / `useActionView()` / `useActionError()` / `useInvalid()` read action-only state
+- `useData()` / `useView()` / `useError()` read the latest settled merged value for the resource
+### Multiple Resource Instances
+Resources are instance-scoped, not global. You can render the same resource multiple times on the
+same page with different inputs:
+```tsx
+<>
+  <userCard.Component params={{ id: "u_123" }} />
+  <userCard.Component params={{ id: "u_456" }} />
+</>
+```
+Each instance resolves against its own `params` and `search`. If two instances render with the
+same resource path and the same request identity, they share the keyed runtime state under the hood,
+so they stay in sync instead of duplicating work.
+## API Routes
+API routes expose raw HTTP handlers and come with a thin client helper.
+```ts
+import { defineApiRoute } from "litz";
+export const api = defineApiRoute("/api/health", {
+  middleware: [],
+  GET() {
+    return Response.json({ ok: true });
+  },
+  ALL({ request }) {
+    return Response.json({ method: request.method });
+  },
+});
+```
+```ts
+const response = await api.fetch();
+const data = await response.json();
+```
+Supported method keys:
+- `GET`
+- `POST`
+- `PUT`
+- `PATCH`
+- `DELETE`
+- `OPTIONS`
+- `HEAD`
+- `ALL`
+`ALL` acts as a fallback when there is no method-specific handler.
+`api.fetch(...)` accepts route params, search params, headers, and the HTTP method when needed.
+## Server Runtime
+Litz ships a default WinterCG-style server runtime:
+```ts
+import { createServer } from "litz/server";
+export default createServer({
+  createContext(request) {
+    return {
+      requestId: request.headers.get("x-request-id"),
+    };
+  },
+  onError(error, context) {
+    console.error("Litz server error", { error, context });
+  },
+});
+```
+In simple apps, `createServer()` with no arguments is enough:
+```ts
+import { createServer } from "litz/server";
+export default createServer();
+```
+The Vite plugin injects the discovered server manifest automatically into that entry.
+### Production Output
+When you run `vite build`, Litz always writes the browser assets to `dist/client`.
+Server output depends on whether you provide a custom server entry:
+- No custom server entry:
+  Litz emits a self-contained `dist/server/index.js`.
+  That file inlines the built document HTML and all client asset contents, so the server handler can
+  serve `/` and `/assets/*` by itself. This is the default one-file server deployment mode.
+- Custom server entry present:
+  Litz emits `dist/server/index.js` from your server entry and injects the discovered server
+  manifest into `createServer(...)`.
+  Litz does not inject static asset or document serving in this mode. Your host server or platform
+  is responsible for serving `dist/client` however you want, for example through `express.static`,
+  a CDN, or a platform asset binding.
+You can let Litz discover `src/server.ts` or `src/server/index.ts`, or configure a different path
+explicitly in `vite.config.ts`:
+```ts
+import { defineConfig } from "vite";
+import { litz } from "litz/vite";
+export default defineConfig({
+  plugins: [
+    litz({
+      server: "app/server/entry.ts",
+    }),
+  ],
+});
+```
+In the custom-server case, unmatched document and static asset requests fall through to the normal
+`createServer(...)` 404 behavior unless your host server handles them first.
+## Security Model
+Litz's server boundaries are explicit, but they are still normal server request surfaces.
+- Route loaders and actions are server handlers.
+- Resource loaders and actions are server handlers.
+- API routes are raw HTTP handlers.
+- The `/_litz/*` transport used by the client runtime is an implementation detail, not a private trust boundary.
+That means Litz apps should treat route loaders, actions, resources, and API routes like any other
+server endpoint:
+- authenticate and authorize inside middleware or handlers
+- validate params, search params, headers, and form/body input
+- apply CSRF protections when using cookie-backed auth for writes
+- do not assume a request came from Litz just because it arrived through `/_litz/*`
+Litz may serve `index.html` itself, but it also supports deployments where the document is served
+statically or by a custom server. Security decisions must not depend on the document coming from
+Litz.
+## Result Helpers
+Server handlers can return these helpers:
+- `data(value, options?)`
+- `view(node, options?)`
+- `invalid({ ... })`
+- `redirect(location, options?)`
+- `error(status, message, options?)`
+- `withHeaders(result, headers)`
+```tsx
+import { data, defineRoute, error, redirect, server, withHeaders } from "litz";
+export const route = defineRoute("/projects/:id", {
+  component: ProjectPage,
+  loader: server(async ({ params }) => {
+    if (params.id === "new") {
+      return redirect("/projects/create");
+    }
+    return withHeaders(data({ id: params.id }, { revalidate: ["/projects/:id"] }), {
+      "cache-control": "private, max-age=60",
+    });
+  }),
+  action: server(async ({ request }) => {
+    const formData = await request.formData();
+    if (!formData.get("name")) {
+      return error(422, "Missing project name", {
+        code: "missing_name",
+        data: { field: "name" },
+      });
+    }
+    return data({ ok: true });
+  }),
+});
+```
+Behavior summary:
+- `data(...)` populates loader/action data hooks
+- `view(...)` populates loader/action view hooks
+- `invalid(...)` populates `useInvalid()`
+- `redirect(...)` navigates instead of producing hook state
+- explicit action `error(...)` is available through `useActionError()` and `useError()`
+- route faults and loader failures go through route error boundaries
+## Middleware
+Routes, resources, and API routes can declare a `middleware` array. Middleware runs in order and can continue with `next()`, short-circuit with a result, or explicitly replace `context` with `next({ context })`.
+```tsx
+import { data, defineApiRoute, defineRoute, error, server } from "litz";
+export const route = defineRoute("/dashboard", {
+  component: DashboardPage,
+  middleware: [
+    async ({ context, next }) => {
+      if (!context.userId) {
+        return error(401, "Unauthorized");
+      }
+      return next();
+    },
+  ],
+  loader: server(async ({ context }) => {
+    return data({ userId: context.userId });
+  }),
+});
+export const api = defineApiRoute("/api/dashboard", {
+  middleware: [
+    async ({ context, next }) => {
+      if (!context.userId) {
+        return Response.json({ error: "Unauthorized" }, { status: 401 });
+      }
+      return next();
+    },
+  ],
+  GET({ context }) {
+    return Response.json({ userId: context.userId });
+  },
+});
+```
+Middleware receives:
+- `request`
+- `params`
+- `context`
+- `signal`
+- `next(...)`
+## Core Ideas
+- Litz is SPA-first. The browser owns the document.
+- Server logic only exists at explicit framework boundaries.
+- `view(...)` uses RSC as a transport, not as the whole app architecture.
+- Routes, resources, and API routes are discovered from top-level glob options.
+- Paths are explicit and absolute.
+## Try The Fixture
+This repo includes a working fixture app in [`fixtures/rsc-smoke`](./fixtures/rsc-smoke):
+```bash
+bun run fixture:dev
+```
+Then open [http://127.0.0.1:4173/](http://127.0.0.1:4173/).