@beatzball/create-litro 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # create-litro
 
+## 0.3.0
+
+### Minor Changes
+
+- 2456382: Add official documentation site and starlight recipe improvements
+
+  **`@beatzball/litro`**
+
+  - Add `LITRO_BASE_PATH` env var support in `create-page-handler.ts` — prefixes the `/_litro/app.js` script URL for sub-path deployments (e.g. GitHub Pages project sites at `owner.github.io/repo/`)
+  - Fix Lit hydration mismatch on SSR'd pages: `LitroPage.connectedCallback()` now peeks at the `__litro_data__` script tag to set `serverData` before Lit's first render, without consuming the tag
+  - Fix layout shift on navigation: `LitroOutlet.firstUpdated()` no longer eagerly clears SSR children — the router's atomic swap handles it
+
+  **`@beatzball/litro-router`**
+
+  - Atomic DOM swap in `_resolve()`: new element is appended hidden alongside old SSR content, waits for `updateComplete` + `requestAnimationFrame`, then old content is removed and new element revealed — eliminates blank flash and layout shift during navigation
+  - `_lastPathname` guard prevents re-render on hash-only `popstate` events (TOC / fragment link clicks)
+
+  **`@beatzball/create-litro`**
+
+  - Starlight recipe: rename `sl-card`, `sl-card-grid`, `sl-badge`, `sl-tabs`, `sl-tab-item`, `sl-aside` → `litro-card`, `litro-card-grid`, `litro-badge`, `litro-tabs`, `litro-tab-item`, `litro-aside` to avoid collision with Shoelace's registered custom element names
+  - Starlight recipe: integrate Shoelace (`@shoelace-style/shoelace`) — tree-shaken component imports in `app.ts`, icon assets at `/shoelace/assets/`, theme CSS at `/shoelace/themes/`; `sl-button` and `sl-icon-button` now available in all scaffolded starlight sites
+  - Starlight recipe: `litro-card` improvements — equal-height cards via flex column, icon + title rendered inline side-by-side, new `iconSrc` prop for image-based icons
+  - Starlight recipe: sticky header via `:host { position: sticky }` (works correctly across shadow DOM boundary); sticky TOC matching sidebar behaviour
+  - Starlight recipe: theme script falls back to `prefers-color-scheme` when no localStorage preference is set
+  - Add `docs/` workspace (`@beatzball/litro-docs`) — official Litro documentation site built on the starlight recipe, deployed to GitHub Pages via `.github/workflows/docs.yml`
+
+## 0.2.1
+
+### Patch Changes
+
+- 338e2c7: Add Playwright e2e setup to all recipe templates. Each scaffolded project now includes `playwright.config.ts` and `e2e/index.spec.ts` with 3 starter tests, and `@playwright/test` in `devDependencies`.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/recipes/11ty-blog/template/e2e/index.spec.ts

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+test('home renders page-home component', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('page-home');
+  await expect(page.locator('page-home')).toBeVisible();
+});
+
+test('blog index renders', async ({ page }) => {
+  await page.goto('/blog');
+  await page.waitForSelector('page-blog');
+  await expect(page.locator('page-blog')).toBeVisible();
+});
+
+test('blog post renders with h1', async ({ page }) => {
+  await page.goto('/blog/hello-world');
+  await page.waitForSelector('page-blog-slug');
+  await expect(page.locator('page-blog-slug h1')).toBeVisible();
+});

package/dist/recipes/11ty-blog/template/package.json

@@ -9,7 +9,8 @@
     "dev": "litro dev",
     "build": "litro build",
     "preview": "litro preview",
-    "generate": "litro generate"
+    "generate": "litro generate",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@beatzball/litro": "latest",
@@ -21,6 +22,7 @@
   "devDependencies": {
     "nitropack": "^2.13.1",
     "vite": "^5.4.11",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "@playwright/test": "^1.48.0"
   }
 }

package/dist/recipes/11ty-blog/template/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: false,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3030',
+    trace: 'on-first-retry',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+  webServer: {
+    command: 'pnpm dev',
+    url: 'http://localhost:3030',
+    reuseExistingServer: !process.env.CI,
+    timeout: 60000,
+  },
+});

