@beatzball/create-litro 0.1.4 → 0.2.0

package/dist/recipes/starlight/template/src/components/sl-tabs.ts

@@ -0,0 +1,108 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { SlTabItem } from './sl-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>
+ *
+ * Reads slotted <sl-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 {
+  static override properties = {
+    _labels: { type: Array, state: true },
+    _selectedIndex: { type: Number, state: true },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+      margin: 1.5rem 0;
+    }
+
+    .tab-bar {
+      display: flex;
+      gap: 0;
+      border-bottom: 2px solid var(--sl-color-border, #e8e8e8);
+      overflow-x: auto;
+    }
+
+    .tab-btn {
+      appearance: none;
+      background: none;
+      border: none;
+      padding: 0.5rem 1rem;
+      font: inherit;
+      font-size: var(--sl-text-sm, 0.875rem);
+      font-weight: 500;
+      cursor: pointer;
+      color: var(--sl-color-gray-4, #757575);
+      border-bottom: 2px solid transparent;
+      margin-bottom: -2px;
+      white-space: nowrap;
+      transition: color 0.15s, border-color 0.15s;
+    }
+
+    .tab-btn:hover {
+      color: var(--sl-color-text, #23262f);
+    }
+
+    .tab-btn[aria-selected='true'] {
+      color: var(--sl-color-accent, #7c3aed);
+      border-bottom-color: var(--sl-color-accent, #7c3aed);
+    }
+
+    .tab-content {
+      padding-top: 1rem;
+    }
+  `;
+
+  _labels: string[] = [];
+  _selectedIndex = 0;
+
+  private _items(): SlTabItem[] {
+    const slot = this.shadowRoot?.querySelector('slot');
+    if (!slot) return [];
+    return slot.assignedElements().filter(
+      (el): el is SlTabItem => el.tagName.toLowerCase() === 'sl-tab-item',
+    );
+  }
+
+  private _onSlotChange() {
+    const items = this._items();
+    this._labels = items.map((item) => item.label || `Tab ${items.indexOf(item) + 1}`);
+    this._selectIndex(this._selectedIndex < items.length ? this._selectedIndex : 0, items);
+  }
+
+  private _selectIndex(index: number, items?: SlTabItem[]) {
+    const all = items ?? this._items();
+    this._selectedIndex = index;
+    all.forEach((item, i) => {
+      item.selected = i === index;
+    });
+  }
+
+  override render() {
+    return html`
+      <div class="tab-bar" role="tablist">
+        ${this._labels.map((label, i) => html`
+          <button
+            class="tab-btn"
+            role="tab"
+            aria-selected="${this._selectedIndex === i ? 'true' : 'false'}"
+            @click=${() => this._selectIndex(i)}
+          >${label}</button>
+        `)}
+      </div>
+      <div class="tab-content">
+        <slot @slotchange=${this._onSlotChange}></slot>
+      </div>
+    `;
+  }
+}
+
+export default SlTabs;

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

@@ -0,0 +1,152 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+export interface NavItem {
+  label: string;
+  href: string;
+}
+
+/**
+ * <starlight-header siteTitle="My Docs" .nav=${nav} currentPath="/docs/getting-started">
+ *   Top navigation bar with site title, nav links, and dark/light theme toggle.
+ */
+@customElement('starlight-header')
+export class StarlightHeader extends LitElement {
+  static override properties = {
+    siteTitle: { type: String },
+    nav: { type: Array },
+    currentPath: { type: String },
+    _theme: { type: String, state: true },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 100;
+      height: var(--sl-nav-height, 3.5rem);
+      background-color: var(--sl-color-bg-nav, #fff);
+      border-bottom: 1px solid var(--sl-color-border, #e8e8e8);
+      display: flex;
+      align-items: center;
+      padding: 0 var(--sl-content-pad-x, 1.5rem);
+      gap: 1.5rem;
+    }
+
+    .site-title {
+      font-size: var(--sl-text-lg, 1.125rem);
+      font-weight: 700;
+      color: var(--sl-color-text, #23262f);
+      text-decoration: none;
+      white-space: nowrap;
+    }
+
+    .site-title:hover { opacity: 0.85; }
+
+    nav {
+      display: flex;
+      align-items: center;
+      gap: 0.25rem;
+      flex: 1;
+    }
+
+    nav a {
+      padding: 0.35rem 0.75rem;
+      font-size: var(--sl-text-sm, 0.875rem);
+      font-weight: 500;
+      color: var(--sl-color-gray-5, #4b4b4b);
+      text-decoration: none;
+      border-radius: var(--sl-border-radius, 0.375rem);
+      transition: color 0.15s, background-color 0.15s;
+    }
+
+    nav a:hover {
+      color: var(--sl-color-text, #23262f);
+      background-color: var(--sl-color-gray-2, #e8e8e8);
+    }
+
+    nav a[aria-current='page'] {
+      color: var(--sl-color-accent, #7c3aed);
+      background-color: var(--sl-color-accent-low, #ede9fe);
+    }
+
+    .theme-toggle {
+      margin-left: auto;
+      appearance: none;
+      background: none;
+      border: 1px solid var(--sl-color-border, #e8e8e8);
+      border-radius: var(--sl-border-radius, 0.375rem);
+      width: 2.25rem;
+      height: 2.25rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      cursor: pointer;
+      font-size: 1rem;
+      color: var(--sl-color-text, #23262f);
+      transition: background-color 0.15s;
+      flex-shrink: 0;
+    }
+
+    .theme-toggle:hover {
+      background-color: var(--sl-color-gray-2, #e8e8e8);
+    }
+  `;
+
+  siteTitle = '';
+  nav: NavItem[] = [];
+  currentPath = '';
+
+  _theme = 'light';
+
+  override firstUpdated() {
+    const stored = (typeof localStorage !== 'undefined'
+      ? localStorage.getItem('sl-theme')
+      : null) ?? 'light';
+    this._theme = stored;
+    if (typeof document !== 'undefined') {
+      document.documentElement.setAttribute('data-theme', stored);
+    }
+  }
+
+  private _toggleTheme() {
+    const next = this._theme === 'light' ? 'dark' : 'light';
+    this._theme = next;
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem('sl-theme', next);
+    }
+    if (typeof document !== 'undefined') {
+      document.documentElement.setAttribute('data-theme', next);
+    }
+  }
+
+  override render() {
+    const icon = this._theme === 'dark' ? '☀️' : '🌙';
+    const label = this._theme === 'dark' ? 'Switch to light mode' : 'Switch to dark mode';
+
+    return html`
+      <header>
+        <a class="site-title" href="/">${this.siteTitle}</a>
+        <nav aria-label="Main navigation">
+          ${this.nav.map(item => html`
+            <a
+              href="${item.href}"
+              aria-current="${this.currentPath.startsWith(item.href) ? 'page' : 'false'}"
+            >${item.label}</a>
+          `)}
+        </nav>
+        <button
+          class="theme-toggle"
+          aria-label="${label}"
+          @click="${this._toggleTheme}"
+        >${icon}</button>
+      </header>
+    `;
+  }
+}
+
+export default StarlightHeader;

package/dist/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/dist/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/dist/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/dist/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);
+}