acrylblends 0.6.2 → 0.6.4

package/README.md

@@ -273,10 +273,14 @@ See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting
 | `acrylblends/utils/*` | the utilities the framework is built from |
 | `acrylblends/tiny`, `acrylblends/quick` | the presets: `Acryl` with another router (`PatternRouter`; `LinearRouter` and `TrieRouter`) ([presets](https://github.com/acryldev/acryl/blob/main/docs/framework/api/presets.md)) |
 | `acrylblends/cache`, `acrylblends/mount` | the cache middleware and mounting another framework's fetch handler |
+| `acrylblends/ssg` | static site generation: `toSSG` writes every route as a file ([SSG helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/ssg.md)) |
 | `acrylblends/proxy`, `acrylblends/dev` | the proxy helper and the dev helpers (`showRoutes`, `inspectRoutes`, `getRouterName`) |
+| `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx.md)) |
+| `acrylblends/jsx/dom` | JSX in the browser: hooks and `render` (needs the DOM library) ([client components](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx-dom.md)) |
+| `acrylblends/css` | CSS in JSX: `css`, `cx`, `keyframes`, `Style` ([CSS helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/css.md)) |
 | `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static` and `node-server/conninfo` |
 
-Every subpath is listed in the package's `exports`. JSX, SSG and other runtimes' adapters are being ported. The docs mark them "not yet available" until they ship
+Every subpath is listed in the package's `exports`. The adapters of other runtimes are being ported. The docs mark them "not yet available" until they ship
 ([FAQ](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/faq.md)).
 
 To extend the context's typed variables, augment the root module:

package/docs/framework/README.md

@@ -39,14 +39,15 @@ Verified: Node.js. Bun is experimental. The other runtimes the framework could t
 
 ## Not yet available
 
-Some parts of the documented API surface are not part of the package yet, and their pages say so at the top: the JSX packages, static site generation, the CSS helper, the
-`proxy`, `dev` and `cache` pieces, the `quick` and `tiny` presets and the adapters of the runtimes other than Node.js. They are enabled as they are ported.
+Some parts of the documented API surface are not part of the package yet, and their pages say so at the top: the adapters of the runtimes other than Node.js.
+They are enabled as they are ported.
 
 ## Where to read next
 
 | I want to | Read |
 | --- | --- |
 | Run something in five minutes | [Getting started](getting-started/basic.md) |
+| Run the app as a desktop app | [Desktop](getting-started/desktop.md) |
 | Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
 | Understand the design | [Concepts](concepts/motivation.md) |
 | Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md) |

package/docs/framework/UPSTREAM.md

@@ -1,3 +1,3 @@
 # Generated copy
 
-This folder is a copy of `docs/framework` of acryldev/acryl at commit `0174cb01625bfd32d0162ad56179c582f353321e`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `fd1f7dcaaff8b757c0562294002c0d32d6e0a893`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

package/docs/framework/cordis/acryl-in-a-cordis-app.md

@@ -94,6 +94,12 @@ const app = new Acryl()
 Use middleware for authentication, logging, CORS, compression, request IDs and other behavior that should wrap more than one handler.
 The built-in set is listed in [Middleware](../concepts/middleware.md).
 
+## Render pages with JSX
+
+A plugin renders HTML with the same JSX as the published package: set `"jsx": "react-jsx"` and `"jsxImportSource": "acryl-router/jsx"`
+in its `tsconfig.json` (a `.tsx` file), and style with the CSS helper from `acryl-router/helpers`. Streaming with `Suspense` is in
+`acryl-router/jsx/streaming`. The [JSX guide](../guides/jsx.md) covers the rest; its examples import from `acrylblends/jsx` instead.
+
 ## Run the same app on a surface
 
 The application does not open a socket. A surface supplies requests to it:

package/docs/framework/getting-started/basic.md

@@ -192,5 +192,6 @@ See [Testing](../guides/testing.md).
 ## Next
 
 - [Node.js](nodejs.md) and [Bun](bun.md) (experimental)
+- [Desktop](desktop.md): the same app in an Electron window
 - [Routing](../api/routing.md), [Context](../api/context.md) and [Request](../api/request.md)
 - [Validation](../guides/validation.md)

package/docs/framework/getting-started/desktop.md

@@ -0,0 +1,41 @@
+# Desktop
+
+An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
+template) and a Blend app (the `acryl-app` template or `acrylblends init`). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
+
+## Add it
+
+In an Acryl app made by `npm create acrylblends@latest my-app -- --template nodejs`:
+
+```sh
+cd my-app
+npm install
+npx acrylblends add desktop
+npm install
+npm run desktop
+```
+
+In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm install`) add the Blend form of the shell, and `npx acrylblends init my-app --template todo --desktop` creates a Blend app with it already in.
+`acrylblends add desktop` chooses the right form: a Blend app (it has `src/plugins/instance`) or a plain Acryl app.
+
+## What it adds
+
+- `src/plugins/desktop-web/` (a plain app) or `src/plugins/desktop/` (a Blend app): the window code. Only this folder imports `electron`; the app's own code never does.
+- `electron` as a development dependency (pinned to 44.0.0) and the script `npm run desktop`.
+- `.acrylblends/` in `.gitignore`: Electron's user data (window state, cache, logs) lives in `.acrylblends/electron` inside the app's own folder, never in the user's application-data folder.
+
+## What `npm run desktop` does
+
+1. Serves the app on `127.0.0.1` with a free port: for a plain app, `app.fetch` from `src/app.ts` (`export default app`) through `acrylblends/node-server`; for a Blend app, its own `createApp`.
+2. Takes a single-instance lock: a second launch of the same app focuses the first window and exits.
+3. Opens one window on the server's address, with a locked-down renderer (context isolation, no Node in the page, the sandbox, web security). Navigation stays on the app's own origin; any other link opens in the system browser.
+4. When the window closes (or on SIGINT or SIGTERM), stops the server and exits.
+
+## The first launch downloads Electron
+
+`npm install` does not download Electron's binary (Electron 44 has no install script). The first `npm run desktop` does: about 100 MB, once per machine, then it is cached. Behind a proxy or mirror set `ELECTRON_MIRROR`
+(and `ELECTRON_CACHE` to reuse a download); if the download is blocked, run `npx install-electron` where the mirror is reachable.
+
+## A different start page
+
+The window opens on `/`. To open another path, set it in `package.json`: `"acrylblends": { "desktopPath": "/todo" }`.

package/docs/framework/guides/jsx-dom.md

@@ -1,8 +1,5 @@
 # Client Components
 
-> **Not yet available.** The client-side JSX package (`acrylblends/jsx/dom`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
-
-
 `acrylblends/jsx` supports not only server side but also client side. This means that it is possible to create an interactive UI that runs in the browser. We call it Client Components or `acrylblends/jsx/dom`.
 
 It is fast and very small. The counter program in `acrylblends/jsx/dom` is only 2.8KB with Brotli compression, but 47.8KB for React.

package/docs/framework/guides/jsx.md

@@ -1,12 +1,33 @@
 # JSX
 
-> **Not yet available.** The JSX packages (`acrylblends/jsx` and its subpaths) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
-
-
 You can write HTML with JSX syntax with `acrylblends/jsx`.
 
 Although `acrylblends/jsx` works on the client, you will probably use it most often when rendering content on the server side. Here are some things related to JSX that are common to both server and client.
 
+## Node.js runs `jsx()`, not JSX syntax
+
+The apps `npm create acrylblends@latest` makes run their TypeScript on Node.js by stripping the types (no build step). That does **not** compile JSX: a `.tsx` file does not load. Either compile the file first (`tsc`
+or a bundler, with the settings below), or write the call that JSX compiles to. `jsx(tag, props, ...children)` takes the children after the props, and a node renders with `toString()`:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { jsx } from 'acrylblends/jsx'
+import type { PropsWithChildren } from 'acrylblends/jsx'
+
+const Layout = (props: PropsWithChildren<{ title: string }>) =>
+  jsx('html', { lang: 'en' }, jsx('head', null, jsx('title', null, props.title)), jsx('body', null, props.children))
+
+const About = () =>
+  jsx(Layout, { title: 'About' }, jsx('h1', null, 'About'), jsx('p', { class: 'lead' }, 'Rendered on the server.'))
+
+const app = new Acryl()
+app.get('/about', (c) => c.html(jsx(About, null).toString()))
+
+export default app
+```
+
+Pass the children as arguments after the props. A `children` entry inside the props object is not rendered by this form.
+
 ## Settings
 
 To use JSX, modify the `tsconfig.json`:

package/docs/framework/helpers/css.md

@@ -1,8 +1,5 @@
 # css Helper
 
-> **Not yet available.** The CSS helper (`acrylblends/css`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
-
-
 The CSS helper - `acrylblends/css` - is Acryl's built-in CSS in JS(X).
 
 You can write CSS in JSX in a JavaScript template literal named `css`. The return value of `css` will be the class name, which is set to the value of the class attribute. The `<Style />` component will then contain the value of the CSS.

package/docs/framework/helpers/ssg.md

@@ -1,8 +1,5 @@
 # SSG Helper
 
-> **Not yet available.** Static site generation (`acrylblends/ssg`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
-
-
 SSG Helper generates a static site from your Acryl application. It will retrieve the contents of registered routes and save them as static files.
 
 ## Usage
@@ -237,7 +234,7 @@ Plugins allow you to extend the functionality of the static site generation proc
 
 ### Default Plugin
 
-By default, `toSSG` uses `defaultPlugin` which skips non-200 status responses (like redirects, errors, or 404s). This prevents generating files for unsuccessful responses.
+By default, `toSSG` uses `defaultPlugin()`, which skips non-200 status responses (like redirects, errors, or 404s). This prevents generating files for unsuccessful responses.
 
 ```ts
 import { toSSG, defaultPlugin } from 'acrylblends/ssg'
@@ -246,14 +243,14 @@ import { toSSG, defaultPlugin } from 'acrylblends/ssg'
 toSSG(app, fs)
 
 // Equivalent to:
-toSSG(app, fs, { plugins: [defaultPlugin] })
+toSSG(app, fs, { plugins: [defaultPlugin()] })
 ```
 
 If you specify custom plugins, `defaultPlugin` is **not** automatically included. To keep the default behavior while adding custom plugins, explicitly include it:
 
 ```ts
 toSSG(app, fs, {
-  plugins: [defaultPlugin, myCustomPlugin],
+  plugins: [defaultPlugin(), myCustomPlugin],
 })
 ```
 

package/docs/framework/middleware/builtin/jsx-renderer.md

@@ -1,8 +1,5 @@
 # JSX Renderer Middleware
 
-> **Not yet available.** The JSX renderer middleware (`acrylblends/jsx-renderer`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
-
-
 JSX Renderer Middleware allows you to set up the layout when rendering JSX with the `c.render()` function, without the need for using `c.setRenderer()`. Additionally, it enables access to instances of Context within components through the use of `useRequestContext()`.
 
 ## Import

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "0174cb01625bfd32d0162ad56179c582f353321e"
+    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
   },
-  "files": 87,
-  "digest": "sha256:be8b4bb2555dbc97ef94caa57f6b071f5c0f173f0711eecc2836a537a1a71681"
+  "files": 88,
+  "digest": "sha256:5e6989c7fe1b3006f8917926d8cc3e84e14c2af03440682c18d22bec0045c3d2"
 }

package/lib/accepts.d.ts

@@ -1,4 +1,4 @@
-import { t as Context } from "./context-B5Y1lLha.js";
+import { t as Context } from "./context-DS3fYyG-.js";
 import { t as AcceptHeader } from "./headers-tu2YYN8T.js";
 
 //#region ../../plugins/acryl-router/src/core/helper/accepts/accepts.d.ts

package/lib/acryl-base.d.ts

@@ -1,2 +1,2 @@
-import { $ as Acryl, et as AcrylOptions } from "./context-B5Y1lLha.js";
+import { et as Acryl, tt as AcrylOptions } from "./context-DS3fYyG-.js";
 export { Acryl as AcrylBase, AcrylOptions };

package/lib/adapter.d.ts

@@ -1,4 +1,4 @@
-import { t as Context } from "./context-B5Y1lLha.js";
+import { t as Context } from "./context-DS3fYyG-.js";
 
 //#region ../../plugins/acryl-router/src/core/helper/adapter/index.d.ts
 type Runtime = 'node' | 'deno' | 'bun' | 'workerd' | 'fastly' | 'edge-light' | 'other';

package/lib/{app-BdrVHBlJ.d.ts → app-D8riatvv.d.ts}

@@ -1,4 +1,4 @@
-import { $ as Acryl$1, J as Schema, _ as Env, et as AcrylOptions, h as BlankSchema, p as BlankEnv } from "./context-B5Y1lLha.js";
+import { Y as Schema, et as Acryl$1, g as BlankSchema, m as BlankEnv, tt as AcrylOptions, v as Env } from "./context-DS3fYyG-.js";
 
 //#region ../../plugins/acryl-router/src/core/app.d.ts
 /**