lit-ui-router-ssr 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -36
- package/dist/client.d.ts +126 -4
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +149 -25
- package/dist/client.js.map +1 -1
- package/dist/dev-warn.d.ts +10 -0
- package/dist/dev-warn.d.ts.map +1 -1
- package/dist/dev-warn.js +1 -0
- package/dist/dev-warn.js.map +1 -1
- package/dist/development/client.js +162 -30
- package/dist/development/client.js.map +1 -1
- package/dist/development/dev-warn.js +4 -0
- package/dist/development/dev-warn.js.map +1 -1
- package/dist/development/index.js +1 -0
- package/dist/development/index.js.map +1 -1
- package/dist/development/light-dom-brand.js +7 -0
- package/dist/development/light-dom-brand.js.map +1 -0
- package/dist/development/light-dom.js +55 -0
- package/dist/development/light-dom.js.map +1 -0
- package/dist/development/light-element-renderer.js +16 -0
- package/dist/development/light-element-renderer.js.map +1 -0
- package/dist/development/prerender.js +19 -138
- package/dist/development/prerender.js.map +1 -1
- package/dist/development/served-markers.js +1 -1
- package/dist/development/served-view.js +18 -15
- package/dist/development/served-view.js.map +1 -1
- package/dist/development/signature.js +3 -1
- package/dist/development/signature.js.map +1 -1
- package/dist/development/ui-view-renderer.js +12 -2
- package/dist/development/ui-view-renderer.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/light-dom-brand.d.ts +20 -0
- package/dist/light-dom-brand.d.ts.map +1 -0
- package/dist/light-dom-brand.js +7 -0
- package/dist/light-dom-brand.js.map +1 -0
- package/dist/light-dom.d.ts +61 -0
- package/dist/light-dom.d.ts.map +1 -0
- package/dist/light-dom.js +55 -0
- package/dist/light-dom.js.map +1 -0
- package/dist/light-element-renderer.d.ts +45 -0
- package/dist/light-element-renderer.d.ts.map +1 -0
- package/dist/light-element-renderer.js +16 -0
- package/dist/light-element-renderer.js.map +1 -0
- package/dist/prerender.d.ts +23 -108
- package/dist/prerender.d.ts.map +1 -1
- package/dist/prerender.js +19 -121
- package/dist/prerender.js.map +1 -1
- package/dist/served-markers.d.ts +4 -4
- package/dist/served-markers.js +1 -1
- package/dist/served-view.d.ts +43 -0
- package/dist/served-view.d.ts.map +1 -1
- package/dist/served-view.js +16 -11
- package/dist/served-view.js.map +1 -1
- package/dist/signature.d.ts +10 -0
- package/dist/signature.d.ts.map +1 -1
- package/dist/signature.js +3 -1
- package/dist/signature.js.map +1 -1
- package/dist/ui-view-renderer.d.ts +27 -1
- package/dist/ui-view-renderer.d.ts.map +1 -1
- package/dist/ui-view-renderer.js +12 -2
- package/dist/ui-view-renderer.js.map +1 -1
- package/package.json +2 -2
- package/src/client.ts +444 -58
- package/src/dev-warn.ts +19 -1
- package/src/index.ts +2 -0
- package/src/light-dom-brand.ts +34 -0
- package/src/light-dom.ts +139 -0
- package/src/light-element-renderer.ts +66 -0
- package/src/prerender.ts +78 -382
- package/src/served-markers.ts +4 -4
- package/src/served-view.ts +80 -31
- package/src/signature.ts +26 -0
- package/src/ui-view-renderer.ts +45 -4
package/README.md
CHANGED
|
@@ -26,10 +26,12 @@ imports the pre-1.0 renderer or re-derives the incantation.
|
|
|
26
26
|
`<script type="application/json" data-lit-ui-router-ssr>`, naming this package's version, the
|
|
27
27
|
state the router stood on, and that state's url parameter values. A page `renderShell` returns
|
|
28
28
|
as a string is written as-is, without one.
|
|
29
|
-
- **The emit loop.**
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
29
|
+
- **The lit render inside the emit loop.** The loop itself — verdict to file name, redirect to
|
|
30
|
+
rules line, the `_redirects` file, delegating states skipped, tally, warnings for paths that
|
|
31
|
+
matched nothing — is
|
|
32
|
+
`prerender` from `ui-router-server/prerender`, which takes any render. This package's `prerender`
|
|
33
|
+
supplies the lit one and takes the same options, plus `router`, `renderShell`, `document`,
|
|
34
|
+
`root` and `elementRenderers`. No SPA catch-all is ever written: one turns every 404 into a 200.
|
|
33
35
|
- **`<ui-view>` on both sides.** `UiViewRenderer` fills the element's light DOM on the server;
|
|
34
36
|
`lit-ui-router-ssr/client` adopts what it drew.
|
|
35
37
|
|
|
@@ -66,9 +68,13 @@ const result = await prerender({
|
|
|
66
68
|
document: (body, { path }) => fillShell(titles.get(path), body),
|
|
67
69
|
});
|
|
68
70
|
|
|
69
|
-
console.log(result.tally); // { shell: 2, redirect: 1, notFound: 0, document: 1 }
|
|
71
|
+
console.log(result.tally); // { shell: 2, redirect: 1, notFound: 0, delegate: 0, document: 1 }
|
|
70
72
|
```
|
|
71
73
|
|
|
74
|
+
`result.delegated` lists the paths that matched a delegating state. They get no page and no rules
|
|
75
|
+
line, so route them to your server; on Cloudflare, list them in the Worker's
|
|
76
|
+
`assets.run_worker_first` so the asset layer doesn't answer them first.
|
|
77
|
+
|
|
72
78
|
`result.pages` lists every artefact in enumeration order, `result.rules` every line the host file
|
|
73
79
|
carries, and `result.warnings` the paths that matched no route and had no projection to fall back
|
|
74
80
|
on. `dryRun: true` plans all of it and writes nothing.
|
|
@@ -121,8 +127,10 @@ directly, so a page loop calls it once per path on the same router, started or n
|
|
|
121
127
|
|
|
122
128
|
## The routed view, drawn on the server
|
|
123
129
|
|
|
124
|
-
`elementRenderers` defaults to `[UiViewRenderer]` — not `@lit-labs/ssr`'s
|
|
125
|
-
which wraps every custom element in a declarative shadow root it never asked
|
|
130
|
+
`elementRenderers` defaults to `[UiViewRenderer, LightElementRenderer]` — not `@lit-labs/ssr`'s
|
|
131
|
+
`[LitElementRenderer]`, which wraps every custom element in a declarative shadow root it never asked
|
|
132
|
+
for. `LightElementRenderer` answers only for an element that opted in (see
|
|
133
|
+
[Light-DOM elements](#light-dom-elements)). `UiViewRenderer`
|
|
126
134
|
answers for `ui-view`: it registers the view at the address its `name` attribute and enclosing
|
|
127
135
|
`<ui-view>`s spell, takes the `ViewConfig` the registration syncs back, and writes the routed
|
|
128
136
|
component into the element's light DOM between the part markers the element's own `render()`
|
|
@@ -172,8 +180,8 @@ card empty:
|
|
|
172
180
|
```
|
|
173
181
|
|
|
174
182
|
`@lit-labs/ssr` writes a `.prop=${…}` binding as its part marker and nothing else — no attribute, no
|
|
175
|
-
child, no value. Setting the property is an element renderer's job, and `elementRenderers`
|
|
176
|
-
|
|
183
|
+
child, no value. Setting the property is an element renderer's job, and the default `elementRenderers`
|
|
184
|
+
answer for `ui-view` and for opted-in light-DOM elements alone. The card has no renderer, so nothing on
|
|
177
185
|
the server sets `post` or runs its `render()`: the card first draws on the client, once hydration
|
|
178
186
|
sets the property, and the served page shows an empty tag where it stands.
|
|
179
187
|
|
|
@@ -233,11 +241,16 @@ shadow root:
|
|
|
233
241
|
|
|
234
242
|
```typescript
|
|
235
243
|
import { LitElementRenderer } from '@lit-labs/ssr';
|
|
236
|
-
import {
|
|
244
|
+
import {
|
|
245
|
+
LightElementRenderer,
|
|
246
|
+
prerender,
|
|
247
|
+
UiViewRenderer,
|
|
248
|
+
} from 'lit-ui-router-ssr';
|
|
237
249
|
|
|
238
250
|
await prerender({
|
|
239
251
|
// …
|
|
240
|
-
|
|
252
|
+
// The list replaces the default; LightElementRenderer stays ahead of the shadow-root renderer.
|
|
253
|
+
elementRenderers: [UiViewRenderer, LightElementRenderer, LitElementRenderer],
|
|
241
254
|
});
|
|
242
255
|
```
|
|
243
256
|
|
|
@@ -270,16 +283,14 @@ registers `<ui-view>`. That entry defines `<ui-router>` from core and `<ui-view>
|
|
|
270
283
|
`withServedRender(UiView)`. Every value the app takes from the router — `UIRouterLit`, `srefHref`,
|
|
271
284
|
`srefActiveClass`, `srefAriaCurrent` — comes from `lit-ui-router/pure`, which registers nothing;
|
|
272
285
|
the root entry registers the plain `<ui-view>` as a side effect, and imported after this one it
|
|
273
|
-
warns that the tag is already defined. Then
|
|
286
|
+
warns that the tag is already defined. Then one call boots the router and adopts the page:
|
|
274
287
|
|
|
275
288
|
```typescript
|
|
276
289
|
import 'lit-ui-router-ssr/register';
|
|
277
290
|
import { UIRouterLit, srefHref } from 'lit-ui-router/pure';
|
|
278
|
-
import {
|
|
291
|
+
import { bootstrap } from 'lit-ui-router-ssr/client';
|
|
279
292
|
|
|
280
|
-
router
|
|
281
|
-
await booted; // the first successful transition
|
|
282
|
-
const release = hydrateRoot(root, page(router));
|
|
293
|
+
await bootstrap(router, root, page(router));
|
|
283
294
|
```
|
|
284
295
|
|
|
285
296
|
A `<ui-view>` another class already defined throws, naming both ways out.
|
|
@@ -325,29 +336,41 @@ The result still extends core's `UiView`, so an enclosing view adopts it as a pa
|
|
|
325
336
|
|
|
326
337
|
## The client half
|
|
327
338
|
|
|
328
|
-
`lit-ui-router-ssr/client` is the adopt side — no import side effects.
|
|
329
|
-
|
|
339
|
+
`lit-ui-router-ssr/client` is the adopt side — no import side effects. One call boots the router
|
|
340
|
+
and adopts the page, or renders it cold, and resolves once the page is live:
|
|
330
341
|
|
|
331
342
|
```typescript
|
|
332
|
-
import {
|
|
333
|
-
|
|
334
|
-
const booted = new Promise<void>((resolve) => {
|
|
335
|
-
const off = router.transitionService.onSuccess({}, () => {
|
|
336
|
-
off();
|
|
337
|
-
resolve();
|
|
338
|
-
});
|
|
339
|
-
});
|
|
340
|
-
router.start();
|
|
341
|
-
await booted;
|
|
343
|
+
import { bootstrap } from 'lit-ui-router-ssr/client';
|
|
342
344
|
|
|
343
|
-
const
|
|
344
|
-
if (!release) render(page(router), root);
|
|
345
|
+
const { outcome } = await bootstrap(router, root, page(router));
|
|
345
346
|
```
|
|
346
347
|
|
|
347
|
-
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
348
|
+
- **`bootstrap(router, container, value, options?)` owns the boot.** It reads the container's
|
|
349
|
+
signature, starts the router, waits for the boot transition to land — following redirects to the
|
|
350
|
+
one that succeeds — then runs `hydrateRoot()`. The walk commits `.uiRouter` onto `<ui-router>` and
|
|
351
|
+
each `<ui-view>` re-seeks the router before its own first render, so every view finds the settled
|
|
352
|
+
router rather than the placeholder it registered against. The call waits for every awake
|
|
353
|
+
`<ui-view>`, nested ones included, to finish updating, then releases the adopter. It resolves with
|
|
354
|
+
`outcome` — `adopted` or `cold` — and `signature` (`BootstrapSignature`): `matched` when the boot
|
|
355
|
+
landed on the state and url parameters the signature names, `elsewhere` when the document carried
|
|
356
|
+
a signature and the boot landed somewhere else or landed no transition, and `absent` when it
|
|
357
|
+
carried none. Nothing constrains when `lit-ui-router-ssr/register` is imported.
|
|
358
|
+
- **The cold path is the same call.** A container with nothing to adopt is emptied and `value`
|
|
359
|
+
rendered into it before the router starts. A boot transition that fails, a url that starts none,
|
|
360
|
+
and a root `hydrate()` that throws over a mutated document all empty the container and render
|
|
361
|
+
`value` cold too, and the call resolves with the cause in `error` rather than rejecting.
|
|
362
|
+
- **The boot decides mismatches once.** A boot that lands where the document was drawn adopts every
|
|
363
|
+
view, and a view that still mismatches warns in development: the two halves render that template
|
|
364
|
+
differently. A boot that lands elsewhere — one static document served for a family of urls, or a
|
|
365
|
+
redirect — adopts the views that match and renders the rest cold without a warning each; once the
|
|
366
|
+
page is live, the development build warns once, naming both states and how many views rendered
|
|
367
|
+
cold.
|
|
368
|
+
- **The boot transition takes a seed.** `options.payload` is handed to `seed()` from
|
|
369
|
+
`ui-router-server/ssr/client` before the router starts, so the boot transition adopts the
|
|
370
|
+
resolved values a server render drew in place of running their resolve functions.
|
|
371
|
+
- **`hydrateRoot()` is the step underneath.** An app that owns its own boot calls `router.start()`,
|
|
372
|
+
awaits the first successful transition, then `hydrateRoot(root, page(router))`, and renders
|
|
373
|
+
`page(router)` itself when that returns `false`.
|
|
351
374
|
- **The signature decides first.** `hydrateRoot()` reads the container's hydration signature before
|
|
352
375
|
it touches the document, and returns `false` over an emptied container when there is none — a
|
|
353
376
|
cold client render, a dev server, a page from an earlier `prerender()`, a string `renderShell` —
|
|
@@ -368,7 +391,9 @@ if (!release) render(page(router), root);
|
|
|
368
391
|
before that update stays asleep, holding its nodes, until it is attached again. The walk pins the
|
|
369
392
|
adopter to every served view it passes, so that view is adopted on its return even once the root
|
|
370
393
|
provider is released. A view the walk never reached drops those nodes, renders cold, and warns in
|
|
371
|
-
development.
|
|
394
|
+
development. A deferred element no walk reaches — one the render wrote no marker for — wakes
|
|
395
|
+
with the adoption of the view that holds it, after that view's hydrate, or with the root walk when
|
|
396
|
+
no view holds it.
|
|
372
397
|
- **The prefix is the protocol, and both halves are here.** `UiViewRenderer` writes a plain outer
|
|
373
398
|
part pair around each view's routed markup and prefixes every marker between them; `hydrate()`
|
|
374
399
|
reads past a prefixed comment, so the walk hydrating a view's surroundings stops at that pair. The
|
|
@@ -392,11 +417,67 @@ if (!release) render(page(router), root);
|
|
|
392
417
|
(`uiViewAdoptEventName`), bubbling and composed, with `detail.outcome` one of `adopted` — its
|
|
393
418
|
served nodes are the live ones — `fell-back` — a mismatch or a lost pair, with `detail.error`
|
|
394
419
|
carrying the cause — or `none`, nothing to adopt. It fires once per view, parent first, in
|
|
395
|
-
production as in development.
|
|
420
|
+
production as in development. The `onAdopt(view, outcome, error)` option of `bootstrap()` and `hydrateRoot()` receives
|
|
396
421
|
the same reports for every view its walk reaches, a view the pin adopts after the release included.
|
|
397
422
|
- **A mutated document throws.** `hydrateRoot()` rethrows what `hydrate()` threw, over a container it
|
|
398
423
|
first empties. The caller renders into it.
|
|
399
424
|
|
|
425
|
+
### Light-DOM elements
|
|
426
|
+
|
|
427
|
+
A consumer's own `LitElement` that renders into its light DOM opts in to the same sleep-then-adopt
|
|
428
|
+
cycle with `LightDomHydrating(Base)` from `lit-ui-router-ssr/client`. `LightElementRenderer` from
|
|
429
|
+
`lit-ui-router-ssr`, one of `prerender()`'s default renderers, draws it on the server, and
|
|
430
|
+
`lightSlot()` marks the hole at the use site:
|
|
431
|
+
|
|
432
|
+
```typescript
|
|
433
|
+
import { html, LitElement } from 'lit';
|
|
434
|
+
import { property } from 'lit/decorators.js';
|
|
435
|
+
import { LightDomHydrating, lightSlot } from 'lit-ui-router-ssr/client';
|
|
436
|
+
|
|
437
|
+
export class AppCard extends LightDomHydrating(LitElement) {
|
|
438
|
+
@property() label = '';
|
|
439
|
+
|
|
440
|
+
render() {
|
|
441
|
+
return html`<p>${this.label}</p>`;
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
export const card = (label: string) =>
|
|
446
|
+
html`<app-card .label=${label}>${lightSlot()}</app-card>`;
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
- **Each class opts in.** The mixin stamps a `Symbol.for` brand on the class it returns, and the
|
|
450
|
+
renderer matches that brand, so a subclass stays opted in, the base class does not, and a second
|
|
451
|
+
copy of this package recognises it. An element that did not opt in is served empty and renders
|
|
452
|
+
cold.
|
|
453
|
+
- **The server writes `render()` into the light DOM.** `LightElementRenderer` extends
|
|
454
|
+
`@lit-labs/ssr`'s `LitElementRenderer`: it builds the element, sets its attributes and properties,
|
|
455
|
+
runs `willUpdate`, and writes the render where a shadow root would go, prefixing its markers as
|
|
456
|
+
`UiViewRenderer` prefixes a view's. Custom elements inside it, `<ui-view>` included, render too.
|
|
457
|
+
An explicit `elementRenderers` replaces the default, so keep it in that list, ahead of any
|
|
458
|
+
`LitElementRenderer`: the first renderer that matches a class wins. A render that awaits is not
|
|
459
|
+
served.
|
|
460
|
+
- **`lightSlot()` is the hole.** It is `uiViewSlot()` under a name that does not read as a view: the
|
|
461
|
+
server reaches the renderer through it, and on the client it wakes the element when the
|
|
462
|
+
enclosing walk reaches it, parent first, and pins the adopter to it.
|
|
463
|
+
- **The element wakes through the adopter.** It sleeps under `defer-hydration`, which `prerender()`
|
|
464
|
+
writes on every custom element, and its first update requests `adoptUiViewContext`. The adopter
|
|
465
|
+
hydrates `render()` against the served nodes in place, then wakes the elements inside it. A view's
|
|
466
|
+
reveal stops at a light-DOM element and the element's stops at a view or another light-DOM
|
|
467
|
+
element, so each interior waits for its own wake. With no adopter, the element drops the served
|
|
468
|
+
nodes and renders cold, warning in development.
|
|
469
|
+
- **It reports through its own event.** Each opted-in element dispatches `light-dom:adopt`
|
|
470
|
+
(`lightDomAdoptEventName`) with the same `detail` as `ui-view:adopt`. `onAdopt`, and the count of
|
|
471
|
+
views `bootstrap()` rendered cold, report views only.
|
|
472
|
+
- **A mismatch falls back.** A hydrate that throws drops the element's served nodes, and it renders
|
|
473
|
+
cold, warning in development; its surroundings keep theirs.
|
|
474
|
+
- **An author child with bindings of its own falls back every time.** A child the use site writes
|
|
475
|
+
beside `lightSlot()` keeps its markers ahead of the element's pair, and the element's hydrate
|
|
476
|
+
meets them first. Static author children are kept, ahead of the render, as they are in a
|
|
477
|
+
`<ui-view>`.
|
|
478
|
+
- **`static styles` do not apply.** A light-DOM element has no shadow root to adopt them into; it
|
|
479
|
+
takes the document's styles.
|
|
480
|
+
|
|
400
481
|
### How this compares
|
|
401
482
|
|
|
402
483
|
Two axes separate the hydration models in circulation: where the code that wakes the markup comes
|
package/dist/client.d.ts
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
import { renderLight } from "@lit-labs/ssr-client/directives/render-light.js";
|
|
2
2
|
import type { RenderOptions } from "lit";
|
|
3
|
+
import type { UIRouterLit } from "lit-ui-router/pure";
|
|
4
|
+
import type { ResolvePayload } from "ui-router-server/ssr/client";
|
|
3
5
|
import type { HydrationSignature } from "./signature.js";
|
|
4
6
|
export { adoptUiViewContext, type AdoptableView, type AdoptUiViewContext, type AdoptUiViewContextKey } from "./adopt-context.js";
|
|
5
7
|
export { isServedViewClass, type ServedUiView, type ServedUiViewConstructor, servedViewBrand, withServedRender } from "./served-view.js";
|
|
8
|
+
export { LightDomHydrating, type LightDomHydratingConstructor, type LightDomHydratingElement, type LitElementConstructor } from "./light-dom.js";
|
|
6
9
|
export type { HydrationSignature } from "./signature.js";
|
|
7
10
|
/**
|
|
8
11
|
* What a served `<ui-view>`'s wake came to.
|
|
@@ -16,7 +19,7 @@ export type { HydrationSignature } from "./signature.js";
|
|
|
16
19
|
export type AdoptOutcome = "adopted" | "fell-back" | "none";
|
|
17
20
|
/**
|
|
18
21
|
* The name of the event a served `<ui-view>` dispatches once its wake's
|
|
19
|
-
* outcome is known
|
|
22
|
+
* outcome is known.
|
|
20
23
|
*/
|
|
21
24
|
export declare const uiViewAdoptEventName: "ui-view:adopt";
|
|
22
25
|
/**
|
|
@@ -34,6 +37,14 @@ export interface UiViewAdoptDetail {
|
|
|
34
37
|
*/
|
|
35
38
|
export type UiViewAdoptEvent = CustomEvent<UiViewAdoptDetail>;
|
|
36
39
|
/**
|
|
40
|
+
* The event a light-DOM hydrating element dispatches from itself at its wake,
|
|
41
|
+
* once its outcome is known. It carries the same detail as {@link
|
|
42
|
+
* uiViewAdoptEventName}, and it does not reach `onAdopt`, which reports views.
|
|
43
|
+
*/
|
|
44
|
+
export declare const lightDomAdoptEventName: "light-dom:adopt";
|
|
45
|
+
/** A light-DOM hydrating element's hydration outcome. */
|
|
46
|
+
export type LightDomAdoptEvent = CustomEvent<UiViewAdoptDetail>;
|
|
47
|
+
/**
|
|
37
48
|
* Receives each served view's outcome, as {@link HydrateRootOptions.onAdopt}.
|
|
38
49
|
*/
|
|
39
50
|
export type AdoptReporter = (view: Element, outcome: AdoptOutcome, error?: unknown) => void;
|
|
@@ -53,6 +64,8 @@ declare global {
|
|
|
53
64
|
interface HTMLElementEventMap {
|
|
54
65
|
/** A served `<ui-view>`'s hydration outcome; see {@link UiViewAdoptEvent}. */
|
|
55
66
|
"ui-view:adopt": UiViewAdoptEvent;
|
|
67
|
+
/** A light-DOM hydrating element's hydration outcome; see {@link LightDomAdoptEvent}. */
|
|
68
|
+
"light-dom:adopt": LightDomAdoptEvent;
|
|
56
69
|
}
|
|
57
70
|
}
|
|
58
71
|
/**
|
|
@@ -77,6 +90,21 @@ declare global {
|
|
|
77
90
|
*/
|
|
78
91
|
export declare const uiViewSlot: typeof renderLight;
|
|
79
92
|
/**
|
|
93
|
+
* The hole a `LightDomHydrating` element fills, written at the use site: the
|
|
94
|
+
* {@link uiViewSlot} directive under a name that does not read as a view.
|
|
95
|
+
*
|
|
96
|
+
* On the server it reaches `LightElementRenderer`'s `renderLight()`, so the
|
|
97
|
+
* element's own render goes where the template puts it. On the client it wakes
|
|
98
|
+
* the element when the enclosing walk reaches it, parent first, and pins the
|
|
99
|
+
* adopter to it.
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```ts
|
|
103
|
+
* html`<app-card .title=${title}>${lightSlot()}</app-card>`;
|
|
104
|
+
* ```
|
|
105
|
+
*/
|
|
106
|
+
export declare const lightSlot: typeof renderLight;
|
|
107
|
+
/**
|
|
80
108
|
* Reads the hydration signature `prerender()` wrote ahead of the render a
|
|
81
109
|
* container holds: the version of this package that drew the document, and
|
|
82
110
|
* the state and parameter values it was drawn for.
|
|
@@ -97,7 +125,7 @@ export declare const uiViewSlot: typeof renderLight;
|
|
|
97
125
|
*
|
|
98
126
|
* await booted;
|
|
99
127
|
* const { state } = readHydrationSignature(root) ?? {};
|
|
100
|
-
* const
|
|
128
|
+
* const bootedWhereDrawn = state === router.globals.current.name;
|
|
101
129
|
* const release = hydrateRoot(root, page(router));
|
|
102
130
|
* ```
|
|
103
131
|
*
|
|
@@ -132,7 +160,9 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
|
|
|
132
160
|
* outside `container`, or one whose attribute the app cleared itself after the
|
|
133
161
|
* release — is answered by nobody: core drops its held nodes and warns in
|
|
134
162
|
* development. An element the render deferred and wrote no marker for is woken
|
|
135
|
-
* once the walk has finished, since nothing in the walk reaches it
|
|
163
|
+
* once the walk has finished, since nothing in the walk reaches it — except
|
|
164
|
+
* one inside a `<ui-view>`, which wakes once that view has hydrated its own
|
|
165
|
+
* render, so a routed element never wakes ahead of the view that routes it.
|
|
136
166
|
*
|
|
137
167
|
* The provider answers synchronously and stops immediate propagation, so an
|
|
138
168
|
* outer provider never answers the same request twice. It outlives this call,
|
|
@@ -150,7 +180,8 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
|
|
|
150
180
|
* A `hydrate()` that throws is rethrown, over a container emptied the same
|
|
151
181
|
* way. The caller renders into it.
|
|
152
182
|
*
|
|
153
|
-
*
|
|
183
|
+
* {@link bootstrap} runs the whole boot around this call. Called directly, the
|
|
184
|
+
* boot is the router first: `router.start()`, await its first successful
|
|
154
185
|
* transition, then this call. The walk commits `.uiRouter` onto `<ui-router>`
|
|
155
186
|
* and each woken `<ui-view>` re-seeks the router before its own first render,
|
|
156
187
|
* so the views find the settled router rather than the placeholder they
|
|
@@ -172,4 +203,95 @@ export declare function readHydrationSignature(container: ParentNode): Hydration
|
|
|
172
203
|
* @returns the function that releases the provider, or `false`, over an emptied container, when there is nothing to adopt — no signature, as on a cold client render or a dev server, one from another release line, or one no render marker follows
|
|
173
204
|
*/
|
|
174
205
|
export declare function hydrateRoot(container: HTMLElement, value: unknown, options?: HydrateRootOptions): false | (() => void);
|
|
206
|
+
/** What {@link bootstrap} came to, once the page is live. */
|
|
207
|
+
export type BootstrapOutcome = "adopted" | "cold";
|
|
208
|
+
/**
|
|
209
|
+
* How a boot compares with the {@link readHydrationSignature | hydration
|
|
210
|
+
* signature} the document carried.
|
|
211
|
+
*
|
|
212
|
+
* - `matched`: the boot transition landed on the state and url parameters the
|
|
213
|
+
* signature names.
|
|
214
|
+
* - `elsewhere`: the document carried a signature, and the boot landed on
|
|
215
|
+
* another state or other parameters — a redirect, or a static host serving
|
|
216
|
+
* one document for a family of urls. A signed document whose boot landed no
|
|
217
|
+
* transition reports this too, beside `outcome: 'cold'` and its `error`.
|
|
218
|
+
* - `absent`: the document carried no signature.
|
|
219
|
+
*
|
|
220
|
+
* A signature from another release line, or one no render marker follows, is
|
|
221
|
+
* still compared, though the container renders cold.
|
|
222
|
+
*/
|
|
223
|
+
export type BootstrapSignature = "matched" | "elsewhere" | "absent";
|
|
224
|
+
/** What {@link bootstrap} resolves with. */
|
|
225
|
+
export interface BootstrapResult {
|
|
226
|
+
/**
|
|
227
|
+
* `adopted`: the served document was hydrated, and each served view reported
|
|
228
|
+
* its own {@link AdoptOutcome}. `cold`: the container was emptied and the
|
|
229
|
+
* template rendered into it.
|
|
230
|
+
*/
|
|
231
|
+
readonly outcome: BootstrapOutcome;
|
|
232
|
+
/** How the boot compares with the document's hydration signature; see {@link BootstrapSignature}. */
|
|
233
|
+
readonly signature: BootstrapSignature;
|
|
234
|
+
/**
|
|
235
|
+
* The boot transition's `Rejection`, or what the root `hydrate()` threw;
|
|
236
|
+
* present only on a cold boot that one of them caused.
|
|
237
|
+
*/
|
|
238
|
+
readonly error?: unknown;
|
|
239
|
+
}
|
|
240
|
+
/** {@link bootstrap}'s options: {@link HydrateRootOptions}, plus the boot transition's seed. */
|
|
241
|
+
export interface BootstrapOptions extends HydrateRootOptions {
|
|
242
|
+
/**
|
|
243
|
+
* Resolved values the document was drawn with, handed to `seed` from
|
|
244
|
+
* `ui-router-server/ssr/client` before the router starts, so the boot
|
|
245
|
+
* transition adopts them in place of running their resolve functions.
|
|
246
|
+
*/
|
|
247
|
+
readonly payload?: ResolvePayload;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Boots `router` into the page `container` holds, and resolves once that page
|
|
251
|
+
* is live.
|
|
252
|
+
*
|
|
253
|
+
* It owns the whole client boot. `options.payload`, when given, seeds the boot
|
|
254
|
+
* transition first. The container's {@link readHydrationSignature | signature}
|
|
255
|
+
* is read before anything else touches the document; a container {@link
|
|
256
|
+
* hydrateRoot} would not adopt — no signature, another release line, stripped
|
|
257
|
+
* markers — is emptied and `value` rendered into it at once, and the router
|
|
258
|
+
* then starts. Otherwise the router starts, the call waits for the boot
|
|
259
|
+
* transition to land, following redirects to the one that succeeds, and then
|
|
260
|
+
* hydrates the container with `value`.
|
|
261
|
+
*
|
|
262
|
+
* The boot decides once what the page does:
|
|
263
|
+
*
|
|
264
|
+
* - The boot lands where the signature says the document was drawn: every
|
|
265
|
+
* served view adopts, and a view that still mismatches warns in development,
|
|
266
|
+
* since that is a template the two halves render differently.
|
|
267
|
+
* - The boot lands elsewhere — a static host serving one document for a
|
|
268
|
+
* family of urls, or a redirect: the views that match adopt, and the views
|
|
269
|
+
* that differ render cold without a warning of their own. Once the page is
|
|
270
|
+
* live, one development warning names both states and how many views
|
|
271
|
+
* rendered cold, when any did.
|
|
272
|
+
* - The boot fails, or the url starts no transition: the container is emptied
|
|
273
|
+
* and `value` rendered cold. The root `hydrate()` throwing, as over a
|
|
274
|
+
* mutated document, does the same. The call resolves rather than rejects.
|
|
275
|
+
*
|
|
276
|
+
* Every served view still reports its own {@link AdoptOutcome}, as a {@link
|
|
277
|
+
* UiViewAdoptEvent} and to `options.onAdopt`. The call waits for each awake
|
|
278
|
+
* `<ui-view>` to finish updating, nested views included, then releases the
|
|
279
|
+
* adopter `hydrateRoot()` provided; a view the app detached keeps its pin.
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* ```ts
|
|
283
|
+
* import { bootstrap } from 'lit-ui-router-ssr/client';
|
|
284
|
+
*
|
|
285
|
+
* const { outcome } = await bootstrap(router, root, page(router));
|
|
286
|
+
* ```
|
|
287
|
+
*
|
|
288
|
+
* @param router - the client router, its states registered and not yet started
|
|
289
|
+
* @param container - the element the server's markup was written into, or an empty one
|
|
290
|
+
* @param value - the same template the server rendered, with every `<ui-view>` hole empty
|
|
291
|
+
* @param options - lit render options, `onAdopt`, and the boot transition's `payload`
|
|
292
|
+
* @returns what the boot came to, once every awake view has updated
|
|
293
|
+
* @throws what `router.start()` throws, as on a router already started
|
|
294
|
+
* @throws the `TypeError` `seed` throws on a payload with no `resolves`, before the router starts
|
|
295
|
+
*/
|
|
296
|
+
export declare function bootstrap(router: UIRouterLit, container: HTMLElement, value: unknown, options?: BootstrapOptions): Promise<BootstrapResult>;
|
|
175
297
|
//# sourceMappingURL=client.d.ts.map
|
package/dist/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","mappings":"
|
|
1
|
+
{"version":3,"file":"client.d.ts","mappings":"AAQA,SAAS,mBAAmB;AAK5B,cAAyB,qBAAqB;AAM9C,cAAc,mBAAmB;AAEjC,cAAc,sBAAsB;AAOpC,cAAc,0BAA0B;AAExC,SACE,yBACK,oBACA,yBACA,6BACA;AAEP,SACE,wBACK,mBACA,yBACL,iBACA,wBACK;AAEP,SACE,wBACK,mCACA,+BACA,6BACA;AAEP,cAAc,0BAA0B;;;;;;;;;;AAcxC,YAAY,eAAe,YAAY,cAAc;;;;;AAMrD,OAAO,cAAM,sBAAuB;;;;AAKpC,iBAAiB,kBAAkB;;UAExB,SAAS;;UAET;AACX;;;;;AAMA,YAAY,mBAAmB,YAAY;;;;;;AAO3C,OAAO,cAAM,wBAAyB;;AAGtC,YAAY,qBAAqB,YAAY;;;;AAK7C,YAAY,iBACV,MAAM,SACN,SAAS,cAET;;;;;AAOF,iBAAiB,2BAA2B,cAAc;;;;;;CAMxD,UAAU;AACZ;eAEe;WACH,oBAAoB;;EAE5B,iBAAiB;;EAEjB,mBAAmB;CACrB;AACF;;;;;;;;;;;;;;;;;;;;;AAgEA,OAAO,cAAM,mBAAmB;;;;;;;;;;;;;;;AAgBhC,OAAO,cAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuY/B,OAAO,iBAAS,uBACd,WAAW,aACV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+IH,OAAO,iBAAS,YACd,WAAW,aAEX,gBACA,UAAS,qBACR;;AAsCH,YAAY,mBAAmB,YAAY;;;;;;;;;;;;;;;;AAiB3C,YAAY,qBAAqB,YAAY,cAAc;;AAG3D,iBAAiB,gBAAgB;;;;;;UAMtB,SAAS;;UAET,WAAW;;;;;UAKX;AACX;;AAGA,iBAAiB,yBAAyB,mBAAmB;;;;;;UAMlD,UAAU;AACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0JA,OAAO,iBAAe,UACpB,QAAQ,aACR,WAAW,aAEX,gBACA,UAAS,mBACR,QAAQ","names":[],"ignoreList":[],"sources":["../src/client.ts"]}
|