@beatzball/create-litro 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # create-litro
 
+## 0.1.4
+
+### Patch Changes
+
+- 76d3bc7: fix: client-side navigation links do not work on first load
+
+  `<litro-link>` clicks were silently no-ops in scaffolded apps because of
+  three compounding bugs.
+
+  ***
+
+  **Bug 1 — Empty route table on init** (`LitroOutlet`, `app.ts`)
+
+  `app.ts` set `outlet.routes` inside a `DOMContentLoaded` callback (a
+  macrotask). By that point Lit's first-update microtask had already fired,
+  so `firstUpdated()` ran with `routes = []` and the router was initialised
+  with no routes.
+
+  _Fix — `LitroOutlet`_: Replace `@property({ type: Array }) routes` with a
+  plain getter/setter. The setter calls `router.setRoutes()` directly when
+  the router is already initialised, without going through Lit's render cycle
+  (which would crash with "ChildPart has no parentNode" because
+  `firstUpdated()` removes Lit's internal marker nodes to give the router
+  ownership of the outlet's subtree).
+
+  _Fix — `app.ts`_ (fullstack recipe template + playground): Set
+  `outlet.routes` synchronously after imports rather than inside a
+  `DOMContentLoaded` callback. Module scripts are deferred by the browser;
+  by the time they execute the DOM is fully parsed and `<litro-outlet>` is
+  present.
+
+  ***
+
+  **Bug 2 — Click handler never attached on SSR'd pages** (`LitroLink`)
+
+  `@lit-labs/ssr` adds `defer-hydration` to custom elements inside shadow
+  DOM. `@lit-labs/ssr-client` patches `LitElement.prototype.connectedCallback`
+  to block Lit's update cycle when this attribute is present. A `@click`
+  binding on the shadow `<a>` is a Lit binding — it is never attached until
+  `defer-hydration` is removed, which only happens when the parent component
+  hydrates. For page components that are never hydrated client-side (because
+  the router replaces the SSR content before they load), `<litro-link>`
+  elements inside them never receive a click handler.
+
+  This is why the playground appeared to work: its home page has no
+  `<litro-link>` elements. The fullstack generator template does, so clicks
+  on the SSR'd page were silently ignored.
+
+  _Fix_: Move the click handler from a `@click` binding on the shadow `<a>`
+  to the HOST element via `addEventListener('click', ...)` registered in
+  `connectedCallback()` (before `super.connectedCallback()`). The host
+  listener runs in `LitroLink`'s own `connectedCallback` override, which
+  executes before the `@lit-labs/ssr-client` patch checks for
+  `defer-hydration`. This ensures the handler is active immediately after the
+  element connects to the DOM, even for SSR'd elements on first load.
+
+  The shadow `<a>` is kept without a `@click` binding — it exists for
+  progressive enhancement (no-JS navigation) and accessibility (cursor,
+  focus, keyboard navigation).
+
+  ***
+
+  **Bug 3 — `_resolve()` race condition** (`LitroRouter`)
+
+  `setRoutes()` calls `_resolve()` immediately for the current URL. If the
+  user clicks a link before that initial `_resolve()` completes (e.g. while
+  the page action's dynamic import is in flight), a second `_resolve()` call
+  starts concurrently. If the first call (for `/`) completes after the second
+  (for `/blog`), it overwrites the blog page with the home page.
+
+  _Fix_: Add a `_resolveToken` monotonic counter. Each `_resolve()` call
+  captures its own token at the start and checks it after every `await`. If
+  the token has advanced, a newer navigation superseded this one and the call
+  returns without touching the DOM.
+
+  ***
+
+  **Bug 4 — `@property()` decorators silently dropped by esbuild TC39 transform** (`LitroLink`)
+
+  esbuild 0.21+ uses the TC39 Stage 3 decorator transform. In that mode,
+  Lit's `@property()` decorator only handles `accessor` fields; applied to a
+  plain field (`href = ''`) it is silently not applied. As a result `href`,
+  `target`, and `rel` were absent from `observedAttributes`, so
+  `attributeChangedCallback` was never called during element upgrade, leaving
+  `this.href = ''` forever regardless of what the HTML attribute said.
+
+  _Fix_: Replace the three `@property()` field decorators with a
+  `static override properties = { href, target, rel }` declaration. Lit reads
+  this static field at class-finalization time via `finalize()`, which runs
+  before the element is defined in `customElements`, ensuring the properties
+  are correctly registered in `observedAttributes`.
+
+  ***
+
+  Adds a new `LitroOutlet.test.ts` test file (6 tests) covering the
+  synchronous and late-assignment code paths, the setter guard, SSR child
+  clearing, and the `LitroRouter` constructor call.
+
+  Updates `LitroLink.test.ts` (12 tests) to dispatch real `MouseEvent`s on
+  the host element (exercising the `addEventListener` path) rather than
+  calling the private handler directly by name.
+
+  ***
+
+  **Template fix — `@state() declare serverData` incompatible with jiti/SSG**
+
+  The fullstack recipe template used `@state() declare serverData: T | null` to
+  narrow the `serverData: unknown` type inherited from `LitroPage`. The `declare`
+  modifier emits no runtime code, but jiti's oxc-transform (used in SSG mode to
+  load page files) throws "Fields with the 'declare' modifier cannot be
+  initialized here" under TC39 Stage 3 decorator mode.
+
+  _Fix_: Remove `@state() declare serverData` from both page templates. Use a
+  local type cast in `render()` instead: `const data = this.serverData as T | null`.
+  The property is already reactive (declared as `@state() serverData = null` in
+  `LitroPage`). Updated `LitroPage.ts` JSDoc and `DECISIONS.md` to document this
+  pattern and warn against `declare` fields in subclasses.
+
 ## 0.1.3
 
 ### Patch Changes

package/dist/recipes/fullstack/template/app.ts

@@ -10,11 +10,14 @@ import '@beatzball/litro/runtime/LitroLink.js';
 // emptyOutDir does not delete it between builds.
 import { routes } from './routes.generated.js';
 
-document.addEventListener('DOMContentLoaded', () => {
-  const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
-  if (outlet) {
-    outlet.routes = routes;
-  } else {
-    console.warn('[litro] <litro-outlet> not found — router will not start.');
-  }
-});
+// Set routes synchronously. By the time this module-script executes (all
+// module scripts are deferred), the HTML is fully parsed and <litro-outlet>
+// is already in the DOM. Setting outlet.routes here — before Lit's first
+// update microtask fires — ensures firstUpdated() sees the real route table
+// rather than the empty default, so the router starts correctly.
+const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
+if (outlet) {
+  outlet.routes = routes;
+} else {
+  console.warn('[litro] <litro-outlet> not found — router will not start.');
+}

package/dist/recipes/fullstack/template/pages/blog/[slug].ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 import type { LitroLocation } from '@beatzball/litro-router';
@@ -27,8 +27,6 @@ export async function generateRoutes(): Promise<string[]> {
 
 @customElement('page-blog-slug')
 export class BlogPostPage extends LitroPage {
-  @state() declare serverData: PostData | null;
-
   // Called by LitroRouter on client-side navigation to fetch data for the new slug.
   override async fetchData(location: LitroLocation): Promise<PostData> {
     const slug = location.params['slug'] ?? '';
@@ -40,10 +38,11 @@ export class BlogPostPage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as PostData | null;
     return html`
       <article>
-        <h1>${this.serverData?.title ?? 'Loading…'}</h1>
-        <p>${this.serverData?.content ?? ''}</p>
+        <h1>${data?.title ?? 'Loading…'}</h1>
+        <p>${data?.content ?? ''}</p>
         <litro-link href="/blog">← Back to Blog</litro-link>
         &nbsp;|&nbsp;
         <litro-link href="/">← Home</litro-link>

package/dist/recipes/fullstack/template/pages/index.ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 
@@ -18,8 +18,6 @@ export const pageData = definePageData(async (_event) => {
 
 @customElement('page-home')
 export class HomePage extends LitroPage {
-  @state() declare serverData: HomeData | null;
-
   // Called on client-side navigation (not on the initial SSR load).
   override async fetchData() {
     const res = await fetch('/api/hello');
@@ -27,11 +25,12 @@ export class HomePage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as HomeData | null;
     if (this.loading) return html`<p>Loading…</p>`;
     return html`
       <main>
-        <h1>${this.serverData?.message ?? 'Welcome to {{projectName}}'}</h1>
-        <p><small>Rendered at: ${this.serverData?.timestamp ?? '—'}</small></p>
+        <h1>${data?.message ?? 'Welcome to {{projectName}}'}</h1>
+        <p><small>Rendered at: ${data?.timestamp ?? '—'}</small></p>
         <nav>
           <litro-link href="/blog">Go to Blog →</litro-link>
         </nav>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beatzball/create-litro",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Create a new Litro app",
   "license": "Apache-2.0",
   "repository": {

package/recipes/fullstack/template/app.ts

@@ -10,11 +10,14 @@ import '@beatzball/litro/runtime/LitroLink.js';
 // emptyOutDir does not delete it between builds.
 import { routes } from './routes.generated.js';
 
-document.addEventListener('DOMContentLoaded', () => {
-  const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
-  if (outlet) {
-    outlet.routes = routes;
-  } else {
-    console.warn('[litro] <litro-outlet> not found — router will not start.');
-  }
-});
+// Set routes synchronously. By the time this module-script executes (all
+// module scripts are deferred), the HTML is fully parsed and <litro-outlet>
+// is already in the DOM. Setting outlet.routes here — before Lit's first
+// update microtask fires — ensures firstUpdated() sees the real route table
+// rather than the empty default, so the router starts correctly.
+const outlet = document.querySelector('litro-outlet') as (Element & { routes: unknown }) | null;
+if (outlet) {
+  outlet.routes = routes;
+} else {
+  console.warn('[litro] <litro-outlet> not found — router will not start.');
+}

package/recipes/fullstack/template/pages/blog/[slug].ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 import type { LitroLocation } from '@beatzball/litro-router';
@@ -27,8 +27,6 @@ export async function generateRoutes(): Promise<string[]> {
 
 @customElement('page-blog-slug')
 export class BlogPostPage extends LitroPage {
-  @state() declare serverData: PostData | null;
-
   // Called by LitroRouter on client-side navigation to fetch data for the new slug.
   override async fetchData(location: LitroLocation): Promise<PostData> {
     const slug = location.params['slug'] ?? '';
@@ -40,10 +38,11 @@ export class BlogPostPage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as PostData | null;
     return html`
       <article>
-        <h1>${this.serverData?.title ?? 'Loading…'}</h1>
-        <p>${this.serverData?.content ?? ''}</p>
+        <h1>${data?.title ?? 'Loading…'}</h1>
+        <p>${data?.content ?? ''}</p>
         <litro-link href="/blog">← Back to Blog</litro-link>
         &nbsp;|&nbsp;
         <litro-link href="/">← Home</litro-link>

package/recipes/fullstack/template/pages/index.ts

@@ -1,5 +1,5 @@
 import { html } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement } from 'lit/decorators.js';
 import { LitroPage } from '@beatzball/litro/runtime';
 import { definePageData } from '@beatzball/litro';
 
@@ -18,8 +18,6 @@ export const pageData = definePageData(async (_event) => {
 
 @customElement('page-home')
 export class HomePage extends LitroPage {
-  @state() declare serverData: HomeData | null;
-
   // Called on client-side navigation (not on the initial SSR load).
   override async fetchData() {
     const res = await fetch('/api/hello');
@@ -27,11 +25,12 @@ export class HomePage extends LitroPage {
   }
 
   render() {
+    const data = this.serverData as HomeData | null;
     if (this.loading) return html`<p>Loading…</p>`;
     return html`
       <main>
-        <h1>${this.serverData?.message ?? 'Welcome to {{projectName}}'}</h1>
-        <p><small>Rendered at: ${this.serverData?.timestamp ?? '—'}</small></p>
+        <h1>${data?.message ?? 'Welcome to {{projectName}}'}</h1>
+        <p><small>Rendered at: ${data?.timestamp ?? '—'}</small></p>
         <nav>
           <litro-link href="/blog">Go to Blog →</litro-link>
         </nav>