@solidjs/web 2.0.0-rc.15 → 2.0.0-rc.16
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.
- package/README.md +1 -1
- package/dist/server.dev.js +358 -479
- package/dist/server.js +343 -387
- package/dist/server.observe.js +343 -387
- package/dist/web.dev.js +57 -54
- package/dist/web.js +47 -49
- package/dist/web.observe.js +57 -54
- package/frames/dist/client.dev.js +610 -621
- package/frames/dist/client.js +540 -566
- package/frames/dist/client.observe.js +571 -573
- package/frames/dist/regions.js +43 -2
- package/frames/dist/server.dev.js +514 -423
- package/frames/dist/server.js +514 -370
- package/frames/dist/server.observe.js +514 -370
- package/frames/dist/wire.js +371 -6
- package/package.json +11 -11
- package/serialization/dist/decode.js +9 -7
- package/serialization/dist/serialization.js +9 -7
- package/serialization/types/serializer-decode.d.ts +2 -2
- package/server-functions/dist/client.dev.js +3 -1
- package/server-functions/dist/client.js +1 -1
- package/server-functions/dist/client.observe.js +3 -1
- package/server-functions/dist/rich-args.js +33 -1
- package/server-functions/dist/server.dev.js +127 -18
- package/server-functions/dist/server.js +127 -18
- package/server-functions/dist/server.observe.js +127 -18
- package/skills/server-components/SKILL.md +74 -185
- package/types/client.d.ts +15 -5
- package/types/frames/assets-tier.d.ts +2 -2
- package/types/frames/client.d.ts +8 -3
- package/types/frames/frame-client.d.ts +121 -157
- package/types/frames/frame-morph.d.ts +28 -0
- package/types/frames/frame-sink.d.ts +13 -9
- package/types/frames/frame-transport.d.ts +30 -1
- package/types/frames/regions-tier.d.ts +15 -0
- package/types/frames/serializer-decode.d.ts +2 -2
- package/types/frames/server.d.ts +0 -52
- package/types/frames/wire-tier.d.ts +54 -1
- package/types/index.d.ts +2 -2
- package/types/jsx.d.ts +11 -5
- package/types/observe.d.ts +14 -7
- package/types/render.d.ts +3 -1
- package/types/response.d.ts +5 -4
- package/types/serializer-decode.d.ts +2 -2
- package/types/server-functions/argument-codec.d.ts +21 -0
- package/types/server-functions/client.d.ts +14 -5
- package/types/server-functions/server.d.ts +6 -2
- package/types/server-functions/shared.d.ts +19 -0
- package/types/server-observe.d.ts +3 -2
- package/types/server.d.ts +57 -76
- package/frames/dist/bind.dev.js +0 -326
- package/frames/dist/bind.js +0 -295
- package/types/frames/bind-tier.d.ts +0 -60
|
@@ -56,11 +56,9 @@ function parseTraceparent(value) {
|
|
|
56
56
|
};
|
|
57
57
|
}
|
|
58
58
|
function randomHex(bytes) {
|
|
59
|
-
const buffer = new Uint8Array(bytes);
|
|
60
|
-
crypto.getRandomValues(buffer);
|
|
61
59
|
let out = "";
|
|
62
|
-
for (let i = 0; i <
|
|
63
|
-
return out;
|
|
60
|
+
for (let i = 0; i < bytes; i += 4) out += (Math.random() * 0x100000000 >>> 0).toString(16).padStart(8, "0");
|
|
61
|
+
return out.length === bytes * 2 ? out : out.slice(0, bytes * 2);
|
|
64
62
|
}
|
|
65
63
|
function randomTraceId() {
|
|
66
64
|
let id = randomHex(16);
|
|
@@ -832,6 +830,10 @@ function createEventChunk(data, id) {
|
|
|
832
830
|
return CHUNK_ENCODER.encode(event + "\n");
|
|
833
831
|
}
|
|
834
832
|
const EVENT_STREAM_HEARTBEAT = /* @__PURE__ */new TextEncoder().encode(":\n\n");
|
|
833
|
+
function isEventStream(source) {
|
|
834
|
+
const contentType = source.headers.get("content-type");
|
|
835
|
+
return !!contentType && contentType.startsWith("text/event-stream");
|
|
836
|
+
}
|
|
835
837
|
function positionDigest(value) {
|
|
836
838
|
if (value === undefined || !isJSONSafe(value)) return undefined;
|
|
837
839
|
const text = JSON.stringify(value);
|
|
@@ -894,7 +896,7 @@ async function deserializeStream(source, codecOptions, wire) {
|
|
|
894
896
|
if (!source.body) {
|
|
895
897
|
throw new Error("missing body");
|
|
896
898
|
}
|
|
897
|
-
const reader = new ChunkReader(source.body);
|
|
899
|
+
const reader = wire && isEventStream(source) ? wire.open(source.body) : new ChunkReader(source.body);
|
|
898
900
|
try {
|
|
899
901
|
const result = await reader.next();
|
|
900
902
|
if (!result.done) {
|
|
@@ -913,10 +915,18 @@ async function deserializeStream(source, codecOptions, wire) {
|
|
|
913
915
|
}
|
|
914
916
|
const connection = wire && wire.connection;
|
|
915
917
|
let endConnection;
|
|
916
|
-
if (connection) ;
|
|
918
|
+
if (connection) connection.ended = new Promise(resolve => endConnection = resolve);
|
|
917
919
|
const end = error => {
|
|
918
920
|
const sweep = () => deserializeChunk.abort(error);
|
|
919
|
-
if (connection)
|
|
921
|
+
if (connection) {
|
|
922
|
+
const close = () => deserializeChunk.close();
|
|
923
|
+
endConnection({
|
|
924
|
+
open: deserializeChunk.open(),
|
|
925
|
+
error,
|
|
926
|
+
sweep,
|
|
927
|
+
close
|
|
928
|
+
});
|
|
929
|
+
} else sweep();
|
|
920
930
|
};
|
|
921
931
|
reader.drain(interpretChunk).then(() => end(new Error("Server function stream ended unexpectedly.")), error => end(error));
|
|
922
932
|
return interpretChunk(result.value);
|
|
@@ -926,9 +936,6 @@ async function deserializeStream(source, codecOptions, wire) {
|
|
|
926
936
|
throw error;
|
|
927
937
|
}
|
|
928
938
|
}
|
|
929
|
-
async function deserializeString(text, codecOptions) {
|
|
930
|
-
return await deserializeStream(new Response(text), codecOptions);
|
|
931
|
-
}
|
|
932
939
|
async function decodeResponse(response, codecOptions) {
|
|
933
940
|
if (!response.body) return undefined;
|
|
934
941
|
return await extractBody(response.clone(), codecOptions === undefined ? codecConfig.codec : codecOptions);
|
|
@@ -1238,6 +1245,57 @@ async function decodeFlashCookie(cookieHeader) {
|
|
|
1238
1245
|
}
|
|
1239
1246
|
}
|
|
1240
1247
|
|
|
1248
|
+
const RESPONSE_TAG = "seroval-plugins/web/Response";
|
|
1249
|
+
const REQUEST_TAG = "seroval-plugins/web/Request";
|
|
1250
|
+
const REFUSED_TAGS = [RESPONSE_TAG, REQUEST_TAG];
|
|
1251
|
+
const RESOLVED_PLUGINS = Symbol.for("solid.codec.resolvedPlugins");
|
|
1252
|
+
const REFUSED_ARGUMENT = Symbol("solid.serverFunction.refusedArgument");
|
|
1253
|
+
function refusedArgumentError(name = "Response or Request") {
|
|
1254
|
+
const error = new TypeError(`Server function arguments cannot carry Response or Request values (got a ${name}). ` + "Pass the data it holds — its body, headers or url — instead.");
|
|
1255
|
+
error[REFUSED_ARGUMENT] = true;
|
|
1256
|
+
return error;
|
|
1257
|
+
}
|
|
1258
|
+
function refusedArgument(error) {
|
|
1259
|
+
for (let depth = 0; depth < 4 && error !== null && typeof error === "object"; depth++) {
|
|
1260
|
+
if (error[REFUSED_ARGUMENT] === true) return error;
|
|
1261
|
+
error = error.cause;
|
|
1262
|
+
}
|
|
1263
|
+
}
|
|
1264
|
+
const refused = plugin => REFUSED_TAGS.includes(plugin.tag);
|
|
1265
|
+
const reachesRefused = plugin => refused(plugin) || !!plugin.extends && plugin.extends.some(reachesRefused);
|
|
1266
|
+
function filterPlugins(plugins, out, seen) {
|
|
1267
|
+
for (const plugin of plugins) {
|
|
1268
|
+
if (seen.has(plugin)) continue;
|
|
1269
|
+
seen.add(plugin);
|
|
1270
|
+
if (refused(plugin)) continue;
|
|
1271
|
+
const severs = !!plugin.extends && plugin.extends.some(reachesRefused);
|
|
1272
|
+
out.push(severs ? {
|
|
1273
|
+
...plugin,
|
|
1274
|
+
extends: undefined
|
|
1275
|
+
} : plugin);
|
|
1276
|
+
if (plugin.extends) filterPlugins(plugin.extends, out, seen);
|
|
1277
|
+
}
|
|
1278
|
+
return out;
|
|
1279
|
+
}
|
|
1280
|
+
let defaultArgumentPlugins;
|
|
1281
|
+
const customArgumentPlugins = new WeakMap();
|
|
1282
|
+
function argumentDecodeCodec(codec, defaults) {
|
|
1283
|
+
const custom = codec && codec.plugins;
|
|
1284
|
+
let plugins = custom ? customArgumentPlugins.get(custom) : defaultArgumentPlugins;
|
|
1285
|
+
if (!plugins) {
|
|
1286
|
+
plugins = filterPlugins(custom ? [...custom, ...defaults] : defaults, [], new Set());
|
|
1287
|
+
if (custom) customArgumentPlugins.set(custom, plugins);else defaultArgumentPlugins = plugins;
|
|
1288
|
+
}
|
|
1289
|
+
return {
|
|
1290
|
+
...codec,
|
|
1291
|
+
[RESOLVED_PLUGINS]: plugins
|
|
1292
|
+
};
|
|
1293
|
+
}
|
|
1294
|
+
function namesRefusedType(payload) {
|
|
1295
|
+
for (const tag of REFUSED_TAGS) if (payload.includes(`"c":"${tag}"`)) return true;
|
|
1296
|
+
return false;
|
|
1297
|
+
}
|
|
1298
|
+
|
|
1241
1299
|
const config = {
|
|
1242
1300
|
provideEvent: undefined,
|
|
1243
1301
|
wrapInvocation: undefined,
|
|
@@ -1803,14 +1861,49 @@ function unknownFormatError(tag) {
|
|
|
1803
1861
|
error[FORMAT_SKEW] = true;
|
|
1804
1862
|
return error;
|
|
1805
1863
|
}
|
|
1806
|
-
async function
|
|
1864
|
+
async function decodeArguments(decode, payload) {
|
|
1865
|
+
if (payload === null) return await decode(undefined);
|
|
1866
|
+
const refuseNamed = () => {
|
|
1867
|
+
const text = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
|
|
1868
|
+
if (namesRefusedType(text)) throw refusedArgumentError();
|
|
1869
|
+
};
|
|
1870
|
+
const connection = {};
|
|
1871
|
+
let value;
|
|
1872
|
+
try {
|
|
1873
|
+
value = await decode({
|
|
1874
|
+
connection
|
|
1875
|
+
});
|
|
1876
|
+
} catch (error) {
|
|
1877
|
+
if (connection.ended) connection.ended.then(end => end.sweep());
|
|
1878
|
+
refuseNamed();
|
|
1879
|
+
throw error;
|
|
1880
|
+
}
|
|
1881
|
+
if (connection.ended) {
|
|
1882
|
+
const {
|
|
1883
|
+
open,
|
|
1884
|
+
sweep
|
|
1885
|
+
} = await connection.ended;
|
|
1886
|
+
sweep();
|
|
1887
|
+
if (open) refuseNamed();
|
|
1888
|
+
}
|
|
1889
|
+
return value;
|
|
1890
|
+
}
|
|
1891
|
+
let decodeModule;
|
|
1892
|
+
async function loadArgumentCodec(codec) {
|
|
1893
|
+
decodeModule = await import('@solidjs/web/serialization/decode');
|
|
1894
|
+
return argumentDecodeCodec(codec, decodeModule.DEFAULT_WEB_PLUGINS);
|
|
1895
|
+
}
|
|
1896
|
+
const argumentCodecFor = codec => decodeModule ? argumentDecodeCodec(codec, decodeModule.DEFAULT_WEB_PLUGINS) : loadArgumentCodec(codec);
|
|
1897
|
+
async function parseArguments(request, url, scripted, codec, buffered) {
|
|
1807
1898
|
const parsed = [];
|
|
1808
1899
|
const bodyFormat = request.method === "POST" ? request.headers.get(BODY_FORMAT_HEADER) : null;
|
|
1809
1900
|
const args = url.searchParams.get("args");
|
|
1810
1901
|
if (args && (!scripted || request.method === "GET" || bodyFormat !== BodyFormat.Serialized)) {
|
|
1811
1902
|
let result;
|
|
1812
1903
|
if (args.startsWith(";0x")) {
|
|
1813
|
-
|
|
1904
|
+
let argumentCodec = argumentCodecFor(codec);
|
|
1905
|
+
if (argumentCodec instanceof Promise) argumentCodec = await argumentCodec;
|
|
1906
|
+
result = await decodeArguments(wire => deserializeStream(new Response(args), argumentCodec, wire), args);
|
|
1814
1907
|
} else {
|
|
1815
1908
|
result = JSON.parse(args);
|
|
1816
1909
|
assertDecodeDepth(result);
|
|
@@ -1830,7 +1923,14 @@ async function parseArguments(request, url, scripted, codec) {
|
|
|
1830
1923
|
throw unknownFormatError(bodyFormat);
|
|
1831
1924
|
}
|
|
1832
1925
|
const body = request.clone();
|
|
1833
|
-
|
|
1926
|
+
let decoded;
|
|
1927
|
+
if (bodyFormat === BodyFormat.Serialized) {
|
|
1928
|
+
let argumentCodec = argumentCodecFor(codec);
|
|
1929
|
+
if (argumentCodec instanceof Promise) argumentCodec = await argumentCodec;
|
|
1930
|
+
decoded = await decodeArguments(wire => extractBody(body, argumentCodec, wire), buffered);
|
|
1931
|
+
} else {
|
|
1932
|
+
decoded = await extractBody(body, codec);
|
|
1933
|
+
}
|
|
1834
1934
|
if (bodyFormat === BodyFormat.Serialized || bodyFormat === BodyFormat.Json) {
|
|
1835
1935
|
if (bodyFormat === BodyFormat.Json) assertDecodeDepth(decoded);
|
|
1836
1936
|
if (!Array.isArray(decoded)) {
|
|
@@ -2822,6 +2922,7 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
2822
2922
|
});
|
|
2823
2923
|
return finish(protectsRequest ? withCSRFVary(response) : response);
|
|
2824
2924
|
}
|
|
2925
|
+
let argumentBytes = null;
|
|
2825
2926
|
if (method === "POST" && request.body !== null && bodySizeLimit !== Infinity) {
|
|
2826
2927
|
const raw = request.headers.get("content-length");
|
|
2827
2928
|
const declared = raw !== null && /^\d+$/.test(raw) ? Number(raw) : NaN;
|
|
@@ -2847,6 +2948,7 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
2847
2948
|
return finish(protectsRequest ? withCSRFVary(response) : response);
|
|
2848
2949
|
}
|
|
2849
2950
|
request = withBufferedBody(request, buffered);
|
|
2951
|
+
argumentBytes = buffered;
|
|
2850
2952
|
}
|
|
2851
2953
|
let event;
|
|
2852
2954
|
try {
|
|
@@ -2903,10 +3005,10 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
2903
3005
|
const collectsFlight = flightHooks.length > 0;
|
|
2904
3006
|
let parsed;
|
|
2905
3007
|
try {
|
|
2906
|
-
parsed = await parseArguments(request, url, scripted, codec);
|
|
3008
|
+
parsed = await parseArguments(request, url, scripted, codec, argumentBytes);
|
|
2907
3009
|
} catch (error) {
|
|
2908
|
-
const
|
|
2909
|
-
const response = new Response(DEV ?
|
|
3010
|
+
const named = error !== null && typeof error === "object" && error[FORMAT_SKEW] === true ? error : refusedArgument(error);
|
|
3011
|
+
const response = new Response(DEV ? named ? named.message : "Malformed server function arguments" : null, {
|
|
2910
3012
|
status: 400
|
|
2911
3013
|
});
|
|
2912
3014
|
return refuseCommitted(response);
|
|
@@ -2960,7 +3062,7 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
2960
3062
|
response,
|
|
2961
3063
|
value
|
|
2962
3064
|
} = result;
|
|
2963
|
-
if (!scripted && !handleNoJS && response && response.body) {
|
|
3065
|
+
if (!scripted && !handleNoJS && response && response.body && isJSONSafe(value)) {
|
|
2964
3066
|
return response;
|
|
2965
3067
|
}
|
|
2966
3068
|
if (response && response.headers) {
|
|
@@ -3149,11 +3251,15 @@ function ownResponse(response) {
|
|
|
3149
3251
|
function finalizeTransportResponse(response, method) {
|
|
3150
3252
|
const stripBody = method === "HEAD" && response.body !== null;
|
|
3151
3253
|
const defaultsCache = !response.headers.has("Cache-Control") && response.status !== 304;
|
|
3152
|
-
|
|
3254
|
+
const defaultsSniff = !response.headers.has("X-Content-Type-Options");
|
|
3255
|
+
if (stripBody || defaultsCache || defaultsSniff) {
|
|
3153
3256
|
try {
|
|
3154
3257
|
if (defaultsCache) {
|
|
3155
3258
|
response.headers.set("Cache-Control", "no-store");
|
|
3156
3259
|
}
|
|
3260
|
+
if (defaultsSniff) {
|
|
3261
|
+
response.headers.set("X-Content-Type-Options", "nosniff");
|
|
3262
|
+
}
|
|
3157
3263
|
if (!stripBody) return response;
|
|
3158
3264
|
response.body.cancel().catch(() => {});
|
|
3159
3265
|
return new Response(null, {
|
|
@@ -3164,6 +3270,9 @@ function finalizeTransportResponse(response, method) {
|
|
|
3164
3270
|
} catch {
|
|
3165
3271
|
const headers = new Headers(response.headers);
|
|
3166
3272
|
if (defaultsCache && !headers.has("Cache-Control")) headers.set("Cache-Control", "no-store");
|
|
3273
|
+
if (defaultsSniff && !headers.has("X-Content-Type-Options")) {
|
|
3274
|
+
headers.set("X-Content-Type-Options", "nosniff");
|
|
3275
|
+
}
|
|
3167
3276
|
if (stripBody) response.body.cancel().catch(() => {});
|
|
3168
3277
|
return new Response(stripBody ? null : response.body, {
|
|
3169
3278
|
status: response.status,
|
|
@@ -1,228 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: server-components
|
|
3
|
+
description: Rules for writing Solid 2.0 server components ("use server" functions that return a template) and their slots with @solidjs/web. Use when writing or reviewing a server component, deciding what lives on the server versus the client, or wiring a slot.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Writing Solid server components with slots
|
|
2
7
|
|
|
3
8
|
A Solid server component is a `"use server"` function that returns a
|
|
4
9
|
template; the browser receives its markup and never its code. Anything the
|
|
5
|
-
client contributes goes through a **slot** on the component's props
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
this
|
|
10
|
+
client contributes goes through a **slot** on the component's props: a
|
|
11
|
+
client component the client places at a position in the server's markup.
|
|
12
|
+
This guide is the set of rules an author — a person or an agent — needs to
|
|
13
|
+
write one correctly the first time. The design record is
|
|
14
|
+
`documentation/server-components/server-components-principles.md`; this
|
|
15
|
+
file is the operative subset.
|
|
10
16
|
|
|
11
17
|
## Where things go
|
|
12
18
|
|
|
13
19
|
> **An element lives where the data that creates it lives.**
|
|
14
20
|
|
|
15
21
|
- Exists because of **server data** (a todo row, a nav link, a search
|
|
16
|
-
form the server renders)? It is **server markup**.
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
placed through a **template slot**.
|
|
22
|
+
form the server renders)? It is **server markup**. A mutation on it is a
|
|
23
|
+
form `action` — it works without JavaScript, and the router marks a
|
|
24
|
+
submission in flight (`aria-busy`) so CSS can show the intent.
|
|
25
|
+
- Needs **client behavior or client state** (a handler, an optimistic add,
|
|
26
|
+
a modal, a drag ghost, an editor open over a field)? It is a **client
|
|
27
|
+
component** placed through a **slot**.
|
|
23
28
|
|
|
24
29
|
When the client confirms an optimistic entity and the server renders it, the
|
|
25
30
|
row _becomes_ server markup; `$key` on the element reconciles the two.
|
|
26
31
|
|
|
27
|
-
##
|
|
32
|
+
## Slots
|
|
28
33
|
|
|
29
34
|
```tsx
|
|
30
|
-
import type {
|
|
35
|
+
import type { Slot } from "@solidjs/web/frames";
|
|
31
36
|
|
|
32
37
|
interface TodosProps {
|
|
33
|
-
pending: Slot; //
|
|
34
|
-
|
|
35
|
-
filters: BindingSlot<{}, FilterBehavior>; // no args: called bare
|
|
38
|
+
pending: Slot; // no props
|
|
39
|
+
editor: Slot<{ id: string; title: string }>; // props from the server
|
|
36
40
|
}
|
|
37
41
|
```
|
|
38
42
|
|
|
39
|
-
A
|
|
40
|
-
owns
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
are _bound_ at positions of the server's own template:
|
|
43
|
+
A slot is placed as an element: `<props.pending />`,
|
|
44
|
+
`<props.editor id={t.id} title={t.title} />`. The client owns the nodes
|
|
45
|
+
between the slot's markers; the server's markup around them stays the
|
|
46
|
+
server's.
|
|
44
47
|
|
|
45
48
|
```tsx
|
|
46
49
|
export async function todoList() {
|
|
47
50
|
"use server";
|
|
48
51
|
const todos = await db.list();
|
|
49
|
-
return (props: TodosProps) =>
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
{
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
))}
|
|
61
|
-
<props.pending />
|
|
62
|
-
</ul>
|
|
63
|
-
<a href="#/" class={{ selected: filters.all }}>
|
|
64
|
-
All
|
|
65
|
-
</a>
|
|
66
|
-
</>
|
|
67
|
-
);
|
|
68
|
-
};
|
|
52
|
+
return (props: TodosProps) => (
|
|
53
|
+
<ul>
|
|
54
|
+
{todos.map(t => (
|
|
55
|
+
<li $key={t.id}>
|
|
56
|
+
{t.title}
|
|
57
|
+
<props.editor $key={t.id} id={t.id} title={t.title} />
|
|
58
|
+
</li>
|
|
59
|
+
))}
|
|
60
|
+
<props.pending />
|
|
61
|
+
</ul>
|
|
62
|
+
);
|
|
69
63
|
}
|
|
70
64
|
```
|
|
71
65
|
|
|
72
|
-
The client passes the fill — a
|
|
66
|
+
The client passes the fill — a component of the slot's props:
|
|
73
67
|
|
|
74
68
|
```tsx
|
|
75
|
-
<Todos
|
|
69
|
+
<Todos editor={p => <Editor id={p.id} title={p.title} />} pending={() => <For each={adds}>{…}</For>} />
|
|
76
70
|
```
|
|
77
71
|
|
|
78
|
-
The fill must return a plain object. An array, a DOM node, a function or
|
|
79
|
-
an async value is a type error on both sides (`BindingSlot`'s return is
|
|
80
|
-
`SlotOutput<J>`, a branded `SlotError` naming the reason) and a
|
|
81
|
-
`fill-shape` finding at runtime.
|
|
82
|
-
|
|
83
|
-
## The one rule for binding slots
|
|
84
|
-
|
|
85
|
-
> **A slot property is a JSX attribute value or a text child, whole, and nothing else.**
|
|
86
|
-
|
|
87
|
-
Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
|
|
88
|
-
`title={row.error}`), a class name inside object form
|
|
89
|
-
(`class={{ completed: row.done }}`), the whole `class`/`style`
|
|
90
|
-
(`class={row.rowClass}`), a style property (`style={{ opacity: row.fade }}`),
|
|
91
|
-
an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element
|
|
92
|
-
with a spread too (`<button {...rest} onClick={row.go} />` — the last
|
|
93
|
-
source that has the key wins, `undefined` included, as the client's
|
|
94
|
-
spread reads it) — and a text child (`<strong>{list.remaining}</strong> items
|
|
95
|
-
left`): a string or number renders, nullish and booleans render empty, and
|
|
96
|
-
the client owns the text between a `<!--_s:t=…-->` marker pair. Never the
|
|
97
|
-
content of `<textarea>`, `<title>`, `<style>` or `<script>`, where the
|
|
98
|
-
markers would be literal text — bind `value=` or a style property there.
|
|
99
|
-
Not a `prop:*` property, not inside another slot call's args (nested in
|
|
100
|
-
plain objects and arrays included). Reserved keys the fill must not use:
|
|
101
|
-
keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`,
|
|
102
|
-
`constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map`
|
|
103
|
-
included) is a plain property.
|
|
104
|
-
|
|
105
|
-
The server **does not have the value** — on the stream face a property read
|
|
106
|
-
is a stand-in with no value, on the document face only the initial one — so
|
|
107
|
-
nothing can be computed from it on the server. Every one of these is wrong:
|
|
108
|
-
|
|
109
|
-
| Wrong | Why | Write instead |
|
|
110
|
-
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
111
|
-
| ``class={`todo ${row.done}`}`` | stringified: not the whole value | `class={{ todo: true, completed: row.done }}` or return `rowClass` from the fill |
|
|
112
|
-
| `row.count > 3 ? "a" : "b"` | comparison on a stand-in | decide in the fill; return the decided value |
|
|
113
|
-
| `if (row.error) …`, `row.error && <button/>`, `<Show when={row.done}>` | truthiness: a stand-in is an object and **always truthy** — the branch always renders | presence → `hidden={…}` or a class; a node that exists because of client state → a template slot |
|
|
114
|
-
| `<strong>{row.label}</strong>` where the fill returns JSX for `label` | a text position renders a string or number | a template slot for markup |
|
|
115
|
-
| `<textarea>{row.draft}</textarea>` | raw-text content: the markers land in the text | `value={row.draft}` |
|
|
116
|
-
| `format(row.title)` (a server helper) | the helper receives a stand-in | do the formatting in the fill |
|
|
117
|
-
| `<li {...row}>` | spread: the template must show what the client owns | name each position |
|
|
118
|
-
| `onClick={() => …}` on a server element | a server function can never run in the browser | bind a slot property or a form `action` |
|
|
119
|
-
| `onKeyDown={[row.key, 1]}` | a tuple: a marker names keys, never data | return `onKeyDown: [handler, data]` from the fill; bind `onKeyDown={row.onKeyDown}` |
|
|
120
|
-
|
|
121
|
-
Every case except truthiness and raw-text content is a dev finding
|
|
122
|
-
(`BINDING_SLOT_POSITION`) and renders **nothing on either face**, so it
|
|
123
|
-
shows on the first render. Truthiness has no runtime hook: if a retry button
|
|
124
|
-
appears on every row, this is why. Raw-text content has none either; in
|
|
125
|
-
`<textarea>` and `<title>` the markers show as text.
|
|
126
|
-
|
|
127
|
-
## Writing the fill
|
|
128
|
-
|
|
129
72
|
- **The fill runs once per occurrence, as a component body does.** It runs
|
|
130
|
-
untracked, under the occurrence's owner, with live
|
|
73
|
+
untracked, under the occurrence's owner, with live props. State it
|
|
131
74
|
creates (a signal, a memo, an `onCleanup`) lives as long as the
|
|
132
75
|
occurrence. A top-level read is read once, and `STRICT_READ_UNTRACKED`
|
|
133
|
-
names it.
|
|
134
|
-
- **
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
`onCopy`, `onClearCompleted`; the position names the DOM event, the key
|
|
163
|
-
names the meaning, as a component's `onSelect` does. Values are nouns or
|
|
164
|
-
adjectives (`done`, `rowClass`, `error`, `busy`); a ref is `ref`. The
|
|
165
|
-
runtime reads nothing into the prefix — the position decides what a
|
|
166
|
-
property is — but a reader can tell a handler from a value without
|
|
167
|
-
opening the type.
|
|
168
|
-
- Handlers and refs are read once, when an element binds, and bind as in
|
|
169
|
-
client JSX: delegated events delegate, a `[handler, data]` tuple returned
|
|
170
|
-
from the fill binds as a tuple, a ref fires once per element. A handler
|
|
171
|
-
behind a getter is read once, as `onClick={cond() ? a : b}` is.
|
|
172
|
-
- **`$key` is optional.** A call repeated within a render (a component
|
|
173
|
-
prop re-evaluates it per position) is one occurrence either way. Add
|
|
174
|
-
`$key: t.id` when the fill holds its own state (an edit draft, a signal
|
|
175
|
-
created inside) that must follow the entity across refetches and
|
|
176
|
-
reorders. Values never depend on it.
|
|
177
|
-
- Reserved keys in the returned object: anything beginning with `$`, the
|
|
178
|
-
node keys `t` `h` `p` `then`, and `Object`/`Array` prototype member names
|
|
179
|
-
(`length`, `map`, …).
|
|
76
|
+
names it ("the \`editor\` template-slot fill").
|
|
77
|
+
- **Place slots as JSX, not calls.** The compiler wraps each prop in a
|
|
78
|
+
getter so the read defers to the slot border; a call form
|
|
79
|
+
(`props.status({ … })`) evaluates its args eagerly in the server
|
|
80
|
+
component's body.
|
|
81
|
+
- **`$key` is optional.** Add it when the fill holds its own state (an edit
|
|
82
|
+
draft, a signal created inside) that must follow the entity across
|
|
83
|
+
refetches and reorders.
|
|
84
|
+
- **An async value crosses with `asyncArg`.**
|
|
85
|
+
`<props.status progress={asyncArg(gen.progress)} />` ships the promise or
|
|
86
|
+
async iterable; the fill's read settles (suspends until the first value).
|
|
87
|
+
|
|
88
|
+
## Behavior on server markup
|
|
89
|
+
|
|
90
|
+
A handler on a server-rendered element cannot come from the server: a
|
|
91
|
+
server function never runs in the browser. Pick one:
|
|
92
|
+
|
|
93
|
+
- **A form.** A mutation is `<form action={…}>`; it works before
|
|
94
|
+
JavaScript and needs no client code.
|
|
95
|
+
- **A client component that owns the element.** Move the control into a
|
|
96
|
+
slot's fill (`<props.toggle id={t.id} done={t.completed} />`, rendering
|
|
97
|
+
the checkbox on the client).
|
|
98
|
+
- **One delegated listener.** For many identical controls inside server
|
|
99
|
+
markup (a copy button on every code block), place one slot occurrence
|
|
100
|
+
whose component registers a single document listener in `onSettled` and
|
|
101
|
+
finds its target from the event (`closest("button.copy-code")`). Inside a
|
|
102
|
+
live hole this is the shape that keeps the hole streaming: a slot placed
|
|
103
|
+
inside a live hole latches it (`SSR_LIVE_HOLE_LATCHED`, `data.cause`
|
|
104
|
+
`"records"`). `examples/chat`'s Copy button is this shape.
|
|
180
105
|
|
|
181
106
|
## Shared components
|
|
182
107
|
|
|
183
|
-
One component can render on both sides
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
different job. Do not read `document`/`window` during render; that is the
|
|
188
|
-
ordinary isomorphic rule.
|
|
108
|
+
One component can render on both sides. Put `$key={props.id}` on the
|
|
109
|
+
element it renders (morph identity) — the slot's own `$key` is a different
|
|
110
|
+
key for a different job. Do not read `document`/`window` during render;
|
|
111
|
+
that is the ordinary isomorphic rule.
|
|
189
112
|
|
|
190
113
|
## Compiling
|
|
191
114
|
|
|
192
|
-
|
|
193
|
-
option. With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
|
|
115
|
+
With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
|
|
194
116
|
{ components: true } })` is the turnkey setup (the examples under
|
|
195
|
-
`examples/todos-server`, `examples/notes`, `examples/chat`)
|
|
196
|
-
build passes `serverComponents: true` to `@solidjs/compiler` or
|
|
197
|
-
`@solidjs/babel-plugin` for the SSR side. Without it a dynamic
|
|
198
|
-
`class`/`style` compiles inside the template's quotes, where a slot value
|
|
199
|
-
cannot be marked — the `inline` finding below.
|
|
200
|
-
|
|
201
|
-
## Diagnostics
|
|
202
|
-
|
|
203
|
-
`BINDING_SLOT_POSITION` (`data.reason`):
|
|
204
|
-
|
|
205
|
-
| reason | severity | what happened | fix |
|
|
206
|
-
| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
207
|
-
| `spread` | error (throws) | a slot's return was spread onto an element | name each position |
|
|
208
|
-
| `stringified` | warn | template literal / concatenation | whole value at one position |
|
|
209
|
-
| `coerced` | warn | comparison, arithmetic, `==` | decide in the fill |
|
|
210
|
-
| `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` |
|
|
211
|
-
| `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot |
|
|
212
|
-
| `server-local` | warn | a server function at `on*`/`ref` | bind a slot property |
|
|
213
|
-
| `tuple` | warn | an array at an `on*` position | return the tuple from the fill |
|
|
214
|
-
| `reserved-key` | warn | the fill used a reserved key | rename it |
|
|
215
|
-
| `arg` | warn | a slot property passed in another slot call's argument (nested in plain objects/arrays; `data.path`) | pass the server's own value, or read it in the fill from client state |
|
|
216
|
-
| `prop` | warn | a slot property at a `prop:*` key of a spread | bind the attribute form, or set the property in the fill's ref |
|
|
217
|
-
| `fill-shape` | warn (client) | the fill returned a non-object (`null`, array, DOM node, async value, primitive), or the prop read as data is not a function | return a plain object from a function prop |
|
|
218
|
-
| `text-shape` | warn (client) | a text position received a non-primitive (object, array, DOM node, function, async value — `data.key`, `data.shape`) | return a string or number; markup goes in a template slot |
|
|
219
|
-
| `orphan` | warn (client) | markers for an occurrence that can never bind: `data.why` `"fill"` — no fill for the prop; `"record"` — a called occurrence with no args record | `fill`: pass the prop / match the name on both sides. `record`: not the fill — rebuild client and server together (stale prebundle, cached asset), else report it |
|
|
220
|
-
|
|
221
|
-
Every reason but `fill-shape`, `text-shape` and `orphan` comes from the server render.
|
|
222
|
-
`orphan` is the one failure this model cannot otherwise show you: the
|
|
223
|
-
element is inert — a handler that never fires, a class that never updates —
|
|
224
|
-
with no error.
|
|
225
|
-
|
|
226
|
-
`STRICT_READ_UNTRACKED` naming a fill ("the \`row\` binding-slot fill",
|
|
227
|
-
"the \`comment\` template-slot fill"): a top-level read in its body; use
|
|
228
|
-
getters (above).
|
|
117
|
+
`examples/todos-server`, `examples/notes`, `examples/chat`).
|
package/types/client.d.ts
CHANGED
|
@@ -126,7 +126,7 @@ export declare function takeHydrationValue<T = unknown>(key: string): HydrationV
|
|
|
126
126
|
* Client stub — a render's link handler is set during server rendering
|
|
127
127
|
* (see the server entry's `setLinkClaim`). Always `false` here, so a router
|
|
128
128
|
* can call it unguarded from isomorphic setup code.
|
|
129
|
-
* @
|
|
129
|
+
* @internal
|
|
130
130
|
*/
|
|
131
131
|
export declare function setLinkClaim(_handler: LinkClaimHandler | undefined): boolean;
|
|
132
132
|
/**
|
|
@@ -137,7 +137,7 @@ export declare function setLinkClaim(_handler: LinkClaimHandler | undefined): bo
|
|
|
137
137
|
* and after hydration. `false` on a page rendered without the router — the
|
|
138
138
|
* absence of link state on an anchor then means nothing, and a link
|
|
139
139
|
* consumer must resolve it itself. Server: `false`.
|
|
140
|
-
* @
|
|
140
|
+
* @internal
|
|
141
141
|
*/
|
|
142
142
|
export declare function hasServerLinkState(): boolean;
|
|
143
143
|
/**
|
|
@@ -203,7 +203,10 @@ export declare function unregisterDelegatedContainer(container: MountableElement
|
|
|
203
203
|
export declare function dispatchAsInteraction<T>(e: Event, fn: () => T): T;
|
|
204
204
|
export declare function getDelegatedRoot(node: MountableElement): MountableElement | undefined;
|
|
205
205
|
export declare function setProperty(node: Element, name: string, value: any): void;
|
|
206
|
-
/**
|
|
206
|
+
/**
|
|
207
|
+
* Options for `registerElementClaim`.
|
|
208
|
+
* @internal
|
|
209
|
+
*/
|
|
207
210
|
export type ElementClaimOptions = {
|
|
208
211
|
/**
|
|
209
212
|
* Attribute names whose compiler-owned writes re-claim an already claimed
|
|
@@ -272,8 +275,8 @@ export declare function style(node: Element, value: {
|
|
|
272
275
|
export declare function readShallow(value: unknown): unknown;
|
|
273
276
|
/** Compiler-emitted primitive; not for hand-written code. @internal */
|
|
274
277
|
export declare function setStyleProperty(node: Element, name: string, value: any): void;
|
|
275
|
-
export declare function spread(node: Element, sources: unknown[], skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string): void;
|
|
276
|
-
export declare function spread<T>(node: Element, accessor: T, skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string): void;
|
|
278
|
+
export declare function spread(node: Element, sources: unknown[], skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string, loc?: string): void;
|
|
279
|
+
export declare function spread<T>(node: Element, accessor: T, skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string, loc?: string): void;
|
|
277
280
|
export declare function dynamicProperty(props: unknown, key: string): unknown;
|
|
278
281
|
export declare function applyRef<T extends Element = Element>(r: ((element: NoInfer<T>) => void) | ((element: NoInfer<T>) => void)[], element: T): void;
|
|
279
282
|
export declare function ref(fn: () => ((element: Element) => void) | ((element: Element) => void)[], element: Element): void;
|
|
@@ -300,6 +303,13 @@ export declare function insert<T>(parent: MountableElement, accessor: (() => T)
|
|
|
300
303
|
* observe runtimes carry it on the node; production ignores it.
|
|
301
304
|
*/
|
|
302
305
|
name?: string;
|
|
306
|
+
/**
|
|
307
|
+
* Source location of the hole (`src/App.tsx:14:7`, root-relative
|
|
308
|
+
* `file:line:col`) — the compiler's `sourceNames` `locations` kind. Dev
|
|
309
|
+
* and observe runtimes carry it on the node for console reports and
|
|
310
|
+
* diagnostic events; production ignores it.
|
|
311
|
+
*/
|
|
312
|
+
loc?: string;
|
|
303
313
|
}): JSX.Element;
|
|
304
314
|
export declare function assign(node: Element, props: any, skipChildren?: Boolean, prevProps?: any, skipRef?: Boolean): void;
|
|
305
315
|
export declare function warmAsset(descriptor: AssetDescriptor): AssetEntry | undefined;
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
* `applyInlineStyles`, `findHeadElement`'s attribute-compared lookup and
|
|
11
11
|
* head.ts's `qualifierValue`), the per-frame flush a pending stylesheet
|
|
12
12
|
* wakes, and the assets pass over a record (modules, typed preloads, inline
|
|
13
|
-
* styles). The eager client keeps the record itself (
|
|
14
|
-
* `assets`
|
|
13
|
+
* styles). The eager client keeps the record itself (the wire's
|
|
14
|
+
* `seg:<k>:assets` record, the host's `seg::assets` accumulate), the pass's walk over
|
|
15
15
|
* the store, and the reveal's READINESS TERM: a segment whose assets record
|
|
16
16
|
* carries stylesheets or inline styles while this tier is not resident is
|
|
17
17
|
* not ready — the server's `<Loading>` fallback stays on screen; the reveal
|