Skip to content

Commit bb66b43

Browse files
ryansolidClaude via Cursorcursoragentclaude
authored
examples: idiomatic pass — hackernews twins, notes, occlusion specs (#3717)
* examples: hackernews collapse as a binding slot, twins in the authoring layout The thread's collapse was a `Toggle` client component wrapping a template slot. It is now a binding slot on server markup: the recursive `Comment` is a server component, and each comment with replies calls `props.toggle({ $key: c.id })` and binds the toggle's `open` class name, its `onClick`, its label (a text position) and the replies' `display`. The fill is the SPA twin's `Toggle` without its markup: a signal in the body, getters over it, a plain handler. No client components remain. Both twins take the authoring layout: each route file holds its query with the server function inline (markup in one twin, data in the other), and `src/server/hn.ts` is a plain module behind `import "server-only"`, with the boundary types referenced from `vite-env.d.ts` (TypeScript 6 rejects the undeclared side-effect import). `lib/`, `api.ts`, `views.tsx` and `components/toggle.tsx` go. `CommentDefinition` gains `id` and `StoryDefinition.id` is a number, as the data carries. The READMEs lead with the collapse, name their coordinates, and correct the bundle check (grep the client JavaScript; `app.css` carries both class names). A server spec pins the class-array form at a binding position on both faces. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: hackernews server routes, nav outside Loading, router next.31 The feeds and the user page have no client half, so they become server routes: `serverRouteComponent(query(...))`, with the router making the call from the match on navigation and on link hover, so they need no route component and no `preload`. The feeds are one `/:type?` route filtered to the five feed names, with `page` read through a hand-written search schema. The story route keeps its component because of the collapse fill. The nav leaves the `Loading` boundary, since it does no I/O and the shell can wait on it. The SPA twin uses the same route pattern and filter, and parses `?page` itself. Router 2.0.0-next.29 sent a schema-less server route's args as `{ params, search: undefined }`. The JSON argument check rejects that, so client navigation to the user page silently never happened. next.30 fixed it (#615), so every example that uses the router moves to next.31. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: hackernews collapse as native details, navigation dim The collapse only hides replies, which is what <details> does natively, so the binding slot was a heavier way to do what the browser already does. Both twins now render the same <details> with a CSS label swap: the server twin's thread has no client code, its story route becomes a server route like the feeds and user page, and the SPA's Toggle component is deleted. The toggle styles move to the <summary> so font sizes don't compound with nesting. Markup stays byte-identical between the twins. Both roots dim the page while a navigation is pending (`useIsRouting()`), with a short delay so a navigation that hover preloading already made fast never flickers. The old page stays up instead of going blank. The plan records the revision, and that the occlusion proof (content a client component doesn't place ships once, as a record) has had no demo or end-to-end test since the early HN demo's deep-collapsed replies were dropped. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: notes in React's shape, end-to-end occlusion specs The notes demo moves to the authoring layout and toward the React original. The shell is a client component, as App.js is; only the sidebar list and the note preview are server components. The server shell had existed only to host the search field as a binding slot, and with the shell on the client the field is a plain client component. The editor's data is a plain query (getNoteEdit) instead of a server component used as a data loader. router.tsx holds the routes, the root preload and getNoteList, and server-config.ts passes that Router to the flight collector, as in the fullstack template. The excerpt now mounts only while expanded, as in the demo, so a collapsed excerpt ships once as an sc:region record and expanding it makes no request. The list is newest first and the excerpt is the rendered markdown as plain text, both matching the demo; the excerpt renders on the server, so marked stays in the lazy editor chunk only. The occlusion specs prove the single-copy claim end to end. The server spec checks each excerpt ships once (markup where placed, a record where not) and that late placement is locked to records. The hydration spec adopts the document with the network stubbed to throw, then expands, collapses and re-expands, with each text on screen once. The README, the grid plan and the principles doc are updated: the notes search field is no longer a binding-slot example, and the hackernews occlusion gap is closed. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: todos README names its coordinate, small cleanups The README opens with the example's place on the grid: the client-owned, request/response corner beside hackernews-spa, twin of todos-server, and the baseline for the planned board example. It points at todos.ts as the file to read. The todos.ts header keeps its instruction to read the file for its layering rather than as a list of React-to-Solid renames, but drops the rebuke. The error map moves from module scope into createTodos, so each instance has its own; the unused TodoActions type goes; the row checkbox uses onChange like toggle-all. Vite 7 -> 8, as in the other grid examples. The grid plan marks todos built. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: todos-server as forms with binding slots, router next.34, vite-plugin next.47 todos-server rebuilt around forms: every control is a form that works without JavaScript (`.with()` binds a row's id), and the server answers the page it was posted from in one round trip. Two binding slots, `row` and `list`, add back the optimism a form cannot express (toggle-all, clear-completed, the live count) from one intent store the actions' onSubmit hooks write. Failures are returned `{ error }` values read through useSubmissions; the no-JS path reads the same answers from the router's flash cookie. The README is rewritten around that shape. Dependencies across the examples: - @solidjs/router 2.0.0-next.34 in notes, room, hackernews, hackernews-spa and todos-server (server-rendered `.with()` forms find the registered action; the flash decode runs once per request). - @solidjs/vite-plugin 3.0.0-next.47 in all eleven, so they compile with the workspace compiler and babel plugin; next.47 is also the first to inject the flash-cookie secret. effect, migrating-element, rendering and sierpinski move to vite ^8, which next.47 requires (transformWithOxc). The plan's verification note records V1-V4 holding and the two router fixes they needed. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: router next.35 Actions now settle at the commit of their transition (#649): a form's aria-busy, the onSettled hooks and the submission record release when the result is on screen, not when the action body returns. Busy state is keyed by the form's action URL, so it survives a server-component morph. Also picks up the link-state fixes (aria-current compares the query, base path on a segment boundary, non-ASCII paths). Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: todos-server shows intent through aria-busy, not an optimistic store The list no longer predicts outcomes. While a form's submission is in flight the router marks it aria-busy, and app.css shows the request from that alone: a pressed toggle, a dimmed row, and through :has() every row toggle-all or clear-completed touches. A mark waiting over two seconds pulses. The server's answer replaces the mark; the SPA twin keeps the predicting version. Failures are answers the server words (it knows the todo's title): the actions return { error } with the message, and the route lists them under the list with a retry, cleared when the next attempt at the same thing settles. The fills, the binding-slot bindings and the optimistic store are gone; the list has no client code. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: todos-server dismisses errors a later success answered A failed toggle's error stayed up after mark-all completed the todo, or after the todo was deleted. A settled attempt already replaced earlier answers to the same question within one action; now a successful delete also dismisses that todo's toggle errors, and a successful mark-all dismisses every row's. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: todos-server README names the render-mode condition for no-JS Without JavaScript the page has to arrive whole: streamed content that settles after the first flush needs a script to swap in. The example's reads land before the flush, which is timing, not a guarantee; an app that must work without JavaScript renders in the vite plugin's async mode. Also brings the toggle snippet in line with the markup (aria-pressed). Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: router next.37, server components mount through dynamicComponent Every example moves to @solidjs/router 2.0.0-next.37, and the server component mounts in chat, notes, room and todos-server use dynamicComponent, the documented mount for a server component. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: hackernews routes answer cacheable GETs, no navigation dim The server-components twin's routes are GET reads that answer through respond(View, cacheable): a minute of public HTTP caching, so a link hover's preload is the response the click then reads from the browser's cache. Both twins drop the routing dim: the current page stays up until the next is ready. Depends on respond() being typed as its value and envelopes unwrapping on the direct leg (#3910). Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: router 2.0.0-next.38, vite-plugin 3.0.0-next.48 Link preloading is opt-in in next.38, so each example's router passes intentPreload() and keeps the hover, focus, and touch preload it had. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: vite-plugin 3.0.0-next.49 Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * examples: record the grid handoff The apps that exist are as far as the runtime can take them. The plan names what landed, what stays, and what is handed off, and the chat, room, and migrating-element READMEs say the same. Co-authored-by: Grok via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * test(web): occlusion spec makes the regions tier resident before hydrate The spec predates #3860, which moved `{$frame}` slot regions into the lazily loaded regions tier: a record naming a region waits for the tier, so the slot fills never mounted and expanding item a rendered nothing. Load it before hydrate (as welcome-status-parity does for trace), assert the document announces it, and re-record the artifact, which predated the announcement. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017PDt8Jv6uf5xRDsrux4UwF --------- Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> Co-authored-by: Claude <[email protected]>
1 parent 4101c67 commit bb66b43

92 files changed

Lines changed: 2168 additions & 1928 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎documentation/plans/examples-grid-plan.md‎

Lines changed: 190 additions & 48 deletions
Large diffs are not rendered by default.

‎documentation/server-components/server-components-principles.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3183,7 +3183,7 @@ the text above, the build is right and the text is amended here:
31833183
names percent-encode onto `[A-Za-z0-9_.-]`, the occurrence
31843184
alphabet, so `:`/`=`/`,` split exactly. A zero-arg call is the
31853185
occurrence named by the prop alone (`codeBlock:onCopy`, no `#n`) —
3186-
one data context per prop, the notes search field's shape. The
3186+
one data context per prop, the chat copy button's shape. The
31873187
document face writes the value where the position would have put
31883188
it and the marker after. A class-name or style-property position
31893189
whose names all resolve empty writes no `class=""` — the marker
@@ -4457,7 +4457,13 @@ slots (§9.2.3) with markup slots for the elements that exist only
44574457
because of client state. The ratio is one to ten. Rejections: none
44584458
(behavior only). *Standing: this is what attribute slots are for,
44594459
and the advice writes itself — bind the position, don't lift the
4460-
element.* Examples: `chat`'s `codeBlock`, `notes`' `search` field.
4460+
element.* Examples: `chat`'s `codeBlock`; `notes`' expand toggle,
4461+
the markup-slot half (the excerpt exists only while expanded, so it
4462+
ships once as a record, A1). `notes`' search field was an
4463+
attribute-slot example while its shell was a server component; with
4464+
the shell on the client there is no server markup around it to
4465+
annotate, and it is a client component, as in the React demo. The
4466+
position has to sit in server markup for the slot to be the answer.
44614467

44624468
**Q4 — Widgets.** Small data, this user's alone, changing faster
44634469
than a round trip, with dense interaction on every element:
@@ -4494,7 +4500,7 @@ example quadrant role
44944500
─────── ──────── ────
44954501
hackernews Q1 front door for the core
44964502
hackernews-spa — client control for hackernews
4497-
notes Q1 + Q3 + Q5 list + search slot + single-flight mutations
4503+
notes Q1 + Q3 + Q5 list + expand slot + single-flight mutations
44984504
chat Q2 + Q3 live generation + attribute slot
44994505
room Q2 live transport end to end
45004506
todos Q4 client control for todos-server

‎examples/chat/README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ Where the HackerNews twin ([../hackernews](../hackernews)) shows markup that
1111
changing after it arrives** — one generation streaming through live markup
1212
holes, live slot arguments, and a live store, all crossing the same border.
1313

14+
This stands in the persistent, server-owned corner as the demo the runtime
15+
can show today: one generation, a fake model, no threads. The product —
16+
durable threads, a generation that outlives the tab — is handed off in
17+
[`examples-grid-plan.md`](../../documentation/plans/examples-grid-plan.md).
18+
It is not built here.
19+
1420
```sh
1521
pnpm dev # http://localhost:3009
1622
pnpm build && pnpm start # http://localhost:3009
@@ -87,7 +93,7 @@ bottom.
8793
for each message, `welcome()` for the t=0 face, `<Message>` for the live
8894
hole, and the projection that becomes the client's usage store.
8995
- [src/app.tsx](./src/app.tsx) — the whole client app: transcript state, the
90-
composer, autoscroll, and one `dynamic()` per reply.
96+
composer, autoscroll, and one `dynamicComponent()` per reply.
9197
- [src/components/status.tsx](./src/components/status.tsx) — the client fill
9298
reading all three tiers: expression args, the pending promise read, and the
9399
materialized store.

‎examples/chat/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
"solid-js": "workspace:*"
2020
},
2121
"devDependencies": {
22-
"@solidjs/vite-plugin": "3.0.0-next.35",
22+
"@solidjs/vite-plugin": "3.0.0-next.49",
2323
"vite": "^8.0.0"
2424
}
2525
}

‎examples/chat/src/app.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// answers) are server components; their markup arrives as HTML over frame
55
// streams and never exists here as templates or JSON.
66
import { createSignal, For, Loading, onSettled } from "solid-js";
7-
import { dynamic } from "@solidjs/web";
7+
import { dynamicComponent } from "@solidjs/web";
88
import { reply, welcome } from "~/lib/ai";
99
import Status from "~/components/status";
1010
import "./app.css";
@@ -43,7 +43,7 @@ export default function App() {
4343
// document's own response, and hydration adopts the boundary in place
4444
// (zero network) and picks the generation up mid-sentence. The `reply`
4545
// calls below are the same machinery on the call-driven face.
46-
const Welcome = dynamic(() => welcome());
46+
const Welcome = dynamicComponent(() => welcome());
4747

4848
const send = (e: SubmitEvent) => {
4949
e.preventDefault();
@@ -104,7 +104,7 @@ export default function App() {
104104
// with two live expression args (DR-2): progress updates on every
105105
// yield, stats settles when generation completes. The <Status>
106106
// reading them is client code.
107-
const Reply = dynamic(() => reply(m.prompt));
107+
const Reply = dynamicComponent(() => reply(m.prompt));
108108
return (
109109
<li class="exchange">
110110
<div class="bubble user">{m.prompt}</div>

‎examples/effect/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@
1616
"effect": "^3.22.0"
1717
},
1818
"devDependencies": {
19-
"@solidjs/vite-plugin": "3.0.0-next.35",
19+
"@solidjs/vite-plugin": "3.0.0-next.49",
2020
"@solidjs/web": "workspace:*",
2121
"@types/node": "^25.6.0",
2222
"solid-js": "workspace:*",
2323
"typescript": "^6.0.2",
24-
"vite": "^7.0.0"
24+
"vite": "^8.0.0"
2525
}
2626
}

‎examples/hackernews-spa/README.md‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
A real HackerNews client built the conventional way: server functions return
44
JSON, client components render everything, and the document ships standard
5-
hydration data.
5+
hydration data. It sits in the client-owned, request/response corner of the
6+
examples, beside `todos`.
67

78
It is the comparison twin of [../hackernews](../hackernews) — the *same
89
application*, with the same routes, the same markup, and the same data layer,
@@ -18,29 +19,34 @@ pnpm build && pnpm start # http://localhost:3005
1819

1920
This is a *good* baseline, not a strawman: fine-grained hydration, no requests
2021
at boot (the serialized data resumes the render), one JSON fetch per
21-
navigation, preloading on link hover, and client state that survives
22-
navigation.
22+
navigation, preloading on link hover, and navigations that keep the current
23+
page up until the next is ready.
2324

2425
The difference from the server-components twin is structural rather than one
2526
of quality. View source on a thread and search for any comment's text: it is
2627
there twice — once as the HTML the server painted, and once inside the
2728
hydration data that produced it. That is inherent, not an oversight. The
2829
client renders these templates itself, so it needs the data that drives them,
2930
which also means every content component ships to the browser. The twin
30-
carries content once and ships only the components that own state.
31+
carries content once and ships no content components at all.
3132

3233
## How it's wired
3334

34-
- [src/lib/hn.ts](./src/lib/hn.ts) — the data source, server-only. Live HN API,
35-
except story `30186326` ("Facebook loses users for the first time", 1,406
36-
comments, 14 levels deep), which is served from a capture so the big thread
37-
is deterministic.
38-
- [src/lib/api.ts](./src/lib/api.ts) — `query()` wrappers so the router can
39-
preload on hover and dedupe the call the route then makes.
40-
- [src/components/](./src/components) — the templates: nav, story, comment,
41-
and the collapse toggle. In the twin, only the toggle exists on the client.
42-
- [src/routes/](./src/routes) — one route component per view, each reading its
43-
query.
35+
- [src/routes/](./src/routes) — one file per screen: its server function
36+
inside `query` (so the router can preload on hover and dedupe the call the
37+
route then makes, and the result lands in the hydration data), and the route
38+
component that renders it. Only the default component and `preload` are
39+
exported. The twin's route files hold the same `getStory`, returning markup
40+
instead of data, and none of its routes has a route component, because
41+
there the router makes the call.
42+
- [src/server/hn.ts](./src/server/hn.ts) — the data source, identical to the
43+
twin's. Live HN API, except story `30186326` ("Facebook loses users for the
44+
first time", 1,406 comments, 14 levels deep), which is served from a capture
45+
so the big thread is deterministic. It begins `import "server-only"`, which
46+
fails the build if it is ever imported from client code.
47+
- [src/components/](./src/components) — the templates: nav, story, and
48+
comment, whose collapse is a native `<details>`. The twin has no client
49+
components: its markup is server components.
4450
- [vite.config.ts](./vite.config.ts) — the turnkey `ssr` object generates the
4551
entries and the serving layer, so there is no `entry-server`, `entry-client`,
4652
or dev-server script here. `serverFunctions` serves the `/_server` endpoint.

‎examples/hackernews-spa/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,12 @@
1313
"typecheck": "tsc --noEmit"
1414
},
1515
"dependencies": {
16-
"@solidjs/router": "2.0.0-next.29",
16+
"@solidjs/router": "2.0.0-next.38",
1717
"@solidjs/web": "workspace:*",
1818
"solid-js": "workspace:*"
1919
},
2020
"devDependencies": {
21-
"@solidjs/vite-plugin": "3.0.0-next.35",
21+
"@solidjs/vite-plugin": "3.0.0-next.49",
2222
"vite": "^8.0.0"
2323
}
2424
}

‎examples/hackernews-spa/src/app.css‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ a {
236236
position: relative;
237237
}
238238

239-
.comment .by, .comment .text, .comment .toggle {
239+
.comment .by, .comment .text, .comment .toggle > summary {
240240
font-size: 0.9em;
241241
margin: 1em 0;
242242
}
@@ -262,23 +262,30 @@ a {
262262
white-space: pre-wrap;
263263
}
264264

265-
.comment .toggle {
265+
.comment .toggle > summary {
266266
background-color: #fffbf2;
267267
padding: 0.3em 0.5em;
268268
border-radius: 4px;
269-
}
270-
271-
.comment .toggle a {
272269
color: #626262;
273270
cursor: pointer;
271+
list-style: none;
272+
}
273+
274+
.comment .toggle > summary::-webkit-details-marker {
275+
display: none;
274276
}
275277

276-
.comment .toggle.open {
278+
.comment .toggle[open] > summary {
277279
padding: 0;
278280
background-color: transparent;
279281
margin-bottom: -0.5em;
280282
}
281283

284+
.comment .toggle[open] > summary > .closed-label,
285+
.comment .toggle:not([open]) > summary > .open-label {
286+
display: none;
287+
}
288+
282289
.user-view {
283290
background-color: #fff;
284291
box-sizing: border-box;

‎examples/hackernews-spa/src/app.tsx‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// (../hackernews) renders the same routes with the same markup — only the
55
// static parts come back as server components there, so they arrive as HTML
66
// once and never as data.
7-
import { createRouter, defineRoute } from "@solidjs/router";
7+
import { createRouter, defineRoute, intentPreload } from "@solidjs/router";
88
import { Loading } from "solid-js";
99
import Nav from "~/components/nav";
1010
import Stories, { preload as preloadStories } from "~/routes/stories";
@@ -13,15 +13,19 @@ import User, { preload as preloadUser } from "~/routes/user";
1313
import "./app.css";
1414

1515
// Explicit route tree rather than the file routes a metaframework provides:
16-
// this example is plain Vite. The feed paths are enumerated instead of a
17-
// splat so the typed path proxy stays useful.
16+
// this example is plain Vite. The same table as the server-components twin:
17+
// the feed is an optional param the filter limits to the five feed names.
1818
// `defineRoute` types each route's component and preload from its own `path`,
1919
// so the `:id` routes read `params.id` as `string` rather than
2020
// `string | undefined`.
21+
// `intentPreload` is the hover, focus, and touch preload. Link preloading is
22+
// opt-in as of router 2.0.0-next.38.
2123
const Router = createRouter({
24+
preloadLinks: intentPreload(),
2225
routes: [
2326
defineRoute({
24-
path: ["/", "/top", "/new", "/show", "/ask", "/job"],
27+
path: "/:type?",
28+
matchFilters: { type: ["top", "new", "show", "ask", "job"] },
2529
component: Stories,
2630
preload: preloadStories
2731
}),
@@ -36,7 +40,11 @@ export default function App() {
3640
{props => (
3741
<>
3842
<Nav />
39-
<Loading fallback={<div class="news-list-nav">Loading...</div>}>{props.children}</Loading>
43+
<div class="page">
44+
<Loading fallback={<div class="news-list-nav">Loading...</div>}>
45+
{props.children}
46+
</Loading>
47+
</div>
4048
</>
4149
)}
4250
</Router>

0 commit comments

Comments
 (0)