@beatzball/create-litro 0.1.3 → 0.2.0

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

@@ -0,0 +1,168 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { NavItem } from './starlight-header.js';
+import type { SidebarGroup } from './starlight-sidebar.js';
+import type { TocEntry } from '../extract-headings.js';
+
+// Side-effect imports — registers child custom elements
+import './starlight-header.js';
+import './starlight-sidebar.js';
+import './starlight-toc.js';
+
+/**
+ * <starlight-page
+ *   siteTitle="My Docs"
+ *   pageTitle="Getting Started"
+ *   .nav=${nav}
+ *   .sidebar=${sidebar}
+ *   .toc=${toc}
+ *   currentSlug="getting-started"
+ *   currentPath="/docs/getting-started"
+ * >
+ *   <div slot="content">…rendered HTML…</div>
+ * </starlight-page>
+ *
+ * Three-column grid layout: sidebar | content | TOC.
+ * Responsive: single column below 768px, sidebar/TOC collapsed.
+ */
+@customElement('starlight-page')
+export class StarlightPage extends LitElement {
+  static override properties = {
+    siteTitle:   { type: String },
+    pageTitle:   { type: String },
+    nav:         { type: Array },
+    sidebar:     { type: Array },
+    toc:         { type: Array },
+    currentSlug: { type: String },
+    currentPath: { type: String },
+    noSidebar:   { type: Boolean },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    .page-wrap {
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+    }
+
+    .body {
+      display: grid;
+      grid-template-columns: var(--sl-sidebar-width, 16rem) 1fr var(--sl-toc-width, 14rem);
+      grid-template-areas: 'sidebar content toc';
+      flex: 1;
+      max-width: 90rem;
+      margin: 0 auto;
+      width: 100%;
+    }
+
+    .body.no-sidebar {
+      grid-template-columns: 1fr;
+      grid-template-areas: 'content';
+    }
+
+    .sidebar-wrap {
+      grid-area: sidebar;
+      border-right: 1px solid var(--sl-color-border, #e8e8e8);
+      background-color: var(--sl-color-bg-sidebar, #f6f6f6);
+      position: sticky;
+      top: var(--sl-nav-height, 3.5rem);
+      height: calc(100vh - var(--sl-nav-height, 3.5rem));
+      overflow-y: auto;
+    }
+
+    .content-wrap {
+      grid-area: content;
+      padding: var(--sl-content-pad-y, 2rem) var(--sl-content-pad-x, 1.5rem);
+      min-width: 0;
+    }
+
+    .content-inner {
+      max-width: var(--sl-content-width, 48rem);
+    }
+
+    .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);
+    }
+
+    .page-title {
+      font-size: var(--sl-text-4xl, 2.25rem);
+      font-weight: 700;
+      color: var(--sl-color-text, #23262f);
+      margin: 0 0 1.5rem;
+      line-height: 1.15;
+    }
+
+    /* Responsive: hide sidebar and TOC on narrow screens */
+    @media (max-width: 72rem) {
+      .body {
+        grid-template-columns: 1fr var(--sl-toc-width, 14rem);
+        grid-template-areas: 'content toc';
+      }
+
+      .sidebar-wrap {
+        display: none;
+      }
+    }
+
+    @media (max-width: 48rem) {
+      .body {
+        grid-template-columns: 1fr;
+        grid-template-areas: 'content';
+      }
+
+      .toc-wrap {
+        display: none;
+      }
+    }
+  `;
+
+  siteTitle = '';
+  pageTitle = '';
+  nav: NavItem[] = [];
+  sidebar: SidebarGroup[] = [];
+  toc: TocEntry[] = [];
+  currentSlug = '';
+  currentPath = '';
+  noSidebar = false;
+
+  override render() {
+    return html`
+      <div class="page-wrap">
+        <starlight-header
+          siteTitle="${this.siteTitle}"
+          .nav="${this.nav}"
+          currentPath="${this.currentPath}"
+        ></starlight-header>
+        <div class="body${this.noSidebar ? ' no-sidebar' : ''}">
+          ${!this.noSidebar ? html`
+            <aside class="sidebar-wrap">
+              <starlight-sidebar
+                .groups="${this.sidebar}"
+                currentSlug="${this.currentSlug}"
+              ></starlight-sidebar>
+            </aside>
+          ` : ''}
+          <main class="content-wrap">
+            <div class="content-inner">
+              ${this.pageTitle ? html`<h1 class="page-title">${this.pageTitle}</h1>` : ''}
+              <slot name="content"></slot>
+            </div>
+          </main>
+          ${!this.noSidebar ? html`
+            <aside class="toc-wrap">
+              <starlight-toc .entries="${this.toc}"></starlight-toc>
+            </aside>
+          ` : ''}
+        </div>
+      </div>
+    `;
+  }
+}
+
+export default StarlightPage;

package/recipes/starlight/template/src/components/starlight-sidebar.ts

@@ -0,0 +1,125 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+export interface SidebarItem {
+  label: string;
+  slug: string;
+  badge?: { text: string; variant?: string };
+}
+
+export interface SidebarGroup {
+  label: string;
+  items: SidebarItem[];
+}
+
+/**
+ * <starlight-sidebar .groups=${sidebar} currentSlug="getting-started">
+ *   Renders grouped navigation links for the docs sidebar.
+ *   The active item (matching currentSlug) is highlighted with aria-current.
+ */
+@customElement('starlight-sidebar')
+export class StarlightSidebar extends LitElement {
+  static override properties = {
+    groups: { type: Array },
+    currentSlug: { type: String },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    nav {
+      padding: 1rem 0;
+    }
+
+    .group {
+      margin-bottom: 1.5rem;
+    }
+
+    .group-label {
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      color: var(--sl-color-gray-4, #757575);
+      padding: 0 1rem;
+      margin: 0 0 0.5rem;
+    }
+
+    ul {
+      list-style: none;
+      padding: 0;
+      margin: 0;
+    }
+
+    li {
+      margin: 0;
+    }
+
+    a {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0.35rem 1rem;
+      font-size: var(--sl-text-sm, 0.875rem);
+      color: var(--sl-color-gray-5, #4b4b4b);
+      text-decoration: none;
+      border-left: 2px solid transparent;
+      transition: color 0.15s, background-color 0.15s;
+    }
+
+    a:hover {
+      color: var(--sl-color-text, #23262f);
+      background-color: var(--sl-color-gray-2, #e8e8e8);
+    }
+
+    a[aria-current='page'] {
+      color: var(--sl-color-accent, #7c3aed);
+      border-left-color: var(--sl-color-accent, #7c3aed);
+      background-color: var(--sl-color-accent-low, #ede9fe);
+      font-weight: 600;
+    }
+
+    .badge {
+      display: inline-block;
+      padding: 0.1em 0.45em;
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 600;
+      border-radius: 9999px;
+      background-color: var(--sl-color-accent-low, #ede9fe);
+      color: var(--sl-color-accent-high, #5b21b6);
+      margin-left: 0.5rem;
+    }
+  `;
+
+  groups: SidebarGroup[] = [];
+  currentSlug = '';
+
+  override render() {
+    return html`
+      <nav aria-label="Site navigation">
+        ${this.groups.map(group => html`
+          <div class="group">
+            <p class="group-label">${group.label}</p>
+            <ul>
+              ${group.items.map(item => html`
+                <li>
+                  <a
+                    href="/docs/${item.slug}"
+                    aria-current="${this.currentSlug === item.slug ? 'page' : 'false'}"
+                  >
+                    <span>${item.label}</span>
+                    ${item.badge ? html`<span class="badge">${item.badge.text}</span>` : ''}
+                  </a>
+                </li>
+              `)}
+            </ul>
+          </div>
+        `)}
+      </nav>
+    `;
+  }
+}
+
+export default StarlightSidebar;

package/recipes/starlight/template/src/components/starlight-toc.ts

@@ -0,0 +1,133 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { TocEntry } from '../extract-headings.js';
+
+/**
+ * <starlight-toc .entries=${toc}>
+ *   Renders the table of contents as anchor links.
+ *   Active section highlighting is handled by CSS :target pseudo-class.
+ */
+@customElement('starlight-toc')
+export class StarlightToc extends LitElement {
+  static override properties = {
+    entries: { type: Array },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    nav {
+      position: sticky;
+      top: calc(var(--sl-nav-height, 3.5rem) + 1rem);
+      max-height: calc(100vh - var(--sl-nav-height, 3.5rem) - 2rem);
+      overflow-y: auto;
+      padding: 0 0.5rem;
+    }
+
+    h2 {
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      color: var(--sl-color-gray-4, #757575);
+      margin: 0 0 0.75rem;
+      padding: 0;
+      border: none;
+    }
+
+    ul {
+      list-style: none;
+      padding: 0;
+      margin: 0;
+    }
+
+    li {
+      margin: 0;
+    }
+
+    a {
+      display: block;
+      padding: 0.2rem 0;
+      font-size: var(--sl-text-sm, 0.875rem);
+      color: var(--sl-color-gray-4, #757575);
+      text-decoration: none;
+      transition: color 0.15s;
+      border-left: 2px solid transparent;
+    }
+
+    a:hover {
+      color: var(--sl-color-text, #23262f);
+    }
+
+    /* Depth indentation */
+    .depth-2 a { padding-left: 0.75rem; }
+    .depth-3 a { padding-left: 1.5rem; }
+    .depth-4 a { padding-left: 2.25rem; }
+
+    /* Active via [aria-current] set by the click handler */
+    li a[aria-current='true'] {
+      color: var(--sl-color-accent, #7c3aed);
+      border-left-color: var(--sl-color-accent, #7c3aed);
+    }
+  `;
+
+  entries: TocEntry[] = [];
+
+  /**
+   * Click handler for TOC anchor links.
+   *
+   * Heading elements rendered via unsafeHTML live inside shadow roots that
+   * native fragment navigation and document.getElementById() cannot reach.
+   * Instead of relying on the browser's default hash navigation (which also
+   * fires popstate and re-renders the page component with no data), we:
+   *   1. Prevent the default navigation.
+   *   2. Walk the shadow tree to find the target element.
+   *   3. Scroll to it smoothly.
+   *   4. Update the URL hash via pushState (does not fire popstate).
+   */
+  private _handleClick(e: MouseEvent, slug: string) {
+    e.preventDefault();
+    const target = this._findDeep(document, slug);
+    if (target) target.scrollIntoView({ behavior: 'smooth' });
+    history.pushState(null, '', `#${slug}`);
+  }
+
+  /** Recursively searches shadow roots for an element matching the CSS id selector. */
+  private _findDeep(root: Document | ShadowRoot | Element, id: string): Element | null {
+    const sel = `#${CSS.escape(id)}`;
+    const direct = root.querySelector(sel);
+    if (direct) return direct;
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) {
+        const found = this._findDeep(el.shadowRoot, id);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  override render() {
+    if (!this.entries.length) return html``;
+    const currentHash = typeof location !== 'undefined' ? location.hash : '';
+    return html`
+      <nav aria-label="On this page">
+        <h2>On this page</h2>
+        <ul>
+          ${this.entries.map(entry => html`
+            <li class="depth-${entry.depth}">
+              <a
+                href="#${entry.slug}"
+                aria-current="${currentHash === '#' + entry.slug ? 'true' : 'false'}"
+                @click=${(e: MouseEvent) => this._handleClick(e, entry.slug)}
+              >${entry.text}</a>
+            </li>
+          `)}
+        </ul>
+      </nav>
+    `;
+  }
+}
+
+export default StarlightToc;

package/recipes/starlight/template/src/date-utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Formats a Date or date string into a human-readable form.
+ * Uses the `en-US` locale with month-name style (e.g. "January 15, 2026").
+ */
+export function formatDate(date: Date | string): string {
+  const d = date instanceof Date ? date : new Date(date as string);
+  return d.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Returns an ISO 8601 string (e.g. "2026-01-15") suitable for a `datetime` attribute.
+ */
+export function isoDate(date: Date | string): string {
+  const d = date instanceof Date ? date : new Date(date as string);
+  return d.toISOString().slice(0, 10);
+}

package/recipes/starlight/template/src/extract-headings.ts

@@ -0,0 +1,68 @@
+export interface TocEntry {
+  depth: number;
+  text: string;
+  slug: string;
+}
+
+/**
+ * Extracts h2–h4 headings from raw Markdown source.
+ * Returns an array of TocEntry objects suitable for rendering a table of contents.
+ */
+export function extractHeadings(rawMarkdown: string): TocEntry[] {
+  const headings: TocEntry[] = [];
+  const lines = rawMarkdown.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/^(#{2,4})\s+(.+)$/);
+    if (!match) continue;
+
+    const depth = match[1].length;
+    const text = match[2].trim().replace(/\s*\{[^}]*\}\s*$/, ''); // strip {#custom-id} syntax
+    const slug = text
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .trim()
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-');
+
+    headings.push({ depth, text, slug });
+  }
+
+  return headings;
+}
+
+/**
+ * Post-processes rendered HTML to inject `id` attributes on h2–h4 elements,
+ * matching the slugs produced by `extractHeadings()`.
+ * Enables anchor-link navigation from the table of contents.
+ */
+export function addHeadingIds(html: string): string {
+  const counters: Record<string, number> = {};
+
+  return html.replace(
+    /<(h[2-4])([^>]*)>([\s\S]*?)<\/h[2-4]>/gi,
+    (_match, tag: string, attrs: string, content: string) => {
+      // Strip HTML tags from content to get plain text
+      const text = content.replace(/<[^>]+>/g, '').trim().replace(/\s*\{[^}]*\}\s*$/, '');
+      let slug = text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-');
+
+      // Deduplicate: if the same slug appears twice, append -2, -3, etc.
+      counters[slug] = (counters[slug] ?? 0) + 1;
+      if (counters[slug] > 1) {
+        slug = `${slug}-${counters[slug]}`;
+      }
+
+      // Avoid double-injecting if an id already exists
+      if (/\bid=/.test(attrs)) {
+        return `<${tag}${attrs}>${content}</${tag}>`;
+      }
+
+      return `<${tag}${attrs} id="${slug}">${content}</${tag}>`;
+    },
+  );
+}

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

@@ -0,0 +1,16 @@
+/**
+ * HTML injected into every page's <head> via routeMeta.head.
+ *
+ * Order matters:
+ *   1. Stylesheet link — loaded asynchronously by the browser; must come before
+ *      the FOUC-prevention script so --sl-* tokens are available immediately.
+ *   2. Inline script — synchronous, runs before first paint to set data-theme
+ *      from localStorage, preventing a flash of the wrong theme on reload.
+ */
+export const starlightHead = [
+  '<link rel="stylesheet" href="/styles/starlight.css" />',
+  '<script>(function(){',
+  'var t=localStorage.getItem("sl-theme")||"light";',
+  'document.documentElement.setAttribute("data-theme",t);',
+  '})();</script>',
+].join('');

package/recipes/starlight/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", ".nitro"]
+}

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

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import litroContentPlugin from '@beatzball/litro/vite';
+
+export default defineConfig({
+  plugins: [litroContentPlugin()],
+  base: '/_litro/',
+  resolve: {
+    conditions: ['source', 'browser', 'module', 'import', 'default'],
+  },
+  build: {
+    outDir: 'dist/client',
+    rollupOptions: {
+      input: 'app.ts',
+      output: {
+        entryFileNames: '[name].js',
+      },
+    },
+  },
+});