package/dist/recipes/fullstack/template/e2e/index.spec.ts

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+test('SSR renders without JavaScript (DSD in source)', async ({ request }) => {
+  const response = await request.get('/');
+  const body = await response.text();
+  expect(body).toContain('shadowrootmode');
+});
+
+test('__litro_data__ is injected into HTML', async ({ request }) => {
+  const response = await request.get('/');
+  const body = await response.text();
+  expect(body).toContain('__litro_data__');
+});
+
+test('page-home is visible after hydration', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('page-home');
+  await expect(page.locator('page-home')).toBeVisible();
+});

package/dist/recipes/fullstack/template/package.json

@@ -9,7 +9,8 @@
     "dev": "litro dev",
     "build": "litro build",
     "preview": "litro preview",
-    "generate": "litro generate"
+    "generate": "litro generate",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@beatzball/litro": "latest",
@@ -21,6 +22,7 @@
   "devDependencies": {
     "nitropack": "^2.13.1",
     "vite": "^5.4.11",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "@playwright/test": "^1.48.0"
   }
 }

package/dist/recipes/fullstack/template/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: false,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3030',
+    trace: 'on-first-retry',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+  webServer: {
+    command: 'pnpm dev',
+    url: 'http://localhost:3030',
+    reuseExistingServer: !process.env.CI,
+    timeout: 60000,
+  },
+});

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

@@ -5,6 +5,20 @@ import '@lit-labs/ssr-client/lit-element-hydrate-support.js';
 import '@beatzball/litro/runtime/LitroOutlet.js';
 import '@beatzball/litro/runtime/LitroLink.js';
 
+// Shoelace components (tree-shaken — only what the template uses)
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/icon/icon.js';
+import '@shoelace-style/shoelace/dist/components/badge/badge.js';
+import '@shoelace-style/shoelace/dist/components/copy-button/copy-button.js';
+import '@shoelace-style/shoelace/dist/components/details/details.js';
+import '@shoelace-style/shoelace/dist/components/tab-group/tab-group.js';
+import '@shoelace-style/shoelace/dist/components/tab/tab.js';
+import '@shoelace-style/shoelace/dist/components/tab-panel/tab-panel.js';
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
+
+// Point Shoelace's icon loader at the served assets directory
+setBasePath('/shoelace/');
+
 // Routes generated by the page scanner before each vite build.
 import { routes } from './routes.generated.js';
 

package/dist/recipes/starlight/template/e2e/index.spec.ts

@@ -0,0 +1,32 @@
+import { test, expect } from '@playwright/test';
+
+const PRERENDERED_ROUTES = [
+  '/',
+  '/docs/getting-started',
+  '/docs/installation',
+  '/docs/configuration',
+  '/docs/guides-first-page',
+  '/docs/guides-deploying',
+  '/blog',
+  '/blog/welcome',
+  '/blog/release-notes',
+];
+
+test('home renders page-home component', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('page-home');
+  await expect(page.locator('page-home')).toBeVisible();
+});
+
+test('/docs/getting-started renders', async ({ page }) => {
+  await page.goto('/docs/getting-started');
+  await page.waitForSelector('page-docs-slug');
+  await expect(page.locator('page-docs-slug')).toBeVisible();
+});
+
+test('all prerendered routes return 200', async ({ request }) => {
+  for (const route of PRERENDERED_ROUTES) {
+    const response = await request.get(route);
+    expect(response.status(), `Expected 200 for ${route}`).toBe(200);
+  }
+});

package/dist/recipes/starlight/template/nitro.config.ts

@@ -15,6 +15,8 @@ export default defineNitroConfig({
     { dir: '../dist/client', baseURL: '/_litro/', maxAge: 31536000 },
     { dir: '../public',      baseURL: '/',        maxAge: 0 },
     { dir: '../content',     baseURL: '/content/', maxAge: 86400 },
+    { dir: '../node_modules/@shoelace-style/shoelace/dist/assets', baseURL: '/shoelace/assets/', maxAge: 604800 },
+    { dir: '../node_modules/@shoelace-style/shoelace/dist/themes', baseURL: '/shoelace/themes/', maxAge: 604800 },
   ],
 
   externals: { inline: ['@lit-labs/ssr', '@lit-labs/ssr-client'] },

package/dist/recipes/starlight/template/package.json

@@ -9,10 +9,12 @@
     "dev": "litro dev",
     "build": "litro build",
     "preview": "litro preview",
-    "generate": "litro generate"
+    "generate": "litro generate",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@beatzball/litro": "latest",
+    "@shoelace-style/shoelace": "^2.19.0",
     "lit": "^3.2.1",
     "@lit-labs/ssr": "^3.3.0",
     "@lit-labs/ssr-client": "^1.1.7",
@@ -21,6 +23,7 @@
   "devDependencies": {
     "nitropack": "^2.13.1",
     "vite": "^5.4.11",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "@playwright/test": "^1.48.0"
   }
 }

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

