@beatzball/create-litro 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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

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/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

@@ -14,6 +14,7 @@
   },
   "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",

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/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;

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

@@ -1,18 +1,18 @@
 import { LitElement, html, css } from 'lit';
 import { customElement } from 'lit/decorators.js';
-import type { SlTabItem } from './sl-tab-item.js';
+import type { LitroTabItem } from './litro-tab-item.js';
 
 /**
- * <sl-tabs>
- *   <sl-tab-item label="First">Content A</sl-tab-item>
- *   <sl-tab-item label="Second">Content B</sl-tab-item>
- * </sl-tabs>
+ * <litro-tabs>
+ *   <litro-tab-item label="First">Content A</litro-tab-item>
+ *   <litro-tab-item label="Second">Content B</litro-tab-item>
+ * </litro-tabs>
  *
- * Reads slotted <sl-tab-item> elements via the slotchange event.
+ * Reads slotted <litro-tab-item> elements via the slotchange event.
  * Renders a tab bar in Shadow DOM; clicking selects the tab.
  */
-@customElement('sl-tabs')
-export class SlTabs extends LitElement {
+@customElement('litro-tabs')
+export class LitroTabs extends LitElement {
   static override properties = {
     _labels: { type: Array, state: true },
     _selectedIndex: { type: Number, state: true },
@@ -64,11 +64,11 @@ export class SlTabs extends LitElement {
   _labels: string[] = [];
   _selectedIndex = 0;
 
-  private _items(): SlTabItem[] {
+  private _items(): LitroTabItem[] {
     const slot = this.shadowRoot?.querySelector('slot');
     if (!slot) return [];
     return slot.assignedElements().filter(
-      (el): el is SlTabItem => el.tagName.toLowerCase() === 'sl-tab-item',
+      (el): el is LitroTabItem => el.tagName.toLowerCase() === 'litro-tab-item',
     );
   }
 
@@ -78,7 +78,7 @@ export class SlTabs extends LitElement {
     this._selectIndex(this._selectedIndex < items.length ? this._selectedIndex : 0, items);
   }
 
-  private _selectIndex(index: number, items?: SlTabItem[]) {
+  private _selectIndex(index: number, items?: LitroTabItem[]) {
     const all = items ?? this._items();
     this._selectedIndex = index;
     all.forEach((item, i) => {
@@ -105,4 +105,4 @@ export class SlTabs extends LitElement {
   }
 }
 
-export default SlTabs;
+export default LitroTabs;

package/dist/recipes/starlight/template/src/components/starlight-header.ts

@@ -22,12 +22,12 @@ export class StarlightHeader extends LitElement {
   static override styles = css`
     :host {
       display: block;
-    }
-
-    header {
       position: sticky;
       top: 0;
       z-index: 100;
+    }
+
+    header {
       height: var(--sl-nav-height, 3.5rem);
       background-color: var(--sl-color-bg-nav, #fff);
       border-bottom: 1px solid var(--sl-color-border, #e8e8e8);

package/dist/recipes/starlight/template/src/components/starlight-page.ts

@@ -86,8 +86,12 @@ export class StarlightPage extends LitElement {
 
     .toc-wrap {
       grid-area: toc;
-      padding: var(--sl-content-pad-y, 2rem) 0 var(--sl-content-pad-y, 2rem) var(--sl-content-pad-x, 1.5rem);
       border-left: 1px solid var(--sl-color-border, #e8e8e8);
+      position: sticky;
+      top: var(--sl-nav-height, 3.5rem);
+      height: calc(100vh - var(--sl-nav-height, 3.5rem));
+      overflow-y: auto;
+      padding: var(--sl-content-pad-y, 2rem) 0 var(--sl-content-pad-y, 2rem) var(--sl-content-pad-x, 1.5rem);
     }
 
     .page-title {

package/dist/recipes/starlight/template/src/route-meta.ts

@@ -8,9 +8,11 @@
  *      from localStorage, preventing a flash of the wrong theme on reload.
  */
 export const starlightHead = [
+  '<link rel="stylesheet" href="/shoelace/themes/light.css" />',
   '<link rel="stylesheet" href="/styles/starlight.css" />',
   '<script>(function(){',
-  'var t=localStorage.getItem("sl-theme")||"light";',
+  'var s=localStorage.getItem("sl-theme");',
+  'var t=s||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light");',
   'document.documentElement.setAttribute("data-theme",t);',
   '})();</script>',
 ].join('');

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

@@ -3,7 +3,7 @@ import litroContentPlugin from '@beatzball/litro/vite';
 
 export default defineConfig({
   plugins: [litroContentPlugin()],
-  base: '/_litro/',
+  base: process.env.LITRO_BASE_PATH ? `${process.env.LITRO_BASE_PATH}/_litro/` : '/_litro/',
   resolve: {
     conditions: ['source', 'browser', 'module', 'import', 'default'],
   },

package/dist/src/scaffold.test.js

@@ -248,12 +248,12 @@ describe('scaffold', () => {
             expect(existsSync(join(targetDir, 'src/components/starlight-header.ts'))).toBe(true);
             expect(existsSync(join(targetDir, 'src/components/starlight-sidebar.ts'))).toBe(true);
             expect(existsSync(join(targetDir, 'src/components/starlight-toc.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-card.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-card-grid.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-badge.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-aside.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-tabs.ts'))).toBe(true);
-            expect(existsSync(join(targetDir, 'src/components/sl-tab-item.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-card.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-card-grid.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-badge.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-aside.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-tabs.ts'))).toBe(true);
+            expect(existsSync(join(targetDir, 'src/components/litro-tab-item.ts'))).toBe(true);
             // Content
             expect(existsSync(join(targetDir, 'content/docs/.11tydata.json'))).toBe(true);
             expect(existsSync(join(targetDir, 'content/docs/getting-started.md'))).toBe(true);