@solidjs/web 2.0.0-rc.13 → 2.0.0-rc.15
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/dist/server.dev.js +317 -185
- package/dist/server.js +298 -161
- package/dist/server.observe.js +299 -171
- package/dist/web.dev.js +207 -189
- package/dist/web.js +180 -178
- package/dist/web.observe.js +180 -180
- package/frames/dist/assets.js +92 -0
- package/frames/dist/bind.dev.js +326 -0
- package/frames/dist/bind.js +295 -0
- package/frames/dist/client.dev.js +665 -1114
- package/frames/dist/client.js +630 -1087
- package/frames/dist/client.observe.js +629 -1087
- package/frames/dist/regions.js +130 -0
- package/frames/dist/server.dev.js +400 -201
- package/frames/dist/server.js +397 -198
- package/frames/dist/server.observe.js +397 -198
- package/frames/dist/trace.js +45 -0
- package/frames/dist/wire.js +133 -0
- package/package.json +30 -4
- package/performance-tracks/dist/performance-tracks.dev.js +2 -1
- package/performance-tracks/dist/performance-tracks.observe.js +2 -1
- package/performance-tracks/types/index.d.ts +8 -6
- package/serialization/dist/decode.js +38 -9
- package/serialization/dist/serialization.js +40 -11
- package/serialization/types/serializer-decode.d.ts +24 -2
- package/server-functions/dist/client.dev.js +101 -62
- package/server-functions/dist/client.js +101 -62
- package/server-functions/dist/client.observe.js +101 -62
- package/server-functions/dist/server.dev.js +178 -67
- package/server-functions/dist/server.js +178 -67
- package/server-functions/dist/server.observe.js +178 -67
- package/skills/server-components/SKILL.md +65 -43
- package/types/client.d.ts +120 -8
- package/types/constants.d.ts +3 -1
- package/types/diagnostics.d.ts +8 -0
- package/types/frames/assets-tier.d.ts +78 -0
- package/types/frames/bind-tier.d.ts +60 -0
- package/types/frames/client.d.ts +37 -3
- package/types/frames/frame-client.d.ts +249 -78
- package/types/frames/frame-container-plugin.d.ts +2 -2
- package/types/frames/frame-sink.d.ts +33 -0
- package/types/frames/frame-transport.d.ts +66 -18
- package/types/frames/regions-tier.d.ts +45 -0
- package/types/frames/serializer-decode.d.ts +24 -2
- package/types/frames/server.d.ts +33 -9
- package/types/frames/trace-tier.d.ts +2 -0
- package/types/frames/wire-tier.d.ts +116 -0
- package/types/head.d.ts +1 -0
- package/types/index.d.ts +61 -16
- package/types/index.server.d.ts +3 -18
- package/types/jsx.d.ts +4 -13
- package/types/observe.d.ts +4 -2
- package/types/response.d.ts +26 -4
- package/types/serializer-decode.d.ts +24 -2
- package/types/server-functions/client.d.ts +30 -0
- package/types/server-functions/registry.d.ts +4 -1
- package/types/server-functions/shared.d.ts +12 -8
- package/types/server-mock.d.ts +22 -3
- package/types/server.d.ts +119 -17
|
@@ -372,7 +372,7 @@ function serializeCookie(name, value, options = {}) {
|
|
|
372
372
|
return cookie;
|
|
373
373
|
}
|
|
374
374
|
const FLASH_COOKIE = "flash";
|
|
375
|
-
const FLASH_MATCHER =
|
|
375
|
+
const FLASH_MATCHER = /(?:^|;\s*)flash=([^;]+)/;
|
|
376
376
|
function hasFlashCookie(cookieHeader) {
|
|
377
377
|
return !!cookieHeader && FLASH_MATCHER.test(cookieHeader);
|
|
378
378
|
}
|
|
@@ -690,7 +690,7 @@ async function extractBody(source, codecOptions, wire) {
|
|
|
690
690
|
const format = source.headers.get(BODY_FORMAT_HEADER);
|
|
691
691
|
switch (true) {
|
|
692
692
|
case format === BodyFormat.Serialized:
|
|
693
|
-
return await deserializeStream(source, codecOptions);
|
|
693
|
+
return await deserializeStream(source, codecOptions, wire);
|
|
694
694
|
case format === BodyFormat.Json:
|
|
695
695
|
return JSON.parse(await source.text());
|
|
696
696
|
case format === BodyFormat.String:
|
|
@@ -716,26 +716,42 @@ async function extractBody(source, codecOptions, wire) {
|
|
|
716
716
|
return undefined;
|
|
717
717
|
}
|
|
718
718
|
function createChunk(data) {
|
|
719
|
-
const
|
|
720
|
-
const encodeData = encoder.encode(data);
|
|
719
|
+
const encodeData = CHUNK_ENCODER.encode(data);
|
|
721
720
|
const bytes = encodeData.length;
|
|
721
|
+
if (bytes > MAX_CHUNK_BYTES) {
|
|
722
|
+
throw new RangeError("Server function chunk is too large to frame.");
|
|
723
|
+
}
|
|
722
724
|
const chunk = new Uint8Array(12 + bytes);
|
|
723
|
-
chunk.set(
|
|
725
|
+
chunk.set(CHUNK_ENCODER.encode(`;0x${bytes.toString(16).padStart(8, "0")};`));
|
|
724
726
|
chunk.set(encodeData, 12);
|
|
725
727
|
return chunk;
|
|
726
728
|
}
|
|
729
|
+
const CHUNK_ENCODER = /* @__PURE__ */new TextEncoder();
|
|
730
|
+
const CHUNK_DECODER = /* @__PURE__ */new TextDecoder("utf-8", {
|
|
731
|
+
fatal: true
|
|
732
|
+
});
|
|
733
|
+
const MAX_CHUNK_BYTES = 0xffffffff;
|
|
734
|
+
const RETAINED_STORE_BYTES = 64 * 1024;
|
|
735
|
+
const DONE = {
|
|
736
|
+
done: true,
|
|
737
|
+
value: undefined
|
|
738
|
+
};
|
|
739
|
+
function malformedStream() {
|
|
740
|
+
return new Error("Malformed server function stream.");
|
|
741
|
+
}
|
|
727
742
|
class ChunkReader {
|
|
728
743
|
constructor(stream) {
|
|
729
744
|
this.reader = stream.getReader();
|
|
730
745
|
this.store = new Uint8Array(0);
|
|
731
746
|
this.buffer = this.store;
|
|
732
747
|
this.done = false;
|
|
748
|
+
this.cancelled = false;
|
|
733
749
|
}
|
|
734
750
|
async readChunk() {
|
|
735
751
|
const chunk = await this.reader.read();
|
|
736
752
|
if (chunk.done) {
|
|
737
753
|
this.done = true;
|
|
738
|
-
return;
|
|
754
|
+
return this.cancelled;
|
|
739
755
|
}
|
|
740
756
|
const incoming = chunk.value;
|
|
741
757
|
const store = this.store;
|
|
@@ -756,55 +772,66 @@ class ChunkReader {
|
|
|
756
772
|
this.store = grown;
|
|
757
773
|
this.buffer = grown.subarray(0, needed);
|
|
758
774
|
}
|
|
775
|
+
return this.cancelled;
|
|
759
776
|
}
|
|
760
777
|
async next() {
|
|
778
|
+
if (this.cancelled) return DONE;
|
|
761
779
|
while (this.buffer.length < 12) {
|
|
762
780
|
if (this.done) {
|
|
763
|
-
if (this.buffer.length === 0) return
|
|
764
|
-
|
|
765
|
-
value: undefined
|
|
766
|
-
};
|
|
767
|
-
throw new Error("Malformed server function stream.");
|
|
781
|
+
if (this.buffer.length === 0) return DONE;
|
|
782
|
+
throw malformedStream();
|
|
768
783
|
}
|
|
769
|
-
await this.readChunk();
|
|
770
|
-
}
|
|
771
|
-
const decoder = new TextDecoder();
|
|
772
|
-
const bytes = Number.parseInt(decoder.decode(this.buffer.subarray(1, 11)), 16);
|
|
773
|
-
if (Number.isNaN(bytes)) {
|
|
774
|
-
throw new Error("Malformed server function stream.");
|
|
784
|
+
if (await this.readChunk()) return DONE;
|
|
775
785
|
}
|
|
786
|
+
const header = String.fromCharCode(...this.buffer.subarray(0, 12));
|
|
787
|
+
if (!/^;0x[\dA-Fa-f]{8};$/.test(header)) throw malformedStream();
|
|
788
|
+
const bytes = parseInt(header.slice(3, 11), 16);
|
|
776
789
|
while (bytes > this.buffer.length - 12) {
|
|
777
790
|
if (this.done) {
|
|
778
|
-
throw
|
|
791
|
+
throw malformedStream();
|
|
779
792
|
}
|
|
780
|
-
await this.readChunk();
|
|
793
|
+
if (await this.readChunk()) return DONE;
|
|
794
|
+
}
|
|
795
|
+
let partial;
|
|
796
|
+
try {
|
|
797
|
+
partial = CHUNK_DECODER.decode(this.buffer.subarray(12, 12 + bytes));
|
|
798
|
+
} catch {
|
|
799
|
+
throw malformedStream();
|
|
781
800
|
}
|
|
782
|
-
const partial = decoder.decode(this.buffer.subarray(12, 12 + bytes));
|
|
783
801
|
this.buffer = this.buffer.subarray(12 + bytes);
|
|
802
|
+
if (this.store.length > RETAINED_STORE_BYTES && this.buffer.length <= RETAINED_STORE_BYTES) {
|
|
803
|
+
this.store = this.buffer = this.buffer.slice();
|
|
804
|
+
}
|
|
784
805
|
return {
|
|
785
806
|
done: false,
|
|
786
807
|
value: partial
|
|
787
808
|
};
|
|
788
809
|
}
|
|
789
810
|
async drain(interpret) {
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
811
|
+
try {
|
|
812
|
+
while (true) {
|
|
813
|
+
const result = await this.next();
|
|
814
|
+
if (result.done) {
|
|
815
|
+
break;
|
|
816
|
+
}
|
|
817
|
+
interpret(result.value);
|
|
794
818
|
}
|
|
795
|
-
|
|
819
|
+
} catch (error) {
|
|
820
|
+
this.cancel(error).catch(() => {});
|
|
821
|
+
throw error;
|
|
796
822
|
}
|
|
797
823
|
}
|
|
798
824
|
cancel(reason) {
|
|
825
|
+
this.cancelled = true;
|
|
799
826
|
return this.reader.cancel(reason);
|
|
800
827
|
}
|
|
801
828
|
}
|
|
802
829
|
function createEventChunk(data, id) {
|
|
803
830
|
let event = id !== undefined && !id.includes("\0") ? `id: ${id}\n` : "";
|
|
804
831
|
for (const line of data.split(/\r\n|\r|\n/)) event += `data: ${line}\n`;
|
|
805
|
-
return
|
|
832
|
+
return CHUNK_ENCODER.encode(event + "\n");
|
|
806
833
|
}
|
|
807
|
-
const EVENT_STREAM_HEARTBEAT = new TextEncoder().encode(":\n\n");
|
|
834
|
+
const EVENT_STREAM_HEARTBEAT = /* @__PURE__ */new TextEncoder().encode(":\n\n");
|
|
808
835
|
function positionDigest(value) {
|
|
809
836
|
if (value === undefined || !isJSONSafe(value)) return undefined;
|
|
810
837
|
const text = JSON.stringify(value);
|
|
@@ -868,29 +895,36 @@ async function deserializeStream(source, codecOptions, wire) {
|
|
|
868
895
|
throw new Error("missing body");
|
|
869
896
|
}
|
|
870
897
|
const reader = new ChunkReader(source.body);
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
if (result.
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
898
|
+
try {
|
|
899
|
+
const result = await reader.next();
|
|
900
|
+
if (!result.done) {
|
|
901
|
+
if (result.value.startsWith(ERROR_TRAILER_PREFIX)) {
|
|
902
|
+
throw errorFromTrailer(result.value);
|
|
903
|
+
}
|
|
904
|
+
const {
|
|
905
|
+
createJSONDeserializer
|
|
906
|
+
} = await import('@solidjs/web/serialization/decode');
|
|
907
|
+
const deserializeChunk = createJSONDeserializer(codecOptions);
|
|
908
|
+
function interpretChunk(chunk) {
|
|
909
|
+
if (chunk.startsWith(ERROR_TRAILER_PREFIX)) {
|
|
910
|
+
throw errorFromTrailer(chunk);
|
|
911
|
+
}
|
|
912
|
+
return deserializeChunk(JSON.parse(chunk));
|
|
883
913
|
}
|
|
884
|
-
|
|
914
|
+
const connection = wire && wire.connection;
|
|
915
|
+
let endConnection;
|
|
916
|
+
if (connection) ;
|
|
917
|
+
const end = error => {
|
|
918
|
+
const sweep = () => deserializeChunk.abort(error);
|
|
919
|
+
if (connection) ; else sweep();
|
|
920
|
+
};
|
|
921
|
+
reader.drain(interpretChunk).then(() => end(new Error("Server function stream ended unexpectedly.")), error => end(error));
|
|
922
|
+
return interpretChunk(result.value);
|
|
885
923
|
}
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
};
|
|
890
|
-
reader.drain(interpretChunk).then(() => end(new Error("Server function stream ended unexpectedly.")), error => end(error));
|
|
891
|
-
return interpretChunk(result.value);
|
|
924
|
+
} catch (error) {
|
|
925
|
+
reader.cancel(error).catch(() => {});
|
|
926
|
+
throw error;
|
|
892
927
|
}
|
|
893
|
-
return undefined;
|
|
894
928
|
}
|
|
895
929
|
async function deserializeString(text, codecOptions) {
|
|
896
930
|
return await deserializeStream(new Response(text), codecOptions);
|
|
@@ -1000,10 +1034,13 @@ function copyInitHeaders(init) {
|
|
|
1000
1034
|
for (const cookie of init.getSetCookie()) headers.append("Set-Cookie", cookie);
|
|
1001
1035
|
return headers;
|
|
1002
1036
|
}
|
|
1003
|
-
|
|
1004
|
-
|
|
1037
|
+
let stubGapFillExcluded;
|
|
1038
|
+
function isStubGapFillExcluded(key) {
|
|
1039
|
+
return (stubGapFillExcluded ||= new Set([ERROR_HEADER, BODY_FORMAT_HEADER, SINGLE_FLIGHT_HEADER, REVALIDATE_HEADER, REDIRECT_HEADER, "Location",
|
|
1040
|
+
...COMPOSED_BODY_FRAMING].map(header => header.toLowerCase()))).has(key);
|
|
1041
|
+
}
|
|
1005
1042
|
function fillsStubGap(key, headers, response) {
|
|
1006
|
-
if (key === "set-cookie" ||
|
|
1043
|
+
if (key === "set-cookie" || isStubGapFillExcluded(key)) return false;
|
|
1007
1044
|
if (response.body === null && (key === "content-type" || key === "content-length")) return false;
|
|
1008
1045
|
return !headers.has(key);
|
|
1009
1046
|
}
|
|
@@ -1558,20 +1595,28 @@ function createServerReference({
|
|
|
1558
1595
|
const scope = run => provideEvent(evt, run);
|
|
1559
1596
|
const wrap = resolveWrapInvocation(config.wrapInvocation);
|
|
1560
1597
|
const hook = requestErrorHook(ogEvt);
|
|
1561
|
-
let result
|
|
1562
|
-
|
|
1563
|
-
|
|
1564
|
-
|
|
1565
|
-
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1598
|
+
let result;
|
|
1599
|
+
try {
|
|
1600
|
+
result = provideEventOnce(provideEvent, evt, () => {
|
|
1601
|
+
const run = () => fn.apply(thisArg, args);
|
|
1602
|
+
return observeInvocation({
|
|
1603
|
+
id,
|
|
1604
|
+
direct: true,
|
|
1605
|
+
event: evt,
|
|
1606
|
+
args
|
|
1607
|
+
}, () => reportDirectFailure(() => wrap ? wrap(run, {
|
|
1608
|
+
id,
|
|
1609
|
+
args,
|
|
1610
|
+
event: evt,
|
|
1611
|
+
direct: true
|
|
1612
|
+
}) : run(), id, hook));
|
|
1613
|
+
});
|
|
1614
|
+
} catch (error) {
|
|
1615
|
+
throw directEnvelopeValue(error, evt);
|
|
1616
|
+
}
|
|
1617
|
+
result = result && typeof result.then === "function" ? result.then(value => directEnvelopeValue(value, evt), error => {
|
|
1618
|
+
throw directEnvelopeValue(error, evt);
|
|
1619
|
+
}) : directEnvelopeValue(result, evt);
|
|
1575
1620
|
result = scopeDeferredResult(result, scope);
|
|
1576
1621
|
const transform = config.transformDirectResult;
|
|
1577
1622
|
if (transform && result && typeof result.then === "function") {
|
|
@@ -2455,7 +2500,7 @@ function encodeLiveResult(value, headers, status, codec, request, scope) {
|
|
|
2455
2500
|
function encodeResult(value, headers, status, codec, signal, scope) {
|
|
2456
2501
|
if (NULL_BODY_STATUSES.has(status)) {
|
|
2457
2502
|
if (value === undefined || value === null) {
|
|
2458
|
-
headers.set(BODY_FORMAT_HEADER, BodyFormat.Void);
|
|
2503
|
+
if (status !== 304) headers.set(BODY_FORMAT_HEADER, BodyFormat.Void);
|
|
2459
2504
|
return new Response(null, {
|
|
2460
2505
|
status,
|
|
2461
2506
|
headers
|
|
@@ -2542,6 +2587,7 @@ function currentEvent() {
|
|
|
2542
2587
|
}
|
|
2543
2588
|
function reportDirectFailure(run, id, hook) {
|
|
2544
2589
|
const report = error => {
|
|
2590
|
+
if (error instanceof Response || isResponseEnvelope(error)) throw error;
|
|
2545
2591
|
reportServerError(error, {
|
|
2546
2592
|
kind: "server-function",
|
|
2547
2593
|
handling: "thrown",
|
|
@@ -2558,6 +2604,20 @@ function reportDirectFailure(run, id, hook) {
|
|
|
2558
2604
|
}
|
|
2559
2605
|
return result && typeof result.then === "function" ? result.then(undefined, report) : result;
|
|
2560
2606
|
}
|
|
2607
|
+
function directEnvelopeValue(result, event) {
|
|
2608
|
+
if (!isResponseEnvelope(result)) return result;
|
|
2609
|
+
const {
|
|
2610
|
+
response,
|
|
2611
|
+
value
|
|
2612
|
+
} = result;
|
|
2613
|
+
const stub = event.response;
|
|
2614
|
+
if (response && stub && stub.headers && response.headers.getSetCookie) {
|
|
2615
|
+
for (const cookie of response.headers.getSetCookie()) {
|
|
2616
|
+
stub.headers.append("Set-Cookie", cookie);
|
|
2617
|
+
}
|
|
2618
|
+
}
|
|
2619
|
+
return value;
|
|
2620
|
+
}
|
|
2561
2621
|
function sanitizeServerError(value) {
|
|
2562
2622
|
if (DEV) return value;
|
|
2563
2623
|
if (isSafeError(value)) return value;
|
|
@@ -2806,8 +2866,14 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
2806
2866
|
});
|
|
2807
2867
|
return finish(protectsRequest ? withCSRFVary(response) : response);
|
|
2808
2868
|
}
|
|
2869
|
+
const commitResponse = raw => {
|
|
2870
|
+
if ((method === "GET" || method === "HEAD") && (sharedCacheMayStore(departingHeader(raw, event, "Cache-Control")) || cdnMayStore(departingHeader(raw, event, "CDN-Cache-Control")))) {
|
|
2871
|
+
withholdTrace(event);
|
|
2872
|
+
}
|
|
2873
|
+
return commitEventResponse(raw, event);
|
|
2874
|
+
};
|
|
2809
2875
|
const refuseCommitted = raw => {
|
|
2810
|
-
const response =
|
|
2876
|
+
const response = commitResponse(raw);
|
|
2811
2877
|
return finish(protectsRequest ? withCSRFVary(response) : response);
|
|
2812
2878
|
};
|
|
2813
2879
|
const provide = options.provideEvent || provideEvent;
|
|
@@ -3025,9 +3091,54 @@ async function handleServerFunctionRequest(request, options = {}) {
|
|
|
3025
3091
|
return respondThrown(x);
|
|
3026
3092
|
}
|
|
3027
3093
|
};
|
|
3028
|
-
const response =
|
|
3094
|
+
const response = commitResponse(enforceComposedHeaderInvariants(ownResponse(await dispatch())));
|
|
3029
3095
|
return finish(protectsRequest ? withCSRFVary(response) : response);
|
|
3030
3096
|
}
|
|
3097
|
+
function departingHeader(response, event, name) {
|
|
3098
|
+
const own = response.headers.get(name);
|
|
3099
|
+
if (own !== null) return own;
|
|
3100
|
+
const stub = event.response;
|
|
3101
|
+
return stub && stub.headers && !stub.committed ? stub.headers.get(name) : null;
|
|
3102
|
+
}
|
|
3103
|
+
function cdnMayStore(cdnCacheControl) {
|
|
3104
|
+
return cdnCacheControl !== null && !forbidsStoring(cdnCacheControl);
|
|
3105
|
+
}
|
|
3106
|
+
function sharedCacheMayStore(cacheControl) {
|
|
3107
|
+
let shared = false;
|
|
3108
|
+
return !!cacheControl && !eachDirective(cacheControl, name => {
|
|
3109
|
+
if (name === "public" || name === "s-maxage") shared = true;
|
|
3110
|
+
}) && shared;
|
|
3111
|
+
}
|
|
3112
|
+
function forbidsStoring(value) {
|
|
3113
|
+
return eachDirective(value, () => {});
|
|
3114
|
+
}
|
|
3115
|
+
function eachDirective(value, visit) {
|
|
3116
|
+
let start = 0;
|
|
3117
|
+
let quoted = false;
|
|
3118
|
+
for (let i = 0; i <= value.length; i++) {
|
|
3119
|
+
const c = value[i];
|
|
3120
|
+
if (quoted) {
|
|
3121
|
+
if (c === "\\") i++;else if (c === '"') quoted = false;
|
|
3122
|
+
continue;
|
|
3123
|
+
}
|
|
3124
|
+
if (c === '"') {
|
|
3125
|
+
quoted = true;
|
|
3126
|
+
continue;
|
|
3127
|
+
}
|
|
3128
|
+
if (c !== "," && i < value.length) continue;
|
|
3129
|
+
const directive = value.slice(start, i);
|
|
3130
|
+
start = i + 1;
|
|
3131
|
+
const eq = directive.indexOf("=");
|
|
3132
|
+
const name = (eq === -1 ? directive : directive.slice(0, eq)).trim().toLowerCase();
|
|
3133
|
+
if (name === "no-store" || name === "private" && eq === -1) return true;
|
|
3134
|
+
visit(name);
|
|
3135
|
+
}
|
|
3136
|
+
return false;
|
|
3137
|
+
}
|
|
3138
|
+
function withholdTrace(event) {
|
|
3139
|
+
if (event.response && event.response.committed) return;
|
|
3140
|
+
traceForEvent(event).emit = false;
|
|
3141
|
+
}
|
|
3031
3142
|
function ownResponse(response) {
|
|
3032
3143
|
try {
|
|
3033
3144
|
return new Response(response.body, response);
|
|
@@ -14,12 +14,12 @@ this file is the operative subset.
|
|
|
14
14
|
|
|
15
15
|
- Exists because of **server data** (a todo row, a nav link, a search
|
|
16
16
|
form the server renders)? It is **server markup**. Client behavior or a
|
|
17
|
-
client-driven value on it is
|
|
17
|
+
client-driven value on it is a **binding slot** — bind, never wrap.
|
|
18
18
|
Do not wrap a server-rendered element in a client component to give it a
|
|
19
19
|
handler or a class.
|
|
20
20
|
- Exists because of **client state alone** (an optimistic add, a modal, a
|
|
21
21
|
drag ghost, an editor open over a field)? It is a **client component**
|
|
22
|
-
placed through a **
|
|
22
|
+
placed through a **template slot**.
|
|
23
23
|
|
|
24
24
|
When the client confirms an optimistic entity and the server renders it, the
|
|
25
25
|
row _becomes_ server markup; `$key` on the element reconciles the two.
|
|
@@ -27,19 +27,19 @@ row _becomes_ server markup; `$key` on the element reconciles the two.
|
|
|
27
27
|
## The two kinds of slot
|
|
28
28
|
|
|
29
29
|
```tsx
|
|
30
|
-
import type {
|
|
30
|
+
import type { BindingSlot, Slot } from "@solidjs/web/frames";
|
|
31
31
|
|
|
32
32
|
interface TodosProps {
|
|
33
|
-
pending: Slot; //
|
|
34
|
-
row:
|
|
35
|
-
filters:
|
|
33
|
+
pending: Slot; // template: the client returns JSX
|
|
34
|
+
row: BindingSlot<{ id: string; completed: boolean }, RowBehavior>; // bindings: the client returns an object
|
|
35
|
+
filters: BindingSlot<{}, FilterBehavior>; // no args: called bare
|
|
36
36
|
}
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
-
A **
|
|
39
|
+
A **template slot** is placed as an element: `<props.pending />`. The client
|
|
40
40
|
owns those nodes.
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
A **binding slot** is _called_ once per data context and its properties
|
|
43
43
|
are _bound_ at positions of the server's own template:
|
|
44
44
|
|
|
45
45
|
```tsx
|
|
@@ -72,12 +72,17 @@ export async function todoList() {
|
|
|
72
72
|
The client passes the fill — a function of the args that returns the object:
|
|
73
73
|
|
|
74
74
|
```tsx
|
|
75
|
-
<Todos row={rowFor} filters={() => ({ all
|
|
75
|
+
<Todos row={rowFor} filters={() => ({ get all() { return filter() === "all"; }, … })} pending={() => <For each={adds}>{…}</For>} />
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
|
|
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.
|
|
79
82
|
|
|
80
|
-
|
|
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.**
|
|
81
86
|
|
|
82
87
|
Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
|
|
83
88
|
`title={row.error}`), a class name inside object form
|
|
@@ -86,8 +91,12 @@ Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
|
|
|
86
91
|
an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element
|
|
87
92
|
with a spread too (`<button {...rest} onClick={row.go} />` — the last
|
|
88
93
|
source that has the key wins, `undefined` included, as the client's
|
|
89
|
-
spread reads it)
|
|
90
|
-
|
|
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
|
|
91
100
|
plain objects and arrays included). Reserved keys the fill must not use:
|
|
92
101
|
keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`,
|
|
93
102
|
`constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map`
|
|
@@ -97,25 +106,34 @@ The server **does not have the value** — on the stream face a property read
|
|
|
97
106
|
is a stand-in with no value, on the document face only the initial one — so
|
|
98
107
|
nothing can be computed from it on the server. Every one of these is wrong:
|
|
99
108
|
|
|
100
|
-
| Wrong | Why | Write instead
|
|
101
|
-
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
102
|
-
| ``class={`todo ${row.done}`}`` | stringified: not the whole value | `class={{ todo: true, completed: row.done }}` or return `rowClass` from the fill
|
|
103
|
-
| `row.count > 3 ? "a" : "b"` | comparison on a stand-in | decide in the fill; return the decided value
|
|
104
|
-
| `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
|
|
105
|
-
| `<strong>{row.
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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.
|
|
114
126
|
|
|
115
127
|
## Writing the fill
|
|
116
128
|
|
|
117
|
-
- **
|
|
118
|
-
|
|
129
|
+
- **The fill runs once per occurrence, as a component body does.** It runs
|
|
130
|
+
untracked, under the occurrence's owner, with live args. State it
|
|
131
|
+
creates (a signal, a memo, an `onCleanup`) lives as long as the
|
|
132
|
+
occurrence. A top-level read is read once, and `STRICT_READ_UNTRACKED`
|
|
133
|
+
names it.
|
|
134
|
+
- **Values as getters, handlers as plain closures.** A getter is the
|
|
135
|
+
reactive form, as on a component's props object; a plain value never
|
|
136
|
+
updates:
|
|
119
137
|
|
|
120
138
|
```tsx
|
|
121
139
|
const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({
|
|
@@ -133,11 +151,11 @@ is why.
|
|
|
133
151
|
});
|
|
134
152
|
```
|
|
135
153
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
154
|
+
Each getter is read where its position binds, so a change moves the
|
|
155
|
+
positions that read it. The same object serves a client
|
|
156
|
+
`<TodoRow row={rowFor(todo)} />`, whose body reads it the same way. A
|
|
157
|
+
plain value is right only for what never changes (a constant handler,
|
|
158
|
+
a fixed class).
|
|
141
159
|
|
|
142
160
|
- **Name it like a props interface**, because it is one (a shared component
|
|
143
161
|
takes it as a prop). Handlers are `on` + intent — `onToggle`, `onRemove`,
|
|
@@ -147,9 +165,10 @@ is why.
|
|
|
147
165
|
runtime reads nothing into the prefix — the position decides what a
|
|
148
166
|
property is — but a reader can tell a handler from a value without
|
|
149
167
|
opening the type.
|
|
150
|
-
-
|
|
151
|
-
|
|
152
|
-
fires once per element.
|
|
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.
|
|
153
172
|
- **`$key` is optional.** A call repeated within a render (a component
|
|
154
173
|
prop re-evaluates it per position) is one occurrence either way. Add
|
|
155
174
|
`$key: t.id` when the fill holds its own state (an edit draft, a signal
|
|
@@ -162,7 +181,7 @@ is why.
|
|
|
162
181
|
## Shared components
|
|
163
182
|
|
|
164
183
|
One component can render on both sides: on the server its `row` prop is
|
|
165
|
-
the
|
|
184
|
+
the binding slot's return, on the client it is the fill's result. It
|
|
166
185
|
cannot tell and need not. Put `$key={props.id}` on the element it renders
|
|
167
186
|
(morph identity) — the slot call's own `$key` is a different key for a
|
|
168
187
|
different job. Do not read `document`/`window` during render; that is the
|
|
@@ -181,26 +200,29 @@ cannot be marked — the `inline` finding below.
|
|
|
181
200
|
|
|
182
201
|
## Diagnostics
|
|
183
202
|
|
|
184
|
-
`
|
|
203
|
+
`BINDING_SLOT_POSITION` (`data.reason`):
|
|
185
204
|
|
|
186
205
|
| reason | severity | what happened | fix |
|
|
187
206
|
| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
188
207
|
| `spread` | error (throws) | a slot's return was spread onto an element | name each position |
|
|
189
208
|
| `stringified` | warn | template literal / concatenation | whole value at one position |
|
|
190
209
|
| `coerced` | warn | comparison, arithmetic, `==` | decide in the fill |
|
|
191
|
-
| `text` | warn | placed as a text child | markup slot |
|
|
192
210
|
| `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` |
|
|
193
211
|
| `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot |
|
|
194
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 |
|
|
195
214
|
| `reserved-key` | warn | the fill used a reserved key | rename it |
|
|
196
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 |
|
|
197
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 |
|
|
198
|
-
| `fill-shape` | warn (client) | the fill returned a non-object (`null`, array, DOM node, primitive), or the prop read as data is not a function
|
|
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 |
|
|
199
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 |
|
|
200
220
|
|
|
201
|
-
Every reason but `fill-shape` and `orphan` comes from the server render.
|
|
221
|
+
Every reason but `fill-shape`, `text-shape` and `orphan` comes from the server render.
|
|
202
222
|
`orphan` is the one failure this model cannot otherwise show you: the
|
|
203
223
|
element is inert — a handler that never fires, a class that never updates —
|
|
204
224
|
with no error.
|
|
205
225
|
|
|
206
|
-
`STRICT_READ_UNTRACKED`
|
|
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).
|