@@ -8,8 +8,8 @@ import { starlightHead } from '../src/route-meta.js';
 
 // Register components used in render()
 import '../src/components/starlight-header.js';
-import '../src/components/sl-card.js';
-import '../src/components/sl-card-grid.js';
+import '../src/components/litro-card.js';
+import '../src/components/litro-card-grid.js';
 
 export interface SplashData {
   siteTitle: string;
@@ -116,15 +116,15 @@ export class SplashPage extends LitroPage {
           </section>
 
           <section>
-            <sl-card-grid>
+            <litro-card-grid>
               ${features.map(f => html`
-                <sl-card
+                <litro-card
                   icon="${f.icon ?? ''}"
                   title="${f.title}"
                   description="${f.description}"
-                ></sl-card>
+                ></litro-card>
               `)}
-            </sl-card-grid>
+            </litro-card-grid>
           </section>
         </main>
       </div>

package/dist/recipes/starlight/template/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: false,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3030',
+    trace: 'on-first-retry',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+  webServer: {
+    command: 'pnpm dev',
+    url: 'http://localhost:3030',
+    reuseExistingServer: !process.env.CI,
+    timeout: 60000,
+  },
+});

package/dist/recipes/starlight/template/public/styles/starlight.css

@@ -1,3 +1,23 @@
+/* FOUCE - https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/ */
+:not(:defined) {
+  visibility: hidden;
+}
+
+/* Shoelace theme bridge — map sl-color-primary-* to Litro's accent palette */
+:root {
+  --sl-color-primary-50: #f5f3ff;
+  --sl-color-primary-100: #ede9fe;
+  --sl-color-primary-200: #ddd6fe;
+  --sl-color-primary-300: #c4b5fd;
+  --sl-color-primary-400: #a78bfa;
+  --sl-color-primary-500: #8b5cf6;
+  --sl-color-primary-600: #7c3aed;
+  --sl-color-primary-700: #6d28d9;
+  --sl-color-primary-800: #5b21b6;
+  --sl-color-primary-900: #4c1d95;
+  --sl-color-primary-950: #2e1065;
+}
+
 /* Starlight design tokens — light mode defaults */
 :root {
   --sl-color-white: #fff;
@@ -30,14 +50,14 @@
   --sl-font-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
   --sl-font-mono: ui-monospace, "Cascadia Code", "Fira Code", monospace;
 
-  --sl-text-xs:   0.75rem;
-  --sl-text-sm:   0.875rem;
+  --sl-text-xs: 0.75rem;
+  --sl-text-sm: 0.875rem;
   --sl-text-base: 1rem;
-  --sl-text-lg:   1.125rem;
-  --sl-text-xl:   1.25rem;
-  --sl-text-2xl:  1.5rem;
-  --sl-text-3xl:  1.875rem;
-  --sl-text-4xl:  2.25rem;
+  --sl-text-lg: 1.125rem;
+  --sl-text-xl: 1.25rem;
+  --sl-text-2xl: 1.5rem;
+  --sl-text-3xl: 1.875rem;
+  --sl-text-4xl: 2.25rem;
 
   --sl-nav-height: 3.5rem;
   --sl-sidebar-width: 16rem;
@@ -54,7 +74,7 @@
 }
 
 /* Dark mode overrides */
