create-ngmd 0.0.1

package/template/src/app/components/command-palette.ts

@@ -0,0 +1,299 @@
+import {
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  HostListener,
+  inject,
+  signal,
+  viewChild,
+} from '@angular/core';
+import { Router } from '@angular/router';
+import { injectContentFiles } from '@analogjs/content';
+import {
+  LucideAngularModule,
+  Search,
+  ArrowRight,
+  Hash,
+  FileText,
+} from 'lucide-angular';
+import { navItems } from '../../ngmd.config';
+
+type ItemKind = 'page' | 'heading' | 'snippet';
+
+interface PaletteItem {
+  kind: ItemKind;
+  label: string;
+  subtitle: string;
+  href: string;
+  hash?: string;
+}
+
+interface IndexedFile {
+  slug: string;
+  pageLabel: string;
+  href: string;
+  body: string;
+  bodyLower: string;
+  headings: { text: string; slug: string }[];
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/** Strip markdown syntax for cleaner snippet previews. */
+function stripMarkdown(s: string): string {
+  return s
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[*_#>]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+@Component({
+  selector: 'app-command-palette',
+  imports: [LucideAngularModule],
+  template: `
+    @if (open()) {
+      <div
+        class="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50 backdrop-blur-sm"
+        (click)="close()"
+      >
+        <div
+          class="w-full max-w-2xl rounded-2xl border border-zinc-200 bg-white shadow-2xl dark:border-zinc-800 dark:bg-zinc-950 overflow-hidden"
+          (click)="$event.stopPropagation()"
+        >
+          <div class="flex items-center gap-3 px-5 py-4">
+            <i-lucide [img]="searchIcon" class="size-6 text-zinc-400"></i-lucide>
+            <input
+              #input
+              type="text"
+              placeholder="Type a command or search..."
+              class="flex-1 bg-transparent text-lg outline-none placeholder:text-zinc-400"
+              [value]="query()"
+              (input)="onInput($event)"
+            />
+          </div>
+
+          <div class="border-t border-zinc-200 dark:border-zinc-800 h-96 overflow-y-auto p-3">
+            @if (filtered().length === 0) {
+              <div class="py-12 text-center text-base text-zinc-500">No results.</div>
+            } @else {
+              @for (item of filtered(); track $index; let i = $index) {
+                <button
+                  type="button"
+                  class="flex w-full cursor-pointer items-center gap-4 rounded-lg px-4 py-3 text-left"
+                  [class]="i === active() ? 'bg-fuchsia-500/10' : ''"
+                  (mouseenter)="active.set(i)"
+                  (click)="select()"
+                >
+                  <i-lucide [img]="iconFor(item)" class="size-5 text-zinc-400"></i-lucide>
+                  <div class="flex-1 min-w-0">
+                    <div class="text-base font-semibold truncate">{{ item.label }}</div>
+                    <div class="text-sm text-zinc-500 truncate">{{ item.subtitle }}</div>
+                  </div>
+                </button>
+              }
+            }
+          </div>
+
+          <div class="flex items-center justify-end border-t border-zinc-200 dark:border-zinc-800 px-4 py-2 text-xs text-zinc-500">
+            esc to close
+          </div>
+        </div>
+      </div>
+    }
+  `,
+})
+export class CommandPalette {
+  private readonly router = inject(Router);
+  private readonly input = viewChild<ElementRef<HTMLInputElement>>('input');
+  private readonly contentFiles = injectContentFiles<{ title?: string }>();
+
+  readonly searchIcon = Search;
+  readonly arrowIcon = ArrowRight;
+  readonly hashIcon = Hash;
+  readonly fileIcon = FileText;
+
+  readonly open = signal(false);
+  readonly query = signal('');
+  readonly active = signal(0);
+
+  constructor() {
+    effect(() => {
+      if (typeof document === 'undefined') return;
+      document.body.style.overflow = this.open() ? 'hidden' : '';
+    });
+  }
+
+  private readonly pageItems: PaletteItem[] = navItems.map((item) => ({
+    kind: 'page',
+    label: item.label,
+    subtitle: item.section,
+    href: item.href,
+  }));
+
+  private readonly index: IndexedFile[] = this.buildIndex();
+
+  readonly filtered = computed(() => {
+    const q = this.query().toLowerCase().trim();
+    if (!q) return this.pageItems;
+
+    const results: PaletteItem[] = [];
+    const seen = new Set<string>();
+    const push = (item: PaletteItem) => {
+      const key = `${item.kind}:${item.href}#${item.hash ?? ''}:${item.label}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      results.push(item);
+    };
+
+    // 1. Pages by label
+    for (const p of this.pageItems) {
+      if (p.label.toLowerCase().includes(q)) push(p);
+    }
+
+    // 2. Headings by text
+    for (const file of this.index) {
+      for (const h of file.headings) {
+        if (h.text.toLowerCase().includes(q)) {
+          push({
+            kind: 'heading',
+            label: h.text,
+            subtitle: file.pageLabel,
+            href: file.href,
+            hash: h.slug,
+          });
+        }
+      }
+    }
+
+    // 3. Body matches with snippet
+    for (const file of this.index) {
+      const idx = file.bodyLower.indexOf(q);
+      if (idx === -1) continue;
+      const start = Math.max(0, idx - 40);
+      const end = Math.min(file.body.length, idx + q.length + 60);
+      const snippet =
+        (start > 0 ? '…' : '') +
+        file.body.slice(start, end).trim() +
+        (end < file.body.length ? '…' : '');
+      push({
+        kind: 'snippet',
+        label: snippet,
+        subtitle: file.pageLabel,
+        href: file.href,
+      });
+    }
+
+    return results.slice(0, 30);
+  });
+
+  iconFor(item: PaletteItem) {
+    if (item.kind === 'heading') return this.hashIcon;
+    if (item.kind === 'snippet') return this.fileIcon;
+    return this.arrowIcon;
+  }
+
+  @HostListener('document:keydown', ['$event'])
+  onKeydown(event: KeyboardEvent) {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+      event.preventDefault();
+      this.toggle();
+      return;
+    }
+    if (event.key === 'Escape' && this.open()) {
+      event.preventDefault();
+      this.close();
+    }
+  }
+
+  toggle() {
+    this.open.update((v) => !v);
+    if (this.open()) {
+      this.query.set('');
+      this.active.set(0);
+      queueMicrotask(() => this.input()?.nativeElement.focus());
+    }
+  }
+
+  close() {
+    this.open.set(false);
+  }
+
+  onInput(event: Event) {
+    this.query.set((event.target as HTMLInputElement).value);
+    this.active.set(0);
+  }
+
+  move(delta: number) {
+    const max = this.filtered().length - 1;
+    if (max < 0) return;
+    const next = (this.active() + delta + max + 1) % (max + 1);
+    this.active.set(next);
+  }
+
+  select() {
+    const item = this.filtered()[this.active()];
+    if (!item) return;
+    this.close();
+    if (!item.hash) {
+      this.router.navigateByUrl(item.href);
+      return;
+    }
+    // Navigate first, then poll for the heading to appear (markdown loads async).
+    this.router.navigateByUrl(item.href).then(() => {
+      this.scrollToWhenReady(item.hash!);
+    });
+  }
+
+  private scrollToWhenReady(slug: string, attempt = 0): void {
+    if (typeof document === 'undefined' || attempt > 30) return;
+    const el = document.getElementById(slug);
+    if (!el) {
+      setTimeout(() => this.scrollToWhenReady(slug, attempt + 1), 50);
+      return;
+    }
+    el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    history.replaceState(null, '', `${location.pathname}#${slug}`);
+  }
+
+  private buildIndex(): IndexedFile[] {
+    const slugToNav = new Map(
+      navItems.map((item) => [item.href.split('/').pop() ?? '', item]),
+    );
+    const out: IndexedFile[] = [];
+
+    for (const file of this.contentFiles) {
+      const navItem = slugToNav.get(file.slug);
+      if (!navItem) continue;
+      const raw = typeof file.content === 'string' ? file.content : '';
+      if (!raw) continue;
+
+      const headings: { text: string; slug: string }[] = [];
+      for (const m of raw.matchAll(/^(##+)\s+(.+)$/gm)) {
+        const text = m[2].trim();
+        headings.push({ text, slug: slugify(text) });
+      }
+
+      const body = stripMarkdown(raw);
+      out.push({
+        slug: file.slug,
+        pageLabel: navItem.label,
+        href: navItem.href,
+        body,
+        bodyLower: body.toLowerCase(),
+        headings,
+      });
+    }
+
+    return out;
+  }
+}

package/template/src/app/components/external-links.ts

@@ -0,0 +1,55 @@
+import {
+  AfterViewInit,
+  Component,
+  DestroyRef,
+  inject,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { NavigationEnd, Router } from '@angular/router';
+import { filter } from 'rxjs';
+
+/**
+ * Adds `target="_blank" rel="noopener noreferrer"` to external anchors in
+ * rendered markdown after each route change.
+ */
+@Component({
+  selector: 'app-external-links',
+  template: '',
+  styles: `
+    :host { display: none; }
+  `,
+})
+export class ExternalLinks implements AfterViewInit {
+  private readonly router = inject(Router);
+  private readonly destroyRef = inject(DestroyRef);
+
+  ngAfterViewInit(): void {
+    this.enhanceWithRetry();
+    this.router.events
+      .pipe(
+        filter((e) => e instanceof NavigationEnd),
+        takeUntilDestroyed(this.destroyRef),
+      )
+      .subscribe(() => this.enhanceWithRetry());
+  }
+
+  private enhanceWithRetry(attempt = 0): void {
+    if (typeof document === 'undefined' || attempt > 20) return;
+    const container =
+      document.querySelector('main analog-markdown') ??
+      document.querySelector('main analog-markdown-route');
+    const anchors = container?.querySelectorAll('a[href^="http"]:not([data-external-enhanced])');
+    if (!anchors || anchors.length === 0) {
+      setTimeout(() => this.enhanceWithRetry(attempt + 1), 50);
+      return;
+    }
+    const origin = window.location.origin;
+    anchors.forEach((node) => {
+      const a = node as HTMLAnchorElement;
+      a.setAttribute('data-external-enhanced', 'true');
+      if (a.href.startsWith(origin)) return;
+      a.setAttribute('target', '_blank');
+      a.setAttribute('rel', 'noopener noreferrer');
+    });
+  }
+}

package/template/src/app/components/heading-anchors.ts

@@ -0,0 +1,95 @@
+import { AfterViewInit, Component, DestroyRef, inject } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { NavigationEnd, Router } from '@angular/router';
+import { filter } from 'rxjs';
+
+/**
+ * Scans rendered docs pages for h2/h3 with an id and appends a copy-link
+ * button that writes the absolute URL with `#fragment` to the clipboard.
+ * Runs on mount and after every route change, same pattern as CodeCopy.
+ */
+@Component({
+  selector: 'app-heading-anchors',
+  template: '',
+  styles: `
+    :host { display: none; }
+  `,
+})
+export class HeadingAnchors implements AfterViewInit {
+  private readonly router = inject(Router);
+  private readonly destroyRef = inject(DestroyRef);
+
+  ngAfterViewInit(): void {
+    this.enhanceWithRetry();
+    this.router.events
+      .pipe(
+        filter((e) => e instanceof NavigationEnd),
+        takeUntilDestroyed(this.destroyRef),
+      )
+      .subscribe(() => this.enhanceWithRetry());
+  }
+
+  private enhanceWithRetry(attempt = 0): void {
+    if (typeof document === 'undefined' || attempt > 20) return;
+    const headings = document.querySelectorAll<HTMLElement>(
+      'main h1[id]:not([data-anchor-enhanced]), main h2[id]:not([data-anchor-enhanced]), main h3[id]:not([data-anchor-enhanced])',
+    );
+    if (headings.length === 0) {
+      setTimeout(() => this.enhanceWithRetry(attempt + 1), 50);
+      return;
+    }
+    headings.forEach((h) => this.enhance(h));
+  }
+
+  private enhance(heading: HTMLElement): void {
+    heading.setAttribute('data-anchor-enhanced', 'true');
+    heading.style.scrollMarginTop = heading.style.scrollMarginTop || '6rem';
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.setAttribute('aria-label', `Copy link to ${heading.id}`);
+    button.className =
+      'ml-2 inline-flex items-center justify-center size-5 align-middle relative -top-[2px] rounded text-zinc-400 hover:text-fuchsia-600 dark:hover:text-fuchsia-400 opacity-0 transition-opacity focus:opacity-100';
+    button.innerHTML = this.linkIcon();
+
+    heading.addEventListener('mouseenter', () => (button.style.opacity = '1'));
+    heading.addEventListener('mouseleave', () => (button.style.opacity = '0'));
+
+    // h1 is the page itself; copying #h1-slug duplicates the path in the URL.
+    // For h1, copy + show the bare page URL with no fragment.
+    const isH1 = heading.tagName === 'H1';
+
+    button.addEventListener('click', async (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const base = `${location.origin}${location.pathname}`;
+      const url = isH1 ? base : `${base}#${heading.id}`;
+      try {
+        await navigator.clipboard.writeText(url);
+        button.innerHTML = this.checkIcon();
+        setTimeout(() => (button.innerHTML = this.linkIcon()), 1500);
+      } catch {
+        // clipboard API unavailable, no-op
+      }
+    });
+
+    heading.appendChild(button);
+  }
+
+  private linkIcon(): string {
+    return `
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/>
+        <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/>
+      </svg>
+    `;
+  }
+
+  private checkIcon(): string {
+    return `
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <polyline points="20 6 9 17 4 12"/>
+      </svg>
+    `;
+  }
+}

package/template/src/app/components/hlm-card.ts

@@ -0,0 +1,31 @@
+import { Component, input } from '@angular/core';
+
+/**
+ * Tailwind-styled card mirroring Spartan UI's `hlm-card` shape.
+ * Replace with the official spartan helm card later when wiring the full CLI.
+ */
+@Component({
+  selector: 'hlm-card',
+  template: `
+    <div
+      class="rounded-xl border border-zinc-200 bg-white text-zinc-950 shadow-sm
+             dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-50"
+    >
+      @if (title()) {
+        <div class="px-6 pt-6">
+          <h3 class="text-lg font-semibold leading-none tracking-tight">{{ title() }}</h3>
+          @if (description()) {
+            <p class="mt-1.5 text-sm text-zinc-500 dark:text-zinc-400">{{ description() }}</p>
+          }
+        </div>
+      }
+      <div class="p-6">
+        <ng-content></ng-content>
+      </div>
+    </div>
+  `,
+})
+export class HlmCard {
+  readonly title = input<string>('');
+  readonly description = input<string>('');
+}

package/template/src/app/components/media-enhancer.ts

@@ -0,0 +1,95 @@
+import {
+  AfterViewInit,
+  Component,
+  DestroyRef,
+  inject,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { NavigationEnd, Router } from '@angular/router';
+import { filter } from 'rxjs';
+
+/**
+ * Hydrates the placeholder divs emitted by the ngmd-video and ngmd-image
+ * marked extensions. The marked extensions output plain `<div data-...>`
+ * elements; this enhancer creates the real <iframe> and <figure><img>
+ * structures programmatically — bypassing any Angular [innerHTML]
+ * sanitisation that may strip iframes in some configurations.
+ */
+@Component({
+  selector: 'app-media-enhancer',
+  template: '',
+  styles: `:host { display: none; }`,
+})
+export class MediaEnhancer implements AfterViewInit {
+  private readonly router = inject(Router);
+  private readonly destroyRef = inject(DestroyRef);
+
+  ngAfterViewInit(): void {
+    this.enhanceWithRetry();
+    this.router.events
+      .pipe(
+        filter((e) => e instanceof NavigationEnd),
+        takeUntilDestroyed(this.destroyRef),
+      )
+      .subscribe(() => this.enhanceWithRetry());
+  }
+
+  private enhanceWithRetry(attempt = 0): void {
+    if (typeof document === 'undefined' || attempt > 20) return;
+    const videos = document.querySelectorAll<HTMLElement>(
+      '.ngmd-video[data-video-src]:not([data-enhanced])',
+    );
+    const images = document.querySelectorAll<HTMLElement>(
+      '.ngmd-image[data-image-src]:not([data-enhanced])',
+    );
+    if (videos.length === 0 && images.length === 0) {
+      setTimeout(() => this.enhanceWithRetry(attempt + 1), 50);
+      return;
+    }
+    videos.forEach((el) => this.enhanceVideo(el));
+    images.forEach((el) => this.enhanceImage(el));
+  }
+
+  private enhanceVideo(el: HTMLElement): void {
+    el.setAttribute('data-enhanced', 'true');
+    const src = el.dataset['videoSrc'] ?? '';
+    const title = el.dataset['videoTitle'] ?? 'Video player';
+    const iframe = document.createElement('iframe');
+    iframe.src = src;
+    iframe.title = title;
+    iframe.setAttribute(
+      'allow',
+      'accelerometer; encrypted-media; gyroscope; picture-in-picture',
+    );
+    iframe.setAttribute('allowfullscreen', '');
+    iframe.loading = 'lazy';
+    el.appendChild(iframe);
+  }
+
+  private enhanceImage(el: HTMLElement): void {
+    el.setAttribute('data-enhanced', 'true');
+    const src = el.dataset['imageSrc'] ?? '';
+    const alt = el.dataset['imageAlt'] ?? '';
+    const caption = el.dataset['imageCaption'] ?? '';
+    const width = el.dataset['imageWidth'] ?? '';
+
+    // Replace the placeholder with an actual <figure>
+    const figure = document.createElement('figure');
+    figure.className = 'ngmd-image';
+    if (width) figure.style.maxWidth = width;
+
+    const img = document.createElement('img');
+    img.src = src;
+    img.alt = alt;
+    img.loading = 'lazy';
+    figure.appendChild(img);
+
+    if (caption) {
+      const figcaption = document.createElement('figcaption');
+      figcaption.textContent = caption;
+      figure.appendChild(figcaption);
+    }
+
+    el.replaceWith(figure);
+  }
+}

package/template/src/app/components/page-footer.ts

@@ -0,0 +1,107 @@
+import { Component, computed, inject, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { NavigationEnd, Router, RouterLink } from '@angular/router';
+import { filter, map, startWith } from 'rxjs';
+import { LucideAngularModule, ArrowLeft, ArrowRight, Pencil } from 'lucide-angular';
+import { pageMeta } from 'virtual:ngmd/page-meta';
+import { navItems } from '../../ngmd.config';
+
+/**
+ * Bottom-of-page chrome shown under every docs route: previous/next sibling
+ * pages derived from `ngmd.config.ts`, an "Edit on GitHub" link, and the
+ * page's last-updated date (commit cs from `git log`, baked at build time
+ * via the page-meta vite plugin).
+ */
+@Component({
+  selector: 'app-page-footer',
+  imports: [RouterLink, LucideAngularModule],
+  template: `
+    <footer class="mt-12 border-t border-zinc-200 dark:border-zinc-800 pt-6 pb-10 text-sm">
+      <div class="flex flex-wrap items-center justify-between gap-3 text-zinc-500 dark:text-zinc-400">
+        @if (editUrl(); as url) {
+          <a
+            [href]="url"
+            target="_blank"
+            rel="noopener noreferrer"
+            class="inline-flex items-center gap-1.5 hover:text-zinc-900 dark:hover:text-zinc-100"
+          >
+            <i-lucide [img]="editIcon" class="size-3.5"></i-lucide>
+            Edit this page on GitHub
+          </a>
+        }
+        @if (lastUpdated(); as date) {
+          <span>Last updated: {{ date }}</span>
+        }
+      </div>
+
+      @if (prev() || next()) {
+        <nav class="mt-6 grid gap-3 sm:grid-cols-2">
+          @if (prev(); as p) {
+            <a
+              [routerLink]="p.href"
+              class="group rounded-lg border border-zinc-200 dark:border-zinc-800 p-4 hover:border-fuchsia-500 dark:hover:border-fuchsia-400 transition-colors sm:col-start-1"
+            >
+              <span class="flex items-center gap-1.5 text-xs text-zinc-500 dark:text-zinc-400">
+                <i-lucide [img]="prevIcon" class="size-3.5"></i-lucide>
+                Previous
+              </span>
+              <span class="mt-1 block text-base font-medium text-zinc-900 dark:text-zinc-100">{{ p.label }}</span>
+            </a>
+          }
+          @if (next(); as n) {
+            <a
+              [routerLink]="n.href"
+              class="group rounded-lg border border-zinc-200 dark:border-zinc-800 p-4 hover:border-fuchsia-500 dark:hover:border-fuchsia-400 transition-colors text-right sm:col-start-2"
+            >
+              <span class="flex items-center justify-end gap-1.5 text-xs text-zinc-500 dark:text-zinc-400">
+                Next
+                <i-lucide [img]="nextIcon" class="size-3.5"></i-lucide>
+              </span>
+              <span class="mt-1 block text-base font-medium text-zinc-900 dark:text-zinc-100">{{ n.label }}</span>
+            </a>
+          }
+        </nav>
+      }
+    </footer>
+  `,
+})
+export class PageFooter {
+  private readonly router = inject(Router);
+
+  readonly editIcon = Pencil;
+  readonly prevIcon = ArrowLeft;
+  readonly nextIcon = ArrowRight;
+
+  private readonly url = toSignal(
+    this.router.events.pipe(
+      filter((e) => e instanceof NavigationEnd),
+      map(() => this.router.url),
+      startWith(this.router.url),
+    ),
+    { initialValue: '/' },
+  );
+  private readonly cleanUrl = computed(
+    () => this.url().split('?')[0].split('#')[0],
+  );
+
+  private readonly meta = computed(() => pageMeta[this.cleanUrl()]);
+  readonly editUrl = computed(() => this.meta()?.editUrl ?? '');
+  readonly lastUpdated = computed(() => {
+    const iso = this.meta()?.lastUpdated;
+    if (!iso) return '';
+    const [y, m, d] = iso.split('-');
+    return y && m && d ? `${d}/${m}/${y}` : iso;
+  });
+
+  private readonly index = computed(() =>
+    navItems.findIndex((n) => n.href === this.cleanUrl()),
+  );
+  readonly prev = computed(() => {
+    const i = this.index();
+    return i > 0 ? navItems[i - 1] : null;
+  });
+  readonly next = computed(() => {
+    const i = this.index();
+    return i >= 0 && i < navItems.length - 1 ? navItems[i + 1] : null;
+  });
+}