-[data-theme='dark'] {
+[data-theme="dark"] {
   --sl-color-text: #f0f0f0;
   --sl-color-bg: #17181c;
   --sl-color-bg-sidebar: #1e1f24;
@@ -80,7 +100,9 @@
 }
 
 /* Base reset */
-*, *::before, *::after {
+*,
+*::before,
+*::after {
   box-sizing: border-box;
 }
 
@@ -99,7 +121,12 @@ body {
 }
 
 /* Typography reset for content areas */
-h1, h2, h3, h4, h5, h6 {
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
   margin-top: 1.5em;
   margin-bottom: 0.5em;
   font-weight: 600;
@@ -107,10 +134,20 @@ h1, h2, h3, h4, h5, h6 {
   color: var(--sl-color-text);
 }
 
-h1 { font-size: var(--sl-text-4xl); }
-h2 { font-size: var(--sl-text-2xl); border-bottom: 1px solid var(--sl-color-border); padding-bottom: 0.25em; }
-h3 { font-size: var(--sl-text-xl); }
-h4 { font-size: var(--sl-text-lg); }
+h1 {
+  font-size: var(--sl-text-4xl);
+}
+h2 {
+  font-size: var(--sl-text-2xl);
+  border-bottom: 1px solid var(--sl-color-border);
+  padding-bottom: 0.25em;
+}
+h3 {
+  font-size: var(--sl-text-xl);
+}
+h4 {
+  font-size: var(--sl-text-lg);
+}
 
 p {
   margin-top: 0;
@@ -147,7 +184,7 @@ pre {
   line-height: 1.6;
 }
 
-[data-theme='dark'] pre {
+[data-theme="dark"] pre {
   background-color: #0d0e11;
   color: #e2e4e9;
 }
@@ -166,7 +203,8 @@ table {
   font-size: var(--sl-text-sm);
 }
 
-th, td {
+th,
+td {
   border: 1px solid var(--sl-color-border);
   padding: 0.5rem 0.75rem;
   text-align: left;
@@ -177,11 +215,12 @@ th {
   font-weight: 600;
 }
 
-[data-theme='dark'] th {
+[data-theme="dark"] th {
   background-color: var(--sl-color-gray-1);
 }
 
-ul, ol {
+ul,
+ol {
   padding-left: 1.5rem;
   margin: 0 0 1rem;
 }
@@ -199,7 +238,7 @@ blockquote {
   border-radius: 0 var(--sl-border-radius) var(--sl-border-radius) 0;
 }
 
-[data-theme='dark'] blockquote {
+[data-theme="dark"] blockquote {
   background-color: var(--sl-color-accent-low);
 }
 

package/dist/recipes/starlight/template/src/components/{sl-aside.ts → litro-aside.ts}

@@ -18,13 +18,13 @@ const LABELS: Record<AsideType, string> = {
 };
 
 /**
- * <sl-aside type="tip" title="Custom Title">
+ * <litro-aside type="tip" title="Custom Title">
  *   Callout box with an icon and colored left border.
  *   Slot content is the body.
- * </sl-aside>
+ * </litro-aside>
  */
-@customElement('sl-aside')
-export class SlAside extends LitElement {
+@customElement('litro-aside')
+export class LitroAside extends LitElement {
   static override properties = {
     type: { type: String },
     title: { type: String },
@@ -88,4 +88,4 @@ export class SlAside extends LitElement {
   }
 }
 
-export default SlAside;
+export default LitroAside;

package/{recipes/starlight/template/src/components/sl-badge.ts → dist/recipes/starlight/template/src/components/litro-badge.ts}

@@ -4,12 +4,12 @@ import { customElement } from 'lit/decorators.js';
 type BadgeVariant = 'note' | 'tip' | 'caution' | 'danger' | 'default';
 
 /**
- * <sl-badge variant="tip" text="New">
+ * <litro-badge variant="tip" text="New">
  *   Inline color-coded chip. Use `text` attribute or slot content.
- * </sl-badge>
+ * </litro-badge>
  */
-@customElement('sl-badge')
-export class SlBadge extends LitElement {
+@customElement('litro-badge')
+export class LitroBadge extends LitElement {
   static override properties = {
     variant: { type: String },
     text: { type: String },
@@ -73,4 +73,4 @@ export class SlBadge extends LitElement {
   }
 }
 
-export default SlBadge;
+export default LitroBadge;

package/{recipes/starlight/template/src/components/sl-card-grid.ts → dist/recipes/starlight/template/src/components/litro-card-grid.ts}

@@ -2,13 +2,13 @@ import { LitElement, html, css } from 'lit';
 import { customElement } from 'lit/decorators.js';
 
 /**
- * <sl-card-grid>
- *   Responsive auto-fit grid for <sl-card> elements.
- *   Single slot — place <sl-card> elements directly inside.
- * </sl-card-grid>
+ * <litro-card-grid>
+ *   Responsive auto-fit grid for <litro-card> elements.
+ *   Single slot — place <litro-card> elements directly inside.
+ * </litro-card-grid>
  */
-@customElement('sl-card-grid')
-export class SlCardGrid extends LitElement {
+@customElement('litro-card-grid')
+export class LitroCardGrid extends LitElement {
   static override styles = css`
     :host {
       display: block;
@@ -31,4 +31,4 @@ export class SlCardGrid extends LitElement {
   }
 }
 
-export default SlCardGrid;
+export default LitroCardGrid;

package/{recipes/starlight/template/src/components/sl-card.ts → dist/recipes/starlight/template/src/components/litro-card.ts}

@@ -2,28 +2,32 @@ import { LitElement, html, css } from 'lit';
 import { customElement } from 'lit/decorators.js';
 
 /**
- * <sl-card title="Feature" description="Short desc" href="/docs/feature">
+ * <litro-card title="Feature" description="Short desc" href="/docs/feature">
  *   Renders as an <a> when `href` is set, otherwise a <div>.
  *   Rotating accent color per nth-card via CSS counter.
- * </sl-card>
+ * </litro-card>
  */
-@customElement('sl-card')
-export class SlCard extends LitElement {
+@customElement('litro-card')
+export class LitroCard extends LitElement {
   static override properties = {
     title: { type: String },
     description: { type: String },
     icon: { type: String },
+    iconSrc: { type: String },
     href: { type: String },
   };
 
   static override styles = css`
     :host {
-      display: block;
+      display: flex;
+      flex-direction: column;
       counter-increment: card;
     }
 
     .card {
-      display: block;
+      display: flex;
+      flex-direction: column;
+      flex: 1;
       padding: 1.25rem 1.5rem;
       border: 1px solid var(--sl-color-border, #e8e8e8);
       border-radius: var(--sl-border-radius, 0.375rem);
@@ -45,16 +49,31 @@ export class SlCard extends LitElement {
       transform: translateY(-2px);
     }
 
+    .card-header {
+      display: flex;
+      align-items: center;
+      gap: 0.6rem;
+      margin-bottom: 0.4rem;
+    }
+
     .card-icon {
-      font-size: 1.75rem;
-      margin-bottom: 0.5rem;
+      font-size: 1.5rem;
+      flex-shrink: 0;
+      line-height: 1;
+    }
+
+    .card-icon-img {
+      width: 1.5rem;
+      height: 1.5rem;
+      object-fit: contain;
+      flex-shrink: 0;
     }
 
     .card-title {
       font-size: var(--sl-text-lg, 1.125rem);
       font-weight: 600;
       color: var(--sl-color-text, #23262f);
-      margin: 0 0 0.4rem;
+      margin: 0;
     }
 
     .card-desc {
@@ -72,12 +91,17 @@ export class SlCard extends LitElement {
   title = '';
   description = '';
   icon = '';
+  iconSrc = '';
   href = '';
 
   override render() {
     const inner = html`
-      ${this.icon ? html`<div class="card-icon">${this.icon}</div>` : ''}
-      <p class="card-title">${this.title}</p>
+      <div class="card-header">
+        ${this.iconSrc
+          ? html`<img class="card-icon-img" src="${this.iconSrc}" alt="" aria-hidden="true" />`
+          : this.icon ? html`<span class="card-icon">${this.icon}</span>` : ''}
+        <p class="card-title">${this.title}</p>
+      </div>
       ${this.description ? html`<p class="card-desc">${this.description}</p>` : ''}
       <div class="card-slot"><slot></slot></div>
     `;
@@ -88,4 +112,4 @@ export class SlCard extends LitElement {
   }
 }
 
-export default SlCard;
+export default LitroCard;

package/dist/recipes/starlight/template/src/components/{sl-tab-item.ts → litro-tab-item.ts}

@@ -2,13 +2,13 @@ import { LitElement, html, css } from 'lit';
 import { customElement } from 'lit/decorators.js';
 
 /**
- * <sl-tab-item label="Tab Label">
- *   A single tab panel managed by a parent <sl-tabs> element.
+ * <litro-tab-item label="Tab Label">
+ *   A single tab panel managed by a parent <litro-tabs> element.
  *   Hidden automatically when not selected.
- * </sl-tab-item>
+ * </litro-tab-item>
  */
-@customElement('sl-tab-item')
-export class SlTabItem extends LitElement {
+@customElement('litro-tab-item')
+export class LitroTabItem extends LitElement {
   static override properties = {
     label: { type: String },
     selected: { type: Boolean, reflect: true },
@@ -32,4 +32,4 @@ export class SlTabItem extends LitElement {
   }
 }
 
-export default SlTabItem;
+export default LitroTabItem;